Google ADK Agent Development

Build AI agents using Google's Agent Development Kit (ADK) - a flexible, modular Python framework for developing, evaluating, and deploying AI agents.

Project Structure

Standard ADK project layout:

my_agent/
├── agent.py          # Agent definition (must export root_agent)
├── tools.py          # Custom tool functions (optional)
├── __init__.py       # Package init
└── .env              # API keys (GOOGLE_API_KEY or GOOGLE_CLOUD_PROJECT)

For multi-agent projects:

my_project/
├── agents/
│   ├── coordinator.py
│   ├── specialist_a.py
│   └── specialist_b.py
├── tools/
│   └── custom_tools.py
├── agent.py          # Root agent entry point
└── .env

Core Patterns

Single Agent with Tools

from google.adk.agents import Agent

def get_weather(city: str) -> dict:
    """Get weather for a city. The docstring is critical - ADK uses it for tool schema."""
    return {"status": "success", "temp": "72F", "city": city}

root_agent = Agent(
    name="weather_agent",
    model="gemini-3.0-flash-preview",
    description="Provides weather information.",
    instruction="You help users get weather. Use the get_weather tool when asked.",
    tools=[get_weather],
)

Multi-Agent with Delegation

from google.adk.agents import LlmAgent

billing = LlmAgent(name="billing", model="gemini-3.0-flash-preview",
                   description="Handles billing and payment questions.")
support = LlmAgent(name="support", model="gemini-3.0-flash-preview",
                   description="Handles technical support.")

root_agent = LlmAgent(
    name="coordinator",
    model="gemini-3.0-flash-preview",
    instruction="Route billing questions to billing agent, technical issues to support.",
    sub_agents=[billing, support],
)

Sequential Pipeline

from google.adk.agents import SequentialAgent, LlmAgent

step1 = LlmAgent(name="researcher", instruction="Research the topic.", output_key="research")
step2 = LlmAgent(name="writer", instruction="Write based on {research}.", output_key="draft")
step3 = LlmAgent(name="editor", instruction="Polish the {draft}.")

root_agent = SequentialAgent(name="content_pipeline", sub_agents=[step1, step2, step3])

Parallel Execution

from google.adk.agents import ParallelAgent, SequentialAgent, LlmAgent

fetch_news = LlmAgent(name="news", output_key="news_data")
fetch_weather = LlmAgent(name="weather", output_key="weather_data")

gatherer = ParallelAgent(name="info_gather", sub_agents=[fetch_news, fetch_weather])
synthesizer = LlmAgent(name="synth", instruction="Combine {news_data} and {weather_data}.")

root_agent = SequentialAgent(name="pipeline", sub_agents=[gatherer, synthesizer])

Loop with Termination

from google.adk.agents import LoopAgent, LlmAgent, BaseAgent
from google.adk.events import Event, EventActions

class QualityChecker(BaseAgent):
    async def _run_async_impl(self, ctx):
        status = ctx.session.state.get("quality", "fail")
        yield Event(author=self.name, actions=EventActions(escalate=(status == "pass")))

refiner = LlmAgent(name="refiner", instruction="Improve {draft}.", output_key="draft")
checker = LlmAgent(name="checker", instruction="Rate quality.", output_key="quality")

root_agent = LoopAgent(
    name="refinement_loop",
    max_iterations=5,
    sub_agents=[refiner, checker, QualityChecker(name="gate")],
)

Key Concepts

Agent Parameters

name

model

instruction

description

tools

sub_agents

output_key

State Management

Use

{var}

output_key

agent_a = LlmAgent(name="a", output_key="result_a")  # Writes to state["result_a"]
agent_b = LlmAgent(name="b", instruction="Process {result_a}.")  # Reads state["result_a"]

Tool Design

Tool functions must have:

• Clear docstrings (ADK parses these for the LLM)
• Type hints for parameters
• Return dict or simple types

def search_database(query: str, limit: int = 10) -> dict:
    """Search the database for matching records.

    Args:
        query: The search query string.
        limit: Maximum results to return (default 10).

    Returns:
        dict with 'status' and 'results' keys.
    """
    return {"status": "success", "results": [...]}

Running Agents

Via CLI (Development)

# Install
pip install google-adk

# Set API key
export GOOGLE_API_KEY="your-key"

# Run CLI
adk run my_agent

# Run web UI (development only)
adk web --port 8000

# Run API server
adk api_server my_agent --port 8080

Programmatically (Production)

For APIs, UIs, or custom integrations, use Runner and Session directly:

from google.adk.agents import Agent
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types

# Setup
agent = Agent(name="assistant", model="gemini-3.0-flash-preview", instruction="Be helpful.")
session_service = InMemorySessionService()
runner = Runner(agent=agent, app_name="my_app", session_service=session_service)

# Create session
await session_service.create_session(
    app_name="my_app", user_id="user_123", session_id="session_456"
)

# Run agent
message = types.Content(role="user", parts=[types.Part(text="Hello!")])
async for event in runner.run_async(
    user_id="user_123", session_id="session_456", new_message=message
):
    if event.is_final_response():
        print(event.content.parts[0].text)

See runtime.md for complete API/UI integration examples.

examples

For detailed patterns and examples:

• agents.md: LlmAgent, workflow agents, custom agents
• tools.md: Function tools, MCP tools, OpenAPI tools, AgentTool
• patterns.md: Multi-agent design patterns
• runtime.md: Runner, Session, Events, and building APIs/UIs