# Google ADK 2.0 Tutorial: Graph Workflows and Multi-Agents

> A hands-on Google ADK 2.0 tutorial: build a procurement approval graph with routes and human approval, persist sessions across restarts, choose between graph, dynamic and collaborative workflows, test it, and migrate from 1.x.

URL: https://www.matthewswong.com/en/blog/google-adk-2-graph-workflows-tutorial/

- Author: Matthews Wong (https://www.matthewswong.com/en/about/)
- Published: 2026-10-01
- Updated: 2026-10-01
- Category: AI

> **Key takeaway:** Google ADK 2.0 turns agents, tools and functions into nodes of a workflow graph. Use a graph Workflow when the routing rules are known, such as approval thresholds, and keep the LLM for the one step that needs judgement. Always map DEFAULT_ROUTE, because an unmatched route ends the run silently with no error.

The first version of our procurement assistant let the model decide who approved a purchase. It read the request, guessed the amount band and transferred to a manager or director agent. It was right most of the time, which is the wrong standard for a rule the finance team had already written down as two numbers: under 5 million rupiah is automatic, under 50 million needs a manager, anything above needs a director.

This Google ADK 2.0 tutorial rebuilds that flow on the new graph engine, where the LLM only extracts the request and plain Python does the routing. I ran every snippet against google-adk 2.10.0 on Python 3.11, with the intake agent swapped for a function stub so the deterministic path could run without a model. Where the behaviour surprised me, the post says so; everything else traces to the official ADK 2.0 docs.

## What changed in ADK 2.0: agents became nodes

ADK 2.0 replaced hierarchical agent execution with a graph engine. Agents, tools and plain functions are all nodes, and BaseAgent now extends BaseNode. Python reached GA on 19 May 2026, Go on 30 June 2026 and TypeScript on 21 August 2026, and Python has shipped a minor release roughly every two weeks since, reaching 2.10.0 in late September. The release gives you three ways to compose nodes.

| Workflow type | How you write it | Who decides the next step | Use it for |
| --- | --- | --- | --- |
| Graph workflow | Workflow with an edges list and route maps | Your code, through Event route values | Rules you can write down: thresholds, statuses, fixed pipelines |
| Dynamic workflow | An async function decorated with node that calls ctx.run_node | Your code, with loops and conditionals | Variable-length chains and retries that would clutter a graph |
| Collaborative workflow | A coordinator Agent with sub_agents in chat, task or single_turn mode | The coordinator model, through generated delegation tools | Open-ended work where the plan is not known in advance |

The question that picks the row is simple: could a junior analyst follow the rule from a written policy? If yes, it belongs in a graph or a dynamic workflow, and the model should not be the one choosing the branch. The approval thresholds pass that test, so they go in code. Turning a vague message into a vendor, an amount and a cost centre does not, so that step stays with the model.

## Google ADK 2.0 tutorial: a procurement approval graph

The whole policy fits in one Workflow. The edges list reads top to bottom: START feeds the intake agent, its structured output feeds the amount router, and each route value maps to a branch. Every approval branch converges on a second router that splits approved from rejected.

Three details carry the design. The intake agent uses output_schema, so the router receives a validated PurchaseRequest rather than prose. ADK coerces each node_input to the parameter's type annotation, which is why a node can return a plain dict and the next one still gets a model. And route_by_amount writes the request into ctx.state, so create_po can read the vendor two hops later without threading it through every return value.

> Test the graph without a model first. I replaced intake_agent with a five-line function that parsed JSON into a PurchaseRequest and drove all three bands through the Runner: 1.2 million auto-approved, 12 million paused at the manager node, 80 million paused at the director node. A node is a node, so the stub slots into the same edges list.

## Pausing for a human with RequestInput

A manager does not answer in milliseconds, so the approval node cannot block. Yielding RequestInput ends the current run and emits an event whose content is a function call named adk_request_input, carrying the message, your payload and an interrupt id that is also listed in long_running_tool_ids. To resume, send a function response with that id back into the same session.

- The reply is handed to the successor node, not to the node that paused, so manager_approval never runs a second time. That is the default for function nodes, where rerun_on_resume is false.
- response_schema is enforced on the way back in. A reply of approved set to maybe made run_async raise WorkflowDataError with the Pydantic errors, so wrap the resume call and send the error back to your approval UI.
- Defaults do not survive the round trip. My first Decision model had note as str with an empty-string default; the resumed value carried note as None, and the annotated decision_router failed with a ValidationError event. Declaring note as optional with a None default fixed it.

## The route nobody mapped ends the run silently

This is the failure I would most like someone to have warned me about. When a router returns a route value that is not a key in its map, ADK does not raise and does not emit an error event. The router's output event appears, and then the run just ends. In a test I returned an unmapped value and got exactly one event back.

> An LLM classifier that answers Manager instead of MANAGER, or a fourth approval tier added to the router but not to the map, will quietly drop requests on the floor. Map DEFAULT_ROUTE, imported from google.adk.workflow, on every route dictionary and send it somewhere a human looks. With the default in place, the same unmapped value ran the fallback node as expected.

## Sessions that survive a restart

Pausing is only useful if the pause outlives the process. InMemorySessionService loses everything on restart, so production needs DatabaseSessionService. I created a session, ran it to the manager interrupt, then built a brand-new service and Runner on the same SQLite file and sent the approval. The workflow resumed at record_decision with the request still in state.

Getting there cost me one misleading error. The db extra installs SQLAlchemy, which resolved to 2.1.1, and the asyncio layer of that release needs greenlet, which nothing pulled in. ADK reported only that it failed to create the database engine; the real cause was an ImportError underneath. Installing greenlet fixed it. The event rows also show why custom session stores break on 2.0: node_info and output now sit inside every stored event, and a validator that rejects unknown properties will reject them.

## When the graph is wrong: dynamic and collaborative workflows

A real approval matrix is rarely three fixed boxes. Above 500 million rupiah our chain adds a CFO, and drawing a graph for every chain length gets ugly quickly. A dynamic workflow expresses it as a loop, with each approval delegated to a child node through ctx.run_node.

The trace in the comment is from a real run and it is the thing to understand: on every resume the orchestrator body starts again from the top, and finished children return their stored answers instead of pausing again. The checkpointing lives in the children. Anything with a side effect, such as an email, an ERP write or a counter, must be its own node, or it will fire once per resume. When the work itself is open-ended, such as finding vendors and collecting quotes, a coordinator with subagents fits better.

- chat is the default mode: the subagent talks with the user and must hand control back explicitly.
- task allows clarifying questions and returns automatically when finished. It cannot have its own subagents and is disabled inside graph workflows in Python 2.0.
- single_turn allows no user interaction, returns immediately and is the only mode that can run in parallel.

The coordinator gets one generated tool per subagent, named after it, and task and single_turn agents run in isolated session branches, so parallel siblings cannot see each other's work. Do not set a mode on the root agent. The model chooses which subagent to call, which is exactly why approvals stay in the graph and sourcing goes here.

## Testing the graph and evaluating the agent

Split the testing along the same line as the design. Deterministic nodes are ordinary Python functions, so test them with pytest and no API key. The one model-backed node is where adk eval earns its place: tool_trajectory_avg_score compares tool calls against an expected list, and response_match_score compares the final answer.

The trajectory criterion defaults to a threshold of 1.0 with an exact match, meaning no extra or missing calls. IN_ORDER accepts extra calls between the expected ones, and ANY_ORDER ignores sequence, so pick the loosest mode that still catches the regression you care about. response_match_score defaults to 0.8. For the intake agent I care that it never skips the vendor lookup, so IN_ORDER is the honest setting.

## Migrating from ADK 1.x without breaking sessions

Most 1.x agents keep working, but four changes bite in practice.

1. Update custom session stores and strict JSON validators for the new Event fields: node_info, output, route and isolation scope in every language, plus RequestedInput in Go.
2. In Python, overrides of _run_async_impl are bypassed. Move that logic into before and after agent callbacks, yield events instead of appending to context.session.events, and stop catching BaseException so retries can work.
3. In Go, change the module path to google.golang.org/adk/v2 and pass the context as the first argument to session.NewEvent.
4. In TypeScript, SequentialAgent, ParallelAgent and LoopAgent are deprecated in favour of graph workflows, and InvocationContext.agent may now be undefined.

> ADK is open source under Apache 2.0, with google-adk on PyPI and @google/adk on npm, plus Go, Java and Kotlin ports. For an existing database-backed session store, adk migrate session copies a source database to a destination URL at the latest schema version.

The rule I took from the rebuild: let the model read, let the code decide. In ADK 2.0 that is a Workflow whose only LLM node turns text into a schema, with every threshold in a route map that has a DEFAULT_ROUTE. Persist sessions in a database before the first human pause, and keep side effects in child nodes so a resume cannot repeat them.

## Sources

- ADK 2.0 overview, release dates and migration notes (adk.dev)
- Graph-based agent workflows (adk.dev)
- Human input in workflows: RequestInput (adk.dev)
- Collaborative workflows and subagent modes (adk.dev)
- Evaluation criteria: tool trajectory match types (adk.dev)

## Source links

- https://adk.dev/2.0/
- https://adk.dev/graphs/
- https://adk.dev/graphs/human-input/
- https://adk.dev/workflows/collaboration/
- https://adk.dev/evaluate/criteria/

## FAQ

### What is new in Google ADK 2.0?

ADK 2.0 replaces hierarchical agent execution with a graph engine in which agents, tools and functions are all nodes, and BaseAgent now extends BaseNode. It adds graph-based, dynamic and collaborative workflows. Python reached GA on 19 May 2026, Go on 30 June 2026 and TypeScript on 21 August 2026.

### When should I use a graph workflow instead of letting the LLM route?

Use a graph workflow whenever the routing rule can be written down, such as approval thresholds, document statuses or a fixed pipeline. Keep the model for steps that need judgement, like turning a free-text request into structured fields. A deterministic route is testable with plain pytest and never drifts between runs.

### How do I pause an ADK 2.0 workflow for human approval?

Yield RequestInput from a function node with a message, an optional payload and an optional response_schema. The run ends with an adk_request_input function call carrying an interrupt id. Resume by sending a function response with that id to the same session, and the reply becomes the input of the next node.

### What happens when an ADK router returns a route that is not mapped?

In google-adk 2.10.0 the run simply ends after the router's output event, with no exception and no error event. Add DEFAULT_ROUTE from google.adk.workflow to every route map and point it at a fallback node that a human monitors. That catches casing drift from LLM classifiers and newly added tiers.

### What breaks when migrating from ADK 1.x to 2.0?

Custom session stores and strict validators must accept new Event fields such as node_info and output. In Python, _run_async_impl overrides are bypassed in favour of callbacks, and in Go the import path moves to google.golang.org/adk/v2 with NewEvent taking a context first. TypeScript deprecates SequentialAgent, ParallelAgent and LoopAgent.

---

- HTML version: https://www.matthewswong.com/en/blog/google-adk-2-graph-workflows-tutorial/
- Bahasa Indonesia: https://www.matthewswong.com/id/blog/google-adk-2-graph-workflows-tutorial/
- Site index for agents: https://www.matthewswong.com/llms.txt
- Sitemap: https://www.matthewswong.com/sitemap.xml
- API description (OpenAPI): https://www.matthewswong.com/openapi.json
