Agent 是基于 SDK 的工作流的核心单元。它封装了模型、指令以及可选的运行时行为，例如工具、护栏、MCP 服务器、交接和结构化输出。
Agent 上应该包含什么
使用 Agent 配置来处理该专家固有的决策：
| 属性 | 用途 | 延伸阅读 |
|---|---|---|
name | 追踪和工具/交接界面中供人阅读的标识 | 本页 |
instructions | 该 Agent 的任务、约束和风格 | 本页 |
prompt | 用于基于 Responses 的运行的已存储提示词配置 | 模型与提供方 |
model and model settings | 选择模型并调整行为 | 模型与提供方 |
tools | Agent 可直接调用的能力 | 使用工具 |
handoffDescription | 提示何时应将任务委派给此处的其他 Agent | 编排与交接 |
handoffs | 委派给另一个 Agent | 编排与交接 |
outputType | 返回结构化输出而非纯文本 | 本页 |
| 护栏与审批 | 验证、阻断与审查流程 | 护栏与人工审查 |
| MCP 服务器和托管的 MCP 工具 | 附加基于 MCP 的能力 | 集成与可观测性 |
从一个专注的 Agent 开始
定义能够负责明确任务的最小 Agent。仅当需要独立的归属权、不同的指令、不同的工具界面或不同的审批策略时，才添加更多 Agent。
定义单个 Agent
typescript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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-5.5",
tools: [getWeather],
});塑造指令、交接与输出
有三个配置选择需要特别注意：
- 从静态开始
instructions。当指引依赖于当前用户、租户或运行时上下文时，请改用动态指令回调，而不是在调用处拼接字符串。 - 保持
handoffDescription - 使用
outputType
返回结构化输出
typescript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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);使用 prompt 当你想引用 Responses API 中的已存储提示词配置，而不是将整个系统提示词嵌入代码中时。
将本地上下文与模型上下文分开
SDK 允许你将应用状态和依赖项传递给运行，而无需将它们发送给模型。将此用于认证用户信息、数据库客户端、日志记录器和辅助函数等数据。
将本地上下文传递给工具
typescript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import { Agent, RunContext, run, tool } from "@openai/agents";
import { z } from "zod";
interface UserInfo {
name: string;
uid: number;
}
const fetchUserAge = tool({
name: "fetch_user_age",
description: "Return the age of the current user.",
parameters: z.object({}),
async execute(_args, runContext?: RunContext<UserInfo>) {
return `User ${runContext?.context.name} is 47 years old`;
},
});
const agent = new Agent<UserInfo>({
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);The important boundary is:
- 对话历史记录是模型所看到的内容。
- 运行上下文是你的代码所看到的内容。
如果模型需要一个事实，请将其放入指令、输入、检索或工具中。如果只有你的运行时需要它，请将其保留在本地上下文中。
何时将一个 Agent 拆分为多个
当某个专家不应拥有完整的回复，或者当各项独立能力存在显著差异时，请拆分 Agent。常见原因包括：
- 专家需要不同的工具或 MCP 界面。
- 专家需要不同的审批策略或护栏。
- 工作流的某个分支需要不同的模型或输出风格。
- 你希望在追踪中进行显式路由，而不是使用单一的大型提示词。
后续步骤
一旦某个专家被干净利落地定义完毕，请前往与下一个设计问题相匹配的指南。