🤖AI Agents Guide
TutorialsComparisonsReviewsExamplesIntegrationsUse CasesTemplatesGlossary
Get Started
🤖AI Agents Guide

Your comprehensive resource for understanding, building, and implementing AI Agents.

Learn

  • Tutorials
  • Glossary
  • Use Cases
  • Examples

Compare

  • Tool Comparisons
  • Reviews
  • Integrations
  • Templates

Company

  • About
  • Contact
  • Privacy Policy

© 2026 AI Agents Guide. All rights reserved.

Home/Tutorials/Build an AI Agent with Google ADK
intermediate32 min read

Build an AI Agent with Google ADK

A complete tutorial for building AI agents using Google Agent Development Kit (ADK) for Python, covering Gemini model integration, tool use, and constructing multi-agent systems with sequential and parallel pipelines.

Google-colored light trails representing data flow through an AI pipeline
Photo by Milad Fakurian on Unsplash
By AI Agents Guide Team•February 28, 2026

Table of Contents

  1. What You'll Learn
  2. Prerequisites
  3. Step 1: Project Setup
  4. Step 2: Define Custom Tools
  5. Step 3: Build the Agent
  6. Step 4: Test with the ADK Web UI
  7. Step 5: Run Programmatically with the Runner
  8. Step 6: Sequential Multi-Agent Pipelines
  9. What's Next
  10. Frequently Asked Questions
Developer writing Python code on a monitor for building intelligent agents
Photo by Clint Patterson on Unsplash

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 SequentialAgent and 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

Developer analyzing Python code on screen while building an AI agent pipeline

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.

Related Tutorials

How to Create a Meeting Scheduling AI Agent

Build an autonomous AI agent to handle meeting scheduling, calendar checks, and bookings intelligently. This step-by-step tutorial covers Python implementation with LangChain, Google Calendar integration, and advanced features like conflict resolution for efficient automation.

How to Manage Multiple AI Agents

Master managing multiple AI agents with this in-depth tutorial. Learn orchestration, state sharing, parallel execution, and scaling using LangGraph and custom tools. From basics to production-ready swarms for complex tasks.

How to Train an AI Agent on Your Own Data

Master training AI agents on custom data with three methods: context stuffing, RAG using vector databases, and fine-tuning. This beginner-to-advanced guide includes step-by-step code examples, pitfalls, and best practices to build knowledgeable agents for your specific needs.

← Back to All Tutorials