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. Python: an agent with app tools needs deps on every run; pass deps=None when its tools take none.
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; in TypeScript a thread id also works (Python takes a handle only). 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.
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; in TypeScript a thread id also works (Python takes a handle only). 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
TypeScript only. Validate the definition and resolve setup (secrets, MCP handshakes, capabilities) without starting a run.
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.