google-adk-scaffold

name	google-adk-scaffold
description	Scaffold a new Google ADK (Agent Development Kit) Python project. Use when creating a new ADK agent project from scratch — sets up directory structure, __init__.py, agent.py, pyproject.toml, and .env template.

Google ADK Python — Project Scaffold

Requirements

• Python 3.10+ (3.11+ recommended)
• uv package manager (install: curl -LsSf https://astral.sh/uv/install.sh | sh)
• Google API key (GOOGLE_API_KEY) or Vertex AI credentials

Project Structure (Required Convention)

ADK CLI (adk web, adk run) auto-discovers agents via this structure:

my_project/
├── my_agent/
│   ├── __init__.py       # MUST contain: from . import agent
│   ├── agent.py          # MUST define: root_agent = Agent(...)
│   └── tools.py          # Optional: custom tool functions
├── .env                  # GOOGLE_API_KEY or GOOGLE_CLOUD_PROJECT
└── pyproject.toml

init.py (Required)

from . import agent

agent.py — Simple Agent Pattern

from google.adk.agents import Agent

root_agent = Agent(
    name="my_agent",
    model="gemini-2.5-flash",
    description="Brief description of what this agent does.",
    instruction="You are a helpful assistant that...",
    tools=[],
)

agent.py — App Pattern (plugins, compaction)

from google.adk.agents import Agent
from google.adk.apps import App

root_agent = Agent(
    name="my_agent",
    model="gemini-2.5-flash",
    instruction="You are a helpful assistant.",
    tools=[],
)

app = App(
    name="my_app",
    root_agent=root_agent,
    plugins=[],
)

pyproject.toml

[project]
name = "my-adk-agent"
version = "0.1.0"
description = "ADK agent project"
requires-python = ">=3.10"
dependencies = [
    "google-adk>=1.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
]

.env Template

GOOGLE_API_KEY=your-api-key-here
# Or for Vertex AI:
# GOOGLE_CLOUD_PROJECT=your-project-id
# GOOGLE_CLOUD_LOCATION=us-central1

Setup Commands

# Create venv
uv venv --python "python3.11" ".venv"
source .venv/bin/activate

# Install dependencies
uv sync

# Run agent (interactive CLI)
adk run my_agent/

# Launch web UI
adk web my_agent/

# Start API server
adk api_server my_agent/

Available Models

Model	Use Case
gemini-2.5-flash	Fast, cost-effective (default)
gemini-2.5-pro	Complex reasoning
gemini-2.0-flash	Legacy, still supported

Multi-Agent Directory Structure

my_project/
├── coordinator/
│   ├── __init__.py
│   ├── agent.py          # root_agent with sub_agents=[]
│   ├── researcher.py     # Sub-agent definitions
│   └── writer.py         # Sub-agent definitions
├── .env
└── pyproject.toml

Related Skills

• google-adk-llm-agent — Agent configuration and parameters
• google-adk-function-tool — Creating custom tools
• google-adk-app — App pattern with plugins
• google-adk-deploy — Deploying to production