Construye un agente de LangGraph con llamadas a herramientas acotadas y revisión humana
Un patrón práctico para evaluar un agente de LangGraph que llama a herramientas con límites de pasos explícitos, aprobación humana para acciones de riesgo y casos de prueba repetibles.
Resumen · TL;DR
Usa un límite de pasos del grafo para acotar la ejecución, HumanInTheLoopMiddleware para pausar llamadas a herramientas de riesgo y un pequeño conjunto fijo de pruebas para comprobar el comportamiento de aprobación, rechazo y límite. Considera los ejemplos como un punto de partida: el comportamiento del modelo y de las herramientas debe probarse en tu propio entorno.
Puntos clave
- Un límite de recursión del grafo establece un límite de ejecución claro para un agente; no garantiza que el agente complete su tarea.
- La revisión humana puede pausar la ejecución de herramientas y reanudarla más tarde cuando el grafo tiene un checkpointer y un ID de hilo.
- Mantén las evaluaciones repetibles fijando las entradas de prueba, los resultados esperados, los fixtures de herramientas y el límite de ejecución.
- Prueba explícitamente las acciones rechazadas y el agotamiento del límite; ninguno de los dos equivale a una recuperación correcta.
En esta página (6)
Un agente que llama a herramientas necesita algo más que un buen prompt: necesita un límite de detención, un plan para las acciones de riesgo y pruebas que hagan reproducible su comportamiento. En LangGraph, puedes combinar un límite de recursión del grafo con una revisión human-in-the-loop (HITL) para herramientas seleccionadas. Después, evalúa el flujo de trabajo con casos fijos en lugar de depender de unas pocas ejecuciones exitosas.
El ejemplo siguiente es ilustrativo, no una configuración probada. Supone un entorno de Python con paquetes compatibles de LangChain y LangGraph, un modelo de chat compatible con llamadas a herramientas y una herramienta que hayas implementado. Comprueba las versiones y los parámetros del proveedor del modelo en tu propio entorno.
Elige el límite antes de añadir herramientas
Un límite de recursión acota los pasos de ejecución del grafo. Es un límite de seguridad, no una promesa de que el agente terminará ni un límite preciso del número de llamadas a herramientas: la estructura del grafo influye en cómo se cuentan los pasos. Si la ejecución alcanza el límite, espera un error de recursión del grafo y trátalo como una ejecución incompleta. No lo consideres una respuesta correcta.
Empieza con un límite pequeño durante la evaluación y auméntalo solo cuando un caso de prueba demuestre que el flujo de trabajo necesita más pasos. Mantén también las operaciones de las herramientas acotadas. Un límite a nivel del grafo no puede deshacer un efecto secundario que una herramienta ya haya ejecutado.
Configura una llamada a una herramienta que pueda pausarse para revisión
Este ejemplo usa create_agent con middleware HITL. La herramienta write_file se interrumpe para su aprobación o rechazo; read_data no. Las implementaciones de las herramientas y el nombre del modelo son marcadores de posición. Confirma que el modelo y el endpoint elegidos admitan los parámetros y el comportamiento de llamadas a herramientas que utiliza tu agente.
from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver
# Replace these placeholders with your own tool implementations.
tools = [write_file, read_data]
agent = create_agent(
model="your-tool-capable-chat-model",
tools=tools,
middleware=[
HumanInTheLoopMiddleware(
interrupt_on={
"write_file": {"allowed_decisions": ["approve", "reject"]},
"read_data": False,
}
)
],
checkpointer=InMemorySaver(),
)
config = {
"configurable": {"thread_id": "evaluation-case-001"},
"recursion_limit": 8,
}
result = agent.invoke(
{"messages": [{"role": "user", "content": "Save the approved summary."}]},
config=config,
version="v2",
)
InMemorySaver es adecuado para un prototipo o una prueba que se ejecuta en un solo proceso; no es persistente entre reinicios del proceso. Para un flujo de trabajo desplegado, usa un checkpointer persistente. La guía de HITL de LangChain explica que se necesitan un checkpointer y un ID de hilo para pausar y reanudar una ejecución. Fuente: Human-in-the-loop.
Cuando la ejecución devuelva una interrupción, muestra a un revisor la acción solicitada y sus argumentos. Reanuda el mismo hilo con una decisión. El orden de las decisiones debe coincidir con el orden de las acciones en la interrupción. Rechaza una acción que estés denegando; respond sirve para devolver una respuesta humana como resultado de una herramienta, no para denegar un efecto secundario.
from langgraph.types import Command
# Use the same config, including the same thread ID, to resume.
result = agent.invoke(
Command(resume={"decisions": [{"type": "reject", "message": "Outside the approved scope."}]}),
config=config,
version="v2",
)
Haz que la evaluación sea repetible
Mantén un conjunto de pruebas compacto bajo control de versiones. Cada caso debe especificar la solicitud del usuario, el comportamiento esperado de la herramienta, si se requiere revisión y el estado final esperado. Usa fixtures inocuos o herramientas simuladas para las pruebas; no permitas que los casos de evaluación escriban en archivos reales ni modifiquen datos de producción.
| Caso | Configuración | Resultado esperado |
|---|---|---|
| Lectura segura | Solicitar información mediante read_data | No aparece ninguna interrupción HITL; se devuelve el resultado de la herramienta |
| Escritura revisada | Solicitar una escritura permitida | Aparece una interrupción antes de ejecutar la escritura; la aprobación permite la ejecución |
| Escritura rechazada | Solicitar una escritura y rechazarla después | La herramienta de escritura no se ejecuta; los comentarios del rechazo se devuelven al agente |
| Límite de pasos | Usar un fixture que impida que el flujo de trabajo termine | La ejecución se detiene en el límite configurado y se registra como incompleta |
En cada ejecución, registra el ID del caso, el límite configurado, las llamadas a herramientas, las decisiones de interrupción, el estado de finalización y cualquier error. Compara esos campos con las expectativas. Evita evaluar únicamente la respuesta final en lenguaje natural: un agente puede producir una respuesta plausible después de realizar la acción equivocada.
Gestión de fallos: pausar, rechazar o detener
HITL es una pausa controlada, no un mecanismo general de reintento. Un revisor puede aprobar, editar, rechazar o responder según la política configurada. El rechazo omite la llamada a la herramienta solicitada y devuelve al agente comentarios sobre el rechazo. Que el agente termine, solicite otra acción o falle después depende de su comportamiento posterior, por lo que debes probar ese recorrido.
Si el grafo alcanza su límite de recursión, registra la ejecución como un fallo por límite e inspecciona su estado y el historial de herramientas. No repitas automáticamente una ejecución que quizá ya haya producido efectos secundarios. Haz que las herramientas sean idempotentes cuando sea práctico o exige una comprobación independiente antes de repetir una operación. La documentación proporcionada describe la pausa y reanudación con checkpointing; no establece una recuperación automática frente a fallos arbitrarios de herramientas o modelos.
Lista de comprobación para solucionar problemas
- No aparece ninguna interrupción: Comprueba que el nombre de la herramienta coincida con la asignación
interrupt_ony que su política habilite la revisión. - La reanudación no encuentra la ejecución pausada: Confirma que se usan el mismo checkpointer y el mismo ID de hilo.
- La ejecución se detiene antes de tiempo: Inspecciona el límite de recursión configurado y la ruta del grafo; aumenta el límite solo cuando un caso de prueba lo justifique.
- Parece que se ha realizado una acción rechazada: Verifica que la herramienta no se invocara antes de la revisión y que el revisor usara
reject, norespond. - Las pruebas varían entre ejecuciones: Fija los fixtures de las herramientas y las entradas de prueba, y controla o simula las respuestas del modelo cuando tu configuración lo permita. Una entrada fija por sí sola no hace determinista la salida del modelo.
La regla práctica
Usa el límite de recursión para acotar el trabajo del grafo, HITL para controlar las llamadas a herramientas con consecuencias y un conjunto pequeño y explícito de pruebas para verificar tanto el recorrido correcto como los recorridos de fallo. Trata las ejecuciones interrumpidas, rechazadas y detenidas por agotamiento del límite como resultados distintos. Esa distinción facilita la evaluación de un agente y hace más seguras sus modificaciones.
FAQ
¿El límite de recursión de LangGraph limita el número de llamadas a herramientas?
No exactamente. Limita los pasos de ejecución del grafo, y el número de llamadas a herramientas que caben depende de la estructura del grafo. Trata el agotamiento del límite como una ejecución incompleta y prueba ese límite.
¿Qué se necesita para reanudar una llamada a una herramienta revisada por una persona?
Configura un checkpointer, proporciona un ID de hilo y reanuda usando el mismo hilo y el mismo contexto de persistencia. El revisor proporciona una decisión para cada acción interrumpida.
¿HITL reintenta automáticamente una llamada a una herramienta que ha fallado?
No. El flujo de trabajo HITL documentado pausa para obtener una decisión humana y después ejecuta u omite la acción revisada. No establece reintentos automáticos para fallos arbitrarios de herramientas o modelos.
¿Cómo debo probar una llamada a una herramienta rechazada?
Usa una herramienta inocua o simulada, activa la interrupción, rechaza la acción y comprueba que la herramienta no se haya ejecutado y que la ejecución registre los comentarios del rechazo.
Artículos relacionados
Guides
Crea un agente de LangGraph con protección de la privacidad, aprobación de herramientas y recuperación
Un patrón práctico para usar la revisión humana, los puntos de control, las ejecuciones limitadas y las herramientas que protegen las credenciales en un agente que maneja datos sensibles.
Guides
Llamadas a herramientas en LangGraph con ejecución limitada y recuperación ante fallos
Crea un agente de operaciones de producción con LangGraph que use llamadas a herramientas, límites de reintentos, aprobación humana y rutas de recuperación explícitas en lugar de una ejecución sin límites.
Guides
Crea un agente LangGraph con ejecución acotada para diagnosticar incidentes de API
Crea un agente de LangGraph para diagnosticar incidentes que use herramientas de diagnóstico de solo lectura, limite la ejecución, haga visibles los fallos y se detenga antes de realizar acciones riesgosas.
Guides
Crea un agente de atención al cliente con LangGraph, llamadas a herramientas, aprobación humana y límites de ejecución
Un patrón práctico de LangGraph para clasificar solicitudes de atención al cliente: dirigir solicitudes, llamar a herramientas de consulta, pausar los reembolsos para su aprobación humana y limitar la ejecución del grafo.