Events
Every session event type.
Each event is one JSON object: its sequence number seq, its created_at time, its type, and the fields of that type. See Streaming events for how to read them.
Session and messages
| Type | Fields | |
|---|---|---|
session_created |
agent_id, agent_version_id |
The session’s first event. |
message_user |
message, source |
Input. source is client, or steer when it was sent during a run. |
message_assistant |
message |
What the model wrote: text, thinking, and the tool calls it made. |
session_display_name_changed |
display_name, author |
Renamed, by user or agent. |
error |
message |
An error of the session’s, outside any run’s outcome. |
custom |
kind, payload |
The engine’s own bookkeeping. Skip it when rendering. |
A message has a role and content, an array of blocks:
| Block | |
|---|---|
{"type": "text", "data": {"text"}} |
Text, as Markdown |
{"type": "thinking", "data": {"thinking", "redacted"}} |
What the model thought, where its provider reports it |
{"type": "tool_call", "data": {"id", "name", "arguments"}} |
A call the model made |
{"type": "image", "data": {"media_type", "sha256"}} |
An image; its bytes are at GET /v1/sessions/{id}/images/{sha256} |
Runs
| Type | Fields | |
|---|---|---|
run_queued |
run_id |
Input started a run. |
run_started |
run_id |
The run began working. |
run_completed |
run_id |
It finished its turn. |
run_failed |
run_id, error |
It stopped on an error. |
run_cancelled |
run_id |
It was stopped. |
A run ends in exactly one of the last three.
Tools
| Type | Fields | |
|---|---|---|
tool_call |
call_id, name, arguments |
A call, by the name the model used: <kind>__<name>__<tool> (see Tools). |
tool_result |
call_id, content, is_error |
What it answered. |
Approvals and forms
| Type | Fields | |
|---|---|---|
approval_requested |
call_id, server, tool, arguments, args_hash |
A call waits for a person. |
approval_resolved |
call_id, decision, deny_message, resolved_by |
allow or deny. |
input_requested |
call_id, request |
The agent puts a form: request.questions. |
input_resolved |
call_id, resolution, resolved_by |
submitted, declined, or expired. |
resolved_by is who settled it: user:<id>, api_key:<id>, session:<id> for a session token, or system when it timed out after 24 hours. See Approvals and forms.
Clients
| Type | Fields | |
|---|---|---|
client_registered |
client_id, name, lifetime, tools |
A client joined, under the name it was given. |
client_tools_updated |
client_id, tools |
It replaced its tools. |
client_left |
client_id, reason |
departed, or timed_out. |
client_tool_dispatched |
call_id, client_id, tool, arguments |
A call sent to it, by the tool’s own name. |
client_tool_acked |
call_id, client_id |
It acknowledged the call. |
client_tool_failed |
call_id, client_id, reason |
client_gone, ack_timeout, result_timeout, or run_gone. |
See Client tools.