google-agents-cli

# google-agents-cli > Skill by [ara.so](https://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](https://docs.astral.sh/uv/), Node.js ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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) ```bash # Run data ingestion pipeline agents-cli data-ingestion --source gs://my-bucket/docs agents-cli data-ingestion --source ./local-docs --datastore my-datastore ``` ### Utilities ```bash # 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 ```python # 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 ```python 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 ```python 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 ```python 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 ```python 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` ```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 ```yaml # 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 ```yaml # 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 ```bash # 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 ```bash # 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 ```python 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")