Agents

Role-specific agent constructors. Each returns an AgentSpec that define_runtime(...) composes into a RuntimeSpec.

define_coordinator

define_coordinator(name: 'str', *, model: 'ModelInput', prompt: 'str | LayeredPrompt', routes: 'Iterable[str]' = (), tools: 'Iterable[ToolSpec]' = (), stateful: 'bool | None' = None, max_turns: 'int | None' = None, approval: 'ApprovalPolicyPatch | Mapping[str, Any] | None' = None, tool_approvals: 'Mapping[str, Any] | None' = None, toolkits: 'Iterable[str] | None' = None) -> 'AgentSpec'

Parameter	Type	Default
name	str	required
model	ModelInput	required
prompt	str | LayeredPrompt	required
routes	Iterable[str]	()
tools	Iterable[ToolSpec]	()
stateful	bool | None	None
max_turns	int | None	None
approval	ApprovalPolicyPatch | Mapping[str, Any] | None	None
tool_approvals	Mapping[str, Any] | None	None
toolkits	Iterable[str] | None	None

Returns: AgentSpec

Define a coordinator agent spec.

The coordinator is the user-facing entrypoint agent. It owns the conversation thread and hands work off to the agents named in routes.

Args: name: Unique agent name within the runtime spec. model: Model selection: a model id string, a ModelSpec, or a mapping with id and optional provider. prompt: System prompt as a string or a LayeredPrompt. A LayeredPrompt also contributes its deterministic prompt cache key. routes: Names of agents this coordinator can hand off to. At least one route is required; every route must name an agent registered in the same runtime spec. tools: ToolSpec values bound directly to this agent. stateful: Whether the agent keeps thread state across turns. Defaults to True for coordinators when None. max_turns: Maximum orchestration turns for this agent, or None for the runtime default. approval: Agent-level approval override for the plans and tools channels as an ApprovalPolicyPatch or mapping. The "default" sentinel for a channel means "do not override the runtime default for this channel". tool_approvals: Per-tool approval rules keyed by tool name. Each rule is "never", "always", or {"kind": "dynamic", "value": id}. toolkits: Built-in toolkit ids to attach. Defaults to ["agents"], which exposes the route hand-off tools.

Returns: A validated AgentSpec with role="coordinator".

Raises: ValueError: If routes is empty, or a tool_approvals key or approval rule is invalid. TypeError: If prompt is neither a string nor a LayeredPrompt.

define_planner

define_planner(name: 'str', *, model: 'ModelInput', prompt: 'str | LayeredPrompt', plan: 'PlanSpec | Mapping[str, Any]', tools: 'Iterable[ToolSpec]' = (), stateful: 'bool | None' = None, max_turns: 'int | None' = None, approval: 'ApprovalPolicyPatch | Mapping[str, Any] | None' = None, tool_approvals: 'Mapping[str, Any] | None' = None, toolkits: 'Iterable[str] | None' = None) -> 'AgentSpec'

Parameter	Type	Default
name	str	required
model	ModelInput	required
prompt	str | LayeredPrompt	required
plan	PlanSpec | Mapping[str, Any]	required
tools	Iterable[ToolSpec]	()
stateful	bool | None	None
max_turns	int | None	None
approval	ApprovalPolicyPatch | Mapping[str, Any] | None	None
tool_approvals	Mapping[str, Any] | None	None
toolkits	Iterable[str] | None	None

Returns: AgentSpec

Define a planner agent spec.

A planner authors plan instances for the supplied plan schema. The plan is auto-attached to the runtime spec when not declared explicitly.

Args: name: Unique agent name within the runtime spec. model: Model selection: a model id string, a ModelSpec, or a mapping with id and optional provider. prompt: System prompt as a string or a LayeredPrompt. plan: PlanSpec (or mapping validated as one) describing the action schema this planner authors. tools: ToolSpec values bound directly to this agent. stateful: Whether the agent keeps thread state across turns. Defaults to True for planners when None. max_turns: Maximum orchestration turns for this agent, or None for the runtime default. approval: Agent-level approval override for the plans and tools channels as an ApprovalPolicyPatch or mapping. tool_approvals: Per-tool approval rules keyed by tool name. toolkits: Built-in toolkit ids to attach. Defaults to ["plans"].

Returns: A validated AgentSpec with role="planner".

Raises: ValueError: If a tool_approvals key or approval rule is invalid. TypeError: If prompt is neither a string nor a LayeredPrompt.

define_executor

define_executor(name: 'str', *, model: 'ModelInput', prompt: 'str | LayeredPrompt', plan: 'PlanSpec | Mapping[str, Any]', tools: 'Iterable[ToolSpec]' = (), stateful: 'bool | None' = None, max_turns: 'int | None' = None, approval: 'ApprovalPolicyPatch | Mapping[str, Any] | None' = None, tool_approvals: 'Mapping[str, Any] | None' = None, toolkits: 'Iterable[str] | None' = None) -> 'AgentSpec'

Parameter	Type	Default
name	str	required
model	ModelInput	required
prompt	str | LayeredPrompt	required
plan	PlanSpec | Mapping[str, Any]	required
tools	Iterable[ToolSpec]	()
stateful	bool | None	None
max_turns	int | None	None
approval	ApprovalPolicyPatch | Mapping[str, Any] | None	None
tool_approvals	Mapping[str, Any] | None	None
toolkits	Iterable[str] | None	None

Returns: AgentSpec

Define an executor agent spec.

An executor carries out approved plan instances of the supplied plan schema, emitting business actions for host dispatch.

Args: name: Unique agent name within the runtime spec. model: Model selection: a model id string, a ModelSpec, or a mapping with id and optional provider. prompt: System prompt as a string or a LayeredPrompt. plan: PlanSpec (or mapping validated as one) describing the action schema this executor executes. tools: ToolSpec values bound directly to this agent. stateful: Whether the agent keeps thread state across turns. Defaults to False for executors when None. max_turns: Maximum orchestration turns for this agent, or None for the runtime default. approval: Agent-level approval override for the plans and tools channels as an ApprovalPolicyPatch or mapping. tool_approvals: Per-tool approval rules keyed by tool name. toolkits: Built-in toolkit ids to attach. Defaults to ["plans", "references"].

Returns: A validated AgentSpec with role="executor".

Raises: ValueError: If a tool_approvals key or approval rule is invalid. TypeError: If prompt is neither a string nor a LayeredPrompt.

define_specialist

define_specialist(name: 'str', *, model: 'ModelInput', prompt: 'str | LayeredPrompt', tools: 'Iterable[ToolSpec]' = (), stateful: 'bool | None' = None, max_turns: 'int | None' = None, approval: 'ApprovalPolicyPatch | Mapping[str, Any] | None' = None, tool_approvals: 'Mapping[str, Any] | None' = None, toolkits: 'Iterable[str] | None' = None) -> 'AgentSpec'

Parameter	Type	Default
name	str	required
model	ModelInput	required
prompt	str | LayeredPrompt	required
tools	Iterable[ToolSpec]	()
stateful	bool | None	None
max_turns	int | None	None
approval	ApprovalPolicyPatch | Mapping[str, Any] | None	None
tool_approvals	Mapping[str, Any] | None	None
toolkits	Iterable[str] | None	None

Returns: AgentSpec

Define a specialist agent spec.

A specialist is a focused single-purpose agent without routes or a plan. It can be routed to by a coordinator or dispatched directly via runtime.run_specialist(...).

Args: name: Unique agent name within the runtime spec. model: Model selection: a model id string, a ModelSpec, or a mapping with id and optional provider. prompt: System prompt as a string or a LayeredPrompt. tools: ToolSpec values bound directly to this agent. stateful: Whether the agent keeps thread state across turns. Defaults to False for specialists when None. max_turns: Maximum orchestration turns for this agent, or None for the runtime default. approval: Agent-level approval override for the plans and tools channels as an ApprovalPolicyPatch or mapping. tool_approvals: Per-tool approval rules keyed by tool name. toolkits: Built-in toolkit ids to attach. Defaults to none.

Returns: A validated AgentSpec with role="specialist".

Raises: ValueError: If a tool_approvals key or approval rule is invalid. TypeError: If prompt is neither a string nor a LayeredPrompt.