跳转到内容

智能体

智能体是 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
});

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


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],
});

智能体对其上下文类型是泛化的,即 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. 任何兼容 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 而不是纯文本。


组合智能体的方式有很多。在生产应用中我们经常看到两种模式:

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

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

在这种模式中,管理者不会移交控制权——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],
});

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 函数。


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

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

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


需要现有智能体的略微修改版本?使用 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.',
});

提供工具并不保证 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' },
});

在工具调用之后,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',
});