ADK Project Scaffolding Guide Requires: agents-cli ( uv tool install google-agents-cli ) — install uv first if needed. Use the agents-cli CLI to create new ADK agent projects or enhance existing ones with deployment, CI/CD, and infrastructure scaffolding. Prerequisite: Clarify Requirements (MANDATORY for new projects) Before scaffolding a new project, load /google-agents-cli-workflow and complete Phase 0 — clarify the user's requirements before running any scaffold create command. Ask what the agent should do, what tools/APIs it needs, and whether they want a prototype or full deployment. Step 1: Choose Architecture Mapping user choices to CLI flags: Choice CLI flag RAG with vector search --agent agentic_rag --datastore agent_platform_vector_search RAG with document search --agent agentic_rag --datastore agent_platform_search A2A protocol --agent adk_a2a Prototype (no deployment) --prototype Deployment target --deployment-target CI/CD runner --cicd-runner Session storage --session-type Product name mapping The platform formerly known as "Vertex AI" is now Gemini Enterprise Agent Platform (short: Agent Platform ). Users may refer to products by different names. Map them to the correct CLI values: User may say CLI value Agent Engine, Vertex AI Agent Engine, Agent Runtime --deployment-target agent_runtime Vertex AI Search, Agent Search --datastore agent_platform_search Vertex AI Vector Search, Vector Search --datastore agent_platform_vector_search Agent Engine sessions, Agent Platform Sessions --session-type agent_platform_sessions The vertexai Python SDK package name is unchanged. Step 2: Create or Enhance the Project Create a New Project agents-cli scaffold create < project-name

\ --agent < template

\ --deployment-target < target

\ --region < region

\ --prototype 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 ( GEMINI.md for Gemini CLI, CLAUDE.md for Claude Code, AGENTS.md for OpenAI Codex/other). When enhancing an existing project, check where the agent code lives. If it's not in app/ , pass --agent-directory

(e.g. --agent-directory agent ). Getting this wrong causes enhance to miss or misplace files. Reference Files File Contents references/flags.md Full flag reference for create and enhance commands Enhance an Existing Project agents-cli scaffold enhance . --deployment-target < target

agents-cli scaffold enhance . --cicd-runner < runner

Run this from inside the project directory (or pass the path instead of . ). Upgrade a Project Upgrade an existing project to a newer agents-cli version, intelligently applying updates while preserving your customizations: agents-cli scaffold upgrade

Upgrade current directory

agents-cli scaffold upgrade < project-path

Upgrade specific project

agents-cli scaffold upgrade --dry-run

Preview changes without applying

agents-cli scaffold upgrade --auto-approve

Auto-apply non-conflicting changes

Execution Modes The CLI defaults to strict programmatic mode — all required params must be supplied as CLI flags or a UsageError is raised. No approval flags needed. Pass all required params explicitly. 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 (strict programmatic)

agents-cli scaffold enhance . --deployment-target agent_runtime

Add CI/CD pipeline (ask: GitHub Actions or Cloud Build?)

agents-cli scaffold enhance . --cicd-runner github_actions Template Options Template Deployment Description adk Agent Runtime, Cloud Run, GKE Standard ADK agent (default) adk_a2a Agent Runtime, Cloud Run, GKE Agent-to-agent coordination (A2A protocol) agentic_rag Agent Runtime, Cloud Run, GKE RAG with data ingestion pipeline Deployment Options Target Description agent_runtime Managed by Google (Vertex AI Agent Runtime). 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 scaffold enhance :

Step 1: Create a prototype

agents-cli scaffold create my-agent --agent adk --prototype

Step 2: Iterate on the agent code...

Step 3: Add deployment when ready

agents-cli scaffold enhance . --deployment-target agent_runtime Agent Runtime and session_type When using agent_runtime as the deployment target, Agent Runtime manages sessions internally. If your code sets a session_type`, clear it — Agent Runtime overrides it. Step 3: Load Dev Workflow After scaffolding, save DESIGN_SPEC.md to the project root if it isn't there already. Then immediately load /google-agents-cli-workflow — it contains the development workflow, coding guidelines, and operational rules you must follow when implementing the agent. Key files to customize: app/agent.py (instruction, tools, model), app/tools.py (custom tool functions), .env (project ID, location, API keys). Files to preserve: pyproject.toml [tool.agents-cli] section (CLI reads this), deployment configs under deployment/ , Makefile , app/init.py (the App(name=...) must match the directory name — default app ). RAG projects ( agentic_rag ) — provision datastore first: Before running agents-cli playground or testing your RAG agent, you must provision the datastore and ingest data: agents-cli infra datastore

Provision datastore infrastructure

agents-cli data-ingestion

Ingest data into the datastore

Use infra datastore — not infra single-project . Both provision the datastore, but infra datastore is faster because it skips unrelated Terraform. Without this step, the agent won't have data to search over. Vector Search region: vector_search_location defaults to us-central1 , separate from region ( us-east1 ). It sets both the Vector Search collection region and the BQ ingestion dataset region, kept colocated to avoid cross-region data movement. Override per-invocation with agents-cli data-ingestion --vector-search-location . Verifying your agent works: Use agents-cli run "test prompt" for quick smoke tests, then agents-cli eval run for systematic validation. Do NOT write pytest tests that assert on LLM response content — that belongs in eval. 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/ : agents-cli scaffold create /tmp/ref-project \ --agent adk \ --deployment-target cloud_run 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 the CLI generates before committing to it Critical Rules NEVER skip requirements clarification — load /google-agents-cli-workflow Phase 0 and clarify the user's intent before running scaffold create 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 Runtime clears session_type — if deploying to agent_runtime , 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: agents-cli scaffold create /tmp/ref --agent adk --deployment-target cloud_run 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 (understand requirements, choose architecture, scaffold) agents-cli scaffold create my-a2a-agent --agent adk_a2a --deployment-target cloud_run --prototype Result: Valid A2A imports and Dockerfile — no manual A2A code written. Troubleshooting agents-cli command not found See /google-agents-cli-workflow → Setup section.