run(...)

run(...) is the main execution entrypoint.

Signatures

run(agent, input, { stream: true, ...options }): Promise<StreamedRunResult<TContext>>

run(agent, input, options?): Promise<RunResult<TContext>>

Where:

• agent is the starting Agent
• input is either string or AgentInputItem[]
• stream defaults to false

Non-streaming Result

type RunResult<TContext> = {
  finalOutput: string;
  history: AgentInputItem[];
  lastAgent: Agent<TContext>;
}

Streaming Result

When stream: true, run(...) returns StreamedRunResult<TContext>.

The important API is:

result.toStream(): AsyncIterable<RunStreamEvent<TContext>>

The stream can be consumed only once.

StreamedRunResult also exposes:

• history
• lastAgent

For UI-oriented streaming that keeps text deltas live while collecting final output, history, last agent, and paired tool calls, see Run Output Events.

Options

The current shared option surface is:

{
  context?: TContext;
  maxTurns?: number;
  logger?: RunLogger;
  policies?: PolicyConfiguration<TContext>;
  record?: RunRecordOptions<TContext>;
}

Important Operational Notes

Default provider

run(...) uses the configured default provider.

If no default provider has been set, runtime execution fails.

Model requirement

The active agent must have model configured.

Default max turns

If omitted, maxTurns defaults to 10.

Input normalization

If input is a string, it is normalized to a single user message item.

Tool and handoff order

Within each model response, ordinary tools are processed sequentially in their original order, then only the first requested handoff is evaluated. All calls belong to the agent that made the model request. Handoff recognition uses the tools exposed for that turn, not a function-name prefix.

The first requested handoff is selected before authorization: if it is denied, requires approval, or fails, no later handoff from the same response is tried. Later handoffs are ignored and produce no history items, item stream events, policy decisions, or suspended proposals.

A blocking tool error prevents the handoff. Non-allow tool outcomes with resultMode: "tool_result" let processing continue. The handoff policy sees context changes made by preceding tools; their effects are not rolled back if the handoff is blocked. After an allowed handoff, the next model request uses the target agent.

Runtime logging

If logger is configured, run(...) emits structured runtime events during execution.

See Logging.

Example

const result = await run(agent, "Summarize report Q1.", {
  context: { actor: { groups: ["finance"] } },
  policies: { toolPolicy },
  record: {
    includePromptText: true,
    sink: (record) => records.push(record),
  },
});

console.log(result.finalOutput);