跳转到内容

智能体

智能体是 OpenAI Agents SDK 的主要构建模块。智能体是配置了以下内容的大语言模型(LLM):

  • 指令——系统提示,用于告诉模型它的角色是什么以及它应该如何回应。
  • 模型——要调用的 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 构造函数接受一个配置对象。下表列出了最常用的属性。

属性是否必需说明
name是简短、易读的标识符。
instructions是系统提示(字符串或函数——参见动态指令)。
prompt否OpenAI Responses API 提示词配置。接受静态提示词对象或函数。参见提示词。
handoffDescription否将此智能体作为交接工具提供时使用的简短描述。
handoffs否将对话委派给专业智能体。参见组合模式和交接指南。
model否模型名称或自定义的 Model 实现。
modelSettings否调优参数(temperature、top_p 等)。参见模型。如果您需要的属性不在顶层,可以将它们放在 providerData 下。
tools否模型可以调用的 Tool 实例数组。参见工具。
mcpServers否为智能体提供工具的 MCP 服务器。参见 MCP 集成指南。
mcpConfig否本地 MCP 工具的选项,例如严格模式、错误处理以及带服务器前缀的工具名称。参见智能体级 MCP 配置。
inputGuardrails否应用于此智能体链首次用户输入的护栏。参见护栏。
outputGuardrails否应用于此智能体最终输出的护栏。参见护栏。
outputType否返回结构化输出,而非纯文本。参见输出类型和执行结果。
toolUseBehavior否控制 SDK 是将函数工具的结果发回模型,还是将函数工具的结果用作本次运行的最终输出。参见强制工具使用。
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 接受以下类型:

  1. Zod 模式(z.object({...}))。
  2. 支持通过 Standard JSON Schema 转换的 Standard Schema 值。
  3. 任何兼容 JSON Schema 的对象。
使用 Zod 的结构化输出
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,而非纯文本。

Zod 和受支持的 Standard Schema 值会在本地验证解析后的输出,并保留其推断出的输出类型。原始 JSON Schema 描述了模型的输出约定,但解析结果的类型仍为 unknown。有关 Standard Schema 示例和支持的验证范围,请参见模式验证。


一些智能体概念直接对应 OpenAI 平台概念,另一些则在运行智能体时配置,而非在定义智能体时配置。

SDK 概念OpenAI 指南适用场景
outputTypeStructured Outputs智能体需要返回具有明确类型的 JSON 或经过模式验证的对象,而非文本。
tools / 托管工具工具指南模型需要搜索、检索、执行代码或调用您的函数/工具。
conversationId / previousResponseId对话状态您希望 OpenAI 在轮次之间持久保存或串联对话状态。

conversationId 和 previousResponseId 是运行时控制项,而非 Agent 构造函数字段。如果需要使用这些 SDK 入口,请参阅运行智能体。


当智能体参与较大的工作流时,最常用到以下两种 SDK 入口:

  1. 管理者(agents as tools)——由一个中央智能体掌控对话,并调用以工具形式提供的专业智能体。
  2. 交接——初始智能体识别出用户请求后,将整个对话委派给专业智能体。

这两种方式相辅相成。管理者模式让您可以在一个统一位置实施护栏或速率限制,而交接模式则让每个智能体专注于单一任务,无需持续掌控对话。有关设计上的权衡以及各模式的适用时机,请参见智能体编排。

在此模式下,管理者始终保留控制权——LLM 使用工具,管理者汇总最终答案。更多信息请参阅工具指南。

Agents as tools
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 可以是函数,而非字符串。该函数接收当前的 RunContext 和智能体实例,并可返回字符串或 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 支持与 instructions 相同的回调形式,但返回提示词配置对象,而非字符串。当提示词 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.',
});

clone() 不会复制 tools、handoffs、mcpServers、inputGuardrails 或 outputGuardrails 等列表属性。当克隆配置省略其中某个属性时,原始智能体和克隆智能体会共享同一个数组,因此通过任一智能体修改该数组都会影响两个智能体。要让克隆智能体拥有自己的数组,请传入新数组,例如 tools: [...agent.tools, extraTool];该新数组中的条目仍然是相同的工具或交接对象。将列表属性传为 undefined 也算显式提供该属性,此时该列表会初始化为空列表,而非继承原始数组。


提供工具并不保证 LLM 会调用工具。您可以通过 modelSettings.toolChoice 强制使用工具:

  1. 'auto'(默认)——LLM 自行决定是否使用工具。
  2. 'required'——LLM 必须调用工具(可以自行选择调用哪一个)。
  3. 'none'——LLM 不得调用工具。
  4. 具体的工具名称,例如 'calculator'——LLM 必须调用该特定工具。

当可用工具是 OpenAI Responses 上的 computerTool() 时,toolChoice: 'computer' 有特殊含义:它会强制使用正式发布的内置计算机工具,而非将 'computer' 视为普通函数名。SDK 也接受与预览版兼容的计算机工具选择器,以支持旧版集成,但新代码应优先使用 '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) => ...——返回是否应结束运行的自定义函数。
在获得第一个函数工具结果后停止
import { Agent, tool } from '@openai/agents';
import { z } from 'zod';
const calculatorTool = tool({
name: 'calculator',
description: 'Add two numbers.',
parameters: z.object({ left: z.number(), right: z.number() }),
execute: async ({ left, right }) => left + right,
});
const agent = new Agent({
name: 'Calculator agent',
instructions: 'Use the calculator tool to answer arithmetic questions.',
tools: [calculatorTool],
toolUseBehavior: 'stop_on_first_tool',
});

注意:toolUseBehavior 仅适用于函数工具。托管工具始终会将结果返回给模型处理。


  • 模型:模型选择、已存储的提示词和提供方配置。
  • 工具:函数工具、托管工具、MCP 和 agent.asTool()。
  • 智能体编排:在管理者模式、交接和代码驱动的编排之间做出选择。
  • 交接:配置向专业智能体的委派。
  • 运行智能体:执行轮次、流式传输和对话状态。
  • 执行结果:finalOutput、运行条目和恢复状态。
  • 在侧边栏的 @openai/agents 下探索完整的 TypeDoc 参考文档。