如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

集成与可观测性

在开始调优之前,先通过 MCP 接入外部能力并检查运行记录。

明确工作流的结构后,您需要决定将哪些外部能力接入智能体的执行循环,以及如何查看运行时实际发生了什么。

选择要在 SDK 中集成的功能

需求 建议从这里开始 原因
让智能体访问远程托管的公开 MCP 工具 SDK 中的托管 MCP 工具 模型可以通过托管接口调用远程 MCP 服务器
从您的运行时环境连接本地或私有 MCP 服务器 由 SDK 管理、通过 stdio 或流式 HTTP 连接的 MCP 服务器 您的运行时环境负责管理连接、审批和网络边界
调试提示、工具、任务交接或审批流程 内置追踪功能 在建立正式的评估流程之前,您就可以通过追踪查看端到端的运行记录

有关各类工具的能力及其工作方式,请参阅使用工具。本页重点介绍如何在 SDK 中接入 MCP,以及如何通过追踪检查工作流的运行情况。

MCP

如果需要让模型通过平台提供的接口调用远程 MCP 服务器,请使用托管 MCP 工具。

接入托管 MCP 服务器
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 服务器
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 层面或针对单次运行调整追踪设置,这样仍能观察工作流的运行情况。

在一条追踪记录中包含多次运行
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);
});

追踪记录有两种用途:

  • 调试工作流的某一次运行,了解实际发生了什么。
  • 当您准备好对智能体的行为进行系统评分时,从追踪记录中选取更能反映其行为的样例,用于智能体工作流评估。

后续步骤

接入外部能力后,您可以根据需要继续阅读有关能力设计、审查范围或评估的指南。