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

1. Introducción

Este codelab, que comienza con los conceptos básicos y avanza hacia el desarrollo de agentes con múltiples herramientas, proporciona una introducción integral para crear 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 mediante la realización autónoma de una secuencia de tareas.

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

LLM vs. 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 bloques de construcción 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 con 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 para lograr un objetivo final.

Qué compilarás

En este codelab, compilarás un agente de "Healthy Hints", un consultor nutricional inteligente que pasa de un razonamiento de texto simple a una potencia de múltiples herramientas. Comenzarás por crear un agente conversacional básico que comprenda los 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 organizador completamente funcional que puede tomar una foto subida de una etiqueta de alimentos, almacenarla en un bucket de la nube para el mantenimiento de registros y proporcionar de inmediato "Healthy Hints" 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 para 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 está configurado con el ID de tu proyecto. En Cloud Shell, ejecuta el siguiente comando para confirmar que tienes la autenticación:

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 Open editor en la esquina superior derecha. Se abrirá un editor de VSCode.

3. Configuración de 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 la API de Google

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

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

• Verás una ventana de claves de API. Haz clic en Create API key en esta ventana:

• Verás una ventana emergente para crear una clave nueva. Nombra la clave como healthy-hints-key.

Ve al menú desplegable "Elige un proyecto importado".

• Haz clic en Import Project. Aparecerá una ventana lateral que muestra todos tus proyectos de Google Cloud. Selecciona el que deseas 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. Haz clic en Crear clave ahora. 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 del proyecto que desees:

adk create healthy_hints

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

En este codelab, usaremos Google AI. 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 y, 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 carpetas healthy_hints suele verse de la siguiente manera:

• Verás un archivo .env que tiene tu clave de la API de Google. Puedes usar este archivo para configurar 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 el 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, nombramos el agente y proporcionamos una descripción adecuada. La instrucción es lo más importante aquí, ya que es donde le indicamos al agente lo que debe hacer en lenguaje natural.
• Este agente de muestra es bastante genérico y solo responderá cualquier pregunta que tenga un usuario.
• Ahora ejecutemos este agente de forma local. Existen dos maneras de interactuar con este agente : CLI y Web.
• CLI: Ejecuta el siguiente comando desde fuera del directorio healthy_hints.

adk run healthy_hints

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

adk run .

Verás un resultado similar:

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 superior 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 función: 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: 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 sistemas avanzados de "múltiples herramientas" o "múltiples agentes", un agente especializado puede actuar como una 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, abordaremos las herramientas de función. Ahora, avancemos nuestro agente y hagámoslo de múltiples herramientas.

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 agent.py y cambiemos el nombre, la descripción y la instrucción 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}

Y modifiquemos nuestro agente para invocar también 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, la instrucción y las herramientas según corresponda. Ahora vamos a ejecutar este agente actualizado. Esta vez, el agente también responderá 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 el agente nos informará sobre cada ingrediente que sea saludable o no.

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

Esto 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 de buckets, ingresa el nombre del bucket. El nombre puede ser cualquier cosa, pero para este codelab, lo pondremos como healthy-hints-bucket-kolkata . Deja todo lo demás como está y haz clic en el botón Create.

• Creemos un archivo nuevo llamado requirements.txt y agreguemos google-cloud-storage en él. Usaremos el SDK de Storage de Python para subir la imagen en 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 herramienta nueva:

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

De nuevo, 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 usar 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 con múltiples herramientas. Si usas el ADK para integrar la API de Vision y el SDK de Cloud Storage, le diste 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 proporcionar 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 la nube o compiles asistentes personales, el núcleo sigue siendo el mismo: define herramientas especializadas y deja que el agente organice la lógica. Como siguiente paso, intenta agregar más herramientas, como una "base de datos nutricional" o una "herramienta de correo electrónico", para expandir el impacto de tu agente.