Instrument agent dependencies and workflows

AI Observability has two graph views for understanding agent structure: Dependencies and Workflow. Use them together to debug how LLM calls depend on each other and how the full agent workflow executed.

Before you begin

Set up AI Observability for your agent before you instrument graph relationships. For framework-based agents, refer to Instrument agents with frameworks. For direct generation export, refer to Get started with Grafana AI Observability.

To view useful graphs, your agent must send one of the following:

parent_generation_ids on generations, for the Dependencies graph.
Workflow steps with parent_step_ids and linked_generation_ids, for the Workflow graph.

Workflow-step export and automatic framework capture are available only in SDKs and framework integrations that support workflow steps. If your SDK doesn’t support workflow steps yet, instrument generation dependencies first so you can use the Dependencies graph.

Choose the right graph

Use Dependencies when you need to inspect relationships between LLM calls. Each node is one generation, and each edge comes from parent_generation_ids. This is the right view for multi-agent handoffs, chained model calls, or calls that cross services and processes.

Use Workflow when you need to inspect the higher-level execution path around the LLM calls. Each node is a workflow step, for example, routing, planning, retrieval, validation, or tool orchestration. A workflow step can wrap zero, one, or many generations.

You don’t need to choose only one. A production agent often benefits from both:

Workflow:    classify request -> retrieve context -> analyze evidence -> summarize response
Dependencies:          gen_classify -> gen_analyze -> gen_summary

In this example, Workflow shows the full orchestration, including retrieval. Dependencies shows how the LLM calls depend on each other.

Instrument generation dependencies

Add parent_generation_ids when one generation depends on the output of another generation. Pass the upstream generation ID into the downstream call and set it as a parent.

This works well when:

One agent hands work to another agent.
A planner generation creates work for a worker generation.
A reviewer generation evaluates or rewrites a previous generation.
A downstream service receives a generation ID over the wire and continues the same logical flow.

AI Observability uses these IDs to build the Dependencies DAG. The tab is available for every conversation. If no parents are declared, it still shows the generations as independent nodes.

Capture workflow steps

Use workflow steps when you want to show non-LLM execution nodes in the conversation detail view. This is useful for agent frameworks and custom orchestrators where important work happens outside a model call.

Capture a workflow step for each meaningful execution node. Include:

step_name, such as classify, retrieve_context, validate_answer, or summarize.
parent_step_ids, to connect the step to upstream workflow steps.
linked_generation_ids, to connect the step to the LLM generations that ran inside it.
agent_name and agent_version, to make the workflow easier to compare across releases.

Some framework adapters can capture workflow steps automatically when workflow-step capture is enabled. If your SDK supports workflow-step export and you use a custom orchestration layer, send workflow steps manually with the core SDK. If your SDK doesn’t support workflow-step export yet, use parent_generation_ids to model the generation DAG until workflow-step support is available.

Open the graph views

Navigate to Conversations in the AI Observability plugin and open a conversation.

Use Dependencies to inspect the generation DAG. This view helps you follow generation-level lineage and understand how quality signals move through multi-agent handoffs.

Use Workflow to inspect the agent execution graph. This tab appears when the conversation includes workflow-step telemetry. It helps you understand routing, planning, retrieval, validation, tool orchestration, duration, and errors around the LLM calls.

You read workflow steps as part of the conversation detail, alongside the generations they link to. There’s no separate query for workflow steps on their own — open a conversation to see its steps.

For a full UI reference, refer to Browse and debug conversations.

Debug workflow runs

Start with Workflow when you need to understand where the agent spent time or which orchestration step failed. Look for errored steps, long-running steps, missing outputs, or unexpected branches.

Then use Dependencies to inspect the LLM calls involved in that failure. Check the generation inputs, outputs, tool calls, token usage, latency, and evaluation scores. If an upstream generation fails an evaluation, downstream generations can explain how that failure affected the rest of the flow.

For example, if a final answer is low quality, the workflow graph may show that the retrieval step completed successfully but linked to a generation with irrelevant context. The dependency DAG then helps you inspect which downstream generation used that context.

Compare workflow versions

Set a stable agent_version when you change prompts, tools, or workflow structure. This lets AI Observability group related generations and workflow steps by release.

Use version comparisons to answer questions such as: