Getting Started with ADK 2.0 Graph Workflows

Standard orchestration classes (SequentialAgent, ParallelAgent, LoopAgent) cover common agentic interaction patterns, but complex enterprise processes demand graph-based workflows. For domains like financial transaction processing, regulatory compliance, or order fulfillment, you need deterministic state machines with explicit, programmable routing.

ADK 2.0 introduces the Workflow API — a graph-based orchestration engine that combines non-deterministic LLM reasoning nodes with deterministic Python routing logic.

Core Concepts of Graph Workflows

A graph workflow is defined as a directed graph composed of Nodes connected by Edges:

• Nodes: Execution units representing LLM agents, Python functions, or tool calls.
• Edges: Direct connections governing the flow of execution state between nodes.
• State Object: A strongly-typed class or dictionary-based data structure passed sequentially or in parallel from node to node.
• Conditional Edges: Python functions that inspect state attributes and programmatically determine the next active node.

[!NOTE] The ADK 2.0 Workflow API requires Python 3.11+ and google-adk >= 2.0.0.

Architectural Comparison: Graphs vs. Class-Based Agents

When deciding between standard agent primitives and graph workflows, consider the level of determinism and state isolation required:

Pattern	Branching Mechanism	State Management	Determinism	Best Use Case
SequentialAgent	None (Linear flow)	Implicit (Context pass-through)	Full	Multi-step linear tasks (e.g., draft & edit)
ParallelAgent	None (Concurrent execution)	Implicit (Isolated branches)	Full	Independent data retrieval or analysis
LoopAgent	Evaluates loop exit condition	Implicit	Bounded	Iterative refinement (e.g., code linting)
Graph Workflow	Conditional edges & sub-graphs	Explicit state objects	Full + Auditable	Complex enterprise workflows & governance

Graphs give engineering teams explicit control over branch logic. The LLM suggests options or evaluates contextual nuance, but the application harness decides the path — a non-negotiable requirement in regulated environments.

Conditional Routing in Action

A primary advantage of the Workflow API is branching based on dynamic state evaluation. For example, consider processing a customer refund claim:

• Condition 1: If amount <= $100 $\rightarrow$ Route directly to AutoApproveNode
• Condition 2: If amount > $100 $\rightarrow$ Route to HumanApprovalNode (pause execution for sign-off)
• Condition 3: If transaction data is invalid $\rightarrow$ Route directly to RejectNode

This prevents the LLM from hallucinating unauthorized financial approvals. The routing logic lives in clean, testable Python code rather than inside prompt instructions.

Parallel Processing in Graphs

Graphs also excel at handling batch list processing efficiently. When an initial node outputs a collection of items (e.g., 50 accounts requiring compliance verification), the graph engine can fan out child nodes across each item in parallel, collect outputs, and merge them back into the main workflow state before proceeding to downstream steps.

Basic Graph Structure Example

Here is how you configure a fundamental graph workflow in Python using ADK 2.0 primitives:

from google.adk.workflows import WorkflowGraph, Node  # ADK 2.0

# 1. Instantiate the workflow graph container
graph = WorkflowGraph(name="refund_processing_workflow")

# 2. Define workflow nodes
node_analyze = Node(name="analyze", description="Extract claim metadata")
node_approve = Node(name="approve", description="Execute instant refund")
node_reject  = Node(name="reject", description="Issue rejection notice")

# 3. Register nodes within the graph
graph.add_node(node_analyze)
graph.add_node(node_approve)
graph.add_node(node_reject)

# 4. Attach conditional routing edge
# The condition_fn evaluates state and returns the key of the target node
graph.add_edge(from_node="analyze", condition_fn=route_decision)

When to Use the Graph API

Deploy ADK Graph Workflows when your application demands:

1. Deterministic Branching: Business rules and compliance thresholds that must not be delegated to model probability.
2. Comprehensive Audit Trails: Every state transition, edge traversal, and node mutation is logged and verifiable.
3. Sub-graph Composition: Modular, nested workflow components that can be reused across multiple business units.
4. Human-in-the-Loop (HITL) Nodes: Suspended workflow states awaiting explicit human sign-off before proceeding with sensitive actions.

Key Takeaways

Graph workflows represent the most resilient and flexible orchestration primitive in ADK 2.0. By decoupling LLM reasoning from decision-tree routing, you gain full auditability for high-stakes enterprise applications. For simpler, linear tasks, SequentialAgent and ParallelAgent remain lightweight and effective choices.

Next Up: A step-by-step tutorial on building an approval and refund graph workflow.