The Problem: Starting an AI Agent Project Feels Like Building a House from Scratch
You have a clear idea for an AI agent. Maybe it's a customer support bot that uses RAG to answer questions from your documentation, or an internal tool that coordinates multiple specialized agents. You know what it should do, but the moment you sit down to code, you hit a wall of decisions that have nothing to do with your agent's actual logic.
Which project structure should you use? How do you set up the deployment pipeline? What about CI/CD? Do you need a Dockerfile? How do you configure session storage? Each question leads to another, and before you know it, you've spent hours on infrastructure instead of building the agent itself.
This is a common pain point for developers working with the Google Agent Development Kit (ADK). The ADK provides powerful tools for building agents, but the initial project setup—creating the right directory structure, adding deployment configurations, setting up CI/CD pipelines—requires knowledge of Google Cloud infrastructure that many developers don't have immediately. The result is often a slow, error-prone start where developers either copy-paste from old projects (risking outdated patterns) or build everything manually (wasting time on boilerplate).
The core issue isn't a lack of skill; it's a lack of a standardized, opinionated starting point. You need a way to go from "I want to build an agent" to "I have a working project structure with deployment options" in minutes, not hours.
What a Good Solution Should Provide
A proper solution to this problem should do several things:
- Reduce decision fatigue: It should offer sensible defaults and clear choices for common configurations (like deployment targets and CI/CD runners) without requiring you to be an expert in each.
- Generate a complete, working project structure: Not just a skeleton, but a structure that includes the necessary configuration files for deployment, testing, and development workflows.
- Support iterative development: It should allow you to start with a simple prototype and add complexity (like deployment or CI/CD) later, without having to restructure your project.
- Stay out of your way: The generated code should be a starting point, not a cage. You need to be able to easily modify the agent logic, tools, and configurations.
- Integrate with your existing workflow: Whether you're using GitHub Actions or Google Cloud Build for CI/CD, the solution should adapt to your preferred tools.
Introducing Google Agents CLI Scaffold: A Practical Option for Project Setup
One tool designed to address this specific problem is the scaffold command within the Google Agents CLI. It's part of the broader Google ADK skills suite and focuses exclusively on the project initialization and enhancement phase. It's not for writing your agent's core logic or for performing deployment operations—those are separate concerns.
Think of it as a project generator that understands ADK conventions and Google Cloud deployment patterns. You describe what you want (e.g., "a RAG agent deployed on Cloud Run with GitHub Actions CI/CD"), and it generates a project directory with the correct structure, configuration files, and even a Makefile with common commands.
How It Works: The Prototype-First Workflow
The recommended approach is to start simple and add complexity later. This aligns with how most developers actually work: get the core idea functioning first, then worry about deployment and pipelines.
Step 1: Create a Prototype
You can create a project with just the agent code, skipping all deployment and CI/CD scaffolding initially. This lets you focus entirely on defining your agent's instructions, tools, and logic.
agents-cli scaffold create my-support-agent --agent adk --prototype
This command creates a directory my-support-agent with a basic ADK agent structure. The --prototype flag means no deployment configs (Terraform, Dockerfiles) or CI/CD pipelines are generated. You get a clean starting point to iterate on app/agent.py and app/tools.py.
Step 2: Enhance When Ready
Once your agent works locally, you can "enhance" the project to add the infrastructure you need. For example, to add deployment to Google's managed Agent Runtime:
cd my-support-agent
agents-cli scaffold enhance . --deployment-target agent_runtime
This command analyzes your existing project and adds the necessary deployment configurations without overwriting your agent code. You can also add CI/CD separately:
agents-cli scaffold enhance . --cicd-runner github_actions
This iterative pattern—prototype first, enhance later—prevents you from getting bogged down in infrastructure decisions before you even know if your agent idea works.
Key Capabilities and Choices
The scaffold command offers several templates and configuration options. Understanding these helps you evaluate if it fits your use case.
Agent Templates:
adk: The standard template for most agents.adk_a2a: For agents that need to coordinate with other agents using the A2A protocol.agentic_rag: A specialized template that includes a data ingestion pipeline for Retrieval-Augmented Generation. This is more complex and requires provisioning a datastore.
Deployment Targets:
agent_runtime: A fully managed service on Google Cloud. Simplest option, handles sessions automatically.cloud_run: Container-based deployment. More control, requires understanding Docker.gke: For Kubernetes-based deployment on Google Kubernetes Engine Autopilot. Maximum control and complexity.none: No deployment scaffolding. Code only.
CI/CD Runners:
github_actions: Generates GitHub Actions workflow files.google_cloud_build: Generates Cloud Build configuration files.
Session Storage:
For stateful agents, you can choose where session data is stored: in-memory (for prototyping), Cloud SQL, or the Agent Platform's managed sessions.
Evaluating If This Skill Fits Your Workflow
Before deciding to use this tool, consider these points:
When it's a good fit:
- You are starting a new ADK-based agent project from scratch.
n* You want to add deployment or CI/CD to an existing ADK project that was initially created as a prototype. - You prefer a standardized project structure that follows Google's recommended patterns.
- You plan to deploy to Google Cloud (Agent Runtime, Cloud Run, or GKE).
When it might not be the right tool:
- You are not using the Google Agent Development Kit (ADK). This tool is specific to the ADK ecosystem.
- You need to heavily customize the project structure from the very beginning. The scaffold generates a specific layout; if you need a radically different structure, manual setup might be better.
- You are looking to write or debug your agent's core logic. This tool is for project setup, not coding. For that, you would use the
google-agents-cli-adk-codeskill. - You are performing deployment operations (like
kubectl applyorgcloud run deploy). That's the domain of thegoogle-agents-cli-deployskill.
What to Inspect Before Using It
If you decide this tool could help, here are practical things to check and understand:
1. Prerequisites and Installation:
The CLI itself requires uv (a Python package installer) to install. You'll need to run uv tool install google-agents-cli. Ensure you have a working Python environment and uv installed first.
2. Project Naming Constraints:
The generated project name has strict rules: 26 characters or less, lowercase letters, numbers, and hyphens only. Plan your name accordingly.
3. The --agent-guidance-filename Flag:
The scaffold can generate a guidance file for your AI coding assistant (like Gemini CLI, Claude Code, etc.). It tries to auto-detect your environment, but you can specify it explicitly with --agent-guidance-filename. This is a small but useful detail for integrating with your existing AI-assisted development flow.
4. The "Enhance" Workflow for Existing Projects:
If you have an existing ADK project (not created by this scaffold), the enhance command needs to know where your agent code lives. By default, it looks in the app/ directory. If your code is elsewhere (e.g., agent/), you must specify --agent-directory agent. Getting this wrong will cause the enhance command to miss your code or place files incorrectly.
5. RAG Projects Require Extra Steps:
If you choose the agentic_rag template, the scaffold creates the code structure, but you must separately provision the underlying datastore and ingest data. The documentation provides specific commands (agents-cli infra datastore and agents-cli data-ingestion) for this. Skipping this step means your RAG agent will have no data to search.
6. Repository and Safety Signals:
The tool is developed by Google and hosted in their official agents-cli repository. It's licensed under Apache-2.0. The repository has over 3000 stars, indicating significant community interest. The security level is marked as "Low," which typically means it's a development tool that doesn't handle sensitive runtime secrets by default, but you should always review generated configuration files, especially those related to deployment and CI/CD, to ensure they align with your security policies.
7. Understanding the Generated Files:
After scaffolding, take a moment to review the key files. The agents-cli-manifest.yaml is important for the CLI to understand your project. The Makefile contains useful commands for local development. Your agent's core logic will be in app/agent.py and app/tools.py. Environment variables go in .env. Knowing this layout helps you navigate and customize effectively.
Conclusion: A Structured Start for Your Agent Journey
Building an AI agent involves two distinct phases: the creative work of defining what the agent does, and the engineering work of packaging it for deployment. The Google Agents CLI scaffold tool is designed to handle the second phase efficiently, giving you a solid, opinionated foundation so you can spend more time on the first.
It's not a magic solution that writes your agent for you, but it is a practical utility that removes the friction of project setup. By following the "prototype first" workflow, you can validate your agent idea quickly and then incrementally add the production-grade infrastructure you need. If you're working within the Google ADK ecosystem and want to avoid boilerplate headaches, it's a tool worth inspecting.
You can find more details, full command references, and examples on the Google Agents CLI Scaffold skill page.