跳转到内容

智能体

智能体是 OpenAI Agents SDK 的主要构建块。一个**智能体（Agent）**是经过以下配置的 Large Language Model（LLM）：

  • Instructions —— 指示模型“它是谁”以及“应如何回复”的系统提示。
  • Model —— 要调用的 OpenAI 模型，以及可选的模型调优参数。
  • Tools —— LLM 可调用以完成任务的函数或 API 列表。
基础智能体定义
import { Agent } from '@openai/agents';


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

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

基础配置

Section titled “基础配置”

Agent 构造函数接受一个配置对象。最常用的属性如下所示。

PropertyRequiredDescription
nameyes简短的、可读的人类标识符。
instructionsyes系统提示（字符串或函数——参见 Dynamic instructions）。
handoffDescriptionno当该智能体作为交接工具提供时使用的简短描述。
modelno模型名称或自定义的 Model 实现。
modelSettingsno调优参数（temperature、top_p 等）。如果你需要的属性不在顶层，可放在 providerData 下。
toolsno模型可调用的 Tool 实例数组。
mcpServersno为智能体提供工具的 MCP 服务器。参见 MCP 集成。
resetToolChoiceno在工具调用后将 tool_choice 重置为默认值（默认：true），以防止工具使用循环。参见 Forcing tool use。
带工具的智能体
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],
});

上下文

Section titled “上下文”

智能体对其上下文类型是泛型的 —— 即 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 () => [] },
});

输出类型

Section titled “输出类型”

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

  1. Zod schema（z.object({...})）。
  2. 任意兼容 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，而不是纯文本。

多智能体系统设计模式

Section titled “多智能体系统设计模式”

组合智能体的方式有很多。在生产应用中常见的两种模式是：

  1. Manager（Agents as tools） —— 一个中心智能体拥有对话并调用作为工具暴露的专业化智能体。
  2. 交接（Handoffs） —— 初始智能体在识别出用户请求后，将整个对话委派给专家智能体。

这两种方式是互补的。Manager 让你能在一个位置统一实施护栏或速率限制，而交接让每个智能体专注于单一任务，而无需保留对话的控制权。

Manager（Agents as tools）

Section titled “Manager（Agents as tools）”

在该模式中，管理器不会移交控制权——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.',
    }),
  ],
});

交接

Section titled “交接”

在交接模式中，分诊智能体负责路由请求，但一旦发生交接，专家智能体将拥有对话的控制权，直到其产生最终输出。这样可以保持提示更短，并且使你可以独立地思考每个智能体。进一步了解 交接。

带交接的智能体
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],
});

动态 instructions

Section titled “动态 instructions”

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

带动态 instructions 的智能体
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 函数。

生命周期钩子

Section titled “生命周期钩子”

对于高级用例，你可以通过监听事件来观察智能体生命周期。要了解可用项，请参阅列在此处的智能体钩子事件名称。

带生命周期钩子的智能体
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);
});

护栏

Section titled “护栏”

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

克隆/复制智能体

Section titled “克隆/复制智能体”

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

克隆智能体
import { Agent } from '@openai/agents';


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


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

强制使用工具

Section titled “强制使用工具”

提供工具并不保证 LLM 会调用。你可以通过 modelSettings.tool_choice 来强制使用工具：

  1. 'auto'（默认）—— 由 LLM 决定是否使用工具。
  2. 'required' —— LLM 必须调用某个工具（可自行选择）。
  3. 'none' —— LLM 必须不调用任何工具。
  4. 指定工具名，例如 'calculator' —— LLM 必须调用该特定工具。
强制使用工具
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: 'auto' },
});

防止无限循环

Section titled “防止无限循环”

在工具调用后，SDK 会自动将 tool_choice 重置回 '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 仅适用于函数工具（function tools）。托管工具（Hosted tool）始终会返回给模型进行处理。

后续步骤

Section titled “后续步骤”