traceAI-ag2-classic

Send AG2 Classic traces to Future AGI. AG2 Classic is the autogen distribution at 0.14.x, imported as autogen, from ag2ai/ag2classic. It ships its own OpenTelemetry instrumentation, autogen.opentelemetry. This package turns that on against a Future AGI tracer provider and maps its span attributes to Future AGI conventions. Alpha. Validated against fixtures and a loopback fake model, and re-verified 2026-10-16 end to end against a local Future AGI stack with a real model (autogen 0.14.1 and 0.14.0).

Supported: autogen 0.14.0 and 0.14.1. Upstream ag2ai/ag2classic at 86fa5ccb3f9424cee87edb4a9ea58f191ea958ba, Apache-2.0, copyright AG2ai. autogen is a normal dependency (>=0.14.0,<0.15); it is never vendored.

Note on 0.14.0: PyPI autogen==0.14.0 is a small alias whose only requirement is ag2==0.14.0, and the autogen module is shipped by that ag2 0.14.0 distribution. Its autogen/opentelemetry tree is identical to 0.14.1's, so the version guard accepts exactly that pairing. autogen==0.14.1 ships the module itself and installs no ag2. ag2 1.x ships only an ag2 module.

Install

pip install traceAI-ag2-classic "autogen[openai]"

traceAI-ag2-classic pins autogen to >=0.14.0,<0.15. Plain autogen installs no model client; the openai extra adds the OpenAI client the quick start below needs (without it, creating an agent with an llm_config raises ImportError: ... 'openai' is not installed). For another provider, use its extra instead or as well, for example "autogen[anthropic]" or "autogen[gemini]".

autogen[openai,tracing] also works. The tracing extra adds opentelemetry-sdk and the OTLP gRPC exporter; this package never constructs that exporter.

export FI_API_KEY="YOUR_API_KEY"
export FI_SECRET_KEY="YOUR_SECRET_KEY"
export FI_PROJECT_NAME="my-chatbot"

Set up

from autogen import ConversableAgent
from fi_instrumentation import register
from fi_instrumentation.fi_types import ProjectType
from traceai_ag2_classic import setup

trace_provider = register(
    project_type=ProjectType.OBSERVE,
    project_name="my-chatbot",
)

assistant = ConversableAgent("assistant", llm_config={"config_list": [{"model": "gpt-4o-mini"}]})
user = ConversableAgent("user", llm_config=False, human_input_mode="NEVER")

tracing = setup(tracer_provider=trace_provider, agents=[assistant, user])
user.initiate_chat(assistant, message="Hello", max_turns=2)

trace_provider.force_flush()  # short scripts: flush before exit

Upstream instruments agents per instance, so pass every agent you want traced, or call tracing.instrument_agent(agent) for agents created later. Pass a GroupChatManager and its group chat members and speaker selection are instrumented too. Pass group patterns with patterns=[...] or tracing.instrument_pattern(pattern). tracing.instrument_a2a_server(server) is available only when upstream exports it (the autogen[a2a] extra); it is never called unless you ask.

setup():

1. Checks that autogen is AG2 Classic 0.14.x. It raises AG2ClassicCompatibilityError, naming the packages above, when autogen is missing (for example only ag2 1.x or Microsoft AutoGen is installed), when the version is not 0.14.x, when autogen.opentelemetry is missing, or when the autogen module comes from pyautogen or from ag2 outside the 0.14.0 alias pairing.
2. Puts AG2ClassicSpanProcessor first on the provider you pass, ahead of the Future AGI exporter.
3. Calls upstream instrument_llm_wrapper(capture_messages=...) (on unless every content side is hidden), then instrument_agent and instrument_pattern for what you pass. If one of those raises (for example a non-agent in agents=), setup() restores OpenAIWrapper.create and re-raises.

It never creates a provider, never sets the global provider, and never adds an exporter. One provider, the one register() returned. HTTP to the collector is the default; pass transport=Transport.GRPC (from fi_instrumentation.otel) to register() for gRPC. Do not also install the [tracing] extra's gRPC exporter as a global provider, or spans are duplicated.

tracing.uninstrument() restores OpenAIWrapper.create, so no new LLM spans. If another library wrapped OpenAIWrapper.create after setup(), that wrapper is left in place and a WARNING is logged; call uninstrument() again once it is removed. Agents stay instrumented; upstream has no per-agent undo. The processor stays on the provider, so spans from those agents still have content removed and aggregate usage moved off non-LLM spans. It is shared by every handle on that provider and shuts down with trace_provider.shutdown().

Conformance

Every row was read from autogen/opentelemetry/instrumentators/ at 0.14.1. LLM, agent, tool, conversation, group-chat speaker selection, pattern and initiate_chats spans are exercised by real autogen runs against a loopback fake model in tests/; code execution, human input and remote-agent spans are covered by mapping unit tests only.

Limits

• To tell a nested chat from the outermost one, AG2ClassicSpanProcessor tracks every live span on the provider (AG2 or not) and frees each entry when its span ends. Tracking caps at 10000 live spans. The nested-session split (an inner chat getting its own session.id) returns only if that many spans leak (start and never end) or run concurrently on the provider; spans started past the cap are not tracked. Upstream ends every span it starts (with tracer.start_as_current_span(...)), so a leak needs other code on the same provider.

Privacy

Content follows the traceAI TraceConfig convention, like every traceAI instrumentor: message bodies, tool arguments and results are exported by default, and hidden with the standard variables (no package-specific switch):

export FI_HIDE_INPUTS=true        # input side: messages in, tool arguments, human prompt
export FI_HIDE_OUTPUTS=true       # output side: messages out, tool results, code output, chat summaries
# also honoured: FI_HIDE_INPUT_MESSAGES, FI_HIDE_OUTPUT_MESSAGES, FI_HIDE_INPUT_TEXT, FI_HIDE_OUTPUT_TEXT

or in code, setup(..., config=TraceConfig(hide_inputs=True, hide_outputs=True)) (from fi_instrumentation import TraceConfig). setup(..., capture_content=False) hides both sides and capture_content=True keeps both; either overrides config.

Upstream has a content flag only on instrument_llm_wrapper (capture_messages). Its agent, conversation, tool, human-input and code-execution spans always record message bodies, tool arguments and results, the human prompt and answer, code output and chat summaries. This package removes the keys of a hidden side before export. Input side: gen_ai.input.messages, gen_ai.tool.call.arguments, ag2.human_input.prompt and input.value. Output side: gen_ai.output.messages, gen_ai.tool.call.result, ag2.human_input.response, ag2.code_execution.output, ag2.chats.summaries and output.value. That is stricter than upstream. Kept content is lifted into input.value / output.value. Note that a conversation's output messages carry the whole chat history, so the prompt also appears there unless FI_HIDE_OUTPUTS is set.

Never exported in either mode: local paths, user names, host names, e-mail addresses and stack traces (spans carry the exception class in error.type and OpenTelemetry's status; checked on a real run). Exception messages from the model provider or your tool do appear in the span status text, as with any OpenTelemetry instrumentation; hide them by not putting secrets in exception messages.

The filtering lives in AG2ClassicSpanProcessor, which must run before any exporting processor. setup() keeps it first on the provider:

• trace_provider.add_span_processor(...) after setup(): Future AGI's provider shuts down and removes every processor on the first such call after register() (fi_instrumentation/otel.py:336-339), this one included. setup() wraps that method on your provider instance, so after the call this processor is put back first and re-enabled. Your processor sees filtered spans.
• tracing.uninstrument() leaves the processor in place, because agents instrumented earlier keep emitting spans.
• Editing _active_span_processor._span_processors yourself, or shutting the processor down without going through trace_provider.add_span_processor, bypasses this; call setup() again to put the processor back first and re-enable it.
• A provider built with the SDK's ConcurrentMultiSpanProcessor runs every processor's on_end in parallel, so an exporter can send a span before its content is removed. setup() logs a WARNING for it; use the default SynchronousMultiSpanProcessor, which register() uses.

Attribute inventory (autogen 0.14.1)

Paths are relative to autogen/opentelemetry/. Scope name opentelemetry.instrumentation.ag2, schema https://opentelemetry.io/schemas/1.11.0 (consts.py:25-26).

Troubleshooting

• No traces: register() needs project_name or FI_PROJECT_NAME; the collector drops a batch whose resource has no project_name.
• No LLM spans after a second setup() on another provider: upstream patches OpenAIWrapper.create once and keeps the first provider (llm_wrapper.py:64-65). Call uninstrument() on the first handle first.
• Calling trace_provider.add_span_processor(...) after register() drops Future AGI's default exporter; that is fi_instrumentation behaviour. setup() does not use it, and puts this package's processor back first when you call it (see Privacy).
• setup() raises and names three packages: you have Microsoft AutoGen, ag2 1.x, or pyautogen instead of autogen 0.14.x.
• Content missing: check FI_HIDE_INPUTS / FI_HIDE_OUTPUTS (and the _MESSAGES / _TEXT variants) and any TraceConfig you pass to setup().
• Exporter errors are logged and never fail the agent.