Agent SDK · Running agents

Run.

Run a prompt to completion and get the final output.

`runner.run(agent, input, options?)`

Runs an agent turn and returns the complete result. Internally streams and collects all events.

TypeScript

import { Runner } from '@maincode-ai/matilda-agent-sdk';

const runner = new Runner();

const result = await runner.run(
  { name: 'helper', instructions: 'Be concise.' },
  'What is the capital of Australia?',
  {
    conversationId: 'conv-123',
    responseMode: 'instant',
    callbacks: {
      onToken: (delta) => process.stdout.write(delta),
      onDone: () => console.log('\n[done]'),
    },
  },
);

console.log(result.finalOutput);
console.log(result.usage);

`AgentRunOptions`

Extends RequestOptions. All fields optional.

Field	type	description
signal	AbortSignal	Abort the run.
conversationId	string	Associates this turn with a conversation thread. Auto-generated when omitted.
fileIds	string[]	File IDs to attach (from files.upload()).
clientTools	ClientTool[]	Client tools to advertise for this turn.
context	string	Override the agent's context.
responseMode	ChatResponseMode	Override the response mode.
responseSchema	string	Raw JSON Schema (as a string) to grammar-constrain the response to. Prefer runner.runObject / runner.streamObject, which convert a zod schema for you.
stallTimeoutMs	number	SSE stall watchdog timeout in ms. Defaults to 45_000. Pass 0 to disable.
metadata	Record<string, unknown>	Custom data available to dynamic instructions.
toolHandlers	ToolHandlers	Handlers for client tools.
maxToolRoundtrips	number	Maximum tool roundtrip cycles before stopping. Defaults to 25.
maxRetries	number	Maximum retries on retryable errors (5xx, 429, 408, network). Defaults to 0.
throwOnStreamError	boolean	Throw MatildaAgentStreamError if the stream emits an error event. Defaults to true.
callbacks	AgentCallbacks	Callback hooks for events (see below).
core	MatildaCore	Override the runner's core for this run.
fingerprint	string	Device fingerprint for rate limiting.
accessToken	string	Override the core-level access token for this request.

Note

Prefer runner.runObject / runner.streamObject over responseSchema — they convert a zod schema for you; see Structured output. Client tool handlers are wired up in Client tools.

`AgentCallbacks`

Simple callback hooks that fire as events arrive. An alternative to manually iterating stream().

TypeScript

const result = await runner.run(agent, input, {
  callbacks: {
    onToken: (delta) => process.stdout.write(delta),
    onToolCall: (name, args) => console.log(`Tool: ${name}`),
    onToolResult: (name, result, isError) => console.log(`Result: ${result}`),
    onUsage: (usage) => console.log(`Tokens: ${usage.output_tokens}`),
    onError: (code, message) => console.error(`Error: ${code}`),
    onRetry: (attempt, error, delayMs) => console.log(`Retry ${attempt} in ${delayMs}ms`),
    onDone: () => console.log('Done'),
  },
});

Field	type	description
onEvent	(event: AgentRunEvent) => void	Every event — catch-all, fires before the typed hooks below. Useful for telemetry, UI plumbing, or event logging.
onToken	(delta: string) => void	A text chunk arrives.
onToolCall	(name: string, args: Record<string, unknown>) => void	The agent calls a client tool.
onToolResult	(name: string, result: string, isError: boolean) => void	A client tool handler returns.
onUsage	(usage: UsageEvent) => void	Token usage data arrives.
onError	(code: ChatErrorCode, message: string) => void	A stream error occurs.
onRetry	(attempt: number, error: { code: string; message: string }, delayMs: number) => void	A retryable error triggers a retry.
onDone	() => void	The stream finishes. Fires per-turn in multi-turn tool loops.

`AgentRunResult`

Field	type	description
agentName	string	The agent's name.
finalOutput	string	The full assistant response text. Accumulated from message.delta events.
events	AgentRunEvent[]	Every event emitted during the run.
streamId	string \| undefined	Durable stream ID (from stream.started event).
lastEventId	string \| undefined	Last stream event ID (for resume).
usage	UsageEvent \| undefined	Token usage. Accumulated across multi-roundtrip runs.
errors	Array<{ code: ChatErrorCode; message: string }>	Any errors emitted during the run.
truncatedReason	string \| undefined	Why the response was truncated (e.g. 'max_tokens', 'max_tool_roundtrips').
safetyReplace	{ message: string; categories: string[] } \| undefined	Set when the backend replaced the answer for safety. finalOutput holds the replacement text.

`throwOnStreamError: false`

By default, run() throws MatildaAgentStreamError if the stream emits an error event. Pass throwOnStreamError: false to suppress the throw and inspect errors on the returned result instead:

TypeScript

const result = await runner.run(agent, input, { throwOnStreamError: false });

if (result.errors.length > 0) {
  for (const err of result.errors) {
    console.log(`${err.code}: ${err.message}`);
  }
}
console.log('Partial output:', result.finalOutput || '(none)');