ag2-telemetry

用途

ag2-telemetry 用于为 AG2 的 Agent 添加 OpenTelemetry 追踪。当用户希望查看每轮对话或每次调用的延迟分解、按操作归因 token 用量、把追踪推送到 Jaeger、Grafana Tempo、Datadog、Honeycomb、Langfuse 等后端，或用结构化 span 而非 print 语句端到端调试慢 Agent 时，可使用本技能。若只需要快速的标准输出调试，应改用 LoggingMiddleware（参见 ag2-middleware）。

安装

pip install "ag2[openai,tracing]"

这是必需步骤，应在交付代码前运行。若无法执行命令，需给出上述确切的 pip install 命令。

主要能力

快速上手示例

from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor, ConsoleSpanExporter

from ag2 import Agent
from ag2.config import OpenAIConfig
from ag2.middleware.builtin import TelemetryMiddleware

# 1. 配置 OpenTelemetry
resource = Resource.create({"service.name": "ag2-quickstart"})
tracer_provider = TracerProvider(resource=resource)
tracer_provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(tracer_provider)

# 2. 接入中间件
agent = Agent(
    "assistant",
    prompt="You are a helpful assistant.",
    config=OpenAIConfig(model="gpt-4o-mini"),
    middleware=[
        TelemetryMiddleware(
            tracer_provider=tracer_provider,
            agent_name="assistant",
        ),
    ],
)

# 3. 运行——span 自动发出
import asyncio
asyncio.run(agent.ask("What is the capital of France?"))

生产环境中，应将 ConsoleSpanExporter 换成 OTLPSpanExporter（或所用后端的导出器），并将 SimpleSpanProcessor 换成 BatchSpanProcessor。

Span 层级

每次 ask() 会产生一个根 span，其子 span 包括：

invoke_agent assistant
  ├── chat gpt-4o-mini              # LLM API 调用
  ├── execute_tool get_weather      # 工具执行
  ├── chat gpt-4o-mini              # 工具结果后的 LLM 调用
  └── await_human_input assistant   # 人工介入

Span 类型

每个 span 都带有 ag2.span.type 属性：

ag2.span.type	操作名	钩子
agent	invoke_agent	on_turn——完整轮次
llm	chat	on_llm_call——每次 LLM 调用
tool	execute_tool	on_tool_execution——每个工具
human_input	await_human_input	on_human_input——HITL

语义属性（GenAI semconv）

Span 携带标准 OpenTelemetry GenAI 属性：

属性	所属 Span	说明
gen_ai.operation.name	全部	invoke_agent / chat / execute_tool / await_human_input
gen_ai.agent.name	agent, human_input	Agent 名称
gen_ai.provider.name	agent, llm	自动检测（openai、anthropic 等）
gen_ai.request.model	agent, llm	例如 gpt-4o-mini
gen_ai.response.model	llm	从响应解析
gen_ai.response.finish_reasons	llm	例如 ["stop"]、["tool_calls"]
gen_ai.usage.input_tokens	llm	提示 token 数
gen_ai.usage.output_tokens	llm	补全 token 数
gen_ai.usage.cache_creation_input_tokens	llm	提示缓存写入（Anthropic）
gen_ai.usage.cache_read_input_tokens	llm	提示缓存读取（Anthropic、OpenAI、Gemini）
gen_ai.tool.name	tool	工具函数名
gen_ai.tool.call.id	tool	工具调用 ID
gen_ai.tool.type	tool	始终为 function

内容捕获（默认开启）

默认情况下，消息内容、工具参数与结果会写入 span。这对调试有用，但可能泄露敏感数据：

TelemetryMiddleware(
    tracer_provider=tracer_provider,
    agent_name="assistant",
    capture_content=False,   # 省略消息、工具参数、结果
)

开启时会出现以下额外属性：

属性	Span	内容
gen_ai.input.messages	llm	JSON 请求消息
gen_ai.output.messages	llm	JSON 响应消息
gen_ai.tool.call.arguments	tool	工具参数（JSON）
gen_ai.tool.call.result	tool	工具结果
ag2.human_input.prompt	human_input	展示给人工的提示
ag2.human_input.response	human_input	人工的响应

对于隐私敏感的后端（或任何遥测数据离开自有基础设施的场景），应设置 capture_content=False。

构造函数参数

参数	类型	默认值	说明
tracer_provider	TracerProvider \| None	全局 provider	OpenTelemetry TracerProvider
capture_content	bool	True	是否在 span 中包含消息/工具内容
agent_name	str \| None	"unknown"	用于 span 属性的 Agent 名称
provider_name	str \| None	None	提供方覆盖（未设置时自动检测）
model_name	str \| None	None	模型覆盖（未设置时自动检测）

使用方式

后端集成

TelemetryMiddleware 使用标准 OpenTelemetry，因此任何 OTLP 兼容后端均可使用：

Jaeger——OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")
Grafana Tempo——同样的 OTLP 导出器，指向 Tempo 网关
Langfuse、Honeycomb、Datadog——厂商专用导出器；Agent 侧配置完全相同

对于容器编排的栈，本仓库包含 tracing/ 目录，提供 otel-collector + Grafana Tempo 的 Docker-Compose 配置。

深入了解

website/docs/user-guide/telemetry.mdx——完整属性表、配置与示例。
tracing/——本地 otel-collector + Tempo + Grafana 的 Docker 配置。
其他同类中间件（日志、重试、历史限制）参见 ag2-middleware。

适用场景

查看每轮/每次调用的延迟分解。
按操作归因 token 用量。
将追踪推送到 Jaeger、Grafana Tempo、Datadog、Honeycomb、Langfuse 等。
用结构化 span 端到端调试慢 Agent。

限制与常见陷阱

生产环境使用 SimpleSpanProcessor + ConsoleSpanExporter：同步阻塞每次 span 发出。开发之外应使用 BatchSpanProcessor 和真实导出器（OTLP / Jaeger / 厂商）。
内容泄露到遥测：capture_content=True 是默认值。对于隐私敏感的提示（PII、凭据），应设置 capture_content=False 并审计后端保留的内容。
忘记 trace.set_tracer_provider(...)：没有它，传给中间件的 tracer_provider 本身没问题，但自动插桩的第三方库可能使用不同的 provider。
token 用量缺失：gen_ai.usage.* 需要提供方客户端在响应中暴露用量。流式提供方可能只在结束时发出用量；若看不到，请检查提供方的响应结构。
Span 层级不显示父子关系：导出器或后端可能需要启用 OTLP/HTTP 路径，而不仅是 OTLP/gRPC。两者都要检查。
与 AG2 Classic 追踪文档对比：语义属性格式相同，仅 Agent 插桩方法不同（AG2 Classic 使用 instrument_agent() / instrument_llm_wrapper() / instrument_pattern()；AG2 使用 TelemetryMiddleware）。