Agent

AG2 ships a TelemetryMiddleware that emits OpenTelemetry spans for a single agent's work — its turns, LLM calls, tool executions, and human-in-the-loop interactions.

The middleware follows the OpenTelemetry GenAI Semantic Conventions, so traces can be exported to any compatible backend — Jaeger, Grafana Tempo, Datadog, Honeycomb, Langfuse, and others.

Tip

To trace the interactions between agents in a network — the hub's dispatch, channels, agent lifecycles, and tasks — see Network Telemetry. The two compose: an agent's invoke_agent span links back to the network envelope that triggered it.

Installation

pip install "ag2[openai,tracing]"

Quick Start

Trace Hierarchy

Each ask() call produces a root span with child spans for LLM calls, tool executions, and human input:

invoke_agent assistant
  |-- chat gpt-4o-mini              # LLM API call
  |-- execute_tool get_weather      # tool execution
  |-- chat gpt-4o-mini              # LLM call after tool result
  +-- await_human_input assistant   # human-in-the-loop

Span Types

Every span includes an ag2.span.type attribute:

Semantic Attributes

Spans carry standard OpenTelemetry GenAI attributes:

Content Capture

By default, message content, tool arguments, and results are included in spans. To disable content capture for privacy-sensitive environments:

When content capture is enabled (the default), spans include these additional attributes:

Warning

With capture_content=True, message content, tool arguments, and human input will appear in your tracing backend. Ensure your backend has appropriate access controls.

Custom Span Attributes

Use span_attributes to stamp custom key-value pairs onto spans the middleware emits. This is useful for routing or filtering traces by tenant, environment, deployment, or any other label your backend supports. Every span will carry these attributes.

Tip

This is the right place to add tenant or organization identifiers when your tracing backend filters traces by span-level labels (for example, Google Cloud Trace label filters or Datadog tags).

Note

If a key in span_attributes collides with an intrinsic attribute set by the middleware (such as ag2.span.type or gen_ai.usage.input_tokens), the middleware's value always wins.

Configuration

TelemetryMiddleware accepts:

Tool Execution Example

Backend Integration

Since TelemetryMiddleware emits standard OpenTelemetry spans, any OTLP-compatible backend works — Grafana Tempo, Jaeger, Datadog, Honeycomb, Langfuse, and others. Swap the ConsoleSpanExporter from the Quick Start above for an OTLPSpanExporter pointed at your backend (or a local OpenTelemetry Collector); nothing else about the instrumentation changes.