Workflows (graph orchestration)
Compose agents and functions into a DAG with conditional routing, retries, timeouts, HITL, and state schemas.
Verified against google-adk 2.13.0 (google/adk/workflow/), checked 2026-11-19. The examples were run against a stub model that stands in for Gemini. The human-in-the-loop helpers changed after 2.10 (see that section).
Workflow is the graph-based orchestrator that replaces SequentialAgent, ParallelAgent, and LoopAgent in ADK 2.x. It is a BaseNode (not a BaseAgent). Wire it to a Runner with App(root_agent=workflow), which is also where plugins and resumability go; Runner(agent=workflow, ...) and Runner(node=workflow, ...) work too.
Public surface
Section titled “Public surface”google.adk.workflow exports (workflow/__init__.py):
| Name | Purpose |
|---|---|
Workflow | Graph orchestrator. Takes edges=[...] and runs the DAG. |
BaseNode | Pydantic base for every node. |
Node | Subclass-friendly base — implement run_node_impl. |
node | Decorator / function to wrap a callable, agent, or tool as a BaseNode. |
FunctionNode | What @node produces for a function. |
JoinNode | Fan-in — waits for all predecessors before emitting. |
Edge | Explicit from_node → to_node, optional route. |
RetryConfig | Per-node retry policy. |
NodeTimeoutError | Raised when a node exceeds its timeout. |
START | Sentinel for the graph entry point. |
DEFAULT_ROUTE | Matches routes with no explicit mapping. |
Minimal example
Section titled “Minimal example”import asynciofrom google.adk.agents import LlmAgentfrom google.adk.apps import Appfrom google.adk.runners import InMemoryRunnerfrom google.adk.workflow import Workflow, node, START
drafter = LlmAgent( name="drafter", model="gemini-3.8-flash", instruction="Write a tight 3-sentence summary of the input.", mode="single_turn",)polisher = LlmAgent( name="polisher", model="gemini-3.8-flash", instruction="Shorten and sharpen the input. Return only the final text.", mode="single_turn",)
@nodedef trim(node_input: str) -> str: return node_input.strip()
pipeline = Workflow( name="summarize_pipeline", edges=[(START, trim, drafter, polisher)],)
async def main(): app = App(name="demo", root_agent=pipeline) runner = InMemoryRunner(app=app) await runner.session_service.create_session( app_name="demo", user_id="u1", session_id="s1" ) events = await runner.run_debug( "Electric cars sold well in Q1.", user_id="u1", session_id="s1" )
asyncio.run(main())A tuple in edges= is a chain — each adjacent pair becomes an Edge. START is the sentinel that receives new_message on invocation.
Edge syntax
Section titled “Edge syntax”Four ways to declare edges:
1. Chain (tuple)
Section titled “1. Chain (tuple)”edges = [(START, a, b, c)] # START→a, a→b, b→c2. Fan-out (nested tuple)
Section titled “2. Fan-out (nested tuple)”edges = [(START, (a, b, c), join)] # START fans out to a/b/c, all feed join3. Routing map (dict)
Section titled “3. Routing map (dict)”edges = [ (START, classifier, {"billing": billing_agent, "support": support_agent}),]Edges carry a route value. The source node picks one by setting ctx.route = "billing" (in a FunctionNode) or by the router’s output matching a key. Use DEFAULT_ROUTE for the fallback.
4. Explicit Edge
Section titled “4. Explicit Edge”from google.adk.workflow import Edgeedges = [Edge(from_node=a, to_node=b, route="yes")]Mix them freely. BaseAgent, BaseTool, and plain callables are auto-wrapped via build_node() when they appear in an edge.
build_node() — automatic node conversion
Section titled “build_node() — automatic node conversion”build_node is an internal helper that converts any NodeLike value (callable, LlmAgent, BaseTool, or Workflow) into a concrete BaseNode. The edge parser calls it automatically whenever you place an agent, callable, or tool directly in an edge — you do not import or call it yourself. Understanding its mode-defaulting rules helps you predict how the edge parser will configure each node.
from google.adk.workflow import Workflow, STARTfrom google.adk.agents import LlmAgent
writer = LlmAgent( name="writer", model="gemini-3.8-flash", instruction="Summarise the input in one sentence.",)
# Place the agent directly in an edge — the edge parser calls build_node()# internally, defaulting mode to 'single_turn' (no parent_agent provided).wf = Workflow(name="demo", edges=[(START, writer)])Mode defaulting rules applied by build_node (for reference):
| Input | mode result |
|---|---|
LlmAgent with mode=None, no parent_agent | 'single_turn' |
LlmAgent with mode=None, parent_agent provided | 'chat' |
LlmAgent with mode='task' or mode='chat' | forces wait_for_output=True |
LlmAgent in single_turn mode, include_contents not set | sets include_contents='none': the node sees only its input, not the conversation |
Any LlmAgent | defaults rerun_on_resume=True |
To control the mode explicitly, set it on the LlmAgent before placing it in the edge:
from google.adk.workflow import Workflow, STARTfrom google.adk.agents import LlmAgent
# Explicitly set mode so build_node() preserves it rather than defaultingwriter = LlmAgent(name="writer", model="gemini-3.8-flash", instruction="Summarise the input.", mode="single_turn")
wf = Workflow(name="demo", edges=[(START, writer)])Nested workflows. A Workflow is itself a BaseNode and can appear inside another Workflow’s edge list. This lets you compose large pipelines from reusable sub-pipelines:
from google.adk.workflow import Workflow, node, START
@nodedef validate(node_input: str) -> str: if not node_input.strip(): raise ValueError("empty input") return node_input
@nodedef publish(node_input: str) -> dict: return {"published": True, "content": node_input}
# Inner pipeline — reusable unitinner = Workflow( name="inner_pipeline", edges=[(START, validate)],)
# Outer pipeline — nests inner as a nodeouter = Workflow( name="outer_pipeline", edges=[(START, inner, publish)], # Workflow is already BaseNode; edge parser accepts it directly)@node decorator
Section titled “@node decorator”from google.adk.workflow import node, RetryConfig
@nodeasync def fetch(node_input: str, ctx) -> dict: ctx.state["last_query"] = node_input return {"query": node_input, "results": [...]}
@node( name="safe_fetch", retry_config=RetryConfig(max_attempts=3), timeout=10.0, rerun_on_resume=True,)async def safe_fetch(node_input: str, ctx): ...RetryConfig fields
Section titled “RetryConfig fields”RetryConfig lives in google.adk.workflow and implements exponential backoff with jitter. All fields are optional — omitting them uses the stated defaults:
| Field | Default | Description |
|---|---|---|
max_attempts | 5 | Total attempts including the first. Set to 0 or 1 for no retries. |
initial_delay | 1.0 s | Delay before the first retry. |
max_delay | 60.0 s | Cap on inter-retry delay. |
backoff_factor | 2.0 | Multiplier applied after each failure. |
jitter | 1.0 | Randomness injected into delay (0.0 = no jitter). |
exceptions | None | List of exception class names or classes to retry on. None = retry on any exception. |
from google.adk.workflow import RetryConfig, node, Workflow, START
# Retry only on network-related errors, up to 4 attempts with exponential backoff@node( retry_config=RetryConfig( max_attempts=4, initial_delay=0.5, max_delay=30.0, backoff_factor=2.0, jitter=0.5, exceptions=["httpx.TimeoutException", "httpx.ConnectError", "ConnectionError"], ), timeout=15.0, # NodeTimeoutError if the node takes > 15s rerun_on_resume=True,)async def resilient_fetch(node_input: str, ctx) -> dict: import httpx async with httpx.AsyncClient() as client: resp = await client.get(node_input, timeout=10.0) # node_input is the URL resp.raise_for_status() return resp.json()
pipeline = Workflow( name="fetch_pipeline", edges=[(START, resilient_fetch)],)NodeTimeoutError is raised when a node exceeds its timeout, and it counts as a failure for retries: with exceptions=None a timed-out node is retried, and with an exceptions list it is retried only if "NodeTimeoutError" is in the list. The worst-case time for a node is therefore roughly max_attempts × timeout plus the delays between attempts.
Signatures recognised by FunctionNode:
node_input— the incoming value (the predecessor’s output, or the user’snew_messagefor START successors).ctx— theContext(state,run_node,route,interrupt, artifact helpers).- Any other parameter is read from session state by name. A missing key without a default fails the node with
WorkflowDataError: Missing value for parameter ..., and if the workflow has astate_schemathe name must be one of its fields (checked when theWorkflowis built). A common mistake is naming the input after its meaning (draft,url) instead ofnode_input: that parameter is then looked up in state.
That is the default parameter_binding="state". With @node(parameter_binding="node_input") the parameters are filled from the fields of a dict/Pydantic node_input instead, and input_schema/output_schema are inferred from the signature (this is the mode used when a node acts as an agent’s tool):
@node(parameter_binding="node_input")def greet(name: str, greeting: str = "Hello") -> str: return f"{greeting}, {name}!" # called with node_input={"name": "Alice"}Values are coerced to the annotations with a Pydantic TypeAdapter: a dict becomes the annotated BaseModel, a list[dict] becomes list[Model], and a types.Content (such as the user’s message reaching a START successor) becomes str when the parameter expects one.
Return types are honoured: returning a value sets ctx.output; yielding values from an async generator lets you stream partials.
Node subclass
Section titled “Node subclass”Use when you need a node with its own fields and logic:
from google.adk.workflow import Nodefrom collections.abc import AsyncGeneratorfrom typing import Any
class DedupeNode(Node): name: str = "dedupe" seen: set[str] = set()
async def run_node_impl(self, *, ctx, node_input: list[str]) -> AsyncGenerator[Any, None]: fresh = [x for x in node_input if x not in self.seen] self.seen.update(fresh) yield freshparallel_worker=True (on Node or @node) makes the node a map step: given a list as input, it runs once per item in parallel and outputs the list of results. max_parallel_workers caps how many run at once.
Workflow fields
Section titled “Workflow fields”| Field | Type | Default | Notes |
|---|---|---|---|
name | str | required | Must be a Python identifier |
edges | list[EdgeItem] | [] | Tuples or Edge objects |
max_concurrency | int | None | None | Caps concurrent graph-scheduled nodes |
state_schema | type[BaseModel] | None | Validates ctx.state mutations |
rerun_on_resume | bool | True | Workflow-level resume behaviour |
input_schema / output_schema | SchemaType | None | Validates workflow-level in/out |
All fields from BaseNode (retry_config, timeout, wait_for_output, …) apply too.
Workflow — max_concurrency and state_schema in action
Section titled “Workflow — max_concurrency and state_schema in action”Source-verified against google.adk.workflow._workflow.Workflow and its _validate_state_schema method (first verified in 2.7.1; re-checked against 2.13.0). Two fields deserve dedicated coverage because they change failure modes at graph-build time (state_schema) and at runtime (max_concurrency).
from pydantic import BaseModel, Fieldfrom google.adk.workflow import Workflow, node, START
# ── State schema is a Pydantic model. Every FunctionNode parameter that is# not `ctx` / `node_input` / `self` must appear as a field here, or the# Workflow raises StateSchemaError on construction — *before* it runs. ──class ResearchState(BaseModel): topic: str = Field(default="") findings: list[str] = Field(default_factory=list) iteration: int = 0
@nodeasync def search(topic: str, ctx) -> list[str]: # `topic` matches a state field → auto-injected from ctx.state at run time. results = [f"result about {topic} #{i}" for i in range(3)] # A node's return value becomes event.output — it does NOT auto-populate # ctx.state. Write to state explicitly so the next node's state-bound # `findings` parameter reads the value we just produced instead of the # schema default (empty list). ctx.state["findings"] = results return results
@nodeasync def critique(findings: list[str], ctx) -> str: # `findings` matches a state field → auto-injected from ctx.state. return "\n".join(findings)
wf = Workflow( name="research", state_schema=ResearchState, max_concurrency=4, # cap graph-scheduled parallel nodes at 4 edges=[(START, search, critique)],)# StateSchemaError would fire here if search() or critique() had a parameter# name (say, `authors`) that is not declared on ResearchState.Why the check happens at construction, not runtime. _validate_state_schema runs from model_post_init, right after _build_graph compiles the edge list. That means a mis-named parameter (typo, refactor drift) surfaces the moment you import the module — not on the ninetieth production request. The exact error message:
FunctionNode 'search' parameter 'authors' is not declared in state_schema 'ResearchState'. Declared fields: ['findings', 'iteration', 'topic']
What max_concurrency does — and does not. It caps parallelism for graph-scheduled nodes only. ctx.run_node(...) dynamic nodes are excluded from the cap because throttling them would deadlock (their parent awaits them inline). So:
- A
(START, (a, b, c, d, e, f), join)fan-out withmax_concurrency=2runsa, bin parallel, thenc, d, thene, f, thenjoin. - A single node that internally does
await asyncio.gather(*[ctx.run_node(...) for _ in range(20)])still fans out to 20 dynamic tasks regardless ofmax_concurrency.
rerun_on_resume=True (workflow level, default). When a paused workflow resumes, it rebuilds its progress from the session’s events and runs only the nodes that had not finished. Nodes default to rerun_on_resume=False: an interrupted node is completed with the resume response as its output rather than run again. Set rerun_on_resume=True on a node that needs to see the response (ctx.resume_inputs) and carry on, as in Human-in-the-loop.
Routing and conditions
Section titled “Routing and conditions”A node can steer the graph by setting ctx.route:
@nodeasync def classify(node_input: str, ctx): intent = "billing" if "invoice" in node_input.lower() else "support" ctx.route = intent return node_input
workflow = Workflow( name="triage", edges=[ (START, classify, { "billing": billing_agent, "support": support_agent, DEFAULT_ROUTE: fallback_agent, }), ],)How the next nodes are chosen after a node finishes (Graph.get_next_pending_nodes):
- Edges with no route are always followed (an unconditional fan-out).
- Edges whose route matches the emitted
ctx.routeare followed; a list route matches if any value overlaps. DEFAULT_ROUTEedges are followed only when no specific route matched.- If a node has routing edges and none matched, the branch ends with a logged warning, not an error.
Route values can be bool, int or str.
Routing on a classifier (ClassifierNode, experimental)
Section titled “Routing on a classifier (ClassifierNode, experimental)”Since 2.13.0, ClassifierNode (in google.adk.labs.classifiers) routes on a classifier’s answer instead of code you write. The classifier gets the node’s input and one question, either Choice (route is the chosen label) or Binary (route is True or False, with a threshold that defaults to 0.5). The input passes through unchanged, so the next node sees what the classifier saw. Graph validation checks that every label has an edge, unless a DEFAULT_ROUTE or unrouted edge catches the rest. Set answer_key to store the full answer, including each label’s probability, in session state.
LlmClassifier(model=...) answers the question with any ADK model, as structured output. A BaseClassifier subclass can wrap a dedicated decision model instead; ADK includes TypesafeClassifier for TypeSafe’s Jev models. The example below uses a stub model that stands in for Gemini; pass a real model name or BaseLlm in its place.
import asyncioimport json
from google.adk.labs.classifiers import Choice, ClassifierNode, LlmClassifierfrom google.adk.models.base_llm import BaseLlmfrom google.adk.models.llm_response import LlmResponsefrom google.adk.runners import InMemoryRunnerfrom google.adk.workflow import START, Workflow, nodefrom google.genai import types
class StubModel(BaseLlm): """Stands in for Gemini: always answers 'billing'.""" model: str = "stub-classifier"
async def generate_content_async(self, llm_request, stream=False): answer = {"route": {"billing": 0.9, "support": 0.1}} yield LlmResponse(content=types.Content( role="model", parts=[types.Part(text=json.dumps(answer))]))
@nodedef billing(node_input: str): return f"billing handled: {node_input}"
@nodedef support(node_input: str): return f"support handled: {node_input}"
router = ClassifierNode( name="router", classifier=LlmClassifier(model=StubModel()), question=Choice( instructions="Which team should handle this message?", criteria={"billing": "Invoices and payments", "support": "Everything else"}, ), answer_key="route_answer",)workflow = Workflow(name="triage", edges=[(START, router, {"billing": billing, "support": support})])
async def main(): runner = InMemoryRunner(agent=workflow, app_name="triage_app") session = await runner.session_service.create_session(app_name="triage_app", user_id="u1") message = types.Content(role="user", parts=[types.Part(text="Where is my invoice?")]) async for event in runner.run_async(user_id="u1", session_id=session.id, new_message=message): if event.output and isinstance(event.output, str): print(event.output) # billing handled: Where is my invoice?
asyncio.run(main())Replace LoopAgent with a routing map that either loops back to the same node or flows to a terminal node (any node with no outgoing edges). There is no END_NODE sentinel — terminality is structural.
from google.adk.workflow import Workflow, node, START
@nodeasync def critic(node_input: str, ctx) -> str: if len(node_input) <= 500: ctx.route = "done" return node_input ctx.route = "continue" return node_input[:500] # trimmed draft fed back in
@nodedef publish(node_input: str) -> str: return node_input # terminal: no outgoing edge
loop = Workflow( name="refine", edges=[ (START, critic, {"continue": critic, "done": publish}), ],)publish is the terminal node — the workflow finishes when routing lands there. Persist iteration count in ctx.state if you need max_iterations semantics, and set max_concurrency=1 to keep the loop single-threaded.
JoinNode
Section titled “JoinNode”Fan-in that waits for all declared predecessors. Useful after a (START, (a, b, c), join) fan-out.
from google.adk.agents import LlmAgentfrom google.adk.workflow import JoinNode, Workflow, node, START
a = LlmAgent(name="a", model="gemini-3.8-flash", instruction="Reply 'A'.", mode="single_turn")b = LlmAgent(name="b", model="gemini-3.8-flash", instruction="Reply 'B'.", mode="single_turn")
join = JoinNode(name="merge")
@nodedef finalize(node_input: dict) -> str: # node_input is a dict keyed by predecessor name return f"A={node_input['a']} B={node_input['b']}"
wf = Workflow( name="fanin", edges=[(START, (a, b), join, finalize)],)JoinNode receives a dict of {predecessor_name: output} as its node_input.
Dynamic nodes (ctx.run_node)
Section titled “Dynamic nodes (ctx.run_node)”Call another node from inside a node — the result is awaited in place. The caller must have rerun_on_resume=True, or run_node raises ValueError: A node must have rerun_on_resume=True: if the child pauses, the workflow resumes by running the parent again.
@node(rerun_on_resume=True)async def supervisor(node_input: str, ctx): research = await ctx.run_node(research_agent, node_input) answer = await ctx.run_node(writer_agent, research) return answerHuman-in-the-loop
Section titled “Human-in-the-loop”Yield a RequestInput from a node to pause the workflow. The run ends with an adk_request_input function call whose ID is the interrupt_id; the workflow resumes when Runner.run_async is called again on the same session with a FunctionResponse of that ID and name. With rerun_on_resume=True the node runs again and finds the response in ctx.resume_inputs[interrupt_id]; without it, the response itself becomes the node’s output. yield does not return the answer: the node is re-run instead.
import asyncio
from google.adk.apps import Appfrom google.adk.events import RequestInputfrom google.adk.runners import InMemoryRunnerfrom google.adk.workflow import START, Workflow, nodefrom google.genai import types
@nodedef draft(node_input: str) -> str: return f"Draft post about {node_input}"
@node(rerun_on_resume=True)def approve(node_input: str, ctx): decision = ctx.resume_inputs.get("approval") if decision is None: # first run: ask and pause yield RequestInput(interrupt_id="approval", message=f"Publish this? {node_input}") return ctx.route = "publish" if decision.get("approved") else "rewrite" yield node_input
@nodedef publish(node_input: str) -> str: return f"published: {node_input}"
@nodedef rewrite(node_input: str) -> str: return "sent back for rewriting"
review = Workflow( name="review", edges=[(START, draft, approve, {"publish": publish, "rewrite": rewrite})],)
async def main(): runner = InMemoryRunner(app=App(name="review_app", root_agent=review)) session = await runner.session_service.create_session(app_name="review_app", user_id="u1")
pending = None async for event in runner.run_async( user_id="u1", session_id=session.id, new_message=types.Content(role="user", parts=[types.Part(text="pricing")]), ): for call in event.get_function_calls(): if call.name == "adk_request_input": pending = call.id # == the interrupt_id print("paused:", call.args["message"])
answer = types.Content(role="user", parts=[types.Part(function_response=types.FunctionResponse( id=pending, name="adk_request_input", response={"approved": True}, ))]) async for event in runner.run_async(user_id="u1", session_id=session.id, new_message=answer): if event.output is not None: print(event.output)
asyncio.run(main())Pair with auth_config= on the @node to gate a node on an OAuth flow instead of a free-form answer. For pauses that can outlast the process, use a persistent session service (next section).
Retries and timeouts
Section titled “Retries and timeouts”from google.adk.workflow import node, RetryConfig
@node(retry_config=RetryConfig(max_attempts=3, backoff_factor=2.0), timeout=30.0)async def flaky(node_input: str, ctx): ...A node that exceeds timeout is cancelled and raises NodeTimeoutError. If retries are configured, the node is restarted.
Patterns
Section titled “Patterns”1 — Linear pipeline
Section titled “1 — Linear pipeline”edges=[(START, step1, step2, step3)] — direct replacement for SequentialAgent.
2 — Map-reduce
Section titled “2 — Map-reduce”edges=[(START, split, (worker1, worker2, worker3), join, summarize)] — fan-out with JoinNode.
3 — Router → specialist fleet
Section titled “3 — Router → specialist fleet”classify node sets ctx.route to a string; routing map fans to the matching agent; optional DEFAULT_ROUTE catches unknowns.
4 — Retry-aware scraper
Section titled “4 — Retry-aware scraper”Wrap the scraper with retry_config=RetryConfig(max_attempts=5) and timeout=20. Log retries via LoggingPlugin on the App.
5 — HITL review gate
Section titled “5 — HITL review gate”Insert a @node(rerun_on_resume=True) that yields RequestInput between producer and publisher, as in Human-in-the-loop. The workflow pauses, the event is persisted, and Runner.run_async resumes it when the answer arrives. Since 2.12.0, @node(require_confirmation=True) does the same for a plain yes/no approval before a node runs.
6 — state_schema — validated shared state
Section titled “6 — state_schema — validated shared state”Pass a Pydantic BaseModel class as Workflow.state_schema. The framework validates every ctx.state write against it and raises StateSchemaError on unknown keys. Schema fields can be injected directly as @node function parameters.
from pydantic import BaseModelfrom google.adk.workflow import Workflow, node, START
class PipelineState(BaseModel): iteration: int = 0 best_score: float = 0.0 status: str = "pending"
@nodedef tracker(node_input: str, ctx, iteration: int = 0) -> str: # `iteration` is injected from ctx.state["iteration"]; default 0 for first run # (state_schema validates writes but does not pre-populate state with defaults) ctx.state["iteration"] = iteration + 1 ctx.state["status"] = "running" return f"pass {iteration + 1}: {node_input}"
@nodedef scorer(node_input: str, ctx) -> float: score = len(node_input) / 100.0 if score > ctx.state.get("best_score", 0.0): ctx.state["best_score"] = score return score
pipeline = Workflow( name="scored_pipeline", state_schema=PipelineState, edges=[(START, tracker, scorer)],)Writing an unknown key (ctx.state["typo_key"] = 1) raises StateSchemaError at runtime — catching schema drift early.
Full conditional routing example
Section titled “Full conditional routing example”A classifier node routes between specialist agents based on detected intent. DEFAULT_ROUTE catches any unrecognised intent so the workflow never deadlocks on missing edges.
import asynciofrom google.adk.agents import LlmAgentfrom google.adk.apps import Appfrom google.adk.runners import InMemoryRunnerfrom google.adk.workflow import Workflow, node, START, DEFAULT_ROUTE
billing_agent = LlmAgent( name="billing", model="gemini-3.8-flash", instruction="Handle billing questions. Be concise.", mode="single_turn",)support_agent = LlmAgent( name="support", model="gemini-3.8-flash", instruction="Handle technical support questions. Be concise.", mode="single_turn",)general_agent = LlmAgent( name="general", model="gemini-3.8-flash", instruction="Handle general queries. Be concise.", mode="single_turn",)
@nodedef classify(node_input: str, ctx) -> str: lower = node_input.lower() if any(w in lower for w in ("invoice", "payment", "charge", "refund")): ctx.route = "billing" elif any(w in lower for w in ("error", "bug", "crash", "broken", "help")): ctx.route = "support" else: ctx.route = DEFAULT_ROUTE return node_input # pass through to the selected agent
triage_wf = Workflow( name="triage", edges=[ (START, classify, { "billing": billing_agent, "support": support_agent, DEFAULT_ROUTE: general_agent, }), ],)
async def main(): app = App(name="triage_app", root_agent=triage_wf) runner = InMemoryRunner(app=app) await runner.session_service.create_session( app_name="triage_app", user_id="u1", session_id="s1" ) events = await runner.run_debug( "I need a refund for invoice #1234", user_id="u1", session_id="s1" ) print(events[-1].content.parts[0].text)
asyncio.run(main())Fan-out / join (map-reduce)
Section titled “Fan-out / join (map-reduce)”Spawn multiple specialist agents in parallel, then aggregate with a JoinNode and a summary node.
import asynciofrom google.adk.agents import LlmAgentfrom google.adk.apps import Appfrom google.adk.runners import InMemoryRunnerfrom google.adk.workflow import JoinNode, Workflow, node, START
security_reviewer = LlmAgent( name="security", model="gemini-3.8-flash", instruction="Review the code for security issues only. List findings as bullet points.", mode="single_turn",)perf_reviewer = LlmAgent( name="performance", model="gemini-3.8-flash", instruction="Review the code for performance issues only. List findings as bullet points.", mode="single_turn",)style_reviewer = LlmAgent( name="style", model="gemini-3.8-flash", instruction="Review the code for style/readability issues only. List findings as bullet points.", mode="single_turn",)
join = JoinNode(name="join_reviews")
@nodedef summarize(node_input: dict) -> str: # node_input is {predecessor_name: output} — one key per fan-out branch parts = [] for reviewer, findings in node_input.items(): parts.append(f"### {reviewer.capitalize()}\n{findings}") return "\n\n".join(parts)
review_wf = Workflow( name="code_review", edges=[ # Fan-out to all three reviewers in parallel, then fan-in via join (START, (security_reviewer, perf_reviewer, style_reviewer), join, summarize), ],)
async def main(): # Intentionally vulnerable SQL — this is the code the review agents will catch code = "def get_user(id): return db.query(f'SELECT * FROM users WHERE id={id}')" app = App(name="review_app", root_agent=review_wf) runner = InMemoryRunner(app=app) await runner.session_service.create_session( app_name="review_app", user_id="u1", session_id="s1" ) events = await runner.run_debug(code, user_id="u1", session_id="s1") # The last event comes from the `summarize` function node: its result is in # `event.output`, not `event.content`. print(events[-1].output)
asyncio.run(main())JoinNode waits for all predecessor branches before forwarding a {name: output} dict to the next node.
HITL with persisted sessions
Section titled “HITL with persisted sessions”For a pause that can outlast the process (a person approves tomorrow), keep sessions in a database. The first request runs until the workflow pauses and returns the interrupt ID; a later request, possibly in another process, answers it:
import asyncio
from google.adk.agents import LlmAgentfrom google.adk.apps import App, ResumabilityConfigfrom google.adk.events import RequestInputfrom google.adk.runners import Runnerfrom google.adk.sessions import DatabaseSessionServicefrom google.adk.workflow import START, Workflow, nodefrom google.adk.workflow.utils._workflow_hitl_utils import create_request_input_responsefrom google.genai import types
drafter = LlmAgent( name="drafter", model="gemini-3.8-flash", instruction="Write a short marketing email for the product described in the input.", mode="single_turn",)
@node(rerun_on_resume=True)def human_review(node_input: str, ctx): decision = ctx.resume_inputs.get("email_review") if decision is None: yield RequestInput( interrupt_id="email_review", message=f"Draft:\n\n{node_input}\n\nApprove? (yes/no)", ) return # A response of exactly {"result": value} arrives unwrapped, as value. if str(decision).strip().lower() == "yes": ctx.route = "approved" yield node_input return ctx.route = "revise" # loop back for another draft yield node_input
@nodedef send(node_input: str, ctx) -> str: ctx.state["approved_email"] = node_input return "email queued"
approval_wf = Workflow( name="email_approval", edges=[(START, drafter, human_review, {"approved": send, "revise": drafter})],)
app = App( name="email_app", root_agent=approval_wf, resumability_config=ResumabilityConfig(is_resumable=True),)
def request_input_ids(event) -> list[str]: """Interrupt ids of any RequestInput pauses carried by this event.""" return [fc.id for fc in event.get_function_calls() if fc.name == "adk_request_input"]
async def start(runner: Runner) -> str | None: """First request: runs until the workflow pauses; returns the interrupt id.""" await runner.session_service.create_session(app_name="email_app", user_id="u1", session_id="s1") message = types.Content(role="user", parts=[types.Part(text="noise-cancelling headphones for office workers")]) interrupt_id = None async for event in runner.run_async(user_id="u1", session_id="s1", new_message=message): for call_id in request_input_ids(event): interrupt_id = call_id print("Workflow paused, waiting for approval.") return interrupt_id
async def resume(runner: Runner, interrupt_id: str, answer: str) -> None: """Later request (possibly another process): answers the pause.""" response = types.Content(role="user", parts=[create_request_input_response(interrupt_id, {"result": answer})]) async for event in runner.run_async(user_id="u1", session_id="s1", new_message=response): if event.output is not None: print("output:", event.output)
async def main(): sessions = DatabaseSessionService("sqlite+aiosqlite:///./sessions.db") runner = Runner(app=app, session_service=sessions) interrupt_id = await start(runner) # ... store interrupt_id with your task and show the draft to a person ... if interrupt_id: await resume(Runner(app=app, session_service=sessions), interrupt_id, "yes")
asyncio.run(main())- Send a
FunctionResponsethat matches theinterrupt_id: plain text does not resume a paused node. A response of exactly{"result": value}reaches the node unwrapped, asvalue; any other dict arrives as is. create_request_input_responsebuilds that part. It lives in a private module, so pin your ADK version if you rely on it, or build thetypes.Partyourself as in the previous section. Thehas_request_input_function_callandget_request_input_interrupt_idshelpers that module shipped up to 2.10 have been removed; read the ID from the event’sadk_request_inputfunction call, asrequest_input_idsdoes.DatabaseSessionServicecreates its tables on first use (await sessions.prepare_tables()does it eagerly). WithResumabilityConfig(is_resumable=True)on theApp, an invocation interrupted by a crash can also be resumed from the session’s events.- Give every node that can be on a routing branch somewhere to go: if a node has routing edges and sets no matching route, the branch ends with a logged warning (
... none were matched by the emitted route(s)), which is why approval routes tosendabove.
Gotchas
Section titled “Gotchas”- Nodes are Pydantic models — if you subclass
Node, annotate fields or they won’t serialise. Workflowis not aBaseAgent, and it cannot be anLlmAgentsub-agent. As a root it works withApp(root_agent=workflow),Runner(node=workflow, ...)orRunner(agent=workflow, ...); useAppwhen you need plugins or resumability.ctx.run_node(callable)requiresrerun_on_resume=Trueon the calling node.wait_for_output=Truemeans a node is not complete until it yields an output. A node with it set that finishes without one leaves its successors waiting.- When a tuple contains only one element (e.g.
(START, single_node)), you still get a single edge — not sugar for fan-out. Fan-out needs a nested tuple:(START, (a, b)). - Nodes are inferred from
edges; there is nonodes=field (an unknown keyword is ignored, not rejected). state_schemavalidatesctx.statewrites — fields on the schema class can be injected directly as node parameters; this is the recommended way to thread typed state through a pipeline.