ADK: de los conceptos básicos a los agentes con múltiples herramientas

1. Introducción

Este codelab comienza con los conceptos básicos y avanza hasta el desarrollo de agentes multiherramienta, y proporciona una introducción integral a la creación de agentes con el ADK.

En su forma más simple, un agente de IA es un sistema de software que usa un modelo de lenguaje grande (LLM) como su "motor de razonamiento" para lograr un objetivo realizando de forma autónoma una secuencia de tareas.

Si un LLM es un asesor altamente capaz que puede darte consejos, un agente de IA es un ingeniero proactivo que puede usar herramientas para ejecutar esos consejos.

Comparación entre LLM y agentes

El cerebro (LLM): Proporciona razonamiento, planificación y comprensión del lenguaje natural. Decide qué se debe hacer.

Las manos (herramientas): Son las APIs, los SDKs y las funciones personalizadas que permiten que el agente interactúe con el mundo real. Ejecuta el plan.

El Kit de desarrollo de agentes (ADK)

El Kit de desarrollo de agentes (ADK) es un framework especializado diseñado para simplificar la creación, la implementación y la organización de agentes de IA. Proporciona los componentes básicos estandarizados necesarios para transformar un modelo de lenguaje grande estático en un agente dinámico capaz de ejecutar código, llamar a APIs y administrar flujos de trabajo de varios pasos.

Un agente de múltiples herramientas es un organizador que puede seleccionar y secuenciar diferentes funciones especializadas, como un motor de búsqueda, una base de datos y una calculadora, para resolver problemas complejos. Determina de forma inteligente qué herramienta usar para cada paso y puede pasar el resultado de una acción como entrada para la siguiente y, así, alcanzar un objetivo final.

Qué compilarás

En este codelab, compilarás un agente de "Sugerencias saludables", un asesor nutricional inteligente que pasa de un razonamiento de texto simple a una potencia multitarea. Comenzarás por crear un agente conversacional básico que comprenda conceptos de nutrición y, luego, lo equiparás progresivamente con una herramienta del SDK de Storage para archivar imágenes de ingredientes y una herramienta de Vision para "leer" y analizar esas imágenes. Al final de este lab, tendrás un orquestador completamente funcional que puede tomar una foto subida de una etiqueta de alimentos, almacenarla en un bucket de Cloud para el mantenimiento de registros y proporcionar de inmediato "Sugerencias saludables" para cada ingrediente.

2. Requisitos previos

• Un proyecto de Google Cloud con la facturación habilitada
• Un navegador web

Crea tu proyecto

• En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
• Asegúrate de que la facturación esté habilitada en tu proyecto de Cloud. Obtén información sobre cómo verificar si la facturación está habilitada en un proyecto.

Activar Cloud Shell

• Usarás Cloud Shell, un entorno de línea de comandos que se ejecuta en la consola de Google Cloud y que viene precargado con los lenguajes necesarios instalados. En la consola de Cloud, haz clic en Activar Cloud Shell en la esquina superior derecha:

• Una vez que te conectes a Cloud Shell, deberías ver que ya te autenticaste y que el proyecto se configuró con tu ID del proyecto. En Cloud Shell, ejecuta el siguiente comando para confirmar que te autenticaste:

gcloud auth list

• En Cloud Shell, ejecuta el siguiente comando para confirmar que el comando gcloud conoce tu proyecto:

gcloud config list project

• Si tu proyecto no está configurado, usa el siguiente comando para hacerlo:

gcloud config set project <YOUR_PROJECT_ID>

Consulta la documentación para ver los comandos y el uso de gcloud.

Abrir editor

• En este codelab, usaremos el editor de Cloud integrado. En la ventana de Cloud Shell, haz clic en el botón Abrir editor que se encuentra en la esquina superior derecha. Se abrirá un editor de VSCode.

3. Configuración del ADK

Pasemos a la terminal de Cloud Shell que activamos en la sección anterior:

• Crea y activa un entorno virtual (recomendado).

Desde la terminal de Cloud Shell, crea un entorno virtual:

python -m venv .venv

Activa el entorno virtual:

source .venv/bin/activate

• Instala el ADK.

pip install google-adk

4. Clave de API de Google

Crea una clave de la API de Google con AI Studio:

• Visita https://aistudio.google.com/ y, en el menú de la parte inferior izquierda, haz clic en Get API Key.

• Verás una ventana de claves de API. Haz clic en Crear clave de API en esta ventana:

• Verás una ventana emergente para crear una clave nueva. Asigna el siguiente nombre a la clave: healthy-hints-key

Ve al menú desplegable “Elige un proyecto importado”.

• Haz clic en Import Project. Aparecerá una ventana lateral con todos tus proyectos de Google Cloud. Selecciona el que quieras usar.

Haz clic en Importar.

• El menú desplegable ahora se actualizará con el proyecto que acabas de importar. Selecciona el proyecto en el menú desplegable. Ahora haz clic en Crear clave. Ahora verás la lista de claves de API creadas. Haz clic en el ícono de copia de la clave de API que acabas de crear.

5. Agente de muestra

• Desde la terminal de Cloud Shell, crea un directorio raíz para tu agente en la ubicación deseada del proyecto:

adk create healthy_hints

Puedes elegir cualquier modelo, pero para este codelab, usaremos gemini-2.5-flash.

En este codelab, usaremos la IA de Google. Pega la clave de API que creaste en el paso anterior.

• Abramos la carpeta que acabamos de crear. En el menú de la izquierda, haz clic en el ícono , luego en File -> Open Folder. Selecciona la carpeta healthy_hints que se acaba de crear. Por lo general, se encuentra en la carpeta /home/<username>.
• La estructura de la carpeta healthy_hints suele verse de la siguiente manera:

• Verás un archivo .env que contiene tu clave de la API de Google. Puedes usar este archivo para establecer cualquier variable de entorno.
• También se crea otro archivo llamado agent.py, que es nuestro archivo de agente principal. Aquí es donde se crea un agente raíz de muestra. Analicemos de cerca el contenido de este archivo. Primero, importamos llm_agent desde el ADK. Luego, usamos el DSL del ADK para crear el agente raíz. Especificamos el nombre del modelo como Gemini-2.5-flash, le asignamos un nombre al agente y proporcionamos una descripción agradable. La instrucción es lo más importante aquí, ya que es donde le decimos al agente lo que debe hacer en lenguaje natural.
• Este agente de ejemplo es bastante genérico y solo responderá cualquier pregunta que tenga un usuario.
• Ahora, ejecutemos este agente de forma local. Puedes interactuar con este agente de dos maneras : a través de la CLI y la Web.
• CLI: Ejecuta el siguiente comando desde fuera del directorio healthy_hints.

adk run healthy_hints

O bien, si estás dentro del directorio healthy_hints, ejecuta el siguiente comando:

adk run .

Verás un resultado similar al siguiente:

Escribe "hola" o cualquier pregunta que tengas. La respuesta puede ser diferente para cada persona, esa es la naturaleza de la IA generativa.

• Web: Ejecuta el siguiente comando desde el directorio principal de healthy_hints :

adk web

6. Agente con múltiples herramientas

Una herramienta es un fragmento de código modular (por lo general, una función o una API) que permite que un agente interactúe con el mundo más allá de su conocimiento interno.

Tipos de herramientas en el ADK

• Herramientas de funciones: Lógica personalizada que escribes tú mismo Por ejemplo, una función que se conecta a tu base de datos específica o un "analizador de registros" personalizado para el formato único de tu empresa.
• Herramientas integradas: Son capacidades listas para usar que proporcionan Google o el ADK, como la Búsqueda de Google, el Intérprete de código o el Motor de RAG de Google.
• Agents-as-Tools: En los sistemas avanzados de "varias herramientas" o "varios agentes", un agente especializado puede actuar como herramienta para otro. Por ejemplo, un "Agente de búsqueda" puede ser una herramienta que usa un "Agente de administrador de investigación".

En este codelab, analizaremos las herramientas de funciones. Ahora, avancemos con nuestro agente y hagámoslo multiherramienta.

Agreguemos un nuevo método get_weather en agent.py.

def get_weather(city: str) -> dict:
  """Retrieves the current weather report for a specified city.

  Args:
    city (str): The name of the city for which to retrieve the weather report.

  Returns:
    dict: status and result or error msg.
  """
  if city.lower() == "new york":
    return {
      "status": "success",
      "report": (
          "The weather in New York is sunny with a temperature of 25 degrees"
          " Celsius (77 degrees Fahrenheit)."
      ),
    }
  else:
    return {
      "status": "error",
      "error_message": f"Weather information for '{city}' is not available.",
    }

Modifiquemos el archivo agent.py y cambiemos el nombre, la descripción y las instrucciones del agente:

root_agent = Agent(
    model='gemini-2.5-flash',
    name='healthy_hints_agent',
    description='Agent to answer questions about the weather in a city.',
    instruction='You are a helpful agent who can answer user questions about the weather in a city.',
    tools=[get_weather],
)

Hasta ahora, solo creamos una herramienta. Ahora, creemos varias herramientas:

Creemos otro método llamado get_current_time :

def get_current_time(city: str) -> dict:
  """Returns the current time in a specified city.

  Args:
    city (str): The name of the city for which to retrieve the current time.

  Returns:
    dict: status and result or error msg.
  """

  if city.lower() == "new york":
    tz_identifier = "America/New_York"
  else:
    return {
      "status": "error",
      "error_message": (
        f"Sorry, I don't have timezone information for {city}."
      ),
    }

  tz = ZoneInfo(tz_identifier)
  now = datetime.datetime.now(tz)
  report = (
    f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
  )
  return {"status": "success", "report": report}

Modifiquemos nuestro agente para que también invoque esta herramienta:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to answer questions about the time and weather in a city.',
  instruction='You are a helpful agent who can answer user questions about the time and weather in a city.',
  tools=[get_weather, get_current_time],
)

Modificamos la descripción, las instrucciones y las herramientas según corresponda. Ahora, ejecutemos este agente actualizado. Esta vez, el agente también respondería con la hora y el clima actuales.

7. Integración de SDK

Ahora que sabemos cómo usar varias herramientas, Trabajemos con algunos ejemplos de la vida real. Creemos un agente de sugerencias saludables. Nuestro objetivo aquí es subir cualquier imagen que tenga una lista de ingredientes a nuestro agente, y este nos dirá si cada ingrediente es saludable o no.

• Primero, creemos un bucket para subir la imagen a Google Cloud Storage. Abramos una pestaña nueva y naveguemos a https://console.cloud.google.com/. En la barra de búsqueda, escribe Cloud Storage. Ahora, selecciona Cloud Storage en Productos y páginas:

Esta acción te llevará a la página de descripción general de Google Cloud Storage. Haz clic en el botón Create bucket. En la página de creación del bucket, ingresa el nombre del bucket. El nombre puede ser cualquiera, pero, para este codelab, lo llamaremos healthy-hints-bucket-kolkata . Deja todo lo demás como está y haz clic en el botón Create.

• Crearemos un archivo nuevo llamado requirements.txt y le agregaremos google-cloud-storage. Usaremos el SDK de Storage de Python para subir la imagen a Storage.

Primero, instalemos las dependencias:

pip install -r requirements.txt

Es posible que primero debas habilitar la API de Storage. Para ello, ejecuta el siguiente comando en la terminal:

gcloud services enable storage.googleapis.com 

Ahora agreguemos una herramienta nueva para subir la imagen.

def upload_image() -> str:
  storage_client = storage.Client()
  bucket_name = "healthy-hints-bucket-kolkata"
  bucket = storage_client.bucket(bucket_name)
  blob = bucket.blob("ingredirents")
  blob.upload_from_filename(<image-file-path>)

• Ahora, actualicemos nuestro agente para que use la nueva herramienta:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool.',
  tools=[upload_image],
)

• Ahora agregaremos otra herramienta para leer los ingredientes de la imagen. Agreguemos google-cloud-vision en requirements.txt y, luego, instalemos la nueva dependencia.

pip install -r requirements.txt

Nuevamente, es posible que primero debas habilitar la API de Vision. Para ello, ejecuta el siguiente comando en la terminal:

gcloud services enable vision.googleapis.com

Ahora agreguemos una herramienta nueva read_ingredients :

def read_ingredients() -> str:
  vision_client = vision.ImageAnnotatorClient()

  with io.open("/home/bajajnehaa/healthy_hints/images/Ingredients-list.jpg", 'rb') as image_file:
    content = image_file.read()

  image = vision.Image(content=content)
  response = vision_client.text_detection(image=image)
  texts = response.text_annotations
  return texts[0].description

Ahora actualicemos nuestro agente para que use esta herramienta.

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage, read the list of ingredients from the image and explain if the ingredient is healthy or not',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool, read the ingredients of the image using `read_ingredients` tool and explain if the ingredient is healthy or not in one line.',
  tools=[upload_image, read_ingredients],
)

8. Conclusión

¡Felicitaciones por completar el codelab de Healthy Hints! Transformaste correctamente una IA estándar de un generador de texto en un agente proactivo de múltiples herramientas. Con el uso del ADK para integrar la API de Vision y el SDK de Cloud Storage, le proporcionaste a tu agente los "ojos" para leer etiquetas y la "memoria" para archivarlas. Viste cómo el agente decide de forma autónoma cuándo guardar un archivo y cómo interpretar datos sin procesar para brindar consejos de salud del mundo real.

En el futuro, estos principios servirán como modelo para cualquier sistema automatizado. Ya sea que administres la infraestructura de nube o crees asistentes personales, el núcleo sigue siendo el mismo: define herramientas especializadas y deja que el agente coordine la lógica. Como siguiente paso, intenta agregar más herramientas, como una "Base de datos nutricionales" o una "Herramienta de correo electrónico", para ampliar el impacto de tu agente.