Metadata-Version: 2.4
Name: traceAI-ag2
Version: 0.1.0
Summary: Future AGI tracing for AG2 1.x (PyPI ag2) through its native TelemetryMiddleware
License: Apache-2.0
Keywords: traceai,futureagi,opentelemetry,tracing,observability,llm,ag2
Author: Future AGI
Author-email: no-reply@futureagi.com
Requires-Python: >=3.10,<3.14
Classifier: Framework :: OpenTelemetry
Classifier: Framework :: OpenTelemetry :: Instrumentations
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Dist: ag2 (>=1.0.0)
Requires-Dist: fi-instrumentation-otel (>=1.1.0)
Project-URL: Changelog, https://github.com/future-agi/traceAI/blob/dev/python/frameworks/ag2/CHANGELOG.md
Project-URL: Documentation, https://docs.futureagi.com/docs/tracing
Project-URL: Homepage, https://futureagi.com
Project-URL: Issues, https://github.com/future-agi/traceAI/issues
Project-URL: Repository, https://github.com/future-agi/traceAI/tree/dev/python/frameworks/ag2
Description-Content-Type: text/markdown

# traceAI-ag2

Send AG2 1.x traces to Future AGI through AG2's own `TelemetryMiddleware`.
Alpha, fixture-validated. No live vendor run is claimed.

AG2 1.x is the PyPI package `ag2`, imported as `ag2`. It is not Microsoft AutoGen
(`autogen-agentchat`) and it is not AG2 Classic (`autogen` 0.14.x).

| You installed | Import | Package |
|---|---|---|
| `ag2` 1.x | `ag2` | `traceAI-ag2` (this package) |
| `autogen` 0.14.x | `autogen` | AG2 Classic integration (TH-8237) |
| `autogen-agentchat` | `autogen_agentchat` | `traceAI-autogen` |

Requires `ag2>=1.0.0` (the first stable 1.x that ships `TelemetryMiddleware`),
`fi-instrumentation-otel>=1.1.0` and Python 3.10 to 3.13. The offline test
suite runs against ag2 1.0.0, 1.0.3 and 1.1.2 on Python 3.11, and against
ag2 1.1.2 on Python 3.10, 3.12 and 3.13. `ag2` is
Apache-2.0 and is a dependency only; nothing from it is vendored.

## What it does

AG2 1.x already emits OpenTelemetry GenAI spans from `TelemetryMiddleware`.
This package does not wrap `Agent`. It:

1. registers the Future AGI exporter through `fi_instrumentation.register()`
   (or uses the provider you pass),
2. attaches `TelemetryMiddleware` to your agents through AG2's public
   `Agent.add_middleware` (content is captured by default, like every traceAI
   instrumentor; hide it with `FI_HIDE_*` / `TraceConfig`),
3. installs `AG2SpanProcessor`, which, on spans from AG2's
   `opentelemetry.instrumentation.ag2` scope only:
   - sets `gen_ai.span.kind` from `gen_ai.operation.name`
     (`chat` -> `LLM`, `execute_tool` -> `TOOL`, `invoke_agent` -> `AGENT`),
   - copies AG2's cache and thinking usage keys onto the keys Future AGI reads
     and keeps the originals:

     | AG2 key | Alias |
     |---|---|
     | `gen_ai.usage.cache_creation_input_tokens` | `gen_ai.usage.cache_write_tokens` |
     | `gen_ai.usage.cache_read_input_tokens` | `gen_ai.usage.cache_read_tokens` |
     | `gen_ai.usage.thinking_tokens` | `gen_ai.usage.reasoning.output_tokens` |

     Future AGI reads the cache counts from `gen_ai.usage.cache_read_tokens` /
     `gen_ai.usage.cache_write_tokens`, not from the dotted OpenTelemetry
     spellings (`gen_ai.usage.cache_read.input_tokens`). On a `record_usage`
     span that repeats a chat span's usage (see below), they move to
     `ag2.usage.*` with the token counts.

   - applies `TraceConfig` (`FI_HIDE_INPUTS`, `FI_HIDE_OUTPUTS`, ...), and
     removes local paths, stack traces and raw error text (see Privacy).

## Set up

```bash
pip install traceAI-ag2 "ag2[openai]"   # the openai extra is only for the OpenAIConfig example below
export FI_API_KEY="YOUR_API_KEY"
export FI_SECRET_KEY="YOUR_SECRET_KEY"
export FI_PROJECT_NAME="my-chatbot"
```

AG2 attaches middleware per agent, so pass your agents to `setup`:

```python
from ag2 import Agent
from ag2.config import OpenAIConfig
from fi_instrumentation import register
from fi_instrumentation.fi_types import ProjectType
from traceai_ag2 import setup

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

agent = Agent("assistant", "You are helpful.", config=OpenAIConfig(model="gpt-4o-mini"))
setup(agent, tracer_provider=trace_provider)  # content captured; FI_HIDE_* hides it

reply = await agent.ask("Hello")  # inside an async function
trace_provider.force_flush()  # short scripts: flush before exit
```

This snippet is illustrative and was not run against a live model; the
offline example below is what the tests execute.

`setup(agent)` without `tracer_provider` calls
`register(project_type=ProjectType.OBSERVE, project_name=project_name)` itself
and returns the provider. Later `setup()` calls without `tracer_provider`
reuse that provider until it is shut down, so `setup(planner)` followed by
`setup(worker)` gives both agents one provider and one `AG2SpanProcessor`. A
different `project_name` on a later call is ignored with a warning; pass
`tracer_provider=` to send agents to another project.

Agents created later, or per-call middleware:

```python
from traceai_ag2 import create_telemetry_middleware

mw = create_telemetry_middleware(tracer_provider=trace_provider, agent_name="worker")
worker = Agent("worker", config=cfg, middleware=[mw])
# or: await agent.ask("...", middleware=[mw])
```

Call `setup(tracer_provider=trace_provider)` once in that case too, so the span
processor is installed. `setup` is idempotent: an agent that already has a
`TelemetryMiddleware` is skipped. One `AG2SpanProcessor` serves the provider:
a later `setup(..., config=TraceConfig(...))` replaces its `TraceConfig` (the
most recent call wins and a warning is logged when it changes), while
`config=None` keeps the current one.

Span processors you add after `setup()` with
`trace_provider.add_span_processor(...)` are fine: `setup` wraps that method on
the provider instance so `AG2SpanProcessor` stays first and is not shut down
when fi's provider replaces its default exporter.

Sessions and users come from traceAI's context helpers, as with the other
traceAI integrations:

```python
from fi_instrumentation import using_attributes, using_session

with using_session("chat-123"):
    reply = await agent.ask("Hello")  # every AG2 span gets session.id="chat-123"

with using_attributes(session_id="chat-123", user_id="user-7", metadata={"tier": "pro"}):
    reply = await agent.ask("Hello")
```

`provider_name` is never invented. Pass it if you want it on every span;
otherwise AG2 fills it from the model response when the client reports one.

An offline example with a scripted model (no model API key) is in
`examples/offline_weather_agent.py`.

## Privacy

This package follows the traceAI `TraceConfig` convention: prompts, replies,
tool arguments and tool results are captured by default, and hidden with the
standard variables (or `TraceConfig(...)`):

```bash
export FI_HIDE_INPUTS=true FI_HIDE_OUTPUTS=true   # or FI_HIDE_INPUT_MESSAGES, FI_HIDE_OUTPUT_MESSAGES, FI_HIDE_INPUT_TEXT, ...
```

There is no second switch. `capture_content` is AG2's own `TelemetryMiddleware`
argument and defaults to `True`, as upstream; `setup(..., capture_content=False)`
stops AG2 itself from recording content, but the supported way to hide it is
`FI_HIDE_*`.

Never exported, in either mode: local file paths, user names, stack traces and
raw exception text. Tracebacks that AG2 puts into a tool message (a failing
tool's error is sent back to the model and recorded in the next chat span's
input) are cut to `[stack trace removed]`, absolute local paths become
`[path]`, a failing span's status description is the exception class name
(for example `RuntimeError`) instead of `str(exc)`, and exception events keep
`exception.type` only.

`TraceConfig` (or the matching `FI_HIDE_*` variables) removes it in the span
processor. AG2 records message content as one JSON
string per span (`gen_ai.input.messages`, `gen_ai.output.messages`), not as
the per-message keys that `TraceConfig.mask`'s text and image rules match, so
the processor drops whole attributes:

| `TraceConfig` flag | Removed from AG2 spans |
|---|---|
| `hide_inputs`, `hide_input_text` | `gen_ai.input.messages`, `gen_ai.system_instructions`, `gen_ai.tool.call.arguments`, `ag2.human_input.prompt` |
| `hide_outputs`, `hide_output_text` | `gen_ai.output.messages`, `gen_ai.tool.call.result`, `ag2.human_input.response` |
| `hide_input_messages` | `gen_ai.input.messages`, `gen_ai.system_instructions` |
| `hide_output_messages` | `gen_ai.output.messages` |
| `hide_llm_invocation_parameters` | Nothing: AG2 sets no invocation-parameter attribute (`gen_ai.request.parameters`) |
| `hide_input_images`, `hide_embedding_vectors` | Nothing: AG2 records only text parts (binary inputs are omitted) and no embeddings |

The text flags cannot redact just the text inside the JSON, so they remove the
whole message attribute, which is the privacy-safe choice. A removed key is
not copied to `input.value` / `output.value` either.

## Conformance

| Field | What you get | When it is omitted |
|---|---|---|
| Span kind | `AGENT`, `LLM`, `TOOL` from `gen_ai.operation.name` | `await_human_input` and `record_usage` spans get no kind (see below) |
| Model | `gen_ai.request.model`, `gen_ai.response.model` pass through | When AG2 did not set them |
| Provider | `gen_ai.provider.name` from `provider_name` or the model response | When neither is known |
| Tokens | `gen_ai.usage.input_tokens` / `output_tokens` pass through, except on `anthropic` spans, where cache read and write tokens are added to `input_tokens` (and `total_tokens` recomputed when present; see the note below). Cache tokens are aliased to `gen_ai.usage.cache_read_tokens` / `cache_write_tokens` and thinking tokens to `gen_ai.usage.reasoning.output_tokens`, originals kept | When the usage field is zero/absent. Cost is not emitted |
| Session | Not emitted by AG2. `session.id` from traceAI's `using_session` / `using_attributes` context, which wins over a static value; or set it yourself: `setup(..., span_attributes={"session.id": "..."})` | When neither is set |
| User, metadata, tags | `user.id`, `metadata`, `tag.tags` (and the other traceAI context keys) from `using_user` / `using_metadata` / `using_tags` / `using_attributes`; a key AG2 or `span_attributes` already set is not overridden | When the context does not set them |
| Tools | `gen_ai.tool.name`, `gen_ai.tool.call.id`, `gen_ai.tool.type`; arguments/result unless hidden by `FI_HIDE_*` | |
| Input / output | `input.value` / `output.value` (what Observe shows as a span's input and output), copied from the captured chat messages, tool arguments and result, or human input. A single chat completion goes on `output.value` as its message object, which Observe's chat view shows as the assistant reply. `invoke_agent` gets the first chat input and the last chat output of its turn, so the trace list shows the question and the answer | When a `TraceConfig` flag hides the source, and always on `record_usage` spans (AG2 records no content there) |
| Errors | OTel status `ERROR` on failing tool / model / agent spans | |

Notes:

- AG2 also emits `await_human_input {agent}` spans. That operation is not in
  the Microsoft Agent Framework kind table, so no kind is guessed for it.
- From ag2 1.0.3, AG2 also emits a `record_usage {kind}` span per usage event
  (`ag2.usage.kind` = `model_call`, `aggregation`, `compaction` or `subtask`).
  It has no operation name and gets no span kind; the aliases are applied.
  Future AGI totals tokens by summing the promoted
  `gen_ai.usage.input_tokens` / `output_tokens` / `total_tokens` over every
  span in a trace, so the processor moves those three keys to
  `ag2.usage.input_tokens` / `output_tokens` / `total_tokens` (values kept on
  the span) exactly where a chat span already counts the same spend:

  | `ag2.usage.kind` | Same tokens already on a chat span? | Promoted tokens |
  |---|---|---|
  | `model_call` | Yes: the chat span of that LLM call | Moved to `ag2.usage.*` |
  | `aggregation` | No: memory aggregation calls the model client directly, outside the middleware | Kept |
  | `compaction` | No: history compaction calls the model client directly | Kept |
  | `subtask` | Only if the sub-agent named in `ag2.usage.label` is itself instrumented and its `invoke_agent` span ended earlier in the same trace | Moved when it is, kept otherwise |

  With that, the trace total equals AG2's own `UsageReport` total; the tests
  check this with real AG2 for every kind above. Exception: with an
  Anthropic model and prompt caching (`AnthropicConfig` caches by default),
  AG2's Anthropic mapper reports `prompt_tokens` without the cached tokens,
  while its OpenAI mapper and the GenAI conventions count them as input. The
  processor adds `cache_read_input_tokens` and `cache_creation_input_tokens`
  to `gen_ai.usage.input_tokens` on `anthropic` spans whose tokens count, so
  the trace total is the real prompt size and exceeds `UsageReport` by the
  cached tokens. A `record_usage` span that repeats a chat span keeps AG2's
  own numbers under `ag2.usage.*`. For the `subtask` match, the
  sub-agent's `TelemetryMiddleware` must use the agent's own name (`setup`
  does; `create_telemetry_middleware(agent_name=...)` must pass `agent.name`).
  On ag2 1.0.0 to 1.0.2 there are no `record_usage` spans, so aggregation,
  compaction and uninstrumented sub-agent spend does not reach the trace.
- Network trace propagation (`ag2.otel.traceparent`) is upstream. Apart from
  that usage move, the processor never removes attributes it did not hide by
  request, except under a span attribute limit: the processor keeps the
  span's `BoundedAttributes` (limits and `dropped_attributes_count` carry
  over), so on a span already at `max_span_attributes` (128 by default) a key
  it adds evicts the oldest one and the drop is counted, as the SDK does.
  traceAI context keys (`session.id`, `user.id`, `metadata`, ...) are moved
  behind AG2's keys first, so AG2's oldest keys are evicted before them.

## Limits

- PRD J4 is not met: a middleware short-circuit shows neither `ERROR` nor a
  typed reason, and this package adds no capture for it. `setup()` adds
  `TelemetryMiddleware` as the innermost middleware, so a middleware
  registered before it (for example in `Agent(middleware=[...])`) that
  answers `on_llm_call` without calling `call_next` leaves no `chat` span for
  that call (the `invoke_agent` span ends with status `UNSET`), and one that
  answers `on_turn` leaves no span at all. AG2's own halt (the `HaltEvent`
  that `AlertPolicy` sends on a FATAL alert) does the same when the policies
  come from `Agent(assembly=[...])`. With per-call `Plugin` policies
  (`agent.ask(..., plugins=[...])`, ag2 1.1.2) the halted call gets a `chat`
  span with status `UNSET` and no attribute carrying the halt reason.
- The `record_usage subtask` dedupe matches the sub-agent by name within a
  trace, so if an instrumented agent and an uninstrumented sub-agent with the
  same name both run in one trace, the uninstrumented one's rollup loses its
  promoted tokens and the trace undercounts; give such agents distinct names.
- `create_telemetry_middleware()` defaults `agent_name=None`, which AG2
  records as `unknown`, so a sub-agent instrumented that way never matches
  its rollup's `ag2.usage.label` and its spend is counted twice (pass
  `agent_name=agent.name`), and `tracer_provider=None` sends spans to the
  OpenTelemetry global provider, which `register()` does not set by default
  (pass the provider from `register()` or `setup()`).
- Two threads making the first `add_span_processor` call on a fresh
  `register()` provider at the same time can race with fi's unlocked
  exporter reset and drop `AG2SpanProcessor`; add span processors from one
  thread, or before calling `setup()`.

## Troubleshooting

- No traces: `register()` needs `project_name` or `FI_PROJECT_NAME`; the
  collector drops a batch whose resource has no `project_name`.
- Duplicate spans: do not attach a second `TelemetryMiddleware`, and do not
  also enable `traceai-autogen` in an `ag2` process.
- Export failures are logged and never fail the agent.
- Spans arrive without `gen_ai.span.kind`: the provider runs its processors
  concurrently (`TracerProvider(active_span_processor=ConcurrentMultiSpanProcessor())`;
  `setup` logs a warning), so the exporter can read a span before
  `AG2SpanProcessor` normalizes it. Use the default synchronous processor.
- Content is missing: a `FI_HIDE_*` variable or `TraceConfig` hide flag is set.
- Content you wanted hidden still appears: you constructed `TelemetryMiddleware`
  yourself on a provider without `AG2SpanProcessor`; use `setup()`.
- This package never imports `autogen`. If your code imports `autogen`, you
  are on AG2 Classic or Microsoft AutoGen; use that integration instead.

