Agent Graphs

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 panel when a trace contains agent spans.

​

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: 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: explore traces with the trace, thread, and timeline views
• Span Attributes: full reference for orq.span_type and agent attributes