运行智能体

智能体本身不会执行任何操作——您需要使用 Runner 类或 run() 工具来运行它们。

在您已经阅读智能体，并希望执行轮次、流式传输事件或管理对话状态后，再阅读本页。如果您仍在决定应如何定义智能体，请先从智能体开始。

import { Agent, run } from '@openai/agents';

const agent = new Agent({
  name: 'Assistant',
  instructions: 'You are a helpful assistant',
});

const result = await run(
  agent,
  'Write a haiku about recursion in programming.',
);
console.log(result.finalOutput);

// Code within the code,
// Functions calling themselves,
// Infinite loop's dance.

当您不需要自定义 Runner 时，也可以使用 run() 工具，它会运行一个单例默认 Runner 实例。

或者，您也可以创建自己的 Runner 实例：

import { Agent, Runner } from '@openai/agents';

const agent = new Agent({
  name: 'Assistant',
  instructions: 'You are a helpful assistant',
});

// You can pass custom configuration to the runner
const runner = new Runner();

const result = await runner.run(
  agent,
  'Write a haiku about recursion in programming.',
);
console.log(result.finalOutput);

// Code within the code,
// Functions calling themselves,
// Infinite loop's dance.

运行智能体后，您会收到一个执行结果对象，其中包含最终输出和本次运行的完整历史。

Runner 生命周期与配置

智能体循环

当您使用 Runner 中的 run 方法时，会传入一个起始智能体和输入。输入可以是字符串（会被视为用户消息），也可以是一组输入项，即 OpenAI Responses API 中的项。

Runner 随后执行一个循环：

使用当前输入调用当前智能体的模型。
检查 LLM 响应。
- 最终输出 → 返回。
- 交接 → 切换到新的智能体，保留累积的对话历史，回到第 1 步。
- 工具调用 → 执行工具，将结果追加到对话中，回到第 1 步。
一旦达到 maxTurns，就抛出 MaxTurnsExceededError，除非 maxTurns 为 null。

Runner 生命周期

在应用启动时创建一个 Runner，并在各个请求之间复用它。该实例会存储全局配置，例如模型提供商和追踪选项。只有在需要完全不同的设置时，才创建另一个 Runner。对于简单脚本，也可以调用 run()，它会在内部使用默认 Runner。

运行参数

run() 方法的输入包括用于开始运行的初始智能体、运行输入以及一组选项。

输入可以是字符串（会被视为用户消息），也可以是一组输入项，或者在构建人机协作智能体时使用 RunState 对象。

其他选项如下：

选项	默认值	描述
`stream`	`false`	如果为 `true`，调用会返回 `StreamedRunResult`，并在事件从模型抵达时发出事件。
`context`	–	转发给每个工具 / 护栏 / 交接的上下文对象。更多信息请参阅上下文管理。
`maxTurns`	`10`	安全限制——达到时会抛出 `MaxTurnsExceededError`。传入 `null` 可禁用该限制。
`signal`	–	用于取消的 `AbortSignal`。
`session`	–	会话持久化实现。请参阅会话。
`sessionInputCallback`	–	会话历史与新输入的自定义合并逻辑；在模型调用前运行。请参阅会话。
`callModelInputFilter`	–	在调用模型前编辑模型输入（items + 可选 instructions）的钩子。请参阅模型调用输入过滤器。
`toolErrorFormatter`	–	用于自定义返回给模型的工具批准拒绝消息的钩子。请参阅工具错误格式化器。
`reasoningItemIdPolicy`	–	控制在先前运行项重新转换为模型输入时，是保留还是省略推理项 `id`。请参阅推理项 ID 策略。
`tracing`	–	每次运行的追踪配置覆盖（例如导出 API 密钥）。
`sandbox`	–	用于 `SandboxAgent` 运行的沙盒客户端、实时会话、会话状态、快照、manifest 覆盖或并发限制。请参阅概念。
`toolExecution`	–	本地工具调用的 SDK 端执行设置。使用 `toolExecution.maxFunctionToolConcurrency` 限制同时运行的函数工具数量。
`errorHandlers`	–	受支持运行时错误（当前为 `maxTurns`）的处理器。请参阅错误处理器。
`conversationId`	–	复用服务器端对话（仅限 OpenAI Responses API + Conversations API）。
`previousResponseId`	–	从上一次 Responses API 调用继续，而不创建对话（仅限 OpenAI Responses API）。

流式传输

流式传输允许您在 LLM 运行时额外接收流式事件。流启动后，StreamedRunResult 将包含本次运行的完整信息，包括生成的所有新输出。您可以使用 for await 循环遍历流式事件。更多信息请参阅流式传输。

运行配置

如果您要创建自己的 Runner 实例，可以传入 RunConfig 对象来配置 Runner。

字段	类型	用途
`model`	`string \| Model`	为运行中的所有智能体强制使用特定模型。
`modelProvider`	`ModelProvider`	解析模型名称——默认为 OpenAI 提供商。
`modelSettings`	`ModelSettings`	覆盖每个智能体设置的全局调优参数。详情请参阅模型，包括选择启用的重试配置。
`handoffInputFilter`	`HandoffInputFilter`	执行交接时修改输入项（如果交接本身尚未定义）。
`inputGuardrails`	`InputGuardrail[]`	应用于初始用户输入的护栏。
`outputGuardrails`	`OutputGuardrail[]`	应用于最终输出的护栏。
`tracingDisabled`	`boolean`	完全禁用 OpenAI 追踪。
`traceIncludeSensitiveData`	`boolean`	在仍发出 span 的同时，从追踪中排除 LLM/工具输入和输出。
`workflowName`	`string`	显示在 Traces 仪表板中——有助于对相关运行进行分组。
`traceId` / `groupId`	`string`	手动指定追踪或组 ID，而不是让 SDK 生成。
`traceMetadata`	`Record<string, string>`	附加到每个 span 的任意元数据。
`tracing`	`TracingConfig`	每次运行的追踪配置覆盖（例如导出 API 密钥）。
`sessionInputCallback`	`SessionInputCallback`	此 Runner 上所有运行的默认历史合并策略。
`callModelInputFilter`	`CallModelInputFilter`	在每次模型调用前编辑模型输入的全局钩子。
`toolErrorFormatter`	`ToolErrorFormatter`	用于自定义返回给模型的工具批准拒绝消息的全局钩子。
`reasoningItemIdPolicy`	`ReasoningItemIdPolicy`	将生成的项重放进后续模型调用时，保留或省略推理项 `id` 的默认策略。
`sandbox`	`SandboxRunConfig`	用于 `SandboxAgent` 运行的默认沙盒运行时配置。
`toolExecution`	`ToolExecutionConfig`	本地工具调用的默认 SDK 端执行设置。`maxFunctionToolConcurrency` 限制每个轮次的本地函数工具并发数；未设置或为 `null` 时，会启动该轮次中发出的所有函数工具调用。

toolExecution.maxFunctionToolConcurrency 必须是大于或等于 1 的整数。此设置仅限制本地函数工具在 SDK 端的执行。它不会改变提供商端的 modelSettings.parallelToolCalls。

状态与对话管理

记忆策略选择

有四种将状态带入下一轮的常见方式：

策略	状态存储位置	适用场景	下一轮传入内容
`result.history`	您的应用内存	小型聊天循环、完全手动控制、任何提供商	`result.history`
`session`	您的存储 + SDK	持久聊天状态、可恢复运行、自定义存储	同一个 `session` 实例（或由存储支持的实例）
`conversationId`	OpenAI Conversations API	跨 worker/服务共享的服务器端状态	同一个 `conversationId`，外加仅新的用户轮次
`previousResponseId`	仅 OpenAI Responses API	无需创建对话的最简单服务器管理延续方式	`result.lastResponseId`，外加仅新的用户轮次

result.history 和 session 由客户端管理。conversationId 和 previousResponseId 由 OpenAI 管理，并且仅在您使用 OpenAI Responses API 时适用。在大多数应用中，每个对话选择一种持久化策略即可。除非您有意协调这两层，否则混合使用客户端管理的历史与服务器管理的状态可能会导致上下文重复。

沙盒智能体会增加另一层状态：实时沙盒工作区。对话历史请使用常规 SDK session、conversationId 或 previousResponseId；沙盒文件系统状态请使用 sandbox.session、sandbox.sessionState、RunState 或快照。有关工作区生命周期，请参阅概念。

对话 / 聊天线程

对 runner.run()（或 run() 工具）的每次调用都表示应用级对话中的一个轮次。您可以自行决定向最终用户展示多少 RunResult 内容——有时只展示 finalOutput，有时展示每个生成项。

import { Agent, run } from '@openai/agents';
import type { AgentInputItem } from '@openai/agents';

let thread: AgentInputItem[] = [];

const agent = new Agent({
  name: 'Assistant',
});

async function userSays(text: string) {
  const result = await run(
    agent,
    thread.concat({ role: 'user', content: text }),
  );

  thread = result.history; // Carry over history + newly generated items
  return result.finalOutput;
}

await userSays('What city is the Golden Gate Bridge in?');
// -> "San Francisco"

await userSays('What state is it in?');
// -> "California"

交互版本请参阅聊天示例。

服务器管理的对话

您可以让 OpenAI Responses API 为您持久化对话历史，而不是在每个轮次都发送完整的本地对话历史。当您需要协调长对话或多个服务时，这会很有用。对于下面任一服务器管理方式，每次请求只需传入本轮的新输入。API 会为您复用之前的状态。详情请参阅对话状态指南。

OpenAI 提供两种复用服务器端状态的方式：

1. 用于整个对话的 `conversationId`

您可以使用 Conversations API 创建一次对话，然后在每个轮次复用其 ID。SDK 会自动仅包含新生成的项。

import { Agent, run } from '@openai/agents';
import { OpenAI } from 'openai';

const agent = new Agent({
  name: 'Assistant',
  instructions: 'Reply very concisely.',
});

async function main() {
  // Create a server-managed conversation:
  const client = new OpenAI();
  const { id: conversationId } = await client.conversations.create({});

  const first = await run(agent, 'What city is the Golden Gate Bridge in?', {
    conversationId,
  });
  console.log(first.finalOutput);
  // -> "San Francisco"

  const second = await run(agent, 'What state is it in?', { conversationId });
  console.log(second.finalOutput);
  // -> "California"
}

main().catch(console.error);

2. 从上一轮继续的 `previousResponseId`

如果无论如何都只想从 Responses API 开始，可以使用上一条响应返回的 ID 串联每个请求。这样无需创建完整的对话资源，也能在多个轮次间保持上下文。

import { Agent, run } from '@openai/agents';

const agent = new Agent({
  name: 'Assistant',
  instructions: 'Reply very concisely.',
});

async function main() {
  const first = await run(agent, 'What city is the Golden Gate Bridge in?');
  console.log(first.finalOutput);
  // -> "San Francisco"

  const previousResponseId = first.lastResponseId;
  const second = await run(agent, 'What state is it in?', {
    previousResponseId,
  });
  console.log(second.finalOutput);
  // -> "California"
}

main().catch(console.error);

conversationId 和 previousResponseId 互斥。当您需要一个可跨系统共享的具名对话资源时使用 conversationId；当您只需要从一次响应到下一次响应之间最轻量的 SDK 级延续机制时使用 previousResponseId。

钩子与自定义

模型调用输入过滤器

使用 callModelInputFilter 在模型被调用的前一刻编辑模型输入。该钩子会接收当前智能体、上下文以及合并后的输入项（存在会话历史时会包含它）。返回更新后的 input 数组和可选的 instructions，用于遮盖敏感数据、丢弃旧消息或注入额外的系统指导。

可以在每次运行中通过 runner.run(..., { callModelInputFilter }) 设置，也可以在 Runner 配置中作为默认值设置（RunConfig 中的 callModelInputFilter）。

返回值必须是 ModelInputData 对象：{ input: AgentInputItem[], instructions? }。input 字段是必需的，且必须是数组。返回任何其他形状都会抛出 UserError。

SDK 会在调用过滤器前克隆准备好的轮次输入。如果您同时使用 session，被过滤后的克隆会被持久化，因此此处应用的遮盖或截断也会反映在已存储的会话历史中。

使用 conversationId 或 previousResponseId 时，该钩子会在下一次 Responses API 调用的已准备载荷上运行。之前由服务器管理的上下文会由 API 恢复，因此该调用的过滤后数组可能已经只表示新轮次增量，而不是对早期历史的完整重放。如果需要在最终过滤步骤之前改变已存储历史与当前轮次的合并方式，请使用 sessionInputCallback。

工具错误格式化器

使用 toolErrorFormatter 自定义当工具调用被拒绝时发送回模型的批准拒绝消息。这样您可以返回特定领域的措辞（例如合规指导），而不是 SDK 默认消息。

该格式化器可以按运行设置（runner.run(..., { toolErrorFormatter })），也可以在 RunConfig 中全局设置（new Runner(...) 中的 toolErrorFormatter）。

此格式化器是批准拒绝的全局回退。如果您使用 result.state.reject(interruption, { message: '...' }) 拒绝特定中断，则该次调用的 message 优先于 toolErrorFormatter。如果两者都未提供，SDK 会回退到默认拒绝文本：Tool execution was not approved.

该格式化器目前针对 approval_rejected 事件运行，并接收：

kind（目前始终为 'approval_rejected'）
toolType（'function'、'computer'、'shell' 或 'apply_patch'）
toolName
callId
defaultMessage（SDK 回退消息，目前为 Tool execution was not approved.）
runContext

返回字符串以覆盖消息，或返回 undefined 保留 SDK 默认值。如果格式化器抛出异常（或返回非字符串值），SDK 会记录警告并回退到默认批准拒绝消息。

推理项 ID 策略

使用 reasoningItemIdPolicy 控制当 SDK 将先前生成的运行项转换回 AgentInputItem[] 以用于后续模型输入时，推理项是否保留其 id 字段。

这会影响 SDK 将生成的模型项重放为输入的场景，例如：

同一次运行内的后续模型调用（例如工具执行之后），
复用生成项作为输入/历史的后续轮次，
从已保存的 RunState 恢复的运行，
result.history / result.output 等派生的执行结果视图（它们是形如模型输入的数组）。
'preserve'（默认）保留推理项 ID。
'omit' 会在推理项被作为输入发送回去之前移除其 id 字段。
非推理项不受影响。

这不会改变：

原始模型响应（result.rawResponses），
运行项（result.newItems），
提供商返回的模型当前轮次输出。

换句话说，该策略适用于 SDK 基于先前生成项构建下一次输入时。

您可以按运行设置该策略（runner.run(..., { reasoningItemIdPolicy: 'omit' })），也可以作为 Runner 默认值设置（new Runner({ reasoningItemIdPolicy: 'omit', ... })）。从已保存的 RunState 恢复时，除非您覆盖它，否则会复用先前已解析的策略。

与 `callModelInputFilter` 的交互

reasoningItemIdPolicy 会在 callModelInputFilter 之前应用。如果您需要自定义行为，callModelInputFilter 仍然可以检查准备好的输入，并在模型调用前手动重新引入或移除推理 ID。

`'omit'` 的使用时机

当您希望重放的推理项在没有 ID 的情况下规范化时（例如，让转发/重放的模型输入更简单，或匹配应用流水线中的集成要求），请使用 'omit'。

如果您的后端/提供商因请求校验错误而拒绝重放的推理项（例如与后续输入中的推理项 ID 相关的 HTTP 400 错误），这也是一个有用的故障排除选项。在这些情况下，使用 'omit' 移除重放的推理 ID，可以避免发送后端认为对新请求无效的 ID。

如果您希望 SDK 在重放输入中保留推理项 ID，并且您的集成接受这些 ID，请保留 'preserve'。

错误与恢复

错误处理器

使用 errorHandlers 将受支持的运行时错误转换为最终输出，而不是抛出异常。受支持的键是 maxTurns 和 modelRefusal。

errorHandlers.maxTurns 仅处理最大轮次错误。
errorHandlers.modelRefusal 处理以 ModelRefusalError 暴露的模型拒绝。
errorHandlers.default 用作受支持类型的回退。
处理器接收 { error, context, runData }，并可返回 { finalOutput, includeInHistory? }。

异常

SDK 会抛出少量可捕获的错误：

MaxTurnsExceededError——达到 maxTurns。
ModelBehaviorError——模型产生了无效输出（例如格式不正确的 JSON、未知工具）。
ModelRefusalError——模型拒绝生成请求的输出。
InputGuardrailTripwireTriggered / OutputGuardrailTripwireTriggered——护栏违规。
ToolInputGuardrailTripwireTriggered / ToolOutputGuardrailTripwireTriggered——工具护栏违规。
GuardrailExecutionError——护栏未能完成。
ToolTimeoutError——函数工具超过 timeoutMs 且使用了 timeoutBehavior: 'raise_exception'。
ToolCallError——函数工具执行因非超时错误而失败。
UserError——基于配置或用户输入抛出的任何错误。

它们都继承自基类 AgentsError，该类可提供 state 属性以访问当前运行状态。

下面是一段处理 GuardrailExecutionError 的示例代码。由于输入护栏只在第一个用户输入上运行，该示例会使用原始输入和上下文重新启动运行。它还展示了如何复用已保存的状态来重试输出护栏，而无需再次调用模型：

import {
  Agent,
  GuardrailExecutionError,
  InputGuardrail,
  InputGuardrailTripwireTriggered,
  OutputGuardrail,
  OutputGuardrailTripwireTriggered,
  run,
} from '@openai/agents';
import { z } from 'zod';

// Shared guardrail agent to avoid re-creating it on every fallback run.
const guardrailAgent = new Agent({
  name: 'Guardrail check',
  instructions: 'Check if the user is asking you to do their math homework.',
  outputType: z.object({
    isMathHomework: z.boolean(),
    reasoning: z.string(),
  }),
});

async function main() {
  const input = 'Hello, can you help me solve for x: 2x + 3 = 11?';
  const context = { customerId: '12345' };

  // Input guardrail example

  const unstableInputGuardrail: InputGuardrail = {
    name: 'Math Homework Guardrail (unstable)',
    execute: async () => {
      throw new Error('Something is wrong!');
    },
  };

  const fallbackInputGuardrail: InputGuardrail = {
    name: 'Math Homework Guardrail (fallback)',
    execute: async ({ input, context }) => {
      const result = await run(guardrailAgent, input, { context });
      const isMathHomework =
        result.finalOutput?.isMathHomework ??
        /solve for x|math homework/i.test(JSON.stringify(input));
      return {
        outputInfo: result.finalOutput,
        tripwireTriggered: isMathHomework,
      };
    },
  };

  const agent = new Agent({
    name: 'Customer support agent',
    instructions:
      'You are a customer support agent. You help customers with their questions.',
    inputGuardrails: [unstableInputGuardrail],
  });

  try {
    // Input guardrails only run on the first turn of a run, so retries must start a fresh run.
    await run(agent, input, { context });
  } catch (e) {
    if (e instanceof GuardrailExecutionError) {
      console.error(`Guardrail execution failed (input): ${e}`);
      try {
        agent.inputGuardrails = [fallbackInputGuardrail];
        // Retry from scratch with the original input and context.
        await run(agent, input, { context });
      } catch (ee) {
        if (ee instanceof InputGuardrailTripwireTriggered) {
          console.log('Math homework input guardrail tripped on retry');
        } else {
          throw ee;
        }
      }
    } else {
      throw e;
    }
  }

  // Output guardrail example

  const replyOutputSchema = z.object({ reply: z.string() });

  const unstableOutputGuardrail: OutputGuardrail<typeof replyOutputSchema> = {
    name: 'Answer review (unstable)',
    execute: async () => {
      throw new Error('Output guardrail crashed.');
    },
  };

  const fallbackOutputGuardrail: OutputGuardrail<typeof replyOutputSchema> = {
    name: 'Answer review (fallback)',
    execute: async ({ agentOutput }) => {
      const outputText =
        typeof agentOutput === 'string'
          ? agentOutput
          : (agentOutput?.reply ?? JSON.stringify(agentOutput));
      const flagged = /math homework|solve for x|x =/i.test(outputText);
      return {
        outputInfo: { flaggedOutput: outputText },
        tripwireTriggered: flagged,
      };
    },
  };

  const agent2 = new Agent<unknown, typeof replyOutputSchema>({
    name: 'Customer support agent (output check)',
    instructions: 'You are a customer support agent. Answer briefly.',
    outputType: replyOutputSchema,
    outputGuardrails: [unstableOutputGuardrail],
  });

  try {
    await run(agent2, input, { context });
  } catch (e) {
    if (e instanceof GuardrailExecutionError && e.state) {
      console.error(`Guardrail execution failed (output): ${e}`);
      try {
        agent2.outputGuardrails = [fallbackOutputGuardrail];
        // Output guardrails can be retried using the saved state without another model call.
        await run(agent2, e.state);
      } catch (ee) {
        if (ee instanceof OutputGuardrailTripwireTriggered) {
          console.log('Output guardrail tripped after retry with saved state');
        } else {
          throw ee;
        }
      }
    } else {
      throw e;
    }
  }
}

main().catch(console.error);

输入重试与输出重试：

输入护栏只在一次运行的第一个用户输入上运行，因此必须用相同的输入/上下文启动一次全新的运行来重试它们——传入已保存的 state 不会重新触发输入护栏。
输出护栏在模型响应之后运行，因此可以复用 GuardrailExecutionError 中保存的 state 来重新运行输出护栏，而无需再次调用模型。

运行上面的示例时，您会看到以下输出：

Guardrail execution failed (input): Error: Input guardrail failed to complete: Error: Something is wrong!
Math homework input guardrail tripped on retry
Guardrail execution failed (output): Error: Output guardrail failed to complete: Error: Output guardrail crashed.
Output guardrail tripped after retry with saved state