智能体（Agent）是基于 SDK 工作流的核心单元。它封装了模型、指令以及可选的运行时行为，例如工具、护栏（guardrails）、MCP 服务器、交接（handoffs）和结构化输出。
智能体应包含哪些内容
对于该专家智能体所固有的决策，请使用智能体配置
| 属性 | 将其用于 | 继续阅读 |
|---|---|---|
name | 在追踪信息及工具/交接界面中提供人类可读的身份标识 | 本页面 |
instructions (指令) | 该智能体的工作任务、约束条件和风格 | 本页面 |
prompt | 基于 Responses 的运行所存储的提示词配置 | 模型与服务商 |
model (模型) 及模型设置 | 选择模型并调整行为 | 模型与服务商 |
tools (工具) | 智能体可直接调用的能力 | 使用工具 |
handoffDescription (交接描述) | 当其他智能体应委托任务于此时的提示 | 编排与交接 |
handoffs (交接) | 委托给另一个智能体 | 编排与交接 |
outputType (输出类型) | 返回结构化输出而非纯文本 | 本页面 |
| 护栏与审批 | 验证、拦截和审核流程 | 护栏与人工审核 |
| MCP 服务器与托管的 MCP 工具 | 附加基于 MCP 的能力 | 集成与可观测性 |
从一个专注的智能体开始
定义能够处理明确任务的最小智能体。仅在需要单独的所有权、不同的指令、不同的工具界面或不同的审批策略时，才添加更多智能体。
定义单个智能体
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);当你想要引用 Responses API 中存储的提示词配置，而不是将整个系统提示词嵌入代码时，请使用 prompt。
将本地上下文与模型上下文分开
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);重要的边界在于
- 对话历史记录是模型所看到的内容。
- 运行上下文是你的代码所看到的内容。
如果模型需要某个事实，请将其放入指令、输入、检索或工具中。如果只有你的运行时需要它，请将其保留在本地上下文中。
何时将一个智能体拆分为多个
当某个专家不应拥有全部回复，或者当不同的功能本质上存在差异时，应拆分智能体。常见原因包括：
- 专家需要不同的工具或 MCP 界面。
- 专家需要不同的审批策略或护栏。
- 工作流的某个分支需要不同的模型或输出风格。
- 你希望在追踪中进行显式路由，而不是使用单个大型提示词。
后续步骤
一旦某个专家被清晰定义，请移步至符合下一个设计问题的指南。