title: "google-adk: Develop agentic software and multi-agent systems using Google ADK in Python"
name: google-adk
description: Develop agentic software and multi-agent systems using Google ADK in Python
tags:
- sdd-workflow
- shared-architecture
- domain-specific
custom_fields:
layer: null
artifact_type: null
architecture_approaches: [ai-agent-based, traditional-8layer]
priority: shared
development_status: active
skill_category: domain-specific
upstream_artifacts: []
downstream_artifacts: []

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

1. 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

2. 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

3. 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:

1. Built-in Tools:
2. Search - Web search via Google Search API
3. Code Execution - Python code interpreter (sandboxed)

4. Google Cloud tools - Vertex AI, BigQuery, Cloud Storage

5. Custom Function Tools:

6. Python functions wrapped as tools
7. Automatic schema generation from type hints

8. Supports async functions

9. OpenAPI Tools:

10. Auto-generate from OpenAPI/Swagger specs

11. HTTP-based service integration

12. MCP (Model Context Protocol) Tools:

13. Integration with MCP servers
14. 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

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:
1. Single Responsibility - One clear purpose per tool
2. Descriptive Naming - Clear action and object naming
3. 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:

1. Functionality:
2. ✓ Agent completes primary objective on test cases
3. ✓ Tool execution succeeds with valid inputs
4. ✓ Error handling covers expected failure modes

5. ✓ Multi-turn conversations maintain context

6. Performance:

7. ✓ Response time <5 seconds for simple queries
8. ✓ Response time <30 seconds for complex workflows
9. ✓ Evaluation pass rate ≥80% on criteria

10. ✓ Resource usage within deployment limits

11. Safety:

12. ✓ Input validation on all tools
13. ✓ High-risk actions require confirmation (HITL)
14. ✓ No hardcoded credentials or API keys

15. ✓ Rate limiting on external API calls

16. Observability:

17. ✓ Logging configured for debugging
18. ✓ Tracing enabled for multi-agent workflows
19. ✓ Evaluation metrics tracked

20. ✓ Error alerts configured

21. Documentation:

22. ✓ Agent purpose and capabilities documented
23. ✓ Tool descriptions clear and accurate
24. ✓ Example usage provided
25. ✓ Known limitations documented

Definition of Done: Tools

A tool is production-ready when:

1. Interface:
2. ✓ Function has type hints for all parameters
3. ✓ Docstring explains purpose, args, returns
4. ✓ Parameter descriptions guide LLM selection

5. ✓ Return values are JSON-serializable

6. Reliability:

7. ✓ Error handling with informative messages
8. ✓ Input validation prevents invalid operations
9. ✓ Timeout configured for long-running operations

10. ✓ Retry logic for transient failures

11. Testing:

12. ✓ Unit tests cover success cases
13. ✓ Unit tests cover error cases
14. ✓ Integration tests with agent execution
15. ✓ 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:
```python
# 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 ([email protected]).

  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:
python # 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:
python 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:
python # Use Parallel Agent or async tools agent = ParallelAgent( tools=[tool1, tool2, tool3] # Execute concurrently )

Issue: Context limit exceeded
- Cause: Conversation history too long
- Resolution:
python 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:
```bash
# 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

1. Enable verbose logging:

import logging

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("google.adk")
logger.setLevel(logging.DEBUG)

2. Test tools independently:

# Test tool without agent
tool = Tool.from_function(my_function)
result = my_function("test_input")
print(f"Tool output: {result}")

3. Use web UI for interactive debugging:

adk api_server --debug
# Access UI at http://localhost:4200
# View tool calls, agent reasoning, response generation

4. Inspect agent execution trace:

response = agent.run("test query", return_trace=True)
print(response.trace)  # Shows all tool calls and decisions

Complexity Ratings

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