Integration overview

The map of every way traffic flows between your systems and an agent — SDK conversations, event delivery, autonomous triggers and callbacks, third-party webhooks, and tool calls — with auth and links

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 §1–4
2a	Receive replies by polling — sess.events() long-poll stream, offset-resumable	agent → you (pulled)	Bearer	Integrating the SDK §5; wire shapes: Events & callbacks
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 §5; wire shapes: Events & callbacks
3	Trigger an automation — POST /routines/{routine_id}/trigger with typed JSON input	you → agent	Bearer	Autonomous routines; endpoint spec: HTTP API
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 §5; payload schema + error codes: Events & callbacks
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; setup + signature self-test: Authoring autonomous routines §6; hardening: Security
6	The agent calls your tools — MCP servers you run	agent → you	Optional per-server Bearer (mcps[].api_key)	Connecting tools
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

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.

• 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.

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.