building-google-adk-agents

Building Google ADK Agents

Quick Start

ADK agents require a root_agent definition in agent.py. Minimal agent:

from google.adk.agents import Agent

def my_tool(query: str) -> dict:
    """Does something useful. Args: query: The search query. Returns: dict with status and result."""
    return {"status": "success", "result": f"Processed: {query}"}

root_agent = Agent(
    model="gemini-2.5-flash",
    name="my_agent",
    description="Handles user requests.",
    instruction="You are a helpful assistant. Use 'my_tool' when the user asks you to process something.",
    tools=[my_tool],
)

Install: pip install google-adk

Run: adk web (browser UI) or adk run <agent_folder> (terminal)

Project Structure

my_agent/
├── __init__.py        # Empty or imports
├── agent.py           # Must define root_agent (or app for App-based agents)
├── .env               # API keys (GOOGLE_API_KEY or GOOGLE_GENAI_USE_VERTEXAI + project)
└── tools/             # Optional: separate tool modules

The .env file should contain one of:

# Option A: Google AI Studio (free tier)
GOOGLE_API_KEY=your_key_here

# Option B: Vertex AI
GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_PROJECT=your_project_id
GOOGLE_CLOUD_LOCATION=us-central1

Core Concepts

Agent Types

Type	Use When	LLM-Powered?
LlmAgent / Agent	Dynamic reasoning, tool use, conversation	Yes
SequentialAgent	Fixed pipeline (A → B → C)	No (orchestration only)
ParallelAgent	Independent tasks run concurrently	No
LoopAgent	Repeat until condition met	No
BaseAgent (custom)	Unique control flow not covered above	Your choice

LlmAgent Key Parameters

Agent(
    name="agent_name",              # Required, unique identifier
    model="gemini-2.5-flash",       # Required, LLM model string
    description="What this does",   # Recommended for multi-agent routing
    instruction="Your persona...",  # Core behavior guidance
    tools=[tool1, tool2],           # Functions, BaseTool, or AgentTool
    output_key="result_key",        # Auto-save response to state[key]
    output_schema=MyPydanticModel,  # Enforce structured JSON output
    sub_agents=[agent_a, agent_b],  # For LLM-driven delegation
    include_contents="default",     # "default" or "none" (stateless)
)