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:

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

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 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`, `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	Standard ADK agent (default)
`adk_a2a`	Agent Engine, Cloud Run	Agent-to-agent coordination (A2A protocol)
`agentic_rag`	Agent Engine, Cloud Run	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.
`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

Examples

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

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

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.

adk-scaffold