Build graph workflows with explicit control flow

Learning objective

Build a graph workflow when correctness requires conditional branches, joins, and explicit control flow. This lesson focuses on fixed graph topology and enforced transitions, not open-ended planning or model-driven routing.

Core idea

Treat a graph workflow as an executable control-flow contract:

• nodes perform bounded work;
• edges define which transitions are permitted;
• routers activate edges from validated outcomes; and
• joins define when several incoming paths are complete enough to continue.

The graph, not an agent prompt, owns the process. A node can contain an agent, tool, code function, or human task, but it cannot choose an undeclared next step. This separation lets you combine probabilistic reasoning inside nodes with predictable orchestration between them.

Agent Development Kit (ADK) graph workflows represent logic as execution nodes and edges. Nodes can contain AI agents, tools, functions, and nested workflows. Use a graph when a linear list or one parallel block cannot express the required paths.

How it works

Define nodes as contracts

Give each node a single responsibility, typed inputs and outputs, and success and error contracts. Keep rule evaluation in code when business facts fully determine the answer. Use an agent only for semantic judgment.

Pass a node’s result as structured data rather than relying on conversational history. The ADK data-handling guidance distinguishes a node’s downstream output from user-visible content and session state. This distinction prevents routing logic from parsing prose and makes each edge testable.

Make every branch total and explicit

A router evaluates a named field, status, or predicate and selects an outgoing edge. Define whether it selects exactly one path or several paths:

• An exclusive branch activates one alternative, such as ELIGIBLE or INELIGIBLE.
• A multi-select branch activates every applicable path, such as separate compliance checks for several jurisdictions.
• A default or error branch handles missing, malformed, or unknown route values.

ADK route nodes emit a route value that declared edges map to target nodes, as shown in the graph routes documentation. If a model supplies the classification, constrain and validate its result before routing. The graph limits the available destinations, but an explicit edge does not make the model’s classification deterministic.

Give each convergence point a policy

Do not treat every node with several incoming edges as the same kind of join. Two common convergence semantics are:

• A merge continues after whichever mutually exclusive path ran. It does not wait for paths that the router did not activate.
• A synchronizing join waits for all required parallel predecessors, or for another declared completion rule, before it releases downstream work.

ADK’s JoinNode is a synchronizing fan-in barrier: it waits for every predecessor and passes the next node a record keyed by predecessor name. Wire only predecessors that are guaranteed to run for that join. Otherwise, an untaken exclusive branch can leave the barrier waiting for work that never started.

At every join, define branch identities, required versus optional results, timeouts, failure policy, and output schema. Aggregate by branch identity, not arrival order. Implement quorum or first-success as a different control rule.

Key distinctions and trade-offs

Google Cloud’s custom logic pattern fits complex branching that goes beyond a direct sequence and mixes fixed rules with model reasoning. The benefit is fine-grained control and auditable paths. The cost is more topology, contracts, test cases, and failure states to maintain.

Explicit control flow does not guarantee deterministic node output, durable execution, exactly-once side effects, or rollback. Add checkpoints, idempotency, compensation, and recovery when the process requires them.

Architecture / decision scenario

An insurer automates low-value claims. The system first validates the claim and uses policy rules to route invalid submissions to an explanation path. For an eligible claim, it starts coverage and fraud checks. Neither check depends on the other, but payment requires both, so an all-required join waits for their named results.

A deterministic decision node then applies thresholds. A passing claim goes to the payment node; an uncertain claim goes to human review. Both alternatives merge into one response node. Payment uses an idempotency key, and a failed check does not silently become a partial approval.

The claim graph branches on eligibility, joins the two parallel checks, and merges the exclusive alternatives into one response.

The diagram contains both kinds of convergence. J synchronizes two paths that run together. O merges alternatives because only one outcome path reaches it on a given execution.

A sequence would either run unnecessary work or need hidden conditionals. A single parallel template would not express the rejection and review paths. A model-driven coordinator would add variability to decisions already defined by policy. The graph makes every permitted route and synchronization point visible and testable.

Common exam traps

• Choosing a graph only because the workflow has many steps; a sequence is simpler when every run follows the same line.
• Confusing a merge of exclusive alternatives with a join that waits for every parallel predecessor.
• Omitting a default or error route and letting an unknown route value continue unpredictably.
• Assuming explicit edges make model outputs or model-selected classifications deterministic.
• Joining by completion order instead of predecessor identity and schema.
• Treating graph topology as automatic durability, exactly-once execution, or transaction rollback.
• Routing consequential actions from unvalidated natural-language output.

What to remember

• Model the graph as nodes that do work, edges that permit movement, routers that activate paths, and joins that enforce completeness.
• Use a merge for exclusive alternatives and a barrier for required parallel work.
• Define every route, default, join policy, data contract, and failure outcome explicitly.
• Keep deterministic policy in code and constrain any model result used for routing.
• Add durability and side-effect safety separately; the graph supplies control flow, not transaction guarantees.

Knowledge check

References

• Agent Development Kit, Graph-based agent workflows
• Agent Development Kit, Build graph routes for agent workflows
• Agent Development Kit, Data handling for agent workflows
• Google Cloud Architecture Center, Choose a design pattern for your agentic AI system