Crie um agente LangGraph limitado para diagnosticar incidentes de API

A decisão: diagnosticar automaticamente, remediar com critério

Um agente para incidentes de API pode economizar tempo ao coletar evidências de logs, verificações de integridade e metadados de implantações recentes. Ele não deve reiniciar serviços, reverter versões ou alterar configurações sem avisar. Um projeto mais seguro separa o diagnóstico somente leitura da remediação com efeitos colaterais, limita o trabalho do agente e deixa visíveis ao operador as evidências ausentes ou as falhas.

Este é um projeto prático, não uma integração testada nem um serviço pronto para produção. Os corpos das ferramentas abaixo são ilustrativos: substitua-os pelos seus próprios clientes de observabilidade autenticados e com permissões limitadas.

Pré-requisitos e fluxo de trabalho

Você precisa de Python, de um modelo de chat compatível com LangGraph configurado na sua aplicação e de funções cliente para os sistemas de diagnóstico que já utiliza. Este exemplo pressupõe que essas funções retornem dados ou gerem exceções. Ele não pressupõe um provedor de modelo, endpoint ou integração de ferramentas específico.

Uma execução útil para investigar um incidente segue um ciclo restrito:

1. Colete um pequeno conjunto predefinido de sinais para o serviço afetado e o intervalo de tempo relevante.
2. Classifique cada resultado como bem-sucedido, com falha ou indisponível.
3. Peça ao modelo que resuma as evidências e identifique o que ainda é desconhecido.
4. Interrompa após um número limitado de etapas do grafo; solicite revisão humana antes de qualquer ação que altere o estado.

O campo de status tem uma finalidade operacional: uma consulta de logs com falha não pode parecer uma busca bem-sucedida sem eventos correspondentes.

Defina ferramentas de diagnóstico com sinais explícitos de falha

Mantenha o contrato das ferramentas restrito. Exija o nome do serviço e um intervalo de tempo limitado; evite dar ao modelo acesso arbitrário a consultas quando uma consulta fixa for suficiente. Retorne resultados estruturados para que os nós seguintes e o relatório do incidente possam distinguir evidências vazias de uma falha na ferramenta.

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)

Adicione ferramentas separadas para verificações de integridade ou metadados de implantação, usando o mesmo formato de resultado. Não capture todas as exceções para retornar uma string vazia: preserve contexto de erro suficiente para diagnosticar uma integração com problemas, sem expor segredos ou dados confidenciais nos logs e no contexto do modelo.

Limite a execução e mostre quando ela estiver incompleta

Para um agente criado com create_agent do LangGraph, defina um limite de recursão do grafo na chamada. O limite restringe as etapas do grafo; não garante uma resposta útil nem substitui os timeouts das ferramentas. Trate o caso em que o limite é atingido na aplicação que envolve o agente e retorne um status claro de “incompleto”, em vez de considerar a execução um diagnóstico concluído.

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__}

O valor do limite é apenas um exemplo, não uma recomendação universal. Escolha-o de acordo com o número de ferramentas e de interações com o modelo permitidas e adicione timeouts e limites de tamanho de solicitação nas camadas das ferramentas e da aplicação. Registre o ID da execução, o serviço e o intervalo de tempo selecionados, as ferramentas acionadas, o status de cada ferramenta e o motivo do encerramento. Esses sinais permitem que o operador diferencie “nenhum erro encontrado” de “o backend de logs atingiu o tempo limite”.

Inclua revisão humana antes da remediação

Se, mais adiante, você adicionar ferramentas que alterem o estado de produção, controle-as com o middleware human-in-the-loop do LangChain e um checkpointer. O middleware documentado pode pausar chamadas de ferramentas selecionadas para aprovação, edição, rejeição ou resposta direta. O estado é salvo para que a execução possa ser retomada após uma decisão; em produção, é necessário usar um checkpointer persistente, em vez da opção em memória apresentada para prototipagem. Consulte a documentação do LangChain sobre human-in-the-loop.

Uma política prática é permitir diagnósticos somente leitura sem interrupção e exigir aprovação para ferramentas de reinicialização, reversão ou alteração de configuração. Rejeite uma ação proposta quando não a aprovar; a documentação alerta que “respond” serve para agir como a ferramenta, não para negar uma chamada com efeitos colaterais. Valide os argumentos editados na implementação das suas ferramentas: o middleware documentado não verifica as edições em relação ao esquema exibido.

Casos de falha a considerar

• Resultados vazios: Informe “nenhum evento correspondente retornado”, não “o serviço está íntegro”.
• Timeout da ferramenta ou falha de autorização: Preserve a fonte que falhou e a categoria do erro; não repita a tentativa indefinidamente sem avisar.
• Chamadas repetidas à ferramenta: Limite a execução do grafo e restrinja as entradas das ferramentas. Se adicionar novas tentativas, defina uma política explícita e pequena e mostre a contagem de tentativas.
• A interrupção não pode ser retomada: Verifique se há um checkpointer configurado e se o mesmo identificador de thread é usado ao retomar. A documentação de referência exige checkpointing para a revisão humana.
• Resumo final enganoso: Exija que as afirmações do relatório façam referência aos sinais coletados e liste as fontes indisponíveis e as questões não resolvidas.

Lista de verificação da execução do incidente

Antes da implantação, confirme que as ferramentas de diagnóstico são somente leitura e têm escopo definido; que os intervalos de tempo e o volume de consultas são limitados; que os erros das ferramentas continuam observáveis; que a execução do grafo tem um limite; e que cada ação com efeitos colaterais é pausada para uma decisão humana. Teste os caminhos de timeout, resultado vazio, ação rejeitada e retomada após interrupção. Um bom agente não se limita a propor uma causa raiz plausível: ele mostra quais evidências realmente obteve e até onde seu diagnóstico chega.

Fontes

• LangChain: middleware human-in-the-loop — decisões de interrupção, revisão condicional de ferramentas, checkpointing e retomada de execuções pausadas.