Google Agent Development Kit (ADK) Skill Purpose
Provide specialized guidance for developing agentic applications and multi-agent systems using Google's Agent Development Kit (ADK). Enable AI assistants to design agents, build tools, orchestrate multi-agent workflows, implement memory/state management, and deploy agent-based applications following code-first development patterns.
When to Use This Skill
Invoke this skill when:
Building conversational AI agents with tool integration Creating multi-agent orchestration systems Developing workflow agents (sequential, parallel, iterative) Implementing custom tools for agents Designing agent architectures for complex tasks Deploying agent applications to production Evaluating agent performance and behavior Implementing human-in-the-loop patterns
Do NOT use this skill for:
Generic Python development (use Python-specific skills) Simple REST API development (ADK is for agentic systems) Frontend development (ADK is backend agent framework) Direct LLM API usage without agent orchestration (use LLM provider SDKs) Non-Python agent frameworks (LangChain, CrewAI, AutoGPT - different patterns) Core ADK Concepts Platform Architecture
Framework Philosophy:
Code-first approach - Define agents in Python code (not YAML/JSON configs) Model-agnostic - Optimized for Gemini but supports other LLMs Composable - Build complex systems from simple agent primitives Observable - Built-in integration with tracing and monitoring tools
Supported Languages:
Python (primary, most mature) - google-adk package Go (available) - adk-go repository Java (available) - adk-java repository
Runtime Environment:
Python 3.9+ required Agent Engine for deployment (containerized execution) Web UI for development/testing (Angular + FastAPI) CLI for evaluation and deployment operations Agent Types and Hierarchy
- LlmAgent (Dynamic, model-driven)
Use for:
Conversational interfaces Decision-making with uncertainty Natural language understanding Creative tasks (content generation) Contextual reasoning
Characteristics:
Uses LLM for decision-making Non-deterministic execution Tool selection driven by model Handles ambiguous inputs
- Workflow Agents (Deterministic, programmatic)
Sequential Agent:
Executes tools in fixed order Use for: Multi-step processes with dependencies Example: Data pipeline (fetch → transform → load)
Parallel Agent:
Executes multiple tools concurrently Use for: Independent operations requiring aggregation Example: Multi-source data gathering
Loop Agent:
Repeats execution until condition met Use for: Iterative refinement, convergence tasks Example: Generator-critic pattern
- Custom Agents (User-defined logic)
Use for:
Domain-specific orchestration Complex state machines Integration with existing systems Specialized execution patterns
Agent Composition:
Agents can contain sub-agents (hierarchical) Parent agent coordinates child agents Supports multi-level nesting Tool Ecosystem
Tool Categories:
Built-in Tools:
Search - Web search via Google Search API Code Execution - Python code interpreter (sandboxed) Google Cloud tools - Vertex AI, BigQuery, Cloud Storage
Custom Function Tools:
Python functions wrapped as tools Automatic schema generation from type hints Supports async functions
OpenAPI Tools:
Auto-generate from OpenAPI/Swagger specs HTTP-based service integration
MCP (Model Context Protocol) Tools:
Integration with MCP servers Cross-framework tool sharing
Tool Attributes:
Name - Unique identifier Description - Natural language explanation for LLM Parameters - JSON schema defining inputs Function - Execution logic Confirmation - Optional human-in-the-loop approval Memory and State Management
Session Management:
Agent maintains conversation history Automatic context window management Configurable history retention
State Persistence:
Custom state objects per agent Serialization support (JSON, pickle) Database integration for long-term storage
Context Caching:
Reduces token usage for repeated context Automatic cache invalidation Configurable cache TTL Agent Development Methodology Planning Phase
Step 1: Define Agent Purpose
Primary objective (single responsibility) Input/output format Success criteria Failure modes
Step 2: Identify Required Tools
Decision criteria:
Use built-in tools when available (Search, Code Execution) Create custom functions for simple operations (<100 lines) Use OpenAPI tools for existing REST APIs Use MCP tools for cross-framework compatibility
Step 3: Select Agent Type
START: What's the agent's decision pattern? │ ├─> Requires natural language reasoning? ─Yes─> LlmAgent ★ │ ├─> Fixed sequence of steps? │ └─> Sequential Workflow Agent ★ │ ├─> Independent parallel operations? │ └─> Parallel Workflow Agent ★ │ ├─> Iterative refinement needed? │ └─> Loop Workflow Agent ★ │ └─> Custom orchestration logic? └─> Custom Agent ★
Step 4: Design Multi-Agent Architecture (if needed)
Patterns:
Coordinator/Dispatcher - Central agent routes to specialists Sequential Pipeline - Output of Agent A → Input of Agent B Parallel Fan-Out/Gather - Distribute work, aggregate results Hierarchical Decomposition - Break complex task into subtasks Implementation Phase
Agent Implementation Examples:
[See Code Examples: examples/google_adk_agent_implementation.py]
Key agent patterns demonstrated:
LlmAgent - create_weather_assistant() - Conversational agent with custom tools SequentialAgent - create_data_pipeline() - Ordered execution (fetch → transform → save) ParallelAgent - create_market_researcher() - Concurrent tool execution LoopAgent - create_content_generator() - Iterative refinement with break conditions Session Management - create_stateful_session() - Multi-turn conversation with history Testing Phase
Web UI Testing:
Start API server
adk api_server --port 8000
Start web UI (separate terminal)
cd adk-web npm install npm start
Access: http://localhost:4200
Programmatic Testing:
Unit test for agent
def test_weather_agent(): agent = create_weather_agent() response = agent.run("Weather in NYC?") assert "weather" in response.content.lower() assert response.success is True
Integration test with mock tools
def test_pipeline_agent(): agent = create_pipeline_agent(mock_tools=True) result = agent.run({"input": "test_data"}) assert result["status"] == "completed"
Evaluation Framework:
from google.adk.evaluation import evaluate_agent
Criteria-based evaluation
results = evaluate_agent( agent=my_agent, test_cases=[ {"input": "What's 2+2?", "expected_output": "4"}, {"input": "Explain quantum computing", "criteria": "mentions_qubits"} ], evaluator_model="gemini-2.0-flash" )
print(f"Pass rate: {results.pass_rate}") print(f"Average score: {results.avg_score}")
Tool Development
[See Code Examples: examples/google_adk_tools_example.py]
Custom Function Tools
Examples demonstrated:
Basic Function Tool - calculate_tax() - Simple tool with type hints Async Tool - fetch_user_data() - Asynchronous API calls HITL Confirmation - send_email(), delete_user_account() - Human approval required Input Validation - send_email_tool() - Email format validation and sanitization Retry Logic - fetch_external_data() - Automatic retry with exponential backoff Rate Limiting - call_external_api() - Decorator-based rate limiting Error Handling - fetch_stock_price() - Graceful degradation on failures OpenAPI Tools
Integration Pattern:
Load tools from OpenAPI spec URL Optional tool filtering for specific operations Automatic schema generation from spec [See: create_api_agent() in examples/google_adk_tools_example.py] MCP Tool Integration
Integration Pattern:
Connect to MCP server endpoint Import tools for cross-framework compatibility [See: create_mcp_agent() in examples/google_adk_tools_example.py] Multi-Agent Orchestration
[See Code Examples: examples/google_adk_multi_agent.py]
Multi-Agent Patterns
Pattern 1: Coordinator/Dispatcher (Complexity: 4)
Use case: Route user requests to specialized agents Function: create_coordinator_system() - Weather + Finance specialists
Pattern 2: Sequential Pipeline (Complexity: 3)
Use case: Multi-stage processing with dependencies Function: create_content_pipeline() - Research → Write → Edit
Pattern 3: Parallel Fan-Out/Gather (Complexity: 4)
Use case: Aggregate results from multiple sources Function: create_market_analysis_system() - Technical + Fundamental + Sentiment analysis
Pattern 4: Hierarchical Decomposition (Complexity: 5)
Use case: Break complex tasks into manageable subtasks Function: create_project_management_system() - Multi-level agent hierarchy
Pattern 5: Generator-Critic Loop (Complexity: 4)
Use case: Iterative refinement with feedback Function: create_quality_content_system() - Generate → Critique → Refine
Pattern 6: Human-in-the-Loop (HITL) (Complexity: 3)
Use case: Critical decisions require human approval Function: create_account_management_agent() - Confirmation before deletion
Pattern 7: State Management
Use case: Persistent user context across sessions Class: StatefulAgent - In-memory state storage with history
Pattern 8: Database Persistence
Use case: Long-term state storage Functions: save_state(), load_state() - PostgreSQL-backed persistence Memory and State Management
[See Code Examples: examples/google_adk_multi_agent.py - State Management section]
Session Management
Basic Session Pattern:
Multi-turn conversation with history retention Automatic context window management Configurable history limits
[See: create_stateful_session() in examples/google_adk_agent_implementation.py]
State Persistence
Custom State Object:
In-memory state storage per user Dataclass-based state modeling Conversation history tracking
[See: StatefulAgent class in examples/google_adk_multi_agent.py]
Database Persistence:
Long-term state storage with SQLAlchemy JSON-serialized state data PostgreSQL/MySQL support
[See: save_state(), load_state() functions in examples/google_adk_multi_agent.py]
Deployment Options
[See Code Examples: examples/google_adk_deployment.py]
Agent Engine (Managed Service)
Deployment Commands:
pip install google-adk[cli] adk auth login adk deploy --agent-file agent.py --agent-name my_agent --project-id my-gcp-project --region us-central1
[See: create_production_agent() for configuration example]
Cloud Run Deployment
Components:
FastAPI server with agent endpoints Dockerfile for containerization Health check and error handling Environment configuration
[See: FastAPI app implementation, Dockerfile reference, deployment commands in examples/google_adk_deployment.py]
Docker Containerization
Self-Hosted Options:
Docker Compose with Redis Single container deployment Environment variable configuration
[See: docker-compose.yml reference, deployment commands in examples/google_adk_deployment.py]
Resource Requirements Agent Complexity CPU RAM Concurrent Requests Simple LlmAgent 1 core 512MB 10 Workflow Agent 2 cores 1GB 20 Multi-Agent (3-5 agents) 4 cores 2GB 10 Complex Multi-Agent (>5) 8 cores 4GB 5 Evaluation and Testing
[See Code Examples: examples/google_adk_deployment.py - Evaluation endpoint]
Criteria-Based Evaluation
Pattern:
Define custom evaluation criteria (accuracy, helpfulness, etc.) Run test cases against agent Analyze pass rate and scores
[See: evaluate_agent_endpoint() in examples/google_adk_deployment.py]
User Simulation Evaluation
Pattern:
Simulate user interactions with defined goals Track goal completion rate Measure average turns to completion
[See documentation for UserSimulator examples]
Best Practices
[See Code Examples: examples/google_adk_tools_example.py - Tool Design Best Practices section]
Agent Instruction Writing
Effective Patterns:
Clear role and responsibilities Structured format with constraints Specific tool usage guidance Example interactions
[See: GOOD vs BAD examples at end of examples/google_adk_tools_example.py]
Tool Design Principles
Key Principles:
Single Responsibility - One clear purpose per tool Descriptive Naming - Clear action and object naming Type Hints - Complete type annotations for all parameters
[See: Tool design examples at end of examples/google_adk_tools_example.py]
Error Handling
Strategies:
Graceful Degradation - Return error messages instead of raising exceptions Retry Logic - Automatic retry with exponential backoff Input Validation - Validate and sanitize all inputs
[See: fetch_stock_price(), fetch_external_data(), send_email_tool() in examples/google_adk_tools_example.py]
Security and Safety
Implementation:
Input Validation - Email format validation, length limits Rate Limiting - Decorator-based request throttling Sanitization - Remove dangerous HTML/script content
[See: send_email_tool(), rate_limit() decorator in examples/google_adk_tools_example.py]
Performance Optimization
Async Tools:
Automatic parallel execution for async functions Improved throughput for I/O-bound operations
[See: fetch_price(), create_portfolio_analyzer() in examples/google_adk_tools_example.py]
Quality Gates Definition of Done: Agents
An agent is production-ready when:
Functionality:
✓ Agent completes primary objective on test cases ✓ Tool execution succeeds with valid inputs ✓ Error handling covers expected failure modes ✓ Multi-turn conversations maintain context
Performance:
✓ Response time <5 seconds for simple queries ✓ Response time <30 seconds for complex workflows ✓ Evaluation pass rate ≥80% on criteria ✓ Resource usage within deployment limits
Safety:
✓ Input validation on all tools ✓ High-risk actions require confirmation (HITL) ✓ No hardcoded credentials or API keys ✓ Rate limiting on external API calls
Observability:
✓ Logging configured for debugging ✓ Tracing enabled for multi-agent workflows ✓ Evaluation metrics tracked ✓ Error alerts configured
Documentation:
✓ Agent purpose and capabilities documented ✓ Tool descriptions clear and accurate ✓ Example usage provided ✓ Known limitations documented Definition of Done: Tools
A tool is production-ready when:
Interface:
✓ Function has type hints for all parameters ✓ Docstring explains purpose, args, returns ✓ Parameter descriptions guide LLM selection ✓ Return values are JSON-serializable
Reliability:
✓ Error handling with informative messages ✓ Input validation prevents invalid operations ✓ Timeout configured for long-running operations ✓ Retry logic for transient failures
Testing:
✓ Unit tests cover success cases ✓ Unit tests cover error cases ✓ Integration tests with agent execution ✓ Performance benchmarks for expensive operations Error Handling Guide Common Issues and Resolutions
Issue: Agent doesn't call the right tool
Cause: Tool description unclear or ambiguous Resolution:
BAD: Vague description
def process(data): """Process data.""" # Too generic
GOOD: Specific description
def validate_email_format(email: str) -> bool: """Check if email address matches valid format (user@domain.com).
Use this tool ONLY to validate email syntax, not to verify
if email exists or is deliverable."""
Issue: Agent loops indefinitely
Cause: No termination condition in Loop Agent Resolution:
Add max_iterations and explicit break condition
agent = LoopAgent( tools=[...], max_iterations=10, # Hard limit break_condition=lambda result: result.get("completed", False) )
Issue: "Tool execution failed" errors
Cause: Tool raises unhandled exception Resolution: def robust_tool(param: str) -> str: try: result = risky_operation(param) return f"Success: {result}" except SpecificError as e: return f"Operation failed: {e.message}" except Exception as e: logger.error(f"Unexpected error in robust_tool: {e}") return "Temporary service error, please try again"
Issue: Agent response is too slow
Cause: Sequential tool calls when parallelization possible Resolution:
Use Parallel Agent or async tools
agent = ParallelAgent( tools=[tool1, tool2, tool3] # Execute concurrently )
Issue: Context limit exceeded
Cause: Conversation history too long Resolution: session = Session( agent=my_agent, max_history_turns=10, # Limit history context_window_tokens=30000 # Set explicit limit )
Issue: Deployment fails on Cloud Run
Cause: Missing dependencies or environment variables Resolution:
Ensure requirements.txt is complete
pip freeze > requirements.txt
Set required environment variables
gcloud run deploy my-agent \ --set-env-vars GOOGLE_API_KEY=your_key,AGENT_CONFIG=prod
Debugging Strategies
- Enable verbose logging:
import logging
logging.basicConfig(level=logging.DEBUG) logger = logging.getLogger("google.adk") logger.setLevel(logging.DEBUG)
- Test tools independently:
Test tool without agent
tool = Tool.from_function(my_function) result = my_function("test_input") print(f"Tool output: {result}")
- Use web UI for interactive debugging:
adk api_server --debug
Access UI at http://localhost:4200
View tool calls, agent reasoning, response generation
- Inspect agent execution trace:
response = agent.run("test query", return_trace=True) print(response.trace) # Shows all tool calls and decisions
Complexity Ratings Task Rating Description Simple LlmAgent with tools 2 Basic conversational agent Sequential Workflow Agent 2 Fixed-order tool execution Parallel Workflow Agent 3 Concurrent operations Loop Workflow Agent 3 Iterative refinement Custom Agent 3 User-defined orchestration Coordinator/Dispatcher (2-3 agents) 4 Multi-agent routing Sequential Pipeline (3+ agents) 4 Chained agent execution Hierarchical Multi-Agent (>5 agents) 5 Complex nested architecture Custom tool development 2 Python function wrapper OpenAPI tool integration 2 Auto-generated from spec MCP tool integration 3 Cross-framework tools Deployment to Agent Engine 2 Managed deployment Self-hosted Docker deployment 3 Container orchestration Advanced evaluation framework 4 Custom criteria and simulation References Official Documentation Main docs: https://google.github.io/adk-docs/ Python SDK: https://github.com/google/adk-python Examples: https://github.com/google/adk-samples Web UI: https://github.com/google/adk-web Python SDK Resources Installation: pip install google-adk API Reference: https://google.github.io/adk-docs/api/python/ Quickstart Guide: https://google.github.io/adk-docs/quickstart/ Additional Languages Go SDK: https://github.com/google/adk-go Java SDK: https://github.com/google/adk-java Community Resources GitHub Discussions: https://github.com/google/adk-python/discussions Issue Tracker: https://github.com/google/adk-python/issues Related Skills For workflow automation: Use n8n skill For API design: Use api-design-architect skill For cloud deployment: Use cloud-devops-expert skill For Python development: Use Python-specific skills For LLM integration: Use model provider SDKs (OpenAI, Anthropic, etc.)
Version: 1.0.0 Last Updated: 2025-11-13 Complexity Rating: 3 (Moderate - requires agent architecture knowledge) Estimated Learning Time: 10-15 hours for proficiency