How to Build and Deploy AI Agents Without Getting Lost in Boilerplate?

The "Blank Canvas" Problem in Agent Development

You have a brilliant idea for an AI agent. Maybe it's a customer support bot that queries your internal knowledge base, or a coding assistant that interacts with your local file system. You sit down to build it, and within an hour, you are drowning in configuration files.

You need a project structure that makes sense. You need to decide how to handle state management. You need to set up evaluation frameworks to test if your agent actually works before you ship it. You need to figure out how to deploy it to the cloud without breaking the bank or exposing security holes.

Most developers start by copying and pasting code snippets from documentation or old projects. This leads to a "Frankenstein" codebase where the scaffolding logic is mixed with the business logic. When it comes time to deploy, you realize you forgot to set up the CI/CD pipeline correctly, or your local testing environment doesn't match the cloud environment.

The result? You spend 80% of your time fighting infrastructure and boilerplate, and only 20% actually building the agent's intelligence.

Why Does This Happen?

Agent development is inherently complex because it sits at the intersection of software engineering and probabilistic AI. Unlike a standard web app, an agent involves:

• Dynamic State: Agents need to remember context across turns.
• Tool Integration: Agents call external APIs and functions.
• Evaluation: You need to measure "correctness" which is often subjective.
• Safety: You must guard against prompt injection and hallucinations.

Without a standardized workflow, every developer reinvents the wheel. You might build a great agent, but if you can't reliably test or deploy it, it remains a local experiment.

Introducing a Structured Lifecycle: The Google Agents CLI Workflow

If you are building agents using Google's Agent Development Kit (ADK), there is a specific skill designed to eliminate this friction. It is called the Google Agents CLI Workflow.

This isn't just a library; it's a set of guidelines and a command-line interface (CLI) that enforces a structured development lifecycle. It forces you to stop writing code immediately and instead follow a proven path: Scaffold → Build → Evaluate → Deploy → Observe.

How It Solves the Boilerplate Problem

The core philosophy of this skill is "Scaffold First." Instead of letting you write random Python files, it uses the agents-cli tool to generate a project structure that already includes:

• Evaluation Boilerplate: Pre-configured datasets and metrics for testing your agent.
• CI/CD Configuration: Ready-to-go pipelines for GitHub Actions or Google Cloud Build.
• Project Conventions: Standardized ways to handle tools, callbacks, and state.

By using this workflow, you ensure that your agent is "production-ready" from the first line of code.

Deep Dive: The 7 Phases of the Workflow

The skill defines a clear roadmap. Here is how it breaks down the development process:

Phase 0: Understand (The Most Important Step)

Before you touch the terminal, the skill forces you to answer critical questions. It looks for a file named .agents-cli-spec.md. If it doesn't exist, you must create one.

You have to define:

1. The Problem: What exactly will the agent solve?
2. External APIs: What tools does it need?
3. Safety Constraints: What must the agent never do?
4. Deployment Preference: Is this a prototype or a full production deployment?

This step prevents scope creep. It ensures you know exactly what you are building before you start.

Phase 1: Study Reference Samples

Don't reinvent the wheel. The skill encourages you to look at existing samples provided by Google. For example, if you are building an agent that reacts to events (like a cron job), you should study the ambient-expense-agent sample.

Phase 2: Scaffold

This is where the CLI shines. You run a command to create the project structure.

agents-cli scaffold create my-new-agent

This command sets up the directory structure, the pyproject.toml, and the necessary configuration files. It ensures you don't miss the evaluation setup.

Phase 3: Build

Now you write the code. The skill provides guidelines on API patterns, tools, and callbacks. It emphasizes using the ADK (Agent Development Kit) correctly.

Phase 4: Evaluate

This is often the skipped step in DIY projects. The workflow mandates evaluation. You run your agent against a dataset to measure performance. The CLI provides commands to run these evaluations and fix issues iteratively.

Phase 5: Deploy

Deployment is where most agents fail. The skill provides specific troubleshooting steps for common errors like 403 Forbidden or timeouts. It maps user-friendly terms (like "Vertex AI") to the correct CLI flags (like --deployment-target agent_runtime).

Phase 6: Publish

If you want your agent to be available to other agents or users via the Gemini Enterprise Agent Platform, this phase handles the registration.

Phase 7: Observe

Once deployed, you need to see what's happening. The workflow includes setup for traces, logging, and monitoring.

Practical Example: Building a Simple Q&A Agent

Let's say you want to build an agent that answers questions about your company's HR policy PDF.

1. Spec: You write .agents-cli-spec.md stating the goal is "HR Policy Q&A" and the tool is "PDF Reader".
2. Scaffold: You run agents-cli scaffold create hr-agent.
3. Build: You write the code to load the PDF and use a vector search tool.
4. Evaluate: You create a test set of 10 questions and answers. You run the eval loop to ensure the agent answers correctly 90% of the time.
5. Deploy: You deploy to Cloud Run.

Without the workflow, you might have skipped the eval step and deployed an agent that hallucinates answers. With the workflow, you are forced to prove it works first.

Is This Skill Right for You?

This skill is highly opinionated. It is designed for developers who:

• Are building agents using the Google Agent Development Kit (ADK).
• Want to deploy to Google Cloud (Agent Runtime, Cloud Run, GKE).
• Value structured development over ad-hoc scripting.
• Need to ensure their agents are safe and evaluated before deployment.

When NOT to Use It

• If you are building a simple script that doesn't need deployment or evaluation.
• If you are using a different cloud provider (AWS, Azure) exclusively, though the scaffolding logic might still be useful locally.
• If you prefer a completely unstructured, notebook-style development approach.

Evaluating the Repository

The skill is backed by the google/agents-cli repository on GitHub.

• Stars: 3,000+ (Indicates strong community interest and maintenance).
• Owner: Google (Official support).
• License: Apache-2.0 (Permissive, safe for commercial use).
• Security Level: Low (Standard CLI tool, but always review dependencies).

The repository is actively maintained and is the official way to interact with the ADK ecosystem.

Setup and Prerequisites

To use this skill, you need:

1. Python: Version 3.10 or higher.
2. uv: A fast Python package installer. You can install it via pip install uv or follow the official guide.
3. The CLI: Install the tool itself:

   uv tool install google-agents-cli
   

Once installed, run agents-cli info to verify the installation.

Conclusion

Building AI agents is exciting, but the gap between a local script and a production-ready agent is vast. The Google Agents CLI Workflow bridges that gap by providing a disciplined, structured lifecycle. It forces you to think about evaluation and deployment before you write code, saving you from the painful refactoring that usually happens later.

If you are serious about building robust agents on Google Cloud, inspecting this skill is a worthwhile first step.