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, 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:

• 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

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

• Follow the standard flow (gather requirements, DESIGN_SPEC, scaffold)

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