GuidesOneMux

Chamadas de ferramentas no LangGraph com execução limitada e recuperação de falhas

Crie um agente de operações de produção com LangGraph que use chamadas de ferramentas, limites de tentativas, aprovação humana e caminhos explícitos de recuperação, em vez de execução sem limites.

AI

Resumo · TL;DR

Um agente de operações de produção não deve poder tentar novamente indefinidamente nem repetir efeitos colaterais às cegas. O LangGraph fornece o modelo de grafo e persistência para pausar a execução, enquanto o fluxo de trabalho deve definir limites de tentativas, regras de idempotência, caminhos de escalonamento e estados de recuperação. O HumanInTheLoopMiddleware pode controlar chamadas de ferramentas arriscadas e retomá-las a partir de um checkpoint após aprovação, edição, rejeição ou resposta direta.

Principais pontos

  • Separe falhas transitórias de falhas permanentes antes de decidir se deve tentar novamente.
  • Limite a execução com um orçamento de tentativas por ferramenta e um limite de etapas para o grafo.
  • Use chaves de idempotência em ferramentas que criam, excluem ou modificam recursos de produção.
  • Exija aprovação humana para ações destrutivas ou visíveis externamente.
  • Persista o estado do grafo para que um fluxo interrompido possa ser retomado sem recomeçar do início.
Nesta página (9)

A decisão de projeto: tentar novamente automaticamente ou recuperar de forma deliberada?

Para operações de fluxos de trabalho de produção, o padrão mais seguro não é “tentar novamente após qualquer falha”. Em vez disso:

  1. Tente novamente apenas erros que sejam plausivelmente transitórios.
  2. Pare após um limite pequeno e explícito de tentativas.
  3. Direcione o trabalho cujo limite foi atingido ou cujo resultado seja ambíguo para um estado de recuperação.
  4. Exija aprovação antes de efeitos colaterais que possam ser dispendiosos ou irreversíveis.

O LangGraph é uma boa opção porque o fluxo de trabalho pode representar esses resultados como estados do grafo, em vez de ocultá-los em um único loop grande do agente. O modelo pode propor chamadas de ferramentas, mas o código determinístico decide se uma chamada pode ser executada, repetida, escalada ou ignorada com segurança.

Os exemplos abaixo são padrões ilustrativos. Eles não constituem uma aplicação testada, e as APIs exatas podem variar conforme as versões instaladas do LangGraph e do LangChain.

Pré-requisitos

Você precisa de:

  • Python e pacotes compatíveis do LangGraph e do LangChain.
  • Um modelo de chat que ofereça suporte a chamadas de ferramentas pela integração escolhida.
  • Ferramentas com esquemas de entrada explícitos e tipos de erro previsíveis.
  • Um checkpointer. InMemorySaver é adequado para experimentos; a documentação do LangGraph recomenda um checkpointer persistente, como AsyncPostgresSaver ou MongoDBSaver, para produção.
  • Um thread_id estável para cada execução do fluxo de trabalho.

Não conceda ao modelo acesso irrestrito às credenciais de produção. Implemente autorização, validação, idempotência e política de novas tentativas nas ferramentas ou no middleware.

Defina uma ferramenta com limite de tentativas

O primeiro limite deve ser aplicado à própria operação. Este exemplo tenta novamente apenas um erro transitório classificado e retorna um resultado estruturado quando o limite de tentativas é atingido.

from dataclasses import dataclass
from typing import Literal

class TransientOperationError(Exception):
    pass

class PermanentOperationError(Exception):
    pass

@dataclass
class OperationResult:
    status: Literal["succeeded", "needs_recovery", "failed"]
    attempts: int
    message: str


def run_with_budget(operation, *, max_attempts: int) -> OperationResult:
    for attempt in range(1, max_attempts + 1):
        try:
            operation()
            return OperationResult("succeeded", attempt, "Operation completed")
        except PermanentOperationError as exc:
            return OperationResult("failed", attempt, str(exc))
        except TransientOperationError as exc:
            if attempt == max_attempts:
                return OperationResult(
                    "needs_recovery", attempt,
                    f"Retry budget exhausted: {exc}",
                )

    return OperationResult("needs_recovery", max_attempts, "No attempt was made")

Em operações reais, adicione uma chave de idempotência antes de tentar novamente. Um tempo limite após uma solicitação de implantação não comprova que a implantação não ocorreu. Sem uma chave, uma nova tentativa pode criar um trabalho, chamado, pagamento ou solicitação de alteração duplicado.

Uma tabela de políticas útil seria:

Classe de falhaAção automáticaAção de recuperação
Tempo limite temporário de redeTentar novamente dentro do limiteEscalar com o ID da operação
Limite de taxaTentar novamente conforme as orientações do provedorColocar o fluxo em fila ou adiá-lo
Argumentos inválidosNão tentar novamenteRetornar um erro de validação ao agente
Falha de permissãoNão tentar novamenteSolicitar autorização ou parar
Resultado desconhecido após tempo limiteNão repetir às cegasVerificar o status usando a chave de idempotência

Adicione chamadas de ferramentas e aprovação humana

O create_agent do LangChain usa o LangGraph por baixo dos panos para executar. A documentação fornecida do LangGraph descreve o HumanInTheLoopMiddleware, que pode interromper chamadas selecionadas de ferramentas e retomá-las a partir do estado persistido.

from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver

agent = create_agent(
    model="provider:model-name",
    tools=[inspect_job, restart_job, delete_artifact],
    middleware=[
        HumanInTheLoopMiddleware(
            interrupt_on={
                "inspect_job": False,
                "restart_job": {
                    "allowed_decisions": ["approve", "reject"]
                },
                "delete_artifact": {
                    "allowed_decisions": ["approve", "edit", "reject"]
                },
            },
            interrupt_mode="per_call",
        ),
    ],
    checkpointer=InMemorySaver(),
)

Neste caso, a inspeção ocorre sem revisão, enquanto a reinicialização e a exclusão são pausadas para decisão. approve executa os argumentos originais, edit altera os argumentos antes da execução e reject ignora a chamada e retorna ao agente uma informação de rejeição. A fonte também documenta respond para atuar como uma ferramenta de “perguntar ao usuário”; essa opção não deve ser usada para negar uma ferramenta que produz efeitos colaterais, pois é tratada como um resultado bem-sucedido da ferramenta.

Em produção, substitua o checkpointer em memória por uma implementação persistente e invoque o agente com um ID de thread estável:

config = {
    "configurable": {"thread_id": "ops-workflow-1842"}
}

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "Inspect the failed job and restart it if safe.",
            }
        ]
    },
    config=config,
    version="v2",
)

Com a versão v2, o resultado interrompido expõe uma coleção interrupts. Apresente cada ação solicitada a um revisor autorizado e retome a mesma thread usando o formato de decisão Command documentado.

Mantenha as novas tentativas e a aprovação na ordem correta

A documentação de origem destaca uma regra importante para o middleware: ao usar revisão por chamada, coloque o tratamento de intervenção humana antes do middleware de novas tentativas ou de tratamento de erros das ferramentas. Caso contrário, uma nova tentativa pode fazer com que o revisor receba a solicitação novamente, ou uma resposta inválida pode ser repetida como se fosse uma falha da ferramenta.

A sequência prevista é:

  1. O modelo propõe uma chamada de ferramenta.
  2. A política verifica se a chamada precisa de revisão.
  3. Um revisor aprova, edita ou rejeita a chamada.
  4. A ferramenta é executada com sua própria política limitada de novas tentativas.
  5. Em caso de sucesso, o resultado retorna ao agente; se o limite for atingido, o fluxo entra em recuperação.

Não execute efeitos colaterais em middleware que seja executado novamente durante a retomada de uma interrupção. A documentação alerta especificamente que o middleware anterior à camada de revisão humana precisa ser seguro para reentrada até a pausa.

Adicione um estado de recuperação em vez de outra tentativa

Quando o limite de tentativas for atingido, registre um evento operacional com o ID do fluxo de trabalho, o nome da ferramenta, o número de tentativas, a chave de idempotência e o último erro conhecido. Em seguida, escolha um destes três caminhos:

  • Verificar: consultar o sistema externo para determinar se a operação original foi bem-sucedida.
  • Escalar: pausar para que um operador com contexto suficiente decida a próxima ação.
  • Compensar: executar uma operação corretiva separada e explicitamente aprovada.

Não peça ao modelo que invente uma ação compensatória com base em uma mensagem de erro incompleta. Forneça dados de status estruturados e restrinja as ferramentas disponíveis.

Um limite de execução no nível do grafo é uma segunda barreira de segurança. Configure o limite compatível com a versão instalada do LangGraph e trate seu atingimento como um evento de recuperação, em vez de continuar silenciosamente. Isso impede que um loop entre o modelo e as ferramentas se transforme em um processo de produção sem limites.

Lista de verificação para solução de problemas

  • O fluxo de trabalho recomeça do início: confirme que estão sendo usados um checkpointer persistente e o mesmo thread_id.
  • Uma ação rejeitada ainda é executada: verifique se a decisão de retomada é uma rejeição, e não respond.
  • O revisor recebe solicitações demais: adicione predicados when baseados nos argumentos para interromper apenas chamadas arriscadas.
  • Uma nova tentativa duplica o trabalho: adicione idempotência e uma ferramenta de consulta de status antes de repetir operações com resultado desconhecido.
  • A mesma revisão aparece repetidamente: verifique a ordem do middleware e confirme que o tratamento de novas tentativas não envolve incorretamente a etapa de aprovação.
  • Uma chamada editada tem um comportamento inesperado: valide você mesmo os argumentos editados; o esquema de resposta documentado descreve o formato, mas não necessariamente garante a segurança para o negócio.

Conclusão

Um agente de operações confiável com LangGraph é um fluxo de trabalho com limites, não um chatbot sem restrições. Defina um limite de tentativas para cada ferramenta, classifique as falhas, persista o estado, controle chamadas perigosas e torne a recuperação um ramo explícito. Assim, a aprovação humana se torna um checkpoint controlado no fluxo de trabalho, em vez de uma solução improvisada de emergência.

Fontes

Perguntas frequentes

O LangGraph tenta novamente automaticamente toda chamada de ferramenta que falha?

Não presuma que sim. Defina explicitamente o comportamento das novas tentativas, classifique os erros e estabeleça um número máximo de tentativas. O middleware de novas tentativas para ferramentas pode estar disponível na pilha instalada, mas sua configuração e seu comportamento devem ser verificados na documentação da versão correspondente.

Por que o checkpointing é necessário para a aprovação humana?

Uma interrupção pausa a execução enquanto uma decisão está pendente. Um checkpointer preserva o estado do grafo para que a mesma thread do fluxo de trabalho possa ser retomada após aprovação, edição, rejeição ou resposta direta.

Quando uma chamada de ferramenta deve exigir revisão humana?

Submeta à revisão chamadas que alterem o estado de produção, excluam dados, enviem comunicações externas ou tenham custo ou escopo incertos. Inspeções somente de leitura podem muitas vezes ser executadas automaticamente quando a autorização e os limites de saída estão claros.

O que deve acontecer quando o limite de tentativas é atingido?

Siga um caminho de recuperação: verifique a operação externa, escale para um operador ou execute uma ação compensatória aprovada separadamente. Evite repetir às cegas uma operação cujo resultado seja desconhecido.

Artigos relacionados