Google Agent Development Kit (ADK) Guide

Overview

ADK is Google's open-source framework for building AI agents powered by Gemini models. ADK 2.0+ introduces a graph-based Workflow Runtime engine where agents, tools, and functions are nodes in a composable execution graph. Supports single-agent, multi-agent, collaborative, and dynamic workflow architectures with built-in memory, artifacts, tools, callbacks, and deployment options.

Critical Rules

1. Entry point is root_agent — a module-level variable in agent.py, or a Workflow object for graph-based agents.
2. Every agent package MUST have __init__.py that imports the agent module: from . import agent
3. Set GOOGLE_API_KEY in .env or configure Vertex AI credentials before running.
4. In ADK 2.0, agents are nodes. Do NOT override _run_async_impl() — use BeforeAgentCallback / AfterAgentCallback instead.
5. Do NOT append events directly to context.session.events. Yield events from your node so the framework manages persistence and routing.
6. Never catch BaseException in tools — it breaks HITL pause/resume and automatic retries.
7. One agent = one responsibility. Split agents with 5+ tools into specialists.
8. Use output_key + output_schema for reliable data flow between agents — not free text.