{"id":2046,"library":"google-adk","title":"Google Agent Development Kit (ADK)","description":"The Google Agent Development Kit (ADK) is an open-source, code-first Python framework for building, evaluating, and deploying sophisticated AI agents. It provides a flexible and modular approach to developing multi-agent systems, optimized for Gemini and the Google ecosystem but designed to be model-agnostic. Currently at version 1.28.1, ADK features a rich tool ecosystem, robust debugging capabilities, and support for orchestrating complex agent workflows. It maintains an active release cadence with frequent updates and new features.","status":"active","version":"1.28.1","language":"en","source_language":"en","source_url":"https://github.com/google/adk-python","tags":["AI Agents","LLM","Google Cloud","Gemini","Agentic AI","Orchestration"],"install":[{"cmd":"pip install google-adk","lang":"bash","label":"Install stable version"},{"cmd":"pip install google-adk --pre","lang":"bash","label":"Install ADK 2.0 alpha (breaking changes)"}],"dependencies":[{"reason":"Requires Python 3.10+ for stable v1.x, and 3.11+ for ADK 2.0 alpha.","package":"python","optional":false},{"reason":"Core dependency for interacting with Google's generative AI models like Gemini.","package":"google-genai","optional":false},{"reason":"Used for data validation and settings management.","package":"pydantic","optional":false},{"reason":"Used for creating API servers for agents, especially the `adk api_server` command.","package":"fastapi","optional":false},{"reason":"Asynchronous HTTP client used internally.","package":"httpx","optional":false},{"reason":"For built-in observability and tracing.","package":"opentelemetry-sdk","optional":false}],"imports":[{"note":"The `Agent` class is the modern and recommended way to define agents. Directly importing from `google.adk.agents.llm_agent` might indicate usage of an older pattern which was superseded.","wrong":"from google.adk.agents.llm_agent import Agent","symbol":"Agent","correct":"from google.adk.agents import Agent"},{"note":"The `App` class is used for centralized configuration and lifecycle management of agent workflows.","symbol":"App","correct":"from google.adk.apps import App"},{"note":"Used for persistent session storage in production environments.","symbol":"DatabaseSessionService","correct":"from google.adk.sessions import DatabaseSessionService"}],"quickstart":{"code":"import os\nfrom google.adk.agents import Agent\n\n# Ensure you have your Google AI Studio API key set as an environment variable\n# For example: export GOOGLE_API_KEY='YOUR_API_KEY'\n# If using Vertex AI, set GOOGLE_GENAI_USE_VERTEXAI='True'\nif not os.environ.get('GOOGLE_API_KEY') and not os.environ.get('GOOGLE_GENAI_USE_VERTEXAI'):\n    print(\"Warning: GOOGLE_API_KEY or GOOGLE_GENAI_USE_VERTEXAI environment variable not set.\")\n    print(\"Please set one to run the agent. You can get a free API key at aistudio.google.com/api\")\n    exit()\n\n# Define your agent - the main agent MUST be named 'root_agent'\nroot_agent = Agent(\n    name=\"hello_assistant\",\n    model=\"gemini-2.0-flash\", # Or your preferred model, e.g., 'gemini-1.5-pro'\n    description=\"A friendly AI assistant for general conversation\",\n    instruction=(\n        \"You are a warm and helpful assistant. \"\n        \"Greet users enthusiastically and answer their questions clearly. \"\n        \"Be conversational and friendly!\"\n    ),\n)\n\n# To run this agent, save it as `agent.py` in a directory (e.g., `my_agent/`)\n# and ensure an empty `__init__.py` exists in the same directory (`my_agent/__init__.py`).\n# Then, from the parent directory, run:\n# adk run my_agent\n# Or for the web UI:\n# adk web --agent-dir my_agent\n","lang":"python","description":"This quickstart defines a simple conversational AI agent using the `Agent` class. It demonstrates how to set up the agent with a name, model, description, and instruction. The `root_agent` variable name is crucial for ADK to discover and run the agent. Users need to provide a Google API key (via `GOOGLE_API_KEY` environment variable) or configure Vertex AI access. The code includes a warning for missing authentication setup. Once saved in a proper project structure (e.g., `my_agent/agent.py` and `my_agent/__init__.py`), it can be run via the `adk CLI`."},"warnings":[{"fix":"Do not use ADK 2.0 Alpha in production environments if backward compatibility is required. For new projects, ensure a Python 3.11+ virtual environment is used and install with `pip install google-adk --pre`. Do NOT share storage with ADK 1.x projects.","message":"ADK 2.0 Alpha introduces significant breaking changes, rendering it incompatible with ADK 1.x databases and sessions. APIs are subject to change without notice. It also raises the minimum Python requirement to 3.11+.","severity":"breaking","affected_versions":"2.0.0a1+"},{"fix":"Regularly check release notes for migration instructions when upgrading. For database schema changes, manual migration scripts might be necessary, though Alembic adoption is planned to automate this. Ensure `await` is used for async service calls.","message":"Schema changes in minor versions (e.g., 1.14.0, 1.17.0, 1.19.0) have historically broken deployments without clear migration paths, particularly for database-backed sessions. Core service methods became async requiring `await` for calls to session, memory, and artifact services.","severity":"breaking","affected_versions":"1.x (notably 1.14.0, 1.17.0, 1.19.0, 1.0+ async changes)"},{"fix":"Always name your primary agent variable `root_agent`. Use `from google.adk.agents import Agent` for defining agents.","message":"The main agent definition file must define an `Agent` instance named `root_agent` for ADK's CLI and web UI to automatically discover and run it. Importing older `LlmAgent` instead of `Agent` is also a common mistake.","severity":"gotcha","affected_versions":"All 1.x and 2.0 Alpha"},{"fix":"Instead of callbacks, use Tools for operations like RAG so the agent explicitly 'knows' it's retrieving data. For human-in-the-loop interactions, use the `require_confirmation` tool config. Implement deterministic `BaseAgent` instances for long-running tasks as workflow steps.","message":"Treating AI agent callbacks (hooks) as a dumping ground for heavy business logic, such as RAG operations or long-running tasks, can lead to timeouts and difficult-to-debug agents, breaking the event loop.","severity":"gotcha","affected_versions":"All 1.x and 2.0 Alpha"},{"fix":"Plan for custom multi-user implementations by creating separate agent instances per user. Be aware that the built-in Web UI might not support debugging these custom per-user agents, necessitating alternative debugging approaches (e.g., logging, custom interfaces).","message":"By default, ADK assumes a single root agent shared across users. Implementing multi-user support requires custom logic to create separate agents per user, which can lead to losing built-in debugging tools like the Web UI for these custom per-user agents.","severity":"gotcha","affected_versions":"All 1.x and 2.0 Alpha"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}