Build an AI Agent with Google ADK
Google's Agent Development Kit (ADK) is an open-source framework from Google DeepMind and Google Cloud designed for building, evaluating, and deploying production-ready AI agents. It takes a code-first approach with first-class support for Gemini models, Google tools like Search and Code Execution, and flexible multi-agent composition patterns.
In this tutorial you will build a market research assistant that uses Gemini 2.0 Flash to analyze data, execute code, and coordinate with a summarizer sub-agent. You will learn the ADK's agent hierarchy, tool definitions, and how to use the built-in web UI for testing.
What You'll Learn#
- How to install Google ADK and configure Gemini API credentials
- How to define tools as Python functions and attach them to agents
- How to use ADK's built-in tools (Google Search, Code Execution)
- How to compose multi-agent pipelines using
SequentialAgentand sub-agents - How to test agents with the ADK web development UI
Prerequisites#
- Python 3.10 or higher installed
- A Google Cloud project with Vertex AI enabled, OR a Gemini API key from Google AI Studio
- Basic understanding of AI agents and tool use
- Familiarity with Python functions and type hints
Step 1: Project Setup#
Create a project directory and install the ADK:
mkdir google-adk-demo && cd google-adk-demo
python -m venv .venv && source .venv/bin/activate
# Install Google ADK
pip install google-adk google-generativeai python-dotenv
ADK projects follow a specific directory convention that the CLI expects. Create the following structure:
mkdir market_research_agent
touch market_research_agent/__init__.py
touch market_research_agent/agent.py
touch .env
Configure your API credentials in .env. Choose one of the two options:
# Option A: Use Gemini API (Google AI Studio key)
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your-gemini-api-key
# Option B: Use Vertex AI (Google Cloud project)
# GOOGLE_GENAI_USE_VERTEXAI=TRUE
# GOOGLE_CLOUD_PROJECT=your-project-id
# GOOGLE_CLOUD_LOCATION=us-central1
Step 2: Define Custom Tools#
ADK tools are regular Python functions with type-annotated parameters and descriptive docstrings. The framework automatically generates tool schemas from them.
Open market_research_agent/agent.py and add your tools:
import os
import json
import httpx
from dotenv import load_dotenv
load_dotenv()
def get_company_info(company_name: str) -> dict:
"""Retrieve basic publicly available information about a company.
Args:
company_name: The full name of the company to look up.
Returns:
A dictionary containing the company's name, sector, and a brief description.
"""
# In production, call a financial data API like Yahoo Finance or Alpha Vantage
# Mock data for tutorial purposes
mock_db = {
"openai": {
"name": "OpenAI",
"sector": "Artificial Intelligence",
"description": "AI safety and research company, creator of GPT and ChatGPT.",
"founded": 2015,
},
"anthropic": {
"name": "Anthropic",
"sector": "Artificial Intelligence",
"description": "AI safety company, creator of Claude.",
"founded": 2021,
},
"google deepmind": {
"name": "Google DeepMind",
"sector": "Artificial Intelligence",
"description": "Google's primary AI research lab, creator of Gemini.",
"founded": 2010,
},
}
key = company_name.lower().strip()
return mock_db.get(key, {"error": f"Company '{company_name}' not found in database."})
def calculate_market_metrics(revenue_m: float, growth_rate: float, years: int) -> dict:
"""Calculate projected market metrics for a company.
Args:
revenue_m: Current annual revenue in millions of USD.
growth_rate: Expected annual growth rate as a decimal (e.g., 0.25 for 25%).
years: Number of years to project forward.
Returns:
A dictionary with projected revenue figures for each year.
"""
projections = {}
current = revenue_m
for year in range(1, years + 1):
current = current * (1 + growth_rate)
projections[f"Year {year}"] = round(current, 2)
return {
"base_revenue_m": revenue_m,
"growth_rate_pct": growth_rate * 100,
"projections_m": projections,
"total_5yr_cagr_revenue": round(revenue_m * ((1 + growth_rate) ** years), 2),
}
Step 3: Build the Agent#
ADK agents are defined using the Agent class from google.adk.agents. The framework wires up the model, tools, and instructions automatically.
from google.adk.agents import Agent
from google.adk.tools import google_search # Built-in Google Search tool
# Sub-agent: responsible only for synthesizing and formatting reports
report_writer = Agent(
name="report_writer",
model="gemini-2.0-flash-exp",
description="A specialized agent that formats research findings into executive summaries.",
instruction="""You are a business analyst who writes concise executive summaries.
When given research data, structure your output as:
**Executive Summary: [Company/Topic]**
**Overview**: [2-3 sentence description]
**Key Findings**:
- [Finding 1]
- [Finding 2]
- [Finding 3]
**Outlook**: [Forward-looking assessment]
Be direct, data-driven, and avoid vague language.""",
# This agent needs no extra tools — it only synthesizes text
)
# Primary research agent with tools and delegation capability
root_agent = Agent(
name="market_research_agent",
model="gemini-2.0-flash-exp",
description="A market research agent that gathers and analyzes company data.",
instruction="""You are a market research analyst with access to company data and search capabilities.
For each research request:
1. Use get_company_info to retrieve basic company details
2. Use google_search to find recent news and developments
3. Use calculate_market_metrics if revenue projections are requested
4. Compile all findings into structured notes
5. Transfer to report_writer to format the final executive summary
Always verify information from multiple sources before drawing conclusions.""",
tools=[get_company_info, calculate_market_metrics, google_search],
sub_agents=[report_writer], # ADK's way of declaring child agents
)
The __init__.py must export the root agent for the CLI to discover it:
# market_research_agent/__init__.py
from . import agent
Step 4: Test with the ADK Web UI#
Google ADK ships with a local web development server that lets you interact with your agent in a chat interface and inspect all tool calls and sub-agent delegations.
# From the project root (not inside market_research_agent/)
adk web
Open your browser at http://localhost:8000. Select market_research_agent from the dropdown and start chatting:
- "Tell me about OpenAI and write an executive summary"
- "Project revenue of $100M at 30% growth for 5 years"
- "Search for the latest Gemini 2.0 news"
The web UI shows a trace panel on the right side where you can expand every tool call and see the exact inputs and outputs.
Step 5: Run Programmatically with the Runner#
For production deployment or scripting, use the ADK Runner directly instead of the web UI:
# run_agent.py
import asyncio
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from market_research_agent.agent import root_agent
async def main():
# Session service manages conversation state
session_service = InMemorySessionService()
# Create a session
session = await session_service.create_session(
app_name="market_research_agent",
user_id="demo-user",
session_id="session-001",
)
# Create the runner
runner = Runner(
agent=root_agent,
app_name="market_research_agent",
session_service=session_service,
)
# Send a message and iterate over response events
from google.adk.events import Event
from google.genai import types
user_message = types.Content(
role="user",
parts=[types.Part(text="Research Anthropic and give me a market projection at 40% growth for 3 years.")]
)
print("Running agent...\n")
async for event in runner.run_async(
user_id="demo-user",
session_id="session-001",
new_message=user_message,
):
if event.is_final_response():
print("=== Final Response ===")
print(event.content.parts[0].text)
elif event.get_function_calls():
for call in event.get_function_calls():
print(f"Tool called: {call.name}({call.args})")
if __name__ == "__main__":
asyncio.run(main())
Step 6: Sequential Multi-Agent Pipelines#
For workflows where agents should execute in a fixed order, ADK provides SequentialAgent:
from google.adk.agents import SequentialAgent, Agent
data_collector = Agent(
name="data_collector",
model="gemini-2.0-flash-exp",
instruction="Collect all relevant data points about the requested company.",
tools=[get_company_info, google_search],
)
analyst = Agent(
name="analyst",
model="gemini-2.0-flash-exp",
instruction="Analyze the collected data and identify trends.",
tools=[calculate_market_metrics],
)
reporter = Agent(
name="reporter",
model="gemini-2.0-flash-exp",
instruction="Format the analysis into a professional report.",
)
# Runs data_collector → analyst → reporter in sequence
pipeline = SequentialAgent(
name="research_pipeline",
sub_agents=[data_collector, analyst, reporter],
description="Full research pipeline: collect → analyze → report",
)
What's Next#
You have built a working Google ADK multi-agent system with custom tools and the built-in Google Search integration. Recommended next steps:
- Explore the directory: See the full Google ADK capabilities overview for deployment options
- Compare frameworks: Read the OpenAI Agents SDK vs LangChain comparison to see how ADK fits in the landscape
- Learn agent patterns: Study the ReAct reasoning pattern that Gemini uses for tool selection
- Try LangChain: Explore building an AI agent with LangChain for a different perspective on orchestration
- MCP integration: Learn how to connect your agent to MCP servers to expand tool availability
Frequently Asked Questions#
What Gemini models does ADK support?
ADK officially supports gemini-2.0-flash-exp, gemini-1.5-pro, gemini-1.5-flash, and the latest gemini-2.0-pro variants. You can also use any Vertex AI model including third-party models available on Model Garden (Claude, Llama, etc.) by using the LiteLlm wrapper.
How does ADK handle agent state between turns?
ADK uses a session service abstraction. InMemorySessionService is suitable for development and single-server deployments. For production, use VertexAiSessionService which persists session state in Google Cloud, enabling stateful agents at scale.
Can I deploy ADK agents to Google Cloud?
Yes. ADK integrates natively with Vertex AI Agent Engine, Google's managed runtime for deploying agents. Run adk deploy cloud_run to deploy as a Cloud Run service, or use adk deploy agent_engine for the fully managed option with built-in scaling and monitoring.
What is the difference between sub-agents and tools?
Tools return structured data that the parent agent reasons over. Sub-agents are full agents with their own model, instructions, and tools — the parent delegates an entire reasoning task to them. Use tools for data retrieval; use sub-agents for complex, multi-step subtasks that benefit from a specialized system prompt.
Does ADK support streaming responses?
Yes. The Runner.run_async() method yields events as they are generated, including partial text tokens. You can detect streaming content by checking event.is_partial() in the event loop.