> 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 | — | | | `created_at` | string | yes | — | | | `text` | string | yes | — | | | `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 | — | | | `created_at` | string | yes | — | | | `text` | string | yes | — | | | `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 | — | | | `created_at` | string | yes | — | | | `text` | string | yes | — | | | `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 | — | | | `created_at` | string | yes | — | | | `kind` | string | no | `"status"` | | | `status` | string | yes | — | | | `stage` | string | no | `null` | | | `error_detail` | string | no | `null` | | ```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 | — | | | `created_at` | string | yes | — | | | `kind` | string | no | `"tool"` | | | `tool_calls` | list\[ToolCall] | yes | — | | ```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` | | | `run_id` | string | yes | — | | | `routine_id` | string | yes | — | | | `status` | AutonomousRunStatus | yes | — | | | `output` | dict\[string, JsonValue] | no | `null` | | | `error` | AutonomousRunError | no | `null` | | | `session_id` | string | yes | — | | | `trace_id` | string | no | `null` | | | `started_at` | string | yes | — | | | `completed_at` | string | yes | — | | | `metadata` | dict\[string, JsonValue] | no | — | | | `idempotency_key` | string | no | — | | | `origin_service` | string | no | `"agent-server"` | | `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: ``` GET https://docs.interactive.ai/agents/reference/events-and-callbacks.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.