Lesson 1: Build your first agent with Google ADK

Sebastian Gomez

Jun 24, 2026

Updated: Jun 25, 2026

Lesson 1: Build your first agent with Google ADK

Welcome to the adventure of building your first AI news agent with Google's Agent Development Kit (ADK). In this lesson we lay the groundwork for an agent that can hold a conversation, connect to the real world, and deliver fresh information. Here's a clear walkthrough of the Lesson_1.ipynb notebook, with practical tips so you can move forward with confidence.

A note on model names. The Gemini ecosystem moves very fast and model identifiers change often, especially the ones tagged preview with a date. In this post I use concrete names as examples, but before you copy them, check the current list in the ADK and Gemini documentation and choose a stable (GA) model when one exists.

Overview

Anatomy of an agent: model plus instructions plus tools.
Setting up the environment and getting to know the ADK Web UI.
Adding real time search and trying out Gemini models.
Configuring agents with Python or with YAML.
Tuning instructions for consistent behavior.

1.1 Initial setup

ADK ships with the essential libraries (google-adk, CLI utilities, helpers). Even so, check your dependencies and isolate your environment with a virtualenv. If you're going to extend the demo, add your own requirements.txt to pin versions and avoid surprises.

1.2 Base structure of an ADK project

Generate the skeleton with the following command (code based project):

adk create app_01 --model gemini-2.5-flash --api_key $GOOGLE_API_KEY

This creates a minimal structure:

app_01/agent.py: the agent's logic.
.env: credentials and configuration.
__init__.py: clean imports.

Keep in mind that the model ID in the example is just a starting point; swap it for the one you need based on the current list.

1.3 Painless authentication

You can use a Gemini API key (Google AI Studio) or Vertex AI credentials.

With Google AI Studio, create a .env file inside app_01/:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=<your_api_key>

With Vertex AI, use the .env or environment variables:

GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_PROJECT=<project>
GOOGLE_CLOUD_LOCATION=<location>

Never publish your keys or commit your .env to GitHub.

1.4 Writing the first agent.py

With the %%writefile cell magic you can write the file straight from the notebook. The minimal agent defines:

A readable name (ai_news_agent).
A base model. For voice, you'll want a model compatible with the Gemini Live API.
Short instructions describing its role.

Tip: ADK is model agnostic; you can use Gemini, Claude, Ollama, or integrations via LiteLLM. Decide early whether you prioritize voice, multimodality, or latency, because that drives which model you pick.

1.5 Testing in the ADK Web UI

To chat with the agent you have two options.

From the agent's parent folder, run adk web and then select "app_01" in the menu. Or point straight at the app:

adk web --port 8000 app_01

Open the URL (http://localhost:8000). On Windows, if you see _make_subprocess_transport NotImplementedError, use adk web --no-reload. Stop the process with Ctrl-C.

The Web UI shows the trace (step by step) and allows real time voice interaction. For voice, use a model compatible with the Gemini Live API.

1.6 Adding the search tool

The model on its own doesn't know about recent news. To give it access to the web we add the google_search tool:

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

root_agent = Agent(
    name="ai_news_agent_simple",
    model="gemini-2.5-flash",
    instruction="Eres un asistente de noticias de IA. Usa Google Search para hallar información reciente.",
    tools=[google_search],
)

With this the agent queries the web, processes the results, and cites current sources. Keep two details in mind:

google_search is compatible with Gemini 2 and later models, so it works with the Gemini 2.5 models we use here.
If the response includes "Search suggestions", you must display them in your app (it's a requirement of the Grounding with Google Search policy). See the ADK documentation: docs/tools/built-in-tools.md and docs/grounding/google_search_grounding.md.

Later on you can explore other tools (code execution, databases, Workspace) depending on your use case.

1.7 Testing text models

The gemini-2.5-flash model prioritizes text and tends to respond faster when you don't need audio. You can create another app with the same code and change only the model. Experiment to balance cost, latency, and capabilities.

1.8 Declarative configuration with YAML

If you'd rather not write Python, use --type=config to generate root_agent.yaml with the same fields (name, model, instructions, tools):

name: ai_news_agent_yaml
model: gemini-2.5-flash
description: Agente que resume noticias recientes de IA.
instruction: Usa Google Search para encontrar y resumir novedades de IA.
tools:
  - name: google_search

Suggestion: document your decisions in comments. ADK validates the schema and will warn you if a key field is missing. More details in the agent configuration documentation.

1.9 Tuning advanced instructions

For consistent behavior, add clear rules:

A defined identity: the agent only covers AI news.
A refusal mechanism: exact text for out of scope requests.
Mandatory flows: use of google_search and source citations.
Context controls: define what counts as a valid question.

This pattern minimizes hallucinations and keeps the agent on purpose.

Best practices and next steps

Close old processes with pkill -f "adk web" to free up resources.
Document each variant (app_01 through app_05) with notes and results.
Repeat prompts with small variations to observe changes (output can vary due to stochasticity).
Define naming, folder, and versioning conventions right from the start.

3-point summary

An ADK agent is made of three pieces: a model, some instructions, and some tools. With that you already have a working conversational assistant.
With google_search the agent goes out to the web, processes results, and cites recent sources; remember to display the "Search suggestions" when they appear.
You can define the agent in Python or declaratively in YAML, and model names change fast, so it's worth always checking the current list.

Suggested exercises

Create your own agent with adk create, configure it with your GOOGLE_API_KEY, and test it in the Web UI.
Add the google_search tool and ask it for recent AI news; check that it shows the sources and the "Search suggestions".
Create a second app changing only the model (for example, a text one versus a voice one) and compare latency and answer quality.

Resources

ADK Quickstart: google.github.io/adk docs/get started/quickstart/
ADK Python: google.github.io/adk docs/get started/python/
Built in Tools (Google Search): google.github.io/adk docs/tools/built in tools/
Next lesson: Supercharge your agent with custom tools

This content is based on the course "Building Live Voice Agents with Google's ADK!" by DeepLearning.AI (learn.deeplearning.ai/courses/building live voice agents with googles adk/). This blog aims to bring the ADK material closer to the Spanish speaking audience.

That's all. I hope this lesson is useful to you and that you can apply it to a project you have in mind. Leave me a comment if it helped, if you want to add an opinion, or if you have any questions. And remember, if you liked it, you can also share it using the social links below. See you in the next lesson. Good luck.