Data types

The data objects that the other classes take and return.

Message dataclass

Message(role: Literal['user', 'assistant'], content: tuple[Block, ...], tokens: int | None = None)

One message in the context (state.context).

The system prompt is not a message; it goes in Request.system.

role instance-attribute

role: Literal['user', 'assistant']

"user" or "assistant". Notices and tool results are user messages.

content instance-attribute

content: tuple[Block, ...]

The blocks in order: text, tool calls (assistant only), tool results (user only) and provider-specific blocks such as thinking.

tokens class-attribute instance-attribute

tokens: int | None = None

The token count of the whole context up to and including this message, from API usage. Set on assistant replies only; None if unknown.

text property

text: str

The text of all TextBlocks joined together.

tool_calls property

tool_calls: tuple[ToolCall, ...]

The tool calls in this message, in order.

user classmethod

user(text: str) -> Message

A user message with a single text.

ToolCall dataclass

ToolCall(name: str, args: dict[str, Any], id: str)

One tool call the model requested. Also a block of an assistant message.

Calls are told apart by id, and two calls with the same id hash the same.

name instance-attribute

name: str

The tool name the model called.

args instance-attribute

args: dict[str, Any]

The arguments the model gave, as a dict.

id instance-attribute

id: str

The call id. Tool results refer to the call by this id.

ToolSpec dataclass

ToolSpec(name: str, description: str, input_schema: dict[str, Any])

One tool shown to the model.

name instance-attribute

name: str

The tool name the model calls.

description instance-attribute

description: str

What the tool does, as the model reads it.

input_schema instance-attribute

input_schema: dict[str, Any]

The arguments as a JSON Schema object.

Request dataclass

Request(system: str | None, messages: tuple[Message, ...], tools: tuple[ToolSpec, ...] = (), tool_choice: Literal['auto', 'none'] = 'auto')

A request the Agent sends to the Model. Model settings (max_tokens etc.) belong to the Model object.

system instance-attribute

system: str | None

The system prompt, or None.

messages instance-attribute

messages: tuple[Message, ...]

The context to send.

tools class-attribute instance-attribute

tools: tuple[ToolSpec, ...] = ()

The tools shown to the model.

tool_choice class-attribute instance-attribute

tool_choice: Literal['auto', 'none'] = 'auto'

"auto" lets the model call tools. "none" still sends the tool definitions but forbids calling them.

Reply dataclass

Reply(message: Message, usage: Usage, context_tokens: int | None = None, stop_reason: str | None = None)

One reply from the Model.

message instance-attribute

message: Message

The assistant message. Blocks stay in the order the provider gave.

usage instance-attribute

usage: Usage

The usage of this one request (requests=1).

context_tokens class-attribute instance-attribute

context_tokens: int | None = None

The token count of the whole context up to and including this reply (input + cache read + cache write + output). None if unknown.

stop_reason class-attribute instance-attribute

stop_reason: str | None = None

Exactly what the provider gave, e.g. "end_turn", "tool_use" or "max_tokens".

text property

text: str

The text of the reply message.

tool_calls property

tool_calls: tuple[ToolCall, ...]

The tool calls in the reply message, in order.

Usage dataclass

Usage(input_tokens: int = 0, output_tokens: int = 0, cache_read_tokens: int = 0, cache_write_tokens: int = 0, requests: int = 0, cost: float | None = None)

Token usage. Every provider's counts are mapped to the same meanings, so total input is input_tokens + cache_read_tokens + cache_write_tokens.

Adding two Usages (+) returns a new one. Its cost is None if either side has requests but an unknown cost.

input_tokens class-attribute instance-attribute

input_tokens: int = 0

Input tokens that did not go through the cache.

output_tokens class-attribute instance-attribute

output_tokens: int = 0

Output tokens.

cache_read_tokens class-attribute instance-attribute

cache_read_tokens: int = 0

Input tokens read from the cache.

cache_write_tokens class-attribute instance-attribute

cache_write_tokens: int = 0

Input tokens newly written to the cache.

requests class-attribute instance-attribute

requests: int = 0

The number of model requests.

cost class-attribute instance-attribute

cost: float | None = None

Estimated dollars. None when the price is unknown, which is different from 0.

cache_hit_rate property

cache_hit_rate: float | None

The fraction of total input read from the cache. None when there is no input.

Price dataclass

Price(input: float, output: float, cache_read: float | None = None, cache_write: float | None = None)

Dollars per million tokens. Cache prices default to the input price when not given.

Example

Anthropic("claude-sonnet-5", price=Price(input=3, output=15, cache_read=0.3))

input instance-attribute

input: float

Dollars per million input tokens that did not go through the cache.

output instance-attribute

output: float

Dollars per million output tokens.

cache_read class-attribute instance-attribute

cache_read: float | None = None

Dollars per million tokens read from the cache. None uses input.

cache_write class-attribute instance-attribute

cache_write: float | None = None

Dollars per million tokens written to the cache. None uses input.

cost

cost(usage: Usage) -> float

The cost of usage in dollars.

HistoryEntry dataclass

HistoryEntry(kind: HistoryKind, content: Any, turn: int, call: ToolCall | None = None, error: BaseException | None = None, late: bool = False, substate: Any = None)

One entry of state.history. History only grows; shrinking the context never removes entries.

kind instance-attribute

kind: HistoryKind

What happened. content depends on it:

kind	content
user	str, what the person said. The first entry is the task
reply	Reply
tool_result	str, the result sent to the model. Has call
notice	str starting with "[notice] "
denied	str, the denial reason. Has call
ask	an object with question and answer (answer is None if no answer came)
human	same as ask
context_change	ContextChange
model_event	ModelEvent
error	str such as "TimeoutError: ...". error holds the exception

content instance-attribute

content: Any

The recorded value. Its type depends on kind.

turn instance-attribute

turn: int

state.turn when the entry was recorded.

call class-attribute instance-attribute

call: ToolCall | None = None

The tool call, for tool_result, denied and errors raised by a tool.

error class-attribute instance-attribute

error: BaseException | None = None

The exception, for error entries.

late class-attribute instance-attribute

late: bool = False

True for a tool result that arrived after its call was already closed.

ContextChange dataclass

ContextChange(kind: ContextChangeKind, before_tokens: int, after_tokens: int, summary: str | None = None)

A record that the context changed. Shown by Reporter.on_context_change and kept in history.

kind instance-attribute

kind: ContextChangeKind

"compact", "start_from", "clear_tool_results" or "rollback".

before_tokens instance-attribute

before_tokens: int

The estimated context size before the change (state.context_tokens).

after_tokens instance-attribute

after_tokens: int

The estimated context size after the change.

summary class-attribute instance-attribute

summary: str | None = None

The summary text compact or start_from put in the context. None for other kinds.

ModelEvent dataclass

ModelEvent(kind: str, message: str, data: Mapping[str, Any] = dict())

Something the Model went through while handling a request, such as falling back to another model or a retry. It is not part of the reply.

A Model reports it by calling on_event in respond or compact. The Agent records it in history (model_event) and shows it with Reporter.on_model_event.

kind instance-attribute

kind: str

A short type name, e.g. "fallback".

message instance-attribute

message: str

One line to show a person.

data class-attribute instance-attribute

data: Mapping[str, Any] = field(default_factory=dict)

Extra values the Model adds.

ToolOutcome dataclass

ToolOutcome(kind: ToolOutcomeKind, error: BaseException | None = None)

How a tool call ended, passed to Reporter.on_tool_end next to the result string.

The result string is written for the model and may change. Branch on kind instead of reading it.

kind instance-attribute

kind: ToolOutcomeKind

One of:

• "done": the tool returned, and the result is its output
• "error": the tool returned an error result, which the model sees as an error (an MCP server's isError)
• "input_error": the tool was not called because the tool is unknown or the arguments failed validation
• "aborted": the tool raised
• "interrupted": closed by KeyboardInterrupt or CancelledError
• "denied": closed by state.deny, and the result is the reason

error class-attribute instance-attribute

error: BaseException | None = None

The exception for "aborted" and "interrupted", otherwise None.

Content blocks

The parts of a Message. ToolCall above is also one.

TextBlock dataclass

TextBlock(text: str)

A piece of text.

ToolResultBlock dataclass

ToolResultBlock(call_id: str, content: str, name: str = '', is_error: bool = False)

The result of one tool call. Goes in user messages only.

content is exactly the string sent to the model (e.g. "(done)", "(input error: ...)", "(aborted: TimeoutError)", "(cleared: kept in history)", a denial reason).

RawBlock dataclass

RawBlock(provider: str, data: dict[str, Any])

A provider-specific block (thinking blocks, redacted_thinking, server tools, etc.).

data is kept exactly as received and sent back as is to the same provider. Never modified.