Skill by ara.so — Devtools Skills collection.
agents-cli is the CLI and skills framework for building, evaluating, and deploying AI agents on Google Cloud's Gemini Enterprise Agent Platform. It works with ADK (Agent Development Kit) to provide end-to-end agent development workflows, from scaffolding to production deployment.
What It Does
- Scaffold agent projects: Create new ADK agent projects with best practices built-in
- Local development: Run and test agents locally with hot reload
- Evaluation: Run systematic evaluations with metrics, evalsets, and LLM-as-judge
- Deployment: Deploy to Google Cloud (Agent Runtime, Cloud Run, GKE)
- Publishing: Register agents with Gemini Enterprise
- Observability: Integrate Cloud Trace, logging, and third-party monitoring
- CI/CD: Set up staging/prod pipelines with automated testing
Installation
Prerequisites: Python 3.11+, uv, Node.js
# Install CLI and skills
uvx google-agents-cli setup
# Or just install the CLI
pip install google-agents-cli
# Verify installation
agents-cli --version
Authentication
# Authenticate with Google Cloud
agents-cli login
# Check authentication status
agents-cli login --status
# For local development without Google Cloud, use AI Studio API key
export GOOGLE_API_KEY=your_api_key_here
Core Commands
Project Scaffolding
# Create a new agent project
agents-cli scaffold my-agent
# Create with specific template
agents-cli scaffold my-agent --template basic
agents-cli scaffold my-agent --template rag
# Add features to existing project
agents-cli scaffold enhance --add deployment
agents-cli scaffold enhance --add cicd
agents-cli scaffold enhance --add rag
# Upgrade project to newer agents-cli version
agents-cli scaffold upgrade
Local Development
# Install project dependencies
agents-cli install
# Run agent with a single prompt
agents-cli run "What's the weather in San Francisco?"
# Run with file input
agents-cli run --input-file prompt.txt
# Run with streaming output
agents-cli run "Summarize this article" --stream
# Lint code
agents-cli lint
Evaluation
# Run evaluations
agents-cli eval run
# Run specific evalset
agents-cli eval run --evalset evalsets/basic.yaml
# Compare two evaluation results
agents-cli eval compare results/eval1.json results/eval2.json
# Run with custom metrics
agents-cli eval run --metrics accuracy,latency,cost
Deployment
# Deploy to Google Cloud (interactive)
agents-cli deploy
# Deploy with specific config
agents-cli deploy --config deploy.yaml
# Deploy to specific environment
agents-cli deploy --env production
# Provision infrastructure
agents-cli infra single-project --project-id my-project
agents-cli infra cicd --project-id my-project
# Set up datastore for RAG
agents-cli infra datastore --project-id my-project
Publishing
# Register with Gemini Enterprise
agents-cli publish gemini-enterprise
# Publish with metadata
agents-cli publish gemini-enterprise --name "My Agent" --description "Does X"
Data Ingestion (RAG)
# Run data ingestion pipeline
agents-cli data-ingestion --source gs://my-bucket/docs
agents-cli data-ingestion --source ./local-docs --datastore my-datastore
Utilities
# Show project info and CLI version
agents-cli info
# Force reinstall skills to all IDEs
agents-cli update
ADK Agent Code Patterns
Basic Agent Structure
# my_agent.py
from adk.agents import Agent
from adk.tools import Tool
from adk.models import ModelClient
# Define a custom tool
class WeatherTool(Tool):
"""Get weather information for a location."""
def __init__(self):
super().__init__(
name="get_weather",
description="Get current weather for a location"
)
def execute(self, location: str) -> str:
# Implementation
return f"Weather in {location}: Sunny, 72°F"
# Create agent
agent = Agent(
name="weather-assistant",
description="An agent that provides weather information",
model=ModelClient(model_name="gemini-2.0-flash-exp"),
tools=[WeatherTool()]
)
# Run agent
if __name__ == "__main__":
response = agent.run("What's the weather in NYC?")
print(response)
Agent with State Management
from adk.agents import Agent, AgentState
from adk.models import ModelClient
from typing import Any, Dict
class ConversationState(AgentState):
"""Custom state for conversation tracking."""
def __init__(self):
super().__init__()
self.conversation_history = []
self.user_preferences = {}
def add_message(self, role: str, content: str):
self.conversation_history.append({"role": role, "content": content})
agent = Agent(
name="stateful-assistant",
model=ModelClient(model_name="gemini-2.0-flash-exp"),
state=ConversationState()
)
# Use state in agent execution
response = agent.run("Remember my name is Alice")
agent.state.user_preferences["name"] = "Alice"
Multi-Agent Orchestration
from adk.agents import Agent, AgentOrchestrator
from adk.models import ModelClient
# Create specialized agents
research_agent = Agent(
name="researcher",
description="Researches topics and gathers information",
model=ModelClient(model_name="gemini-2.0-flash-exp")
)
writer_agent = Agent(
name="writer",
description="Writes content based on research",
model=ModelClient(model_name="gemini-2.0-flash-exp")
)
# Orchestrate agents
orchestrator = AgentOrchestrator(
agents=[research_agent, writer_agent],
workflow="sequential" # or "parallel", "conditional"
)
# Run orchestrated workflow
result = orchestrator.run("Write an article about AI agents")
Agent with Callbacks
from adk.agents import Agent
from adk.callbacks import Callback
from adk.models import ModelClient
class LoggingCallback(Callback):
"""Log agent execution steps."""
def on_agent_start(self, agent_name: str, input_data: Any):
print(f"Agent {agent_name} starting with input: {input_data}")
def on_tool_start(self, tool_name: str, tool_input: Dict[str, Any]):
print(f"Tool {tool_name} called with: {tool_input}")
def on_tool_end(self, tool_name: str, tool_output: Any):
print(f"Tool {tool_name} returned: {tool_output}")
def on_agent_end(self, agent_name: str, output: Any):
print(f"Agent {agent_name} finished with: {output}")
agent = Agent(
name="monitored-agent",
model=ModelClient(model_name="gemini-2.0-flash-exp"),
callbacks=[LoggingCallback()]
)
RAG Agent Pattern
from adk.agents import Agent
from adk.tools import Tool
from adk.models import ModelClient
from adk.rag import VectorStore, Retriever
class RAGTool(Tool):
"""Retrieve relevant documents from vector store."""
def __init__(self, datastore_id: str):
super().__init__(
name="retrieve_docs",
description="Retrieve relevant documents"
)
self.retriever = Retriever(datastore_id=datastore_id)
def execute(self, query: str) -> str:
docs = self.retriever.retrieve(query, top_k=5)
return "\n\n".join([doc.content for doc in docs])
agent = Agent(
name="rag-assistant",
description="Agent with RAG capabilities",
model=ModelClient(model_name="gemini-2.0-flash-exp"),
tools=[RAGTool(datastore_id="my-datastore")]
)
Project Configuration
agents.yaml
# Project configuration
name: my-agent
version: 1.0.0
description: My AI agent
# Agent configuration
agent:
name: my-assistant
model: gemini-2.0-flash-exp
temperature: 0.7
max_tokens: 2048
# Tools configuration
tools:
- name: web_search
enabled: true
- name: code_execution
enabled: false
# Evaluation configuration
evaluation:
evalsets:
- path: evalsets/basic.yaml
- path: evalsets/advanced.yaml
metrics:
- accuracy
- latency
- cost
# Deployment configuration
deployment:
target: cloud-run
region: us-central1
min_instances: 1
max_instances: 10
# Observability
observability:
cloud_trace: true
cloud_logging: true
Evalset Configuration
# evalsets/basic.yaml
name: basic-evalset
description: Basic functionality tests
test_cases:
- id: tc-001
input: "What is 2+2?"
expected_output: "4"
metrics:
- accuracy
- latency
- id: tc-002
input: "Explain quantum computing in simple terms"
judge:
type: llm-as-judge
criteria:
- clarity
- accuracy
- conciseness
- id: tc-003
input: "Write a Python function to reverse a string"
validator:
type: code-execution
test: |
def test_reverse():
assert reverse("hello") == "olleh"
assert reverse("") == ""
Deployment Configuration
# deploy.yaml
target: cloud-run
project_id: ${GCP_PROJECT_ID}
region: us-central1
service:
name: my-agent-service
min_instances: 1
max_instances: 10
cpu: 2
memory: 4Gi
timeout: 300s
environment:
- name: GOOGLE_API_KEY
secret: projects/${GCP_PROJECT_ID}/secrets/gemini-api-key
- name: LOG_LEVEL
value: INFO
ci_cd:
enabled: true
environments:
- name: staging
project_id: ${STAGING_PROJECT_ID}
branch: develop
- name: production
project_id: ${PRODUCTION_PROJECT_ID}
branch: main
Environment Variables
# API Keys
export GOOGLE_API_KEY=your_api_key_here
export GOOGLE_CLOUD_PROJECT=your-project-id
# Agent Configuration
export AGENT_MODEL=gemini-2.0-flash-exp
export AGENT_TEMPERATURE=0.7
export AGENT_MAX_TOKENS=2048
# Deployment
export DEPLOY_REGION=us-central1
export DEPLOY_ENV=production
# Observability
export ENABLE_CLOUD_TRACE=true
export ENABLE_CLOUD_LOGGING=true
export LOG_LEVEL=INFO
# RAG
export DATASTORE_ID=my-datastore
export VECTOR_STORE_TYPE=vertex-ai-search
Common Patterns
Creating a Complete Agent Project
# 1. Scaffold project
agents-cli scaffold my-agent
# 2. Navigate to project
cd my-agent
# 3. Install dependencies
agents-cli install
# 4. Edit agent code
# Edit src/agent.py with your agent logic
# 5. Run locally
agents-cli run "Test prompt"
# 6. Create evalset
# Create evalsets/test.yaml
# 7. Run evaluations
agents-cli eval run
# 8. Deploy to Google Cloud
agents-cli login
agents-cli deploy
# 9. Publish to Gemini Enterprise
agents-cli publish gemini-enterprise
Adding Tools to an Agent
from adk.agents import Agent
from adk.tools import Tool
from adk.models import ModelClient
import requests
class SearchTool(Tool):
"""Search the web for information."""
def __init__(self, api_key: str):
super().__init__(
name="web_search",
description="Search the web for current information"
)
self.api_key = api_key
def execute(self, query: str, num_results: int = 5) -> str:
# Implementation using search API
# Use self.api_key from environment
results = self._search(query, num_results)
return "\n".join([r["title"] + ": " + r["snippet"] for r in results])
def _search(self, query: str, num_results: int):
# Actual search implementation
pass
class CalculatorTool(Tool):
"""Perform mathematical calculations."""
def __init__(self):
super().__init__(
name="calculator",
description="Perform mathematical calculations"
)
def execute(self, expression: str) -> float:
# Safe evaluation of mathematical expressions
import ast
import operator
operators = {
ast.Add: operator.add,
ast.Sub: operator.sub,
ast.Mult: operator.mul,
ast.Div: operator.truediv,
}
def eval_expr(node):
if isinstance(node, ast.Num):
return node.n
elif isinstance(node, ast.BinOp):
return operators[type(node.op)](
eval_expr(node.left),
eval_expr(node.right)
)
else:
raise ValueError("Unsupported expression")
return eval_expr(ast.parse(expression, mode='eval').body)
# Create agent with multiple tools
import os
agent = Agent(
name="research-assistant",
model=ModelClient(model_name="gemini-2.0-flash-exp"),
tools=[
SearchTool(api_key=os.getenv("SEARCH_API_KEY")),
CalculatorTool()
]
)
Setting Up CI/CD
# 1. Set up CI/CD infrastructure
agents-cli infra cicd --project-id my-project
# 2. Create deployment configs for staging and prod
# Edit deploy-staging.yaml and deploy-production.yaml
# 3. Configure GitHub Actions or Cloud Build
# The scaffold enhance command creates templates
# 4. Push to repository
git add .
git commit -m "Set up CI/CD"
git push origin main
Implementing Custom Metrics
# evalsets/custom_metrics.py
from adk.evaluation import Metric
from typing import Dict, Any
class CustomAccuracyMetric(Metric):
"""Custom accuracy metric with fuzzy matching."""
def __init__(self, threshold: float = 0.8):
super().__init__(name="custom_accuracy")
self.threshold = threshold
def evaluate(self,
prediction: str,
expected: str,
context: Dict[str, Any]) -> float:
# Custom evaluation logic
from difflib import SequenceMatcher
ratio = SequenceMatcher(None, prediction, expected).ratio()
return 1.0 if ratio >= self.threshold else 0.0
class LatencyMetric(Metric):
"""Measure agent response latency."""
def __init__(self):
super().__init__(name="latency")
def evaluate(self,
prediction: str,
expected: str,
context: Dict[str, Any]) -> float:
# Return latency in milliseconds
return context.get("execution_time_ms", 0)
# Use in evaluation
from adk.evaluation import Evaluator
evaluator = Evaluator(
agent=my_agent,
evalset_path="evalsets/basic.yaml",
metrics=[
CustomAccuracyMetric(threshold=0.85),
LatencyMetric()
]
)
results = evaluator.run()
print(f"Average accuracy: {results.metrics['custom_accuracy']}")
print(f"Average latency: {results.metrics['latency']}ms")
Troubleshooting
Authentication Issues
# Clear credentials and re-authenticate
agents-cli login --force
# Use service account for CI/CD
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
agents-cli login --service-account
# Check authentication status
agents-cli login --status
Deployment Failures
# Check project configuration
agents-cli info
# Validate deployment config
agents-cli deploy --validate-only
# Deploy with verbose logging
agents-cli deploy --verbose
# Check Cloud Run logs
gcloud run services logs read my-agent-service --project=${GCP_PROJECT_ID}
Evaluation Issues
# Run single test case
agents-cli eval run --test-case tc-001
# Run with debug mode
agents-cli eval run --debug
# Validate evalset format
agents-cli eval run --validate-only
# Check evaluation logs
cat .agents-cli/eval-results/latest.log
Dependency Conflicts
# Reinstall dependencies
agents-cli install --force
# Clear cache
rm -rf .agents-cli/cache
agents-cli install
# Use specific Python version
uv venv --python 3.11
source .venv/bin/activate
agents-cli install
Model Access Issues
# Verify API key is set
echo $GOOGLE_API_KEY
# Test model access directly
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash-exp:generateContent?key=${GOOGLE_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{"contents":[{"parts":[{"text":"Hello"}]}]}'
# Switch to different model
export AGENT_MODEL=gemini-1.5-pro
agents-cli run "test"
Performance Optimization
# Enable caching for repeated queries
from adk.models import ModelClient
model = ModelClient(
model_name="gemini-2.0-flash-exp",
cache_enabled=True,
cache_ttl=3600 # 1 hour
)
# Batch processing for evaluations
agents-cli eval run --batch-size 10 --parallel 4
# Reduce token usage
agent = Agent(
name="efficient-agent",
model=ModelClient(
model_name="gemini-2.0-flash-exp",
max_tokens=1024, # Lower limit
temperature=0.3 # More deterministic
)
)
Debugging Agent Behavior
from adk.agents import Agent
from adk.callbacks import DebugCallback
from adk.models import ModelClient
# Enable detailed debugging
debug_callback = DebugCallback(
log_prompts=True,
log_responses=True,
log_tool_calls=True
)
agent = Agent(
name="debug-agent",
model=ModelClient(model_name="gemini-2.0-flash-exp"),
callbacks=[debug_callback],
verbose=True
)
# Check agent execution traces
response = agent.run("Debug this behavior")
print(agent.get_trace())
Model Selection Guide
# Fast, cost-effective for simple tasks
ModelClient(model_name="gemini-2.0-flash-exp")
# Balanced performance and capabilities
ModelClient(model_name="gemini-1.5-pro")
# Maximum capabilities for complex reasoning
ModelClient(model_name="gemini-1.5-pro-002")
# Multimodal tasks (images, video)
ModelClient(
model_name="gemini-1.5-pro-vision",
multimodal=True
)