google/adk-scaffold

ADK Project Scaffolding Guide

Use the agent-starter-pack CLI (via uvx) to create new ADK agent projects or enhance existing ones with deployment, CI/CD, and infrastructure scaffolding.

---

Step 1: Gather Requirements

Start with the use case, then ask follow-ups based on answers.

Always ask:

1. What problem will the agent solve? — Core purpose and capabilities
2. External APIs or data sources needed? — Tools, integrations, auth requirements
3. Safety constraints? — What the agent must NOT do, guardrails
4. Deployment preference? — Prototype first (recommended) or full deployment? If deploying: Agent Engine, Cloud Run, or GKE?

Ask based on context:

• If retrieval or search over data mentioned (RAG, semantic search, vector search, embeddings, similarity search, data ingestion) → Datastore? Use --agent agentic_rag --datastore <choice>:
  • vertex_ai_vector_search — for embeddings, similarity search, vector search
  • vertex_ai_search — for document search, search engine
• If agent should be available to other agents → A2A protocol? Use --agent adk_a2a to expose the agent as an A2A-compatible service.
• If full deployment chosen → CI/CD runner? GitHub Actions (default) or Google Cloud Build?
• If Cloud Run or GKE chosen → Session storage? In-memory (default), Cloud SQL (persistent), or Agent Engine (managed).
• If deployment with CI/CD chosen → Git repository? Does one already exist, or should one be created? If creating, public or private?

---

Step 2: Write DESIGN_SPEC.md

Compose a detailed spec with these sections. Present the full spec for user approval before scaffolding.

# DESIGN_SPEC.md

## Overview
2-3 paragraphs describing the agent's purpose and how it works.

## Example Use Cases
3-5 concrete examples with expected inputs and outputs.

## Tools Required
Each tool with its purpose, API details, and authentication needs.

## Constraints & Safety Rules
Specific rules — not just generic statements.

## Success Criteria
Measurable outcomes for evaluation.

## Edge Cases to Handle
At least 3-5 scenarios the agent must handle gracefully.

The spec should be thorough enough for another developer to implement the agent without additional context.

---

Step 3: Create or Enhance the Project

Create a New Project

uvx agent-starter-pack create <project-name> \
  --agent <template> \
  --deployment-target <target> \
  --region <region> \
  --prototype \
  -y

Constraints:

• Project name must be 26 characters or less, lowercase letters, numbers, and hyphens only.
• Do NOT mkdir the project directory before running create — the CLI creates it automatically. If you mkdir first, create will fail or behave unexpectedly.
• Auto-detect the guidance filename based on the IDE you are running in and pass --agent-guidance-filename accordingly.
• When enhancing an existing project, check where the agent code lives. If it's not in app/, pass --agent-directory <dir> (e.g. --agent-directory agent). Getting this wrong causes enhance to miss or misplace files.

Create Flags

| Flag | Short | Default | Description | |------|-------|---------|-------------| | --agent | -a | adk | Agent template (see template table below) | | --deployment-target | -d | agent_engine | Deployment target (agent_engine, cloud_run, gke, none) | | --region | | us-central1 | GCP region | | --prototype | -p | off | Skip CI/CD and Terraform (recommended for first pass) | | --cicd-runner | | skip | github_actions or google_cloud_build | | --datastore | -ds | — | Datastore for data ingestion (vertex_ai_search, vertex_ai_vector_search) | | --session-type | | in_memory | Session storage (in_memory, cloud_sql, agent_engine) | | --auto-approve | -y | off | Skip confirmation prompts | | --skip-checks | -s | off | Skip GCP/Vertex AI verification checks | | --agent-directory | -dir | app | Agent code directory name | | --agent-guidance-filename | | GEMINI.md | Guidance file name (CLAUDE.md, AGENTS.md) | | --debug | | off | Enable debug logging for troubleshooting |

By default, the scaffolded project uses Google Cloud credentials (Vertex AI). For API key setup and model configuration, see Configuring Gemini models and Supported models.

Enhance an Existing Project

uvx agent-starter-pack enhance . \
  --deployment-target <target> \
  -y

Run this from inside the project directory (or pass the path instead of .). Remember that enhance creates new files (.github/, deployment/, tests/load_test/, etc.) that need to be committed.

Enhance Flags

All create flags are supported, plus:

| Flag | Short | Default | Description | |------|-------|---------|-------------| | --name | -n | directory name | Project name for templating | | --base-template | -bt | — | Override base template (e.g. agentic_rag to add RAG) | | --dry-run | | off | Preview changes without applying | | --force | | off | Force overwrite all files (skip smart-merge) |

Common Workflows

Always ask the user before running these commands. Present the options (CI/CD runner, deployment target, etc.) and confirm before executing.

# Add deployment to an existing prototype
uvx agent-starter-pack enhance . --deployment-target agent_engine -y

# Add CI/CD pipeline (ask: GitHub Actions or Cloud Build?)
uvx agent-starter-pack enhance . --cicd-runner github_actions -y

# Add RAG with data ingestion
uvx agent-starter-pack enhance . --base-template agentic_rag --datastore vertex_ai_search -y

# Preview what would change (dry run)
uvx agent-starter-pack enhance . --deployment-target cloud_run --dry-run -y

---

Template Options

| Template | Deployment | Description | |----------|------------|-------------| | adk | Agent Engine, Cloud Run, GKE | Standard ADK agent (default) | | adk_a2a | Agent Engine, Cloud Run, GKE | Agent-to-agent coordination (A2A protocol) | | agentic_rag | Agent Engine, Cloud Run, GKE | RAG with data ingestion pipeline |

---

Deployment Options

| Target | Description | |--------|-------------| | agent_engine | Managed by Google (Vertex AI Agent Engine). Sessions handled automatically. | | cloud_run | Container-based deployment. More control, requires Dockerfile. | | gke | Container-based on GKE Autopilot. Full Kubernetes control. | | none | No deployment scaffolding. Code only. |

"Prototype First" Pattern (Recommended)

Start with --prototype to skip CI/CD and Terraform. Focus on getting the agent working first, then add deployment later with enhance:

# Step 1: Create a prototype
uvx agent-starter-pack create my-agent --agent adk --prototype -y

# Step 2: Iterate on the agent code...

# Step 3: Add deployment when ready
uvx agent-starter-pack enhance . --deployment-target agent_engine -y

Agent Engine and session_type

When using agent_engine as the deployment target, Agent Engine manages sessions internally. If your code sets a session_type, clear it — Agent Engine overrides it.

---

Step 4: Save DESIGN_SPEC.md and Load Dev Workflow

After scaffolding, save the approved spec from Step 2 to the project root as DESIGN_SPEC.md.

Then immediately load /adk-dev-guide — it contains the development workflow, coding guidelines, and operational rules you must follow when implementing the agent.

---

Scaffold as Reference

When you need specific files (Terraform, CI/CD workflows, Dockerfile) but don't want to scaffold the current project directly, create a temporary reference project in /tmp/:

uvx agent-starter-pack create /tmp/ref-project \
  --agent adk \
  --deployment-target cloud_run \
  --cicd-runner github_actions \
  -y

Inspect the generated files, adapt what you need, and copy into the actual project. Delete the reference project when done.

This is useful for:

• Non-standard project structures that enhance can't handle
• Cherry-picking specific infrastructure files
• Understanding what ASP generates before committing to it

---

Critical Rules

• NEVER change the model in existing code unless explicitly asked
• NEVER mkdir before create — the CLI creates the directory; pre-creating it causes enhance mode instead of create mode
• NEVER create a Git repo or push to remote without asking — confirm repo name, public vs private, and whether the user wants it created at all
• Always ask before choosing CI/CD runner — present GitHub Actions and Cloud Build as options, don't default silently
• Agent Engine clears session_type — if deploying to agent_engine, remove any session_type setting from your code
• Start with --prototype for quick iteration — add deployment later with enhance
• Project names must be ≤26 characters, lowercase, letters/numbers/hyphens only
• NEVER write A2A code from scratch — the A2A Python API surface (import paths, AgentCard schema, to_a2a() signature) is non-trivial and changes across versions. Always use --agent adk_a2a to scaffold A2A projects.

---

Examples

Using scaffold as reference: User says: "I need a Dockerfile for my non-standard project" Actions:

1. Create temp project: uvx agent-starter-pack create /tmp/ref --agent adk --deployment-target cloud_run -y
2. Copy relevant files (Dockerfile, etc.) from /tmp/ref
3. Delete temp project Result: Infrastructure files adapted to the actual project

---

A2A project: User says: "Build me a Python agent that exposes A2A and deploys to Cloud Run" Actions:

1. Follow the standard flow (gather requirements, DESIGN_SPEC, scaffold)
2. uvx agent-starter-pack create my-a2a-agent --agent adk_a2a --deployment-target cloud_run --prototype -y Result: Valid A2A imports and Dockerfile — no manual A2A code written.

---

Troubleshooting

uvx command not found

Install uv following the official installation guide.

If uv is not an option, use pip instead:

# macOS/Linux
python -m venv .venv && source .venv/bin/activate
# Windows
python -m venv .venv && .venv\Scripts\activate

pip install agent-starter-pack
agent-starter-pack create <project-name> ...

For all available options, run uvx agent-starter-pack create --help.