Microsoft Agent Framework

Zero-config tracing for Microsoft Agent Framework  (MAF) agents and workflows.

Microsoft Agent Framework already emits OpenTelemetry spans for agents, model calls, tools, and multi-agent workflows. Rhesis turns those spans into first-class traces with a single call: enable MAF’s instrumentation, translate its GenAI spans into the Rhesis semantic conventions, and synthesize agent handoff events for the Graph View. Your agent code does not change.

Installation

Install the SDK with the agent-framework extra:

pip install "rhesis-sdk[agent-framework]"

Quick Start

Create the RhesisClient first (it installs the OpenTelemetry tracer provider and Rhesis exporter), then call auto_instrument. After that, use MAF exactly as you normally would.

from rhesis.sdk import RhesisClient
from rhesis.sdk.telemetry import auto_instrument
from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient

# 1. Initialize Rhesis (sets up tracing). Required before auto_instrument().
client = RhesisClient(
    api_key="your-api-key",
    project_id="your-project-id",
    environment="development",
)

# 2. Enable Microsoft Agent Framework auto-instrumentation
auto_instrument("agent_framework")  # alias: auto_instrument("maf")

# 3. Use MAF normally - every agent, model, and tool call is traced
agent = Agent(
    client=OpenAIChatClient(),
    instructions="You are a helpful travel assistant.",
)

result = await agent.run("Plan me a relaxed day trip to Lisbon.")
print(result.text)

auto_instrument() with no arguments auto-detects every installed framework (including MAF). Pass "agent_framework" (or "maf") to enable it explicitly. The call returns the list of frameworks that were instrumented:

enabled = auto_instrument("agent_framework")
assert "agent_framework" in enabled  # ["agent_framework"]

What Gets Traced

Once enabled, MAF operations are captured automatically and mapped onto the Rhesis schema:

• Agents - each agent activation becomes an ai.agent.invoke span
• Model calls - chat completions become ai.llm.invoke spans with token counts
• Tools - tool executions become ai.tool.invoke spans with ai.tool.input / ai.tool.output events
• Handoffs - control passing between agents is recorded as ai.agent.handoff spans
• Embeddings - embedding calls become ai.embedding.generate spans
• Workflows - HandoffBuilder / workflow orchestration becomes function.workflow.* spans

Operation Mapping

Spans that don’t match a known operation fall back to function.maf.<name> so they always pass backend validation, with the original name preserved on the gen_ai.original_span_name attribute.

Multi-Agent Handoffs

MAF’s HandoffBuilder workflows route work between agents. With current MAF builds, a handoff is expressed as a tool call inside the chat span rather than a separate tool span, so Rhesis reads the model output and synthesizes an ai.agent.handoff span for each transition. These render as edges in the Graph View.

Each handoff span carries ai.agent.handoff.to and, when it can be resolved, ai.agent.handoff.from. See the Multi-Agent Tracing page for the full span reference.

Content Capture and Privacy

By default, the integration captures message content (prompts, completions, tool arguments and results) so traces show what each agent actually sent and received.

To omit message content - for example in production or regulated environments - set RHESIS_DISABLE_CONTENT_CAPTURE before initializing:

export RHESIS_DISABLE_CONTENT_CAPTURE=1

Accepted truthy values: 1, true, yes, on (case-insensitive). When disabled, spans are still exported with structural metadata (model, provider, token counts, agent names, operation types), but no prompt, completion, or tool input/output payloads are recorded.

Workflow Span Verbosity

To keep traces readable, the integration trims low-value workflow infrastructure spans (edge_group.*, message.send and workflow.build) by default while keeping the structural executor.* spans that parent agent activations.

To keep every workflow span (useful when debugging the orchestration layer itself), set:

export RHESIS_MAF_VERBOSE_WORKFLOW_SPANS=1

Combining with Decorators

Auto-instrumentation composes with @endpoint and @observe. Wrap your entry point with @endpoint so Rhesis can run tests against it; MAF spans created inside are nested under the endpoint span automatically:

from rhesis.sdk import RhesisClient, endpoint
from rhesis.sdk.telemetry import auto_instrument

client = RhesisClient(api_key="your-api-key", project_id="your-project-id")
auto_instrument("agent_framework")

@endpoint()
async def chat(input: str, conversation_id: str = None) -> dict:
    # MAF agent/tool/handoff spans are nested under this endpoint span
    result = await travel_workflow.run(input)
    return {"output": result.text, "conversation_id": conversation_id}

Multi-Turn Conversations

MAF opens its own root span per turn, so OpenTelemetry mints a fresh trace id every time you run an agent or a workflow. Bind a conversation id and the integration puts all of that conversation’s turns on one trace, with the run root of each turn carrying the turn’s message and reply:

from rhesis.telemetry.context import set_conversation_id

set_conversation_id("user-42")

for message in ["Hello", "Tell me more"]:
    result = await agent.run(message)

The first turn keeps the trace id it was born with and later turns join it, so a link to the first turn still resolves. Bind the id before the run starts: the target trace has to be known when the run root is created, and MAF assigns no span attributes before then.

Two cases stand this down, because there the trace id is already owned and published elsewhere: a run inside an @endpoint or @observe span, and a platform-driven turn. Both join the turns themselves, so the integration leaves their spans where they are.

Worked Example: Travel Agent

The repository ships a runnable multi-agent MAF demo - a HandoffBuilder workflow with a coordinator and seven specialists - built specifically to produce agent, LLM, tool, and handoff traces in Rhesis. See agents/travel-agent and its architecture notes .

Migrating from AutoGen

AutoGen 0.2 has been folded into the unified Microsoft Agent Framework. The legacy auto_instrument("autogen") path is now a no-op placeholder - use auto_instrument("agent_framework") instead, which covers the full Agent / tool / workflow surface.

Disabling

Turn instrumentation off (restores the original exporter) with:

from rhesis.sdk.telemetry import disable_auto_instrument

disable_auto_instrument()