agent.ts

Source: sdks/typescript/packages/sdk/src/agent.ts. Back to the TypeScript SDK reference index.

note

This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.

Type alias PlanResult

What plan returns: a tool call (tool, input) or the final answer (final), with optional tokens and cost.

Definition: { tool: string; input: unknown; tokens?: number; cost?: number } \| { final: unknown; tokens?: number; cost?: number }.

Interface VerifyResult

Result of verify for one tool step: ok and an optional feedback.

Fields:

Name	Type	Required	Description
ok	boolean	yes	Whether the exercise succeeded.
feedback	string	no	Optional feedback kept in the history for the next plan call.

Interface LoopStep

One tool step of runAgentLoop: the tool, its input, its output or error and the verification result.

Fields:

Name	Type	Required	Description
step	number	yes	Current step, free text (up to 500 characters).
tool	string	yes	Name of the tool called.
input	unknown	yes	Value that was refused.
output	unknown	no	Output of the operation (transcript, image references...).
error	string	no	Error message when the tool call failed.
verified	boolean	yes	True when the call succeeded and verify accepted it.
feedback	string	no	Feedback of verify, or the error message when the tool failed.

Interface LoopBudget

Limits of runAgentLoop on tokens, cost and duration.

Fields:

Name	Type	Required	Description
maxTokens	number	no	Maximum output tokens; when set, it is the output assumed for the worst case.
maxCost	number	no	Cost limit in the currency unit used by plan results.
maxDurationMs	number	no	Maximum duration of the loop in milliseconds.

Interface AgentLoopOptions

Options of runAgentLoop: the tools, the plan and verify callbacks, the step limit, the budget and the kill switch.

Fields:

Name	Type	Required	Description
tools	Tool<any	yes	Tools its external agents may invoke (names or patterns such as crm.*).
plan	(history: LoopStep[], step: number) => Promise<PlanResult> | PlanResult	yes	Plan: chooses the next tool call or returns the final answer.
verify	(s: LoopStep) => Promise<VerifyResult> | VerifyResult	no	Verify: checks each tool result (default accepts every successful call).
maxSteps	number	no	Maximum number of steps (default 10); reaching it throws agent_max_steps.
budget	LoopBudget	no	Token, cost and duration limits merged into the runner limits; going over them throws agent_budget.
killSwitch	() => Promise<boolean> | boolean	no	Returns true when the agent must stop (kill switch). Checked before every model and tool call.
onStep	(s: LoopStep) => Promise<void> | void	no	Called after each tool step, for example to POST a heartbeat.
signal	AbortSignal	no	AbortSignal that cancels the loop; an abort throws agent_aborted.
locale	Locale	no	Language of the error messages, en (default) or fr.
agentId	string	no	Agent id passed to the runner and named in the agent_killed error message.

Interface AgentLoopResult

Result of runAgentLoop: the final answer, the tool steps and the usage (tokens, cost, duration in milliseconds).

Fields:

Name	Type	Required	Description
final	unknown	yes	True when this is the last step of the run. Default false.
steps	LoopStep[]	yes	Every tool step run by the loop, in order.
usage	{ tokens: number; cost: number; durationMs: number }	yes	Usage counters added to the budget consumption, for example input_tokens, output_tokens.

Functions

runAgentLoop

async runAgentLoop(o: AgentLoopOptions): Promise<AgentLoopResult>

plan / act / verify loop with a step limit, a budget and a kill switch. Delegates to AgentRunner: plan plays the model, continuation rules are off.

Name	Type	Default	Required	Description
o	AgentLoopOptions		yes	Per call options (idempotency key, traceparent, headers).

Returns: Promise<AgentLoopResult>. Final answer, tool steps and usage; throws AgentLoopError on step limit, budget, abort or kill switch.

Raises: AgentLoopError.