> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Graphs

> Visualize multi-agent delegation paths, tool calls, and sub-agent invocations as a graph in the Traces UI.

The **Agent Graph** view renders multi-agent and multi-step workflows as a directed graph. Each node represents a span (an agent step, tool call, or sub-agent invocation), and edges show the delegation path from parent to child.

The graph appears below the trace tree in the [**Traces**](/docs/ai-studio/observability/traces) panel when a trace contains agent spans.

<Frame caption="Agent graph showing a multi-agent workflow with orchestration, research, code execution, and synthesis steps.">
  <img src="https://mintcdn.com/orqai/t8cxhdv8Cc4AqMeo/images/agent-graph-414.png?fit=max&auto=format&n=t8cxhdv8Cc4AqMeo&q=85&s=72ed4c05a65176df6c3b74ad6a2b114f" alt="Agent graph view in Orq.ai Traces UI showing a support-agent root with orchestrate, research-delegation, code-execution, and synthesize-response sub-agents, each with model calls and tool invocations." width="1671" height="1243" data-path="images/agent-graph-414.png" />
</Frame>

## How graphs are produced

Graphs are produced through two distinct paths depending on the framework.

### Pre-stamped graphs (LangGraph)

When a trace originates from **LangGraph**, the graph structure is pre-stamped on the root span's `orq.trace.graph` attribute. The attribute contains:

* **Nodes**: each with an `id`, `type`, and `span_ids` mapping to the trace's span hierarchy
* **Edges**: each with a `source` and `target` node ID

The **Traces** UI reads this attribute directly and renders the graph without needing to infer structure from span parent/child relationships.

### Derived graphs (all other frameworks)

For frameworks that do not pre-stamp a graph (OpenAI Agents SDK, CrewAI, AutoGen, Agno, and managed **Orq.ai** agents), the graph is derived automatically from the span hierarchy:

1. The trace must contain at least one span whose type starts with `span.agent` (e.g. `span.agent`, `span.agent_execution`, `span.agent_tool_execution`)
2. Once triggered, every span in the trace becomes a graph node; there is no type filter inside the derivation
3. Parent/child relationships between spans become edges
4. The layout engine positions nodes top-to-bottom using a dagre algorithm

This means any trace with agent spans automatically produces a graph showing the full execution hierarchy, even without framework-specific instrumentation.

## Span types in the graph

Common span types that appear as graph nodes:

| Span type                   | Node represents                                | Icon                    |
| --------------------------- | ---------------------------------------------- | ----------------------- |
| `span.agent_execution`      | Top-level agent run                            | <Icon icon="robot" />   |
| `span.agent`                | Orchestration step within an agent             | <Icon icon="robot" />   |
| `span.agent_tool_execution` | Tool call within an agent step                 | <Icon icon="wrench" />  |
| `span.tool`                 | External tool invocation (HTTP, MCP, function) | <Icon icon="wrench" />  |
| `span.chain`                | LangChain/LangGraph chain step                 | <Icon icon="link" />    |
| `span.chat_completion`      | Model call                                     | <Icon icon="message" /> |

Nodes are labeled by span name. When multiple calls collapse into a single node (same step repeated), a badge shows the count (e.g. **x3** for three identical calls). Clicking a collapsed node cycles through the individual spans, showing a position indicator (e.g. **2/3**).

## Graph controls

The graph panel is resizable and collapsible:

* **Zoom in / out / reset**: adjust the view to fit the graph or focus on specific nodes
* **Collapse / expand**: hide or show the graph panel below the trace tree
* **Pan**: drag to navigate large graphs

Antiparallel edges (A calls B and B calls A) are drawn on opposite sides of the nodes to avoid visual overlap.

## Debug with graphs

### Trace delegation paths

Open a multi-agent trace and look at the agent graph panel below the trace tree to see which agent delegated to which sub-agent, and in what order. The top-to-bottom layout shows the call chain from root agent to leaf tool calls.

### Find where time is spent

Each node's label shows the span name and type. Click a node to highlight it in the trace tree, where the duration is shown next to each span.

### Inspect failed sub-agent calls

Click a node to open its span details in the side panel, where the error message, attributes, and events are available. Failed spans show an error status in the trace tree list alongside the graph.

### Debug tool call failures

Tool spans (`span.tool`, `span.agent_tool_execution`) show the tool name in the span panel. Click to see arguments, results, and other attributes.

## Related

* [Traces](/docs/ai-studio/observability/traces): explore traces with the trace, thread, and timeline views
* [Span Attributes](/docs/ai-gateway/span-attributes): full reference for `orq.span_type` and agent attributes