Google ADK
Google's open-source, multi-language Agent Development Kit: LLM agents, workflow agents and (since 2.0) a graph-based workflow runtime, with sessions/state, evaluation, A2A and Google Cloud deployment.
Contents
Google ADK (Agent Development Kit) is Google’s open-source, code-first framework for building, evaluating and deploying agents. It has SDKs for Python (google-adk), TypeScript (@google/adk), Go, Java and Kotlin, and its docs now live at adk.dev (ADK docs). It puts model-driven agents (LlmAgent) and deterministic orchestration in one framework, and it ships sessions, state, memory, artifacts, callbacks, a web dev UI (adk web), an evaluation framework and one-command deployment to Google Cloud (Agent Runtime, Cloud Run, GKE). Gemini is the default model, and adapters cover Claude, OpenAI, Ollama, vLLM and LiteLLM (ADK docs). The biggest recent change is ADK 2.0, which went GA for Python on 2026-05-19, Go on 2026-06-30 and TypeScript on 2026-08-21. It replaced the hierarchical agent executor with a graph-based Workflow Runtime in which agents, tools and functions are all nodes (ADK 2.0).
Core primitives
| Primitive | Role |
|---|---|
Agent / LlmAgent | Model, instruction (may template {state_key}), tools, sub_agents, output_key, input/output schemas |
| Tools | Python functions (auto-schema), OpenAPI, MCP, AgentTool (an agent called as a tool), built-ins |
| Workflow agents (1.x) | SequentialAgent, ParallelAgent, LoopAgent: deterministic orchestration with no LLM deciding the order |
| Graph / dynamic workflows (2.0) | Nodes and edges with code-based routing, or orchestration in plain async code |
Runner | Drives one invocation, commits events through services |
SessionService, ArtifactService, MemoryService | Conversation and state persistence, binary artifacts, cross-session memory |
| Callbacks / plugins | Before/after agent, model and tool hooks, used for guardrails and logging |
The runtime: events, Runner and state commits
ADK’s runtime is event-sourced. Agent, tool and callback code yields Events. The Runner takes each event, applies its state_delta and artifact_delta through the SessionService, appends it to history, forwards it to the UI, and only then resumes the agent (event loop).
flowchart LR U["User query"] --> R["Runner (one invocation_id)"] R --> AG["Agent / node code"] AG -->|"yield Event (content, state_delta, artifact_delta)"| R R -->|"commit"| SS["SessionService (state + events)"] R -->|"commit"| AS["ArtifactService"] R -->|"forward"| UI["Client / UI"] R -->|"resume"| AG
Consequences you will hit:
- A state change is durable only after its event is processed. Reads before that are “dirty reads”, and they are lost if the invocation fails (event loop).
- Partial streaming events are displayed, but their actions are never committed (event loop).
run_asyncis the real entry point. Blocking synchronous I/O inside a tool stalls the loop (event loop).
Session state scopes
session.state is a serialisable key-value scratchpad, scoped by key prefix (state):
| Prefix | Scope | Persistence |
|---|---|---|
| (none) | This session | With a persistent SessionService |
user: | All sessions of this user in the app | Database / Vertex AI services |
app: | All users of the app | Database / Vertex AI services |
temp: | This invocation only (shared with sub-agents) | Never |
Write state via output_key (an agent’s final text lands in a key), EventActions.state_delta, or context.state inside tools and callbacks. Never mutate session.state directly on a fetched session: it bypasses the event log, may not persist, and risks races. InMemorySessionService is for development only and isn’t thread-safe. DatabaseSessionService locks per session. VertexAiSessionService is managed (state).
Orchestration: from workflow agents to graphs
1.x style. The 1.x way to orchestrate is to compose LlmAgents under workflow agents. SequentialAgent runs sub-agents in order, ParallelAgent fans them out, and LoopAgent repeats them. None of them consults a model for ordering, so execution is predictable (workflows, Notebook). Data usually moves through state: one agent’s output_key is read by the next agent’s {placeholder}. LoopAgent stops at max_iterations (the Python default is None) or when a sub-agent sets escalate, typically through an exit tool. Without one of these it can loop forever, and prompt-based exit phrases are brittle (workflows). This maps directly onto the sequential, parallel, loop and coordinator patterns Google catalogues in its design-pattern guide. See agent design patterns.
2.0 style. Google’s stated motivation is that model-led orchestration (routing, scheduling, error handling) is slow, costly and variable, and that prompting and guardrails “can only go so far” (Why ADK 2.0). ADK 2.0 adds three styles (workflows, collaboration):
- Graph workflows. Nodes are LLM agents, function or tool nodes, or sub-workflows. Edges start at
START. Conditional edges dispatch on aroutevalue that a node emits, and fan-out and join nodes are supported. A node’s output feeds the next node’s input directly, without going through state. - Dynamic workflows. Orchestration is written in ordinary Python or async code, with loops, retries and recursion, for flows too irregular for a static graph.
- Collaborative workflows. A coordinator has
sub_agents, and each sub-agent gets an auto-generated delegation tool and a mode.chat(the default) lets the user talk freely, and control returns only on transfer.taskmay ask clarifying questions and returns onfinish_task; it must be a leaf, and it is disabled inside graphs in Python v2.0.0.single_turntakes no user input and can run in parallel. Task and single-turn agents run in isolated session branches.
In Google’s illustrative refund benchmark (a Gemini Flash model with mock APIs, not a production measurement), routing with a workflow instead of a free agent cut tokens from 5,152 to 2,265 and latency from 7.2 s to 5.7 s. The post also argues that a graph narrows prompt-injection impact because no edge exists for unauthorised actions (Why ADK 2.0). Synthesis: this is the same “deterministic skeleton, LLM at the leaves” move that LangGraph and Microsoft’s Agent Framework workflows make.
Contradiction: The ADK 2.0 release page says only the TypeScript
SequentialAgent/ParallelAgent/LoopAgentemit deprecation warnings (ADK 2.0). The template-workflow docs mark them deprecated in Python, TypeScript, Go and Kotlin (workflows). Treat them as legacy for new code either way.
A2A: agents across process boundaries
ADK can expose an agent as an Agent2Agent server and consume remote agents through RemoteA2aAgent, a client proxy that handles networking, auth and formatting (A2A). Use A2A when the other agent is a separate service, owned by another team, written in another language or framework, or needs a formal contract. Use local sub-agents for internal structure, latency-sensitive paths and shared state, because A2A adds network and serialisation overhead. Python support is full. Go, Java and Kotlin A2A support is experimental (A2A).
Limitations and failure modes
- Churn. ADK is young, and 2.0 broke custom agents (
BaseAgentnow subclassesBaseNode, so_run_async_imploverrides are bypassed). The event schema also changed, which breaks rigid session stores, and Google advises updating every reader application before writing 2.0 sessions to a shared database (ADK 2.0, Notebook). - Exception handling. Broad
except Exceptionblocks hide failures from 2.0’s automatic retries, and catchingBaseExceptionbreaks human-in-the-loop pauses (ADK 2.0). - Google-centric happy path. It is model-agnostic in principle, but the smoothest path is Gemini plus Google Cloud. Its community is also smaller than LangChain’s (Notebook).
- State pitfalls. Dirty reads,
{key}templating that errors on missing keys (use{key?}), and literal braces in instructions that collide with templating (state). - Runaway loops. A
LoopAgentwithoutmax_iterationsrelies on the model remembering to escalate (workflows).
When to use it, and when not
Use it on Google Cloud / Gemini, when you want deterministic multi-agent workflows and LLM agents in one framework, when you need multi-language SDKs (Go and Java are rare elsewhere), or when you need native A2A and built-in evaluation. For new designs, start from 2.0 graph or dynamic workflows and put LLM agents at the nodes that genuinely need judgement.
Look elsewhere if you need maximum low-level control over state and checkpointing in Python or JS (LangGraph), a minimal OpenAI-centric loop (OpenAI Agents SDK), a full computer-use agent (Claude Agent SDK), or API stability over features. Google’s own pattern guide adds that predictable single-call tasks often need no agent at all (design patterns). See also Google Vertex AI.