智能体

智能体是 OpenAI Agents SDK 的主要构建块。一个智能体是经过如下配置的大型语言模型（LLM）：

Instructions —— 告诉模型它是谁以及应如何响应的系统提示。
模型 —— 要调用的 OpenAI 模型，以及任何可选的模型调优参数。
工具 —— LLM 可调用以完成任务的函数或 API 列表。

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

const agent = new Agent({
  name: 'Haiku Agent',
  instructions: 'Always respond in haiku form.',
  model: 'gpt-5.4', // optional – falls back to the default model
});

当你想定义或自定义单个 Agent 时，请使用本页。如果你正在决定多个智能体应如何协作，请阅读智能体编排。

下一篇指南

将本页作为智能体定义的中心。根据你接下来需要做出的决策，跳转到相邻指南。

如果你想…	接下来阅读
选择模型或配置已存储的提示	模型
为智能体添加能力	工具
为智能体提供隔离的文件系统工作区	概念
在管理器和交接之间做选择	智能体编排
配置交接行为	交接
运行轮次、流式传输事件或管理状态	运行智能体
检查最终输出、运行项或恢复	执行结果

本页其余部分将更详细地介绍每个 Agent 功能。

智能体基础

基础配置

Agent 构造函数接收单个配置对象。下面列出了最常用的属性。

属性	必填	描述
`name`	是	简短的人类可读标识符。
`instructions`	是	系统提示（字符串或函数 —— 参见动态 instructions）。
`prompt`	否	OpenAI Responses API 的 prompt 配置。接受静态 prompt 对象或函数。参见 Prompt。
`handoffDescription`	否	当此智能体作为交接工具提供时使用的简短描述。
`handoffs`	否	将对话委派给专门的智能体。参见组合模式和交接指南。
`model`	否	模型名称或自定义 `Model` 实现。
`modelSettings`	否	调优参数（temperature、top_p 等）。参见模型。如果你需要的属性不在顶层，可以将它们放在 `providerData` 下。
`tools`	否	模型可以调用的 `Tool` 实例数组。参见工具。
`mcpServers`	否	智能体的由 MCP 支持的工具。参见 MCP 集成。
`mcpConfig`	否	本地 MCP 工具的选项，例如严格 schema、错误处理，以及带服务器前缀的工具名称。参见智能体级 MCP 配置。
`inputGuardrails`	否	应用于此智能体链中第一个用户输入的护栏。参见护栏。
`outputGuardrails`	否	应用于此智能体最终输出的护栏。参见护栏。
`outputType`	否	返回结构化输出而不是纯文本。参见输出类型和执行结果。
`toolUseBehavior`	否	控制函数工具结果是回传给模型，还是结束运行。参见强制工具使用。
`resetToolChoice`	否	工具调用后将 `toolChoice` 重置为默认值（默认：`true`），以防止工具使用循环。参见强制工具使用。
`handoffOutputTypeWarningEnabled`	否	当交接输出类型不一致时发出警告（默认：`true`）。参见执行结果。

import { Agent, tool } from '@openai/agents';
import { z } from 'zod';

const getWeather = tool({
  name: 'get_weather',
  description: 'Return the weather for a given city.',
  parameters: z.object({ city: z.string() }),
  async execute({ city }) {
    return `The weather in ${city} is sunny.`;
  },
});

const agent = new Agent({
  name: 'Weather bot',
  instructions: 'You are a helpful weather bot.',
  model: 'gpt-4.1',
  tools: [getWeather],
});

上下文

智能体的上下文类型是泛型，即 Agent<TContext, TOutput>。上下文是你创建并传给 Runner.run() 的依赖注入对象。它会转发给每个工具、护栏、交接等，并且适合用于存储状态或提供共享服务（数据库连接、用户元数据、功能标志等）。

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

interface Purchase {
  id: string;
  uid: string;
  deliveryStatus: string;
}
interface UserContext {
  uid: string;
  isProUser: boolean;

  // this function can be used within tools
  fetchPurchases(): Promise<Purchase[]>;
}

const agent = new Agent<UserContext>({
  name: 'Personal shopper',
  instructions: 'Recommend products the user will love.',
});

// Later
import { run } from '@openai/agents';

const result = await run(agent, 'Find me a new pair of running shoes', {
  context: { uid: 'abc', isProUser: true, fetchPurchases: async () => [] },
});

输出类型

默认情况下，智能体返回纯文本（string）。如果你希望模型返回结构化对象，可以指定 outputType 属性。SDK 接受：

Zod schema（z.object({...})）。
任何兼容 JSON Schema 的对象。

import { Agent } from '@openai/agents';
import { z } from 'zod';

const CalendarEvent = z.object({
  name: z.string(),
  date: z.string(),
  participants: z.array(z.string()),
});

const extractor = new Agent({
  name: 'Calendar extractor',
  instructions: 'Extract calendar events from the supplied text.',
  outputType: CalendarEvent,
});

提供 outputType 后，SDK 会自动使用 structured outputs，而不是纯文本。

OpenAI 平台映射

一些智能体概念会直接映射到 OpenAI 平台概念，另一些则在运行智能体时配置，而不是在定义智能体时配置。

SDK 概念	OpenAI 指南	适用场景
`outputType`	Structured Outputs	智能体应返回类型化 JSON 或经 Zod 验证的对象，而不是文本。
`tools` / 托管工具	工具指南	模型应搜索、检索、执行代码，或调用你的函数/工具。
`conversationId` / `previousResponseId`	对话状态	你希望 OpenAI 在多个轮次之间持久化或串联对话状态。

conversationId 和 previousResponseId 是运行时控制项，不是 Agent 构造函数字段。当你需要这些 SDK 入口点时，请使用运行智能体。

组合模式

当智能体参与更大的工作流时，最常出现两个 SDK 入口点：

管理器（agents as tools） —— 中央智能体拥有对话控制权，并调用以工具形式暴露的专门智能体。
交接 —— 初始智能体在识别用户请求后，将整个对话委派给专门智能体。

这些方法相互补充。管理器让你可以在一个地方强制执行护栏或速率限制，而交接让每个智能体专注于单一任务，无需保留对话控制权。关于设计取舍以及何时选择哪种模式，请参见智能体编排。

管理器（agents as tools）

在此模式中，管理器绝不移交控制权 —— LLM 使用工具，管理器汇总最终答案。在工具指南中了解更多。

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

const bookingAgent = new Agent({
  name: 'Booking expert',
  instructions: 'Answer booking questions and modify reservations.',
});

const refundAgent = new Agent({
  name: 'Refund expert',
  instructions: 'Help customers process refunds and credits.',
});

const customerFacingAgent = new Agent({
  name: 'Customer-facing agent',
  instructions:
    'Talk to the user directly. When they need booking or refund help, call the matching tool.',
  tools: [
    bookingAgent.asTool({
      toolName: 'booking_expert',
      toolDescription: 'Handles booking questions and requests.',
    }),
    refundAgent.asTool({
      toolName: 'refund_expert',
      toolDescription: 'Handles refund questions and requests.',
    }),
  ],
});

交接

使用交接时，分流智能体负责路由请求；但一旦发生交接，专门智能体就会接管对话，直到产生最终输出。这能保持提示简短，并让你可以独立推理每个智能体。在交接指南中了解更多。

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

const bookingAgent = new Agent({
  name: 'Booking Agent',
  instructions: 'Help users with booking requests.',
});

const refundAgent = new Agent({
  name: 'Refund Agent',
  instructions: 'Process refund requests politely and efficiently.',
});

// Use Agent.create method to ensure the finalOutput type considers handoffs
const triageAgent = Agent.create({
  name: 'Triage Agent',
  instructions: `Help the user with their questions.
  If the user asks about booking, hand off to the booking agent.
  If the user asks about refunds, hand off to the refund agent.`.trimStart(),
  handoffs: [bookingAgent, refundAgent],
});

如果你的交接目标可能返回不同输出类型，优先使用 Agent.create(...) 而不是 new Agent(...)。这样 TypeScript 可以在整个交接图中推断可能的 finalOutput 形状的联合类型，并避免由 handoffOutputTypeWarningEnabled 控制的运行时警告。参见执行结果指南获取端到端示例。

高级配置和运行时控制

动态 instructions

instructions 可以是函数而不是字符串。该函数接收当前 RunContext 和 Agent 实例，并可以返回字符串或 Promise<string>。

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

interface UserContext {
  name: string;
}

function buildInstructions(runContext: RunContext<UserContext>) {
  return `The user's name is ${runContext.context.name}. Be extra friendly!`;
}

const agent = new Agent<UserContext>({
  name: 'Personalized helper',
  instructions: buildInstructions,
});

同步函数和 async 函数均受支持。

动态 prompt

prompt 支持与 instructions 相同的回调形状，但返回的是 prompt 配置对象，而不是字符串。当 prompt ID、版本或变量取决于当前运行上下文时，这很有用。

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

interface PromptContext {
  customerTier: 'free' | 'pro';
}

function buildPrompt(runContext: RunContext<PromptContext>) {
  return {
    promptId: 'pmpt_support_agent',
    version: '7',
    variables: {
      customer_tier: runContext.context.customerTier,
    },
  };
}

const agent = new Agent<PromptContext>({
  name: 'Prompt-backed helper',
  prompt: buildPrompt,
});

仅在使用 OpenAI Responses API 时支持此功能。同步函数和 async 函数均受支持。

生命周期钩子

对于高级用例，你可以通过监听事件来观察智能体生命周期。

Agent 实例会为该特定智能体实例发出生命周期事件，而 Runner 则会在整个运行范围内以单个流发出相同名称的事件。这对于多智能体工作流很有用，因为你可能希望在一个地方观察交接和工具调用。

共享事件名称如下：

事件	Agent 钩子参数	Runner 钩子参数
`agent_start`	`(context, agent, turnInput?)`	`(context, agent, turnInput?)`
`agent_end`	`(context, output)`	`(context, agent, output)`
`agent_handoff`	`(context, nextAgent)`	`(context, fromAgent, toAgent)`
`agent_tool_start`	`(context, tool, { toolCall })`	`(context, agent, tool, { toolCall })`
`agent_tool_end`	`(context, tool, result, { toolCall })`	`(context, agent, tool, result, { toolCall })`

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

const agent = new Agent({
  name: 'Verbose agent',
  instructions: 'Explain things thoroughly.',
});

agent.on('agent_start', (ctx, agent) => {
  console.log(`[${agent.name}] started`);
});
agent.on('agent_end', (ctx, output) => {
  console.log(`[agent] produced:`, output);
});

护栏

护栏允许你验证或转换用户输入和智能体输出。它们通过 inputGuardrails 和 outputGuardrails 数组配置。详情请参见护栏。

智能体克隆 / 复制

需要现有智能体的稍微修改版本？使用 clone() 方法，它会返回一个全新的 Agent 实例。

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

const pirateAgent = new Agent({
  name: 'Pirate',
  instructions: 'Respond like a pirate – lots of “Arrr!”',
  model: 'gpt-5.4',
});

const robotAgent = pirateAgent.clone({
  name: 'Robot',
  instructions: 'Respond like a robot – be precise and factual.',
});

强制工具使用

提供工具并不能保证 LLM 会调用其中某个工具。你可以使用 modelSettings.toolChoice 强制使用工具：

'auto'（默认）—— LLM 自行决定是否使用工具。
'required' —— LLM 必须调用工具（它可以选择调用哪一个）。
'none' —— LLM 不得调用工具。
特定工具名称，例如 'calculator' —— LLM 必须调用该特定工具。

当可用工具是 OpenAI Responses 上的 computerTool() 时，toolChoice: 'computer' 是特殊值：它会强制使用 GA 内置计算机工具，而不是将 'computer' 当作普通函数名称。SDK 也接受兼容预览版的 computer 选择器以支持较旧集成，但新代码应优先使用 'computer'。如果没有可用的计算机工具，该字符串的行为与任何其他函数工具名称相同。

import { Agent, tool } from '@openai/agents';
import { z } from 'zod';

const calculatorTool = tool({
  name: 'Calculator',
  description: 'Use this tool to answer questions about math problems.',
  parameters: z.object({ question: z.string() }),
  execute: async (input) => {
    throw new Error('TODO: implement this');
  },
});

const agent = new Agent({
  name: 'Strict tool user',
  instructions: 'Always answer using the calculator tool.',
  tools: [calculatorTool],
  modelSettings: { toolChoice: 'required' },
});

当你使用延迟加载的 Responses 工具（例如 toolNamespace()）、带有 deferLoading: true 的函数工具，或带有 deferLoading: true 的托管 MCP 工具时，请将 modelSettings.toolChoice 保持为 'auto'。SDK 会拒绝按名称强制使用延迟工具或内置 tool_search 辅助工具，因为模型需要决定何时加载这些定义。完整的工具搜索设置请参见工具。

无限循环预防

工具调用后，SDK 会自动将 toolChoice 重置回 'auto'。这可以防止模型进入无限循环，即反复尝试调用该工具。你可以通过 resetToolChoice 标志或配置 toolUseBehavior 覆盖此行为：

'run_llm_again'（默认）—— 使用工具结果再次运行 LLM。
'stop_on_first_tool' —— 将第一个工具结果视为最终答案。
{ stopAtToolNames: ['my_tool'] } —— 当列出的任一工具被调用时停止。
(context, toolResults) => ... —— 自定义函数，返回运行是否应结束。

const agent = new Agent({
  ...,
  toolUseBehavior: 'stop_on_first_tool',
});

注意：toolUseBehavior 仅适用于函数工具。托管工具始终返回给模型处理。

智能体