Agentes de IA con herramientas

Qué es una tool

Las tools (herramientas) son componentes que los agentes utilizan para realizar acciones más allá de generar texto. Permiten que un modelo de lenguaje interactúe con sistemas externos como APIs, bases de datos o servicios web mediante entradas y salidas bien definidas.

Una tool encapsula dos elementos fundamentales:

• Una función ejecutable que realiza la acción deseada
• Un esquema de entrada que define los parámetros que acepta

Cuando un agente recibe una petición del usuario, analiza qué herramientas tiene disponibles y decide cuál invocar y con qué argumentos. Este proceso se conoce como tool calling y es la base del patrón ReAct (Reasoning + Acting) que permite a los agentes razonar sobre qué acción tomar antes de ejecutarla.

El flujo típico de una llamada a herramienta sigue esta secuencia:

[Usuario pregunta] → [Modelo analiza] → [Decide usar tool] → [Ejecuta tool] → [Recibe resultado] → [Genera respuesta]

Herramientas integradas

LangChain ofrece integraciones con servicios externos listos para usar. Una de las más útiles es TavilySearch, que permite realizar búsquedas web en tiempo real. Para utilizarla, primero necesitas instalar el paquete correspondiente:

pip install langchain-tavily

La integración con Tavily requiere una API key que puedes obtener en su sitio web. Una vez configurada como variable de entorno TAVILY_API_KEY, puedes crear un agente con capacidad de búsqueda:

from langchain_tavily import TavilySearch
from langchain.agents import create_agent

# Configuramos la herramienta de búsqueda
web_search = TavilySearch(max_results=3)

# Creamos el agente con la herramienta
agent = create_agent("gpt-5", tools=[web_search])

# Realizamos una consulta que requiere información actualizada
inputs = {
    "messages": [
        {"role": "user", "content": "¿Cuál es la última noticia relevante de Google sobre IA?"}
    ]
}

response = agent.invoke(inputs)
print(response["messages"][-1].content)

El agente analiza la pregunta, determina que necesita información actualizada de internet, invoca la herramienta de búsqueda y formula una respuesta con los datos obtenidos.

Múltiples llamadas a herramientas

Un agente puede realizar varias llamadas a una misma herramienta cuando la consulta lo requiere. Por ejemplo, si el usuario solicita información sobre varios temas:

inputs = {
    "messages": [
        {"role": "user", "content": "Dime el precio actual del Bitcoin y el valor del índice VIX"}
    ]
}

response = agent.invoke(inputs)
print(response["messages"][-1].content)

En este caso, el agente ejecutará múltiples búsquedas para obtener cada dato por separado y luego combinará los resultados en una única respuesta coherente.

Crear herramientas propias

La forma más directa de crear una herramienta personalizada es mediante el decorador @tool. Este decorador transforma una función Python en una tool que el agente puede invocar:

from langchain.tools import tool

@tool
def calcular_descuento(precio: float, porcentaje: float) -> float:
    """Calcula el precio final aplicando un descuento.
    
    Args:
        precio: Precio original del producto
        porcentaje: Porcentaje de descuento a aplicar
    """
    descuento = precio * (porcentaje / 100)
    return precio - descuento

Hay dos elementos obligatorios para que la herramienta funcione correctamente:

• Type hints: Los tipos de los parámetros (float, str, etc.) definen el esquema de entrada
• Docstring: La documentación se convierte en la descripción que el modelo usa para decidir cuándo utilizar la herramienta

Personalizar nombre y descripción

Por defecto, el nombre de la herramienta se toma del nombre de la función. Puedes personalizarlo pasando argumentos al decorador:

@tool("buscar_producto")
def search(query: str) -> str:
    """Busca productos en el catálogo."""
    return f"Resultados para: {query}"

print(search.name)  # buscar_producto

También puedes especificar una descripción personalizada cuando necesites mayor claridad:

@tool("calculadora", description="Realiza operaciones matemáticas. Úsala para cualquier cálculo numérico.")
def calc(expresion: str) -> str:
    """Evalúa expresiones matemáticas."""
    return str(eval(expresion))

Ejemplo práctico: consulta de clima

Veamos un ejemplo completo que combina dos herramientas para obtener el clima de una ubicación. La primera herramienta obtiene las coordenadas geográficas y la segunda consulta la temperatura:

import requests
from langchain.tools import tool
from langchain.agents import create_agent

@tool("obtener_coordenadas")
def get_coordinates(ubicacion: str) -> dict:
    """Obtiene las coordenadas geográficas de una ubicación.
    
    Args:
        ubicacion: Nombre del lugar (ciudad, dirección, punto de interés)
    """
    url = "https://nominatim.openstreetmap.org/search"
    params = {"q": ubicacion, "format": "json", "limit": 1}
    headers = {"User-Agent": "MiApp/1.0"}
    
    respuesta = requests.get(url, params=params, headers=headers)
    datos = respuesta.json()
    
    if datos:
        return {"lat": datos[0]["lat"], "lon": datos[0]["lon"]}
    return {"error": "Ubicación no encontrada"}

@tool("obtener_temperatura")
def get_weather(latitud: str, longitud: str) -> str:
    """Obtiene la temperatura actual a partir de coordenadas.
    
    Args:
        latitud: Latitud de la ubicación
        longitud: Longitud de la ubicación
    """
    url = f"https://api.open-meteo.com/v1/forecast"
    params = {
        "latitude": latitud,
        "longitude": longitud,
        "current": "temperature_2m"
    }
    
    response = requests.get(url, params=params)
    data = response.json()
    return f"{data['current']['temperature_2m']}°C"

Ahora creamos el agente con ambas herramientas:

agent = create_agent(
    "gpt-5",
    tools=[get_coordinates, get_weather]
)

inputs = {
    "messages": [
        {"role": "user", "content": "¿Qué temperatura hace en el Parque del Retiro de Madrid?"}
    ]
}

response = agent.invoke(inputs)
print(response["messages"][-1].content)

El agente ejecutará automáticamente ambas herramientas en secuencia: primero obtendrá las coordenadas del Retiro y luego consultará la temperatura en esas coordenadas.

Esquemas avanzados con Pydantic

Para herramientas con entradas más complejas, puedes definir el esquema usando modelos Pydantic. Esto proporciona validación automática y descripciones detalladas de cada campo:

from pydantic import BaseModel, Field
from typing import Literal

class ConsultaClimaInput(BaseModel):
    """Esquema de entrada para consultas de clima."""
    ubicacion: str = Field(description="Nombre de la ciudad o coordenadas")
    unidades: Literal["celsius", "fahrenheit"] = Field(
        default="celsius",
        description="Unidad de temperatura preferida"
    )
    incluir_pronostico: bool = Field(
        default=False,
        description="Incluir pronóstico de los próximos días"
    )

@tool(args_schema=ConsultaClimaInput)
def consultar_clima(ubicacion: str, unidades: str = "celsius", incluir_pronostico: bool = False) -> str:
    """Obtiene el clima actual y opcionalmente el pronóstico."""
    temp = 22 if unidades == "celsius" else 72
    resultado = f"Clima en {ubicacion}: {temp}° {unidades[0].upper()}"
    
    if incluir_pronostico:
        resultado += "\nPróximos 5 días: Soleado"
    
    return resultado

El uso de Pydantic permite al modelo entender mejor la estructura de los datos esperados y genera llamadas más precisas a las herramientas.