集成和可观测性 | OpenAI API

来源: https://developers.openai.com/api/docs/guides/agents/integrations-observability 抓取时间: 2026-07-21 16:26:50

在工作流结构清晰后，接下来的问题是哪些外部接口应该存在于 Agent 循环中，以及您将如何检查运行时实际发生的情况。

选择 SDK 中包含什么

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",
    }),
  ],
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
from agents import Agent, HostedMCPTool

agent = Agent(
    name="MCP assistant",
    instructions="Use the MCP tools to answer questions.",
    tools=[
        HostedMCPTool(
            tool_config={
                "type": "mcp",
                "server_label": "gitmcp",
                "server_url": "https://gitmcp.io/openai/codex",
                "require_approval": "never",
            }
        )
    ],
)

当您的应用程序应该直接连接到 MCP 服务器时，请使用本地传输。 连接本地 MCP 服务器 typescript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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();
}

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
28
29
import asyncio

from agents import Agent, Runner
from agents.mcp import MCPServerStdio


async def main() -> None:
    async with MCPServerStdio(
        name="Filesystem MCP Server",
        params={
            "command": "npx",
            "args": [
                "-y",
                "@modelcontextprotocol/server-filesystem",
                "./sample_files",
            ],
        },
    ) as server:
        agent = Agent(
            name="Filesystem assistant",
            instructions="Read files with the MCP tools before answering.",
            mcp_servers=[server],
        )
        result = await Runner.run(agent, "Read the files and list them.")
        print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

实际的划分是：

• 对于符合平台信任模型的公共远程服务器，使用 托管 MCP。
• 当您的运行时应该拥有连接、过滤或审批时，使用 本地或私有 MCP。

对于平台范围的概念、信任模型和产品支持故事，请将 MCP 和连接器 作为规范参考。

追踪

追踪内置于 Agents SDK 中，并且在正常的服务器端 SDK 路径中默认启用。每次运行都可以发出模型调用、工具调用、交接、防护措施和自定义跨度的结构化记录，您可以在 追踪仪表板 中检查这些记录。 默认追踪通常为您提供：

• 整体运行或工作流
• 每个模型调用
• 工具调用及其输出
• 交接和防护措施
• 您包裹在工作流周围的任何自定义跨度

如果您需要较少的追踪，请使用 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);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import asyncio

from agents import Agent, Runner, trace

agent = Agent(
    name="Joke generator",
    instructions="Tell funny jokes.",
)


async def main() -> None:
    with trace("Joke workflow"):
        first = await Runner.run(agent, "Tell me a joke")
        second = await Runner.run(
            agent,
            f"Rate this joke: {first.final_output}",
        )
        print(first.final_output)
        print(second.final_output)


if __name__ == "__main__":
    asyncio.run(main())

使用追踪完成两项工作：

• 调试一个工作流运行并了解发生了什么。
• 一旦您准备好系统地对行为进行评分时，将更高信号的示例输入 Agent 工作流评估。

后续步骤

一旦外部接口连接完成，请继续阅读涵盖功能设计、审查边界或评估的指南。 使用工具 了解托管工具、函数工具和 Agent 即工具如何与 MCP 配合使用。 防护措施和人工审核 在敏感功能周围添加审批或验证边界。 Agent 工作流评估 一旦行为稳定后，从一次性追踪转向可重复的评分。