Crea un agente LangGraph con ejecución acotada para diagnosticar incidentes de API

La decisión: diagnosticar automáticamente, remediar con criterio

Un agente para incidentes de API puede ahorrar tiempo al recopilar evidencia de registros, comprobaciones de estado y metadatos de implementaciones recientes. No debería reiniciar servicios, revertir versiones ni cambiar la configuración sin avisar. Un diseño más seguro separa el diagnóstico de solo lectura de la remediación con efectos secundarios, limita el trabajo del agente y hace visibles al operador los fallos o la falta de evidencia.

Este es un diseño práctico, no una integración probada ni un servicio listo para producción. Los cuerpos de las herramientas que aparecen a continuación son ilustrativos: sustitúyelos por tus propios clientes de observabilidad autenticados y con permisos limitados.

Requisitos previos y flujo de trabajo

Necesitas Python, un modelo de chat compatible con LangGraph configurado en tu aplicación y funciones cliente para los sistemas de diagnóstico que ya utilizas. Este ejemplo presupone que esas funciones cliente devuelven datos o generan excepciones. No presupone ningún proveedor de modelos, endpoint ni integración de herramientas en particular.

Una ejecución útil para un incidente sigue un ciclo acotado:

1. Recopilar un conjunto pequeño y predefinido de señales para el servicio afectado y el intervalo de tiempo correspondiente.
2. Marcar cada resultado como correcto, fallido o no disponible.
3. Pedir al modelo que resuma la evidencia e identifique qué aspectos siguen sin conocerse.
4. Detenerse tras un número limitado de pasos del grafo y solicitar revisión humana antes de cualquier acción que cambie el estado.

El campo de estado tiene una finalidad operativa: una consulta de registros fallida no debe parecer una búsqueda correcta sin eventos coincidentes.

Define herramientas de diagnóstico con señales explícitas de fallo

Mantén acotado el contrato de las herramientas. Exige el nombre del servicio y un intervalo de tiempo limitado; evita dar al modelo acceso arbitrario a consultas cuando baste con una consulta fija. Devuelve resultados estructurados para que los nodos posteriores y el informe del incidente puedan distinguir entre falta de evidencia y fallo de una herramienta.

from typing import Literal, TypedDict
from langchain.tools import tool

class Signal(TypedDict):
    status: Literal["ok", "error", "unavailable"]
    source: str
    data: str
    error: str | None


def query_logs(service: str, minutes: int) -> Signal:
    if not 1 <= minutes <= 60:
        return {
            "status": "error", "source": "logs", "data": "",
            "error": "minutes must be between 1 and 60",
        }
    try:
        # Replace with a read-only, scoped observability client call.
        rows = logs_client.search(service=service, minutes=minutes)
        return {
            "status": "ok", "source": "logs",
            "data": str(rows), "error": None,
        }
    except TimeoutError as exc:
        return {
            "status": "unavailable", "source": "logs", "data": "",
            "error": f"timeout: {exc}",
        }

@tool
def inspect_api(service: str, minutes: int = 15) -> dict:
    """Collect scoped, read-only API incident signals."""
    return query_logs(service, minutes)

Añade herramientas independientes para las comprobaciones de estado o los metadatos de implementaciones, con la misma estructura de resultados. No captures todas las excepciones para devolver una cadena vacía: conserva suficiente contexto del error para diagnosticar una integración averiada, pero evita incluir secretos o cargas útiles sensibles en los registros o en el contexto del modelo.

Limita la ejecución y haz visibles las ejecuciones incompletas

Para un agente creado con create_agent de LangGraph, establece un límite de recursión del grafo al invocarlo. El límite restringe los pasos del grafo; no garantiza una respuesta útil ni sustituye los tiempos de espera de las herramientas. Gestiona en la aplicación que lo rodea el caso en que se alcance el límite y devuelve un estado claro de «incompleto» en lugar de tratar la ejecución como un diagnóstico terminado.

from langchain.agents import create_agent

agent = create_agent(
    model=your_configured_chat_model,
    tools=[inspect_api],
    system_prompt=(
        "Diagnose API incidents using available evidence. "
        "Report each source as ok, error, or unavailable. "
        "Do not claim a cause without supporting evidence. "
        "Do not perform remediation."
    ),
)

try:
    result = agent.invoke(
        {"messages": [{"role": "user", "content":
            "Investigate elevated errors for payments-api over the last 15 minutes."}]},
        config={"recursion_limit": 12},
    )
except Exception as exc:
    # Map known graph-limit and provider/tool failures to your app's
    # incident-run status; do not expose credentials or raw secrets.
    result = {"status": "incomplete", "reason": type(exc).__name__}

El valor del límite es un ejemplo, no una recomendación universal. Elige uno según la cantidad de herramientas e interacciones con el modelo que permitas, y añade tiempos de espera y límites de tamaño de las solicitudes en las capas de herramientas y de aplicación. Registra el ID de ejecución, el servicio y el intervalo de tiempo seleccionados, las herramientas utilizadas, el estado de cada herramienta y el motivo de finalización. Esas señales permiten al operador distinguir entre «no se encontraron errores» y «se agotó el tiempo de espera del sistema de registros».

Añade revisión humana antes de la remediación

Si más adelante añades herramientas que modifican el estado de producción, protégelas con el middleware human-in-the-loop de LangChain y un checkpointer. El middleware documentado puede pausar las llamadas a herramientas seleccionadas para permitir su aprobación, edición, rechazo o una respuesta directa. Su estado se guarda para que la ejecución pueda reanudarse después de tomar una decisión; para usarlo en producción se necesita un checkpointer persistente, no la opción en memoria que se muestra para crear prototipos. Consulta la documentación de LangChain sobre human-in-the-loop.

Una política práctica permite ejecutar diagnósticos de solo lectura sin interrupciones y exige aprobación para las herramientas de reinicio, reversión o cambio de configuración. Rechaza una acción propuesta cuando la deniegues; la documentación advierte que «respond» sirve para actuar como la herramienta, no para denegar una llamada con efectos secundarios. Valida los argumentos editados en tu propia implementación de la herramienta: el middleware documentado no comprueba las ediciones con respecto al esquema que se muestra.

Casos de fallo que debes prever

• Resultados vacíos: Informa «no se devolvieron eventos coincidentes», no «el servicio está en buen estado».
• Tiempo de espera agotado o fallo de autorización de una herramienta: Conserva la fuente que falló y la categoría del error; no reintentes indefinidamente sin avisar.
• Llamadas repetidas a herramientas: Limita la ejecución del grafo y restringe las entradas de las herramientas. Si añades reintentos, define una política explícita con pocos intentos y muestra el número de intentos.
• No se puede reanudar una interrupción: Comprueba que haya un checkpointer configurado y que se use el mismo identificador de hilo al reanudar. La documentación de origen exige el uso de puntos de control para la revisión humana.
• Resumen final engañoso: Exige que las afirmaciones del informe citen las señales recopiladas y enumera las fuentes no disponibles y las preguntas sin resolver.

Lista de comprobación para la ejecución de incidentes

Antes de implementar, verifica que las herramientas de diagnóstico sean de solo lectura y tengan un alcance limitado; que los intervalos de tiempo y el volumen de consultas estén restringidos; que los errores de las herramientas sigan siendo observables; que la ejecución del grafo tenga un límite; y que cada acción con efectos secundarios se pause para que una persona decida. Prueba las rutas de tiempo de espera agotado, resultado vacío, acción rechazada y reanudación tras una interrupción. Un buen agente no se limita a proponer una causa raíz plausible: muestra qué evidencia obtuvo realmente y hasta dónde llega su diagnóstico.

Fuentes

• LangChain: middleware human-in-the-loop — decisiones de interrupción, revisión condicional de herramientas, puntos de control y reanudación de ejecuciones pausadas.