Building Agents with Google ADK

10.1 What ADK actually gives you

Strip away the branding and ADK offers one idea: control flow between agents should be structure in your code, not an instruction you hope a model follows.

It is worth being concrete about what that buys, because “orchestration framework” is vague enough to sound like it might be doing nothing. Consider a reviewer agent that should try at most three times to fix a draft. Written as a prompt, “attempt this at most three times” is a suggestion; a confused model that has lost track of its own history will happily attempt it nine times, and the failure mode is a bill rather than an error. Written as LoopAgent(max_iterations=3), four attempts is not a thing that can happen. The constraint holds precisely when the model is behaving worst, which is the only time constraints matter.

That is the same argument as 8.17's permission boundaries and 8.21's approval gates, applied to control flow instead of authority. It is also the honest limit of what a framework can do for you: ADK can guarantee how many times something runs and who is allowed to run it. It cannot guarantee that what runs is any good. The parts of this chapter that deal with quality — the validator, the entailment check, the ledger — are code you write, and the framework's role is only to give them a well-defined place to sit.

10.2 LlmAgent, and what state is for

The smallest useful agent is three fields and one that is easy to overlook.

from google.adk.agents import LlmAgent

# An LlmAgent is a model, an instruction and a toolset. Nothing more.
# `output_key` is the important part: whatever this agent returns is
# written to session state under that name, where later agents read it.
drafter = LlmAgent(
    name="drafter",                       # must be unique among siblings
    model="gemini-2.0-flash",
    description="Writes a first draft of a company overview.",
    instruction="Draft a two-sentence overview of the company.",
    output_key="draft",                   # -> state["draft"]
)

output_key is the field that turns a collection of agents into a pipeline. Whatever the agent produces is written into the session's state dictionary under that name, and any later agent can read it by interpolating {draft} into its own instruction. There is no message passing to write and no return values to thread through — state is the bus.

The distinction between instruction and description catches people repeatedly, so it is worth stating as a rule: the instruction is read by this agent's model and says how to do the work; the description is read by other agents' models and says when to pick this one. They have different audiences and should not be copies of each other.

10.3 Testing without an API key

Before building anything larger, it is worth solving the problem that otherwise makes agent code untestable: every run costs money, takes seconds, and returns something slightly different. A test suite built on real model calls is slow, flaky, expensive, and cannot reproduce the specific failure you are trying to fix.

ADK only ever calls one method on a model, so satisfying that one method gives you a complete stand-in.

from typing import AsyncGenerator

from google.adk.models import BaseLlm, LlmResponse
from google.genai import types


class FakeLlm(BaseLlm):
    """A model that returns scripted text. No network, no API key.

    Subclassing BaseLlm is the supported extension point: ADK only ever
    calls generate_content_async, so anything satisfying this signature
    is indistinguishable from Gemini to the rest of the framework.
    """

    model: str = "fake"
    replies: list[str] = []

    async def generate_content_async(
        self, llm_request, stream: bool = False
    ) -> AsyncGenerator[LlmResponse, None]:
        text = self.replies.pop(0) if self.replies else "done"
        yield LlmResponse(
            content=types.Content(role="model", parts=[types.Part(text=text)])
        )

10.4 Running an agent

A runner connects an agent tree to the services it needs — sessions, artifacts, memory. InMemoryRunner wires up in-memory versions of all of them, which is exactly right for tests and for development, and exactly wrong for production, where a restart would erase every conversation.

import asyncio

from google.adk.runners import InMemoryRunner
from google.genai import types


async def run_once(agent, prompt: str) -> dict:
    """Drive an agent to completion and return the final session state."""
    runner = InMemoryRunner(agent=agent, app_name="demo")

    # A session is one conversation. Its `state` dict is the channel every
    # agent in the tree reads from and writes to.
    session = await runner.session_service.create_session(
        app_name="demo", user_id="u1"
    )

    # run_async yields every event as it happens: model output, tool calls,
    # state updates. Draining it runs the agent to completion.
    async for _ in runner.run_async(
        user_id="u1",
        session_id=session.id,
        new_message=types.Content(role="user", parts=[types.Part(text=prompt)]),
    ):
        pass

    final = await runner.session_service.get_session(
        app_name="demo", user_id="u1", session_id=session.id
    )
    return dict(final.state)

Two things in that snippet are worth dwelling on. First, run_async is an event stream rather than a function returning an answer: you receive model output, tool calls, and state changes as they happen, which is what makes progressive UI streaming (9.12) and live tracing possible. Draining it in a loop, as here, is simply the batch case.

Second, the final answer is read from session state, not from a return value. This feels indirect at first and pays off immediately: a pipeline of six agents needs no plumbing between them, and every intermediate result is still there afterwards for debugging, which is precisely what you want when the sixth agent produces something strange and you need to know which of the first five caused it.

10.5 Functions as tools

A tool in ADK is a plain Python function. There is no registration step and no schema to write, because the schema is derived from the signature and the docstring.

That convenience has a consequence worth internalising: the docstring is production code. It is not a note for the next developer, it is the text the model reads when deciding whether this function is the right one to call and what to pass it. Section 8.4 made this argument in general terms; ADK makes it literal, because there is no separate schema in which to say it better.

10.6 Sub-agents versus AgentTool

This is the most consequential design decision in ADK, and the two options look almost identical when you write them. Both let one agent make use of another. What differs is who is in control afterwards — and the answer is stickier than most people expect.

from google.adk.agents import LlmAgent
from google.adk.tools import AgentTool

specialist = LlmAgent(
    name="refunds",
    model="gemini-2.0-flash",
    description="Handles refund eligibility and processing.",   # <- routing key
    instruction="Decide refund eligibility from the order record.",
)

# OPTION A -- sub_agents: a TRANSFER, and it is sticky.
# Control moves to the specialist and stays there. The specialist answers
# the next user turn too. Right for "this conversation is now about
# refunds"; wrong if the parent still has work to do afterwards.
router = LlmAgent(
    name="router",
    model="gemini-2.0-flash",
    instruction="Route the customer to the right specialist.",
    sub_agents=[specialist],
)

# OPTION B -- AgentTool: a CALL, and it returns.
# The specialist runs, hands its answer back as a tool result, and the
# parent stays in control. Right when you need to combine several
# specialists, or do anything after the specialist finishes.
supervisor = LlmAgent(
    name="supervisor",
    model="gemini-2.0-flash",
    instruction="Answer the customer, consulting specialists as needed.",
    tools=[AgentTool(agent=specialist)],
)

Reading that code, the natural assumption is that the difference is mostly stylistic: one passes work down the tree, the other calls out sideways, and either way you get an answer back. That assumption is wrong, and it is worth seeing exactly how before it costs you an incident.

This matters because the failure it produces is subtle rather than loud. A customer asks about a refund, the router transfers to the refunds specialist, the refund is handled correctly, and everyone is happy. Then the customer asks an unrelated question about delivery times — and the refunds specialist answers it, because it is still holding the conversation. It has no delivery tools and a refund-shaped instruction, so it produces something confident and unhelpful. Nothing errored, and no log line says anything went wrong.

10.7 Choosing between them

The decision is not about hierarchy or code aesthetics. It is one question: after this other agent finishes, does the current agent still have work to do?

10.8 Why prompts cannot enforce grounding

“Only use the provided sources and do not invent facts” is the most common instruction in production AI systems, and it is not an enforcement mechanism. It is a request, addressed to the component whose defining characteristic is that it sometimes produces confident text with no basis.

The gap between a request and an enforcement is easy to see once stated: if the model ignores the instruction, what in your system notices? For most deployments the honest answer is nothing, until a customer does. That is not a prompt-quality problem and no amount of rewording fixes it — the check has to exist outside the thing being checked.

So the first component is not an agent at all. It is a record of what the run has actually seen.

from dataclasses import dataclass, field


@dataclass(frozen=True)
class Doc:
    """One retrieved document. `doc_id` is what a claim must cite."""

    doc_id: str
    url: str
    text: str


@dataclass
class EvidenceLedger:
    """Every document the run has actually seen.

    This is the piece that makes grounding enforceable rather than
    aspirational. If the framework performs the search and hands the model
    a summary, your code never holds the source text, so "do not invent
    facts" can only ever be an instruction. Holding the documents yourself
    turns it into an assertion you can run.
    """

    docs: dict[str, Doc] = field(default_factory=dict)

    def add(self, doc: Doc) -> None:
        self.docs[doc.doc_id] = doc

    def resolve(self, doc_id: str) -> Doc | None:
        return self.docs.get(doc_id)

    def corpus(self) -> str:
        return "\n".join(d.text for d in self.docs.values())

The ledger is deliberately dull: a dictionary of documents and a way to resolve an identifier. Its value is entirely in existing at all, because it converts “the model should not invent facts” from a hope into a claim about two pieces of text that your code is holding.

10.9 A three-tier validator

The obvious way to check a draft is to ask a model whether it is supported by the evidence. That works, and if it is the only thing you do it is both slower and more expensive than necessary, because most fabrications can be caught with a regex.

Order the checks by cost. The cheap ones run on everything; the expensive one runs only on what survives.

import re

# A number in the draft that never appears in any retrieved document is the
# highest-signal fabrication there is: revenue figures, headcounts, dates.
# Checking it costs one regex and no tokens, so it runs on every claim.
_NUMERIC = re.compile(r"\d[\d,]*\.?\d*")


def normalise(token: str) -> str:
    return token.replace(",", "").rstrip(".")


def validate_claim(claim: dict, ledger) -> list[str]:
    """Return a list of problems. Empty list means the claim is clean.

    Tier 1 -- citation integrity: every cited doc_id must resolve. Catches
             the model inventing a plausible-looking source.
    Tier 2 -- literal grounding: every number in the text must appear in
             at least one document the claim actually cites.
    """
    problems: list[str] = []

    cited = [ledger.resolve(i) for i in claim["doc_ids"]]
    for doc_id, doc in zip(claim["doc_ids"], cited):
        if doc is None:
            problems.append(f"cites unknown document {doc_id}")

    if not claim["doc_ids"]:
        problems.append("claim has no citation")

    supporting = " ".join(d.text for d in cited if d is not None)
    for number in _NUMERIC.findall(claim["text"]):
        if normalise(number) not in normalise(supporting):
            problems.append(f"number {number} appears in no cited document")

    return problems

Two details in that code are there because the naive version is wrong. Normalising away commas means 1,200 in the source matches 1200 in the draft — without it the validator produces constant false positives and the team learns to ignore it, which is worse than not having it. And the comparison is against the text of the cited documents only, not the whole corpus: a claim citing document B is not supported by a number that happens to appear in document D.

Then the expensive tier, for the failure the cheap ones cannot see.

async def entails(claim_text: str, evidence: str, judge) -> bool:
    """Tier 3: does the evidence actually support the prose?

    Only reached for claims that already passed tiers 1 and 2, because it
    is the only tier that costs a model call. A claim can cite a real
    document and quote its numbers correctly and still misrepresent it --
    "revenue grew" when the document says it fell -- and that is precisely
    what this catches and the cheap tiers cannot.
    """
    verdict = await judge(
        "Answer only SUPPORTED or UNSUPPORTED.\n"
        f"Evidence:\n{evidence}\n\nClaim: {claim_text}"
    )
    return verdict.strip().upper().startswith("SUPPORTED")


async def validate_all(claims: list[dict], ledger, judge) -> dict:
    """Run the cheap tiers on everything, the expensive tier on survivors."""
    report: dict[str, list[str]] = {}
    for claim in claims:
        problems = validate_claim(claim, ledger)
        if not problems:
            evidence = " ".join(
                ledger.resolve(i).text for i in claim["doc_ids"]
            )
            if not await entails(claim["text"], evidence, judge):
                problems = ["evidence does not support this claim"]
        if problems:
            report[claim["text"]] = problems
    return report

That last example is not hypothetical; it is the test case in the executed version of this code. The cheap tiers return no problems for it, and the judge rejects it. The same test also asserts the ordering works in the other direction: a claim with a fabricated number never reaches the judge at all, so the expensive tier is not spent on something already known to be broken.

10.10 The escalation that gets discarded

Here is the bug that motivates writing this section at all. It is invisible in review, it does not error, the output it produces is correct, and it multiplies your model spend by the loop bound.

A validator lives naturally in an after_agent_callback: the drafter runs, the callback inspects what it produced, and if everything checks out it asks the loop to stop. Asking the loop to stop means setting escalate. Both versions below do that, and only one works.

from google.adk.agents.callback_context import CallbackContext


def validator_BROKEN(callback_context: CallbackContext):
    """Looks correct. Does not stop the loop."""
    callback_context.actions.escalate = True
    return None


def validator_WORKING(callback_context: CallbackContext):
    """Identical intent, but the escalation actually survives.

    ADK only turns the callback's actions into a real event if the callback
    returns content or leaves a state delta. With neither, the escalate flag
    is constructed and then dropped on the floor, and the loop runs to
    max_iterations at full token cost -- while still producing correct
    output, which is what makes it so easy to miss.
    """
    callback_context.actions.escalate = True
    callback_context.state["validation_passed"] = True   # <- the load-bearing line
    return None

The cause is in ADK's own handling of the callback. It only constructs an event carrying the callback's actions if the callback returned content or left a state delta. With neither, the escalate flag is set on an object that is then discarded, so the loop never learns anything happened. The reason this survives review is that the output is still correct — the extra iterations regenerate an already-good draft, the final answer looks right, and the only symptom is the invoice.

There is also a way to avoid the trap entirely. ADK ships the escape hatch as a tool.

from google.adk.tools import exit_loop

# ADK ships the escape hatch as a tool. Given to an LlmAgent inside a
# LoopAgent, the model calls it when its own instruction says the work is
# done, and the loop stops. Because a tool call is already a real event,
# the escalation is never discarded -- the failure mode above cannot occur.
reviewer = LlmAgent(
    name="reviewer",
    model="gemini-2.0-flash",
    instruction=(
        "Review the draft in {draft}. If every claim is supported, call "
        "exit_loop. Otherwise reply with the specific problems to fix."
    ),
    tools=[exit_loop],
)

Because a tool call is already a real event, an escalation raised from tool context cannot be discarded — the failure mode above simply does not apply. It also moves the stop decision into the model's reasoning, where it is visible in traces as an explicit action rather than inferred from a callback's side effects. Prefer this when the stopping criterion is a judgement call. Keep the callback approach when the criterion is deterministic, as it is for the validator, since you do not want to ask a model whether the regex matched.

10.11 The repair loop

With a validator and a working escalation, the loop writes itself — but one detail separates a repair loop from an expensive retry.

from google.adk.agents import LlmAgent, LoopAgent
from google.adk.agents.callback_context import CallbackContext


def make_grounding_gate(ledger):
    """after_agent_callback that stops the loop only when the draft is clean.

    Note both halves of the escape: `escalate` states the intent, and the
    state write is what makes ADK materialise an event carrying it. Setting
    only the flag leaves the loop running to max_iterations.
    """

    def gate(callback_context: CallbackContext):
        draft = callback_context.state.get("draft", "")
        claims = parse_claims(draft)
        problems = {
            c["text"]: p
            for c in claims
            if (p := validate_claim(c, ledger))
        }

        if not problems:
            callback_context.actions.escalate = True
            callback_context.state["grounded"] = True     # makes escalate stick
            return None

        # Feed the specific failures back so the next pass is a repair
        # rather than a reroll. The drafter reads {problems} in its prompt.
        callback_context.state["problems"] = problems
        return None

    return gate


def build_grounded_loop(model, ledger, max_iterations: int = 3) -> LoopAgent:
    drafter = LlmAgent(
        name="drafter",
        model=model,
        instruction=(
            "Write the overview using only the supplied evidence. Cite a "
            "doc_id for every claim. Problems to fix: {problems?}"
        ),
        output_key="draft",
        after_agent_callback=make_grounding_gate(ledger),
    )
    # max_iterations is a structural bound, not a request. The loop cannot
    # exceed it however confused the model becomes.
    return LoopAgent(name="grounded", sub_agents=[drafter],
                     max_iterations=max_iterations)

The executed version of this loop asserts three behaviours: a clean first draft stops after one pass; a draft with a fabricated number is caught and the corrected second draft ends the loop after exactly two; and a model that never gets it right terminates at max_iterations rather than running forever. That third case is the one worth testing deliberately, because it is the one that only shows up in production, on the input nobody thought about.

10.12 Stall detection and quarantine

A bounded loop cannot run forever, but it can still waste its entire budget usefully doing nothing. Two refinements are worth the small amount of code they cost.

Stall detection. If the set of problems after this pass is identical to the set before it, the model is not converging — it is producing the same failure with different wording. Three iterations of that is three times the cost of one, with the same outcome. Compare the problem set between passes and stop early when it stops shrinking; you have learned everything the loop is going to teach you.

Quarantine. When the loop exhausts its budget with problems outstanding, the question is what to publish. Publishing the draft with its unsupported claims intact is the worst option and, unfortunately, the default if nobody decides otherwise. The better move is to drop the specific claims that failed and emit the rest, marked as incomplete — the section that says “revenue: not found” is far more useful than the one that invents a number, and it is the behaviour 5.31's abstention discussion argues for.

10.13 Sequential, parallel, loop

Three control-flow shapes, each corresponding to a property of the work rather than a preference about code. Choosing between them is a question about your task, not about the framework.

The measurement is worth stating plainly, because “parallel” in an async framework is not always as parallel as advertised. Three legs of 0.4s each, run through a ParallelAgent, completed in 0.41s against 1.2s if run one after another — a 3.0× speedup, which is the whole of the theoretical maximum. The branches genuinely overlap.

10.14 What parallel branches can see

Parallel sub-agents run in isolated branches, and the consequence is the thing people get wrong: a branch cannot read what a sibling produced during the same parallel block. If one leg writes findings_people and another leg's instruction interpolates {findings_people}, that placeholder resolves to nothing.

This is worth checking against your intuition, because the failure is quiet. There is no error and no warning; the interpolation resolves to an empty string, the model writes something plausible around the gap, and the result reads fine. It is the same class of problem as the discarded escalation — correct-looking output hiding a structural mistake.

10.15 A full composed pipeline

Now the scenario that combines everything: a research report that plans its own work, gathers evidence on several fronts at once, drafts and re-drafts under validation, and assembles a final document. Four agents, three control-flow shapes, one validator.

from google.adk.agents import LlmAgent, LoopAgent, ParallelAgent, SequentialAgent


def build_pipeline(model, ledger) -> SequentialAgent:
    """Plan -> (research x N in parallel) -> draft/critique loop -> assemble.

    Each shape is chosen for a property, not for variety:
      Sequential -- later stages need earlier stages' output.
      Parallel   -- the research legs are independent, so latency is one
                    leg rather than the sum. Branches are isolated: a
                    sibling's output_key is NOT visible mid-run.
      Loop       -- quality is a fixed point, not a single pass, and the
                    iteration cap is structural.
    """
    planner = LlmAgent(
        name="planner", model=model, output_key="plan",
        instruction="Break the request into research questions.",
    )

    legs = [
        LlmAgent(name=f"research_{topic}", model=model,
                 output_key=f"findings_{topic}",
                 instruction=f"Research {topic} for: {{plan}}")
        for topic in ("financials", "people", "risks")
    ]
    research = ParallelAgent(name="research", sub_agents=legs)

    drafter = LlmAgent(
        name="drafter", model=model, output_key="draft",
        instruction=(
            "Draft from {findings_financials}, {findings_people}, "
            "{findings_risks}. Fix any problems in {problems?}."
        ),
        after_agent_callback=make_grounding_gate(ledger),
    )
    refine = LoopAgent(name="refine", sub_agents=[drafter], max_iterations=3)

    assembler = LlmAgent(
        name="assembler", model=model, output_key="report",
        instruction="Format {draft} as the final report.",
    )

    return SequentialAgent(
        name="pipeline", sub_agents=[planner, research, refine, assembler]
    )

Note also what the shapes cost. The parallel block turns three sequential model calls into one wall-clock leg, which is the difference between a report that takes ninety seconds and one that takes half a minute. The loop's bound means a pathological input costs at most three drafts instead of an unbounded number. Both are properties of the structure, and neither depends on the model cooperating.

10.16 The deprecation problem

An honest note, because this will confuse anyone reading the source. In ADK 2.8.0 all three workflow agents — SequentialAgent, ParallelAgent and LoopAgent — are marked deprecated in favour of a newer graph-based Workflow API. Importing them emits a DeprecationWarning.

The practical response is not to avoid the deprecated classes, which would mean not building the thing. It is to confine them. Keep every construction of a workflow agent inside one small module that exposes your own pipeline-building functions, as build_pipeline does above. Then the migration, when Workflow is ready, is one file rather than a search across the codebase — and your business logic, which does not care how the loop is implemented, never mentions the deprecated names at all.

This is a specific instance of a general habit worth having with fast-moving frameworks: the parts of a young library most likely to be rewritten are its orchestration primitives, and the parts least likely are plain functions and data. Keep your value in the latter. It is also the same advice 8.25 gives about ADK as a whole — use the operational surface, but keep your tool implementations and business rules in ordinary Python that would survive changing frameworks entirely.

10.17 Is “skills” a Claude word?

It is a reasonable suspicion. Agent skills arrived with a great deal of Anthropic branding, and vendor-specific vocabulary dressed up as an industry standard is common enough that scepticism is the right default. In this case the scepticism is misplaced, and the way to settle it is to look in the package rather than at the marketing.

Google ADK 2.8.0 ships a google.adk.skills module. It is not a compatibility shim or a thin adapter — it contains the data model (Skill, Frontmatter, Resources, Script), a registry, loaders for both local directories and cloud storage, and a SkillToolset that exposes skills to a model. Loading a SKILL.md file written to the Claude conventions into an ADK agent works without modification.

So the accurate framing is the same one 8.9 used for MCP and 8.25 used for A2A. All three are protocols that began at one vendor and became shared, and their value comes precisely from being implemented in more than one place. Skills are the third member of that family: MCP standardises how an agent reaches a tool, A2A how it reaches another agent, and skills how it acquires instructions.

10.18 Writing and loading a skill

A skill is a folder, not a Python object. That is the entire idea, and it is what makes skills portable between frameworks in a way that a class hierarchy never could be.

skills/
  refund-policy/
    SKILL.md          # required: YAML frontmatter + markdown instructions
    references/       # optional: deeper documentation, loaded on demand
    assets/           # optional: templates and other resources
    scripts/          # optional: executables the agent may run

The frontmatter carries the metadata; the body carries the instructions.

---
name: refund-policy
description: Apply the refund policy. Use when a customer asks for a
  refund, a return, or an exchange.
license: Apache-2.0
metadata:
  adk_inject_state: true
---

# Refund policy

The customer's loyalty tier is {tier?}.

1. Within 30 days of delivery, with proof of purchase, issue a full refund.
2. Between 30 and 90 days, issue store credit.
3. After 90 days, no refund. Offer a repair booking instead.

Loading it is two lines.

from google.adk.agents import LlmAgent
from google.adk.skills import load_skills_from_dir
from google.adk.tools.skill_toolset import SkillToolset

# A skill is a folder on disk, not a Python object:
#     skills/refund-policy/SKILL.md        <- YAML frontmatter + instructions
#     skills/refund-policy/references/     <- optional deeper docs
#     skills/refund-policy/scripts/        <- optional executables
#
# Only each skill's name and description are put in the prompt up front.
# The body is loaded on demand, when the model decides the skill is
# relevant -- which is the whole point: you can ship fifty skills without
# paying fifty skills' worth of context on every turn.
skills = load_skills_from_dir(SKILLS_DIR)

agent = LlmAgent(
    name="support",
    model="gemini-2.0-flash",
    instruction="Help the customer. Use a skill when one applies.",
    tools=[SkillToolset(skills=skills)],
)

Two ADK-specific extensions live in metadata, and both are worth knowing. adk_inject_state: true enables {variable} interpolation in the skill body from session state — so the refund policy above can address the customer's actual loyalty tier, with {tier?} resolving to an empty string rather than raising when the key is missing. adk_additional_tools lets a skill declare tools that become available when it is loaded.

10.19 Skills versus tools versus agents

Three mechanisms for extending what an agent can do, and a reliable way to choose: what are you actually adding?

It is worth noting that skills partly close the gap that made 8.14's context engineering so difficult. The old dilemma was between a bloated system prompt that covered every eventuality and a lean one that failed on unusual cases. Skills reframe it: keep the system prompt lean, keep the long-tail procedures on disk, and let the model fetch what the current situation calls for. That is retrieval — applied to instructions rather than documents, which is a genuinely good idea and slightly overdue.

10.20 Fixed pipelines versus autonomy

Everything so far has had its control flow decided in advance. 10.15's pipeline always plans, then researches, then drafts, then assembles. The model chooses the words; the code chooses the sequence. A fully autonomous agent inverts that: the model chooses the sequence too.

The temptation is to treat autonomy as the more advanced option and fixed pipelines as the beginner's version. That gets the trade backwards. Autonomy is what you resort to when you cannot specify the sequence, and it costs you every guarantee that came from specifying it.

10.21 Building an autonomous agent

The construction is simpler than the fixed pipeline, which is itself a useful signal about where the difficulty has moved.

from google.adk.agents import LlmAgent, LoopAgent
from google.adk.tools import AgentTool, exit_loop


def build_autonomous(model, tools, specialists, max_steps: int = 12) -> LoopAgent:
    """A fully dynamic agent: it decides its own next step each iteration.

    The difference from the composed pipeline is where control flow lives.
    There, the sequence was fixed in code and the model filled in content.
    Here the model chooses the sequence, and the *bounds* are what live in
    code. That trade buys flexibility on tasks whose shape is not known in
    advance, and it costs you the ability to predict what will run.

    Note what remains structural even at full autonomy:
      - max_steps caps the loop no matter what the model believes;
      - specialists are AgentTools, so control always returns here;
      - exit_loop is the only way to finish early, and it is explicit.
    """
    worker = LlmAgent(
        name="worker",
        model=model,
        instruction=(
            "Goal: {goal}\n"
            "Progress so far: {scratchpad?}\n"
            "Take ONE step towards the goal. Append what you learned to the "
            "scratchpad. When the goal is fully met, call exit_loop."
        ),
        tools=[*tools, exit_loop, *(AgentTool(agent=s) for s in specialists)],
        output_key="scratchpad",
    )
    return LoopAgent(name="autonomous", sub_agents=[worker],
                     max_iterations=max_steps)

One agent, in a loop, with a scratchpad. Each iteration it reads the goal and what it has learned, takes one step, and appends the result. It stops when it decides the goal is met and calls exit_loop, or when the step cap is reached. This is 8.3's agent loop and 8.11's planning discussion, expressed in ADK's primitives.

10.22 Bounding what you cannot predict

Since you can no longer say what an autonomous agent will do, everything rests on what it cannot do. Four bounds, in decreasing order of how much they save you.

A step cap. max_iterations is the difference between a bad run costing a few dollars and a bad run costing until someone notices. Set it from a measurement — the 95th percentile of successful runs on your evaluation set, plus headroom — rather than from a round number that feels generous.

A spend cap. Steps are a poor proxy for cost, because one step that reads a 200-page document costs more than twenty that do not. Track tokens in a callback and stop on the budget, as 8.22 argues. An agent that has spent its allowance should stop even if it has steps remaining.

Read-only by default. The single highest-leverage control. An autonomous agent with only read tools has a worst case of wasting money and returning something wrong. Add one side-effecting tool and the worst case becomes unbounded external damage. Every write should be a separate, approved, idempotent tool — 8.5 and 8.21 in full, applied without exception.

Stall detection. Same idea as 10.12, and more important here. An autonomous agent that has stopped making progress will keep looking busy: it will re-read the same page, rephrase the same query, and consume its entire budget confidently. Compare the scratchpad between iterations and stop when it stops growing in substance.

from google.adk.agents import LlmAgent
from google.adk.workflow._retry_config import RetryConfig

# Per-agent retry and timeout are built in -- there is no need to wrap
# agents in your own retry decorator, and doing so tends to multiply with
# this one rather than replace it.
researcher = LlmAgent(
    name="researcher",
    model="gemini-2.0-flash",
    instruction="Research the question.",
    timeout=60.0,                       # seconds, per agent run
    retry_config=RetryConfig(
        max_attempts=3,
        initial_delay=1.0,
        backoff_factor=2.0,             # 1s, 2s, 4s
        jitter=0.3,                     # avoids a synchronised retry storm
    ),
)

10.23 One flow per row

A different shape of problem: not one conversation with a user, but a hundred thousand rows in a table, each of which must trigger its own multi-agent flow. Enrich every supplier record. Classify every support ticket from last quarter. Draft a summary for every contract. The agent design is the same; everything around it changes.

The first decision is the one that determines whether the rest works, and it is easy to get wrong in a way that only shows up at scale: each row gets its own session.

import asyncio

from google.adk.runners import InMemoryRunner
from google.genai import types


async def process_row(row: dict, build_agent, limit: asyncio.Semaphore) -> dict:
    """Run the full multi-agent flow for exactly one row.

    Three properties matter here, and each is one line:
      - a session PER ROW, so rows cannot see each other's state;
      - a semaphore, so 100k rows do not open 100k concurrent model calls;
      - a try/except returning a value, so one bad row is a recorded
        failure rather than a dead batch.
    """
    async with limit:
        runner = InMemoryRunner(agent=build_agent(), app_name="batch")
        session = await runner.session_service.create_session(
            app_name="batch",
            user_id=row["id"],              # isolation key
            state={"row": row},             # seed input, no prompt stuffing
        )
        try:
            async for _ in runner.run_async(
                user_id=row["id"],
                session_id=session.id,
                new_message=types.Content(
                    role="user", parts=[types.Part(text=row["text"])]
                ),
            ):
                pass
        except Exception as exc:            # noqa: BLE001 -- deliberate
            return {"id": row["id"], "status": "failed", "error": str(exc)}

        final = await runner.session_service.get_session(
            app_name="batch", user_id=row["id"], session_id=session.id
        )
        return {"id": row["id"], "status": "ok", "state": dict(final.state)}


async def run_batch(rows, build_agent, concurrency: int = 8) -> list[dict]:
    limit = asyncio.Semaphore(concurrency)
    # return_exceptions=True is the difference between "one row raised" and
    # "the batch died on row 40,000 after four hours".
    return await asyncio.gather(
        *(process_row(r, build_agent, limit) for r in rows),
        return_exceptions=True,
    )

Note also how the row's data enters: as session state, not by formatting it into the prompt. This keeps structured input structured, avoids an entire class of injection problems from row content that happens to contain instruction-like text (15.7), and means any agent in the tree can read the original row rather than the model's paraphrase of it.

10.24 Concurrency, failure, and cost

Three properties, each worth one line of code, and each catastrophic to omit.

Bound the concurrency. asyncio.gather over 100,000 rows creates 100,000 coroutines that all try to call the model at once. You will hit rate limits within seconds, and the retry storm that follows will make it worse. A semaphore bounds in-flight work regardless of batch size. Verified: with a limit of 2 and six rows, peak concurrency was exactly 2.

Isolate the failures. One row that raises must not end the run. return_exceptions=True plus a per-row try turns a fatal error into a recorded one. Verified: with six rows and one deliberately raising, five completed and the failure was captured with its row identifier intact.

Know the cost before you start. A multi-agent flow with a plan stage, three parallel research legs and a loop that may run three times is not one model call per row. Count the calls in the worst case, multiply by the row count, and price it before running the job rather than after.

10.25 Checkpointing and dead letters

A batch job long enough to be worth parallelising is long enough to be interrupted. The difference between a four-hour job that can resume and one that cannot is a few lines.

import asyncio
import json


async def run_batch_streaming(rows, build_agent, out_path, dead_path,
                              concurrency: int = 8) -> dict:
    """Write each result as it lands, so a crash at row 90,000 is not fatal.

    Collecting into a list and writing at the end means an OOM or a killed
    pod loses the whole run. Appending per row means a rerun skips what is
    already done. For a long batch this is the difference between a retry
    costing minutes and costing the entire job again.
    """
    limit = asyncio.Semaphore(concurrency)
    tally = {"ok": 0, "failed": 0}
    lock = asyncio.Lock()

    with open(out_path, "a") as out, open(dead_path, "a") as dead:

        async def one(row):
            result = await process_row(row, build_agent, limit)
            async with lock:                      # one writer at a time
                if result["status"] == "ok":
                    out.write(json.dumps(result) + "\n")
                    tally["ok"] += 1
                else:
                    # The dead-letter file is the retry queue: it holds the
                    # row itself, not just the error, so a rerun is trivial.
                    dead.write(json.dumps({"row": row, **result}) + "\n")
                    tally["failed"] += 1

        await asyncio.gather(*(one(r) for r in rows))

    return tally

The single lock around the writes is doing real work, and it is the kind of detail that is invisible until it is not. Without it, concurrent coroutines interleave their writes and produce lines that are half one JSON object and half another — a file that looks fine until something tries to parse it, which is usually the following morning.

10.26 Key takeaways

The framework gives you structure. Everything that determines whether the output can be trusted is code you write and place inside that structure.

10.27 Interview drills

Framework questions are a trap in both directions. Reciting an API is not evidence of anything, and dismissing frameworks entirely usually means never having operated one. What an interviewer is listening for is whether you know which guarantees are structural and which are wishful.

Expand all

Where this leaves you

You can now build a multi-agent system in ADK and say precisely which of its properties are guaranteed. The loop cannot exceed its bound. The specialist cannot silently keep the conversation, because you chose call-and-return deliberately. A claim without a resolvable citation does not reach the reader. One bad row in eighty thousand is a line in a dead-letter file rather than a failed overnight run.

None of those guarantees came from the model cooperating, and that is the thread running through the chapter. The framework contributes structure — a well-defined place to attach a validator, a cap that holds when the model is most confused, isolation between parallel branches. Everything that determines whether the output can be trusted is ordinary Python you wrote and could carry to another framework tomorrow. The evidence ledger, the tiered validator, the repair loop, the dead-letter queue: all of it is portable, and keeping it that way is what stops a framework choice from becoming a permanent one.

The failures worth remembering are the quiet ones. An escalation that is set and discarded, a sibling branch that reads an empty string, a session reused across rows — none of them raise, none of them log, and all of them produce output that reads correctly. They are found by an invoice, an auditor, or a customer. The defence is not more careful reading; it is measuring the behaviour you are relying on, and then breaking it on purpose to confirm your test noticed. That habit caught a wrong claim in the drafting of this very chapter, which is as good an argument for it as any.

That closes the course. Chapter 1 began with a model that could only produce text, and the arc since then has been about everything required to make that useful and safe: giving it knowledge it does not have, serving it at a cost that works, giving it tools that change the world, and — here — giving it structure that holds when it is wrong. The last part is the one that turns a demonstration into a system.