Adk Agent Development

1. ADK Project Structure

ADK requires a specific directory layout. The agent directory must be a Python package with these mandatory files:

project-root/
├── my_agent/                # Agent package (directory name = agent name)
│   ├── __init__.py          # REQUIRED: makes it a Python package
│   ├── agent.py             # REQUIRED: defines root_agent
│   └── .env                 # OPTIONAL: env vars (loaded by adk CLI)
├── pyproject.toml           # Python project config
├── .env                     # Project-level env vars
└── .venv/                   # Virtual environment

__init__.py — Module Registration

The __init__.py must import the agent module so ADK can discover root_agent:

from . import agent

Or explicitly export:

from my_agent.agent import root_agent
__all__ = ["root_agent"]

.env — Environment Configuration

The .env file configures the Gemini backend. For Vertex AI (recommended for Google Cloud):

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=us-central1

For Google AI (API key based):

GOOGLE_GENAI_USE_VERTEXAI=0
GOOGLE_API_KEY=your-api-key

Required Google Cloud APIs

When using Vertex AI, enable these APIs:

gcloud services enable aiplatform.googleapis.com
# For Cloud SQL persistence:
gcloud services enable sqladmin.googleapis.com compute.googleapis.com
# For Cloud Run deployment:
gcloud services enable run.googleapis.com artifactregistry.googleapis.com

2. Agent Definition Patterns

Basic Agent (Codelab 1)

The simplest agent uses the Agent class with a model, name, and instruction:

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

Key fields:

• model — The Gemini model to use (e.g., gemini-2.5-flash, gemini-2.5-pro)
• name — Unique identifier for the agent. The variable MUST be named root_agent.
• description — Human-readable summary; also used by other agents in multi-agent systems to understand this agent's capabilities.
• instruction — System prompt that shapes the agent's persona and behavior. This is the most important field for controlling agent output.
• tools — List of tools the agent can invoke (see Section 3).

Using LlmAgent (Codelab 3+)

LlmAgent is an alias/subclass of Agent used in later codelabs:

from google.adk.agents import LlmAgent

root_agent = LlmAgent(
    name="cafe_concierge",
    model="gemini-2.5-flash",
    instruction="""You are a friendly barista at "The Cloud Cafe".
    Your job:
    - Help customers browse the menu.
    - Take coffee and food orders.
    - Remember and respect dietary preferences.
    """,
    tools=[get_menu, place_order],
)

Convention: The agent instance variable must be named root_agent for ADK CLI tools (adk run, adk web) to discover it.

3. Tool Categories & Implementation

ADK supports four categories of tools. The agent's LLM reads tool names and docstrings to decide which tool to invoke.

3.1 FunctionTool — Custom Python Functions (Codelab 2)

Wrap any Python function as a tool. Docstrings are critical — the LLM uses them to understand when and how to call the tool.

from google.adk.agents import Agent
from google.adk.tools import FunctionTool

def get_fx_rate(base: str, target: str):
    """Fetches the current exchange rate between two currencies.

    Args:
        base: The base currency (e.g., "SGD").
        target: The target currency (e.g., "JPY").

    Returns:
        The exchange rate information as a json response.
    """
    import requests
    base_url = "https://hexarate.paikama.co/api/rates/latest"
    api_url = f"{base_url}/{base}?target={target}"
    response = requests.get(api_url)
    if response.status_code == 200:
        return response.json()

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant.',
    instruction='Answer user questions to the best of your knowledge',
    tools=[FunctionTool(get_fx_rate)]
)

Rules for FunctionTool:

• Use clear, descriptive function names and docstrings
• Use type hints on all parameters — the LLM needs them to fill arguments correctly
• The Args: section in the docstring describes each parameter for the LLM
• Return structured data (dicts, lists) rather than formatted strings when possible
• Functions can also be passed directly in the tools list without wrapping in FunctionTool() — ADK will auto-wrap them

3.2 AgentTool — Sub-Agent Delegation (Codelab 2)

Package an entire agent as a tool for another agent. This creates a multi-agent architecture where the root agent orchestrates specialist sub-agents.

from google.adk.agents import Agent
from google.adk.tools import google_search
from google.adk.tools.agent_tool import AgentTool

# Specialist sub-agent
google_search_agent = Agent(
    model='gemini-2.5-flash',
    name='google_search_agent',
    description='A search agent that uses Google Search to get latest information.',
    instruction='Use Google Search to answer questions about real-time information.',
    tools=[google_search],
)

# Root agent delegates to the sub-agent
root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant.',
    tools=[
        FunctionTool(get_fx_rate),
        AgentTool(agent=google_search_agent),
    ]
)

Key patterns:

• The root agent becomes an orchestrator/router — it understands request intent and delegates to the right tool
• The sub-agent's description is what the root agent reads to decide when to delegate
• google_search is a built-in ADK tool imported from google.adk.tools

3.3 LangchainTool — Third-Party Integration (Codelab 2)

Integrate tools from LangChain or other AI frameworks:

from google.adk.tools.langchain_tool import LangchainTool
from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

langchain_wikipedia_tool = WikipediaQueryRun(
    api_wrapper=WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=3000)
)
langchain_wikipedia_tool.description = (
    "Provides deep historical and cultural information on landmarks and places. "
    "Use this for 'tell me about' or 'what is the history of' type questions."
)

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant.',
    tools=[
        FunctionTool(get_fx_rate),
        AgentTool(agent=google_search_agent),
        LangchainTool(langchain_wikipedia_tool),
    ]
)

Additional dependencies: pip install langchain-community wikipedia

3.4 MCP Toolbox — Declarative Database Tools (Codelab 5)

Use MCP Toolbox for Databases to define database tools declaratively in YAML — no database code in your agent.

tools.yaml Configuration

The tools.yaml uses multi-document YAML (separated by ---). Each document has kind, name, and type fields. Toolbox supports four resource kinds:

# --- Data Source ---