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.
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:
- Tente novamente apenas erros que sejam plausivelmente transitórios.
- Pare após um limite pequeno e explícito de tentativas.
- Direcione o trabalho cujo limite foi atingido ou cujo resultado seja ambíguo para um estado de recuperação.
- 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, comoAsyncPostgresSaverouMongoDBSaver, para produção. - Um
thread_idestá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 falha | Ação automática | Ação de recuperação |
|---|---|---|
| Tempo limite temporário de rede | Tentar novamente dentro do limite | Escalar com o ID da operação |
| Limite de taxa | Tentar novamente conforme as orientações do provedor | Colocar o fluxo em fila ou adiá-lo |
| Argumentos inválidos | Não tentar novamente | Retornar um erro de validação ao agente |
| Falha de permissão | Não tentar novamente | Solicitar autorização ou parar |
| Resultado desconhecido após tempo limite | Não repetir às cegas | Verificar 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 é:
- O modelo propõe uma chamada de ferramenta.
- A política verifica se a chamada precisa de revisão.
- Um revisor aprova, edita ou rejeita a chamada.
- A ferramenta é executada com sua própria política limitada de novas tentativas.
- 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
whenbaseados 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
Guides
RAG agêntico com LangGraph: chamadas de ferramentas, atribuição de fontes e execução limitada
Crie um agente LangGraph para perguntas e respostas sobre documentos que decide quando buscar informações, avalia o contexto, tenta novamente após buscas pouco relevantes e retorna respostas com atribuição de fontes, sem execução ilimitada.
Guides
Crie um agente LangGraph limitado para chamadas de ferramentas com revisão humana
Um padrão prático para avaliar um agente LangGraph de chamadas de ferramentas com limites explícitos de etapas, aprovação humana para ações de risco e casos de teste reproduzíveis.
Guides
Gemini 4 Hydrogen vs. Carbon para operações de workflows em produção
O que as evidências disponíveis dizem sobre Gemini 4 Hydrogen e Carbon para programação, chamadas de ferramentas, saída estruturada e workflows de produção recuperáveis.
Guides
Crie um fluxo de extração de dados recuperável no n8n
Projete um fluxo de extração no n8n que valide registros, tente novamente após falhas transitórias e encaminhe exceções para revisão humana sem gerar gravações duplicadas.