Lección 3 de 20 · Lectura y práctica

Integración de herramientas externas en tu agente

Tipo de lección: VideoConcepto claveLa integración de herramientas externas transforma a tu agente de un simple procesador de texto en un sistema capaz de interactuar con el mundo real. Imagina a un asistente personal que no solo.

Del concepto a la práctica

Taller de esta lección

Una herramienta debe tratarse como un contrato: recibe parámetros validados, devuelve una estructura conocida y comunica el fallo sin ocultarlo. En esta ampliación usarás una herramienta local simulada para distinguir la decisión de invocarla del resultado que produce.

Ejemplo resuelto

python

def consultar_catalogo(codigo):
    if not isinstance(codigo, str) or not codigo.strip():
        return {"ok": False, "error": "codigo_invalido"}
    datos = {"A1": {"stock": 4}, "B2": {"stock": 0}}
    if codigo not in datos:
        return {"ok": False, "error": "no_encontrado"}
    return {"ok": True, "dato": datos[codigo]}

print(consultar_catalogo("B2"))
# {'ok': True, 'dato': {'stock': 0}}

Distingue función de herramienta y nodo envolvente. Puedes ejecutar la función desde un nodo determinista sin usar un modelo. Con tool calling, valida nombre/argumentos y asocia cada resultado al tool_call_id correspondiente; una lista de texto sin esa relación no equivale a mensajes de herramientas. El registro no debe contener secretos, y el permiso debe comprobarse en servidor antes de leer cada recurso.

Pruébalo

Define el contrato con ok, dato y error.
Valida que el código sea texto no vacío.
Registra cada llamada en herramientas_usadas.
Envía el resultado a un nodo que decida la siguiente ruta.

Un error frecuente es devolver una lista vacía tanto para “sin resultados” como para “fallo”. Corrígelo usando estados distintos, porque la ruta de recuperación no debe confundirse con una respuesta válida.

Comprueba tu resultado

A1 debe devolver ok: True y stock 4; Z9 debe devolver ok: False con error no_encontrado, sin lanzar una excepción.

Bucle de estado, herramienta y resultado, con revisión humana antes de una acción de alto impacto. — **Un agente necesita límites**
Un agente mantiene un estado y utiliza herramientas dentro de límites definidos. El resultado de cada herramienta actualiza ese estado para decidir el siguiente paso. Las acciones de alto impacto deben pasar por una revisión humana antes de ejecutarse.
Ver la infografía en tamaño completo ↗

Tipo de lección: Video

Concepto clave

La integración de herramientas externas transforma a tu agente de un simple procesador de texto en un sistema capaz de interactuar con el mundo real. Imagina a un asistente personal que no solo entiende tus peticiones, sino que puede consultar tu calendario, enviar correos o buscar información en tiempo real. En LangGraph, las herramientas son funciones que tu agente puede invocar para realizar acciones específicas, como llamar a una API, consultar una base de datos o ejecutar código.

La arquitectura clave aquí es el ciclo de decisión condicional: tu agente analiza el estado actual, decide si necesita usar una herramienta, la ejecuta, y luego procesa los resultados antes de tomar la siguiente decisión. Esto crea un flujo dinámico donde el agente puede adaptarse en tiempo real a la información que recibe, similar a cómo un conductor decide cambiar de carril basándose en el tráfico que observa.

Cómo funciona en la práctica

Veamos un ejemplo paso a paso de integración de una herramienta de búsqueda web:

Primero, defines la herramienta como una función Python que acepta parámetros específicos y devuelve resultados estructurados.
Registras esta herramienta en tu grafo LangGraph usando el decorador @tool o el método add_tool().
Configuras los nodos de tu grafo para que, cuando el agente detecte que necesita información externa, invoque la herramienta apropiada.
El grafo maneja automáticamente la ejecución y pasa los resultados al siguiente nodo para procesamiento.

Ejemplo de código básico:

from langgraph.prebuilt import ToolNode
from langchain.tools import DuckDuckGoSearchRun

# Definir herramienta
search_tool = DuckDuckGoSearchRun()

# Integrar en grafo
tool_node = ToolNode(tools=[search_tool])
graph.add_node("search", tool_node)

Caso de estudio

Implementemos un agente de investigación de mercado que use tres herramientas:

Herramienta	Propósito	API/Origen
Búsqueda web	Obtener noticias recientes	DuckDuckGo
Consulta financiera	Obtener datos de acciones	Alpha Vantage API
Análisis de sentimiento	Procesar texto de noticias	Modelo local HuggingFace

El flujo del agente:

Recibe consulta: "Analiza el impacto de las nuevas regulaciones en Tesla"
Invoca búsqueda web para obtener artículos recientes
Ejecuta análisis de sentimiento en los resultados
Consulta precios históricos de acciones de Tesla
Sintetiza todos los datos en un reporte coherente

La clave del éxito está en el manejo adecuado de los errores de API y el tiempo de espera entre llamadas.

Errores comunes

Falta de validación de entrada: No verificar que los parámetros pasados a las herramientas sean válidos, causando fallos en APIs externas.
Manejo pobre de errores: No implementar reintentos o fallback cuando una herramienta falla, deteniendo todo el flujo.
Dependencias circulares: Crear ciclos donde el agente llama repetidamente a la misma herramienta sin progresar.
Exceso de herramientas: Agregar demasiadas herramientas hace lenta la decisión y confunde al agente.
Falta de límites de costo: No limitar llamadas a APIs pagadas, resultando en gastos inesperados.

Checklist de dominio

Puedo definir al menos 3 tipos diferentes de herramientas (API, base de datos, cálculo)
Sé configurar timeouts y reintentos para llamadas a herramientas
Implemento validación de parámetros antes de invocar herramientas
Uso el estado de LangGraph para pasar resultados entre herramientas
Configuro límites de costo y uso para APIs externas
Pruebo fallos de herramientas y verifico que el agente se recupere
Documento el propósito y parámetros de cada herramienta

Construye un agente de reservas de vuelos con herramientas múltiples

Objetivo

Crea un agente que pueda buscar vuelos, verificar disponibilidad y calcular precios usando herramientas externas.

Pasos

Define tres herramientas:
- search_flights(origin, destination, date): Simula búsqueda en una API de vuelos (puedes usar datos mock)
- check_availability(flight_id): Verifica si hay asientos disponibles
- calculate_price(flight_id, passengers): Calcula el precio total con impuestos
Crea un grafo LangGraph con:
- Nodo inicial que parsea la consulta del usuario
- Nodo de herramientas que puede invocar cualquiera de las tres
- Nodo de decisión que determina qué herramienta usar basado en el estado
- Nodo final que formatea la respuesta
Implementa lógica para:
- Si el usuario pregunta "Vuelos de Madrid a Barcelona el 15 de junio", invocar search_flights
- Si luego pregunta "¿Hay disponibilidad en el vuelo IB123?", invocar check_availability
- Si pregunta precio para 2 pasajeros, invocar calculate_price
Agrega manejo de errores:
- Si una herramienta falla, el agente debe informar al usuario y sugerir alternativas
- Implementa timeout de 10 segundos para cada llamada
Prueba con al menos 3 consultas diferentes y verifica que el flujo funcione correctamente.

Pistas

Usa diccionarios Python para simular respuestas de API si no quieres configurar APIs reales
Considera agregar un nodo de 'fallback' que se active cuando ninguna herramienta es apropiada
Implementa un contador en el estado para limitar el número máximo de llamadas a herramientas por sesión

Evalua tu comprension

Completa el quiz interactivo de arriba para ganar XP.

Sigue con LangGraph para Automatización: Memoria, Estado y Decisiones

Esta lección forma parte de un curso de Cursalo. Revisa su programa y elige entre la compra individual o el acceso a toda la escuela.

Ver curso y opciones de acceso Ya soy estudiante

Si ya tenías acceso a este curso, entra con tu cuenta: tus derechos y tu progreso se conservan. No necesitas comprarlo de nuevo.

← Anterior: Diseño de nodos y aristas para flujos de decisión Siguiente: Práctica: Construye un agente básico que use una API →Entrar y guardar mi progreso