google/adk-python: a code-first Python toolkit for agent graphs

What google/adk-python solves, and who it is actually for

Most agent code starts as one function with a prompt, a tool list and a loop. That shape stops working when you need a branch that only runs on certain inputs, a retry around one step, a pause for a human to approve a tool call, or a second agent that hands work back. At that point you are writing orchestration code anyway, and it is usually untested.

ADK's answer is to make the orchestration explicit. The README describes a graph-based execution engine for composing deterministic execution flows, with routing, fan-out and fan-in, loops, retry, state management, dynamic nodes, human-in-the-loop and nested workflows. The intended reader is a Python developer who wants agents to live in a repository, pass review, and be deployed as a service rather than configured in a console.

It is a poor fit for someone who wants to describe an agent in a form and get a hosted endpoint back. There is no hosted control plane in this repository. The README points at Cloud Run and Vertex AI Agent Engine as deployment targets, which means you still own the container, the credentials and the uptime.

Agent and Workflow: the two classes that carry the model

The whole framework reduces to two classes in the quick start. An Agent holds a name, a model and an instruction. A Workflow holds edges, and an edge is a tuple that names a start node and the nodes that follow it. That is the mental model: agents are the units of work, workflows are the wiring.

The graph is not only for agents. The README lists task agents as workflow nodes, so a Task API call can sit in the same graph as an agent, and the task layer supports multi-turn task mode, single-turn controlled output, mixed delegation patterns and human-in-the-loop. Delegation between agents is therefore a first-class edge rather than a tool call that happens to invoke another agent.

Two design choices are worth flagging. First, the framework is code-first by default, and the README presents Agent Config as the no-code alternative rather than the primary path. Second, it is optimized for Gemini but described as model-agnostic; the dependency list pins google-genai, so the Gemini path is the one that gets exercised by the package's own dependency graph. Treat model-agnostic as a claim to verify against your provider, not as a guarantee.

Installing google-adk and running a first agent

The stable release installs from PyPI and requires Python 3.10 or newer. The README recommends installing with the companion constraints file that matches your Python version, because the project publishes one per minor version from 3.10 through 3.14.

pip install google-adk

For dependency protection, the README gives a constraints-file flow. Download the file for your interpreter, install against it, then delete it. If you are on 3.12, the file is constraints-3.12.txt.

curl -o constraints-3.12.txt https://raw.githubusercontent.com/google/adk-python/main/constraints-3.12.txt
pip install google-adk -c constraints-3.12.txt
rm constraints-3.12.txt

Optional integrations come from an extra. The README shows a single extras name, extensions.

pip install "google-adk[extensions]"

A first agent is a Python file that assigns a module-level name. The README's example uses the model string gemini-2.5-flash and an instruction.

from google.adk import Agent

root_agent = Agent(
    name="greeting_agent",
    model="gemini-2.5-flash",
    instruction="You are a helpful assistant. Greet the user warmly.",
)

Run it from the directory that contains the agent. The CLI takes a path, and the web UI takes a directory of agents or a single agent folder.

adk run path/to/my_agent
adk web path/to/agents_dir

If you need a fix that has not reached PyPI, the README documents installing straight from main, and warns that this build may contain experimental changes or bugs not present in the stable release.

The 2.0 migration is the real cost of entry

The README carries a breaking-change notice for 1.x users. The 2.0 release changes the agent API, the event model and the session schema. The compatibility rule is asymmetric and worth quoting precisely: sessions generated by ADK 2.0 are readable by ADK 1.28 and later, with extra fields ignored, but they are incompatible with older 1.x versions.

That is a one-way door for anyone running a 1.x release below 1.28 with persisted sessions. Reading old sessions in new code is the easy direction; writing new sessions that an old deployment can still read is not supported. If you run two versions side by side during a rollout, the older side is the one that breaks.

The release history in the repository shows two lines moving at once: v1.39.1 was published on 2026-08-27, and v2.8.0 on 2026-08-26, with the README stating a cadence of roughly bi-weekly. Two maintained lines mean two upgrade paths to track, and the README does not document a rollback procedure for either. Plan the session migration before the code migration, not after.

The last push to the repository was on 2026-09-09.

Where ADK is the wrong tool

The framework is Python-only in this repository. The README links sibling projects for Java, Kotlin, Go and TypeScript, and those are separate codebases with their own release cadence. If your team writes Go, adk-python is not the package you install, and the parity between the language ports is not something this repository establishes.

It is also a bad fit for a single prompt with one function tool. A Workflow with one agent and no edges is ceremony. The graph runtime earns its keep when you have branching, retries or human approval; below that threshold you are paying the framework's conceptual cost for nothing.

Finally, the README does not describe a sandbox for tool execution. It offers a tool confirmation flow that guards execution with explicit confirmation and custom input, which is an approval gate, not isolation. If your tools touch production systems, the guard is a human in the loop, and you still need your own containment.

How ADK differs from a LangChain-style chain

The closest comparison is a chain-and-agent library in the LangChain family. The difference is in what the framework treats as the unit of composition.

A chain library composes runnables: you build a pipeline of steps and the agent is a step that decides which tool to call. ADK composes nodes in a graph, where an agent is one node type and a task is another, and the edges are declared up front in the Workflow constructor. Routing, fan-out and fan-in are properties of the graph rather than of the code inside a step.

That shows up in the quick start. The README's Workflow example connects START to generate_fruit_agent to generate_benefit_agent in a single edge tuple, so the order of the two agents is a declaration, not a control-flow statement. In a chain library the same thing is a sequence of calls. The ADK version is easier to inspect and to draw; the chain version is easier to build up dynamically at runtime. Neither is strictly better, but the ADK shape assumes you can name your steps in advance.

Licence, releases and what maintenance costs you

The package is Apache-2.0, declared in pyproject.toml as a file reference to LICENSE and classified as an OSI-approved Apache licence. For most teams that means permissive use with the usual notice and patent-grant terms. This is not legal advice; read the LICENSE file in the repository before you ship.

The dependency list in pyproject.toml is not small. It pins fastapi, starlette, pydantic, opentelemetry-api and opentelemetry-sdk with an upper bound of 1.42.1, google-genai, authlib, aiosqlite, graphviz, jsonschema, tenacity and others. The opentelemetry upper bound is the one to watch: if your service already pins a newer OpenTelemetry, the constraints files are the project's answer, and the README recommends them for exactly this reason.

Upgrade cost is driven by the two release lines and the session schema change. The README states the cadence is roughly bi-weekly, so the surface moves often. Budget for reading the changelog before each bump, and treat the 1.x to 2.x session boundary as a data migration project rather than a version pin.

Editorial conclusion

Adopt ADK when your agents are Python services you want to version, review and test like any other code, and when a graph of agents and tasks is a better fit than one long prompt. Skip it if you need a hosted control plane, a language other than Python, or if you cannot migrate session storage, because the README states 2.0 sessions are incompatible with older 1.x versions. Verify three things before you commit: that the current 1.x and 2.x release lines are the ones you actually want, that your Python version has a matching constraints file in the repository root, and that your model provider is reachable through the model-agnostic path rather than only through Gemini.

Frequently asked questions

Official sources

1. google/adk-python on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases