Multi-Agent Tracing

Multi-agent tracing captures how agents in a system interact — which agent ran, what it received and produced, and when control passed from one agent to another. Each agent becomes a distinct span in the trace, with handoffs recorded as first-class events.

There are two ways to instrument a multi-agent system: auto-instrumentation (zero-config for supported frameworks) and manual decoration (works with any framework or custom code).

Auto-Instrumentation

For supported frameworks, auto_instrument() handles all span creation automatically — no decorator changes required.

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

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

LangGraph

With LangGraph auto-instrumentation, every graph.invoke(), graph.ainvoke(), graph.stream(), and graph.astream() call is traced automatically. Every node gets an ai.agent.invoke span, under one for the graph itself, whatever the nodes are called.

To label a node with something other than its node name, set agent_name in the invocation metadata:

# Explicit agent name — overrides the node name in traces
graph.invoke(state, config={"metadata": {"agent_name": "researcher"}})

Outside LangGraph there is no equivalent marker, so a chain is traced as an agent when its name contains agent, specialist, orchestrator, coordinator or supervisor, or when the invocation metadata sets agent_name or is_agent.

Agent name resolution

The agent name on each ai.agent.invoke span is resolved with this priority order. The first source that produces a value wins:

1. metadata.agent_name — explicit override passed in the invocation config.
2. metadata.langgraph_node — set automatically by LangGraph for each node.
3. serialized.name — provided by the framework when available.
4. Last segment of serialized.id — falls back to the class path (for example ChatGoogleGenerativeAI).
5. The run’s own name — how LangGraph reports the compiled graph’s name, which is what labels the span for the graph itself.
6. "unknown" — when none of the above is set.

Handoff detection

Any tool whose name starts with transfer_to_ creates an ai.agent.handoff span, attributed to the agent that called it. Detection runs in the LangChain callback’s tool path, so it works for any LangChain-based system — including LangGraph and the LangGraph prebuilt agents that emit these tools — not just LangGraph specifically.

An edge from one node to the next is not a handoff. Only an explicit transfer is, so a linear pipeline and an agent looping with a tool both report none.

More Frameworks

LangGraph, Microsoft Agent Framework and Google ADK all produce native ai.agent.invoke and ai.agent.handoff spans.

• For MAF, handoffs in a HandoffBuilder workflow are detected and synthesized automatically - see Microsoft Agent Framework.
• For Google ADK, both of its multi-agent mechanisms produce edges: a transfer_to_agent call becomes the handoff span directly, and an AgentTool delegation gets a synthesized one alongside its tool span - see Google ADK.

LangChain outside LangGraph is supported for general tracing (LLM calls, tools, retrieval), but there an agent span depends on the naming or metadata described above, and a handoff span on a transfer_to_* tool name. Support for additional frameworks will be added over time. Use manual decoration for any framework not yet covered.

Manual Decoration

Use @observe with the ai.agent.invoke span name to instrument any agent function, regardless of how it’s built:

from rhesis.sdk import RhesisClient, observe
from rhesis.telemetry.schemas import AIOperationType
from rhesis.telemetry.attributes import AIAttributes

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

@observe(
    span_name=AIOperationType.AGENT_INVOKE,
    **{AIAttributes.AGENT_NAME: "research_agent"}
)
def research_agent(query: str) -> str:
    # Your agent logic here — LLM calls, tool use, etc.
    return run_research(query)

@observe(
    span_name=AIOperationType.AGENT_INVOKE,
    **{AIAttributes.AGENT_NAME: "analyst_agent"}
)
def analyst_agent(findings: str) -> str:
    return run_analysis(findings)

Recording Handoffs

To explicitly record when one agent hands off to another, create a handoff span around the transition:

from rhesis.telemetry.schemas import AIOperationType
from rhesis.telemetry.attributes import AIAttributes

@observe(
    span_name=AIOperationType.AGENT_HANDOFF,
    **{
        AIAttributes.AGENT_HANDOFF_FROM: "research_agent",
        AIAttributes.AGENT_HANDOFF_TO: "analyst_agent",
    }
)
def handoff_to_analyst(findings: str) -> str:
    return analyst_agent(findings)

Full Manual Example

from rhesis.sdk import RhesisClient, endpoint, observe
from rhesis.telemetry.schemas import AIOperationType
from rhesis.telemetry.attributes import AIAttributes

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

@observe(span_name=AIOperationType.AGENT_INVOKE,
         **{AIAttributes.AGENT_NAME: "research_agent"})
def research_agent(query: str) -> str:
    return call_llm(f"Research this topic: {query}")

@observe(span_name=AIOperationType.AGENT_HANDOFF,
         **{AIAttributes.AGENT_HANDOFF_FROM: "research_agent",
            AIAttributes.AGENT_HANDOFF_TO: "analyst_agent"})
def handoff(findings: str) -> str:
    return analyst_agent(findings)

@observe(span_name=AIOperationType.AGENT_INVOKE,
         **{AIAttributes.AGENT_NAME: "analyst_agent"})
def analyst_agent(findings: str) -> str:
    return call_llm(f"Analyze these findings: {findings}")

@endpoint()
def run_pipeline(input: str) -> dict:
    research = research_agent(input)
    result = handoff(research)
    return {"output": result}

Trace Visualization

The Graph View in Rhesis renders agents, tools, and handoffs as nodes and edges, with turn markers for multi-turn conversations:

Span Reference

ai.agent.invoke

ai.agent.handoff

See Semantic Conventions for the full attribute reference.