明确工作流的结构后,您需要决定将哪些外部能力接入智能体的执行循环,以及如何查看运行时实际发生了什么。
选择要在 SDK 中集成的功能
| 需求 | 建议从这里开始 | 原因 |
|---|---|---|
| 让智能体访问远程托管的公开 MCP 工具 | SDK 中的托管 MCP 工具 | 模型可以通过托管接口调用远程 MCP 服务器 |
| 从您的运行时环境连接本地或私有 MCP 服务器 | 由 SDK 管理、通过 stdio 或流式 HTTP 连接的 MCP 服务器 | 您的运行时环境负责管理连接、审批和网络边界 |
| 调试提示、工具、任务交接或审批流程 | 内置追踪功能 | 在建立正式的评估流程之前,您就可以通过追踪查看端到端的运行记录 |
有关各类工具的能力及其工作方式,请参阅使用工具。本页重点介绍如何在 SDK 中接入 MCP,以及如何通过追踪检查工作流的运行情况。
MCP
如果需要让模型通过平台提供的接口调用远程 MCP 服务器,请使用托管 MCP 工具。
接入托管 MCP 服务器
TypeScript
import { Agent, hostedMcpTool } from "@openai/agents";
const agent = new Agent({
name: "MCP assistant",
instructions: "Use the MCP tools to answer questions.",
tools: [
hostedMcpTool({
serverLabel: "gitmcp",
serverUrl: "https://gitmcp.io/openai/codex",
}),
],
});如果您的应用需要直接连接 MCP 服务器,请使用本地传输方式。
连接本地 MCP 服务器
TypeScript
import { Agent, MCPServerStdio, run } from "@openai/agents";
const server = new MCPServerStdio({
name: "Filesystem MCP Server",
fullCommand:
"npx -y @modelcontextprotocol/server-filesystem fixtures/sample_files",
});
await server.connect();
try {
const agent = new Agent({
name: "Filesystem assistant",
instructions: "Read files with the MCP tools before answering.",
mcpServers: [server],
});
const result = await run(agent, "Read the files and list them.");
console.log(result.finalOutput);
} finally {
await server.close();
}您可以按以下原则选择:
- 对于符合平台信任模型的公开远程服务器,使用托管 MCP。
- 如果需要由您的运行时环境管理连接、过滤或审批,使用本地或私有 MCP。
有关 MCP 在整个平台上的基本概念、信任模型以及各产品的支持情况,请以 MCP 服务器为准。
追踪
Agents SDK 内置了追踪功能,在服务端按常规方式使用 SDK 时默认启用。每次运行都可以生成结构化记录,涵盖模型调用、工具调用、任务交接、护栏和自定义跨度。您可以在追踪仪表板中查看这些记录。
默认情况下,一条追踪记录通常包括:
- 一次运行或一个工作流的整体情况
- 每次模型调用
- 工具调用及其输出
- 任务交接和护栏
- 您为整个工作流设置的自定义跨度
如果需要减少追踪,请在 SDK 层面或针对单次运行调整追踪设置,这样仍能观察工作流的运行情况。
在一条追踪记录中包含多次运行
TypeScript
import { Agent, run, withTrace } from "@openai/agents";
const agent = new Agent({
name: "Joke generator",
instructions: "Tell funny jokes.",
});
await withTrace("Joke workflow", async () => {
const first = await run(agent, "Tell me a joke");
const second = await run(agent, `Rate this joke: ${first.finalOutput}`);
console.log(first.finalOutput);
console.log(second.finalOutput);
});追踪记录有两种用途:
- 调试工作流的某一次运行,了解实际发生了什么。
- 当您准备好对智能体的行为进行系统评分时,从追踪记录中选取更能反映其行为的样例,用于智能体工作流评估。
后续步骤
接入外部能力后,您可以根据需要继续阅读有关能力设计、审查范围或评估的指南。