> 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.

# Microsoft Agent Framework (tracing)

> Trace Microsoft Agent Framework agents, tools, chat completions, and workflows with Respan.

[Microsoft Agent Framework](https://learn.microsoft.com/agent-framework/) is a Python framework for building agents and workflow executors. Respan normalizes the framework's native OpenTelemetry spans into Respan traces for agent runs, model calls, tool executions, and workflow steps.

This tracing setup uses your model provider credentials directly. To route model calls through Respan instead, use the [Microsoft Agent Framework gateway setup](/docs/gateway/microsoft-agent-framework).

#### 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 [Microsoft Agent Framework gateway setup](/docs/gateway/microsoft-agent-framework) to route model calls through the Respan gateway.

#### Example projects

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

## Setup

#### Install packages

```bash
pip install respan-ai respan-instrumentation-microsoft-agent-framework agent-framework-openai
```

#### 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 by Agent Framework for direct model requests. `RESPAN_API_KEY` exports traces to Respan.

#### Initialize and run

```python
import asyncio
import os

from agent_framework import Agent, WorkflowBuilder, WorkflowContext, executor, tool
from agent_framework.openai import OpenAIChatCompletionClient
from respan import Respan
from respan_instrumentation_microsoft_agent_framework import (
    MicrosoftAgentFrameworkInstrumentor,
)

respan = Respan(
    app_name="microsoft-agent-framework-demo",
    instrumentations=[MicrosoftAgentFrameworkInstrumentor(capture_content=True)],
)

@tool
def lookup_weather(city: str) -> str:
    return f"The weather in {city} is sunny."

async def main() -> None:
    client = OpenAIChatCompletionClient(
        api_key=os.environ["OPENAI_API_KEY"],
        model="gpt-4.1-nano",
    )
    agent = Agent(
        client=client,
        name="weather_agent",
        instructions="Use the weather tool when asked about weather.",
        tools=[lookup_weather],
    )

    @executor(id="ask_weather_agent", input=str, workflow_output=str)
    async def ask_weather_agent(query: str, ctx: WorkflowContext) -> None:
        result = await agent.run(query)
        await ctx.yield_output(str(result))

    workflow = WorkflowBuilder(
        start_executor=ask_weather_agent,
        output_from=[ask_weather_agent],
        name="weather_agent_workflow",
    ).build()

    events = await workflow.run("What is the weather in Seattle?")
    for output in events.get_outputs():
        print(output)

asyncio.run(main())
respan.flush()
respan.shutdown()
```

#### View your trace

Open the [Traces page](https://platform.respan.ai/platform/traces) to see workflow, executor, agent, chat, and tool spans.

## Configuration

| Parameter             | Type           | Default           | Description                                                                |
| --------------------- | -------------- | ----------------- | -------------------------------------------------------------------------- |
| `api_key`             | `str \| None`  | `RESPAN_API_KEY`  | Respan API key used to export traces.                                      |
| `base_url`            | `str \| None`  | `RESPAN_BASE_URL` | Optional Respan trace export API URL.                                      |
| `instrumentations`    | `list`         | `[]`              | Include `MicrosoftAgentFrameworkInstrumentor()` to activate normalization. |
| `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, for example `"production"`.                               |

## What gets traced

| Agent Framework operation | Respan span | Notes                                                                                               |
| ------------------------- | ----------- | --------------------------------------------------------------------------------------------------- |
| Workflow run              | `workflow`  | Captures workflow name and input/output.                                                            |
| Executor step             | `task`      | Captures executor id and yielded output.                                                            |
| Agent invocation          | `agent`     | Captures agent name, input, and final output.                                                       |
| Chat completion           | `chat`      | Captures prompts, completions, tool definitions, tool calls, model, and token usage when available. |
| Tool execution            | `tool`      | Captures tool name, arguments, result, and errors.                                                  |

## Attributes

Set defaults at initialization. These apply to every span emitted by the instrumentor.

```python
from respan import Respan
from respan_instrumentation_microsoft_agent_framework import (
    MicrosoftAgentFrameworkInstrumentor,
)

respan = Respan(
    instrumentations=[MicrosoftAgentFrameworkInstrumentor(capture_content=True)],
    customer_identifier="user_123",
    metadata={"service": "agent-api", "version": "1.0.0"},
    environment="production",
)
```

Use `capture_content=False` if you want model and span metadata without prompt, completion, or tool payload content.