Diseña tu primer grafo de agente con nodos y aristas

Concepto clave

En LangGraph, un grafo de agente es una representación visual y programática de cómo un agente de IA toma decisiones secuenciales. Imagina que estás construyendo un asistente virtual para un banco: el grafo define el flujo desde que el usuario pregunta "¿Cuál es mi saldo?" hasta que el agente consulta la base de datos y responde. Cada nodo representa un estado o acción (como "procesar consulta" o "ejecutar herramienta"), y las aristas son las transiciones entre ellos, determinadas por condiciones lógicas.

La arquitectura se basa en grafos dirigidos donde los nodos pueden ser funciones Python decoradas con @node, y las aristas se definen con add_edge() o add_conditional_edges(). Esto permite modelar agentes que no solo responden linealmente, sino que ramifican su comportamiento según el contexto, similar a cómo un conductor navega: en un cruce (nodo), decide girar (arista) basado en las señales (condiciones).

Cómo funciona en la práctica

Para diseñar tu primer grafo, sigue estos pasos con un ejemplo de agente de soporte técnico:

1. Define el estado del agente usando Pydantic, incluyendo memoria como historial de conversación.
2. Crea nodos clave: receive_input (recibe la pregunta del usuario), classify_intent (clasifica la intención usando un LLM), use_tool (ejecuta una herramienta como buscar en una base de datos), y generate_response (genera la respuesta final).
3. Conecta los nodos con aristas: desde receive_input a classify_intent siempre, luego condicionalmente a use_tool si se necesita una herramienta, o directamente a generate_response si no.
4. Implementa la lógica de cada nodo; por ejemplo, use_tool podría llamar a una función que consulta una API externa.

Aquí un fragmento de código ilustrativo:

from langgraph.graph import StateGraph, END

graph = StateGraph(AgentState)
graph.add_node("clasificar", classify_intent)
graph.add_node("herramienta", use_tool)
graph.add_edge("clasificar", "herramienta")
graph.add_conditional_edges("herramienta", should_continue)

Caso de estudio

Considera un agente para un e-commerce que maneja consultas de pedidos. El grafo incluye:

Las aristas condicionales verifican si el ID es válido; si no, el grafo redirige a un nodo de error. Este diseño reduce las llamadas a herramientas innecesarias en un 40%, según datos de implementación real.

En producción, los grafos con 4-7 nodos optimizados logran latencias menores a 2 segundos para el 95% de las consultas.

Errores comunes

• Ciclos infinitos: Conectar nodos sin una condición de salida clara, como un bucle entre "clasificar" y "herramienta". Solución: Usa add_conditional_edges() con una función que evalúe a END después de intentos máximos.
• Estado sobredimensionado: Incluir demasiados campos en el estado, ralentizando el grafo. Solución: Mantén solo datos esenciales como historial y resultados de herramientas.
• Falta de manejo de errores: No prever fallos en herramientas externas. Solución: Añade un nodo "manejar_error" que reintente o degrade la funcionalidad.
• Aristas no determinísticas: Condiciones basadas en salidas de LLM sin umbrales claros, causando comportamientos impredecibles. Solución: Usa reglas basadas en confianza (ej., si confianza > 0.8, ir a "herramienta").

Checklist de dominio

1. ¿Definiste el estado del agente con tipos estrictos (ej., usando Pydantic)?
2. ¿Cada nodo tiene una responsabilidad única y clara (ej., procesamiento, herramienta, respuesta)?
3. ¿Las aristas incluyen condiciones para ramificar el flujo basado en datos del estado?
4. ¿Integraste al menos una herramienta externa (ej., API o base de datos) en un nodo?
5. ¿Probaste el grafo con entradas variadas para cubrir todos los caminos posibles?
6. ¿Documentaste el diseño del grafo con un diagrama o comentarios en el código?
7. ¿Optimizaste el estado para evitar datos redundantes y mejorar el rendimiento?

Construye un grafo de agente para un asistente de reservas de hotel

En este ejercicio, crearás un grafo de LangGraph para un agente que maneja reservas de hotel, usando herramientas y memoria. Sigue estos pasos:

1. Define una clase HotelState con Pydantic que incluya: user_query (str), intent (str, opcional), tool_result (dict, opcional), y response (str, opcional).
2. Implementa cuatro nodos:
   • parse_input: Extrae detalles como destino y fechas de la consulta del usuario usando una expresión regular simple.
   • determine_intent: Clasifica la intención en "reservar", "consultar" o "cancelar" basado en palabras clave.
   • call_booking_api: Simula una herramienta que, si la intención es "reservar", devuelve un ID de reserva aleatorio; de lo contrario, devuelve null.
   • generate_output: Genera una respuesta amigable basada en el resultado de la herramienta o un mensaje de error.
3. Construye el grafo conectando los nodos: desde parse_input a determine_intent siempre, luego condicionalmente a call_booking_api solo si la intención es "reservar", y finalmente a generate_output.
4. Prueba el grafo con al menos tres consultas: "Quiero reservar en Madrid del 1 al 5 de junio", "¿Cuál es mi reserva?", y "Cancelar mi viaje".

• Usa add_conditional_edges() para la transición después de determine_intent, con una función que verifique el valor de intent.
• Para simular la herramienta, en call_booking_api, devuelve un diccionario como {"booking_id": "12345"} si corresponde.
• Asegúrate de que el estado se actualice en cada nodo; por ejemplo, guarda el intent en determine_intent.

Evalua tu comprension

Completa el quiz interactivo de arriba para ganar XP.