Architecture

How an Interactive Agent deployment fits together: the agent server, the InteractiveAI platform, the LLM router, MCP tool servers, storage, and the knowledge base.

Context — Start here. This page names every moving part; the rest of the documentation assumes you know these names. No prior knowledge needed.

YAML examples follow manifest schema 6.1.5. Manifest and content shapes are schema-versioned and differ across runtime versions — see Versioning & compatibility.

The pieces

                     ┌─────────────────────────────────────┐
                     │         InteractiveAI platform       │
                     │   content catalog · LLM router ·     │
                     │            traces backend            │
                     └───────────┬─────────────┬────────────┘
          context fetch (boot),  │             │  LLM calls (chat + evaluation),
          secrets, hosting       │             │  OTel traces (per turn)
                                 ▼             ▼
  ┌──────────────┐  SDK / REST   ┌───────────────────────────┐   MCP    ┌──────────────┐
  │     Your     │◄─────────────►│        Agent server        │◄────────►│   Your MCP   │
  │ integration  │  sessions,    │   one agent per container  │   tool   │ tool servers │
  │  (UI, CRM,   │  events,      │   engine · sessions ·      │   calls  └──────────────┘
  │ backend job) │  triggers     │   webhooks · /chat UI      │
  └──────────────┘               └───────┬─────────────┬──────┘
                                          │             │
                            Postgres /    │             │   pgvector /
                            in-memory     ▼             ▼   HTTP endpoint
                                ┌────────────────┐ ┌──────────────────┐
                                │  session store │ │  knowledge base  │
                                │   (optional)   │ │    (optional)    │
                                └────────────────┘ └──────────────────┘

Component	Owned by	Role
Agent server	InteractiveAI (the platform hosts and runs it)	The runtime. One container = one agent. Hosts the engine, the HTTP API, session state, and webhook entry points.
InteractiveAI platform	InteractiveAI	Stores versioned content (system prompt, routines, policies, glossaries, macros), serves the LLM router, and receives traces. The agent fetches its content from the platform once at boot.
LLM router	InteractiveAI	Single endpoint for all model calls. The agent never talks to a model provider directly — every inference call (chat, evaluation, embeddings) goes through <platform base_url>/api/v1/ with your router API key.
MCP tool servers	You — a service you deploy in the platform, or a remote server you host	HTTP services implementing the Model Context Protocol. Each server's tools become callable by the agent under a namespace (crm:search, cars:create_booking). See Tools.
Session store	You — a database in the platform, a remote Postgres, or in-memory	Conversation history, customers, and context variables. Omit the database block for ephemeral in-memory storage; point it at Postgres (in the platform or remote) for persistence. See Sessions, memory & state.
Knowledge base	You — a database in the platform, a remote pgvector store, or your own HTTP endpoint	Optional retrieval grounding: a pgvector collection the agent searches directly, or an HTTP search endpoint you own. See Knowledge base & retrieval.
Your integration	You	The service that connects a channel (web chat, Zendesk, Slack, IVR, a backend job) to the agent via the Python SDK or raw REST. See Integrating the SDK.

The engine

Inside the agent server sits the Interactive Agents engine — the loop that turns an incoming event into a reply or a typed result. Per turn, it:

1. Matches active policies against the conversation.

2. Evaluates which routine applies and which step of it comes next.

3. Decides whether to call tools, run a think step, or speak.

4. Iterates (up to max_engine_iterations, default 5) until the turn is complete, then emits typed events.

The full walkthrough is in Conversation lifecycle.

The engine makes two distinct kinds of model calls — customer-facing chat calls and internal evaluation calls — routed to independently configured models. This split matters operationally; see Models.

Configuration model

Everything the agent is comes from one manifest plus the versioned content it references:

name: DriveAway Demo
id: driveaway-demo
version: "1"
agent_config:
  runtime:
    api_key: ${AGENT_API_KEY}
  interactive_platform:
    public_key: ${INTERACTIVEAI_PUBLIC_KEY}
    secret_key: ${INTERACTIVEAI_SECRET_KEY}
  llms:
    default: anthropic/claude-haiku-4.5
    api_key: ${ROUTER_API_KEY}
  context:
    system_prompt:
      id: system-prompt
      version: 1
    language: match_user
    routines:
      - id: car-search
        version: 1
    policies:
      - id: stay-on-topic
        version: 1
  mcps:
    - id: cars
      hostname: http://cars-mcp
      port: 8765
      transport: streamable-http

Three rules govern the manifest:

1. Content is referenced, not inlined. Routines, policies, glossaries, and the system prompt live in the platform's versioned catalog — you create and publish them in the InteractiveAI platform, where each save produces a new immutable version, and the document's catalog name is the id the manifest references. The manifest pins exact versions; updating behaviour means publishing a new content version and bumping the pin.

2. Secrets are env-refs, never literals. Every credential field takes a ${VAR_NAME} reference; the platform supplies the value from your secret bundle at boot. A missing variable fails the boot with the variable's name — there is no fallback path. See Environment variables.

3. One manifest, one agent, one container. There is no multi-tenant mode. Autoscaling is on by default and managed by the platform — it adds and removes replicas of your agent internally as demand changes, so scaling an agent up under load (and back down) is handled for you rather than something you configure or operate.

The complete field-by-field schema is in Manifest & content schemas.

Boot sequence

Understanding boot order explains most startup-time behaviour:

1. Parse & validate the manifest. Structural errors fail immediately with every violation listed (the platform also runs this validation when you upload the manifest).

2. Resolve secrets — every ${VAR} env-ref is dereferenced against the secret bundle the platform injected. Any missing required variable aborts boot, naming the variable.

3. Fetch content — the server pulls every referenced routine, policy, glossary, macro, and prompt from the platform at the pinned versions (up to 5 fetches in parallel). A missing reference aborts boot.

4. Connect tool servers — each declared MCP server is contacted and its tools are catalogued.

5. Apply configuration — the agent, policies, routines, retrievers, and webhooks are wired into the engine.

6. Routine evaluation runs — the engine pre-computes behavioural metadata for every routine and policy (which steps speak vs. call tools, which depend on customer input, each node's reachable follow-ups). These are model calls and can take minutes on a cold cache; results are cached by content hash, so warm boots skip this entirely. The stages and their purpose: Startup evaluation; caching and pre-warming: Startup evaluation.

7. The agent starts serving — the HTTP port binds and GET /health/ready begins answering 200 only after evaluation settles. The port isn't open before that, so a cold-cache evaluation delays when the agent becomes reachable at all — which is exactly why the evaluation cache is pre-warmed, so deploys come up fast rather than waiting through a full evaluation.

If startup fails at any stage the process exits non-zero (within 10 seconds) so the platform restarts it instead of leaving a half-configured agent serving traffic.

Network surface

All inbound paths on the agent server:

Path	Auth	Purpose
GET /health/live, GET /health/ready, GET /health	none	Probes
POST /sessions/{id}/events	Bearer	Post a customer or system message into a session (this is how a turn is started)
GET /sessions/{id}/events	Bearer	Receive the agent's events — the long-poll / SSE stream of replies, tool calls, and status, resumable from an offset
Sessions & customers API (POST /sessions, GET /sessions/{id}, /customers/…)	Bearer	Create/read sessions and customers, set variables and metadata
POST /routines/{routine_id}/trigger	Bearer	Fire an autonomous routine
POST /webhooks/{name}	HMAC over raw body	Third-party webhook entry
POST /sessions/{session_id}/tool_events	Bearer	Inject external context as a synthetic tool result
GET /journeys/{journey_id}/graph	Bearer	Routine graph for dashboards (the journeys path segment is legacy wire naming for routines)
GET /chat	Bearer or agent_auth cookie	Built-in browser chat UI for trying the agent directly (cookie login via /auth/login; not meant as a production channel)

The conversation surface — posting messages and receiving events — is normally driven through the SDK rather than called directly; see Integrating the SDK and the full HTTP API reference.

Bearer auth compares Authorization: Bearer <token> in constant time against the manifest's runtime.api_key. Outbound, the agent calls: the platform (boot-time content fetch), the LLM router (every turn), your MCP servers (tool calls), your knowledge base, your callback/webhook URLs, and the traces backend. There are no other outbound calls — in particular, the agent never pushes conversation replies to your integration unless you opt in to event webhook delivery (see Integrating the SDK).

Where to go next

• The turn-by-turn engine walkthrough: Conversation lifecycle

• Build something: Quickstart

• Field-level reference: Manifest & content schemas