> For the complete documentation index, see [llms.txt](https://docs.interactive.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.interactive.ai/agents/guides/integration-overview.md). # Integration overview > **Context** — One page mapping **every traffic direction** between your systems and a running agent. Use it to decide which integration surfaces you need, then follow the link for each. No prior reading needed. ## The map ``` YOUR INTEGRATION AGENT SERVER THIRD PARTIES (UI, CRM, backend) (KYC, payments, …) ──────────────────── ───────────── ────────────────── Conversational (1) open session, ──────► post message (SDK) (2a) pull events ◄────── long-poll stream — or — (2b) receive events ◄────── POST to your event at your endpoint webhook URL Autonomous (3) POST /routines/ ──────► {id}/trigger (4) receive result ◄────── POST to your at callback_url callback_url ◄────── (5) POST /webhooks/{name} (HMAC-signed) Tools & data your MCP servers ◄────── (6) tool calls your KB / search ◄────── (7) retrieval ``` ## The seven flows | # | Flow | Direction | Auth | Where it's explained | | -- | ------------------------------------------------------------------------------------------------------------------ | -------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 1 | **Send a customer message** — `sessions.open()` + `post_user_message()` via the SDK | you → agent | Bearer (agent api key) | [Integrating the SDK](/agents/guides/integrating-the-sdk.md) §1–4 | | 2a | **Receive replies by polling** — `sess.events()` long-poll stream, offset-resumable | agent → you (pulled) | Bearer | [Integrating the SDK](/agents/guides/integrating-the-sdk.md) §5; wire shapes: [Events & callbacks](/agents/reference/events-and-callbacks.md) | | 2b | **Receive replies by webhook** — the agent POSTs each event to the URL you set at client construction (`webhook=`) | agent → you (pushed) | Bearer on the POST; `x-session-id` header routes it | [Integrating the SDK](/agents/guides/integrating-the-sdk.md) §5; wire shapes: [Events & callbacks](/agents/reference/events-and-callbacks.md) | | 3 | **Trigger an automation** — `POST /routines/{routine_id}/trigger` with typed JSON input | you → agent | Bearer | [Autonomous routines](/agents/concepts/autonomous-routines.md); endpoint spec: [HTTP API](/agents/reference/http-api.md#trigger-an-autonomous-routine) | | 4 | **Receive the typed result** — one POST to your `callback_url` per run, retried on failure | agent → you | Bearer on the POST; dedupe by `run_id` | Receiver code: [Authoring autonomous routines](/agents/guides/authoring-autonomous-routines.md) §5; payload schema + error codes: [Events & callbacks](/agents/reference/events-and-callbacks.md#autonomous-callback-payload) | | 5 | **Third-party provider fires a routine** — `POST /webhooks/{name}` from a KYC vendor, payment gateway, etc. | provider → agent | HMAC signature over the raw body (bypasses bearer) | Concept + declaration styles: [Autonomous routines](/agents/concepts/autonomous-routines.md#webhook-entry-points); setup + signature self-test: [Authoring autonomous routines](/agents/guides/authoring-autonomous-routines.md) §6; hardening: [Security](/agents/operations/security.md) | | 6 | **The agent calls your tools** — MCP servers you run | agent → you | Optional per-server Bearer (`mcps[].api_key`) | [Connecting tools](/agents/guides/connecting-tools.md) | | 7 | **The agent searches your knowledge base** — pgvector collection or your HTTP search endpoint | agent → you | Postgres auth / optional Bearer | [Setting up the knowledge base](/agents/guides/knowledge-base-setup.md) | Two more you-to-agent surfaces that don't fit the picture above: * **Inject external context** as a synthetic tool result (`POST /sessions/{session_id}/tool_events`) — for statements, history dumps, CRM exports the agent should treat as fetched data. See [Tools](/agents/concepts/tools.md#injecting-context-as-a-tool-event). * **Write agent-visible context** — customer **variables** via the SDK (visible to the agent next turn), vs **metadata** (your bookkeeping, invisible to the agent). The distinction matters constantly: [Sessions, memory & state](/agents/concepts/memory-and-state.md#variables-vs-metadata). ## Choosing your shape **A chat UI (web, mobile):** flows 1 + 2a. The browser talks to *your* backend; your backend holds the agent api key and relays over the SDK — the token never reaches the client. Polling fits because something is holding a connection anyway. **A server-to-server channel (Zendesk, Slack, IVR):** flows 1 + 2b. No browser to hold a socket — have the agent push events to your endpoint and route them into your channel by `x-session-id`. **A backend automation (no conversation):** flows 3 + 4. Typed JSON in, typed JSON out, schemas enforced at both ends. Add flow 5 if a third party should fire it directly instead of going through your service. **Any of the above with business actions:** add flow 6 — tools are how the agent acts on your systems, whatever the conversation surface is. ## One credential model to internalize Flows 1–4 and the tool-event/variables surfaces all ride **one shared bearer token** (the manifest's `runtime.api_key`): you send it inbound, and the agent sends the *same* token on its outbound POSTs to you (event webhooks, callbacks) — so your receivers must verify it. Flow 5 is the exception: the provider's HMAC signature *is* the auth. Flows 6–7 use credentials you choose per server. Full picture: [Security](/agents/operations/security.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.interactive.ai/agents/guides/integration-overview.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.