feat(ag2-classic): traceAI-ag2-classic for autogen 0.14.x (TH-8237) - #211

The Node OTLP exporter streams with Transfer-Encoding: chunked and sends
no Content-Length. The Receiver read Content-Length only, so every Node
export came back 400 with zero spans; two TH-8103 children had to put a
de-chunking relay in front of it. Receiver now accepts both framings.

It also records one entry per accepted export (path, lower-cased
headers, flattened resource attributes) via requests(), so a contract
test can assert X-Api-Key/X-Secret-Key and project_name through the
shared harness instead of a private recorder.

Verified: 6 harness tests pass, and the TanStack example's real Node
exporter delivered 4 chunked exports (4 spans, collector path, both
auth headers, project_name/project_type) with no relay.

Refs: TH-8339, TH-8103

… 0.14.x

New package python/frameworks/ag2-classic (traceAI-ag2-classic). setup()
enables AG2 Classic's built-in autogen.opentelemetry (instrument_llm_wrapper,
instrument_agent, instrument_pattern) on the Future AGI tracer provider from
register(); it never creates a provider, sets the global provider or adds an
exporter.

AG2ClassicSpanProcessor is prepended ahead of the exporting processor and,
from keys read in autogen/opentelemetry/instrumentators at 0.14.1:
- maps ag2.span.type to gen_ai.span.kind (handoff -> CHAIN, never emitted)
- copies the outermost gen_ai.conversation.id to session.id
- adds gen_ai.cost.total (from gen_ai.usage.cost) and
  gen_ai.usage.total_tokens on LLM spans
- sets ERROR status from upstream error.type (tool failures are caught
  inside execute_function, so upstream never sets status)
- drops message/tool/human-input/code-output content unless
  capture_content=True (upstream has no flag outside the LLM wrapper)

Version guard rejects non-0.14 autogen, Microsoft AutoGen, ag2 1.x and
pyautogen layouts, and accepts the autogen==0.14.0 alias backed by
ag2==0.14.0. Tests: mapping and guard unit tests, in-process real autogen
runs against a loopback fake OpenAI server, and a shared-harness contract
test over the real OTLP/HTTP exporter.

Refs: TH-8237

Conversation spans carry the chat-wide aggregate_usage sum as
gen_ai.usage.input_tokens/output_tokens (autogen 0.14.1
opentelemetry/instrumentators/agent_instrumentators/chat.py 81-82,
146-147) on top of the per-call tokens on the LLM spans
(llm_wrapper.py 123-125). fi-collector promotes those keys on any span
(adapter.go) and Observe sums total_tokens over a trace, so totals
doubled. Non-LLM spans now keep the values under ag2.usage.*.

Tests first: new processor test plus a trace-sum assertion in the
two-agent setup test. 59 passed on autogen 0.14.1 and 0.14.0.

approved: Nikhil 2026-10-03 blanket
Refs: TH-8237

setup() installed the processor and patched OpenAIWrapper.create before
instrumenting agents and patterns. If one of those raised, the caller never
got the handle and the global patch could not be undone. setup() now
restores OpenAIWrapper.create and re-raises; the processor stays, because
agents instrumented before the failure keep emitting spans.

approved: Nikhil 2026-10-03 blanket
Refs: TH-8237

Future AGI's TracerProvider.add_span_processor shuts down and clears every
processor on the first call after register() (fi_instrumentation/otel.py
336-339), including AG2ClassicSpanProcessor. Content then leaked to the new
processor and conversation spans kept the promoted gen_ai.usage.* tokens.

setup() now wraps add_span_processor on the provider instance once. After
the original runs, our processor is re-enabled if that call shut it down
and re-prepended ahead of every other processor. setup() finds the
processor through the wrapper, so repeated setup() calls never stack a
second guard or processor. README Privacy and Troubleshooting updated.

approved: Nikhil 2026-10-03 blanket
Refs: TH-8237

…ation

The processor tracked only AG2-scope spans and stopped the ancestor walk at
the first untracked parent. A user span between two AG2 conversations (an
inner initiate_chat inside the user's own span, agent-as-tool style) hid
the outer conversation, so the inner chat id became a second session.id in
the same trace.

on_start now records (parent span id, AG2 span or None) for every live span
on the provider, still bounded by _MAX_LIVE_SPANS, and on_end releases every
span. The walk continues through non-AG2 spans.

approved: Nikhil 2026-10-03 blanket
Refs: TH-8237

Upstream spans come from a plain OpenTelemetry tracer; only Future AGI's
own tracer applies context attributes (fi_instrumentation/instrumentation/
_tracers.py:165). using_session / using_user / using_attributes were
therefore ignored: session.id was the chat id and user.id was absent.

on_start now copies get_attributes_from_context() (read from the span's
parent context) onto AG2 spans, without overwriting keys upstream already
set. A context session.id is on the span before it ends, so it wins over
the gen_ai.conversation.id copy; the conversation span keeps the real chat
id in gen_ai.conversation.id.

initiate_chats keeps one session per outermost conversation and no session
on the multi_conversation parent. The README Session row now says so and
points to using_session(...) for one session over the whole call; tests
cover both.

approved: Nikhil 2026-10-03 blanket
Refs: TH-8237

The conversation span still carried upstream's chat-wide gen_ai.usage.cost
after the token move. The contract test now asserts, on the OTLP the shared
Receiver decoded, that no gen_ai.usage.* / gen_ai.cost.total /
llm.cost.total key appears on a non-LLM span and that each trace's
gen_ai.usage.total_tokens sum equals its LLM calls x 18 (the reviewer's M1
and M5 mutations passed the contract test before).

map_ag2_attributes now moves every gen_ai.usage.* key on a non-LLM span to
ag2.usage.*, so the aggregate cost lands in ag2.usage.cost next to the
aggregate tokens. README Cost row updated, and notes that upstream reports
response.cost on cache hits (oai/client.py:1230-1241), so cached replies
over-report cost (upstream behaviour, not fixed here).

approved: Nikhil 2026-10-03 blanket
Refs: TH-8237

A model call that raises was untested. The loopback fake model now answers
HTTP 400 to a request carrying LLM_FAIL_TRIGGER (OpenAI raises
BadRequestError, no retry), and failing_llm_chat runs a chat whose only
model call is rejected.

- test_setup.py: the LLM span keeps status ERROR, carries
  error.type=BadRequestError and gen_ai.span.kind=LLM, has no usage or cost,
  and no content leaks on the error path.
- Contract test: the same through register()'s exporting processor (which
  turns only UNSET into OK) and the shared Receiver; the token-sum check
  counts successful LLM spans only.

Upstream sets error.type and re-raises (llm_wrapper.py:97-101) and the SDK
sets ERROR, so these pass on the pre-fix code by design; README Errors row
documents the behaviour.

approved: Nikhil 2026-10-03 blanket
Refs: TH-8237

_guard.py called the autogen==0.14.0 wheel an "8-file alias". The PyPI
wheel has 6 entries, all under autogen-0.14.0.dist-info/ (LICENSE,
METADATA, NOTICE.md, WHEEL, top_level.txt, RECORD), and ships no modules.
Docstring only; no behaviour change.

approved: Nikhil 2026-10-03 blanket
Refs: TH-8237

setup() on a provider that already has AG2ClassicSpanProcessor reused it
and re-prepended it, but never undid a shutdown that bypassed the
add_span_processor guard (an unbound TracerProvider.add_span_processor,
or the multi-processor's shutdown()). A disabled processor returns early
in on_end, so spans were exported unmapped and unfiltered (fail-open).
Reusing the processor now reopens it.

Test: test_setup_again_reopens_a_processor_that_was_shut_down fails
before the fix (LLM span exported with no gen_ai.span.kind and raw
gen_ai.usage.* keys) and passes after.

Review finding N4 (installed review t_7aba4044).

approved: Nikhil 2026-10-03 blanket
Refs: TH-8237

…ently

Content filtering relies on AG2ClassicSpanProcessor running before the
exporting processor. The SDK's ConcurrentMultiSpanProcessor runs every
on_end in parallel on a thread pool, so that order is not guaranteed and
an exporter can serialize a span before content is removed. setup() now
logs a WARNING when the provider's active processor is a
ConcurrentMultiSpanProcessor; the default SynchronousMultiSpanProcessor
(what fi_instrumentation.register() uses) is unchanged and silent.

Test: test_setup_warns_when_span_processors_run_concurrently fails
before the fix (no warning record: assert 0 == 1) and passes after.

Review finding N5 (installed review t_7aba4044).

approved: Nikhil 2026-10-03 blanket
Refs: TH-8237

…rument

uninstrument() restored the captured original OpenAIWrapper.create
unconditionally, so a wrapper another library installed after setup()
was silently dropped. The handle now records the traced function
upstream installed and restores the original only while
OpenAIWrapper.create is still that function; otherwise it logs a
WARNING, leaves the replacement in place and keeps ownership so a later
uninstrument() can still restore. setup()'s rollback path is unchanged
(nothing can replace the method between the patch and the rollback).

Test: test_uninstrument_leaves_a_later_third_party_wrapper_in_place
fails before the fix (OpenAIWrapper.create is the original, not the
third-party wrapper) and passes after.

Review finding N6 (installed review t_7aba4044).

approved: Nikhil 2026-10-03 blanket
Refs: TH-8237

The documented install (`pip install "autogen>=0.14.0,<0.15"` then
`pip install traceAI-ag2-classic`) has no model client: autogen's base
requirements do not include openai, so the README quick start raised
ImportError ('openai' is not installed) when it created an agent with an
llm_config. Install and the example docstring now use
`pip install traceAI-ag2-classic "autogen[openai]"`; the package itself
pins autogen to >=0.14.0,<0.15, and the 0.14.0 alias forwards the extra
to ag2[openai]==0.14.0.

Evidence (scratch venvs, Python 3.11, quick start up to setup(), no
model call): old two-line install -> ImportError from
create_openai_client; new command -> QUICKSTART_OK on autogen 0.14.1
with openai 2.54.0.

Review finding N1 (installed review t_7aba4044).

approved: Nikhil 2026-10-03 blanket
Refs: TH-8237

The Session row said gen_ai.conversation.id "keeps the chat id" inside
using_session / using_attributes. That holds only for the conversation
spans initiate_chat / a_initiate_chat start (upstream sets the key after
start, chat.py:65,131). fi's using_session also puts the session id in
context under gen_ai.conversation.id, and the processor copies missing
context keys at on_start, so LLM, agent, tool, initiate_chats and resumed
conversation spans carry the session id there. README reworded.

Tests pin the documented behaviour (unit: chat m span; real autogen run:
every non-conversation span). They pass before and after by design (doc
fix, no code change); a mutation that skips copying
gen_ai.conversation.id from context makes both fail with KeyError.

Review finding N3 (installed review t_7aba4044).

approved: Nikhil 2026-10-03 blanket
Refs: TH-8237

The nested-conversation check tracks every live span on the provider and
stops tracking at _MAX_LIVE_SPANS (10000); entries are freed in on_end.
A README Limits section now says so, and that the nested-session split
returns only if that many spans leak or run concurrently on the
provider. Upstream ends every span it starts (each instrumentator uses
`with tracer.start_as_current_span`, checked in autogen 0.14.1), so a
leak needs other code on the same provider. Docs only; no code change.

Review finding N2 (installed review t_7aba4044).

approved: Nikhil 2026-10-03 blanket
Refs: TH-8237

fi-instrumentation-otel 1.0.0's register() raises AttributeError
('HTTPSpanExporter' object has no attribute '_headers') with
opentelemetry-exporter-otlp-proto-http 1.45, so a fresh install that
resolves 1.0.0 crashes on startup. Use the floor the other TH-8103
packages already declare.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

Co-Authored-By: Claude Opus 5.5 <[email protected]>