This section guides you through installing ADK, creating your first agent, and running it locally. For detailed installation instructions, see Installation. For a complete walkthrough of creating and running your first agent, see Quick Start Guide. For fundamental concepts about agents, sessions, and tools, see Core Concepts.
This page provides an overview of the initial setup process for developing agents with ADK. You will learn:
pip and from source.For deployment to production environments, see Deployment. For evaluation and testing workflows, see Evaluation and Testing.
Python Version: ADK supports Python 3.10+. Python 3.11 and above is strongly recommended CONTRIBUTING.md147-149 The package is tested on versions up to 3.14 src/google/adk/version.py16
LLM Provider Access: You need access to at least one LLM provider:
GOOGLE_API_KEY src/google/adk/cli/cli_create.py51-53Optional Components: Depending on your use case, you may need additional dependencies:
extensions extra for optional integrations README.md75-76test extra for running unit tests CONTRIBUTING.md186-187Sources: CONTRIBUTING.md147-149 src/google/adk/cli/cli_create.py51-58 README.md75-76 CONTRIBUTING.md186-187
Workflow: From Development to Production
Sources: README.md62-152 CONTRIBUTING.md132-215
This installs the latest stable version of ADK from PyPI README.md66-70 The current version is 1.31.0 src/google/adk/version.py16
To access the latest features and bug fixes from the main branch:
Sources: README.md82-90 src/google/adk/version.py16
The adk CLI provides several commands to manage the agent lifecycle.
| Command | Purpose | Source Reference |
|---|---|---|
adk create | Scaffolds a new agent directory with code or YAML config. | src/google/adk/cli/cli_create.py191-231 |
adk run | Runs an interactive CLI for an agent. | AGENTS.md28 |
adk web | Launches the built-in development UI. | README.md146-150 |
adk eval | Evaluates agent performance against an eval set. | README.md152-158 |
adk deploy | Deploys agents to Cloud Run, GKE, or Agent Engine. | README.md59-61 |
adk migrate | Manages database schema migrations (e.g., v0 to v2). | CHANGELOG.md11 |
Sources: src/google/adk/cli/cli_create.py191-231 README.md146-158 AGENTS.md28 README.md59-61
All agent directories must follow a specific structure for the framework to recognize them AGENTS.md140-142
Agent Module Loading Convention
The framework supports defining a root_agent directly in agent.py or using a YAML-based configuration via root_agent.yaml src/google/adk/cli/cli_create.py222-224
In your agent.py, you can define a single agent using the Agent class (an alias for LlmAgent src/google/adk/cli/cli_create.py32-40).
Sources: src/google/adk/cli/cli_create.py31-40 AGENTS.md140-152
You can run your agent interactively using the adk run command. This initializes a Runner to manage the session AGENTS.md21-30
Each call to the runner processes a single user turn, known as an invocation AGENTS.md45-46
ADK includes a built-in development UI to test and debug agents visually.
This UI allows for visual interaction with function calls and agent traces README.md146-150
Sources: README.md146-150 AGENTS.md21-46
The ADK Runner is a stateless orchestration engine and relies on external services for persistence AGENTS.md39-41
Runner and Service Dependencies
| Service | Responsibility | Implementations |
|---|---|---|
| Session | Manages conversation state and event history. | InMemorySessionService, DatabaseSessionService, VertexAISessionService, FirestoreSessionService AGENTS.md33-34 CHANGELOG.md11 |
| Artifact | Stores files, images, or audio. | FileArtifactService, GcsArtifactService AGENTS.md133-134 |
| Memory | Provides long-term recall across sessions. | VertexAiMemoryBankService, FirestoreMemoryService CHANGELOG.md9-11 AGENTS.md35-36 |
Sources: AGENTS.md17-41 CHANGELOG.md9-11 AGENTS.md133-134
InvocationContext.Refresh this wiki