Microsoft Agent Framework (tracing)

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

Create an account at platform.respan.ai and grab an API key.

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

See Microsoft Agent Framework gateway setup to route model calls through the Respan gateway.

Setup

1

Install packages

$pip install respan-ai respan-instrumentation-microsoft-agent-framework agent-framework-openai
2

Set environment variables

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

3

Initialize and run

1import asyncio
2import os
3
4from agent_framework import Agent, WorkflowBuilder, WorkflowContext, executor, tool
5from agent_framework.openai import OpenAIChatCompletionClient
6from respan import Respan
7from respan_instrumentation_microsoft_agent_framework import (
8 MicrosoftAgentFrameworkInstrumentor,
9)
10
11respan = Respan(
12 app_name="microsoft-agent-framework-demo",
13 instrumentations=[MicrosoftAgentFrameworkInstrumentor(capture_content=True)],
14)
15
16@tool
17def lookup_weather(city: str) -> str:
18 return f"The weather in {city} is sunny."
19
20async def main() -> None:
21 client = OpenAIChatCompletionClient(
22 api_key=os.environ["OPENAI_API_KEY"],
23 model="gpt-4.1-nano",
24 )
25 agent = Agent(
26 client=client,
27 name="weather_agent",
28 instructions="Use the weather tool when asked about weather.",
29 tools=[lookup_weather],
30 )
31
32 @executor(id="ask_weather_agent", input=str, workflow_output=str)
33 async def ask_weather_agent(query: str, ctx: WorkflowContext) -> None:
34 result = await agent.run(query)
35 await ctx.yield_output(str(result))
36
37 workflow = WorkflowBuilder(
38 start_executor=ask_weather_agent,
39 output_from=[ask_weather_agent],
40 name="weather_agent_workflow",
41 ).build()
42
43 events = await workflow.run("What is the weather in Seattle?")
44 for output in events.get_outputs():
45 print(output)
46
47asyncio.run(main())
48respan.flush()
49respan.shutdown()
4

View your trace

Open the Traces page to see workflow, executor, agent, chat, and tool spans.

Configuration

ParameterTypeDefaultDescription
api_keystr | NoneRESPAN_API_KEYRespan API key used to export traces.
base_urlstr | NoneRESPAN_BASE_URLOptional Respan trace export API URL.
instrumentationslist[]Include MicrosoftAgentFrameworkInstrumentor() to activate normalization.
customer_identifierstr | NoneNoneDefault customer identifier for all spans.
metadatadict | NoneNoneDefault metadata attached to all spans.
environmentstr | NoneNoneEnvironment tag, for example "production".

What gets traced

Agent Framework operationRespan spanNotes
Workflow runworkflowCaptures workflow name and input/output.
Executor steptaskCaptures executor id and yielded output.
Agent invocationagentCaptures agent name, input, and final output.
Chat completionchatCaptures prompts, completions, tool definitions, tool calls, model, and token usage when available.
Tool executiontoolCaptures tool name, arguments, result, and errors.

Attributes

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

1from respan import Respan
2from respan_instrumentation_microsoft_agent_framework import (
3 MicrosoftAgentFrameworkInstrumentor,
4)
5
6respan = Respan(
7 instrumentations=[MicrosoftAgentFrameworkInstrumentor(capture_content=True)],
8 customer_identifier="user_123",
9 metadata={"service": "agent-api", "version": "1.0.0"},
10 environment="production",
11)

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