Google's new agent framework, the Agent Development Kit (ADK), is rapidly gaining popularity. This comprehensive guide will take you from beginner to expert, empowering you to build your own AI agents, automate workflows, and integrate AI agents into your applications.

To help you master ADK as quickly as possible, we've created over 10 different examples that we're going to walk through in this article. We'll start with the absolute basics of building an individual agent and gradually add in more advanced features until you're building multi-agent workflows with tool callings and much more.

This guide is designed to be as beginner-friendly as possible, walking through every example step-by-step so you can see just how easy it is to create AI agents with ADK.

What You Will Learn

Here are the numerous examples we'll be building together today. As promised, we'll start with the basics and gradually add complexity and features until you're building some impressive multi-agent workflows.

1. Your First Agent: We'll start by creating a single agent to understand the core principles of creating agents inside ADK.
2. Adding Tools: You'll learn how to add tools to provide more functionality to your agents and access some of the pre-built tools that Google provides.
3. Integrating Other Models: Discover how to bring in other models to ADK, such as those from OpenAI and Anthropic, so you're not just limited to Gemini.
4. Structured Outputs: We'll ensure our agents produce specific JSON structures, which is crucial for passing data to other APIs and tools.
5. Session and Memory: Learn how to give your agents memory to remember things between different conversations.
6. Saving Data: You'll see how to make agents save their session and memory, so they retain information even after the application restarts, introducing database functionality.
7. Multi-Agent Solutions: Things get exciting as we start creating solutions where multiple agents work together.
8. Session and Memory in Multi-Agent Systems: We'll add session and memory to our multi-agent solutions so they can remember information as they collaborate.
9. Callbacks: Explore how to use callbacks to control every part of the agent lifecycle—before, during, and after they run.
10. Sequential Workflows: We'll start with sequential agents, ensuring they work in a specific order (e.g., Agent 1, then 2, then 3).
11. Parallel Workflows: Learn how to make agents work in parallel on a task, combining their results when finished.
12. Looping Agents: Finally, you'll see how to add loops, allowing agents to work continuously until they achieve a desired output.

After going through these examples, you'll go from a complete beginner to an absolute pro. Let's dive into our first example of building your first agent with ADK.

Example 1: Building Your First Single Agent

Welcome to the first example, where we'll focus on building and running your first single agent. We'll walk through five steps together.

The 5 Key Steps: 1. Core Agent Attributes: Understand the properties that make your agent work. 2. Folder Structure: Learn the required format for organizing your agent files. 3. Installing Dependencies: Get your environment set up to run the agents. 4. Getting an API Key: Access and download the necessary API key. 5. Running Your Agent: Kick things off and start interacting with your agent.

Let's get started.

Core Components of an ADK Agent

When creating your first agent in ADK, you need to understand its core components.

• Root Agent: Every ADK project must have at least one root agent. This is the entry point for all requests sent to your agents.
• Name: This property identifies the agent. When the agent runs, this name will appear to show who is generating the results. The agent's name must match the folder name in the file structure (e.g., greeting-agent for a folder named greeting-agent). If they don't match, ADK will throw an error.
• Model: You need to specify a model for your agent. While you can use models from any framework (like Claude or OpenAI), the easiest to use are the Gemini models. For this tutorial, we'll use gemini-1.5-flash. You can explore other available Google models on their model dashboard, which includes powerful options like gemini-1.5-pro and models with multimodal features.
• Description: This property becomes more important in multi-agent solutions. The root agent uses the description to determine which sub-agent is best suited for a given task. It's a high-level job overview for the agent.
• Instructions: This is the most critical property. These are the specific instructions telling the agent what to do and how to do it. As we progress, you'll see how we can add complex instructions that the model can handle with ease.

Folder Structure for ADK Agents

ADK requires a specific folder structure to work correctly.

• Agent Folders: Each agent should be in its own folder.
• __init__.py file: This file tells Python that the folder contains important information. For ADK, it points to the agent that needs to be imported. For example, from .agent import greeting_agent tells ADK to look for the greeting_agent in the agent.py file within the current folder.
• .env file: This file stores your environment variables, like API keys. You only need one .env file, and it should be located in your root agent's folder.
• agent.py file: This file contains the agent's definition. Remember, the agent's name must match the folder name.

Installing Dependencies

To run the agents in this guide, you'll need to install the necessary dependencies. A requirements.txt file is provided, which lists all the packages to install, with the most important one being google-adk.

To create a clean environment for this project, follow these steps:

1. Create a virtual environment: bash python -m venv .venv
2. Activate the environment:
   • On macOS/Linux: bash source .venv/bin/activate
   • On Windows: bash .venv\Scripts\activate
3. Install the dependencies: bash pip install -r requirements.txt

Accessing Your API Key

To run the agents, you'll need a Google Cloud API key.

1. Create a Google Cloud account and project.
2. Navigate to the Google AI Studio to create an API key associated with your project.
3. Copy the generated API key and paste it into the .env file in your root agent's folder.

Running Your First Agent

Now, let's run the agent and see it in action.

1. Navigate to the agent's directory in your terminal.
2. Use the ADK CLI tool. The command adk web will spin up a user-friendly web interface to chat with your agents.

Once the server is running, you can open the provided URL in your browser. You'll see an interface where you can select your agent and start a conversation. For our greeting-agent, if you give it the instruction "You are a helpful assistant that greets the user, asks the user's name, and greets them by their name," it will follow these steps when you interact with it.

The web interface also provides valuable debugging tools, allowing you to inspect events, state, and sessions in real-time, which is one of the most powerful features of ADK.

You are now proficient in creating an agent, understanding its properties and folder structure, obtaining API keys, and running it. Next, we'll explore how to add tools to enhance your agents' capabilities.

Example 2: Adding Tools to Your Agents

In this section, we'll look at adding tools to give your agents additional functionality.

Types of Tools in ADK

ADK is flexible and supports three main types of tools:

1. Function Calling Tools: This is the most common type. You create a Python function (e.g., to get the weather or look up stock prices) and pass it to your agent.
2. Built-in Tools: Google provides several pre-built tools, such as Google Search, Code Execution, and RAG (Retrieval-Augmented Generation). Note: These tools only work with Gemini models.
3. Third-Party Tools: You can integrate tools from other frameworks like LangChain or CrewAI, making ADK highly extensible.

Adding Tools to Your Agent

Adding a tool is straightforward. In your agent.py file, you add a tools property, which is a list of the tools you want the agent to use.

For example, to use the built-in Google Search tool, you would add it to the list: python tools=[google_search.GoogleSearch()] Important Limitation: You can only use one built-in tool at a time per agent.

To create a custom Python tool, you define a function with a docstring that explains what the function does. The agent uses this docstring to determine when to call the function.

def get_current_time() -> dict:
    """Fetches the current time."""
    # ... implementation ...
    return {"current_time": "10:30 AM"}

Best Practices for Custom Tools: - Return Detailed Dictionaries: Always return results in a dictionary with descriptive keys. This helps the agent understand the context of the returned data. - Avoid Default Parameters: ADK does not currently support default values for function parameters.

Limitation: You cannot mix built-in tools and custom tools in the same agent.

Running an Agent with Tools

When you run an agent with a tool like Google Search, you can ask it questions that require external information, like "What's the latest news about Tesla?" The agent will use the tool to search the internet and provide a summarized answer. The web UI will show the tool call event, allowing you to inspect the query and the results.

Similarly, if you provide a custom get_current_time tool, asking "What is the current time?" will trigger your custom function, and the agent will return the formatted time.

You've now leveled up as an ADK developer. Next, we'll learn how to integrate models from other providers like OpenAI and Claude.

Example 3: Connecting to Other Models (OpenAI, Claude)

This section explains how to connect your ADK agents to external models using LightLLM and OpenRouter.

• LightLLM: A free library that simplifies interfacing with various model providers like OpenAI, Claude, and Llama. ADK has built-in support for LightLLM.
• OpenRouter: A service that allows you to purchase credits and use a single API key to access models from multiple providers.

Configuration Steps: 1. Get an OpenRouter API Key: Sign up for OpenRouter, add credits, and create an API key. 2. Add the Key to .env: Store your OpenRouter API key in your project's .env file. 3. Configure the Agent: In your agent.py, import LightLLM from google_adk.models. Then, define your model by specifying the provider (openrouter), the model family (openai), and the specific model name (openai/gpt-4o-mini).

from google_adk.models import LightLLM
import os

model = LightLLM(
    model='openrouter/openai/gpt-4o-mini',
    api_key=os.environ.get("OPEN_ROUTER_API_KEY")
)

Now, your agent will use the specified OpenAI model instead of Gemini to process requests, demonstrating the flexibility of ADK's architecture.

Example 4: Generating Structured Outputs

Ensuring agents produce data in a specific format is crucial for building robust workflows. ADK provides a powerful way to enforce structured outputs.

Using output_schema

The primary method is the output_schema property. You define a class (using Pydantic's BaseModel) that represents the desired JSON structure, and the agent will format its output to match this schema.

For instance, to create an agent that generates an email with a subject and body: ```python from pydantic import BaseModel

class EmailContent(BaseModel): subject: str body: str

In your agent definition

output_schema=EmailContent ``` Critical Rule: For best results, you must also instruct the agent in its prompt to return JSON matching the defined structure. This greatly increases the reliability of the output.

Constraint: You cannot use output_schema when the agent is also using tools or transferring information to other agents.

Saving Structured Output to State with output_key

You can use the output_key property to save the structured output directly to the agent's state. This makes the data easily accessible to other agents or parts of your application.

# In your agent definition
output_key="generated_email"

When the agent runs, the generated email object will be saved in the state under the key generated_email.

Example 5: Understanding Session, State, and Runners

These three components are the core engine of ADK agents.

• Session: A session is a stateful chat history. It contains two main pieces of information:
  • State: A dictionary for storing arbitrary data (e.g., username, preferences).
  • Events: A list of all interactions, including user messages, tool calls, and agent responses.
• Runner: The runner connects everything. It takes a collection of agents and a session, manages the entire lifecycle of a request, and generates a response.

When you run adk web, it handles the creation and management of sessions and runners for you. However, to integrate agents into your own applications, you need to manage these components yourself. This involves creating a session service (in-memory, database, or Vertex AI), defining an initial state, creating a session, and then passing the agent and session service to a runner.

Example 6: Storing Sessions in a Database

To persist conversations, you can store sessions in a local database. Instead of using the InMemorySessionService, you use the DatabaseSessionService and provide a path to a SQLite database file.

This allows your application to retrieve past conversations. When a user interacts with the agent, you can list existing sessions for that user and either resume a previous conversation or create a new one. This is essential for building applications where context and history matter.

Example 7: Your First Multi-Agent System

Multi-agent systems in ADK are different from frameworks like CrewAI. ADK focuses on delegation.

• How it Works: A root agent (the manager) receives a request. It examines the descriptions of its sub-agents to find the best one for the task. It then delegates the entire responsibility to that sub-agent, which handles the request and generates the final response.
• Limitation on Built-in Tools: Sub-agents cannot directly use built-in tools like Google Search.
• Workaround (agent_as_tool): To use a built-in tool in a sub-agent, you must wrap that agent as a tool using agent_as_tool. In this case, the parent agent calls the child agent like a regular tool, and the child's result is passed back to the parent to formulate the final response.

Example 8: Multi-Agent Systems with Shared State

This is where multi-agent systems truly shine. By sharing state, agents can collaborate more intelligently. For example, a customer service system could have:

• A Sales Agent that updates the state when a course is purchased.
• A Course Support Agent that checks the state to see if a user has purchased a course before providing support.
• An Order Agent that checks the state to process refunds and updates it accordingly.

Each agent's behavior is influenced by the shared state, allowing for complex, dynamic, and context-aware interactions.

Example 9: Mastering Callbacks

Callbacks allow you to control every part of the agent lifecycle. There are six types:

1. before_agent_callback: Triggered before any logic runs. Ideal for setting up resources or hydrating state (e.g., fetching user data).
2. after_agent_callback: Runs after the agent is finished. Useful for logging or post-execution validation.
3. before_model_callback: Triggered before sending a request to the LLM. Can be used to add guardrails or modify the request.
4. after_model_callback: Runs after receiving a response from the LLM. Allows you to reformat or censor the response.
5. before_tool_callback: Triggered before a tool is called. Useful for inspecting arguments or performing authorization checks.
6. after_tool_callback: Runs after a tool returns a result. Allows you to modify the tool's output before the agent sees it.

Example 10: Sequential Workflows

A sequential workflow ensures that agents execute in a specific, predefined order. This is useful when one agent's output is a necessary input for the next.

For example, a lead qualification pipeline could have: 1. Lead Validator Agent: Checks if the lead information is complete. 2. Lead Scorer Agent: Scores the validated lead based on certain criteria. 3. Recommendation Agent: Suggests next steps based on the score.

Each agent saves its result to the shared state, which the next agent in the sequence then accesses.

Example 11: Parallel Workflows

Parallel workflows are designed for speed. Multiple agents work on different tasks simultaneously. This is ideal when tasks are independent and can be performed at the same time.

For instance, a system monitoring agent could have: - A CPU Agent checking CPU usage. - A Memory Agent checking RAM usage. - A Disk Agent checking storage space.

These three agents run in parallel. A final Synthesizer Agent can then take the results saved to state by the parallel agents and combine them into a single, well-formatted report.

Example 12: Loop Workflows

Loop agents are one of the most powerful features in ADK, allowing agents to iterate on a problem until a condition is met. This is similar to the ReAct (Reason and Act) pattern.

A loop agent will continue to run until either: - A maximum number of iterations is reached. - A specific condition is met, and a special exit_loop function is called.

For example, you could build a LinkedIn post generator: 1. Initial Post Generator: Creates a draft. 2. Loop (Reviewer & Refiner): - Post Reviewer Agent: Checks the draft against criteria (e.g., character count, tone). If it fails, it provides feedback. If it passes, it calls exit_loop. - Post Refiner Agent: Takes the feedback and improves the post.

The loop continues, with the agents reviewing and refining the post, until the reviewer is satisfied and exits the loop, resulting in a polished final output.