How to Build and Deploy an AI Agent in 15 Minutes with agents-cli

Have you ever been here: you want to build an AI Agent, but suddenly you're drowning in ADK framework docs, struggling with evaluation tests, and figuring out how to deploy to Cloud Run or GKE… You spend the entire afternoon just setting up the environment?

As a developer who spent 8 years on Java and has been diving into AI for the past two, I know this pain all too well. Agent development should focus on business logic, not getting bogged down in toolchain complexity.

Today, I'll walk you through using Google's official agents-cli to go from zero to a fully created, locally tested, quantitatively evaluated, and cloud-deployed AI Agent. You don't need to master every detail of ADK or Google Cloud beforehand—just follow the steps.

Prerequisites

Before we start, make sure your environment meets these requirements:

• Python 3.11+ (Recommended to manage versions with pyenv or conda)
• uv (A modern Python package manager, significantly faster than pip)
• Node.js (Required for skills loading)
• Google AI Studio API Key (For local development, apply for free here)

Why use uv? Traditional pip + venv dependency resolution can be painfully slow. uv, rewritten in Rust, is 10–100x faster and natively supports uvx for one-off tool execution—which is exactly how we'll run agents-cli.

Install uv if you haven't already:

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

Step 1: Install agents-cli and Initialize Your Project

The clever part about agents-cli is that it doesn't require a global installation—you can run it directly with uvx:

uvx google-agents-cli setup

This command does two things:

1. Installs agents-cli itself.
2. Injects the necessary Agent development skills into your preferred coding agent (like Claude Code or Codex).

What are skills? Think of them as "plugin packs" for your coding agent, teaching it ADK syntax, evaluation methodologies, and deployment workflows. Even if you don't use a coding agent, the CLI works perfectly standalone.

Once installed, scaffold your first Agent project:

uvx google-agents-cli scaffold text-summarizer
cd text-summarizer

You'll get a standard project structure containing the Agent definition, test cases, and configuration files.

Step 2: Get the Agent Running

Before writing business logic, verify the project runs correctly. agents-cli provides a quick test command:

## Configure your API Key first
export GOOGLE_API_KEY="your_ai_studio_api_key"

## Run a quick test
uvx google-agents-cli run "Please summarize the core takeaways of the following technical doc"

This command reads your Agent config, calls the Gemini model, and returns the result.

Why test with run first instead of coding immediately? Many tutorials dive straight into complex logic, but if the Agent can't even make a basic call, everything else is wasted effort. The run command lets you use a single prompt to quickly verify if the Agent's behavior is reachable, drastically improving iteration speed.

Step 3: Write Your Agent Logic

Open the Agent definition file in your project (usually agent.py or a similar entry point). You'll see the ADK framework structure. Let's turn it into a practical tool—like a Technical Document Summarizer Agent.

The core idea: define a system prompt, clarify the role and output format, and configure the model. Here's a minimal working example:

from google.adk.agents import Agent

agent = Agent(
    name="tech-doc-summarizer",
    model="gemini-2.5-pro",
    instruction="""You are an expert in summarizing technical documents.
Read the input technical doc and output the following structure:
1. Core Concept (one-sentence summary)
2. Key Features (3-5 bullet points)
3. Use Cases (When to use / When not to use)
Keep the output concise and professional. Avoid filler text.""",
    description="An AI Agent specifically designed to summarize technical documentation.",
)

Model Choice: gemini-2.5-pro is currently the recommended choice for balancing quality and speed. If you're doing heavy local testing, switch to gemini-1.5-flash to save costs. Just change the model parameter—no other code changes needed.

Test a few inputs using run afterward to ensure the output meets expectations before moving on.

Step 4: Quantitatively Evaluate Your Agent

The biggest pitfall in Agent development is "I feel like it's good enough"—we need objective data. agents-cli has a built-in evaluation pipeline:

## Auto-generate evaluation dataset
uvx google-agents-cli eval dataset synthesize

## Run the Agent on all eval cases, generate traces
uvx google-agents-cli eval generate

## Score the outputs
uvx google-agents-cli eval grade

Why can't we skip evaluation? In production, Agent performance must be quantifiable. The eval workflow automatically: generates multi-turn test scenarios, uses LLM-as-judge to score outputs, clusters failure patterns (eval analyze), and can even auto-optimize prompts (eval optimize).

After eval grade, you'll get a report highlighting where the Agent excels and where it needs improvement. Adjust the system prompt or add tools based on the report, then re-run until it hits your benchmarks.

Step 5: Deploy to Google Cloud

Once local testing and evaluation pass, it's time to deploy. agents-cli abstracts away Cloud Run / GKE details:

## Authenticate first
uvx google-agents-cli login

## One-click deployment
uvx google-agents-cli deploy

What happens behind the scenes? This command automatically: packages the Agent code, builds the container image, pushes it to Artifact Registry, deploys it to Agent Runtime or Cloud Run, and configures endpoints and authentication. No need to write a Dockerfile or infra YAML manually.

Upon success, the CLI returns a callable API endpoint. You can invoke it via HTTP in your application, or register it to the Gemini Enterprise platform using agents-cli publish gemini-enterprise.

Common Issues & Pitfalls

Q: Do I have to use Claude Code / Codex with it?
A: No. agents-cli runs completely standalone. All commands execute directly in your terminal. Skills just make coding agents understand the tool better—they're optional.

Q: Do I need a Google Cloud account for local development?
A: No. An AI Studio API Key is enough for the entire scaffold, run, and eval workflow. Only deploy and publish require a Cloud account.

Q: The auto-generated eval dataset quality isn't great. What should I do?
A: eval dataset synthesize is great for quick start-up. If you have real business data, manually prepare eval cases in JSON array format with input and expected_output. The more real data, the more reliable the evaluation.

Q: I already have an existing ADK project. Can I manage it with agents-cli?
A: Yes. Navigate to your project directory and run agents-cli scaffold enhance. It will automatically add deployment and CI/CD configurations without overwriting your existing code.

Q: I get a 401 error after deployment. How to fix it?
A: Check your authentication config. Agents deployed to Cloud Run require IAM authentication by default. Either switch to "Allow unauthenticated invocations" in the Cloud Console (for testing only), or bind the correct Invoker role to your service account.

Summary

Let's recap the full workflow:

1. uvx google-agents-cli scaffold <name> — Create project skeleton
2. export GOOGLE_API_KEY=... — Configure API key
3. uvx google-agents-cli run "prompt" — Quick local testing
4. eval generate && eval grade — Quantitative evaluation
5. login && deploy — One-click cloud deployment

The entire process eliminates the need to write Dockerfiles, study every ADK API, or manually configure Cloud resources. agents-cli standardizes the full lifecycle of Agent development so you can focus purely on business logic.

Next Steps:

• Try eval optimize to let the CLI auto-tune your prompt.
• Use scaffold enhance to add CI/CD pipelines to existing projects.
• Explore the data-ingestion command to build RAG pipelines.

The barrier to Agent development is dropping rapidly. Mature toolchains have shortened the "idea to production" cycle from weeks to hours. With agents-cli, your next Agent might only take as long as a coffee break.

Give it a try! Feel free to share your questions or experiences in the comments.