> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# AutoGen (tracing)

> Trace AutoGen AgentChat workflows with Respan — auto-instrumented spans and full observability.

[AutoGen](https://microsoft.github.io/autogen/) AgentChat is Microsoft's framework for building event-driven single-agent and multi-agent applications. Respan gives you full observability over agent runs, team conversations, tool calls, and LLM generations.

#### Set up Respan

Create an account at [platform.respan.ai](https://platform.respan.ai) and grab an [API key](https://platform.respan.ai/platform/gateway/api-keys).

Run `npx @respan/cli setup` to set up with your coding agent.

#### Use Respan Gateway

See [AutoGen gateway setup](/docs/integrations/gateway/auto-gen) to route this integration through the Respan gateway.

#### Example projects

* [Python examples](https://github.com/respanai/respan-example-projects/tree/main/python/tracing/autogen)

## Setup

#### Install packages

```bash
pip install respan-ai respan-instrumentation-autogen
```

#### Set environment variables

```bash
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
```

`OPENAI_API_KEY` is used for AutoGen model calls. `RESPAN_API_KEY` is used to export traces to Respan. Set `OPENAI_MODEL` to override the default `gpt-4o-mini` model.

#### Initialize and run

```python
import asyncio
import os

from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient
from respan import Respan
from respan_instrumentation_autogen import AutoGenInstrumentor

respan_api_key = os.environ["RESPAN_API_KEY"]
openai_api_key = os.environ["OPENAI_API_KEY"]
openai_model = os.getenv("OPENAI_MODEL", "gpt-4o-mini")

respan = Respan(
    api_key=respan_api_key,
    instrumentations=[AutoGenInstrumentor()],
)

model_client = OpenAIChatCompletionClient(
    model=openai_model,
    api_key=openai_api_key,
)

agent = AssistantAgent(
    name="assistant",
    model_client=model_client,
    system_message="You answer with concise, practical engineering advice.",
)

async def main():
    result = await agent.run(
        task="In one sentence, explain why tracing helps multi-agent apps."
    )
    print(result.messages[-1].content)
    await model_client.close()

asyncio.run(main())
```

#### View your trace

Open the [Traces page](https://platform.respan.ai/platform/traces) to see your AutoGen workflow with agent spans, team spans, tool spans, and LLM generations.

## Configuration

| Parameter             | Type           | Default | Description                                                         |
| --------------------- | -------------- | ------- | ------------------------------------------------------------------- |
| `api_key`             | `str \| None`  | `None`  | Falls back to `RESPAN_API_KEY` env var.                             |
| `base_url`            | `str \| None`  | `None`  | Falls back to `RESPAN_BASE_URL` env var.                            |
| `instrumentations`    | `list`         | `[]`    | Plugin instrumentations to activate (e.g. `AutoGenInstrumentor()`). |
| `customer_identifier` | `str \| None`  | `None`  | Default customer identifier for all spans.                          |
| `metadata`            | `dict \| None` | `None`  | Default metadata attached to all spans.                             |
| `environment`         | `str \| None`  | `None`  | Environment tag (e.g. `"production"`).                              |

## Attributes

### In Respan()

Set defaults at initialization — these apply to all spans.

```python
from respan import Respan
from respan_instrumentation_autogen import AutoGenInstrumentor

respan = Respan(
    instrumentations=[AutoGenInstrumentor()],
    customer_identifier="user_123",
    metadata={"service": "autogen-api", "version": "1.0.0"},
)
```

### With propagate_attributes

Override per-request using a context scope.

```python
from respan import Respan, propagate_attributes
from respan_instrumentation_autogen import AutoGenInstrumentor

respan = Respan(instrumentations=[AutoGenInstrumentor()])

async def handle_request(user_id: str, message: str):
    with propagate_attributes(
        customer_identifier=user_id,
        thread_identifier="conv_abc_123",
        metadata={"plan": "pro"},
    ):
        result = await agent.run(task=message)
        print(result.messages[-1].content)
```

| Attribute             | Type   | Description                                           |
| --------------------- | ------ | ----------------------------------------------------- |
| `customer_identifier` | `str`  | Identifies the end user in Respan analytics.          |
| `thread_identifier`   | `str`  | Groups related messages into a conversation.          |
| `metadata`            | `dict` | Custom key-value pairs. Merged with default metadata. |

## Examples

### Tool calls

Tool calls are captured as spans with inputs, outputs, and timing.

```python
from autogen_agentchat.agents import AssistantAgent

async def estimate_latency(service: str, requests_per_minute: int) -> str:
    """Estimate API latency for a service under load."""
    return f"{service}: about 155 ms p95 latency"

agent = AssistantAgent(
    name="capacity_planner",
    model_client=model_client,
    tools=[estimate_latency],
    reflect_on_tool_use=True,
    system_message="Use the estimate_latency tool before answering.",
)

result = await agent.run(
    task="Estimate p95 latency for tracing-api at 240 requests per minute."
)
print(result.messages[-1].content)
```

### Teams

Team conversations are traced with workflow, agent, and LLM spans.

```python
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.conditions import MaxMessageTermination, TextMentionTermination
from autogen_agentchat.teams import RoundRobinGroupChat

planner = AssistantAgent(
    name="planner",
    model_client=model_client,
    system_message="Create a compact implementation plan.",
)
reviewer = AssistantAgent(
    name="reviewer",
    model_client=model_client,
    system_message="Review the plan. If clear, end with APPROVED.",
)

team = RoundRobinGroupChat(
    [planner, reviewer],
    termination_condition=TextMentionTermination("APPROVED") | MaxMessageTermination(4),
)
result = await team.run(task="Plan a small release checklist.")
```