使用 OpenTelemetry 监控 OpenAI Agents SDK：跟踪

OpenAI Agents SDK 本身就自带追踪功能。每次调用 Runner.run() 都会生成一条 trace，其中 agent 调用、模型请求、工具执行、任务移交和 guardrail 校验都会形成嵌套的 span。默认情况下，这些 span 会发送到 OpenAI 自家的 Traces 仪表盘。

本指南将这套内置追踪机制桥接到 OpenTelemetry，使相同的 span 能以标准 gen_ai.* 遥测数据的形式落入 SigNoz，并与周围的 Web 处理器、数据库查询及下游服务归入同一条 trace 中。

什么是 OpenAI Agents SDK 可观测性？

OpenAI Agents SDK 的可观测性指的是从 agent 应用中采集 trace，从而清晰掌握每次运行的细节：哪些 agent 被执行、调用了哪些模型、消耗了多少 token、触发了哪些工具，以及在哪里发生故障。

借助 SigNoz 完整的 OpenAI Agents SDK 可观测性能力，你可以端到端追踪完整的 agent 运行流程，将 token 开销归因到具体模型，监测死循环等未终止逻辑中的工具调用频率，并将 agent 故障与应用程序的其他部分关联起来。

前提条件

• 一个 SigNoz Cloud 账号和一个 数据摄入密钥
• Python 3.9 或更高版本
• 一个 OpenAI API 密钥
• 基于 openai-agents SDK 构建的应用程序

使用 OpenTelemetry 监控 OpenAI Agents SDK

该 instrumentation 是一种桥接机制，而非 monkey patch。它在 Agents SDK 自身的 trace provider 上注册一个 TracingProcessor，将每个 SDK span 转换为 OpenTelemetry span，随后通过 OTLP 协议导出。

无代码（推荐）代码

无代码自动 instrumentation 适合快速配置且代码改动最小化的场景，特别适用于那些你不希望修改的现有 agent 应用。

第 1 步：在 Python 环境中安装所需依赖包。

复制

pip install \
  openai-agents \
  opentelemetry-distro \
  opentelemetry-exporter-otlp \
  opentelemetry-instrumentation-openai-agents-v2

opentelemetry-distro 负责在启动时配置 tracer provider 和 exporter。缺少它，opentelemetry-instrument 虽然能加载 instrumentation，但不会导出任何数据。

第 2 步：添加自动 instrumentation。

Copy

opentelemetry-bootstrap --action=install

第 3 步：运行一个示例。应用代码中无需编写任何 OpenTelemetry 代码。

Copy

import asyncio
from agents import Agent, Runner, function_tool
 
 
@function_tool
def get_weather(city: str) -> str:
    """Return the current weather for a city."""
    return {"tokyo": "18C, light rain", "paris": "24C, clear"}.get(city.lower(), "unknown")
 
 
agent = Agent(
    name="weather-assistant",
    instructions="You are a concise weather assistant. Answer in one sentence.",
    model="gpt-4o-mini",
    tools=[get_weather],
)
 
 
async def main():
    result = await Runner.run(agent, "What's the weather in Tokyo?")
    print(result.final_output)
 
 
asyncio.run(main())

请先设置你的 OpenAI API key

运行这段代码前，请先从 OpenAI dashboard 获取你的 key，并通过环境变量导出 OPENAI_API_KEY。

第 4 步：使用自动插桩运行你的应用。

Copy

OTEL_RESOURCE_ATTRIBUTES="service.name=<service_name>" \
OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443" \
OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>" \
OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf" \
opentelemetry-instrument python main.py

请核对以下各项取值：

• <service_name>：你的应用在 SigNoz 中显示的名称，例如 support-agents。
• <region>：你的 SigNoz Cloud 区域。
• <your-ingestion-key>：你的 SigNoz ingestion key。

使用自托管 SigNoz？

大部分步骤都相同。只需按 Cloud to Self-Hosted 文档调整 endpoint，并去掉 ingestion key 请求头即可。

代码方式让你能掌控零代码方式做不到的两件事：span 发往何处，以及是否生成 SDK 的 task 和 turn span。

第 1 步：在 Python 环境中安装所需的包。

Copy

pip install \
  openai-agents \
  opentelemetry-sdk \
  opentelemetry-exporter-otlp-proto-http \
  opentelemetry-instrumentation-openai-agents-v2

第二步：通过环境变量配置导出器。

Copy

export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443"
export OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OPENAI_API_KEY="<your-openai-api-key>"

请核对以下变量值：

• <region>：你的 SigNoz Cloud 区域。
• <your-ingestion-key>：你的 SigNoz 数据摄入密钥。
• <your-openai-api-key>：来自 OpenAI 仪表盘 的 API 密钥。

第三步：在首次运行 Agent 之前完成埋点接入。

Copy

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.instrumentation.openai_agents import OpenAIAgentsInstrumentor
 
from agents import set_trace_processors
 
resource = Resource.create({
    "service.name": "<service_name>",
    "deployment.environment": "production",
})
 
provider = TracerProvider(resource=resource)
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
trace.set_tracer_provider(provider)
 
# 仅将 Trace 发送到 SigNoz，同时避免重复发送到 OpenAI 的 Traces 看板。
set_trace_processors([])
 
OpenAIAgentsInstrumentor().instrument(tracer_provider=provider)

为什么要设置 set_trace_processors([])

该埋点工具会将处理器追加到已注册的处理器列表中。如果没有这行代码，SDK 默认导出器将保持激活状态，导致每条 Span 同时发送到 OpenAI 的 Traces 看板和 SigNoz。

不要试图通过设置 OPENAI_AGENTS_DISABLE_TRACING=1 来阻止上述行为。OpenTelemetry 桥接依赖于 SDK 自身的追踪功能，禁用追踪会同时关闭 SigNoz 的导出，导致你最终看不到任何 Span 数据。

步骤 4：运行你的 agent。

Copy

import asyncio
from agents import Agent, RunConfig, Runner, function_tool
 
 
@function_tool
def get_weather(city: str) -> str:
    """Return the current weather for a city."""
    return {"tokyo": "18C, light rain", "paris": "24C, clear"}.get(city.lower(), "unknown")
 
 
agent = Agent(
    name="weather-assistant",
    instructions="You are a concise weather assistant. Answer in one sentence.",
    model="gpt-4o-mini",
    tools=[get_weather],
)
 
run_config = RunConfig(tracing={"include_task_and_turn_spans": False})
 
 
async def main():
    result = await Runner.run(agent, "What's the weather in Tokyo?", run_config=run_config)
    print(result.final_output)
 
    provider.force_flush()
    provider.shutdown()
 
 
asyncio.run(main())

两个值得注意的设置

include_task_and_turn_spans: False 会关闭 SDK 的 task 和 turn span。该埋点方案只映射了 SDK 八种 span 类型中的六种，不包含 TaskSpanData 和 TurnSpanData，所以如果保留这个开关，trace 树的每一层都会多出一个名为 unknown 的 span。等埋点方案支持后再开启即可。

退出前调用 force_flush() 可以把缓冲的 span 发送出去。否则短生命周期的脚本会在批量发送间隔结束前就退出，导致 span 丢失。

使用自托管的 SigNoz？

大部分步骤完全相同。只需按照 Cloud to Self-Hosted 的说明修改 endpoint 并去掉 ingestion key 请求头即可。

每次运行都会产生携带 gen_ai.operation.name、gen_ai.request.model、gen_ai.usage.input_tokens 和 gen_ai.usage.output_tokens 的 span。稍等几秒，它们就会出现在 SigNoz 中。

在 SigNoz 中查看 OpenAI Agents SDK 的 Trace

打开 Traces explorer，按你的 service.name 过滤。每次 agent 运行都会显示为一个 Agent workflow 根 span，其下嵌套着 invoke_agent、chat 和 execute_tool 等 span。

点击根 Span 即可展开完整运行轨迹。瀑布图展示了 Agent 回合、其中的模型调用以及每次工具执行，右侧列出了 gen_ai.* 属性。

Agent 运行生成的 Span 树结构如下所示：

Copy

Agent workflow                 (Server, root)   one per Runner.run()
└─ invoke_agent <agent>        (Client)         carries the real agent name
   ├─ chat <model>             (Client)         carries the token counts
   ├─ execute_tool <tool>      (Internal)
   ├─ agent_handoff            (Internal)
   └─ guardrail_check          (Internal)

在编写查询前，有两处细节值得注意。Token 计数仅出现在 chat Span 中。真实的 Agent 名称仅出现在 invoke_agent Span 中，因为在 chat、tool、handoff 和 guardrail Span 上，gen_ai.agent.name 的值是默认字符串 OpenAI Agent。

在 AI Observability 中查看

AI Observability 展示了 OpenAI Agents SDK 中 Agent 发起的 LLM 调用的成本、Token 用量、延迟和错误。在 SigNoz 中，打开 AI Observability，并在 service_name 筛选器中选择你的服务。

若要查询单个 Trace，请打开