> 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/reference/events-and-callbacks.md). # Events & callbacks > **Context** — The exact wire shapes the agent emits: conversation events (delivered via the polling stream **and** via event webhooks — same JSON either way) and the autonomous callback payload. JSON Schemas for everything here are published per version — see [Versioning & compatibility](/agents/operations/versioning.md#machine-readable-artifacts). ## Conversation events A session's event log is an ordered stream; every event carries: | Field | Type | Meaning | | ------------ | ------------------ | --------------------------------------------------------------------------------------------------------- | | `kind` | string | Discriminator — one of the kinds below. | | `offset` | integer | Monotonic position in the session. Resume with `min_offset = last + 1`; dedupe on `(session_id, offset)`. | | `created_at` | RFC 3339 timestamp | Server-side creation time. | In webhook delivery mode each event is POSTed individually to your endpoint with `Authorization: Bearer ` and the originating session in the `x-session-id` header. Retries with backoff on non-2xx. ### `user_message` | Field | Type | Required | Default | Description | | ------------ | ------- | -------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `offset` | integer | yes | — | Monotonic position in the session's event log. Resume polling with min\_offset = last seen offset + 1; dedupe on (session\_id, offset). | | `created_at` | string | yes | — | Server-side event creation time. | | `text` | string | yes | — | Message body. | | `kind` | string | no | `"user_message"` | | ```json { "kind": "user_message", "offset": 4, "created_at": "2026-06-04T10:15:00Z", "text": "Can I rent a van for Saturday?" } ``` ### `preamble` | Field | Type | Required | Default | Description | | ------------ | ------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | `offset` | integer | yes | — | Monotonic position in the session's event log. Resume polling with min\_offset = last seen offset + 1; dedupe on (session\_id, offset). | | `created_at` | string | yes | — | Server-side event creation time. | | `text` | string | yes | — | Message body. | | `kind` | string | no | `"preamble"` | | ```json { "kind": "preamble", "offset": 5, "created_at": "2026-06-04T10:15:01Z", "text": "Let me check." } ``` ### `assistant_message` | Field | Type | Required | Default | Description | | ------------ | ------- | -------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `offset` | integer | yes | — | Monotonic position in the session's event log. Resume polling with min\_offset = last seen offset + 1; dedupe on (session\_id, offset). | | `created_at` | string | yes | — | Server-side event creation time. | | `text` | string | yes | — | Message body. | | `kind` | string | no | `"assistant_message"` | | ```json { "kind": "assistant_message", "offset": 7, "created_at": "2026-06-04T10:15:06Z", "text": "Yes \u2014 the VW Multivan is available at 110 EUR/day." } ``` ### `status` Engine lifecycle signal — `typing`, `processing`, `ready`, etc. | Field | Type | Required | Default | Description | | -------------- | ------- | -------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `offset` | integer | yes | — | Monotonic position in the session's event log. Resume polling with min\_offset = last seen offset + 1; dedupe on (session\_id, offset). | | `created_at` | string | yes | — | Server-side event creation time. | | `kind` | string | no | `"status"` | | | `status` | string | yes | — | Lifecycle signal: acknowledged, typing, processing, ready, cancelled, or error. | | `stage` | string | no | `null` | Sub-stage label shown alongside 'processing' (e.g. 'Thinking'). | | `error_detail` | string | no | `null` | Failure detail, populated only when status is 'error'. | ```json { "kind": "status", "offset": 8, "created_at": "2026-06-04T10:15:06Z", "status": "ready", "stage": null, "error_detail": null } ``` ### `tool` One tool event — contains every tool call from that batch. | Field | Type | Required | Default | Description | | ------------ | --------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `offset` | integer | yes | — | Monotonic position in the session's event log. Resume polling with min\_offset = last seen offset + 1; dedupe on (session\_id, offset). | | `created_at` | string | yes | — | Server-side event creation time. | | `kind` | string | no | `"tool"` | | | `tool_calls` | list\[ToolCall] | yes | — | Every tool call the engine ran in this batch. | ```json { "kind": "tool", "offset": 6, "created_at": "2026-06-04T10:15:04Z", "tool_calls": [ { "tool_id": "cars:search_cars", "arguments": { "category": "van", "min_seats": 7 }, "result": { "results": [ { "car_id": "van-1", "make": "VW", "model": "Multivan", "daily_price_eur": 110 } ] } } ] } ``` `status` values: `acknowledged`, `typing`, `processing` (with optional `stage` sub-label), `ready`, `cancelled`, `error` (with `error_detail`). UI mapping: [Integrating the SDK](/agents/guides/integrating-the-sdk.md#status-events-drive-your-ui). Unknown kinds and message events without text should be ignored by consumers (the SDK's parsers already do). ## Autonomous trigger request Body of `POST /routines/{routine_id}/trigger` — see the [HTTP API](/agents/reference/http-api.md#trigger-an-autonomous-routine) for the endpoint semantics: | Field | Type | Required | Default | Description | | ----------------- | ------------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------- | | `input` | dict\[string, JsonValue] | no | — | Validated against the routine's input\_schema. | | `callback_url` | string | yes | — | URL that receives the AutonomousCallbackPayload when the run settles. | | `session_id` | string | no | `null` | Reuse an existing session. If omitted an ephemeral session + customer are created and deleted after the callback settles. | | `idempotency_key` | string | no | `null` | Replay-safe key — duplicates return the prior run. | | `metadata` | dict\[string, JsonValue] | no | — | Opaque caller metadata echoed back in the callback payload. | ## Autonomous callback payload POSTed once to the trigger's `callback_url` when the run settles (succeeds, fails, or times out), with `Authorization: Bearer `. Dedupe deliveries by `run_id`. ### `AutonomousCallbackPayload` Payload delivered to `callback_url` when a run settles. | Field | Type | Required | Default | Description | | ----------------- | ------------------------ | -------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `schema_version` | integer | no | `1` | Wire schema version of this payload. | | `run_id` | string | yes | — | Unique id of this run — dedupe callbacks on it. | | `routine_id` | string | yes | — | Id of the routine that was triggered. | | `status` | AutonomousRunStatus | yes | — | Settled run status. Callbacks only carry the terminal values 'succeeded' or 'failed'. | | `output` | dict\[string, JsonValue] | no | `null` | Routine's typed output, matching its output\_schema. Present only when status is 'succeeded'. | | `error` | AutonomousRunError | no | `null` | Structured error detail. Present only when status is 'failed'. | | `session_id` | string | yes | — | Session the run executed in — the caller's session\_id if reused, else the server-created ephemeral one. | | `trace_id` | string | no | `null` | Tracing id for correlating this run's logs/traces. | | `started_at` | string | yes | — | When the run began executing. | | `completed_at` | string | yes | — | When the run settled (success, failure, or timeout). | | `metadata` | dict\[string, JsonValue] | no | — | Caller-supplied metadata from the trigger request, echoed back verbatim. | | `idempotency_key` | string | no | — | Random id generated for this callback delivery; stable across the delivery's own HTTP retries. Unrelated to the trigger request's idempotency\_key, which dedupes runs, not deliveries. | | `origin_service` | string | no | `"agent-server"` | Identifies the service that sent this callback. | `status` values: `accepted`, `running`, `succeeded`, `failed` (callbacks carry only the settled states `succeeded` / `failed`). ### Error codes (`error.code` when `status` is `failed`) | Code | Meaning | | ------------------------------- | -------------------------------------------------------------------------------------- | | `timeout` | Run exceeded its `timeout_seconds`. | | `engine_error` | Internal engine failure during the run. | | `tool_error` | A tool call failed irrecoverably. | | `output_validation_failed` | The final output violated the routine's `output_schema` (details carry the JSON path). | | `input_validation_failed` | The input payload violated `input_schema`. | | `session_error` | Session preparation or engine dispatch failed. | | `max_engine_iterations_reached` | The engine hit `max_engine_iterations` before `emit_output` was called. | `error` is an object: `{code, message, details}` — `details` is a code-specific object (e.g. the violating JSON `path` for validation failures). **Example — success:** ```json { "schema_version": 1, "run_id": "run_9f8e7d6c5b4a3f2e1d0c9b8a", "routine_id": "kyc-decision", "status": "succeeded", "output": { "decision": "approved", "explanation": "Document and selfie match." }, "error": null, "session_id": "sess_abc123", "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736", "started_at": "2026-06-04T10:15:00+00:00", "completed_at": "2026-06-04T10:15:21+00:00", "metadata": { "ticket": "OPS-441" }, "idempotency_key": "a1b2c3d4e5f60718293a4b5c6d7e8f90", "origin_service": "agent-server" } ``` **Example — failure:** ```json { "schema_version": 1, "run_id": "run_1b2c3d4e5f60718293a4b5c6", "routine_id": "kyc-decision", "status": "failed", "output": null, "error": { "code": "output_validation_failed", "message": "'decision' is a required property", "details": { "path": [], "schema_path": [ "required" ] } }, "session_id": "sess_def456", "trace_id": "00f067aa0ba902b7a3ce929d0e0e4736", "started_at": "2026-06-04T11:02:00+00:00", "completed_at": "2026-06-04T11:02:09+00:00", "metadata": {}, "idempotency_key": "0f1e2d3c4b5a69788796a5b4c3d2e1f0", "origin_service": "agent-server" } ``` --- # 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, and the optional `goal` query parameter: ``` GET https://docs.interactive.ai/agents/reference/events-and-callbacks.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.