智能体是基于 SDK 构建的工作流的核心单元。它将模型和指令封装在一起,还可以按需配置工具、护栏、MCP 服务器、任务移交和结构化输出等运行时功能。
智能体应配置哪些内容
与某个智能体自身职责有关的设置,应放在该智能体的配置中。
| 属性 | 用途 | 延伸阅读 |
|---|---|---|
name |
在追踪记录、工具和任务移交界面中提供便于识别的名称 | 本页 |
instructions |
定义智能体的任务、约束和风格 | 本页 |
prompt |
在基于 Responses API 的运行中引用已保存的提示词配置 | 模型与提供商 |
model 和模型设置 |
选择模型并调整其行为 | 模型与提供商 |
tools |
指定智能体可直接调用的功能 | 使用工具 |
handoffDescription |
提示其他智能体何时应将任务交给此智能体 | 编排与任务移交 |
handoffs |
将任务交给其他智能体 | 编排与任务移交 |
outputType |
以结构化输出代替纯文本 | 本页 |
| 护栏与审批 | 验证、拦截和审核流程 | 护栏与人工审核 |
| MCP 服务器和托管的 MCP 工具 | 接入由 MCP 提供的功能 | 集成与可观测性 |
从一个职责明确的智能体开始
先定义一个尽可能简单、能独立负责一项明确任务的智能体。只有在需要划分职责、使用不同的指令或工具接口,或采用不同的审批策略时,才添加更多智能体。
定义单个智能体
TypeScript
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
返回结构化输出
TypeScript
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 允许您在运行时传入应用状态和依赖项,而无需将其发送给模型。这种方式适用于已通过身份验证的用户信息、数据库客户端、日志记录器和辅助函数等。
向工具传递本地上下文
TypeScript
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 接口。
- 某个智能体需要采用不同的审批策略或护栏。
- 工作流中的某个分支需要使用不同的模型或输出风格。
- 您希望在追踪记录中清楚地看到任务如何分派,而不是用一个冗长的提示词处理所有任务。
后续步骤
定义好一个职责明确的智能体后,请根据接下来要解决的设计问题选择相应的指南。