Crea agentes de IA con el ADK: Potencia con herramientas

1. Antes de comenzar

Te damos la bienvenida a la segunda parte de la serie "Crea agentes de IA con el ADK". En este codelab práctico, potenciarás un agente de IA básico con una variedad de herramientas.

Para comenzar, esta guía proporciona dos rutas: una para quienes continúan desde el codelab "Cómo compilar agentes de IA con el ADK: Los conceptos básicos" y otra para quienes comienzan desde cero. Ambas rutas te garantizarán que tengas el código base del agente necesario para comenzar.

Al final de este codelab, habrás potenciado tu agente asistente personal con herramientas para diversos fines, un paso más cerca de expandirse en las partes posteriores de esta serie a medida que lo transformamos en un sofisticado sistema multiagente (MAS).

También puedes acceder a este codelab a través de esta URL acortada: goo.gle/adk-using-tools.

Requisitos previos

Qué aprenderás

  • Bríndale nuevas habilidades a tu agente creando funciones de Python personalizadas como herramientas.
  • Conecta tu agente a información en tiempo real con herramientas integradas, como la Búsqueda de Google.
  • Estructura un agente multiherramienta creando subagentes especializados para tareas complejas.
  • Integra herramientas de frameworks de IA populares, como LangChain, para expandir rápidamente las capacidades.

Requisitos

  • Una computadora que funcione y una red Wi-Fi confiable
  • Un navegador, como Chrome, para acceder a la consola de Google Cloud
  • Una mente curiosa y ganas de aprender

2. Introducción

Un agente básico creado con el ADK tiene un potente cerebro de LLM, pero también tiene limitaciones: no puede acceder a la información creada después de la fecha de su entrenamiento ni interactuar con servicios externos. Es como un asistente brillante y erudito encerrado en una biblioteca sin teléfono ni Internet. Para que un agente sea realmente útil, debemos proporcionarle herramientas.

Piensa en las herramientas como si le dieran acceso al asistente de IA al mundo exterior: una calculadora, un navegador web o acceso a una base de datos específica de la empresa. En ADK, una herramienta es un fragmento de código modular que permite al agente realizar acciones específicas, como buscar datos en tiempo real o llamar a una API externa. El uso de herramientas extiende sus capacidades mucho más allá de la simple conversación.

El ADK ofrece tres categorías de herramientas:

  1. Herramientas de funciones: Son herramientas personalizadas que desarrollas para satisfacer los requisitos únicos de tu aplicación, como funciones y agentes predefinidos.
  2. Herramientas integradas: Herramientas listas para usar que proporciona el framework para operaciones comunes, como la Búsqueda de Google y la ejecución de código
  3. Herramientas de terceros: Bibliotecas externas populares, como Serper y herramientas de LangChain y CrewAI

Para obtener más información sobre el uso de herramientas con agentes de ADK, consulta la documentación oficial. En este codelab, agregaremos herramientas para transformar nuestro agente simple en un asistente personal de viajes capaz. Comencemos.

3. Primeros pasos: Tu agente base

Antes de potenciar un agente con herramientas, necesitas un agente básico con el que trabajar. Elige la ruta que mejor se adapte a tu progreso.

Ruta A: Continuación del Codelab de Foundation

Si acabas de completar el codelab "Crea agentes de IA con ADK: conceptos fundamentales", ya tienes todo listo. Puedes seguir trabajando en tu directorio de proyectos ai-agents-adk existente.

Ruta B: Comenzar de cero

Si vas a comenzar este codelab directamente, completa estos 4 pasos para configurar tu entorno y crear el agente inicial necesario.

  1. Configura los servicios de Google Cloud
  2. Crea un entorno virtual de Python
  3. Crea un agente
  4. Ejecuta el agente en la IU de desarrollo

Una vez que completes los pasos, podrás comenzar tu recorrido de aprendizaje.

4. Crea una herramienta personalizada para el cambio de divisas

En esta etapa, ya deberías saber cómo compilar un agente de IA simple con el ADK y ejecutarlo en la IU de desarrollo.

Imagina que te estás preparando para un viaje a Japón el próximo mes y necesitas verificar el tipo de cambio actual. Pregúntale al agente "¿Cuál es el tipo de cambio del dólar de Singapur al yen japonés?"

a8f38e3c404ada9c.png

Verás que el agente no puede recuperar los tipos de cambio en tiempo real. Esto se debe a que el agente no tiene acceso a Internet ni conectividad con sistemas externos. Incluso si el agente responde con un valor, es difícil confiar en él, ya que es probable que sea una alucinación.

Para abordar este problema, implementaremos una función de Python para recuperar los tipos de cambio a través de una API de REST y la integraremos como una herramienta de función para el agente.

Para finalizar el proceso del agente en ejecución, usa la combinación de teclas Ctrl + C en la ventana de la terminal.

Crea un archivo custom_functions.py

Escribe este comando en la terminal para crear un archivo de Python llamado custom_functions.py en la carpeta personal_assistant.

touch personal_assistant/custom_functions.py

Así debería verse la estructura de carpetas:

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    └── custom_functions.py

Abre custom_functions.py en el editor de código. Este archivo contendrá la función de Python responsable de recuperar los datos del tipo de cambio de una API externa.

Copia y pega el siguiente código en el interior:

import requests

# define a function to get exchange rate
def get_fx_rate(base: str, target: str):
        """
        Fetches the current exchange rate between two currencies.

        Args:
                base: The base currency (e.g., "SGD").
                target: The target currency (e.g., "JPY").

        Returns:
                The exchange rate information as a json response,
                or None if the rate could not be fetched.
        """
        base_url = "https://hexarate.paikama.co/api/rates/latest"
        api_url = f"{base_url}/{base}?target={target}"

        response = requests.get(api_url)
        if response.status_code == 200:
                return response.json()

Ahora, edita el archivo agent.py: importa la función get_fx_rate y asígnala como FunctionTool.

Actualiza el archivo agent.py

Copia este bloque de código y reemplaza el contenido existente del archivo agent.py:

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

from .custom_functions import get_fx_rate

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
    tools=[FunctionTool(get_fx_rate)]
)

Después de los cambios, vuelve a iniciar el agente escribiendo lo siguiente:

adk web

Cuando el agente esté en funcionamiento, vuelve a hacer la misma pregunta: "¿Cuál es el tipo de cambio del dólar de Singapur al yen japonés?"

Esta vez, deberías ver el tipo de cambio real que proporciona la herramienta get_fx_rate.

4f671fe04f8421f5.png

No dudes en hacer todas las preguntas que quieras sobre el cambio de divisas.

5. Integración con la herramienta de Búsqueda de Google integrada

Ahora que el agente puede proporcionar tipos de cambio, la siguiente tarea es obtener el pronóstico del clima del próximo mes. Hazle esta pregunta al agente: "¿Cuál es el pronóstico del tiempo en Tokio, Japón, para el próximo mes?"

96c175077957fdd0.png

Como es de esperar, el pronóstico del clima requiere información en tiempo real que nuestro agente no tiene. Si bien podríamos codificar nuevas funciones de Python para cada caso de uso que requiera datos en tiempo real, agregar cada vez más herramientas personalizadas hace que el agente sea demasiado complicado y difícil de administrar.

Afortunadamente, el Kit de desarrollo de agentes (ADK) proporciona un conjunto de herramientas integradas, incluida la Búsqueda de Google, que están listas para usarse, lo que simplifica la forma en que nuestro agente interactúa con el mundo exterior.

Para equipar al agente con la herramienta de Búsqueda de Google, debes implementar un patrón de varios agentes. Primero, crearás un agente especializado cuyo único trabajo será realizar búsquedas en Google. Luego, asigna este nuevo Agente de la Búsqueda de Google a nuestro personal_assistant principal como herramienta. A continuación, se indican los pasos que debes seguir:

Crea un archivo custom_agents.py

Ahora, crea un archivo de Python llamado custom_agents.py en la carpeta personal_assistant ejecutando este comando en la terminal:

touch personal_assistant/custom_agents.py

Así debería verse la estructura de tu carpeta ahora:

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    ├── custom_functions.py
    └── custom_agents.py

Este archivo contendrá el código del google_search_agent especializado. Copia el siguiente código en el archivo custom_agents.py con el Editor de código.

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


# Create an agent with google search tool as a search specialist
google_search_agent = Agent(
    model='gemini-2.5-flash',
    name='google_search_agent',
    description='A search agent that uses google search to get latest information about current events, weather, or business hours.',
    instruction='Use google search to answer user questions about real-time, logistical information.',
    tools=[google_search],
)

Una vez que se cree el archivo, actualiza el archivo agent.py como se muestra a continuación.

Actualiza el archivo agent.py

Copia este bloque de código y reemplaza el contenido existente del archivo agent.py:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools.agent_tool import AgentTool

from .custom_functions import get_fx_rate
from .custom_agents import google_search_agent


root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    tools=[
        FunctionTool(get_fx_rate), 
        AgentTool(agent=google_search_agent),
    ]
)

Analicemos el nuevo patrón potente en el código:

  • Un nuevo agente especializado: Definimos un agente completamente nuevo, google_search_agent. Ten en cuenta su descripción específica y que su única herramienta es google_search. Es un especialista en búsquedas.
  • agent_tool.AgentTool: Es un wrapper especial del ADK. Toma un agente completo (nuestro google_search_agent) y lo empaqueta para que se vea y actúe como una herramienta estándar.
  • Un**root_agent más inteligente**: Nuestro root_agent ahora tiene una nueva herramienta: AgentTool(agent=google_search_agent). No sabe cómo buscar en la Web, pero sabe que tiene una herramienta a la que puede delegar tareas de búsqueda.

Observa que el campo de instrucciones ya no está en root_agent. Sus instrucciones ahora se definen de forma implícita por las herramientas que tiene disponibles.

El root_agent se convirtió en un orquestador o un router, cuyo trabajo principal es comprender la solicitud de un usuario y pasarla a la herramienta correcta, ya sea la función get_fx_rate o el google_search_agent. Este diseño descentralizado es clave para crear sistemas de agentes complejos y fáciles de mantener.

Ahora, escribe

adk web

en la terminal para iniciar la instancia y volver a hacerle esta pregunta al agente: "¿Cuál es el pronóstico del tiempo en Tokio, Japón, para el próximo mes?"

9771716f64132c54.png

El agente ahora usa google_search_agent para obtener la información más reciente

También puedes hacer una pregunta sobre el tipo de cambio actual. Ahora, el agente debería poder usar la herramienta adecuada para la pregunta correspondiente.

2a8e6525a9f5a4ee.png

No dudes en hacerle otras preguntas al agente que requieran información en tiempo real y observa cómo maneja las consultas con las herramientas a su disposición.

6. Aprovecha la herramienta de Wikipedia de LangChain

Nuestro agente se está convirtiendo en un excelente asistente de viajes. Puede encargarse del cambio de divisas con su herramienta get_fx_rate y administrar la logística con su herramienta google_search_agent. Sin embargo, un gran viaje no se trata solo de logística, sino también de comprender la cultura y la historia de tu destino.

Si bien google_search_agent puede encontrar datos históricos y culturales, la información de una fuente específica, como Wikipedia, suele ser más estructurada y confiable.

Afortunadamente, el ADK está diseñado para ser altamente extensible, lo que te permite integrar sin problemas herramientas de otros frameworks de agentes de IA, como CrewAI y LangChain. Esta interoperabilidad es fundamental porque permite un tiempo de desarrollo más rápido y te permite reutilizar herramientas existentes. Para este caso de uso, aprovecharemos las herramientas de Wikipedia de LangChain.

Primero, detén el proceso del agente en ejecución (Ctrl + C) y, luego, instala bibliotecas adicionales en el entorno virtual de Python actual escribiendo los siguientes comandos en la terminal.

uv pip install langchain-community wikipedia

Crea un archivo third_party_tools.py

Ahora, crea un archivo de Python llamado third_party_tools.py en la carpeta personal_assistant ejecutando el siguiente comando en la terminal:

touch personal_assistant/third_party_tools.py

Así debería verse la estructura de tu carpeta ahora:

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    ├── custom_functions.py
    ├── custom_agents.py
    └── third_party_tools.py

Este archivo contendrá la implementación de la herramienta de Wikipedia de LangChain. Copia el siguiente código en third_party_tools.py con el Editor de Cloud:

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

# Configure the Wikipedia LangChain tool to act as our cultural guide
langchain_wikipedia_tool = WikipediaQueryRun(
    api_wrapper=WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=3000)
)

# Give the tool a more specific description for our agent
langchain_wikipedia_tool.description = (
    "Provides deep historical and cultural information on landmarks, concepts, and places."
    "Use this for 'tell me about' or 'what is the history of' type questions."
)

Actualiza el archivo agent.py

Ahora actualiza el archivo agent.py con el siguiente contenido:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools.agent_tool import AgentTool
from google.adk.tools.langchain_tool import LangchainTool

from .custom_functions import get_fx_rate
from .custom_agents import google_search_agent
from .third_party_tools import langchain_wikipedia_tool


root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    tools=[
        FunctionTool(get_fx_rate), 
        AgentTool(agent=google_search_agent),
        LangchainTool(langchain_wikipedia_tool),
    ]
)

Ahora, escribe

adk web

en la terminal para iniciar la instancia y hacerle esta pregunta al agente: "Cuéntame sobre la historia de Kioto".

862ec3546a8fbb5f.png

El agente identifica correctamente esta búsqueda como histórica y usa su nueva herramienta de Wikipedia. Al integrar una herramienta de terceros y asignarle un rol específico, hiciste que tu agente sea mucho más inteligente y útil para su propósito de planificación de viajes.

Para ver exactamente cómo tomó esta decisión el agente, puedes usar el inspector de eventos en la IU de adk web. Haz clic en la pestaña Eventos y, luego, en el evento functionCall más reciente.

e3f388b64d08e666.png

El inspector muestra una lista de todas las herramientas disponibles y destaca el tool_code de la que ejecutó el agente.

135c9a1068d6c58f.png

7. Limpieza (opcional)

Dado que este codelab no involucra ningún producto de ejecución prolongada, basta con que detengas las sesiones de agentes activos (p.ej., la instancia adk web en tu terminal) presionando Ctrl + C en la terminal.

Borra las carpetas y los archivos del proyecto del agente

Si solo deseas quitar el código de tu entorno de Cloud Shell, usa los siguientes comandos:

cd ~
rm -rf ai-agents-adk

Inhabilita la API de Vertex AI

Para inhabilitar la API de Vertex AI que habilitaste antes, ejecuta este comando:

gcloud services disable aiplatform.googleapis.com

Cómo cerrar todo el proyecto de Google Cloud

Si deseas cerrar por completo tu proyecto de Google Cloud, consulta la guía oficial para obtener instrucciones detalladas.

8. Conclusión

¡Felicitaciones! Habilitaste correctamente el agente de asistente personal con funciones personalizadas y acceso en tiempo real a la Búsqueda de Google. Lee esta documentación oficial sobre cómo usar herramientas con el ADK de Google.

Lo más importante es que aprendiste el patrón arquitectónico fundamental para crear agentes capaces: usar agentes especializados como herramientas. Al crear un google_search_agent dedicado y dárselo a tu root_agent, diste el primer paso para pasar de crear un solo agente a coordinar un sistema multiagente simple, pero potente.

Ahora estás perfectamente preparado para el próximo codelab de la serie, en el que profundizaremos en la organización de varios agentes y flujos de trabajo. ¡Nos vemos!