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.
Resumen · TL;DR
Usa el middleware de LangGraph con intervención humana para pausar llamadas sensibles a herramientas, revisarlas o rechazarlas y reanudar la ejecución desde un punto de control. Combina este flujo de trabajo con límites estrictos para las herramientas, aislamiento de credenciales y un límite de ejecución.
Puntos clave
- Mantén las credenciales dentro de las implementaciones de las herramientas y pasa al modelo solo los argumentos mínimos que necesita.
- Exige revisión humana para las consultas o escrituras sensibles, pero permite que las lecturas seguras continúen.
- Usa un punto de control persistente y un ID de hilo estable para reanudar el trabajo interrumpido.
- Limita la ejecución del grafo y haz que las herramientas sean idempotentes o seguras para reintentar de forma independiente.
- Trata el estado guardado en puntos de control y las cargas útiles de interrupción como datos sensibles.
En esta página (5)
Un agente que protege la privacidad no debería depender del modelo para decidir si una llamada a una herramienta es segura. Mantén las credenciales fuera de la conversación, limita lo que puede hacer cada herramienta y pausa las acciones sensibles para que las revise una persona. El middleware de LangGraph con intervención humana proporciona el mecanismo para pausar y reanudar; aun así, tu aplicación debe definir cómo se manejan los datos, la autorización y los límites de ejecución.
Esta guía crea un patrón sencillo para un agente que puede leer registros de clientes y solicitar un cambio en una base de datos. El código es ilustrativo y no se ha probado aquí. Antes de implementarlo, comprueba que las versiones de los paquetes y las firmas de las herramientas sean compatibles con tu entorno.
1. Separa el contexto del modelo de las credenciales
No incluyas contraseñas, claves de API, cookies de sesión ni credenciales de bases de datos sin restricciones en las instrucciones ni en los argumentos de las herramientas. En su lugar, proporciona a las herramientas operaciones limitadas y haz que obtengan las credenciales de los mecanismos de gestión de secretos de tu aplicación cuando se ejecuten. El modelo solo debería ver los datos necesarios para elegir una acción.
Por ejemplo, es preferible una herramienta como find_customer_record(customer_id) a otra de propósito general que acepte SQL arbitrario y datos de conexión. Valida la autorización en la propia herramienta: la solicitud de un usuario no demuestra que tenga permiso para acceder al registro solicitado.
La revisión humana es un control adicional, no un sistema de autorización. Quienes revisan las solicitudes deben ver lo suficiente para tomar una decisión, pero evita mostrar datos personales o secretos innecesarios en las pantallas de revisión y los registros.
2. Configura la revisión de acciones sensibles
La documentación de LangChain sobre intervención humana describe un middleware que comprueba las llamadas a herramientas según una política. Las llamadas que coinciden con los criterios pueden interrumpir la ejecución; un punto de control guarda el estado del grafo para que la ejecución pueda reanudarse más tarde. Entre las decisiones documentadas están aprobar, editar los argumentos, rechazar con comentarios y responder a una herramienta que plantea una pregunta al usuario.
Esta configuración es ilustrativa. Sustituye las herramientas de ejemplo por implementaciones que apliquen las reglas de acceso y la validación de entradas de tu aplicación.
from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver
agent = create_agent(
model="YOUR_CONFIGURED_MODEL",
tools=[read_customer_record, update_customer_record],
middleware=[
HumanInTheLoopMiddleware(
interrupt_on={
"read_customer_record": False,
"update_customer_record": {
"allowed_decisions": ["approve", "edit", "reject"]
},
},
description_prefix="Review requested customer-data change",
),
],
# For production, use a persistent checkpointer appropriate to your stack.
checkpointer=InMemorySaver(),
)
InMemorySaver sirve para crear prototipos, pero no permite una recuperación duradera después de reiniciar el proceso. La documentación exige un punto de control para las interrupciones que requieren revisión humana y menciona opciones persistentes como AsyncPostgresSaver y MongoDBSaver. Elige un almacenamiento con controles de acceso, reglas de retención y cifrado adecuados para los datos que guardes en los puntos de control. Un punto de control puede contener mensajes y argumentos de herramientas, por lo que podría incluir datos sensibles de usuarios aunque no contenga credenciales.
Si solo algunas llamadas requieren revisión, la documentación también admite un predicado when para las interrupciones condicionales (requiere langchain>=1.3.3). Por ejemplo, podrías pausar una escritura fuera de un espacio de trabajo aprobado o una consulta que no sea de solo lectura. No consideres que una comprobación de prefijos de cadena sea una política de seguridad SQL completa; aplica operaciones seguras también en las capas de la base de datos y las herramientas.
3. Pausa, revisa y reanuda la misma ejecución
Usa un ID de hilo estable para que la aplicación pueda asociar la revisión pendiente con la conversación correcta. Protege ese identificador y la interfaz de revisión: tener un ID de hilo no debería conceder permiso para aprobar una acción.
from langgraph.types import Command
config = {"configurable": {"thread_id": "conversation-123"}}
result = agent.invoke(
{"messages": [{"role": "user", "content": "Update this customer's address"}]},
config=config,
version="v2",
)
if result.interrupts:
# Present the requested action to an authenticated reviewer.
# Resume only after recording that reviewer's decision.
result = agent.invoke(
Command(resume={"decisions": [{"type": "reject", "message": "Verify the request first."}]}),
config=config,
version="v2",
)
Cuando se pausan varias llamadas a herramientas, el orden de las decisiones debe coincidir con el orden de las acciones en la solicitud de interrupción. Usa reject para denegar una acción que tenga efectos secundarios. La documentación advierte que respond proporciona un resultado sintético de herramienta; sirve para responder a una herramienta del tipo «preguntar al usuario», no para denegar una escritura.
4. Limita la ejecución y diseña para la recuperación
Una pausa para revisión no impide por sí sola que el modelo siga solicitando herramientas. Establece un límite de recursión del grafo para las invocaciones y gestiona el error que se produce al alcanzar ese límite como una detención controlada. El límite exacto dependerá de la carga de trabajo: elígelo según la secuencia máxima útil de pasos del modelo y las herramientas, y prueba qué ocurre al llegar al límite.
config = {
"configurable": {"thread_id": "conversation-123"},
"recursion_limit": 12,
}
Esta configuración ilustrativa limita los pasos del grafo; no garantiza que las herramientas sean rápidas, que sus resultados sean pequeños ni que no se repitan los efectos secundarios externos. Añade tiempos de espera a las llamadas de red y a las de bases de datos, limita los resultados de las herramientas y valida las entradas. Para las operaciones que se puedan reintentar, usa controles de idempotencia o comprueba el estado actual antes de aplicar un cambio. Si una ejecución falla después de que una herramienta haya terminado correctamente, pero antes de que el agente registre el resultado, un reintento a ciegas podría realizar la operación dos veces.
Al recuperar una ejecución, reanuda el mismo hilo guardado en el punto de control solo después de verificar que la acción pendiente y su autorización siguen siendo válidas. Si los permisos del usuario o el registro subyacente cambiaron mientras la revisión estaba pendiente, rechaza la acción o vuelve a validarla en vez de ejecutarla con argumentos desactualizados.
5. Lista de comprobación de privacidad y gestión de errores
Antes de pasar a producción, confirma que:
- Las implementaciones de las herramientas obtienen las credenciales de forma privada y nunca las devuelven en resultados de herramientas ni en mensajes de error.
- Cada herramienta aplica la autorización del usuario y acepta únicamente los argumentos más limitados que resulten útiles.
- Los puntos de control, las cargas útiles de interrupción, los registros y las pantallas de revisión cuentan con controles definidos de acceso y retención.
- Quienes revisan pueden identificar el objetivo y las consecuencias sin ver datos personales que no sean pertinentes.
- Los rechazos no ejecutan la herramienta y los reintentos no duplican los efectos secundarios.
- Las ejecuciones tienen límites de pasos, tiempos de espera para las herramientas, límites de resultados y una forma clara de informar sobre el trabajo interrumpido o fallido.
La decisión de diseño clave es tratar la aprobación humana como un punto de control dentro de un flujo de trabajo seguro, no como sustituto del mínimo privilegio, la minimización de datos ni la validación en las herramientas.
FAQ
¿El middleware de LangGraph con intervención humana guarda el estado pausado del agente?
Usa la persistencia de LangGraph para guardar el estado durante una interrupción. Se necesita un punto de control y, en entornos de producción, se debería elegir almacenamiento persistente y aplicar controles adecuados de acceso y retención.
¿Debería usar la decisión `respond` para rechazar una llamada sensible a una herramienta?
No. Según el comportamiento documentado, `respond` proporciona un resultado sintético satisfactorio de la herramienta y está pensado para situaciones como responder a una herramienta que pregunta al usuario. Usa `reject` para denegar una acción que tenga efectos secundarios.
¿Cómo mantengo privadas las credenciales en un agente de LangGraph?
Mantén las credenciales en el entorno de ejecución de la herramienta o en la capa de gestión de secretos. No las incluyas en instrucciones, argumentos de herramientas visibles para el modelo, resultados de herramientas, mensajes de interrupción ni registros.
¿La aprobación humana impide que un agente se ejecute indefinidamente?
No. El middleware de aprobación gestiona la revisión de las llamadas a herramientas configuradas. Añade por separado un límite de ejecución, tiempos de espera para las herramientas, límites de resultados y un comportamiento seguro para los reintentos.
Artículos relacionados
Guides
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.
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.
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.