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.

markdown

# 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

bash

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
`--google-api-key`	`-k`	—	Use Google AI Studio instead of Vertex AI
`--agent-guidance-filename`		`GEMINI.md`	Guidance file name ( `CLAUDE.md` , `AGENTS.md` )
`--debug`		off	Enable debug logging for troubleshooting

Enhance an Existing Project

bash

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.

bash

# 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

bash

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

bash

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

curl -LsSf https://astral.sh/uv/install.sh | sh

uv

is not an option, use pip instead:

bash

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

adk-scaffold

NPX Install

Tags

SKILL.md Content

ADK Project Scaffolding Guide

Step 1: Gather Requirements

Step 2: Write DESIGN_SPEC.md

Step 3: Create or Enhance the Project

Create a New Project

Create Flags

Enhance an Existing Project

Enhance Flags

Common Workflows

Template Options

Deployment Options

"Prototype First" Pattern (Recommended)

Agent Engine and session_type

Step 4: Save DESIGN_SPEC.md and Load Dev Workflow

Scaffold as Reference

Critical Rules

Examples

Troubleshooting

`uvx`
command not found