Google ADK Tutorial: Build Your First AI Agent in Python

Key Insights

Google ADK is a code-first, open-source framework for building, debugging and deploying AI agents in Python, TypeScript, Go, Java and Kotlin. It is optimised for Gemini but supports other models through connectors such as LiteLLM, Ollama and vLLM.
ADK Python 2.0 is now the default install. It became generally available on 19 May 2026 and moved ADK to a graph-based execution engine. Use pip install “google-adk~=1.0” only if you must follow older 1.x code.
A working agent needs only a root_agent defined in agent.py. Agent is an alias of LlmAgent, and a name, model and instruction are enough to start testing in the adk web development UI.
Python functions become tools automatically. ADK wraps each function in tools=[…] as a FunctionTool, using its docstring and type hints as the schema. Google recommends returning a dictionary with a status key.
The Runner manages execution. It processes every event an agent yields and commits state through a SessionService. Sessions and state hold short-term context; a MemoryService stores long-term knowledge.
Orchestration has several options: LLM-driven delegation through sub_agents, Sequential, Parallel and Loop workflow agents, and ADK 2.0 graph workflows for explicit routing.
adk web is for development only. Production agents run on Agent Runtime (called Vertex AI Agent Engine until April 2026), Cloud Run or GKE, deployed with adk deploy.
Model IDs change quickly. The quickstart uses the gemini-flash-latest alias; production apps should pin a stable model ID and check Google’s deprecation schedule.
Reliability needs evaluation and guardrails: adk eval scores tool calls and responses, tracing exposes each step, and tool confirmations, callbacks and plugins limit risky actions.

Google’s Agent Development Kit (ADK) is an open-source framework for developing, orchestrating and deploying AI agents. Unlike a traditional chatbot that only replies to messages, an ADK agent can use tools, maintain context across turns and complete multi-step tasks.

The framework provides building blocks for agents, tools, sessions, workflows and multi-agent coordination. It is optimised for Gemini models and is available in Python, TypeScript, Go, Java and Kotlin.

This Google ADK tutorial explains the framework’s architecture, then guides you through building your first working agent in Python, adding a custom tool, connecting multiple agents and preparing for deployment.

Interactive tool · Generative AI roadmap

Your roadmap to becoming a Generative AI Engineer

See what you already know, what to learn next and how long the switch to a GenAI engineering role takes. Tap any step for what to study and build.

What's inside8 stages · 30 steps to job-ready

Python & engineering foundations
ML & deep learning essentials
How LLMs work
Prompting & building LLM apps
RAG & model customisation
Agents & tool use
Production, evaluation & safety
Portfolio & job readiness

Learn this Level up You have it Done

Stage 1 · Start here

Python & engineering foundations

Stage 2 · Core concepts

ML & deep learning essentials

Stage 3 · Understand the engine

How LLMs work

Stage 4 · Start shipping

Prompting & building LLM apps

Stage 5 · Make models useful

RAG & model customisation

Stage 6 · Automate workflows

Agents & tool use

Stage 7 · Make it reliable

Production, evaluation & safety

Stage 8 · Get hired

Portfolio & job readiness

Phase 1

Fine-tuned text classifier

Adapting a pre-trained transformer to a real task.

Fine-tune a small pre-trained transformer on a labelled dataset, evaluate it properly and compare it with a classic ML baseline.

Python
PyTorch
Hugging Face

Phase 2

Structured data extractor

Turning messy documents into clean JSON.

Use an LLM API with schema-validated outputs to extract fields from invoices or resumes, with a prompt test set to track accuracy.

Python
LLM API
JSON schema

Phase 3

Document Q&A assistant

Retrieval-augmented answers with citations.

Index a document collection in a vector database and build an assistant that answers questions with cited sources and a retrieval-quality report.

Python
LangChain
Vector DB

Phase 3

LoRA fine-tune of an open model

Customising a model when prompting isn't enough.

Fine-tune an open-weights model with LoRA on a narrow task and document when it beats prompting and RAG, and when it doesn't.

PyTorch
PEFT
Hugging Face

Phase 3

Reward model & preference tuning

Teaching a model what good looks like.

Train a small reward model on preference data and run a preference-tuning loop, with a write-up of what changed.

PyTorch
TRL

Phase 3

Multimodal image search

Finding images from plain-language descriptions.

Embed images and text in a shared space and build a search app that retrieves photos from a description.

CLIP
Vector DB

Phase 4

Tool-using research agent

An agent that plans, acts and asks for approval.

Build a LangGraph agent that searches, reads and summarises sources, calls tools through an MCP server and pauses for human approval.

LangGraph
MCP
Python

Phase 4

Deployed GenAI service

From notebook to a monitored production API.

Containerise an LLM app, deploy it on a cloud platform with CI/CD, and add tracing plus a cost and latency dashboard.

Docker
FastAPI
Cloud

Phase 4

Eval harness with guardrails

Proving your AI app works, and stays safe.

Create a 50-case evaluation set, automate scoring on every change, and add input and output guardrails against prompt injection and PII leaks.

Evals
Guardrails
Python

Capstone

Domain AI agent capstone

A client-ready agent for a real industry problem.

Pick a domain such as healthcare, fintech or edtech and ship an agent that combines retrieval, tools, evals and guardrails, with a public demo and write-up.

RAG
Agents
Deployment

GenAI glossary 17 terms

Tap a term to see what it means. You will hear these in every GenAI interview.

IIT Delhi CEP × Varsity

Close your gaps with a structured programme

The Certificate Programme in Generative AI from CEP, IIT Delhi covers transformers, fine-tuning, RAG, agents and responsible AI through live weekend classes and hands-on projects.

6 months
Live online
Weekend classes

Enquire about the programme View programme details

How does Google ADK Work?

Google ADK provides the components needed to create AI agents that understand instructions, use tools and coordinate tasks. It manages agent execution through an organised runtime that supports everything from a simple assistant to a multi-agent application. The subsections below cover agents, the kit and the execution loop.

Understanding AI Agents

An AI agent is a system that interprets instructions, decides what action to take and uses tools to complete tasks. A traditional chatbot maps each message to a reply, while an agent can fetch data or run a function mid-task and continue with the result. This guide on how AI agents work covers the concept in depth.

ADK agents rely on five core capabilities. Each one maps to a framework feature you will use later in this tutorial:

Understanding user instructions written in natural language.
Reasoning about the next action, such as answering or calling a tool.
Calling external tools, from Python functions to third-party APIs.
Maintaining conversational context across turns through sessions.
Completing multi-step tasks by chaining tool calls or delegating to other agents.

What is the Agent Development Kit?

ADK is a framework of reusable building blocks for AI agents. You define an agent’s instructions, model, tools and behaviour in code, and ADK handles model requests, tool execution, conversation storage and routing. The official ADK documentation presents it as a way to build, debug and deploy reliable agents.

The same primitives support individual agents and coordinated multi-agent systems. Without a framework, you would write your own tool-calling loop, state store and test harness. ADK ships these with a development UI, an evaluation command and deployment tooling.

How does an ADK Agent Execute a Task?

A task starts when a user sends a request. ADK passes the message, the agent’s instruction and the available tool definitions to the model, which either answers directly or returns a function call: a structured request to run a named tool with specific arguments.

ADK runs the tool and returns the result to the model, which uses it to generate the final response or calls another tool. Throughout this process, a runtime component called the Runner manages execution and records every step as an event in the session.

Key point: Google ADK helps developers build agents that can move beyond text generation by connecting model reasoning with tools and executable workflows.

What are the Core Components of Google ADK?

ADK’s core components are the building blocks that determine how an agent behaves, interacts with users and executes tasks. Each plays a distinct role at runtime. For a framework-neutral view of these layers, see this overview of AI agent architecture.

Agents

An agent is ADK’s main unit of work. It combines a model, an instruction that defines its role and optional tools, then lets the model decide whether to reply, call a tool or hand the task to another agent. In Python, the key class is LlmAgent, which the ADK docs on LLM agents note is often aliased as Agent.

Tools

Tools are functions or external capabilities that an agent can call to retrieve information or perform actions, such as searching for information, calculating values or retrieving weather data. Developers can write custom Python function tools, load tools from Model Context Protocol (MCP) servers, generate them from OpenAPI specifications or wrap another agent with AgentTool.

Sessions and State

A session maintains the context of one conversation by storing its event history: every message, tool call and response. State is a key-value store inside the session for data the agent needs during execution, such as a user preference or an intermediate result. Both are essential for multi-turn conversations.

Conversation history is short-term. Longer-term memory is separate: ADK’s session, state and memory guide describes it as a searchable archive across past conversations, managed by a MemoryService.

Runners and Runtime

The Runner manages agent execution for each user request. It adds the query to the session, starts the agent and processes every event the agent yields, committing state changes through the SessionService, as the ADK event loop documentation explains. Commands such as adk web and adk run create this runtime for you during testing.

Multi-Agent Systems

Multiple specialised agents can work together when a parent agent, often called a coordinator, lists them as sub_agents and delegates tasks based on their descriptions. Delegation divides complex workflows into smaller responsibilities. ADK supports several organisation patterns, including LLM-driven delegation, workflow agents and, in ADK 2.0, graph-based and collaborative workflows.

Key point: Agents define behaviour, tools provide capabilities, sessions maintain context, and runners manage execution.

What are the Different Types of Agents in Google ADK?

ADK supports different agent patterns depending on the complexity and structure of a task. You can use a single LLM agent or combine specialised agents under workflow agents, which the docs also call template workflows. Workflow agents are deterministic: they run sub-agents by fixed logic, without a model choosing the order.

The ADK workflow agents guide notes that ADK 2.0 for Python and Go supersedes these templates with more flexible graph-based and dynamic workflows. The templates still run in Python, but consider graphs for new projects that need branching.

LLM Agents

LLM agents use a language model to interpret instructions and decide which actions to take. Developers configure the model, the instruction and the tools, and the agent chooses when to call each tool. They suit flexible tasks that require reasoning and tool selection, such as a research assistant.

Sequential Agents

A SequentialAgent runs its sub-agents in a defined order. Sub-agents share session state, so one step can save its output with output_key and the next can read it through a {key} placeholder. A typical example is a research → summarisation → report generation pipeline.

Parallel Agents

A ParallelAgent runs independent sub-agents at the same time. When tasks do not depend on each other, this can reduce overall workflow time, because the slowest branch, not the sum of all branches, sets the pace. For example, separate agents can research different topics, and a later agent merges their findings.

Loop Agents

A LoopAgent repeats its sub-agents until a condition is met or an iteration limit is reached, which suits iterative tasks such as reviewing and improving a draft. Define clear stopping conditions: the ADK loop agent docs combine max_iterations with a tool that sets tool_context.actions.escalate = True when the work is done.

The table below compares the four agent types by execution pattern and typical use case. Use it as a quick reference when structuring a new workflow.

Agent type	Execution pattern	Example use case
LLM Agent	Model-driven decisions	Research assistant
Sequential Agent	Steps run in order	Research and report generation
Parallel Agent	Independent tasks run together	Multi-source research
Loop Agent	Repeated execution	Iterative content review

Key point: Choose an agent pattern based on task dependencies. A simple task may need one LLM agent, while complex workflows may benefit from multiple coordinated agents.

How to Build your First Agent Using Google ADK

This tutorial shows how to create a simple Python-based AI agent using Google ADK and a Gemini model. It covers agent configuration, execution and interaction with the user. Every command follows the official ADK Python quickstart, so you can cross-check each step.

Step 1: Check the Prerequisites

ADK needs a supported Python version and model credentials before it can run. Without credentials, the agent loads but fails on the first prompt because it cannot reach the model. Make sure you have the following before you start:

Python 3.10 or later, as listed in the official quickstart, plus pip.
A Gemini API key from Google AI Studio, or a Google Cloud project with Gemini access.
Basic Python knowledge, including functions, imports and type hints.
A terminal and a code editor, such as VS Code.

Requirements can change between releases, so check the quickstart before you begin.

Step 2: Install Google ADK

ADK for Python is distributed as the google-adk package. Install it in a virtual environment to avoid dependency conflicts with other projects; this guide to creating a Python virtual environment explains the basics. Run these commands from an empty folder such as adk_tutorial:

Windows users activate the environment with .venv\Scripts\activate.bat in Command Prompt or .venv\Scripts\Activate.ps1 in PowerShell, and may need python or py instead of python3.

python3 -m venv .venv

source .venv/bin/activate # macOS / Linux

pip install google-adk

This installs ADK 2.x, generally available since 19 May 2026, according to the ADK 2.0 release page. Install “google-adk~=1.0” only for older 1.x code, and check the official documentation for current installation requirements.

Step 3: Set Up API Authentication

The agent connects to a supported Gemini model through an API key or Google Cloud credentials stored in environment variables. Never hardcode keys in source files, where they can leak through version control. Create a key in Google AI Studio and set it for your terminal session:

export GOOGLE_API_KEY="YOUR_API_KEY" # macOS / Linux

# $env:GOOGLE_API_KEY="YOUR_API_KEY" # Windows PowerShell

# set GOOGLE_API_KEY=YOUR_API_KEY # Windows Command Prompt

You will also save the key in the agent’s .env file in Step 4. The authentication method depends on your model provider and deployment environment; Gemini on Google Cloud, for example, uses project and location variables instead of an API key.

Step 4: Create the Agent Project

ADK expects each agent to live in its own Python package folder, and the adk create command scaffolds one for you with the required files. Run it from your project folder, because adk web later looks for agent folders inside the directory where it starts:

adk create my_agent

The command creates the following structure inside your project folder:

adk_tutorial/ # project folder: run adk commands from here

├── .venv/

└── my_agent/ # agent package created by adk create

├── __init__.py # imports agent.py so ADK can find root_agent

├── agent.py # agent definition

└── .env # API keys or project IDs

Add GOOGLE_API_KEY=”YOUR_API_KEY” to my_agent/.env. Keep the framework’s conventions: __init__.py imports the agent module, and agent.py defines root_agent, which the quickstart calls the only required element of an ADK agent.

Step 5: Define Your First Agent

Replace the contents of my_agent/agent.py with a simple assistant that answers general questions. The code imports ADK’s agent class and configures four settings: a name, a model, a description and an instruction. Together, these define what the agent is and how it behaves:

The name identifies the agent, the model selects Gemini, the description tells other agents what it does and the instruction sets its behaviour. Because Agent is an alias, from google.adk.agents import LlmAgent works too.

from google.adk.agents.llm_agent import Agent # Agent is an alias for LlmAgent

root_agent = Agent(

name="first_agent",

model="gemini-flash-latest",

description="A simple assistant for answering questions.",

instruction=(

"You are a helpful assistant. "

"Answer user questions clearly and concisely. "

"If you are not sure about an answer, say so."

),

)

The gemini-flash-latest alias matches the official quickstart but always points to the newest Flash model. For production, pin a stable ID from the Gemini models page. Older IDs such as gemini-2.5-flash appear on the Gemini deprecations page, so check their status first.

Step 6: Run Your Agent

ADK’s browser-based development interface lets you chat with agents, inspect their responses and review each step of execution. Launch it with the adk web command from the project folder that contains my_agent/, not from inside the agent folder itself:

Open http://localhost:8000, select my_agent in the top-left menu and enter a prompt. Use adk run my_agent for a terminal chat instead. The interface helps you test behaviour before deployment, but the quickstart states that it is not meant for production.

adk web

Step 7: Test the Agent

Testing confirms that the agent follows its instruction and that the model connection works end to end. Start with simple prompts that match the agent’s purpose, then compare each answer with the instruction you wrote. Try these three prompts first:

“Explain what an AI agent is.”
“What is the difference between an AI agent and a chatbot?”
“Explain Google ADK in simple terms.”

Check each reply against the instruction: is it concise, and does it admit uncertainty instead of guessing? Then open the turn’s events in the dev UI, where the execution trace shows the model request, the model response and any tool calls.

Key point: A basic ADK agent can be created with a small amount of Python code, but production-ready agents require additional tool integration, testing, and deployment configuration.

How to Add Tools to a Google ADK Agent

Tools extend an agent’s capabilities beyond generating text. By connecting Python functions or external services, developers can allow agents to retrieve information, perform calculations and execute specific tasks. This section adds a calculation tool to an agent and shows how to confirm that the model actually called it.

What are Custom Tools?

A custom tool is a Python function exposed to an agent. When you add it to the tools list, ADK wraps it as a FunctionTool and builds a schema from its name, docstring, parameters and type hints. The model reads that schema to decide when to invoke the tool, so clear descriptions and parameters matter.

The ADK function tools guide recommends few parameters, simple types and a dictionary return value with a status key.

Create a Custom Python Tool

This function calculates the square of a number, validates its input and returns a dictionary, following ADK’s documented practice for function tools. Register it by passing the function itself, without parentheses, in the agent’s tools list so ADK can build its schema:

from google.adk.agents.llm_agent import Agent

def calculate_square(number: float) -> dict:

"""Calculates the square of a number.

Args:

number: The number to square.

Returns:

A dictionary with the status and the squared value.

"""

if not isinstance(number, (int, float)):

        return {"status": "error", "error_message": "Input must be a number."}
    return {"status": "success", "result": number * number}
root_agent = Agent(
    name="calculator_agent",
    model="gemini-flash-latest",

description="An agent that can perform simple calculations.",

instruction=(

"You help users with arithmetic. When the user asks for the square "

"of a number, call the calculate_square tool and explain the result. "

"Do not calculate squares yourself."

),

tools=[calculate_square],

)

The instruction states when to use the tool, which ADK’s docs recommend over simply listing it. Save the file and restart adk web if it is already running.

Test Tool Calling

Ask the agent, “What is the square of 12?” and open the turn’s events in the dev UI. You should see a function call with number: 12 and a function response containing 144. The sequence follows five steps:

The user sends a request.
The agent identifies the need for a calculation.
The agent calls the Python function.
The function returns a result.
The agent explains the result to the user.

Validate tool inputs and outputs, even in simple functions. A readable error_message lets the agent recover from unexpected values instead of failing.

Key point: Tools let ADK agents interact with external functionality, making them more useful than standalone conversational models.

How to Build Multi-Agent Workflows with Google ADK

Multi-agent workflows divide complex tasks among specialised agents. A coordinating agent can delegate work to other agents and combine their results, while a shared session carries data between them. The example below builds a two-agent research team and explains when each workflow pattern fits best.

Create Specialised Agents

Give each agent one clearly defined responsibility, because focused instructions make agent behaviour easier to test and debug. In this example, a research agent gathers facts about a topic, and a summarisation agent turns those facts into a short, readable paragraph:

from google.adk.agents.llm_agent import Agent

MODEL = "gemini-flash-latest"

research_agent = Agent(

name="research_agent",

model=MODEL,

description="Finds key facts about a topic the user names.",

instruction="List the most important facts about the user's topic as short bullet points.",

output_key="research_notes",

)

summary_agent = Agent(

name="summary_agent",

model=MODEL,

description="Turns research notes into a short, readable summary.",

instruction="Summarise these notes in one paragraph: {research_notes?}",

)

output_key saves the research agent’s reply to session state, and {research_notes?} inserts it into the summary agent’s instruction. The ? tells ADK to skip the placeholder if the value does not exist yet.

Connect Agents Using a Parent Agent

A parent agent coordinates sub-agents through delegation, meaning it hands each request to the specialist best suited to it. ADK shows the parent’s model every sub-agent’s name and description, and the model decides which specialist handles each request:

root_agent = Agent(

name="coordinator",

model=MODEL,

description="Routes research and summarisation requests.",

instruction=(

"Send fact-finding requests to research_agent and summarisation "

"requests to summary_agent. Do not answer research questions yourself."

),

sub_agents=[research_agent, summary_agent],

)

Agents pass outputs through the workflow via shared state. If every request should run research and then summary, use a fixed pipeline instead of the coordinator, because an agent instance can have only one parent:

from google.adk.agents import SequentialAgent

root_agent = SequentialAgent(name="research_pipeline", sub_agents=[research_agent, summary_agent])

ADK 2.0 can express the same order with the graph workflow syntax, Workflow(name=”research_pipeline”, edges=[(“START”, research_agent, summary_agent)]), and adds collaborative modes such as single_turn and task for sub-agents.

Choose the Right Workflow Pattern

Choose a pattern based on how the steps depend on each other, not on how sophisticated the design looks. The wrong choice either adds needless model calls or removes flexibility the task needs. Use these rules of thumb when designing a workflow:

Sequential execution when each step needs the previous output, such as research before summarisation.
Parallel execution when steps are independent, such as researching three competitors at once.
Loop-based execution for iterative tasks like draft, critique and revise, with max_iterations set.
LLM delegation when the next step depends on what the user asks.

Manage dependencies explicitly and prevent unnecessary agent calls. Every LLM agent adds model requests, so a step that needs no reasoning is better as a function tool or a code node in a graph.

Key point: Multi-agent systems are useful when tasks have distinct responsibilities, but unnecessary agent complexity can increase latency and cost.

How to Deploy a Google ADK Agent

Deployment makes an agent accessible beyond the local development environment, usually as an API that other applications call. ADK supports different deployment approaches depending on infrastructure and scalability requirements. Local testing and production deployment are separate stages, and this section covers both, along with authentication, permissions and monitoring.

Local Development and Testing

Local testing uses adk web, adk run or adk api_server to check tool execution, session behaviour and errors on your own machine, before any cloud resources are involved. Before deploying, test at least three kinds of input:

Normal prompts that match the agent’s purpose.
Edge cases, such as long inputs or follow-ups that depend on earlier turns.
Invalid inputs, such as text where a number is expected.

None of these commands deploys your agent. They run only on your machine.

Deploying to Google Cloud

The ADK deployment guide lists three Google Cloud targets: Agent Runtime (called Vertex AI Agent Engine until April 2026), a fully managed service for agents; Cloud Run, for serverless containers; and GKE, for more control. This example deploys to Cloud Run and blocks unauthenticated access:

gcloud auth login

gcloud config set project YOUR_PROJECT_ID

adk deploy cloud_run --project=YOUR_PROJECT_ID --region=us-central1 my_agent \

-- --no-allow-unauthenticated

Use adk deploy agent_engine for Agent Runtime or adk deploy gke for GKE. By default, the Cloud Run deployment includes the API server but not the development UI.

On Google Cloud, you usually replace the AI Studio key with project credentials. ADK’s Gemini model docs set GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION and GOOGLE_GENAI_USE_ENTERPRISE=True. Grant the service account only the permissions it needs, and keep secrets in a secrets manager.

Monitoring and Maintaining Agents

Agent execution should be monitored after deployment, because model updates, untested user questions and failing external APIs can all change behaviour over time. Monitoring surfaces these problems before users report them. Track these signals from day one:

Latency, split into model time and tool time.
Token usage, which drives cost.
Tool errors, including timeouts and failed authentication.
Task completion rates, meaning how often requests are resolved.

ADK can export traces to Google Cloud Trace, where call_llm and execute_tool spans show each step. Evaluate responses regularly and update instructions as requirements change.

Key point: Deployment is not the final step. Agents require monitoring, evaluation, and maintenance to remain reliable.

Google ADK vs Other AI Agent Frameworks

Developers can choose from several frameworks for building AI agents. This comparison looks at ecosystem, workflow orchestration, model flexibility and deployment options. No framework suits every project, so the right choice depends on your stack and requirements. The subsections below compare ADK with three widely used alternatives.

If you’re exploring the broader ecosystem, check out our guide to top agentic AI frameworks, which compares popular frameworks and their approaches to building AI agents.

Google ADK vs LangChain

LangChain is a broad ecosystem for LLM application development. Its long chain documentation describes create_agent, a configurable agent harness built on LangGraph, with a standard model interface across providers. ADK focuses more narrowly on agent development and orchestration, with built-in evaluation and direct Google Cloud deployment. The choice depends on your application and existing stack.

Google ADK vs CrewAI

CrewAI takes a role-based multi-agent approach. Its CrewAI documentation describes Crews of role-playing agents that collaborate and delegate tasks, plus Flows for event-driven control. ADK organises agents as parents and sub-agents, routed by descriptions, workflow agents or graphs, so development starts from agents and orchestration code rather than roles.

Google ADK vs Microsoft AutoGen

AutoGen focuses on multi-agent applications built around agent communication. Its GitHub repository now marks it as in maintenance mode and points new users to Microsoft Agent Framework, its successor. AutoGen connects to models such as OpenAI and Azure OpenAI through extensions, while ADK is Gemini-optimised but model-agnostic.

The table below summarises each framework’s primary focus and the projects it suits best. Treat it as a starting point, then test your shortlist against a real task.

Framework	Primary focus	Best suited for
Google ADK	Agent development and orchestration	Developers building agents in Google’s ecosystem
LangChain	LLM application development	Applications requiring broad integrations
CrewAI	Role-based multi-agent workflows	Collaborative agent teams
Microsoft AutoGen	Multi-agent applications	Agent communication and orchestration

Because AutoGen is in maintenance mode, its row mainly applies to existing projects.

Key point: Choose an agent framework based on model compatibility, orchestration needs, integrations, deployment environment, and team familiarity.

Common Mistakes to Avoid When Building Google ADK Agents

Building an agent involves more than connecting a model to a prompt. Developers must define clear instructions, control tool access, manage context and test execution behaviour. These five mistakes are common reasons a working demo fails with real users.

Writing Vague Agent Instructions

Unclear instructions produce inconsistent outputs, because the model fills gaps with its own assumptions. Define the agent’s role, responsibilities and boundaries instead. ADK’s documentation recommends stating the core task, persona, constraints and output format, and explaining when each tool should be used.

Giving Agents Too Many Tools

Every tool adds a description the model must read and choose between, so long tool lists make selection less reliable. Expose only the tools relevant to the agent’s purpose. For MCP servers, use the tool_filter parameter to load a subset, and move unrelated tools to specialised sub-agents.

Ignoring Session and State Management

Multi-turn applications need reliable context handling. Misspelt, overwritten or unsaved state keys leave the agent answering follow-ups with missing or outdated information. Use unique output_key names, and remember that in-memory services lose all data on restart, so choose persistent session storage for production.

Skipping Testing and Error Handling

Agents must be tested with normal, unexpected and invalid inputs, because model behaviour is not deterministic. Return readable errors when tools fail, and plan for model errors such as rate limits and timeouts. Inspect execution traces before deployment, and turn good sessions into adk eval test cases.

Overcomplicating Multi-Agent Workflows

Not every task requires multiple agents. Each delegation adds model calls, latency and another place where context can be lost. Start with one agent and a few tools, and add a sub-agent only when a responsibility is clearly separate or needs different tools.

Key point: Good agent design starts with a clear task, limited tool access, predictable workflows, and systematic testing.

Conclusion

Google ADK gives developers a code-first path from a few lines of Python to a deployed, observable agent. In this tutorial, you built an assistant, added a custom tool and connected specialised agents through delegation and workflow agents.

Before moving to advanced agent applications, make sure you understand sessions and state, test with realistic inputs and know which deployment target suits your project. This agentic AI roadmap can help you plan what to learn next.

If you want a structured programme in this area, Varsity by InterviewBit delivers the Advanced Certification in AI: From ML to Agentic AI, offered by the Continuing Education Programme (CEP), IIT Delhi. It runs from machine learning foundations to building AI agents, complementing the hands-on skills in this tutorial.

Frequently Asked Questions About Google ADK

How can you connect Google ADK agents to external APIs and third-party services?

Wrap the API call in a Python function tool, generate tools from an OpenAPI specification with OpenAPIToolset, or connect to an MCP server with McpToolset, which converts the server’s tools into ADK tools. Use tool_filter to expose only the MCP tools the agent needs.

What is the difference between Google ADK and Google Vertex AI Agent Builder?

ADK is the open-source framework you use to write agent code. Vertex AI Agent Builder was Google Cloud’s managed suite for deploying and governing agents. According to the Gemini Enterprise Agent Platform release notes, it became part of Agent Platform on 22 April 2026, and Agent Engine became Agent Runtime.

Can Google ADK agents use tools that require authentication?

Yes. The ADK tool authentication guide covers API keys, bearer tokens, OAuth2, OpenID Connect and service accounts. OpenAPI-based tools accept an auth_scheme and auth_credential, and for OAuth, ADK pauses for user consent before retrying the call. Store production tokens in a secrets manager.

How do you give a Google ADK agent access to a database?

Use MCP Toolbox for Databases, an open-source MCP server with ready-made toolsets for databases including BigQuery. You define the allowed queries in Toolbox and load them with the toolbox-core client. Prefer narrow, read-only queries over free-form SQL access.

How can you implement human approval in a Google ADK agent workflow?

Use tool confirmation. Wrapping a function as FunctionTool(my_tool, require_confirmation=True) pauses the call until someone approves it, and passing a function instead of True requires approval only in specific cases. The feature is marked experimental, so test it carefully before production.

What is the difference between session state and memory in Google ADK?

Session state holds data for the current conversation and is managed by a SessionService. Memory is a searchable archive that can span many past conversations, managed by a MemoryService and queried through tools such as load_memory. Use state for working data and memory for long-term recall.

How do you debug tool-calling failures in a Google ADK application?

Open the turn’s event trace in the dev UI to see whether the model requested the tool, which arguments it sent and what the function returned. If the tool is never called, improve its docstring and the agent’s instruction. For deployed agents, Cloud Trace execute_tool spans show where failures occur.

How can you evaluate the accuracy and reliability of AI agents built with Google ADK?

Save representative conversations as eval sets, define the expected tool calls and responses, and run adk eval. The ADK evaluation criteria include tool_trajectory_avg_score for tool calls and response_match_score, which uses ROUGE-1 similarity, plus rubric-based options for quality checks.

How do you manage API costs and token usage when building Google ADK agents?

Use the smallest model that handles each step well, keep instructions concise and cap loops with max_iterations. Set include_contents=’none’ for agents that do not need conversation history. ADK also supports context caching and context compaction, which summarises older session events.

Can Google ADK agents work with models from providers other than Google?

Yes. ADK is optimised for Gemini but model-agnostic. Its model documentation lists connectors such as LiteLlm for providers supported by LiteLLM, plus Ollama, vLLM and LiteRT-LM for self-hosted models. Check each model’s function-calling support before relying on tools.

How do you secure Google ADK agents against unauthorised tool calls and prompt injection?

Expose only the actions an agent needs and validate arguments inside each tool. ADK’s safety and security guide recommends before_tool_callback checks, plugins such as Gemini-as-a-Judge or Model Armor to screen inputs and outputs, and sandboxed code execution. Treat tool outputs as untrusted, since they can carry injected instructions.

When should developers use a single Google ADK agent instead of a multi-agent architecture?

Use a single agent when one instruction and a handful of tools can cover the task, as with most assistants and first projects. Move to multiple agents when responsibilities are clearly distinct, tool lists become too long for reliable selection or parts of the job need different models.