Events & callbacks

Exact wire shapes: conversation events (polling and webhook delivery) and the autonomous callback payload, with status and error-code tables.

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.

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 <agent api key> 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"

{
  "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"

{
  "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"

{
  "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'.

{
  "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.

{
  "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.

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 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 <agent api key>. 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:

{
  "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:

{
  "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"
}