# Google Adk Scaffold

> 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.

- Skill: `eagleisbatman/google-adk-scaffold` (Agent Skill)
- Install (CLI): `npx skillmds@latest add eagleisbatman/google-adk-scaffold`
- Raw SKILL.md: https://api.skillmd.com/api/skills/eagleisbatman/google-adk-scaffold/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: eagleisbatman (https://skillmd.com/u/eagleisbatman)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/eagleisbatman/google-adk-scaffold

---


# 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)

```python
from . import agent
```

## agent.py — Simple Agent Pattern

```python
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)

```python
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

```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

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

## Setup Commands

```bash
# 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