Agent
An agent made by agent(): its name and config, ready to run.
Building one does no I/O; run() or stream() starts a run.
Properties
nameNamerequiredThe agent's name as given to agent(): lowercase letters, digits and underscores, up to 64 characters.
Methods
run
Run one input to a terminal result. Needs no server. The run spans its input turn and every later turn of the same request: when the agent starts background subagents or team members, run() waits until each has reported and the lead has reacted (a wake turn), so it returns later and runs more turns; members an operator or an earlier run started never extend it.
run(input: Input, options?: {
thread?: ThreadId | Thread;
store?: Store;
deps?: Deps;
budget?: Budget;
principal?: Principal;
ceiling?: Partial<Policy.permissions>;
signal?: AbortSignal;
}): Promise<RunResult<Output>>inputInputrequiredText or ordered input parts.
threadThreadId | ThreadThe thread to continue: a Thread handle continues its branch; a thread id continues its main branch in store (a ConfigError invalid_config when the store has no such thread). Omitted: a new thread.
storeStoreWhere the thread's log lives. Omitted: the handle's store when thread is a Thread handle, else sqlite(".threads") in the working directory. See Store.
depsDepsHost-only dependencies your tools and hooks read as RunContext.deps; never serialized or logged. Required when the agent's Deps type is not null; omitted, tools see null (None in Python).
budgetBudgetRun budget, recorded on the user_input; it covers this thread and every subagent it starts. Omitted: only the agent's own budget option applies.
principalPrincipalThe verified sender of this input, recorded on the user_input. Omitted: the local operator (issuer "api", tenant "local", subject "operator").
ceilingPartial<Policy.permissions>The principal and host ceiling. Every permission decision of this run, of its subagents and of every handoff target it starts is also decided under it, in the ceiling's own mode; the stricter decision wins and a tie reports the thread's own. A handoff target is capped by the ceilings of the run that handed off, never by the source agent's own policy. Omitted: no ceiling, so only the agent's own permissions apply.
signalAbortSignalTypeScript only. Local cancellation: aborting it stops the run in this process, and tools see it as RunContext.signal. Python uses task cancellation instead. Omitted: the run stops only through the durable Thread.cancel().
Throws ConfigError for a definition that can't run.
runSync / run_sync
Python only. Blocking run for scripts: runs the agent on a new event loop in the calling thread, and the run's connections are opened and closed within the call. Inside a running event loop (async code, a notebook) it raises ConfigError invalid_config: use await run() there. On Ctrl-C the run is cancelled and cleaned up, then KeyboardInterrupt is raised; if a tool ignores cancellation, a later run closes the turn through recovery once the lease expires. There is no blocking stream.
def run_sync(
input: Input,
*,
thread: Thread | None = None,
store: Store | None = None,
deps: Deps | None = None,
budget: Budget | None = None,
principal: Principal | None = None,
ceiling: Policy.permissions | None = None,
) -> RunResult[Output]inputInputrequiredText or ordered input parts.
threadThreadThe thread to continue: a Thread handle continues its branch. Omitted: a new thread. See Thread.
storeStoreWhere the thread's log lives. Omitted: the handle's store when thread is a Thread handle, else sqlite(".threads") in the working directory. See Store.
depsDepsHost-only dependencies your tools and hooks read as RunContext.deps; never serialized or logged. Required when the agent's Deps type is not null; omitted, tools see None.
budgetBudgetRun budget, recorded on the user_input; it covers this thread and every subagent it starts. Omitted: only the agent's own budget option applies.
principalPrincipalThe verified sender of this input, recorded on the user_input. Omitted: the local operator (issuer "api", tenant "local", subject "operator").
ceilingPartial<Policy.permissions>The principal and host ceiling, exactly as for run(). Omitted: no ceiling, so only the agent's own permissions apply.
Throws ConfigError for a definition that can't run.
stream
Same run, as a subscription to its log. Not a second loop.
stream(input: Input, options?: {
thread?: ThreadId | Thread;
store?: Store;
deps?: Deps;
budget?: Budget;
principal?: Principal;
ceiling?: Partial<Policy.permissions>;
signal?: AbortSignal;
}): RunStream<Output>inputInputrequiredText or ordered input parts.
threadThreadId | ThreadThe thread to continue: a Thread handle continues its branch; a thread id continues its main branch in store (a ConfigError invalid_config when the store has no such thread). Omitted: a new thread.
storeStoreWhere the thread's log lives. Omitted: the handle's store when thread is a Thread handle, else sqlite(".threads") in the working directory. See Store.
depsDepsHost-only dependencies your tools and hooks read as RunContext.deps; never serialized or logged. Required when the agent's Deps type is not null; omitted, tools see null (None in Python).
budgetBudgetRun budget, recorded on the user_input; it covers this thread and every subagent it starts. Omitted: only the agent's own budget option applies.
principalPrincipalThe verified sender of this input, recorded on the user_input. Omitted: the local operator (issuer "api", tenant "local", subject "operator").
ceilingPartial<Policy.permissions>The principal and host ceiling. Every permission decision of this run, of its subagents and of every handoff target it starts is also decided under it, in the ceiling's own mode; the stricter decision wins and a tie reports the thread's own. A handoff target is capped by the ceilings of the run that handed off, never by the source agent's own policy. Omitted: no ceiling, so only the agent's own permissions apply.
signalAbortSignalTypeScript only. Local cancellation: aborting it stops the run in this process, and tools see it as RunContext.signal. Python uses task cancellation instead. Omitted: the run stops only through the durable Thread.cancel().
Throws ConfigError for a definition that can't run.
check
Validate the definition and resolve setup (secrets, MCP handshakes, capabilities) without starting a run. Returns every setup failure as an error value (it never throws them); a failed check can be retried on the same agent after fixing the environment. Connections it opens are closed before it returns.
check(): Promise<Result<void>>Returns an error value with one of these codes: invalid_config, missing_secret, unknown_preset, duplicate_name, capability_missing, mcp_unreachable, budget_unenforceable, permission_rule_invalid, hosted_tool_unsupported, egress_policy_unsupported, transport_fence_unsupported, handoff_in_team.