如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

智能体定义

先配置好一个职责明确的智能体,再扩展到更大的工作流。

智能体是基于 SDK 构建的工作流的核心单元。它将模型和指令封装在一起,还可以按需配置工具、护栏、MCP 服务器、任务移交和结构化输出等运行时功能。

智能体应配置哪些内容

与某个智能体自身职责有关的设置,应放在该智能体的配置中。

属性 用途 延伸阅读
name 在追踪记录、工具和任务移交界面中提供便于识别的名称 本页
instructions 定义智能体的任务、约束和风格 本页
prompt 在基于 Responses API 的运行中引用已保存的提示词配置 模型与提供商
model 和模型设置 选择模型并调整其行为 模型与提供商
tools 指定智能体可直接调用的功能 使用工具
handoffDescription 提示其他智能体何时应将任务交给此智能体 编排与任务移交
handoffs 将任务交给其他智能体 编排与任务移交
outputType 以结构化输出代替纯文本 本页
护栏与审批 验证、拦截和审核流程 护栏与人工审核
MCP 服务器和托管的 MCP 工具 接入由 MCP 提供的功能 集成与可观测性

从一个职责明确的智能体开始

先定义一个尽可能简单、能独立负责一项明确任务的智能体。只有在需要划分职责、使用不同的指令或工具接口,或采用不同的审批策略时,才添加更多智能体。

定义单个智能体
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-6.2-astra",
  tools: [getWeather],
});

配置指令、任务移交和输出

以下三项配置需要特别留意:

  • 先使用静态 instructions。如果指令取决于当前用户、租户或运行时上下文,请改用回调函数动态生成指令,避免在调用处拼接字符串。
  • handoffDescription 的描述应简短具体,让负责路由的智能体知道何时应将任务交给该智能体。
  • 如果下游代码需要有明确类型的数据,而非自由格式的文本,请使用 outputType。
返回结构化输出
import { Agent, run } from "@openai/agents";
import { z } from "zod";

const calendarEvent = z.object({
  name: z.string(),
  date: z.string(),
  participants: z.array(z.string()),
});

const agent = new Agent({
  name: "Calendar extractor",
  instructions: "Extract calendar events from text.",
  outputType: calendarEvent,
});

const result = await run(agent, "Dinner with Priya and Sam on Friday.");

console.log(result.finalOutput);

如果您希望引用 Responses API 中已保存的提示词配置,而无需将完整的系统提示词嵌入代码,请使用 prompt。

区分本地上下文与模型上下文

SDK 允许您在运行时传入应用状态和依赖项,而无需将其发送给模型。这种方式适用于已通过身份验证的用户信息、数据库客户端、日志记录器和辅助函数等。

向工具传递本地上下文
import { Agent, run, tool, type RunContext } from "@openai/agents";
import { z } from "zod";

const fetchUserAge = tool({
  name: "fetch_user_age",
  description: "Return the age of the current user.",
  parameters: z.object({}),
  async execute(
    _args: unknown,
    runContext: RunContext<{ name: string; uid: number }> | undefined
  ) {
    return `User ${runContext?.context.name} is 47 years old`;
  },
});

const agent = new Agent({
  name: "Assistant",
  tools: [fetchUserAge],
});

const result = await run(agent, "What is the age of the user?", {
  context: { name: "John", uid: 123 },
});

console.log(result.finalOutput);

两者的可见范围不同:

  • 模型可以看到对话历史。
  • 您的代码可以访问运行上下文。

如果模型需要某项信息,请在指令或输入中提供,或让模型通过检索或工具获取。如果只有运行时需要该信息,将其保留在本地上下文中即可。

何时将一个智能体拆分为多个

如果不宜由一个智能体负责整个回复,或者各项能力有实质性差异,就可以拆分智能体。常见原因包括:

  • 某个智能体需要使用不同的工具或 MCP 接口。
  • 某个智能体需要采用不同的审批策略或护栏。
  • 工作流中的某个分支需要使用不同的模型或输出风格。
  • 您希望在追踪记录中清楚地看到任务如何分派,而不是用一个冗长的提示词处理所有任务。

后续步骤

定义好一个职责明确的智能体后,请根据接下来要解决的设计问题选择相应的指南。