512 lines
14 KiB
Markdown
512 lines
14 KiB
Markdown
---
|
|
name: Google Cloud Agent SDK Master
|
|
description: |
|
|
Automatic activation for ALL Google Cloud Agent Development Kit (ADK) and Agent Starter Pack operations - multi-agent systems, containerized deployment, RAG agents, and production orchestration.
|
|
**TRIGGER PHRASES:**
|
|
- "adk", "agent development kit", "agent starter pack", "multi-agent", "build agent"
|
|
- "cloud run agent", "gke deployment", "agent engine", "containerized agent"
|
|
- "rag agent", "react agent", "agent orchestration", "agent templates"
|
|
**AUTO-INVOKES FOR:**
|
|
- Agent creation and scaffolding
|
|
- Multi-agent system design
|
|
- Containerized agent deployment
|
|
- RAG (Retrieval-Augmented Generation) implementation
|
|
- CI/CD pipeline setup for agents
|
|
- Agent evaluation and monitoring
|
|
allowed-tools: Read, WebFetch, WebSearch, Grep
|
|
version: 1.0.0
|
|
---
|
|
|
|
# Google Cloud Agent SDK Master - Production-Ready Agent Systems
|
|
|
|
This Agent Skill provides comprehensive mastery of Google's Agent Development Kit (ADK) and Agent Starter Pack for building and deploying production-grade containerized agents.
|
|
|
|
## Core Capabilities
|
|
|
|
### 🤖 Agent Development Kit (ADK)
|
|
|
|
**Framework Overview:**
|
|
- **Open-source Python framework** from Google
|
|
- Same framework powering Google Agentspace and CES
|
|
- Build production agents in <100 lines of code
|
|
- Model-agnostic (optimized for Gemini)
|
|
- Deployment-agnostic (local, Cloud Run, GKE, Agent Engine)
|
|
|
|
**Supported Agent Types:**
|
|
1. **LLM Agents**: Dynamic routing with intelligence
|
|
2. **Workflow Agents**:
|
|
- Sequential: Linear execution
|
|
- Loop: Iterative processing
|
|
- Parallel: Concurrent execution
|
|
3. **Custom Agents**: User-defined implementations
|
|
4. **Multi-agent Systems**: Hierarchical coordination
|
|
|
|
**Key Features:**
|
|
- Flexible orchestration (workflow & LLM-driven)
|
|
- Tool ecosystem (search, code execution, custom functions)
|
|
- Third-party integrations (LangChain, CrewAI)
|
|
- Agents-as-tools capability
|
|
- Built-in evaluation framework
|
|
- Cloud Trace integration
|
|
|
|
### 📦 Agent Starter Pack
|
|
|
|
**Production Templates:**
|
|
1. **adk_base** - ReAct agent using ADK
|
|
2. **agentic_rag** - Document retrieval + Q&A with search
|
|
3. **langgraph_base_react** - LangGraph ReAct implementation
|
|
4. **crewai_coding_crew** - Multi-agent coding system
|
|
5. **adk_live** - Multimodal RAG (audio/video/text)
|
|
|
|
**Infrastructure Automation:**
|
|
- CI/CD setup with single command
|
|
- GitHub Actions or Cloud Build pipelines
|
|
- Multi-environment support (dev, staging, prod)
|
|
- Automated testing and evaluation
|
|
- Deployment rollback mechanisms
|
|
|
|
### 🚀 Deployment Targets
|
|
|
|
**1. Vertex AI Agent Engine**
|
|
- Fully managed runtime
|
|
- Auto-scaling and load balancing
|
|
- Built-in observability
|
|
- Serverless architecture
|
|
- Best for: Production-scale agents
|
|
|
|
**2. Cloud Run**
|
|
- Containerized serverless
|
|
- Pay-per-use pricing
|
|
- Custom domain support
|
|
- Traffic splitting
|
|
- Best for: Web-facing agents
|
|
|
|
**3. Google Kubernetes Engine (GKE)**
|
|
- Full container orchestration
|
|
- Advanced networking
|
|
- Resource management
|
|
- Multi-cluster support
|
|
- Best for: Complex multi-agent systems
|
|
|
|
**4. Local/Docker**
|
|
- Development and testing
|
|
- Custom infrastructure
|
|
- On-premises deployment
|
|
- Best for: POC and debugging
|
|
|
|
### 🔧 Technical Implementation
|
|
|
|
**Installation:**
|
|
```bash
|
|
# Agent Starter Pack (recommended)
|
|
pip install agent-starter-pack
|
|
|
|
# or direct from GitHub
|
|
uvx agent-starter-pack create my-agent
|
|
|
|
# ADK only
|
|
pip install google-cloud-aiplatform[adk,agent_engines]>=1.111
|
|
```
|
|
|
|
**Create Agent (ADK):**
|
|
```python
|
|
from google.cloud.aiplatform import agent
|
|
from vertexai.preview.agents import ADKAgent
|
|
|
|
# Simple ReAct agent
|
|
@agent.adk_agent
|
|
class MyAgent(ADKAgent):
|
|
def __init__(self):
|
|
super().__init__(
|
|
model="gemini-2.5-pro",
|
|
tools=[search_tool, code_exec_tool]
|
|
)
|
|
|
|
def run(self, query: str):
|
|
return self.generate(query)
|
|
|
|
# Multi-agent orchestration
|
|
class OrchestratorAgent(ADKAgent):
|
|
def __init__(self):
|
|
self.research_agent = ResearchAgent()
|
|
self.analysis_agent = AnalysisAgent()
|
|
self.writer_agent = WriterAgent()
|
|
|
|
def run(self, task: str):
|
|
research = self.research_agent.run(task)
|
|
analysis = self.analysis_agent.run(research)
|
|
output = self.writer_agent.run(analysis)
|
|
return output
|
|
```
|
|
|
|
**Using Agent Starter Pack:**
|
|
```bash
|
|
# Create project with template
|
|
uvx agent-starter-pack create my-rag-agent \
|
|
--template agentic_rag \
|
|
--deployment cloud_run
|
|
|
|
# Generates complete structure:
|
|
my-rag-agent/
|
|
├── src/
|
|
│ ├── agent.py # Agent implementation
|
|
│ ├── tools/ # Custom tools
|
|
│ └── config.py # Configuration
|
|
├── deployment/
|
|
│ ├── Dockerfile
|
|
│ ├── cloudbuild.yaml
|
|
│ └── terraform/
|
|
├── tests/
|
|
│ ├── unit_tests.py
|
|
│ └── integration_tests.py
|
|
└── .github/workflows/ # CI/CD pipelines
|
|
```
|
|
|
|
**Deploy to Cloud Run:**
|
|
```bash
|
|
# Using ADK CLI
|
|
adk deploy \
|
|
--target cloud_run \
|
|
--region us-central1 \
|
|
--service-account sa@project.iam.gserviceaccount.com
|
|
|
|
# Manual with Docker
|
|
docker build -t gcr.io/PROJECT/agent:latest .
|
|
docker push gcr.io/PROJECT/agent:latest
|
|
gcloud run deploy agent \
|
|
--image gcr.io/PROJECT/agent:latest \
|
|
--region us-central1 \
|
|
--allow-unauthenticated
|
|
```
|
|
|
|
**Deploy to Agent Engine:**
|
|
```bash
|
|
# Using Agent Starter Pack
|
|
asp deploy \
|
|
--env production \
|
|
--target agent_engine
|
|
|
|
# Manual deployment
|
|
from google.cloud.aiplatform import agent_engines
|
|
agent_engines.deploy_agent(
|
|
agent_id="my-agent",
|
|
project="PROJECT_ID",
|
|
location="us-central1"
|
|
)
|
|
```
|
|
|
|
### 📊 RAG Agent Implementation
|
|
|
|
**Vector Search Integration:**
|
|
```python
|
|
from vertexai.preview.rag import VectorSearchTool
|
|
from google.cloud import aiplatform
|
|
|
|
# Set up vector search
|
|
vector_search = VectorSearchTool(
|
|
index_endpoint="projects/PROJECT/locations/LOCATION/indexEndpoints/INDEX_ID",
|
|
deployed_index_id="deployed_index"
|
|
)
|
|
|
|
# RAG agent with ADK
|
|
class RAGAgent(ADKAgent):
|
|
def __init__(self):
|
|
super().__init__(
|
|
model="gemini-2.5-pro",
|
|
tools=[vector_search, web_search_tool]
|
|
)
|
|
|
|
def run(self, query: str):
|
|
# Retrieves relevant docs automatically
|
|
response = self.generate(
|
|
f"Answer this using retrieved context: {query}"
|
|
)
|
|
return response
|
|
```
|
|
|
|
**Vertex AI Search Integration:**
|
|
```python
|
|
from vertexai.preview.search import VertexAISearchTool
|
|
|
|
# Enterprise search integration
|
|
vertex_search = VertexAISearchTool(
|
|
data_store_id="DATA_STORE_ID",
|
|
project="PROJECT_ID"
|
|
)
|
|
|
|
agent = ADKAgent(
|
|
model="gemini-2.5-pro",
|
|
tools=[vertex_search]
|
|
)
|
|
```
|
|
|
|
### 🔄 CI/CD Automation
|
|
|
|
**GitHub Actions (auto-generated):**
|
|
```yaml
|
|
name: Deploy Agent
|
|
on:
|
|
push:
|
|
branches: [main]
|
|
|
|
jobs:
|
|
deploy:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v3
|
|
- name: Test Agent
|
|
run: pytest tests/
|
|
- name: Deploy to Cloud Run
|
|
run: |
|
|
gcloud run deploy agent \
|
|
--source . \
|
|
--region us-central1
|
|
```
|
|
|
|
**Cloud Build Pipeline:**
|
|
```yaml
|
|
steps:
|
|
# Build container
|
|
- name: 'gcr.io/cloud-builders/docker'
|
|
args: ['build', '-t', 'gcr.io/$PROJECT_ID/agent', '.']
|
|
|
|
# Run tests
|
|
- name: 'gcr.io/$PROJECT_ID/agent'
|
|
args: ['pytest', 'tests/']
|
|
|
|
# Deploy to Cloud Run
|
|
- name: 'gcr.io/cloud-builders/gcloud'
|
|
args:
|
|
- 'run'
|
|
- 'deploy'
|
|
- 'agent'
|
|
- '--image=gcr.io/$PROJECT_ID/agent'
|
|
- '--region=us-central1'
|
|
```
|
|
|
|
### 🎯 Multi-Agent Orchestration
|
|
|
|
**Hierarchical Agents:**
|
|
```python
|
|
# Coordinator agent with specialized sub-agents
|
|
class ProjectManagerAgent(ADKAgent):
|
|
def __init__(self):
|
|
self.researcher = ResearchAgent()
|
|
self.analyst = AnalysisAgent()
|
|
self.writer = WriterAgent()
|
|
self.reviewer = ReviewAgent()
|
|
|
|
def run(self, project_brief: str):
|
|
# Coordinate multiple agents
|
|
research = self.researcher.run(project_brief)
|
|
analysis = self.analyst.run(research)
|
|
draft = self.writer.run(analysis)
|
|
final = self.reviewer.run(draft)
|
|
return final
|
|
```
|
|
|
|
**Parallel Agent Execution:**
|
|
```python
|
|
import asyncio
|
|
|
|
class ParallelResearchAgent(ADKAgent):
|
|
async def research_topic(self, topics: list[str]):
|
|
# Run multiple agents concurrently
|
|
tasks = [
|
|
self.specialized_agent(topic)
|
|
for topic in topics
|
|
]
|
|
results = await asyncio.gather(*tasks)
|
|
return self.synthesize(results)
|
|
```
|
|
|
|
### 📈 Evaluation & Monitoring
|
|
|
|
**Built-in Evaluation:**
|
|
```python
|
|
from google.cloud.aiplatform import agent_evaluation
|
|
|
|
# Define evaluation metrics
|
|
eval_config = agent_evaluation.EvaluationConfig(
|
|
metrics=["accuracy", "relevance", "safety"],
|
|
test_dataset="gs://bucket/eval_data.jsonl"
|
|
)
|
|
|
|
# Run evaluation
|
|
results = agent.evaluate(eval_config)
|
|
print(f"Accuracy: {results.accuracy}")
|
|
print(f"Relevance: {results.relevance}")
|
|
```
|
|
|
|
**Cloud Trace Integration:**
|
|
```python
|
|
from google.cloud import trace_v1
|
|
|
|
# Automatic tracing
|
|
@traced_agent
|
|
class MonitoredAgent(ADKAgent):
|
|
def run(self, query: str):
|
|
# All calls automatically traced
|
|
with self.trace_span("retrieval"):
|
|
docs = self.retrieve(query)
|
|
|
|
with self.trace_span("generation"):
|
|
response = self.generate(query, docs)
|
|
|
|
return response
|
|
```
|
|
|
|
### 🔒 Security & Best Practices
|
|
|
|
**1. Service Account Management:**
|
|
```bash
|
|
# Create minimal-permission service account
|
|
gcloud iam service-accounts create agent-sa \
|
|
--display-name "Agent Service Account"
|
|
|
|
# Grant only required permissions
|
|
gcloud projects add-iam-policy-binding PROJECT_ID \
|
|
--member="serviceAccount:agent-sa@PROJECT.iam.gserviceaccount.com" \
|
|
--role="roles/aiplatform.user"
|
|
```
|
|
|
|
**2. Secret Management:**
|
|
```python
|
|
from google.cloud import secretmanager
|
|
|
|
def get_api_key():
|
|
client = secretmanager.SecretManagerServiceClient()
|
|
name = "projects/PROJECT/secrets/api-key/versions/latest"
|
|
response = client.access_secret_version(name=name)
|
|
return response.payload.data.decode('UTF-8')
|
|
```
|
|
|
|
**3. VPC Service Controls:**
|
|
```bash
|
|
# Enable VPC SC for data security
|
|
gcloud access-context-manager perimeters create agent-perimeter \
|
|
--resources=projects/PROJECT_ID \
|
|
--restricted-services=aiplatform.googleapis.com
|
|
```
|
|
|
|
### 💰 Cost Optimization
|
|
|
|
**Strategies:**
|
|
- Use Gemini 2.5 Flash for most operations
|
|
- Cache embeddings for RAG systems
|
|
- Implement request batching
|
|
- Use preemptible GKE nodes
|
|
- Monitor token usage in Cloud Monitoring
|
|
|
|
**Pricing Examples:**
|
|
- Cloud Run: $0.00024/GB-second
|
|
- Agent Engine: Pay-per-request pricing
|
|
- GKE: Standard cluster costs
|
|
- Gemini API: $3.50/1M tokens (Pro)
|
|
|
|
### 📚 Reference Architecture
|
|
|
|
**Production Agent System:**
|
|
```
|
|
┌─────────────────┐
|
|
│ Load Balancer │
|
|
└────────┬────────┘
|
|
│
|
|
┌────▼────┐
|
|
│Cloud Run│ (Agent containers)
|
|
└────┬────┘
|
|
│
|
|
┌────▼──────────┐
|
|
│ Agent Engine │ (Orchestration)
|
|
└────┬──────────┘
|
|
│
|
|
┌────▼────────────────┐
|
|
│ Vertex AI Search │ (RAG)
|
|
│ Vector Search │
|
|
│ Gemini 2.5 Pro │
|
|
└─────────────────────┘
|
|
```
|
|
|
|
### 🎯 Best Practices for Jeremy
|
|
|
|
**1. Start with Templates:**
|
|
```bash
|
|
# Use Agent Starter Pack templates
|
|
uvx agent-starter-pack create my-agent --template agentic_rag
|
|
```
|
|
|
|
**2. Local Development:**
|
|
```bash
|
|
# Test locally first
|
|
adk serve --port 8080
|
|
curl http://localhost:8080/query -d '{"question": "test"}'
|
|
```
|
|
|
|
**3. Gradual Deployment:**
|
|
```bash
|
|
# Deploy to dev → staging → prod
|
|
asp deploy --env dev
|
|
# Test thoroughly
|
|
asp deploy --env staging
|
|
# Final production push
|
|
asp deploy --env production
|
|
```
|
|
|
|
**4. Monitor Everything:**
|
|
- Enable Cloud Trace
|
|
- Set up error reporting
|
|
- Track token usage
|
|
- Monitor response times
|
|
- Set up alerting
|
|
|
|
### 📖 Official Documentation
|
|
|
|
**Core Resources:**
|
|
- ADK Docs: https://google.github.io/adk-docs/
|
|
- Agent Starter Pack: https://github.com/GoogleCloudPlatform/agent-starter-pack
|
|
- Agent Engine: https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/overview
|
|
- Agent Builder: https://cloud.google.com/products/agent-builder
|
|
|
|
**Tutorials:**
|
|
- Building AI Agents: https://codelabs.developers.google.com/devsite/codelabs/building-ai-agents-vertexai
|
|
- Multi-agent Systems: https://cloud.google.com/blog/products/ai-machine-learning/build-and-manage-multi-system-agents-with-vertex-ai
|
|
|
|
## When This Skill Activates
|
|
|
|
This skill automatically activates when you mention:
|
|
- Agent development, ADK, or Agent Starter Pack
|
|
- Multi-agent systems or orchestration
|
|
- Containerized agent deployment
|
|
- Cloud Run, GKE, or Agent Engine deployment
|
|
- RAG agents or ReAct agents
|
|
- Agent templates or scaffolding
|
|
- CI/CD for agents
|
|
- Production agent systems
|
|
|
|
## Integration with Other Services
|
|
|
|
**Google Cloud:**
|
|
- Vertex AI (Gemini, Search, Vector Search)
|
|
- Cloud Storage (data storage)
|
|
- Cloud Functions (triggers)
|
|
- Cloud Scheduler (automation)
|
|
- Cloud Logging & Monitoring
|
|
|
|
**Third-party:**
|
|
- LangChain integration
|
|
- CrewAI orchestration
|
|
- Custom tool frameworks
|
|
|
|
## Success Metrics
|
|
|
|
**Track:**
|
|
- Agent response time (target: <2s)
|
|
- Evaluation scores (target: >85% accuracy)
|
|
- Deployment frequency (target: daily)
|
|
- System uptime (target: 99.9%)
|
|
- Cost per query (target: <$0.01)
|
|
|
|
---
|
|
|
|
**This skill makes Jeremy a Google Cloud agent architecture expert with instant access to ADK, Agent Starter Pack, and production deployment patterns.**
|