172 lines
4.8 KiB
Markdown
172 lines
4.8 KiB
Markdown
---
|
|
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
|