Google ADK 2.0 Workflow Runtime: A Migration Guide for Reliable AI Agents

Google ADK 2.0 changes the center of gravity for agent applications: instead of asking an LLM to decide every transition, developers can express deterministic execution as a workflow graph and reserve model calls for ambiguous work. The result is a more predictable architecture for refunds, approvals, data pipelines, and other production processes where skipping a required step is worse than producing a less creative answer.

The practical takeaway is simple: use an autonomous agent for interpretation, use workflow nodes for routing and side effects, and put explicit boundaries between them. ADK 2.0 is available for Python and Go, while the official compatibility guide documents the migration hazards for existing ADK 1.x applications.

What changed in Google ADK 2.0?

ADK 2.0 introduces a workflow runtime built around graph-based execution, dynamic workflows, and collaborative agent composition. Agents, tools, and functions can be treated as nodes in a controlled execution graph rather than leaving the model to infer the entire sequence from a prompt.

Google’s documentation lists three central capabilities:

• Graph-based workflows: define how tasks are routed and executed.
• Dynamic workflows: use ordinary code for loops, branching, and more complex control flow.
• Collaborative workflows: coordinate multiple specialized agents and subagents.

The release is not merely a new prompt pattern. The runtime changes the execution model. In ADK 1.x, an agent was primarily an executor in a hierarchical agent system. In ADK 2.0, the documentation describes agents as nodes in a workflow graph, with event and state handling designed around that graph.

For teams building production agents, that distinction matters. The model can still decide how to interpret an email or classify an exception, but it does not need to decide whether a required database write happens before or after a payment API call.

Why deterministic workflows matter for AI agents

An LLM is good at handling ambiguity. It is a poor substitute for a state machine when the business process is already known.

Consider a customer refund:

1. Load the purchase history.
2. Check the current refund policy.
3. Determine eligibility, including unstructured exceptions.
4. Issue the refund only when the policy decision permits it.
5. Notify the customer.
6. Close the support ticket.

A prompt can describe those steps, but a prompt does not guarantee that every run will follow them. Tool results can enlarge the context, an exception can be misinterpreted, and a model can attempt a later action after an earlier operation failed.

ADK 2.0 lets developers encode the fixed parts as programmatic edges. The policy interpretation can remain an LLM step, but the route from policy decision to refund or rejection is controlled by application code.

This is the same design principle behind the site’s existing harness engineering guide for AI coding agents: reliability comes from shaping the environment around the model, not from endlessly expanding the instruction.

ADK 2.0 architecture: model nodes inside a controlled graph

A useful mental model is to separate an agent application into four layers:

The graph owns transitions, retries, state boundaries, and side-effect ordering. LLM nodes handle tasks such as extracting intent, classifying an exception, summarizing evidence, or drafting a response.

This also complements the design of MCP’s stateless server migration. MCP can expose tools and transport capabilities, but the application still needs an execution policy that decides which tools may run, in what order, and under which approval conditions.

A minimal migration strategy from ADK 1.x

Do not migrate a production agent by changing the package version and hoping the old execution assumptions continue to work. Start by identifying where the application relies on implicit model routing.

1. Inventory the current agent loop

List every model call, tool, callback, session write, retry, and external side effect. Mark each operation as either:

• Interpretive: the model must reason about language or uncertain evidence.
• Deterministic: code can decide the outcome from typed state.
• Side effect: the operation changes an external system.
• Human-controlled: the user must approve or supply information.

This inventory exposes places where a prompt is currently acting as an undocumented workflow engine.

2. Promote fixed transitions into nodes

A sequence such as load -> classify -> write -> notify should become an explicit graph. Keep the classifier as an agent node, but route its structured result through code. Avoid asking a second model call to decide whether the first model’s eligible result should trigger a refund.

3. Define state boundaries

ADK 2.0 adds event fields such as node_info and output. If a custom session service maps events into rigid database columns, update that schema before writing 2.0 events. If events are stored as serialized JSON, the migration may be less invasive, but downstream readers and validators still need to understand the new shape.

4. Move lifecycle customization into callbacks

The compatibility guide warns that custom execution overrides from 1.x may no longer drive execution in the new graph engine. Custom telemetry, validation, and state handling should use the supported callback interfaces rather than relying on legacy run() or internal execution overrides.

5. Let failures reach the runtime

ADK 2.0 adds framework-level handling for retries, telemetry, and human-in-the-loop pauses. A broad except Exception inside a tool can hide the failure from that machinery. Let expected errors propagate to the configured retry policy, and do not catch BaseException unless the exception is immediately re-raised.

Python installation and a safe first workflow

For a new Python project, use an isolated environment and pin the major version while validating the migration:

1python3 -m venv .venv
2source .venv/bin/activate
3python -m pip install --upgrade pip
4python -m pip install "google-adk~=2.0"

The exact application API should be checked against the version installed in the project. ADK 2.0’s official compatibility documentation is especially important for applications with custom session storage or execution overrides.

A safe first workflow keeps the side effect outside the model loop:

1from dataclasses import dataclass
2
3@dataclass
4class RefundState:
5    purchase_id: str
6    eligible: bool = False
7    refund_id: str | None = None
8
9
10def route_refund(state: RefundState) -> str:
11    """Route only from typed application state, not free-form model text."""
12    return "issue_refund" if state.eligible else "close_ticket"
13
14
15def issue_refund(state: RefundState, payments) -> RefundState:
16    if not state.eligible:
17        raise ValueError("refund route reached without eligibility")
18    state.refund_id = payments.refund(state.purchase_id)
19    return state

The example is deliberately small. In a real ADK workflow, an agent node could produce a validated eligibility decision, and a deterministic route would select either the refund tool or the rejection path. The payment call should still enforce authorization, idempotency, amount limits, and an independent policy check.

Do not treat a string such as "true" in an unconstrained model response as sufficient authorization for money movement. Use structured output, validate it, bind it to the current customer and purchase, and require confirmation for high-impact actions.

Go ADK 2.0 and multi-agent systems

ADK 2.0 is also available for Go. The official ADK 2.0 documentation identifies Go 2.0 as a general-availability release, and Google Developer Expert coverage shows how the Go stack can be combined with A2A components and Cloud Run deployment patterns.

Go is attractive when the agent is part of a high-throughput service rather than a standalone notebook. Strong typing, explicit concurrency, and straightforward container deployment can make workflow boundaries easier to review. The trade-off is that the Go migration has its own module and API compatibility surface; do not assume Python examples map line-for-line to Go.

A2A and MCP solve different problems in this architecture. A2A can coordinate agents as services, while MCP exposes tools and resources to an agent. ADK’s workflow graph remains the local application policy that controls how those capabilities are composed. For a broader view of the tool layer, see the site’s OpenAI Agents SDK MCP migration guide.

Security and reliability checklist

ADK 2.0’s deterministic routing can reduce risk, but it does not make an agent secure by default.

• Treat model output as untrusted input. Validate schemas, enums, identifiers, and numeric limits.
• Keep authorization outside the prompt. The workflow and downstream service must enforce permissions.
• Make side effects idempotent. Retries must not create duplicate refunds, tickets, or messages.
• Require human approval for irreversible actions. A deterministic edge can still route to the wrong tool if its inputs are wrong.
• Separate untrusted content from instructions. Customer emails, retrieved pages, and tool output can contain prompt injection.
• Log graph transitions. Record node identity, decision evidence, tool arguments after redaction, and outcomes.
• Test failure paths. Include timeouts, partial writes, stale policy data, duplicate events, and resumed HITL runs.

The AI agent authorization bypass coverage on this site is a useful reminder that tool permission checks must be revalidated at execution time. A workflow edge is not a replacement for authorization at the tool or service boundary.

Performance, cost, and observability

The main efficiency win is avoiding unnecessary model turns. If the next step is known, a graph transition is cheaper and faster than asking the model to restate the plan and select another tool.

Google’s announcement includes illustrative comparisons for a refund workflow, reporting lower token use and latency when deterministic nodes handle fixed transitions. Those figures should be treated as example results, not a universal benchmark: model choice, tool latency, payload size, retries, and deployment region can dominate the outcome.

Measure your own workload with at least:

Instrument both the workflow and the model. A low token count is not a success if the graph sends invalid data to a payment system, and a fast run is not useful if human approvals are invisible in the audit trail.

Common migration errors

Treating ADK 2.0 as a drop-in executor upgrade

The graph runtime changes assumptions about execution, events, and callbacks. Read the compatibility guide and migrate one workflow at a time.

Keeping business logic in a giant system prompt

If a rule can be expressed as a typed condition, move it into code. Keep language interpretation in the model and policy enforcement in deterministic services.

Manually appending session events

The 2.0 runtime needs control over event emission for routing, persistence, and streaming. Yield events through the supported node or agent interfaces instead of mutating session collections directly.

Catching every exception inside tools

Broad catches can disable automatic retries and hide the distinction between a retryable failure and a terminal business error. Catch narrowly, add context, and re-raise when the runtime must handle the failure.

Assuming graph control eliminates prompt injection

An injected instruction may still manipulate an LLM node’s classification or extracted arguments. Use schema validation, authorization checks, content isolation, and approval gates at every sensitive boundary.

FAQ

Is ADK 2.0 a replacement for MCP?

No. ADK is an agent development framework and workflow runtime. MCP is a tool and context protocol. ADK can use MCP tools, while its workflow graph controls application-level execution.

Should every AI agent use a deterministic workflow?

No. Open-ended research, brainstorming, and exploratory tasks may benefit from autonomous loops. Use deterministic control when ordering, permissions, compliance, or side effects matter.

Does ADK 2.0 support Python and Go?

Yes. The official ADK 2.0 documentation lists Python and Go support, with separate compatibility guidance for each language. Check the relevant language documentation before migrating.

Can a workflow still call an LLM?

Yes. The intended design is hybrid: deterministic nodes handle routing and operations, while specialized agents handle ambiguous interpretation or generation.

Conclusion

ADK 2.0 is best understood as a control-plane change for agent applications. The model remains useful, but it no longer has to impersonate a workflow engine. Developers can define the reliable path in code, call an LLM only where judgment is needed, and make each transition observable and testable.

For a prototype, the migration may feel like extra structure. For a production system, that structure is the point. Start with one high-risk workflow, move fixed transitions out of the prompt, validate every model-produced decision, and measure the result against the old autonomous loop.

Sources and further reading

• Google Developers Blog: Why we built ADK 2.0
• Official ADK 2.0 documentation and compatibility guide
• Google ADK Python releases
• Google Developer Expert: Building AI Agents with Go ADK 2.0
• ADK documentation home

Visual credit: original Mermaid architecture diagram by Essa Mamdani, based on the workflow and compatibility concepts documented in the linked Google ADK sources.

Visual: Agent loop

This original workflow diagram shows the plan-act-observe-verify loop behind the agent system discussed in this article.

Visual reading: an agent is useful because it can act and verify, not merely because it can produce a chat response. Every loop needs scope, permissions, budget, and an exit condition.