Adk Scaffold

1---2name: adk-scaffold3description: >4  MUST READ before creating or enhancing any ADK agent project.5  Use when the user wants to build a new agent (e.g. "build me a search agent")6  or enhance an existing project (e.g. "add CI/CD to my project", "add RAG").7metadata:8  license: Apache-2.09  author: Google10---11 12# ADK Project Scaffolding Guide13 14Use the `agent-starter-pack` CLI (via `uvx`) to create new ADK agent projects or enhance existing ones with deployment, CI/CD, and infrastructure scaffolding.15 16---17 18## Step 1: Gather Requirements19 20Start with the use case, then ask follow-ups based on answers.21 22**Always ask:**23 241. **What problem will the agent solve?** — Core purpose and capabilities252. **External APIs or data sources needed?** — Tools, integrations, auth requirements263. **Safety constraints?** — What the agent must NOT do, guardrails274. **Deployment preference?** — Prototype first (recommended) or full deployment? If deploying: Agent Engine, Cloud Run, or GKE?28 29**Ask based on context:**30 31- If **retrieval or search over data** mentioned (RAG, semantic search, vector search, embeddings, similarity search, data ingestion) → **Datastore?** Use `--agent agentic_rag --datastore <choice>`:32  - `vertex_ai_vector_search` — for embeddings, similarity search, vector search33  - `vertex_ai_search` — for document search, search engine34- If agent should be **available to other agents** → **A2A protocol?** Use `--agent adk_a2a` to expose the agent as an A2A-compatible service.35- If **full deployment** chosen → **CI/CD runner?** GitHub Actions (default) or Google Cloud Build?36- If **Cloud Run** or **GKE** chosen → **Session storage?** In-memory (default), Cloud SQL (persistent), or Agent Engine (managed).37- If **deployment with CI/CD** chosen → **Git repository?** Does one already exist, or should one be created? If creating, public or private?38 39 40---41 42## Step 2: Write DESIGN_SPEC.md43 44Compose a **detailed** spec with these sections. Present the full spec for user approval before scaffolding.45 46```markdown47# DESIGN_SPEC.md48 49## Overview502-3 paragraphs describing the agent's purpose and how it works.51 52## Example Use Cases533-5 concrete examples with expected inputs and outputs.54 55## Tools Required56Each tool with its purpose, API details, and authentication needs.57 58## Constraints & Safety Rules59Specific rules — not just generic statements.60 61## Success Criteria62Measurable outcomes for evaluation.63 64## Edge Cases to Handle65At least 3-5 scenarios the agent must handle gracefully.66```67 68The spec should be thorough enough for another developer to implement the agent without additional context.69 70---71 72## Step 3: Create or Enhance the Project73 74### Create a New Project75 76```bash77uvx agent-starter-pack create <project-name> \78  --agent <template> \79  --deployment-target <target> \80  --region <region> \81  --prototype \82  -y83```84 85**Constraints:**86- Project name must be **26 characters or less**, lowercase letters, numbers, and hyphens only.87- Do NOT `mkdir` the project directory before running `create` — the CLI creates it automatically. If you mkdir first, `create` will fail or behave unexpectedly.88- Auto-detect the guidance filename based on the IDE you are running in and pass `--agent-guidance-filename` accordingly.89- 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.90 91#### Create Flags92 93| Flag | Short | Default | Description |94|------|-------|---------|-------------|95| `--agent` | `-a` | `adk` | Agent template (see template table below) |96| `--deployment-target` | `-d` | `agent_engine` | Deployment target (`agent_engine`, `cloud_run`, `gke`, `none`) |97| `--region` | | `us-central1` | GCP region |98| `--prototype` | `-p` | off | Skip CI/CD and Terraform (recommended for first pass) |99| `--cicd-runner` | | `skip` | `github_actions` or `google_cloud_build` |100| `--datastore` | `-ds` | — | Datastore for data ingestion (`vertex_ai_search`, `vertex_ai_vector_search`) |101| `--session-type` | | `in_memory` | Session storage (`in_memory`, `cloud_sql`, `agent_engine`) |102| `--auto-approve` | `-y` | off | Skip confirmation prompts |103| `--skip-checks` | `-s` | off | Skip GCP/Vertex AI verification checks |104| `--agent-directory` | `-dir` | `app` | Agent code directory name |105| `--agent-guidance-filename` | | `GEMINI.md` | Guidance file name (`CLAUDE.md`, `AGENTS.md`) |106| `--debug` | | off | Enable debug logging for troubleshooting |107 108By default, the scaffolded project uses Google Cloud credentials (Vertex AI). For API key setup and model configuration, see [Configuring Gemini models](https://adk.dev/agents/models/google-gemini/index.md) and [Supported models](https://adk.dev/agents/models/index.md).109 110### Enhance an Existing Project111 112```bash113uvx agent-starter-pack enhance . \114  --deployment-target <target> \115  -y116```117 118Run 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.119 120#### Enhance Flags121 122All create flags are supported, plus:123 124| Flag | Short | Default | Description |125|------|-------|---------|-------------|126| `--name` | `-n` | directory name | Project name for templating |127| `--base-template` | `-bt` | — | Override base template (e.g. `agentic_rag` to add RAG) |128| `--dry-run` | | off | Preview changes without applying |129| `--force` | | off | Force overwrite all files (skip smart-merge) |130 131### Common Workflows132 133**Always ask the user before running these commands.** Present the options (CI/CD runner, deployment target, etc.) and confirm before executing.134 135```bash136# Add deployment to an existing prototype137uvx agent-starter-pack enhance . --deployment-target agent_engine -y138 139# Add CI/CD pipeline (ask: GitHub Actions or Cloud Build?)140uvx agent-starter-pack enhance . --cicd-runner github_actions -y141 142# Add RAG with data ingestion143uvx agent-starter-pack enhance . --base-template agentic_rag --datastore vertex_ai_search -y144 145# Preview what would change (dry run)146uvx agent-starter-pack enhance . --deployment-target cloud_run --dry-run -y147```148 149---150 151## Template Options152 153| Template | Deployment | Description |154|----------|------------|-------------|155| `adk` | Agent Engine, Cloud Run, GKE | Standard ADK agent (default) |156| `adk_a2a` | Agent Engine, Cloud Run, GKE | Agent-to-agent coordination (A2A protocol) |157| `agentic_rag` | Agent Engine, Cloud Run, GKE | RAG with data ingestion pipeline |158 159---160 161## Deployment Options162 163| Target | Description |164|--------|-------------|165| `agent_engine` | Managed by Google (Vertex AI Agent Engine). Sessions handled automatically. |166| `cloud_run` | Container-based deployment. More control, requires Dockerfile. |167| `gke` | Container-based on GKE Autopilot. Full Kubernetes control. |168| `none` | No deployment scaffolding. Code only. |169 170### "Prototype First" Pattern (Recommended)171 172Start with `--prototype` to skip CI/CD and Terraform. Focus on getting the agent working first, then add deployment later with `enhance`:173 174```bash175# Step 1: Create a prototype176uvx agent-starter-pack create my-agent --agent adk --prototype -y177 178# Step 2: Iterate on the agent code...179 180# Step 3: Add deployment when ready181uvx agent-starter-pack enhance . --deployment-target agent_engine -y182```183 184### Agent Engine and session_type185 186When 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.187 188---189 190## Step 4: Save DESIGN_SPEC.md and Load Dev Workflow191 192After scaffolding, save the approved spec from Step 2 to the project root as `DESIGN_SPEC.md`.193 194**Then immediately load `/adk-dev-guide`** — it contains the development workflow, coding guidelines, and operational rules you must follow when implementing the agent.195 196---197 198## Scaffold as Reference199 200When 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/`:201 202```bash203uvx agent-starter-pack create /tmp/ref-project \204  --agent adk \205  --deployment-target cloud_run \206  --cicd-runner github_actions \207  -y208```209 210Inspect the generated files, adapt what you need, and copy into the actual project. Delete the reference project when done.211 212This is useful for:213- Non-standard project structures that `enhance` can't handle214- Cherry-picking specific infrastructure files215- Understanding what ASP generates before committing to it216 217---218 219## Critical Rules220 221- **NEVER change the model** in existing code unless explicitly asked222- **NEVER `mkdir` before `create`** — the CLI creates the directory; pre-creating it causes enhance mode instead of create mode223- **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 all224- **Always ask before choosing CI/CD runner** — present GitHub Actions and Cloud Build as options, don't default silently225- **Agent Engine clears session_type** — if deploying to `agent_engine`, remove any `session_type` setting from your code226- **Start with `--prototype`** for quick iteration — add deployment later with `enhance`227- **Project names** must be ≤26 characters, lowercase, letters/numbers/hyphens only228- **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.229 230---231 232# Examples233 234Using scaffold as reference:235User says: "I need a Dockerfile for my non-standard project"236Actions:2371. Create temp project: `uvx agent-starter-pack create /tmp/ref --agent adk --deployment-target cloud_run -y`2382. Copy relevant files (Dockerfile, etc.) from /tmp/ref2393. Delete temp project240Result: Infrastructure files adapted to the actual project241 242---243 244A2A project:245User says: "Build me a Python agent that exposes A2A and deploys to Cloud Run"246Actions:2471. Follow the standard flow (gather requirements, DESIGN_SPEC, scaffold)2482. `uvx agent-starter-pack create my-a2a-agent --agent adk_a2a --deployment-target cloud_run --prototype -y`249Result: Valid A2A imports and Dockerfile — no manual A2A code written.250 251---252 253## Troubleshooting254 255### `uvx` command not found256 257Install `uv` following the [official installation guide](https://docs.astral.sh/uv/getting-started/installation/index.md).258 259If `uv` is not an option, use pip instead:260 261```bash262# macOS/Linux263python -m venv .venv && source .venv/bin/activate264# Windows265python -m venv .venv && .venv\Scripts\activate266 267pip install agent-starter-pack268agent-starter-pack create <project-name> ...269```270 271For all available options, run `uvx agent-starter-pack create --help`.