Turn records

What a read or a wait of a turn returns: a TurnState, one of six records, and the values that the calls which start, steer or interrupt a turn return.

Guides: Turns and Session statuses.

type TurnState[T] = Running | Blocked | Completed[T] | Interrupted | Failed | UnknownOutcome

type TurnState[T] = Running | Blocked | Completed[T] | Interrupted | Failed | UnknownOutcome

A turn's state as of cursor: one of the six records Running, Blocked, Completed, Interrupted, Failed and UnknownOutcome.

class Running(*, session_id: str, turn_id: str, cursor: str, text: str | None)

class Running(*, session_id: str, turn_id: str, cursor: str, text: str | None)

The turn is working. Nothing waits on you.

class Blocked(
    *,
    session_id: str,
    turn_id: str,
    cursor: str,
    text: str | None,
    callbacks: tuple[OpenCallback, ...],
)

class Blocked(
    *,
    session_id: str,
    turn_id: str,
    cursor: str,
    text: str | None,
    callbacks: tuple[OpenCallback, ...],
)

The turn waits for an answer to one or more callbacks.

class Completed[T](
    *,
    session_id: str,
    turn_id: str,
    cursor: str,
    text: str | None,
    output: T | InvalidOutput | None,
    stop_reason: str | None = None,
    tool_calls: tuple[ToolCall, ...] = (),
)

class Completed[T](
    *,
    session_id: str,
    turn_id: str,
    cursor: str,
    text: str | None,
    output: T | InvalidOutput | None,
    stop_reason: str | None = None,
    tool_calls: tuple[ToolCall, ...] = (),
)

The turn completed, possibly early: see stop_reason.

With output_type, output is None when the turn ended early, so there is no answer to parse. Without output_type, it is the turn's text, also when the turn ended early (a skipped turn's text is the hook's reason, a cut-off turn's text is the cut-off reply), or "" when there is none.

class Interrupted(*, session_id: str, turn_id: str, cursor: str, text: str | None, cause: str)

class Interrupted(*, session_id: str, turn_id: str, cursor: str, text: str | None, cause: str)

The turn stopped before it completed.

When no cause is given, the SDK reads "cancelled" if the turn ended with its cancelled session, else "interrupted". text is what the turn said before it stopped.

class Failed(*, session_id: str, turn_id: str, cursor: str, text: str | None, error: ProtocolError)

class Failed(*, session_id: str, turn_id: str, cursor: str, text: str | None, error: ProtocolError)

The turn ended with an error, for example a refusal from the model provider.

class UnknownOutcome(
    *,
    session_id: str,
    turn_id: str,
    cursor: str,
    text: str | None,
    outcome: str,
    raw: dict[str, JsonValue] = {},
)

class UnknownOutcome(
    *,
    session_id: str,
    turn_id: str,
    cursor: str,
    text: str | None,
    outcome: str,
    raw: dict[str, JsonValue] = {},
)

The turn ended with an outcome added after your SDK version, such as "future_outcome".

Leave a case for this record, so your code still runs when outcomes are added.

class ProtocolError(
    *,
    message: str,
    code: str | None = None,
    retryable: bool = False,
    details: dict[str, JsonValue] | None = None,
)

class ProtocolError(
    *,
    message: str,
    code: str | None = None,
    retryable: bool = False,
    details: dict[str, JsonValue] | None = None,
)

An error from where the session runs, such as the one a turn failed with.

The code of a failed turn's error says what failed, so you can match on it:

• "completion_rejected": the model provider refused the request with an HTTP 4xx status other than 401, 403, 408, 409 and 429, for example an unknown model or an invalid parameter: fix the request.
• "completion_unauthorized": the model provider refused the credentials (HTTP 401 or 403). Not retryable.
• "completion_rate_limited": more requests than your rate limit allows (HTTP 429 with reason rate_limited). Retryable.
• "completion_unavailable": the model provider could not serve the request: no model capacity (HTTP 409, or any other 429), an outage or a server error. Retryable for a transient cause, such as HTTP 502, 503 or 504.
• "completion_timed_out": the provider answered HTTP 408, the model stopped producing output, or the call ran past its time limit. Retryable, except for a call past its time limit.
• "completion_context_too_large": the request is larger than the model's context window. Not retryable, except when the provider refuses it again right after a context compaction, or refuses even the smallest compaction request (details.reason is "after_compaction" or "minimal_summary_request").
• "completion_billing_denied": billing refused the request, for example because the budget is spent. Not retryable.
• "completion_failed": the model call failed without an HTTP status, for example a lost connection or a stream that ended early. Retryable.
• "completion_failed_permanently": the model call failed without an HTTP status and a retry will not help, for example a reply that reports no token usage: an OpenAI-compatible server must support stream_options.include_usage. Not retryable.
• "remote_session_failed": a served or deployed session failed or reached its time limit. The session has ended: start a new one.
• "capability_execution_failed": a hook other than pre_tool_call or post_tool_call raised an exception, or its saved state was too large. The message ends with the exception's text. Not retryable.
• "tool_raised": a tool raised an exception other than agents.ToolError on an agent with tool_errors="raise". The message names the tool and the exception's type. Not retryable.
• "tool_output_schema_mismatch": a tool's result did not match its output_schema= on an agent with tool_errors="raise". Not retryable.
• "invalid_compaction_summary": a context compaction failed: the model's summary was empty, had malformed <summary> delimiters, called tools, or reached the output token limit. Not retryable.
• "compaction_request_too_large": a context compaction could not start, because the context it must send does not fit under the compaction threshold. Not retryable.
• "compaction_replacement_too_large": the summary and the context the turn needs do not fit under the compaction threshold. Not retryable.
• "turn_failed": a served agent's error that has no code of its own.

class InvalidOutput(*, raw: JsonValue, error: str)

class InvalidOutput(*, raw: JsonValue, error: str)

The turn completed, but its output did not validate against the requested type.

class ToolCall(name: str, arguments: JsonValue)

class ToolCall(name: str, arguments: JsonValue)

One tool call the model made during the turn.

name is the tool's full ID, such as client.get_weather, not the name the model calls. A call to a tool that does not exist keeps the model's name. In the tool_calls of a post_llm_call or post_agent_turn hook, the call is not resolved yet, so name is the name the model called, such as get_weather. A call that did not run is listed too: a permission rule denied it, a user rejected it at approval, its approval timed out, a hook skipped it or failed on it, the agent refused it (invalid_tool_call: arguments that are not valid JSON or that the schema rejects, an unknown tool, wait beside other calls), or, inside run_typescript, its arguments did not match the tool's input schema or the program's time budget stopped it before it started. arguments is the call's arguments: in Completed.tool_calls, the ones a pre_tool_call hook set, else the model's; in a hook's tool_calls, the model's. Arguments that are not valid JSON are the raw string, and a session of a deployed agent may report any JSON value.

class TokenUsage(
    *,
    input_tokens: int,
    output_tokens: int,
    total_tokens: int,
    cached_input_tokens: int = 0,
    cache_write_tokens: int = 0,
    reasoning_tokens: int = 0,
)

class TokenUsage(
    *,
    input_tokens: int,
    output_tokens: int,
    total_tokens: int,
    cached_input_tokens: int = 0,
    cache_write_tokens: int = 0,
    reasoning_tokens: int = 0,
)

The tokens one model call used, as the provider reports them.

total_tokens is input_tokens plus output_tokens. cached_input_tokens counts the input tokens read from the provider's cache, and is part of input_tokens.

class OpenCallback(*, id: str, session_id: str, turn_id: str, kind: str, title: str | None)

class OpenCallback(*, id: str, session_id: str, turn_id: str, kind: str, title: str | None)

A callback that the turn, or one of its subagents, waits on: an OpenApproval, an OpenSignIn, an OpenClientToolCall or an UnknownOpenCallback.

turn.answer takes its id on any turn of its session or of a session above it in the tree. A subagent's callback has the subagent's IDs, its own turn included.

class OpenApproval(
    *,
    id: str,
    session_id: str,
    turn_id: str,
    kind: str,
    title: str | None,
    request: ApprovalRequest,
)

class OpenApproval(
    *,
    id: str,
    session_id: str,
    turn_id: str,
    kind: str,
    title: str | None,
    request: ApprovalRequest,
)

An approval the turn waits on.

Inherits id, session_id, turn_id, kind and title from OpenCallback.

class OpenClientToolCall[P, R](
    *,
    id: str,
    session_id: str,
    turn_id: str,
    kind: str,
    title: str | None,
    call: ClientToolCall,
)

class OpenClientToolCall[P, R](
    *,
    id: str,
    session_id: str,
    turn_id: str,
    kind: str,
    title: str | None,
    call: ClientToolCall,
)

A client tool call the turn waits on.

Check which tool it calls with <stub>.called(callback), then answer it with turn.answer(callback.id, await callback.run(fn)).

Inherits id, session_id, turn_id, kind and title from OpenCallback.

async def run(
    fn: Callable[P, R | ToolResult[Any] | Awaitable[R | ToolResult[Any]]],
    /,
) -> R | ToolResult[Any]

async def run(
    fn: Callable[P, R | ToolResult[Any] | Awaitable[R | ToolResult[Any]]],
    /,
) -> R | ToolResult[Any]

Call fn with the call's arguments, validated by the tool's stub, and return its result: what turn.answer(callback.id, ...) takes for this call.

fn takes the stub's parameters, without a context, and returns the stub's return type or an agents.ToolResult, synchronously or not. A synchronous fn runs in a tool thread. An exception fn raises propagates: tool_errors does not apply.

When the model's arguments do not match the stub, fn is not called: the result is an error agents.ToolResult saying why, so that answering it lets the model correct the call.

class OpenSignIn(
    *,
    id: str,
    session_id: str,
    turn_id: str,
    kind: str,
    title: str | None,
    requests: tuple[SignInRequest, ...],
)

class OpenSignIn(
    *,
    id: str,
    session_id: str,
    turn_id: str,
    kind: str,
    title: str | None,
    requests: tuple[SignInRequest, ...],
)

A sign-in the turn waits on: the agent asks the user to connect one or more sources, such as connectors, before it uses their tools.

Answer it with turn.answer(callback.id, agents.SignInAnswer(connected=..., denied=...)), naming each source by its id, or with an on_sign_in= handler, which gets this record. kind is "sign_in". on_client_tool never gets a sign-in.

Inherits id, session_id, turn_id, kind and title from OpenCallback.

class UnknownOpenCallback(
    *,
    id: str,
    session_id: str,
    turn_id: str,
    kind: str,
    title: str | None,
    raw: dict[str, JsonValue] = {},
)

class UnknownOpenCallback(
    *,
    id: str,
    session_id: str,
    turn_id: str,
    kind: str,
    title: str | None,
    raw: dict[str, JsonValue] = {},
)

A callback of a kind with no type of its own in your SDK version.

A later SDK version can give a kind a type of its own. Match on kind, and leave open the kinds that you do not know.

Inherits id, session_id, turn_id, kind and title from OpenCallback.

class Busy(*, session_id: str, active_turn_id: str, turn: Turn)

class Busy(*, session_id: str, active_turn_id: str, turn: Turn)

A new turn was not started, because another turn of the session is active.

This is not a turn state: no turn was started.

class TurnConflict(*, session_id: str, expected_turn_id: str, active_turn_id: str | None)

class TurnConflict(*, session_id: str, expected_turn_id: str, active_turn_id: str | None)

A request named a turn that is no longer the session's active turn. Nothing was applied: the session refused the request.