使用 OpenTelemetry 实现 AI Agent 可观测性
AI agent 并不只是调用一次模型并返回其响应。相反,它们编排整个工作流,涉及为 LLM 选择要使用的工具、评估护栏(guardrails)、在多次 LLM 调用之间进行路由,以及在多轮对话中管理上下文。这意味着单次用户请求可能产生数十个内部步骤,每一步都是潜在的故障点、延迟来源或意外成本。
AI agent 可观测性就是捕获这些执行流程的实践,使你能够理解 agent 做了什么、为何选择该路径,以及它的表现如何。在实践中,这意味着追踪一次 agent 运行的执行路径、捕获每一步的输入和输出,并跟踪成本、token 用量、延迟和错误率。
AI agent 追踪为 AI agent 可观测性奠定了基础。没有追踪,调试 AI agent 就变成了一场猜测游戏:试图猜出是哪个事件触发了 agent 工作流中的哪项决策,以及为什么。
为什么 AI agent 需要可观测性?
一个请求可能成功返回,但 agent 却给出了错误答案、在某个特定步骤上耗时过长,或触发了重复的 LLM 或工具调用。Agent 可观测性为工程师提供证据来调查这些问题,并比较不同运行之间的行为。
让我们更详细地看看其中一些问题。
LLM 的非确定性会在 agent 步骤间叠加放大
单次 LLM 调用本身就已经是非确定性的:相同的 prompt 在不同运行中可能产生不同的输出。Agent 会放大这一点,因为它们将多次 LLM 调用串联起来,其中一步的输出决定了下一步的输入。
这意味着方差并非只存在于某一个点上。相反,它会在整个工作流中叠加放大。第一步中略有不同的模型响应可能导致 agent 在第二步中选择完全不同的工具,进而改变传递给第三步的上下文,依此类推。如果不捕获完整的执行路径,重现某次特定的 agent 运行几乎是不可能的。
Agent 可能悄无声息地产生错误结果
传统软件也可能在不抛出错误的情况下返回错误结果。对于 agent 而言,这些故障更难被发现,因为每次运行可能走不同的路径:工作流在没有任何错误的情况下完成,但 agent 选错了工具、检索到了过时的上下文,或返回了一个自信却错误的响应。
没有可观测性,这些静默故障只有在用户投诉或下游系统消费了错误输出时才会暴露。追踪 agent 循环中的每一项决策——例如选择了哪个工具、当时有哪些可用上下文、模型实际返回了什么——是评估 agent 的“成功”运行是否在逻辑上真正正确的唯一可靠方法。
成本和延迟在设计上就是不可预测的
Agent 在运行时决定调用多少工具、进行多少次 LLM 往返。一个简单的用户查询可能只需一次 LLM 调用即可解决,而类似的查询可能根据 agent 的推理触发多次工具调用和模型调用。
这使得成本和延迟本质上不可预测。可观测性让工程师能够跨运行跟踪 token 用量、工具调用频率和每步延迟,从而尽早识别昂贵的模式。例如,如果两个不同定价层级的模型在给定工作负载上表现相当,工程师可以切换到更便宜的那个——但前提是他们拥有做出该比较的数据。
OpenTelemetry 如何实现 AI agent 可观测性?
OpenTelemetry(OTel)是一个 CNCF 毕业项目,用于对应用进行插桩,以厂商中立的格式输出遥测数据(主要是 traces、metrics 和 logs)。它之所以特别适合 agent 应用,是因为你的可见性可以超越 AI agent 本身,延伸到整个请求:用户调用了哪个 endpoint、运行了哪些 DB 查询、是否入队了任何后台任务、应用是否发起了任何下游 API 调用?

使用 OpenTelemetry 设置 AI agent 可观测性
前置条件
- Python 3.12 或更新版本。下载最新版本。
- 一个 SigNoz Cloud 账户,用于可视化遥测数据。
- 一个 OpenAI API key,用于运行该 agent。
- 一个 API 客户端,例如 Bruno 或 Postman,用于测试端点。
设置 SigNoz Cloud
SigNoz Cloud 是一个 OpenTelemetry 原生的可观测性平台,在单一界面中统一 traces、metrics 和 logs。
- 注册一个免费的 SigNoz Cloud 账户。
- 按照文档生成一个 ingestion key。
- 请准备好你的 workspace 区域(例如 us、in、eu)和 ingestion key,以便用于应用配置。
运行演示应用
克隆并进入演示应用目录:
git clone --filter=blob:none --sparse https://github.com/SigNoz/examples.git
git -C examples sparse-checkout set python/otel-ai-agent-observability-demo
cd examples/python/otel-ai-agent-observability-demo
创建并激活 Python 虚拟环境:
python3.12 -m venv .venv
source .venv/bin/activate
安装应用及 OpenTelemetry Python 依赖:
pip install -r requirements.txt
requirements.txt 文件固定了以下 OTel 包:
- opentelemetry-distro:提供一种便捷机制,用于配置 Python 自动埋点的一些更常见选项。
- opentelemetry-exporter-otlp:安装将遥测数据发送到任何 OpenTelemetry 兼容后端所需的 OTLP exporters。
- opentelemetry-instrumentation-genai-openai 和 opentelemetry-instrumentation-genai-openai-agents:来自专用 OpenTelemetry GenAI 仓库的现代 OpenAI Agents 和 OpenAI Python API 埋点包。
接下来,运行 opentelemetry-bootstrap 以检测广泛使用的 Python 库(例如 FastAPI Web 框架和 HTTPX 客户端库),并安装它们对应的埋点包:
opentelemetry-bootstrap --action=install
opentelemetry-bootstrap 目前默认会安装一个已弃用的 opentelemetry-instrumentation-openai-v2 包。不过,由于我们的 requirements.txt 显式安装了现代的 opentelemetry-instrumentation-genai-* 库,OpenTelemetry 在运行时会解析到更新的包。
你可以安全地保留 v2 包不动,或者将其卸载。
使用 opentelemetry-instrument 启动应用,以自动对我们的应用(包括 AI agent 工作流)进行埋点:
OPENAI_API_KEY="<your-openai-api-key>" \
OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<your-region>.signoz.cloud:443" \
OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>" \
OTEL_SERVICE_NAME="otel-ai-agent-observability-demo" \
OTEL_RESOURCE_ATTRIBUTES="service.version=1.0.0,deployment.environment=dev" \
OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf" \
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=span_only \
opentelemetry-instrument fastapi run --port 8085 --workers 1
以下是这些 OpenTelemetry 环境变量所配置的内容:
- OTEL_SERVICE_NAME="otel-ai-agent-observability-demo":在 SigNoz Cloud 中唯一标识该应用。
- OTEL_RESOURCE_ATTRIBUTES:将元数据(版本 1.0.0,环境 dev)附加到所有导出的遥测数据上。这用于在 OpenTelemetry 后端中组织和筛选遥测数据。
- OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=span_only:将模型提示、补全和工具定义作为 span 属性捕获到 LLM 模型 span 上。
应用日志由 opentelemetry-bootstrap 安装的日志插桩自动与追踪关联。这消除了设置 OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED 环境变量的需要,该变量在较新的 OpenTelemetry 版本中已被弃用。
FastAPI 服务器在端口 8085 上启动。调用 / 会返回一个快速的健康检查响应:
(.venv) ❯ curl "http://127.0.0.1:8085/"
{"message":"OpenTelemetry NBA agent demo is running"}
演示现在正在运行。在探索智能体代码之前,让我们先看看用于捕获 AI 智能体工作流的 OpenTelemetry 约定和插桩包。
理解 OpenTelemetry 不断演进的 GenAI 约定
虽然早期的插桩讨论仅聚焦于「LLM 追踪」,OpenTelemetry 在生成式 AI(GenAI)这一更宽泛的范畴下标准化 AI 遥测,使用以 gen_ai.* 为前缀的语义约定。
由于 GenAI 模式和智能体框架的演进速度远快于传统 HTTP 或数据库库,OpenTelemetry 创建了一个专门的仓库 open-telemetry/opentelemetry-python-genai,让维护者能够独立开发和发布这些库。
此次迁移引入了更清晰、按范围拆分的架构:
- opentelemetry.instrumentation.genai.openai_agents:对智能体编排框架进行插桩,为工作流执行(invoke_workflow)和智能体路由(invoke_agent)发出 span。
- opentelemetry.instrumentation.genai.openai:一个配套包,对底层模型调用(chat)进行插桩,捕获 token 用量(gen_ai.usage.input_tokens、gen_ai.usage.output_tokens)、模型参数和提示词上下文。
早期的 Agents 插桩将工作流追踪和模型调用追踪合并在单个包中。
此外,由于 opentelemetry-bootstrap 尚未将这些专门的 GenAI 包加入其自动发现列表,你必须通过 requirements.txt 或 pyproject.toml 文件单独安装并跟踪它们。

各 GenAI 插桩包的覆盖范围不尽相同,尤其是对于 handoffs 和 guardrails 这类智能体特性。建议你显式固定插桩包的版本,并在升级依赖时查看它们的变更日志。
NBA 智能体如何使用工具、guardrails 和会话
现在我们已经了解了 OpenTelemetry 如何将智能体编排与模型调用分离,接下来看看 NBA 智能体工作流背后的代码。如果你想直接跳到生成和检查追踪,可以跳到下一节。
FastAPI 提供我们的 HTTP 端点,OpenAI Agents SDK 管理智能体循环,OpenAI Python API 库处理底层模型调用。这种分离正是我们同时插桩 Agents SDK 和 API 库的原因:一个捕获工作流,另一个捕获每次模型调用。
核心智能体设置
我们的 Web 应用暴露了一个 NBA Reporter 智能体,它回答 NBA 相关主题的问题(例如一般新闻或总决赛),执行网络研究,计算球队胜率,并通过服务器管理的会话持久化在多轮对话之间保留对话历史。
agent_service.py 文件定义了智能体配置以及我们的 FastAPI 端点使用的执行函数。
我们使用系统提示词、工具、输入 guardrails 和模型选择来初始化智能体。应用使用 gpt-6-luna(app/config.py 中的 OPENAI_MODEL = "gpt-6-luna"),它提供稳定的多轮推理和工具格式化:
文章标题:OpenTelemetry 与 AI 智能体的可观测性
正文:
NBA_AGENT = Agent(
name="NBA_Reporter",
instructions=NBA_INTERACTIVE_PROMPT,
tools=[WebSearchTool(), calculate_win_percentage],
input_guardrails=[nba_content_guardrail],
model=OPENAI_MODEL,
)
calculate_win_percentage 函数工具为智能体提供了一种确定性的方式来计算并显示球队胜率,而无需担心出现算术幻觉的风险:
@function_tool
def calculate_win_percentage(wins: int, losses: int) -> str:
"""Calculates the winning percentage for an NBA team given their wins and losses."""
total_games = wins + losses
if total_games == 0:
return ".000"
return f"{wins / total_games:.3f}".lstrip("0")
为防止误用或偏离主题的查询,我们定义了一个输入护栏。当用户提示不匹配相关的篮球关键词时,该函数返回一个 tripwire_triggered=True 的 GuardrailFunctionOutput:
@input_guardrail()
def nba_content_guardrail(
context: RunContextWrapper[None],
agent: Agent,
input_data: str | list,
) -> GuardrailFunctionOutput:
"""Ensures the user query is relevant to basketball/NBA."""
keywords = [
"nba",
"basketball",
"player",
... # truncated for brevity
]
# extract the last user message from chat history
if isinstance(input_data, list):
latest_user_message = next(
(
item.get("content", "")
for item in reversed(input_data)
if isinstance(item, dict) and item.get("role") == "user"
),
"",
)
input_query = latest_user_message
else:
input_query = input_data
input_query = input_query.lower()
is_relevant = any(keyword in input_query for keyword in keywords)
if len(input_query) < 5 or is_relevant:
return GuardrailFunctionOutput(tripwire_triggered=False, output_info=None)
return GuardrailFunctionOutput(
tripwire_triggered=True,
output_info={
"reason": "The request is off-topic. Please ask questions relevant to NBA or basketball."
},
)
将 tripwire_triggered=True 会指示 Agents SDK 中止执行并抛出 InputGuardrailTripwireTriggered 异常。我们在 FastAPI 异常处理器中拦截该异常,在返回 HTTP 400 响应之前,将异常事件直接记录到当前活跃的 OpenTelemetry span 上:
@app.exception_handler(InputGuardrailTripwireTriggered)
async def handle_guardrail_block(
request: Request,
exc: InputGuardrailTripwireTriggered,
) -> JSONResponse:
guardrail_msg = exc.guardrail_result.output.output_info
span = trace.get_current_span()
span.record_exception(exc)
return JSONResponse(status_code=400, content={"detail": guardrail_msg})
跨轮次管理会话上下文
run_agent_turn 函数完善了我们的实现。智能体使用 OpenAIConversationsSession 对象来持久化并收集跨轮次的对话上下文。
如果没有传入 session_id,会话对象会触发创建一个新的对话会话。在后续请求中,用户可以附带此 ID,以确保智能体掌握迄今为止的对话上下文。
def run_agent_turn(
topic: str,
user_message: str | None,
session_id: str | None,
) -> dict:
nba_topic = _validate_topic(topic)
prompt = build_nba_turn_prompt(nba_topic, user_message)
# if no session ID was given, the sdk internally creates a session_id during the turn
# subsequent calls which pass the ID maintain the conversation context
session = OpenAIConversationsSession(conversation_id=session_id)
result = Runner.run_sync(NBA_AGENT, prompt, session=session)
message = sanitize_agent_message((result.final_output or "").strip())
... # truncated for brevity
return {
"topic": topic,
"session_id": session.session_id,
"message": message,
"model": OPENAI_MODEL,
"usage": usage,
}
使用 OpenTelemetry 可视化 AI 智能体工作流
让我们向智能体发送几个请求以生成追踪,然后检查工具调用、对话历史和护栏失败如何在 SigNoz Cloud 中呈现。
与智能体交互
让我们先向 NBA Reporter 智能体询问一个关于 Lakers 在 2025-26 赛季胜率的问题,以及 LeBron 和他在球队的未来。这个查询提出了三个不同的问题,为我们在下一轮提出后续问题做好了准备,而关于胜率的提问应触发 calculate_win_percentage 工具。

智能体首先
文章标题:OpenTelemetry 与 AI 智能体的可观测性
正文:
POST /agent/turn [fastapi] Server 26.00s
├─ POST /agent/turn http receive [asgi] Internal
├─ POST /v1/conversations [httpx] Client
├─ GET /v1/conversations/{id}/items?order=asc [httpx] Client
├─ invoke_workflow Agent workflow [genai.openai_agents] Internal 24.41s
│ ├─ POST /v1/conversations/{id}/items [httpx] Client
│ └─ invoke_agent NBA_Reporter [genai.openai_agents] Internal 23.71s
│ ├─ chat gpt-6-luna [genai.openai] Client 3.94s
│ │ └─ POST /v1/responses [httpx] Client 3.84s
│ ├─ execute_tool calculate_win_percentage [genai.openai_agents] Internal
│ ├─ execute_tool calculate_win_percentage [genai.openai_agents] Internal
│ ├─ POST /v1/conversations/{id}/items [httpx] Client
│ ├─ chat gpt-6-luna [genai.openai] Client 18.21s
│ │ └─ POST /v1/responses [httpx] Client 17.90s
│ └─ POST /v1/conversations/{id}/items [httpx] Client
├─ POST /v1/traces/ingest ×3 [httpx] Client
└─ POST /agent/turn http send ×2 [asgi] Internal
这条链路突出展示了智能体循环的几个关键结构细节:
- 全栈请求生命周期:链路始于 FastAPI 边界(POST /agent/turn)。在智能体工作流执行之前,子级 HTTP span 显示会话层正在获取对话历史(GET /v1/conversations/{id}/items)。
- 专属智能体作用域:智能体编排框架通过 invoke_workflow 和 invoke_agent span 捕获在 opentelemetry.instrumentation.genai.openai_agents 之下,界定了智能体的决策边界。
- 迭代式工具执行循环:链路并非只记录单次模型补全,而是描绘了完整的多步循环:初始模型调用(chat gpt-6-luna,3.94s):模型处理该轮次,识别出胜率查询,并发出工具调用指令。工具执行(execute_tool calculate_win_percentage ×2):智能体循环执行我们的工具,随后是一个 HTTP span,将工具结果持久化到对话会话中。最终综合调用(chat gpt-6-luna,18.21s):模型接收工具输出,生成面向用户的完整回复。
- 初始模型调用(chat gpt-6-luna,3.94s):模型处理该轮次,识别出胜率查询,并发出工具调用指令。
- 工具执行(execute_tool calculate_win_percentage ×2):智能体循环执行我们的工具,随后是一个 HTTP span,将工具结果持久化到对话会话中。
- 最终综合调用(chat gpt-6-luna,18.21s):模型接收工具输出,生成面向用户的完整回复。
- 标准化 GenAI 属性:选中任一 chat gpt-6-luna span,即可看到以下属性:提供商与模型:gen_ai.provider.name、gen_ai.request.model 和 gen_ai.response.model。操作与结果:gen_ai.operation.name 和 gen_ai.response.finish_reasons。Token 用量:gen_ai.usage.input_tokens 和 gen_ai.usage.output_tokens。
- 提供商与模型:gen_ai.provider.name、gen_ai.request.model 和 gen_ai.response.model。
- 操作与结果:gen_ai.operation.name 和 gen_ai.response.finish_reasons。
- Token 用量:gen_ai.usage.input_tokens 和 gen_ai.usage.output_tokens。
你一定注意到了重复的 calculate_win_percentage 工具调用。此前几次使用相同提示词的运行都只触发了一次工具调用,考虑到工作量微不足道,这也在意料之中。而在本次运行中,智能体循环触发了第二次工具调用,其输入参数道出了缘由:gen_ai.tool.call.arguments: "{"wins":0,"losses":0}"。
这次工具调用使用了技术上有效但不切实际的输入,并得到了同样不切实际的结果:gen_ai.tool.call.result:".000"。尽管这没有影响最终结果,但这进一步表明 AI agent 的非确定性本质,并凸显了为什么我们需要对 AI 工作负载进行可观测性。
检查消息内容与隐私控制
由于我们设置了 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=span_only,插桩会将 gen_ai.input.messages、gen_ai.output.messages、gen_ai.system_instructions 和 gen_ai.tool.definitions 直接填充为 span 属性。这使工程师能够在调试期间检查每一轮的确切提示、系统指令和模型补全内容。
在包含敏感数据或需严格遵循 PII 合规要求的环境中,可以通过设置以下内容来完全关闭提示内容捕获:
export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=no_content
这样会保留模型时序、token 计数和 span 层级,同时从导出的遥测数据中省略原始消息负载以及输入/输出值。
在 trace 中处理护栏失败
当偏离主题的查询触发输入护栏 tripwire 时,agent 会在调用模型之前停止执行。
在我们的 FastAPI 异常处理程序中,拦截 InputGuardrailTripwireTriggered 并调用 span.record_exception(exc),会将异常事件捕获到根 span 上。

监控 agent 性能与指标
虽然单条 trace 可以让你调试特定的 agent 执行,但理解生产环境行为需要跨轮次、模型和会话的聚合指标。
OpenTelemetry GenAI 插桩会自动发出标准指标——例如 gen_ai.client.operation.duration 和 token 使用量计数器——并与你的 trace 一同输出。SigNoz Cloud 在专用的 AI Observability 界面中捕获这些遥测数据,该界面将运行健康状况、延迟百分位数和 agent 循环行为聚合到一个统一视图中。

高层 KPI 与上下文下钻
顶层概览展示了 agent 基础设施中的高层运行指标:
- 总成本与 token 数量:跟踪各服务的支出和 token 消耗,以帮助识别高成本工作负载。
- 延迟百分位数与 TTFT:跟踪流式响应的尾部延迟和首 token 时间(TTFT)。
- LLM 调用量与错误率:监控各服务的流量峰值和模型失败率。
使用仪表板的 trace 和日志下钻功能,跟踪产生这些数字的对应遥测数据。按模型名称或服务等属性细分各项指标,然后将这些细分结果与仪表板级过滤器结合,以回答如下问题:
- 在给定时间范围内,某个特定服务中哪个模型让你花费最多?
- 随着时间推移,staging 和生产环境之间的 LLM 延迟如何比较?你团队的测试请求与客户请求之间的差异能否解释这一差距?
- 你团队的测试请求与客户请求之间的差异能否解释这一差距?
评估模型延迟与响应时间
多轮推理和工具选择会在 agent 交互中引入可变延迟。按模型划分的 LLM 延迟表格和时间序列图会跨百分位数跟踪执行性能:
- 百分位数细分:按模型比较 p50、p90 和 p95 延迟,以查看慢响应影响的是典型请求还是仅影响尾部请求。
- 交互式时间序列:深入查看延迟峰值附近的追踪,以检查在模型调用和工具执行上花费了多少时间。
使用结束原因诊断代理循环
结束原因面板显示模型调用如何结束:
- ["stop"]:表示模型完成了对用户的最终响应生成。
- ["tool_calls"]:表示模型请求一次或多次工具执行,促使代理循环执行工具并开始另一轮。
["tool_calls"] 相对于 ["stop"] 的峰值可能是递归代理行为、重复工具重试或代理难以综合出答案的信号。
工具调用性能和 span 分布
工具调用部分汇总代理调用的工具产生的遥测数据:
- 工具调用速率和错误跟踪:显示每个工具运行和失败的频率,有助于识别重复调用或不可靠的工具。
- 工具持续时间:显示哪些工具对代理运行贡献了最多延迟。
- 顶级 span 名称:比较代理、模型和工具的 span 计数。意外差异,例如代理 span 与 LLM span 之间的巨大差距,可以指导进一步的追踪检查。
结论
随着 AI 应用从简单的模型提示演变为自主的多轮代理,传统调试方法已力不从心。代理工作流是非确定性的,跨越多个工具调用,并依赖可能悄然降低质量的动态上下文。
使用 OpenTelemetry 为代理添加插桩,可在每一层提供端到端可见性:
- 完整请求上下文:在单个追踪中关联传入的 HTTP 请求、会话存储查找、代理决策循环和下游 API 调用。
- 供应商中立的 GenAI 标准:利用官方 OpenTelemetry 语义约定(gen_ai.*)来标准化指标、属性和 span 结构,而无需专有锁定。
- SigNoz Cloud 中的统一调试:在一个界面中结合追踪、指标和日志,以诊断幻觉工具调用、识别延迟瓶颈,并治理生产运行中的 token 开销。
如果你正在构建代理应用,请注册 SigNoz Cloud 免费试用,立即开始使用 OpenTelemetry 观察你的 AI 代理。