This page provides a minimal working example to help you create, configure, and run your first ADK agent in under 5 minutes. It assumes you have already completed installation (see Installation) and are ready to write agent code.
For deeper understanding of ADK's fundamental concepts like Agents, Runners, Sessions, and Tools, see Core Concepts. For agent configuration options beyond basic examples, see Agent Configuration. For deployment to production environments, see Deployment.
Before beginning this guide:
adk --versionTitle: Quick Start Development Workflow
Sources: src/google/adk/cli/cli_tools_click.py342-402 README.md62-84
Use the adk create command to scaffold a new agent project:
This command creates the following directory structure:
my_first_agent/
├── __init__.py
├── agent.py # Agent definition
├── .env # Environment variables (create this)
└── requirements.txt # Python dependencies
| CLI Option | Description | Example |
|---|---|---|
--model | Specify LLM model | --model gemini-2.0-flash-exp |
--api_key | Google AI Studio API key | --api_key YOUR_KEY |
--project | Google Cloud project ID | --project my-gcp-project |
--region | Google Cloud region | --region us-central1 |
Sources: src/google/adk/cli/cli_tools_click.py342-402 src/google/adk/cli/cli_create.py
Create a .env file in your agent directory with your LLM provider credentials.
For Google AI Studio:
For Google Cloud Vertex AI:
Sources: README.md95-97 CONTRIBUTING.md207-233
Every ADK agent requires an agent.py file that defines a root_agent variable. This is the entry point ADK uses to load your agent.
Title: Agent Definition Structure
Minimal Example:
With Tools Example:
| Parameter | Required | Description |
|---|---|---|
name | Yes | Unique identifier for the agent |
model | Yes | LLM model identifier (e.g., "gemini-2.0-flash-exp") |
instruction | Yes | System prompt defining agent behavior |
description | No | Human-readable agent purpose |
tools | No | List of tool functions agent can use |
Sources: README.md100-114 src/google/adk/agents/llm_agent.py contributing/adk_project_overview_and_architecture.md36-46
Title: Required Agent Directory Structure
Requirements:
__init__.py must contain: from . import agentagent.py must define: root_agent = <Agent instance>.env file should contain LLM provider credentialsSources: contributing/adk_project_overview_and_architecture.md27-46
ADK provides three ways to run agents locally for development and testing:
The adk run command provides a terminal-based chat interface:
Title: adk run Execution Flow
| Option | Description | Example |
|---|---|---|
--session_service_uri | Session storage backend | --session_service_uri memory:// |
--artifact_service_uri | Artifact storage backend | --artifact_service_uri memory:// |
--save_session | Save session on exit | --save_session |
--session_id | Resume specific session | --session_id abc123 |
Sources: src/google/adk/cli/cli_tools_click.py505-600 src/google/adk/cli/cli.py
The adk web command launches a browser-based development interface with debugging capabilities:
This starts a FastAPI server (default: http://127.0.0.1:8000) and opens your browser to the ADK Web UI.
Features:
Title: adk web Architecture
| Option | Description | Example |
|---|---|---|
--host | Server bind address | --host 0.0.0.0 |
--port | Server port | --port 8080 |
--use_local_storage | Use .adk folder for storage | --use_local_storage |
Sources: src/google/adk/cli/cli_tools_click.py1202-1269 src/google/adk/cli/fast_api.py72-542 src/google/adk/cli/adk_web_server.py445-685
For automated testing or custom integration, use the Runner directly in Python:
Sources: src/google/adk/runners.py tests/unittests/cli/test_fast_api.py116-147
ADK uses service URIs to configure where sessions and artifacts are stored. For local development, use in-memory services:
Title: Local Storage Service Options
| Service | URI Pattern | Use Case |
|---|---|---|
| In-memory | memory:// | Quick testing, no persistence |
| Local files | --use_local_storage | Development with persistence |
| SQLite | sqlite:///path/to/db.sqlite | Local database |
Sources: src/google/adk/cli/cli_tools_click.py422-502 src/google/adk/cli/utils/service_factory.py
Test 1: CLI Interaction
Test 2: Web UI
After completing this quick start:
Sources: README.md142-152 CONTRIBUTING.md83-131
| Issue | Solution |
|---|---|
ModuleNotFoundError: No module named 'google.adk' | Reinstall: pip install google-adk |
No root_agent found in agent.py | Ensure agent.py defines root_agent = LlmAgent(...) |
API authentication failed | Check .env file has correct credentials |
Port 8000 already in use | Use --port 8080 or kill existing process |
| Agent responds with "I don't have access to tools" | Verify tools=[...] parameter in agent definition |
Sources: src/google/adk/cli/utils/agent_loader.py CONTRIBUTING.md177-181
Refresh this wiki
This wiki was recently refreshed. Please wait 5 days to refresh again.