---
name: ck-google-adk-python
description: >
  Builds AI agents using Google Agent Development Kit (ADK) for Python.
  Activate when user says 'build a Google ADK agent', 'create agent with ADK',
  'Google Agent Development Kit', 'multi-agent with ADK', or 'ADK tool calling'.
  Accepts agent goals, tool definitions, and orchestration requirements.
---

## Overview
Scaffolds and implements AI agents using Google's Agent Development Kit (ADK) for Python, covering single agents, multi-agent pipelines, tool definitions, and deployment to Vertex AI Agent Engine.

## When to Use
- Building autonomous agents that use tools to complete tasks
- Creating multi-agent systems with specialized sub-agents
- Implementing agents that need Google Cloud service integrations
- Deploying production agents on Vertex AI Agent Engine
- Building agents with structured tool calling and state management

## Don't Use When
- Project uses a different agent framework (LangChain, CrewAI, AutoGen)
- Simple single-turn LLM calls without tool use (use direct Gemini API)
- Frontend-only application with no agent orchestration needs
- Budget constraints prohibit Vertex AI usage (ADK has local dev mode though)

## Steps / Instructions

### 1. Install ADK

```bash
pip install google-adk
# For Vertex AI deployment:
pip install google-adk[vertexai]
```

### 2. Define a Simple Agent

```python
# agent.py
from google.adk.agents import Agent
from google.adk.tools import FunctionTool
import os

def get_weather(city: str) -> dict:
    """Get current weather for a city."""
    # Replace with real weather API call
    return {"city": city, "temperature": 22, "condition": "sunny"}

weather_tool = FunctionTool(func=get_weather)

root_agent = Agent(
    name="weather_agent",
    model="gemini-1.5-pro",
    description="Answers weather questions for any city.",
    instruction="""You help users get weather information.
    Use the get_weather tool to fetch current conditions.
    Always confirm the city before reporting.""",
    tools=[weather_tool],
)
```

### 3. Run Locally

```python
# main.py
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai.types import Content, Part
from agent import root_agent

async def main():
    session_service = InMemorySessionService()
    runner = Runner(
        agent=root_agent,
        app_name="weather_app",
        session_service=session_service,
    )

    session = await session_service.create_session(
        app_name="weather_app",
        user_id="user_001",
    )

    message = Content(parts=[Part(text="What's the weather in Tokyo?")])

    async for event in runner.run_async(
        user_id="user_001",
        session_id=session.id,
        new_message=message,
    ):
        if event.is_final_response():
            print(event.content.parts[0].text)

import asyncio
asyncio.run(main())
```

### 4. Multi-Agent Pattern

```python
from google.adk.agents import Agent
from google.adk.agents.sequential import SequentialAgent

research_agent = Agent(
    name="researcher",
    model="gemini-1.5-pro",
    instruction="Research the given topic and return key facts.",
    tools=[search_tool],
)

writer_agent = Agent(
    name="writer",
    model="gemini-1.5-pro",
    instruction="Write a concise summary based on the research provided.",
)

pipeline = SequentialAgent(
    name="research_writer",
    sub_agents=[research_agent, writer_agent],
)
```

### 5. Tool Definition Best Practices

```python
from typing import Annotated
from pydantic import Field

def search_database(
    query: Annotated[str, Field(description="Search query string")],
    limit: Annotated[int, Field(description="Max results to return", ge=1, le=50)] = 10,
) -> list[dict]:
    """Search the product database and return matching items."""
    # implementation
    pass
```

- Use type annotations — ADK generates JSON schema from them
- Write clear docstrings — used as tool description for the model
- Return dicts/lists that serialize cleanly to JSON
- Handle errors gracefully and return error info in the dict

### 6. Session State Management

```python
from google.adk.sessions import DatabaseSessionService

# Persist sessions across restarts
session_service = DatabaseSessionService(
    db_url=os.environ["DATABASE_URL"]
)
```

### 7. Deploy to Vertex AI Agent Engine

```python
from google.adk.deployment import deploy_agent

deploy_agent(
    agent=root_agent,
    project=os.environ["GOOGLE_CLOUD_PROJECT"],
    location="us-central1",
    staging_bucket=os.environ["GCS_STAGING_BUCKET"],
)
```

## Notes
- Set `GOOGLE_API_KEY` or `GOOGLE_APPLICATION_CREDENTIALS` for authentication
- Use `adk web` CLI for interactive local testing with a built-in UI
- ADK auto-traces tool calls — view in Google Cloud Trace
- Always validate tool inputs; the model may pass unexpected types