跳转到内容

智能体

智能体是 OpenAI Agents SDK 的主要构建模块。一个Agent 是已配置好的大型语言模型（LLM），包含：

  • Instructions —— 告诉模型“它是谁”以及“应如何回复”的系统提示。
  • Model —— 要调用的 OpenAI 模型，以及可选的模型调参。
  • Tools —— LLM 可调用以完成任务的一组函数或 API。
基础 Agent 定义
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
});

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

基础配置

Section titled “基础配置”

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

属性必需描述
nameyes简短的人类可读标识符。
instructionsyes系统提示（字符串或函数——参见动态 instructions）。
modelno模型名称或自定义的 Model 实现。
modelSettingsno调参（temperature、top_p 等）。如果所需属性不在顶层，可放入 providerData 下。
toolsno模型可调用的 Tool 实例数组。
带工具的 Agent
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()。它会被转发到每个工具、护栏、交接等，对于存储状态或提供共享服务（数据库连接、用户元数据、功能开关等）很有用。

带上下文的 Agent
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 “输出类型”

默认情况下，Agent 返回纯文本（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. 管理者（智能体作为工具）——一个中心智能体掌控对话，并调用作为工具暴露的专业智能体。
  2. 交接——初始智能体在识别出用户请求后，将整个对话委派给某个专家智能体。

这些方法是互补的。管理者让你可以在单处实施护栏或速率限制，而交接则让每个智能体专注于单一任务而无需保留对话控制权。

管理者（智能体作为工具）

Section titled “管理者（智能体作为工具）”

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

交接

Section titled “交接”

采用交接时，分诊智能体负责路由请求，但一旦发生交接，专家智能体就拥有对话控制权直到产生最终输出。这能保持提示简短，并让你独立地推理每个智能体。了解更多参见交接指南。

带交接的 Agent
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 的 Agent
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 “生命周期钩子”

对于高级用例，你可以通过监听事件来观察 Agent 的生命周期。可用事件名称参见此处的 agent 钩子事件列表。

带生命周期钩子的 Agent
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 “下一步”