跳转到内容

智能体

智能体是 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系统提示（字符串或函数——参见动态 instructions）。
modelno模型名称或自定义的Model实现。
modelSettingsno调参（temperature、top_p 等）。如果你需要的属性不在顶层，可以将它们放在 providerData 下。
toolsno模型可调用的 Tool 实例数组。
带工具的智能体
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 模式（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 使用工具，管理者总结最终答案。详见工具。

作为工具的智能体
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.',
    }),
  ],
});

交接（Handoffs）

Section titled “交接（Handoffs）”

通过交接，分诊智能体负责路由请求，但一旦发生交接，专家智能体将拥有对话，直到产生最终输出。这能保持提示简短，并让你可以独立地推理每个智能体。了解更多，请参阅交接。

带交接的智能体
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 和 Agent 实例，并可返回字符串或 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',
});

后续步骤

Section titled “后续步骤”