> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# AI agent architecture: flows, retrieval, tools, and the run lifecycle end to end

> The end-to-end architecture of Orbit AI agents — conversation-flow orchestration, RAG over knowledge bases, the tool/skill envelope, presence coordination, and where agents sit relative to the media planes.

# AI agent architecture

An AI agent on Orbit is not one system prompt and a model API key. A turn of conversation moves through four cooperating layers — the orchestration model that decides which instructions apply, the retrieval layer that grounds the reply in your knowledge bases, the tool envelope that executes side effects, and the run lifecycle that tracks every turn to a terminal state. The [AI agents feature pages](/agents/overview) cover each surface in detail; this page connects them at the concept level so you can reason about the whole stack before you pick a configuration.

## 1. The orchestration model: flows and goals

Turn-by-turn execution is driven by a **conversation flow** — a versioned node graph attached to the agent. Every turn picks one active **node**, and that node's `instructions` replace the base persona prompt for that turn only. Edges carry keyword or regex **conditions** evaluated against the customer's latest message (first match wins); when nothing matches, the turn stays on the current node or falls to one of the declared fallback nodes. Deterministic guardrails make the graph safe to route on: duplicate node ids and edges to unknown ids are rejected at save by the API schema, the graph is bounded (64 nodes, 16 edges per node, 8 fallbacks), and replay is deterministic — the same message always takes the same edge. The full authoring model, limits, and experiment pin-in live in [Conversation flows](/agents/conversation-flows).

This is the per-turn counterpart to [Flows](/concepts/flow-execution-model): a classic flow routes a *contact* through channel automations; a conversation flow routes the *conversation itself* between named states while the agent holds it.

Goals and guardrails sit above the routing layer. The base system prompt carries the persona and policy text (what the agent may and may not do); the active node carries the *objective* for this turn. Because saves are validated and versions are pinned, the routing map an experiment or a production agent runs on is the one you approved — prompt and graph changes never bleed across versions (see [Agent versions](/agents/agent-versions)).

## 2. RAG over knowledge bases

Retrieval-augmented generation feeds the model your own content at answer time instead of stuffing everything into the prompt. Attaching a knowledge base to an agent makes three things happen per turn:

1. **The question is retrieved, not keyword-matched.** The user's message is embedded and matched against the KB's chunked documents; the top-scoring chunks enter the context as grounding material.
2. **Content comes from three source families.** Manual document uploads, one-off or scheduled URL crawls, and **connectors** — managed syncs from third-party sources (Notion, Confluence, Google Drive, SharePoint, Zendesk) bound to a connection you authorised in the integrations settings, with a scope (which spaces / folders / collections / labels) and a cadence (manual, hourly, daily, weekly). Connectors keep answers tracking a living source instead of a frozen snapshot.
3. **Freshness is a tenant-visible control.** Each connector exposes a sync status (`idle`, `queued`, `syncing`, `error`) and a content-drift state (`unknown`, `in_sync`, `drifted`) — a drifted source means the agent is answering from stale text until a resync lands, and you can set the connector to auto-queue that resync itself.

The prompt metamodel wraps every turn the same way — the routing preamble, the base persona/policy prompt, the active node's instructions, the retrieved chunks, then the user's message — which is why prompting guidance across the docs (including how you scope candidate actions in [next-best-action decisioning](/concepts/decisioning) when a policy layer drives variant choice) assumes the same fixed shape: knowledge arrives as retrieved chunks, never as free-floating prompt text. Every grounding citation the agent used is auditable per turn (see [Grounding citations](/agents/grounding-citations)).

## 3. The tool and skill envelope

Tools are the side effects of a conversation: API calls and functions the agent invokes mid-turn (looking up an order, booking an appointment, transferring the call). Each tool call follows a small lifecycle inside one run:

1. The model emits a **function call** with the tool name and extracted arguments.
2. **Guardrails and confirmations hook in.** A tool marked `confirmation: "always"` holds the run in a pending-approval state until a human decides ([Human-in-the-loop oversight](/agents/human-in-the-loop-oversight)).
3. The runtime executes the tool, writes the **tool call record** (name, arguments, result), and feeds the result back to the model.
4. The per-run loop counter advances — a run that keeps calling tools past `tool_loop_limit` terminates with `TOOL_ITERATION_LIMIT` instead of looping.

One tool deserves its own pointer: voice-side routing treats **skills** as a governed vocabulary, so an agent that hands a conversation to a queue names tags that routing can match. The catalog enforcing that vocabulary — queues and agents reject unknown tags at write time — is [The skill catalog](/concepts/skill-catalog); eligibility and levels in dispatch are modelled on [The ACD queue model](/concepts/acd-queue-model).

## 4. The run, presence, and lifecycle

Every one of the layers above executes inside a **run** — the unit of execution for one conversation turn, one API turn you requested, or one A2A task. A run follows the state machine `queued → working → completed`, with `input_required` when it parks on an approval and `failed | cancelled` as the terminal alternatives. Guardrail aborts carry specific error codes (`COST_LIMIT`, `TOKEN_LIMIT`, `API_CALL_LIMIT`, `TOOL_ITERATION_LIMIT`), and a parked, resumable `input_required` is not a failure. The full machine, its interrupting actors, and the observable event stream are in [Agent run lifecycle](/concepts/agent-run-lifecycle).

Presence layers sit distinct from run status. **Human** agent presence (the five-state machine dispatch checks — `available`, `busy`, `wrapup`, `paused`, `offline`) decides when a handoff from AI back to a person can actually be claimed; it is defined in [Agent presence and aux-code lifecycle](/concepts/agent-presence-lifecycle). And an AI agent's conversation can pause while a human holds it — the runtime checks `agent_active` before every turn and no new run starts until control returns.

## 5. Where agents sit in the planes

Agents operate in the **application plane**: they consume messages, transcripts, and events and emit replies and tool calls — they never terminate carrier media themselves. The connection to the media planes is a routing decision you make at deploy time:

* **Voice turns.** A PSTN number you route to an agent terminates on the Jambonz SBC + RTPengine carrier plane; the agent receives the transcribed turn and the gateway streams the agent's spoken reply back onto the same leg. Outbound (MT) voice the agent triggers still terminates only via the Devotel wholesale softswitch — the same carrier plane, the same rule, whether a human or an agent initiated the call.
* **Messaging turns.** SMS, WhatsApp, and RCS turns arrive over the messaging pipes and are answered on the same channel bindings you deployed the agent to (`sms`, `whatsapp`, `rcs`, `voice`, or `webhook`).
* **Browser video turns.** A participant in an Orbit Media (SFU) video room may be an agent on the WebRTC side instead of a human.

Read [Media planes](/concepts/media-planes) for the two-plane split itself and [AI agents on Orbit: build, deploy, and monitor](/agents/overview) for the per-channel deploy calls.

## 6. What to branch on

Integrations watching a conversation should select on the machine-readable envelope, not on display text:

| Branch signal                                                                                                   | Where it appears                                         | Drive                                                                                                                                           |
| --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Run `status` and terminal error `code`                                                                          | Run responses, streaming `status` / `error` events       | Retry policy — a cost/token failure means raise a cap or start a fresh conversation; `input_required` means wait.                               |
| Tool call record (name, arguments, result)                                                                      | Streaming `tool_call` events, the per-run tool history   | Audit and downstream side effects — every function call mid-turn lands here.                                                                    |
| Presence transitions (`available → busy → wrapup`), `agent_active` flips, and `agent.handoff_occurred` webhooks | Webhook subscriptions, softphone and supervisor surfaces | Rendering and handoff logic — an AI-to-human transfer is complete only once a human actually claims the conversation from their presence state. |

## Cross-references

* [Agent run lifecycle](/concepts/agent-run-lifecycle) — the state machine every turn moves through.
* [Agent presence and aux-code lifecycle](/concepts/agent-presence-lifecycle) — human presence behind every AI→human handoff.
* [Conversation flows](/agents/conversation-flows) — the node/edge/condition orchestration graph.
* [The skill catalog](/concepts/skill-catalog) and [The ACD queue model](/concepts/acd-queue-model) — governed skill vocabulary and dispatch eligibility.
* [Media planes](/concepts/media-planes) — the two media planes agents surface onto.
* [Next-best-action decisioning](/concepts/decisioning) — policy-layer variant decisioning that consumes the same prompt metamodel.
* [AI agents on Orbit: build, deploy, and monitor](/agents/overview) — the feature entry point for everything above.