Models

The typed data every public entry point accepts and returns — all frozen (model_config = ConfigDict(frozen=True)), all in the compatibility surface (spec 05 §4): fields are never removed or narrowed within a major version.

Execution state

AgentState

Bases: BaseModel

Global shared state threaded through every superstep.

StateUpdate

Bases: BaseModel

The typed delta an agent emits instead of mutating shared state.

Message

Bases: BaseModel

One immutable message produced by an agent in a given superstep.

id is assigned deterministically by the kernel as f"{run_id}:{superstep}:{sender}:{index}" and valid_time comes from the runtime's injected clock — never a uuid4() or datetime.now() default, which would break replay.

RunStatus

Bases: str, Enum

Lifecycle state of a run; the only status vocabulary in the SDK.

Results

RunResult

Bases: BaseModel

Terminal (or paused) outcome of a run, identical across runtimes.

ToolResult

Bases: BaseModel

Normalised outcome of one AUB or MCP tool invocation.

Agent configuration

AgentConfig

Bases: BaseModel

Declarative configuration of one vertex in an agent graph.

AgentPersona

Bases: BaseModel

Static natural-language identity supplied to a compiled signature.

Planning

ExecutionPlan

Bases: BaseModel

Output of the Architect meta-agent: the graph plus its rationale.

TaskDecomposition

Bases: BaseModel

One unit of work the planner assigned to a named agent.

Routing

ModelCard

Bases: BaseModel

Externalised capability/cost/latency description of one model.

TaskSemantics

Bases: BaseModel

What the router knows about the task it must place.

RoutingContext

Bases: BaseModel

Everything a BaseRouter.select_model call is allowed to consider.

RoutingResult

Bases: BaseModel

The router's decision, always explainable.