Inside google/adk-python: Multi-Agent Runner, Tool Callbacks & Session State Architecture — How Does It Work in Production?

TL;DR: Inside google/adk-python is Google's open-source, code-first Agent Development Kit (ADK 2.0) designed to move AI agents from fragile, non-deterministic prototypes to production-grade systems. By combining a graph-based workflow runtime, structured multi-agent delegation via the Task API, and seamless deployment parity between local environments and Vertex AI, it gives engineers the architectural control needed to build reliable, scalable agentic workflows.

What Is Inside google/adk-python: Multi-Agent Runner, Tool Callbacks & Session State Architecture & Why Is It Blowing Up?

In the current landscape of generative AI, the industry is experiencing a massive friction point: building a demo of an AI agent is trivial, but deploying a reliable, deterministic agentic system to production is an architectural nightmare. The google/adk-python repository—the core of the Agent Development Kit (ADK) 2.0—is blowing up because it directly addresses this "prototype-to-production" chasm.

At its core, ADK is an open-source, code-first Python framework that applies rigorous software engineering principles to AI agent creation. Rather than relying on opaque, prompt-driven routing that is prone to infinite loops and hallucinations, ADK introduces a Workflow Runtime: a graph-based execution engine for composing deterministic execution flows. It supports routing, fan-out/fan-in, loops, retries, and state management natively. While it is heavily optimized for Google's Gemini models, the framework is explicitly model-agnostic and deployment-agnostic, supporting integrations with OpenAI, Anthropic (Claude), Ollama, and vLLM.

Engineers are starring this repository because it provides a unified abstraction layer over the entire agent lifecycle. It bridges the gap between defining an agent's logic in Python and deploying it at scale. With built-in support for the Model Context Protocol (MCP), OpenAPI specs, and an advanced A2A (Agent-to-Agent) protocol, ADK allows developers to build modular multi-agent systems where specialized agents are composed into flexible hierarchies.

Real-World Field Use Cases: Where This Moves the Needle in the Field

To understand why this architecture matters, we must examine how it behaves under production constraints. Here are three concrete field use cases demonstrating what engineering teams are building with ADK.

1. Deterministic Tool Verification Gates

• The Everyday Problem: Autonomous agents are dangerous when connected to mutating APIs (e.g., executing database drops, initiating financial transactions, or sending emails). Relying purely on the LLM's internal reasoning to "be careful" is an unacceptable security posture.
• How It Works in Practice: ADK implements a native Tool Confirmation flow (Human-in-the-Loop / HITL) and a robust Callbacks architecture. Engineers can intercept LLM tool calls with pre- and post-execution callbacks. When an agent attempts to invoke a high-risk function, the execution stream pauses, emitting a state event that requires explicit confirmation or custom input before the Runner proceeds.
• The Tangible Impact: Teams achieve zero unauthorized mutations. By moving the security gate out of the prompt and into the deterministic execution graph, organizations can safely deploy agents into high-compliance environments like FinTech and healthcare.

2. Multi-Model Subagent Delegation

• The Everyday Problem: Monolithic agents powered by a single massive prompt and a single frontier model (like Gemini 2.5 Pro) are slow, expensive, and prone to context degradation.
• How It Works in Practice: Using ADK's Task API, engineers can design scalable applications by composing multiple specialized agents. A lightweight, low-latency model (e.g., gemini-2.5-flash) acts as the routing agent. Instead of flat routing, the framework wraps specialist agents (e.g., a coding agent powered by a heavier model) via AgentTool delegation. The parent agent calls the sub-agent as if it were a standard tool, preventing parent-agent context collisions and maintaining strict single-turn or multi-turn task boundaries.
• The Tangible Impact: This hierarchical delegation drastically reduces token costs and latency. Simple tasks are resolved in milliseconds by the Flash model, while complex reasoning is dynamically routed to the Pro model, optimizing the overall system's unit economics.

3. Local Playground to Cloud Run Parity

• The Everyday Problem: The classic "it works on my machine" dilemma plagues AI development. An agent behaves perfectly in a local Jupyter notebook but fails catastrophically when deployed to a cloud container due to state management or dependency mismatches.
• How It Works in Practice: ADK enforces strict environment parity. Engineers develop and test locally using the adk web built-in development UI or the agents-cli playground. When ready, the exact same agent graph is containerized and deployed using adk deploy cloud_run or scaled seamlessly with Vertex AI Agent Engine. The execution pipeline remains identical.
• The Tangible Impact: Deployment cycles shrink from weeks to minutes. Engineering teams can guarantee that the deterministic execution flows validated in local testing will behave identically in production containers, drastically reducing operational overhead.

Under the Hood: Architecture & Design Choices

When we inspect the production topology of google/adk-python#readme, we find a highly opinionated, graph-driven architecture designed to tame the non-deterministic nature of Large Language Models. The framework separates the reasoning (the Agent) from the orchestration (the Workflow).

The Workflow Runtime and Event Loop

Architecturally, ADK relies on a directed graph execution model. The Workflow class orchestrates agents and tasks. When an execution is triggered, the framework initializes an Event Loop (often conceptualized around a Runner.run_async stream in asynchronous Python environments). This runner manages the state transitions between nodes (Agents or Tools). Because the execution flow is deterministic, the runner can handle complex topologies like fan-out/fan-in and loops without relying on the LLM to decide the next step. The LLM simply outputs structured data or tool calls, and the graph routing logic dictates the transition.

AgentTool Delegation and the Task API

One of the most sophisticated design choices in ADK is the Task API and its approach to sub-agent delegation. Instead of building custom orchestrators, ADK allows an Agent to be exposed as a tool to another Agent. When the parent agent decides to delegate a task, it invokes the sub-agent via the A2A (Agent-to-Agent) protocol. This encapsulates the sub-agent's prompt, context, and tools, preventing context window pollution in the parent agent. The framework supports multi-turn task mode (where the sub-agent can interact back-and-forth before returning) and single-turn controlled output.

Session State: InMemory vs. Vertex AI Memory Bank

State management is the Achilles' heel of most agent frameworks. ADK abstracts session state to allow seamless migration from local development to enterprise deployment. Locally, ADK utilizes in-memory session services to maintain conversational context, manage state events, and handle context compression. However, when deployed to Google Cloud, ADK integrates deeply with the Vertex AI Agent Engine. The local session state is swapped for the Vertex AI Memory Bank, a persistent, scalable memory profile system that supports memory revisions, event ingestion, and IAM-conditioned access control. This allows agents to maintain long-term memory across distributed, stateless Cloud Run containers.

MCP and Extensibility

Furthermore, ADK embraces the Model Context Protocol (MCP). The architecture allows agents to utilize MCP tools natively, and more impressively, allows an ADK deployment to act as an MCP server itself. This bidirectional integration means ADK agents can seamlessly plug into existing enterprise toolchains or serve as intelligent backends for other MCP-compatible clients.

flowchart LR
    subgraph ClientLayer["Client Layer"]
        U[User / API Client]
        CLI[Agents CLI / Web UI]
    end

    subgraph AdkWorkflowRuntime["ADK Workflow Runtime"]
        R[Runner / Event Loop]
        W[Graph Workflow Orchestrator]
        
        subgraph AgentHierarchy["Agent Hierarchy"]
            A1[Root Agent<br/>gemini-2.5-flash]
            A2[Sub-Agent<br/>Task API / AgentTool]
            T1[Custom Tools / MCP]
            T2[Tool Confirmation<br/>HITL / Callbacks]
        end
    end

    subgraph SessionStateArchitecture["Session State Architecture"]
        S1[(InMemory Session<br/>Local Dev)]
        S2[(Vertex AI Memory Bank<br/>Production)]
    end

    subgraph ExternalServices["External Services"]
        LLM[Model APIs<br/>Gemini, Claude, vLLM]
        AG[Vertex AI Agent Gateway<br/>Semantic Governance]
    end

    U -->|Trigger Execution| R
    CLI -->|adk run / web| R
    R -->|Stream Events| W
    W -->|Route| A1
    A1 -->|Delegate| A2
    A1 -->|Invoke| T1
    A1 -->|Pause for Auth| T2
    
    A1 <-->|Read/Write State| S1
    A1 <-->|Read/Write State| S2
    
    A1 -->|Generate| LLM
    A2 -->|Generate| LLM
    
    W -->|Egress Traffic| AG
    
    classDef core fill:#2d3436,stroke:#74b9ff,stroke-width:2px,color:#fff;
    classDef state fill:#0984e3,stroke:#00cec9,stroke-width:2px,color:#fff;
    classDef external fill:#d63031,stroke:#ff7675,stroke-width:2px,color:#fff;
    
    class R,W,A1,A2,T1,T2 core;
    class S1,S2 state;
    class LLM,AG external;

Hands-On Quickstart & Code Walkthrough

The ADK Documentation emphasizes a code-first approach, allowing engineers to define logic, tools, and orchestration directly in Python.

1. Installation with Transitive Dependency Protection

To ensure reproducible builds, ADK recommends installing via constraints files. This prevents upstream dependency conflicts, a common issue in the rapidly moving AI ecosystem.

# Install the latest stable version for Python 3.10
curl -o constraints-3.10.txt https://raw.githubusercontent.com/google/adk-python/main/constraints-3.10.txt
pip install google-adk -c constraints-3.10.txt
rm constraints-3.10.txt

# Install optional integrations (e.g., MCP, OpenAPI)
pip install "google-adk[extensions]"

2. Defining Agents and Graph Workflows

ADK applications are built using two primary primitives: Agent and Workflow. The following code demonstrates how to create specialized agents and orchestrate them into a deterministic graph.

from google.adk import Agent, Workflow

# Define a specialized sub-agent for generation
generate_fruit_agent = Agent(
    name="generate_fruit_agent",
    instruction="Return the name of a random fruit. Return only the name.",
)

# Define a specialized sub-agent for reasoning
generate_benefit_agent = Agent(
    name="generate_benefit_agent",
    instruction="Tell me a health benefit about the specified fruit.",
)

# Orchestrate the agents into a Workflow Graph
# The edges define the deterministic execution path: START -> Fruit -> Benefit
root_agent = Workflow(
    name="root_agent",
    edges=[("START", generate_fruit_agent, generate_benefit_agent)],
)

3. Local Execution and Development UI

ADK ships with a robust CLI for local testing and debugging. You can run the agent interactively in the terminal or launch the built-in development UI to visualize the graph execution and inspect session state.

# Run the agent interactively in the terminal
adk run path/to/my_agent

# Launch the Web UI for visual debugging and trace inspection
adk web path/to/agents_dir

4. Evaluation and Production Deployment

Before deploying, engineers can run bundled evaluation sets to simulate agent behavior and measure performance against custom metrics. Once validated, deployment to Google Cloud is a single command.

# Run evaluation criteria against the agent
adk eval \
  contributing/samples/evaluation/home_automation_agent \
  contributing/samples/evaluation/basic_criteria/home_automation.evalset.json \
  --config_file_path contributing/samples/evaluation/basic_criteria/eval_config.json

# Containerize and deploy seamlessly to Cloud Run
adk deploy cloud_run --with_ui --env GOOGLE_GENAI_USE_ENTERPRISE=1

My Honest Verdict: Where It Fits in Your Stack (Pros & Trade-offs)

In our architectural evaluation of the open-source agent ecosystem, google/adk-python occupies a highly strategic position. It is not a lightweight wrapper like early versions of LangChain, nor is it a purely research-focused multi-agent simulator like AutoGen. It is an enterprise-grade orchestration framework built for scale.

The Pros: Where ADK Dominates

1. Deterministic Graph Orchestration: By forcing developers to define explicit execution paths via the Workflow class, ADK eliminates the unpredictable "agent loop" problem. You know exactly how data flows from node to node, making debugging and tracing infinitely easier.
2. First-Class Vertex AI Integration: For teams already embedded in the Google Cloud ecosystem, ADK is a superpower. The ability to swap local in-memory sessions for the Vertex AI Memory Bank, and route traffic through the Agent Gateway for Semantic Governance and Model Armor, provides out-of-the-box enterprise security and compliance.
3. The Task API and A2A Protocol: The way ADK handles sub-agent delegation is architecturally superior to flat prompt routing. Treating agents as tools (AgentTool) cleanly isolates context windows and allows for polyglot micro-agent architectures (e.g., a Python agent calling a Go agent via the A2A protocol).
4. Built-in HITL and Callbacks: The native support for Tool Confirmation flows ensures that destructive actions can be gated deterministically, a mandatory requirement for production systems.

The Trade-offs: Current Limitations

1. Google Cloud Gravity: While the framework is technically model-agnostic (supporting OpenAI, Anthropic, vLLM via LiteLLM), its deployment and state management features heavily favor Google Cloud (Cloud Run, Vertex AI). Teams heavily invested in AWS or Azure will miss out on the native Memory Bank and Agent Gateway integrations, requiring them to build custom session state adapters.
2. Learning Curve for Graph Workflows: For developers used to simply passing a list of tools to an OpenAI client and letting the model figure it out, ADK's graph-based Workflow requires a paradigm shift. Designing explicit edges, fan-outs, and state management requires upfront software engineering design, which can slow down initial prototyping.
3. Rapid Evolution: As noted in the repository, the framework operates on a bi-weekly release cadence. While this means bugs are fixed quickly, it also implies that the API surface (especially around advanced features like MCP integration and dynamic workflows) is still evolving. Teams must strictly pin their dependencies using the provided constraints files to avoid breaking changes.

Final Thoughts

If your goal is to build a quick weekend prototype, ADK might feel overly structured. However, if you are an engineering team tasked with building a reliable, multi-agent system that must integrate with enterprise APIs, maintain long-term memory, and pass strict security audits, google/adk-python provides the exact architectural primitives you need. It successfully brings standard software engineering rigor—versioning, deterministic routing, and state management—into the chaotic world of generative AI.