Metadata-Version: 2.4
Name: traceAI-agent-framework
Version: 0.1.0
Summary: OpenTelemetry instrumentation for Microsoft Agent Framework
License: Apache-2.0
Keywords: traceai,futureagi,opentelemetry,tracing,observability,llm,agent-framework
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: agent-framework (>=1.0.0)
Requires-Dist: fi-instrumentation-otel (>=1.1.0)
Project-URL: Changelog, https://github.com/future-agi/traceAI/blob/dev/python/frameworks/agent-framework/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/agent-framework
Description-Content-Type: text/markdown

# Microsoft Agent Framework OpenTelemetry Integration

## Overview
This integration provides support for using OpenTelemetry with Microsoft Agent Framework. It enables tracing and monitoring of applications built with Agent Framework.

## Installation

1. **Install traceAI Agent Framework**

```bash
pip install traceAI-agent-framework
```

2. **Install Microsoft Agent Framework**

```bash
pip install agent-framework
```


### Set Environment Variables
Set up your environment variables to authenticate with FutureAGI

```python
import os

os.environ["FI_API_KEY"] = FI_API_KEY
os.environ["FI_SECRET_KEY"] = FI_SECRET_KEY
os.environ["OPENAI_API_KEY"] = OPENAI_API_KEY
```

## Quickstart

### Register Tracer Provider
Set up the trace provider to establish the observability pipeline. The trace provider:

```python
from fi_instrumentation import register
from fi_instrumentation.fi_types import ProjectType

trace_provider = register(
    project_type=ProjectType.OBSERVE,
    project_name="agent_framework_app",
    set_global_tracer_provider=True,
)
```

### Configure Agent Framework Instrumentation
Turn on Agent Framework's native OpenTelemetry emission and install the FI attribute mapping.

```python
from agent_framework.observability import enable_instrumentation
from traceai_agent_framework import enable_fi_attribute_mapping

enable_instrumentation(enable_sensitive_data=True)
enable_fi_attribute_mapping()
```

`enable_sensitive_data=True` records prompts, completions and tool arguments on the spans. Leave it off to keep that content out of your traces.

### Privacy
Content is captured by default (as in every traceAI integration) once `enable_sensitive_data` is on. Hide it with the standard `FI_HIDE_INPUTS`, `FI_HIDE_OUTPUTS`, `FI_HIDE_INPUT_MESSAGES`, `FI_HIDE_OUTPUT_MESSAGES`, `FI_HIDE_INPUT_TEXT` and `FI_HIDE_OUTPUT_TEXT` environment variables, or pass `enable_fi_attribute_mapping(config=TraceConfig(...))`. Tool arguments/results and system instructions follow `hide_inputs` / `hide_outputs`. Raw exception text and stack traces are never exported: an errored span keeps ERROR status and the exception class name.

Agent Framework emits on the global tracer provider only, so keep `set_global_tracer_provider=True` in `register(...)`.

### Create Agent Framework Components
Set up your Agent Framework client with built-in observability.

```python
import asyncio
from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient

agent = Agent(
    OpenAIChatClient(model="gpt-4o-mini"),
    name="weather_agent",
    instructions="You are a concise weather assistant.",
)

async def main():
    response = await agent.run("What's the weather in Paris?")
    print(response)

asyncio.run(main())
```

### Token usage

Model-call spans keep `gen_ai.usage.*`. Native agent totals summarize those calls and are retained as `agent_framework.usage.*` diagnostics, not additional billable tokens. This prevents trace totals from counting the same usage twice.

### Sessions
All spans of one run get the same `session.id`, which Observe groups sessions on. It comes from, in order:

1. `using_session(...)` around the run. This works with every chat client, including ones that keep history locally such as `OpenAIChatCompletionClient`:

```python
from fi_instrumentation import using_session

session = agent.create_session()
with using_session("support-chat-42"):
    await agent.run("What's the weather in Paris?", session=session)
    await agent.run("And in Tokyo?", session=session)
```

2. The `gen_ai.conversation.id` the run starts with, which is the session's `service_session_id`. With the Responses API and no stored conversation, that id is the previous response id, so each turn lands in its own session. Use `using_session` for one session across turns.


