agent/runner.ts

Source: sdks/typescript/packages/sdk/src/agent/runner.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.

Interface ToolCall

Tool call requested by a model: identifier, type function, name and arguments.

Fields:

Name	Type	Required	Description
id	string	yes	Identifier of the call.
type	"function"	yes	Type of the call, always function.
function	{ name: string; arguments: string }	yes	Function called: name and arguments as a JSON string.
input	unknown	no	Already parsed input; when set it wins over function.arguments.

Interface AgentMessage

Chat message of a turn in the OpenAI format: role, content, tool calls and tool call id.

Fields:

Name	Type	Required	Description
role	"system" | "user" | "assistant" | "tool"	yes	system, user, assistant or tool.
content	string | null	yes	Text of the message; null for an assistant message that only calls tools.
tool_calls	ToolCall[]	no	Tool calls requested by an assistant message.
tool_call_id	string	no	Id of the tool call this tool message answers.
name	string	no	Name of the tool, on a tool message.

Interface ModelResponse

Answer of a model call: the assistant message, the finish reason, tokens, cost and raw response.

Fields:

Name	Type	Required	Description
message	AgentMessage	yes	Status message (up to 2000 characters).
finishReason	string | null	yes	Finish reason of the model, for example stop, length or tool_calls.
tokens	number	no	Tokens used by the call, added to the turn budget.
cost	number	no	Cost of the call, added to the turn budget.
raw	unknown	no	Raw gateway response.

Interface ModelRequest

What the runner gives a model call: messages, tool declarations and step number.

Fields:

Name	Type	Required	Description
messages	AgentMessage[]	yes	Messages of the turn so far.
tools	Array<{ type: "function"; function: { name: string; description: string; parameters: Record<string, unknown> } }>	yes	Tools its external agents may invoke (names or patterns such as crm.*).
step	number	yes	Current step, free text (up to 500 characters).

Type alias ModelCaller

Replaces the gateway call (tests, custom routing).

Definition: (req: ModelRequest) => Promise<ModelResponse> \| ModelResponse.

Interface RunnerLimits

Limits of a turn of AgentRunner: model calls, tool calls, cost, tokens and duration.

Fields:

Name	Type	Required	Description
maxSteps	number	no	Model calls per turn (default 50).
maxToolCalls	number	no	Maximum tool calls per turn; reaching it stops with max_tool_calls.
maxCost	number	no	Cost limit in the currency unit reported by the gateway.
maxTokens	number	no	Maximum output tokens; when set, it is the output assumed for the worst case.
maxDurationMs	number	no	Maximum duration of the turn in milliseconds; going over it stops with timeout.

Type alias StopReason

Why a turn ended: completed, stopped, aborted, waiting_approval, max_steps, max_tool_calls, budget, timeout or no_progress.

Definition: \| "completed" \| "stopped" \| "aborted" \| "waiting_approval" \| "max_steps" \| "max_tool_calls" \| "budget" \| "timeout" \| "no_progress".

Interface RunnerStep

One model or tool step of a turn, as passed to onStep and reported to the run.

Fields:

Name	Type	Required	Description
index	number	yes	Position of the step in the turn, from 1.
type	"model" | "tool"	yes	model or tool.
name	string	yes	Tool name, or the model name for a model step.
input	unknown	no	Value that was refused.
output	unknown	no	Output of the operation (transcript, image references...).
error	string	no	Error message of a failed tool step.
status	"succeeded" | "failed" | "waiting_approval"	yes	succeeded, failed or waiting_approval.
kind	ToolKind	no	What a tool does, read by the continuation rules (exploration, verify_before_done).
tokens	number	no	Tokens used by a model step.
cost	number	no	Cost of a model step.
durationMs	number	yes	Duration of the step in milliseconds.
toolCalls	number	no	Model step: number of tool calls requested.
finishReason	string | null	no	Finish reason of a model step.

Interface TurnResult

Result of AgentRunner.runTurn.

Fields:

Name	Type	Required	Description
finalText	string	yes	Last text answer of the model.
messages	AgentMessage[]	yes	All messages of the turn, input, nudges and tool results included.
steps	RunnerStep[]	yes	Model and tool steps of the turn, in order.
stopReason	StopReason	yes	Why the turn ended.
stopDetail	string	no	Human readable cause for a non completed turn (limit, heartbeat reason).
nudges	Record<string	yes	Nudges sent in the turn, per rule code.
usage	{ tokens: number; cost: number; durationMs: number; modelCalls: number; toolCalls: number }	yes	Usage counters added to the budget consumption, for example input_tokens, output_tokens.
approval	Doc	no	Set when stopReason is waiting_approval.

Interface AgentRunnerOptions

Options of AgentRunner: model or callModel, tools, run ids, limits, rules, heartbeat, kill switch and reporting.

Fields:

Name	Type	Required	Description
client	EnterpriseAI	no	EnterpriseAI client used for the gateway, the tools, MCP and the run reports.
model	string	no	Gateway model or route alias.
effort	string	no	Reasoning effort sent as reasoning_effort.
callModel	ModelCaller	no	Replaces the gateway call (tests, custom routing).
tools	Tool<any	no	Tools its external agents may invoke (names or patterns such as crm.*).
remoteTools	RemoteToolSpec[]	no	Tools run server side by the Tool Gateway (POST /v1/tools/{name}/invoke).
mcpTools	McpToolSpec[]	no	Tools of registered MCP servers, called through the MCP gateway (tools/call).
agentId	string	no	Agent id sent as agent_id to the gateway and the Tool Gateway.
sessionId	string	no	Session id sent as session_id to the gateway.
runId	string	no	Run id: sent as run_id and, with a client, enables step and checkpoint reports.
taskId	string	no	Task id sent as task_id to the gateway.
dataClassification	string	no	Data classification sent as data_classification with model and remote tool calls.
limits	RunnerLimits	no	Step, tool call, cost, token and duration limits of a turn.
rules	ContinuationRule[]	no	Continuation rules (default defaultRules()). Pass [] to disable them.
deliveryRequired	boolean	no	The workflow needs a tool to run before the answer (delivery rule).
auditMode	boolean	no	Audit mode: exploration cap 8 instead of 4.
heartbeat	HeartbeatHandle	no	Heartbeat handle; beaten before every model call, stopRequested checked before every call.
shouldStop	() => Promise<boolean> | boolean	no	Extra kill switch, checked before every model and tool call.
signal	AbortSignal	no	AbortSignal passed to every call; an abort ends the turn with aborted.
locale	Locale	no	Language of the messages produced by the runner, en (default) or fr.
reportSteps	boolean	no	POST /v1/runs/{id}/steps for each call (default true when client and runId are set).
checkpoints	boolean	no	POST /v1/runs/{id}/checkpoints after tool steps and on stop (default true when client and runId are set).
onStep	(s: RunnerStep) => Promise<void> | void	no	Called with each model and tool step.
onError	(err: unknown) => void	no	Reporting errors (steps, checkpoints) never fail the turn; they land here.

Class AgentRunner

Model then tools, repeated until the final answer, then the Navin continuation rules.

Attributes:

Name	Type	Required	Description
options	AgentRunnerOptions	yes	Options given to the constructor.

Constructor AgentRunner

new AgentRunner(options: AgentRunnerOptions)

Indexes the local, remote and MCP tools and takes defaultRules() when no rules are given; throws invalid_request without a client or a callModel.

Name	Type	Default	Required	Description
options	AgentRunnerOptions		yes	Per call options (idempotency key, traceparent, headers, abort signal).

AgentRunner.runTurn

async runTurn(input: AgentMessage[]): Promise<TurnResult>

Runs one user turn until the final answer or a stop.

Name	Type	Default	Required	Description
input	AgentMessage[]		yes	Messages of the conversation so far; the last user message is read by the go-ahead rule.

Returns: Promise<TurnResult>. Final text, messages, steps, stop reason, nudges sent and usage of the turn.