在工作流结构清晰之后，接下来的问题是：哪些外部接口应置于智能体循环内部，以及如何检查运行时的实际情况。
选择 SDK 中的内置功能
| 需求 | 起始项 | 原因 |
|---|---|---|
| 让智能体能够访问公开的、远程托管的 MCP 工具 | SDK 中托管的 MCP 工具 | 模型可以通过托管接口调用远程 MCP 服务器 |
| 在运行时连接本地或私有 MCP 服务器 | 通过 stdio 或可流式 HTTP 进行 SDK 管理的 MCP 服务器 | 由你的运行时掌控连接、审批和网络边界 |
| 调试提示、工具、交接或审批 | 内置跟踪 | 在正式制定评估体系之前，跟踪记录可提供端到端的完整记录 |
工具功能的语义仍然存在于 使用工具。本页面重点介绍特定于 SDK 的 MCP 连接与可观测性循环。
MCP
当远程服务器应通过模型接口运行时，请使用托管的 MCP 工具。
接入托管的 MCP 服务器
typescript
1
2
3
4
5
6
7
8
9
10
11
12
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import { Agent, MCPServerStdio, run } from "@openai/agents";
const server = new MCPServerStdio({
name: "Filesystem MCP Server",
fullCommand: "npx -y @modelcontextprotocol/server-filesystem ./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();
}The practical split is:
- 使用 托管 MCP 适用于符合平台信任模型的公开远程服务器。
- 使用 本地或私有 MCP 当你的运行时应自主掌控连接、过滤或审批时使用。
有关全平台的概念、信任模型和产品支持说明，请将 MCP 与连接器 作为权威参考。
跟踪
跟踪功能内置于 Agents SDK 中，并在标准的服务器端 SDK 路径中默认启用。每次运行都可以生成包含模型调用、工具调用、交接、护栏和自定义 Span 的结构化记录，你可以在 跟踪面板.
默认跟踪通常会为你提供：
- 整体运行或工作流
- 每次模型调用
- 工具调用及其输出
- 交接和护栏
- 你在工作流周围封装的任何自定义 Span
如果你需要减少跟踪数据，请使用 SDK 级别或单次运行的跟踪控制，而不是彻底移除工作流中的所有可观测性。
将多次运行封装在同一个跟踪中
typescript
1
2
3
4
5
6
7
8
9
10
11
12
13
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);
});使用跟踪来完成两项任务：
- 调试单次工作流运行并了解期间发生的具体情况。
- 一旦你准备好对行为进行系统评分，就将高信号样本输入到 智能体工作流评估 中。
后续步骤
接入外部接口后，请继续阅读涵盖功能设计、审查边界或评估的指南。