DEV Community

Peyton Green
Peyton Green

Posted on

google-adk 2.0 Is Now Stable: Workflow Runtimes, Breaking Changes, and How to Migrate

#ai #googlecloud #python #tutorial

What google-adk 2.0 Changes

1. The Workflow Runtime (The Big One)

The biggest structural change in 2.0 is a new graph-based workflow execution engine. In 1.x, agent orchestration was largely LLM-driven — you defined tools and let the model decide when to use them. In 2.0, you can define deterministic workflows that execute regardless of what the LLM decides.

from google.adk.workflow import Workflow, node

# Define workflow nodes using the @node decorator
@node
async def validate_input(state: dict) -> dict:
    return {**state, "validated": True}

@node
async def call_external_api(state: dict) -> dict:
    # Fan-out: triggers parallel downstream nodes
    return {**state, "api_called": True}

# Compose into a Workflow
workflow = Workflow(
    nodes=[validate_input, call_external_api]
)
Enter fullscreen mode Exit fullscreen mode

This is direct competition with LangGraph's StateGraph. The key difference: ADK's Workflow Runtime is Google-native, has built-in A2A protocol support, and handles the session/state persistence layer automatically.

Supported patterns:

  • Sequential pipelines
  • Fan-out / fan-in (parallel subagent execution)
  • Loops with retry logic
  • Dynamic routing based on node output
  • Human-in-the-loop breakpoints
  • Nested workflows

2. The Event Model Is Completely Different

In 1.x, data passed between agent components through tool call results and prompt context. In 2.0, Events are the primary data primitive. Everything flows as events.

from google.adk.sessions import InMemorySessionService
from google.adk.sessions.state import State

# State is managed through the session service, not through events
session_service = InMemorySessionService()
session = await session_service.create_session(app_name="my_app", user_id="user_1")

# Read and write state through the session
async def my_node(state: dict) -> dict:
    user_context = state.get("user_context", {})
    return {**state, "processed": True, "context": user_context}
Enter fullscreen mode Exit fullscreen mode

The state field in an Event persists automatically across workflow nodes — you don't manage it manually. This is the mechanism that replaces 1.x session management.

3. The Task API for Agent-to-Agent Delegation

2.0 introduces a structured Task API for multi-agent systems. Instead of agents calling tools that happen to invoke other agents, you now have explicit task delegation semantics:

from google.adk.agents import LlmAgent
from google.adk.runners import Runner

# Coordinator agent that delegates to sub-agents
coordinator = LlmAgent(
    name="coordinator",
    model="gemini-2.0-flash",
    sub_agents=[researcher_agent, writer_agent],
    instruction="Coordinate research and writing tasks."
)

# Run with explicit delegation through the runner
runner = Runner(agent=coordinator, app_name="my_app")
Enter fullscreen mode Exit fullscreen mode

This integrates with the A2A protocol, so ADK agents can delegate tasks to non-ADK agents over the standard A2A wire format.

What Breaks in 2.0

Storage Incompatibility (Critical)

Do not use ADK 2.0 storage with ADK 1.x databases. This isn't a "things might break" warning — Google explicitly flags this as data loss territory. The session schema, memory systems, and evaluation data storage are all incompatible between versions.

If you're running 1.x in production, you need to:

  1. Back up your session data before any migration work
  2. Run 1.x and 2.0 projects in completely separate storage environments
  3. Plan a migration window, not an in-place upgrade

Agent API Changes

The top-level agent API has breaking changes across the board. In 1.x, agents were structured around tool calls and hierarchical execution. In 2.0, the entire execution model shifts to graph-based workflows with explicit node definitions and event routing. Key API breaks:

  • Agent initialization: 1.x Agent() constructor signature changed. 2.0 agents must be wrapped in or deployed as WorkflowRuntime nodes.
  • Tool definition: 1.x @tool decorators are superseded by @WorkflowNode patterns. Tool invocation is now event-routed, not LLM-driven.
  • Session state: 1.x session objects with .state attributes replaced by Event-based state persistence. All state must flow through Event.with_state().
  • Response format: 1.x agent responses (direct returns or text) now return structured Event objects with output and node_info fields.

The general pattern is that 1.x agents that used the tool-centric API will need to be restructured around the Event model and WorkflowRuntime graph orchestration.

Session Schema

Session handling is rebuilt around the Event model. Any code that directly manipulated session state in 1.x will need to be rewritten.

Python Version Requirement

2.0 requires Python 3.11+. If you're on 3.10 or earlier, you'll need to upgrade your environment before you can use 2.0.0.

The Security Note: LiteLLM

2.0.0a2 explicitly pins LiteLLM to version 1.82.6, excluding 1.82.7 and 1.82.8. Those two versions were compromised in a supply chain incident. If your 1.x setup uses LiteLLM and you haven't checked your pinned version, check it now — independently of any ADK migration.

# Check your current LiteLLM version
pip show litellm | grep Version

# If you see 1.82.7 or 1.82.8, upgrade immediately
pip install "litellm==1.82.6"
Enter fullscreen mode Exit fullscreen mode

Migration Strategy

Don't migrate during a sprint. Here's the sequence that makes sense:

Step 1: Audit your 1.x footprint

# Find all ADK imports in your codebase
grep -r "from google.adk" . --include="*.py"
grep -r "import google.adk" . --include="*.py"
Enter fullscreen mode Exit fullscreen mode

Step 2: Isolate storage
Stand up a separate dev environment with fresh storage before touching any 2.0 code. Your 1.x session data and your 2.0 dev environment should never share a database.

Step 3: Install 2.0.0 stable
Standard pip install google-adk now pulls 2.0.0 by default. Explicit pin optional but recommended:

pip install "google-adk==2.0.0"
Enter fullscreen mode Exit fullscreen mode

Or update if you're already on a 2.0 alpha:

pip install --upgrade "google-adk==2.0.0"
Enter fullscreen mode Exit fullscreen mode

Step 4: Port your agents to the Event model
The workflow is: identify what state your agents pass around → convert to Event state fields → rebuild orchestration logic using WorkflowRuntime instead of tool chains.

Step 5: Update your A2A integrations
If you're using the A2A protocol, the Task API in 2.0 gives you a cleaner integration path than the 1.x approach. Worth rewriting these deliberately rather than patching.

When to Migrate

2.0.0 is now stable (released May 19, 2026). The migration window is open. Production workloads on 1.x should be evaluated for migration readiness — don't rush, but don't treat this as "far away" anymore. Most teams should plan a migration within the next 2-4 weeks depending on code complexity and storage requirements.

What This Means for Your Tooling

The Workflow Runtime makes ADK 2.0 a direct competitor to LangGraph for Python agent orchestration. The big difference: ADK is Google-native with built-in Vertex AI, Cloud Run, and A2A integration. If you're already deep in Google Cloud, this is worth evaluating seriously.

If you're not on Google Cloud, LangGraph still has a more mature ecosystem and the new A2A Task API in ADK 2.0 doesn't change that calculus much.

For evaluating any major agent framework migration, the AI Dev Toolkit has 30+ prompts specifically for agent architecture decisions — framework comparisons, migration planning, multi-agent design review. Cheaper than an afternoon of context-switching.

Summary

What changed Impact
Workflow Runtime (graph-based) New architecture for deterministic agent flows — as of 2.0.0 stable
Event model All data now flows as Events — major rewrite of state management — as of 2.0.0 stable
Task API Structured agent-to-agent delegation, A2A-native — as of 2.0.0 stable
Storage 1.x and 2.0 storage are incompatible — separate environments required — confirmed in 2.0.0 stable
Session schema Rebuilt — 1.x session code needs rewriting — confirmed in 2.0.0 stable
Python 3.11+ required Upgrade your environment if on 3.10 or earlier — confirmed in 2.0.0 stable
LiteLLM security 2.0.0 stable excludes 1.82.7-1.82.8 (compromised). Check your pins immediately if running < 1.82.6.

Spotted something that changed between this article and current ADK 2.0 stable? Drop it in the comments — this space moves fast.

Top comments (0)