Turn events reference

For a guided walkthrough, see Use an agent — Subscribe to events.

Turn Events

turn.execute({ stream: true }) (or turn.stream() when reconnecting) streams Server-Sent Events (SSE). Each event is a JSON object with a type field.

The stream always opens with turn.created and closes with turn.done.
All events carry a thread_id. Thread-scoped events use "main" (root agent) or a unique sub-agent ID; turn-level events use None.
thread.created and thread.done track sub-agent threads only - they are not emitted for the main thread, which is created automatically on the first Turn and lives for the session’s lifetime.
All events carry an id. It identifies the logical event and is present in both stream() and list_events().
Events delivered via execute({ stream: true }) and stream() also carry a sequence_number, monotonically increasing within a turn.
All events carry a created_at ISO-8601 timestamp marking when the event was emitted.
turn.created and turn.done are stream-only; they appear on the stream but are not returned by listEvents() / list_events().

`type`	Description
`turn.created`	First event on the stream. Carries `turn_id`.
`turn.done`	Last event on every stream. Carries the final `state`.

Model output.

`type`	Description
`model.message.delta`	LLM output - assistant text and/or tool call chunks. Streamed as `ModelMessageDeltaEvent`. Most frequent event.
`model.message`	Assembled model message. Returned by `listEvents()` / `list_events()` as `ModelMessageEvent`.

Tool calls and results.

`type`	Description
`tool.response`	Complete server-side tool result.
`tool.approval_required`	A tool call is awaiting human approval. Resume with an approval.
`tool.response_required`	A client-side tool was called and needs a result. Resume with the tool response.

Sub-agent thread lifecycle.

`type`	Description
`thread.created`	A sub-agent thread started. Not emitted for the main thread.
`thread.done`	A sub-agent thread completed (`done`) or failed (`error`). Not emitted for the main thread; does not close the stream.

MCP server lifecycle.

`type`	Description
`mcp.initialize`	One or more MCP server sessions were initialized.
`mcp.auth_required`	MCP server(s) need OAuth before proceeding. Resume after the user authorizes.

Sandbox lifecycle.

`type`	Description
`sandbox.created`	A sandbox was provisioned for the Turn.

TurnCreatedEvent

First event on every Turn stream, carrying the Turn’s turn_id and metadata. Stream-only.

Field	Type	Required	Description
`type`	`"turn.created"`	Yes
`id`	string	Yes	Unique event identifier.
`thread_id`	`null`	Yes	Always `null` — turn-level event, not tied to a thread.
`turn_id`	string	Yes	Unique ID for this Turn.
`previous_turn_id`	string \| None	No	Turn ID this Turn chains from, or `None` for the first Turn in a session.
`state`	`TurnStateRunning`	Yes	Always `{ "status": "running" }` on this event.
`created_by`	`Subject`	Yes	Subject (user / service account) that created this turn.
`created_at`	string	Yes	ISO-8601 timestamp when the Turn was created.

ModelMessageDeltaEvent

The most frequent SSE event. Carries an incremental LLM delta for one message - assistant text and/or tool call chunks. Every delta shares the id of the base ModelMessageEvent it belongs to; merge each delta into that base event in your id-keyed event index. A delta with a non-null finish_reason signals the message is complete. Use the merge pattern to fold a delta into its base event in place. Import is_event_delta and merge_event_delta from truefoundry_gateway_sdk.agents (Python) or truefoundry-gateway-sdk/agents (TypeScript).

Field	Type	Required	Description
`type`	`"model.message.delta"`	Yes
`id`	string	Yes	Shared by all deltas of one message; equal to the assembled `ModelMessageEvent` `id`. Use `sequence_number` to distinguish individual deltas.
`thread_id`	string	Yes	Thread this message belongs to. `"main"` for the root agent; a unique ID for sub-agents.
`content`	string	No	Incremental text content for this delta.
`reasoning_content`	string	No	Incremental reasoning/thinking text for this delta; concatenate across deltas.
`tool_calls`	`ToolCallDelta[]`	No	Tool call chunks to accumulate by `index`; fully assembled when `finish_reason` is set.
`finish_reason`	string	No	Set on the final delta. Signals the accumulated message is complete.

Each ToolCallDelta is shaped like an OpenAI streaming tool-call chunk. id, type, and tool_info appear only on the first chunk for a given index; function.arguments is a partial JSON string concatenated across chunks.

Field	Type	Required	Description
`index`	int	Yes	Position in the `tool_calls` array; used to merge chunks.
`id`	string	No	Tool call ID. First chunk only.
`type`	`"function"`	No	First chunk only.
`function`	`ToolCallFunctionDelta`	Yes	The function name and partial arguments for this chunk.
`tool_info`	`ToolCallInfo`	No	Tool metadata. First chunk only.

ToolCallFunctionDelta:

Field	Type	Required	Description
`name`	string	No	Tool name. Present only in the first chunk for this `index`.
`arguments`	string	No	Partial JSON string; concatenate across chunks.

ToolCallInfo carries metadata about the tool, discriminated on type. Read the tool name from name. For MCP-backed tools (type: "mcp"):

Field	Type	Required	Description
`type`	`"mcp"`	Yes
`server_id`	string	Yes	ID of the MCP server backing this tool.
`server_name`	string	Yes	Name of the MCP server backing this tool.
`name`	string	Yes	The tool’s original name on the MCP server.

For built-in TrueFoundry system tools (type: "truefoundry-system"), for example ask_user_question:

Field	Type	Required	Description
`type`	`"truefoundry-system"`	Yes
`name`	string	Yes	The system tool’s name.

ModelMessageEvent

The complete, assembled form of a model message: fully concatenated content and fully reconstructed tool_calls, with finish_reason set. Returned by listEvents() / list_events(); on the stream, the assistant output arrives as ModelMessageDeltaEvent deltas that merge into a base event with the same id.

Field	Type	Required	Description
`type`	`"model.message"`	Yes
`id`	string	Yes	Shared across all deltas of one message. Equal to the `id` carried by this message’s `model.message.delta` events.
`thread_id`	string	Yes	Thread this message belongs to. `"main"` for the root agent; a unique ID for sub-agents.
`content`	string	No	The complete assistant text.
`reasoning_content`	string	No	The complete reasoning/thinking text.
`tool_calls`	`ToolCall[]`	No	Fully assembled tool calls.
`finish_reason`	string	Yes	Why the message ended (for example, `"stop"` or `"tool_calls"`).

Each ToolCall is shaped like OpenAI’s ChatCompletionMessageToolCall. Read the tool name from tool_info.name.

Field	Type	Required	Description
`id`	string	Yes	Tool call ID.
`type`	`"function"`	Yes	Always `"function"`.
`function`	`ToolCallFunction`	Yes	The tool name and complete arguments.
`tool_info`	`ToolCallInfo`	No	Tool metadata (same shape as above).

ToolCallFunction:

Field	Type	Required	Description
`name`	string	Yes	Tool name.
`arguments`	string	Yes	Complete JSON string of the tool’s input arguments.

ToolResponseEvent

A complete server-side tool result returned to the LLM. Not a streaming delta - one event carries the full result.

Field	Type	Required	Description
`type`	`"tool.response"`	Yes
`thread_id`	string	Yes	Thread this result belongs to.
`tool_call_id`	string	Yes	Links this result back to the originating tool call.
`content`	string	Yes	The tool result.

ThreadCreatedEvent

Emitted when a sub-agent thread starts.

Not emitted for the main thread. The main thread (thread_id: "main") is the root agent; it is created automatically on the session’s first Turn and is never the subject of a thread.created or thread.done event. thread.created/thread.done track only sub-agent threads.

Field	Type	Required	Description
`type`	`"thread.created"`	Yes
`thread_id`	string	Yes	Unique ID for the sub-agent thread.
`title`	string	No	Human-readable label for the sub-agent thread.
`parent`	`AgentParent`	Yes	Parent thread and tool call that spawned this sub-agent.
`agent_info`	`AgentInfo`	Yes	Type, name, and input of the thread’s agent.

AgentInfo:

Field	Type	Required	Description
`type`	`"dynamic"`	Yes	How the sub-agent was defined.
`name`	string	Yes	The sub-agent’s name.
`input`	string	No	The input the parent thread handed to the sub-agent.

ThreadDoneEvent

Emitted when a sub-agent thread reaches a terminal state. Does not terminate the overall turn stream. Inspect state.status ("done" or "error") on the nested ThreadState object.

Not emitted for the main thread. The main thread is never “done” - it lives across Turns for the lifetime of the session. The overall Turn’s completion is signalled by turn.done, and the session ends only when it is cancelled.

Field	Type	Required	Description
`type`	`"thread.done"`	Yes
`id`	string	Yes	Unique event identifier.
`thread_id`	string	Yes	Unique ID for the sub-agent thread.
`title`	string	Yes	Human-readable label for the sub-agent thread.
`parent`	`AgentParent`	No	Parent thread and tool call that spawned this sub-agent.
`state`	`ThreadState`	Yes	Terminal thread state: `done` (with `output`) or `error` (with `error`).
`created_at`	string	Yes	ISO-8601 timestamp when the event was emitted.

McpInitializeEvent

Emitted when one or more MCP server sessions are initialized for a thread.

Field	Type	Required	Description
`type`	`"mcp.initialize"`	Yes
`thread_id`	string	Yes
`mcp_servers`	`McpServerInitInfo[]`	Yes	List of initialized MCP servers, each with `name` and `session_id`.

SandboxCreatedEvent

Emitted once when a sandbox is provisioned for the Turn. The sandbox is reused across Turns within the session.

Field	Type	Required	Description
`type`	`"sandbox.created"`	Yes
`thread_id`	`null`	Yes	Always `null` — turn-level event, not tied to a thread.
`sandbox_id`	string	Yes	Unique identifier for the provisioned sandbox.

McpAuthRequiredEvent

Emitted when one or more MCP servers require OAuth authorization before the agent can proceed. The stream ends after this event. Resume by creating a new turn on the same session with prepareTurn() / prepare_turn() after the user completes the OAuth flow — no input is required (omit input or pass []).

Field	Type	Required	Description
`type`	`"mcp.auth_required"`	Yes
`thread_id`	`null`	Yes	Always `null` — turn-level event. Blocked threads are listed per server in `mcp_servers[].thread_ids`.
`mcp_servers`	`McpServerAuthInfo[]`	Yes	List of servers needing authorization, each with `id`, `name`, and `auth_url`.

ToolApprovalRequiredEvent

Emitted when one or more tool calls require explicit human approval before they can run. The stream ends after this event. Resume by creating a new turn with UserToolApprovalEvent items — one per pending tool_call_id — via prepareTurn() / prepare_turn().

Field	Type	Required	Description
`type`	`"tool.approval_required"`	Yes
`thread_id`	string	Yes
`tool_calls`	`ToolCallRef[]`	Yes	The tool calls awaiting approval, each with a `tool_call_id` (`id`) and the `source_event_id` of the `model.message` that emitted it — look it up in your event index for the tool name and arguments.

ToolResponseRequiredEvent

Emitted when the agent has called a client-side tool and is waiting for the result. The stream ends after this event. Resume by creating a new turn with UserToolResponseEvent items — one per pending tool_call_id — via prepareTurn() / prepare_turn().

Field	Type	Required	Description
`type`	`"tool.response_required"`	Yes
`thread_id`	string	Yes
`tool_calls`	`ToolCallRef[]`	Yes	The tool calls awaiting a client-supplied result, each with a `tool_call_id` (`id`) and the `source_event_id` of the `model.message` that emitted it — look it up in your event index for the tool name and arguments.

TurnDoneEvent

Final event on every turn stream. Stream-only. Its state is the terminal state object — the same value in turn.state once the turn completes — so callers don’t need a separate turn fetch to know what happened.

Field	Type	Required	Description
`type`	`"turn.done"`	Yes
`thread_id`	`null`	Yes	Always `null` — turn-level event, not tied to a thread.
`state`	`TurnTerminalState`	Yes	The Turn’s terminal state; never running. See `TurnTerminalState`.

TurnTerminalState

The terminal lifecycle state of a turn, available on turn.state and carried by TurnDoneEvent’s state. It is one of three objects, discriminated on status: TurnStateDone, TurnStateCancelled, or TurnStateError. (The non-terminal TurnStateRunning, on turn.state while a turn is still running, has only status: "running".)

TurnStateDone

The turn completed normally.

Field	Type	Required	Description
`status`	`"done"`	Yes
`output`	`TurnStateDoneOutput` \| `null`	No	The final assistant message, or `null` if the turn paused (then `required_actions` is populated).
`required_actions`	(`ToolApprovalRequiredEvent` \| `ToolResponseRequiredEvent` \| `McpAuthRequiredEvent`)[]	Yes	Pause events to act on. Empty when the turn finished without pausing.
`completed_at`	string	Yes	ISO-8601 timestamp when the turn completed.

TurnStateCancelled

The turn was cancelled.

Field	Type	Required	Description
`status`	`"cancelled"`	Yes
`reason`	string	No	Why the turn was cancelled.
`completed_at`	string	Yes	ISO-8601 timestamp when the turn was cancelled.

TurnStateError

The turn failed.

Field	Type	Required	Description
`status`	`"error"`	Yes
`message`	string	Yes	Human-readable error description.
`completed_at`	string	Yes	ISO-8601 timestamp when the turn failed.

Agent Harness

Agent Governance

Turn Events

TurnCreatedEvent

ModelMessageDeltaEvent

ModelMessageEvent

ToolResponseEvent

ThreadCreatedEvent

ThreadDoneEvent

McpInitializeEvent

SandboxCreatedEvent

McpAuthRequiredEvent

ToolApprovalRequiredEvent

ToolResponseRequiredEvent

TurnDoneEvent

TurnTerminalState

TurnStateDone

TurnStateCancelled

TurnStateError

​Turn Events

​TurnCreatedEvent

​ModelMessageDeltaEvent

​ModelMessageEvent

​ToolResponseEvent

​ThreadCreatedEvent

​ThreadDoneEvent

​McpInitializeEvent

​SandboxCreatedEvent

​McpAuthRequiredEvent

​ToolApprovalRequiredEvent

​ToolResponseRequiredEvent

​TurnDoneEvent

​TurnTerminalState

​TurnStateDone

​TurnStateCancelled

​TurnStateError

Turn Events

TurnCreatedEvent

ModelMessageDeltaEvent

ModelMessageEvent

ToolResponseEvent

ThreadCreatedEvent

ThreadDoneEvent

McpInitializeEvent

SandboxCreatedEvent

McpAuthRequiredEvent

ToolApprovalRequiredEvent

ToolResponseRequiredEvent

TurnDoneEvent

TurnTerminalState

TurnStateDone

TurnStateCancelled

TurnStateError