1. Introducción
En este codelab, crearás tu primer agente de IA paso a paso con el Kit de desarrollo de agentes (ADK) de Google y Gemini. Crearás un agente básico de redacción de blogs que planifica y escribe contenido, y mostrarás los conceptos básicos de razonamiento y acción.
Actividades
- Configura tu entorno de desarrollo para el ADK.
- Crea un sistema multiagente con un Planner y un Writer.
- Ejecuta el agente de forma local e interactúa con él a través de la IU web del ADK.
Requisitos
- Un navegador web, como Chrome
- Python 3.10 o una versión posterior instalado en tu máquina
- Una clave de API de Google AI Studio
Este codelab es para desarrolladores de todos los niveles, incluidos los principiantes.
Duración estimada: 30 minutos.
2. Guía visual: ¿Qué son los agentes de IA?
Antes de comenzar a crear, comprendamos rápidamente qué son los agentes de IA y los patrones comunes que siguen.
¿Qué es un agente de IA?
En el nivel más simple, un agente es un software que no solo responde, sino que también puede tomar decisiones y realizar acciones. En lugar de generar una sola respuesta como un chatbot tradicional, analiza tu solicitud, determina qué pasos seguir, tal vez llama a una API, ejecuta código, analiza el resultado y, luego, decide qué hacer a continuación.
Una de las explicaciones más claras proviene del documento de investigación ReAct: Synergizing Reasoning and Acting in Language Models. La idea de ese documento era simple, pero poderosa: los modelos de lenguaje no solo deben generar texto de una vez, sino que también pueden razonar paso a paso, realizar una acción como llamar a una herramienta o API, observar el resultado y, luego, decidir qué hacer a continuación.
Ese ciclo de razonamiento, acción, observación y ajuste es la base del funcionamiento de los agentes de IA modernos. Además, se alinea con la forma en que Google Cloud los define: sistemas con razonamiento, planificación y memoria, con suficiente autonomía para adaptarse y tomar decisiones en nombre del usuario.
Tres patrones de comportamiento del agente
No todos los agentes se comportan de la misma manera. Una forma útil de pensar en ellos es en tres patrones amplios:
- Agentes secuenciales: Se ejecutan paso a paso, como una línea de ensamblaje: paso 1, luego paso 2 y, después, paso 3. Son predecibles, pero rígidos.
- Agentes reactivos: Toman decisiones en el momento. Observan el estado actual y preguntan: “¿Qué debo hacer a continuación?”. Quizás la herramienta A una vez y la herramienta B la siguiente. Son flexibles, pero no planifican con anticipación.
- Agentes deliberativos o de planificación: Hacen una pausa para esbozar un plan y, luego, lo ejecutan. Piensa en reservar un viaje: no compras un vuelo al azar, sino que eliges fechas, hoteles, ordenas los pasos y, luego, los completas.
¿Cuál de estos es el "correcto"? Depende del problema. Para flujos simples y predecibles, el secuencial está bien. Para tareas dinámicas, el reactivo funciona mejor. Para objetivos de varios pasos con dependencias, necesitas agentes de planificación.
En este lab, crearemos un agente deliberativo o de planificación que primero cree un esquema y, luego, escriba la entrada de blog.
3. Antes de comenzar
Crea una cuenta y un proyecto de Google Cloud
Para implementar tu agente en Google Cloud Run más adelante en este lab, necesitas una cuenta de Google Cloud y un proyecto con la facturación habilitada.
- Accede a la consola de Google Cloud. Crea un proyecto nuevo o reutiliza uno existente. Si aún no tienes una Cuenta de Google, debes crear una.
- A continuación, deberás habilitar la facturación en la consola de Cloud para usar los recursos de Cloud. Ejecutar este codelab debería costar menos de unos centavos. Es posible que los usuarios nuevos de Google Cloud también cumplan con los requisitos para participar en el programa Prueba gratuita de USD 300.
- Anota tu ID del proyecto (un nombre único en todos los proyectos de Google Cloud). Lo necesitarás para configurar y, luego, implementar el agente.
Obtén una clave de la API de Google AI Studio
Para usar los modelos de Gemini, necesitas una clave de API de Google AI Studio.
- Ve a Google AI Studio.
- Haz clic en Obtener clave de API.
- Crea una clave nueva o usa una existente. Copia la clave para usarla más adelante.
4. Crea la estructura del proyecto del agente de redacción de blogs
En este paso, configurarás el directorio y los archivos para alojar el código del agente de redacción de blogs en tu máquina local.
1. Crea el espacio de trabajo del agente de redacción de blogs
Abre la terminal y ejecuta los siguientes comandos para crear un directorio dedicado para tu agente de redacción de blogs y navegar a él:
mkdir bloggeragent
cd bloggeragent
2. Inicializa los archivos del agente
El framework del ADK de Google carga los flujos de trabajo del agente directamente desde el directorio de tu proyecto. Crea los archivos necesarios directamente en la raíz de bloggeragent:
touch requirements.txt .env __init__.py agent.py
5. Instala dependencias y configura el entorno
En este paso, configurarás un entorno virtual de Python, instalarás el framework del ADK de Google y configurarás variables de entorno para autenticar tu agente de blog con el modelo de Gemini.
1. Configura los requisitos del agente
Abre el archivo requirements.txt en el directorio bloggeragent y especifica los paquetes necesarios para el agente de redacción de blogs agregando lo siguiente:
google-adk==2.2.0
python-dotenv
2. Crea un entorno virtual para el agente
Desde el directorio bloggeragent, crea y activa un entorno virtual de Python para aislar los paquetes del agente:
python3 -m venv .venv
source .venv/bin/activate
3. Instala el framework del ADK
Instala las dependencias definidas en tu requirements.txt para equipar tu espacio de trabajo local con el ADK de Google:
pip install -r requirements.txt
4. Configura las credenciales de la API del agente
Abre el archivo .env que creaste en la raíz del proyecto y agrega tu clave de la API de Gemini:
GOOGLE_API_KEY=your_api_key
Reemplaza your_api_key por la clave que copiaste de Google AI Studio.
6. Compila el escritor de blogs multiagente
En este paso, implementarás el flujo de trabajo principal de tu sistema de agentes de redacción de blogs.
En lugar de un chatbot simple de una sola instrucción, crearás un sistema multiagente complejo que utiliza bucles de autocorrección y verificación de esquemas para escribir publicaciones técnicas de alta calidad. Esto sigue el patrón de Deliberación/Planificación que analizamos anteriormente.
Descripción general de la arquitectura
Así es como interactúan los agentes especialistas en tu sistema:
Configura init.py
Abre __init__.py en tu editor de texto y agrega la siguiente importación para exponer el flujo de trabajo del agente al ejecutor:
from . import agent
Escribe el flujo de trabajo del agente de redacción de blogs
Abre agent.py en tu editor de código y agrega el siguiente código que define Planner, Writer, Validation Checkers y el agente principal de Blogger:
import os
import sys
from pathlib import Path
import datetime
from dotenv import load_dotenv
from google.adk.agents import Agent, LoopAgent
from google.adk.tools import agent_tool
# env config
load_dotenv()
MODEL = os.getenv("MODEL", "gemini-flash-latest")
# Sub-Agent: Planner
blog_planner = Agent(
name="BlogPlanner",
model=MODEL,
description="Creates a practical, skimmable outline in Markdown.",
instruction="""
You are a technical content strategist. Produce a clear Markdown outline with:
- Title
- Short intro
- 4–6 main sections (each with 2–3 bullets)
- Conclusion
If `codebase_context` exists in state, weave in specific sections/snippets.
Return only the outline in Markdown.
""",
output_key="blog_outline",
)
class OutlineValidationChecker(Agent):
def __init__(self):
super().__init__(
name="OutlineValidationChecker",
model=MODEL,
description="Validates that the outline is usable.",
instruction="""
Check the outline in state `blog_outline`. If it has a title, intro, 4–6 sections, and a conclusion, respond exactly "ok".
Otherwise respond exactly "retry" and list missing pieces.
""",
output_key="validation_result",
)
robust_blog_planner = LoopAgent(
name="RobustBlogPlanner",
description="Retries planning if validation fails.",
sub_agents=[blog_planner, OutlineValidationChecker()],
max_iterations=3,
)
# Sub-Agent: Writer
blog_writer = Agent(
name="BlogWriter",
model=MODEL,
description="Writes a technical blog post from the outline.",
instruction="""
Write a complete Markdown article from the outline in `blog_outline`.
Guidelines:
- Audience: software engineers; skip basics and focus on practical insight.
- Explain both the 'how' and 'why'.
- Include concise code snippets when helpful.
- Follow the outline's structure (H2/H3).
- Output only the final article in Markdown (no fence around the whole post).
""",
output_key="blog_post",
)
class BlogPostValidationChecker(Agent):
def __init__(self):
super().__init__(
name="BlogPostValidationChecker",
model=MODEL,
description="Validates the final post.",
instruction="""
Check `blog_post` for: intro, clear sections matching the outline, conclusion, and technical clarity.
If passes, respond "ok". Else respond "retry" with the specific fixes.
""",
output_key="validation_result",
)
robust_blog_writer = LoopAgent(
name="RobustBlogWriter",
description="Retries writing if validation fails.",
sub_agents=[blog_writer, BlogPostValidationChecker()],
max_iterations=3,
)
# Expose planner/writer as tools so the root agent can call them explicitly
planner_tool = agent_tool.AgentTool(agent=robust_blog_planner)
writer_tool = agent_tool.AgentTool(agent=robust_blog_writer)
# Root Agent: Plan → Write
root_agent = Agent(
name="Blogger",
model=MODEL,
description="Minimal multi-agent blogger that plans and writes.",
instruction=f"""
If the user gives a topic:
1) Call the planner tool to generate the outline.
2) Call the writer tool to produce the full draft.
3) End with 3 alternate titles and 2 tweet-length hooks.
Date: {datetime.datetime.now().strftime("%Y-%m-%d")}
""",
tools=[
planner_tool, # calls RobustBlogPlanner
writer_tool, # calls RobustBlogWriter
],
)
Información sobre la arquitectura del agente
Desglosemos los componentes principales del código que acabas de agregar en agent.py para comprender cómo implementa el flujo de trabajo de planificación y escritura multiagente:
1. El subagente de BlogPlanner
El agente blog_planner es responsable de la planificación del contenido. Toma el tema proporcionado por el usuario y produce un esquema estructurado en Markdown (con un título, una introducción, de 4 a 6 secciones y una conclusión). El esquema se guarda en el diccionario de estado compartido con la clave "blog_outline".
2. OutlineValidationChecker
El agente OutlineValidationChecker actúa como una puerta de control de calidad. Revisa el "blog_outline" generado en el estado. Si el esquema es válido, responde con "ok". De lo contrario, devuelve "retry" junto con una lista de lo que falta.
3. El bucle de RobustBlogPlanner
Para evitar que el agente produzca esquemas deficientes, incluimos el planificador y el verificador de validación dentro de un LoopAgent llamado robust_blog_planner. Si la validación falla y devuelve "retry", el bucle ejecuta automáticamente el planificador de nuevo, hasta 3 veces, lo que garantiza la autocorrección antes de pasar a la siguiente etapa.
4. El subagente BlogWriter
Una vez que se finaliza el esquema, el agente blog_writer lee "blog_outline" del estado y genera el artículo técnico completo en Markdown, que coincide con la estructura del esquema y lo adapta para los ingenieros de software.
5. BlogPostValidationChecker y RobustBlogWriter Loop
Al igual que el esquema, el artículo final se valida con BlogPostValidationChecker para garantizar que todas las secciones clave estén presentes y sean claras. El escritor y el verificador se incluyen en el bucle robust_blog_writer, lo que permite que se autocorrija hasta 3 veces si el verificador encuentra problemas.
6. Cómo exponer Loops como herramientas
Envolvemos el bucle del planificador (robust_blog_planner) y el bucle del escritor (robust_blog_writer) como herramientas (planner_tool y writer_tool) con AgentTool. Esto permite que otros agentes llamen a estos flujos de trabajo complejos como si fueran herramientas simples.
7. El agente raíz de Blogger
El root_agent (llamado Blogger) organiza todo el flujo de trabajo. Cuando se le da un tema, sus instrucciones la guían para hacer lo siguiente:
- Llama a
planner_toolpara generar el esquema validado. - Llama a
writer_toolpara escribir el borrador según ese esquema. - Para finalizar, genera 3 títulos alternativos y 2 cebos para tweets.
Esta arquitectura de bucle multiagente garantiza la confiabilidad, ya que detecta y corrige los errores de formato o estructurales del LLM antes de mostrar el resultado al usuario.
7. Ejecuta y prueba el agente
Ahora es momento de ver tu agente en acción.
1. Inicia la IU web del ADK
Asegúrate de estar en el directorio raíz del proyecto bloggeragent en tu terminal y de que tu entorno virtual esté activo (source .venv/bin/activate). Luego, inicia la interfaz web:
adk web
2. Interactúa con el agente
- Abre el navegador y navega a
http://127.0.0.1:8000(o al puerto que especificaste). - Deberías ver la IU web del ADK con el agente
Bloggercargado y su diseño visual (que muestra el agente raíz de Blogger que apunta a las herramientas RobustBlogPlanner y RobustBlogWriter):
- Escribe un tema técnico en el cuadro de mensaje y presiona Intro. Estas son algunas instrucciones de prueba interesantes que puedes usar para evaluar tu agente:
How to build an AI agent using planning loopsExplain the difference between REST and gRPC in microservicesA guide to using Python's asyncio for backend concurrencyWhy developers should use Docker for local database setups
- Observa el registro de ejecución en la IU. Verás que
BlogPlannercrea el esquema,OutlineValidationCheckerlo valida yBlogWriterescribe el borrador final según el esquema:
8. Implementa en Cloud Run
Ahora que verificaste que el agente funciona de forma local, implementémoslo en Google Cloud Run para que otras personas puedan usarlo.
Google Cloud Run es una plataforma de procesamiento administrada que te permite ejecutar contenedores sin estado que se pueden invocar a través de solicitudes web o eventos de Pub/Sub.
1. Requisitos previos para la implementación
Para implementar el agente de redacción de blogs en Cloud Run, deberás instalar y autenticar Google Cloud CLI (gcloud) en tu máquina local:
- Instala Google Cloud CLI: Si no la tienes instalada, sigue la Guía de instalación de Google Cloud CLI para tu sistema operativo (macOS, Windows o Linux).
- Autentica tu terminal local: Una vez instalado, ejecuta el siguiente comando en tu terminal para acceder a tu cuenta de Google Cloud:
gcloud auth login - Verifica la autenticación: Confirma que accediste correctamente a tu cuenta y que puedes acceder a tus recursos de Google Cloud:
gcloud auth list
2. Configura el proyecto de Google Cloud
Establece tu proyecto activo en la terminal:
gcloud config set project <YOUR_PROJECT_ID>
Habilita los servicios de Google Cloud necesarios para compilar e implementar tu agente en contenedores:
gcloud services enable \
run.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com
Dado que el comando de implementación del ADK usa Google Cloud Build para automatizar el proceso de compilación, debes otorgar permiso a la cuenta de servicio predeterminada de Compute para usar Cloud Build.
Ejecuta el siguiente comando para encontrar el número de tu proyecto:
gcloud projects describe <YOUR_PROJECT_ID> --format="value(projectNumber)"
Ejecuta los siguientes comandos para vincular los roles de IAM necesarios (reemplaza
- Otorga permiso a Cloud Build para compilar tu contenedor:
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
--role="roles/cloudbuild.builds.builder"
- Otorga permiso de acceso a Gemini Enterprise para que el agente implementado pueda invocar modelos de Gemini sin necesidad de una clave de API:
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.user"
3. Configura variables de entorno locales
Para simplificar el comando de implementación y evitar errores de escritura, configura el ID de tu proyecto como una variable de entorno en tu sesión de la terminal:
export PROJECT_ID="<YOUR_PROJECT_ID>"
4. Implementa con la CLI del ADK
La CLI del ADK proporciona un comando optimizado para implementar tu agente en Cloud Run.
Asegúrate de que tu entorno virtual esté activo y de que te encuentres en el directorio del proyecto bloggeragent. Luego, ejecuta el comando de implementación:
# Deploy using ADK
adk deploy cloud_run \
--project=$PROJECT_ID \
--region=us-east1 \
--service_name=bloggeragent \
--with_ui \
. \
-- \
--set-env-vars GOOGLE_GENAI_USE_VERTEXAI=TRUE,MODEL=gemini-3.5-flash,GOOGLE_CLOUD_LOCATION=global
Durante el proceso de implementación, se te harán las siguientes dos preguntas en la terminal:
- Confirma la creación del repositorio:
Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region [us-east1] will be created. Do you want to continue (Y/n)?
Yy presiona Intro. - Permitir acceso no autenticado:
Allow unauthenticated invocations to [bloggeragent] (y/N)?
yy presiona Intro (esto te permite acceder a la IU web del ADK de forma pública en tu navegador).
5. Accede a tu agente implementado
Una vez que se complete la implementación, el comando generará una URL. Abre esa URL en tu navegador para acceder a la IU web del ADK en vivo y de acceso público.
9. Limpia
Para evitar que se apliquen cargos a tu cuenta de Google Cloud, borra los recursos que creaste durante este codelab.
1. Borra el servicio de Cloud Run
Borra el servicio bloggeragent implementado:
gcloud run services delete bloggeragent --region=us-east1 --quiet
2. Borra el repositorio de Artifact Registry
Borra el repositorio de Docker creado para almacenar las imágenes de contenedor compiladas:
gcloud artifacts repositories delete cloud-run-source-deploy --location=us-east1 --quiet
3. Detén el servidor local
Para detener el servidor local del ADK, presiona CTRL+C en la terminal en la que se está ejecutando y desactiva el entorno virtual:
deactivate
10. Felicitaciones
¡Felicitaciones! Creaste tu primer agente de IA con el ADK de Google y Gemini.
Qué aprendiste
- Los conceptos básicos de los agentes de IA (razonamiento y acción)
- Cómo usar el ADK de Google para crear un sistema multiagente
- Cómo ejecutar y probar tu agente con la IU web
Próximos pasos
- Intenta agregar herramientas a tu agente (como la búsqueda web o las llamadas a la API).
- No te pierdas el video 2, en el que integraremos un servidor de MCP.