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.
Resumo · TL;DR
Use um limite de etapas do grafo para restringir a execução, o HumanInTheLoopMiddleware para pausar chamadas de ferramentas de risco e um pequeno conjunto fixo de testes para verificar os comportamentos de aprovação, rejeição e atingimento do limite. Trate os exemplos como um ponto de partida: o comportamento do modelo e das ferramentas deve ser testado no seu próprio ambiente.
Principais pontos
- Um limite de recursão do grafo define uma fronteira clara de execução para o agente; ele não garante que o agente concluirá a tarefa.
- A revisão humana pode pausar a execução de uma ferramenta e retomá-la mais tarde quando o grafo tiver um checkpointer e um ID de thread.
- Mantenha as avaliações reproduzíveis fixando as entradas de teste, os resultados esperados, os fixtures das ferramentas e o limite de execução.
- Teste explicitamente as ações rejeitadas e o esgotamento do limite; nenhum dos dois equivale a uma recuperação bem-sucedida.
Nesta página (6)
Um agente que chama ferramentas precisa de mais do que um bom prompt: ele precisa de um limite de parada, de um plano para ações de risco e de testes que tornem seu comportamento reproduzível. No LangGraph, você pode combinar um limite de recursão do grafo com a revisão human-in-the-loop (HITL) para ferramentas selecionadas. Depois, avalie o fluxo de trabalho com casos fixos, em vez de depender de algumas execuções bem-sucedidas.
O exemplo abaixo é ilustrativo, não uma configuração testada. Ele pressupõe um ambiente Python com pacotes compatíveis do LangChain e do LangGraph, um modelo de chat compatível com chamadas de ferramentas e uma ferramenta que você implementou. Verifique as versões e os parâmetros do provedor do modelo no seu próprio ambiente.
Escolha o limite antes de adicionar ferramentas
Um limite de recursão restringe as etapas de execução do grafo. Ele é uma fronteira de segurança, não uma promessa de que o agente terminará a tarefa, nem um limite preciso para o número de chamadas de ferramentas: a estrutura do grafo afeta a forma como as etapas são contabilizadas. Se a execução atingir o limite, espere um erro de recursão do grafo e trate a execução como incompleta. Não a considere uma resposta bem-sucedida.
Comece com um limite baixo durante a avaliação e só aumente-o quando um caso de teste demonstrar que o fluxo de trabalho precisa de mais etapas. Mantenha também as operações das ferramentas com escopo restrito. Um limite no nível do grafo não pode desfazer um efeito colateral que uma ferramenta já tenha realizado.
Configure uma chamada de ferramenta que possa ser pausada para revisão
Este exemplo usa create_agent com middleware HITL. A ferramenta write_file é interrompida para aprovação ou rejeição; read_data não é. As implementações das ferramentas e o nome do modelo são placeholders. Confirme se o modelo e o endpoint escolhidos são compatíveis com os parâmetros e o comportamento de chamadas de ferramentas usados pelo seu agente.
from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver
# Replace these placeholders with your own tool implementations.
tools = [write_file, read_data]
agent = create_agent(
model="your-tool-capable-chat-model",
tools=tools,
middleware=[
HumanInTheLoopMiddleware(
interrupt_on={
"write_file": {"allowed_decisions": ["approve", "reject"]},
"read_data": False,
}
)
],
checkpointer=InMemorySaver(),
)
config = {
"configurable": {"thread_id": "evaluation-case-001"},
"recursion_limit": 8,
}
result = agent.invoke(
{"messages": [{"role": "user", "content": "Save the approved summary."}]},
config=config,
version="v2",
)
InMemorySaver é adequado para um protótipo ou teste executado em um único processo; ele não é durável entre reinicializações de processos. Para um fluxo de trabalho implantado, use um checkpointer persistente. O guia de HITL do LangChain explica que um checkpointer e um ID de thread são necessários para pausar e retomar uma execução. Fonte: Human-in-the-loop.
Quando a execução retornar uma interrupção, mostre a ação solicitada e seus argumentos a um revisor. Retome a mesma thread com uma decisão. A ordem das decisões deve corresponder à ordem das ações na interrupção. Rejeite uma ação que você está negando; respond serve para retornar uma resposta humana como resultado de uma ferramenta, não para negar um efeito colateral.
from langgraph.types import Command
# Use the same config, including the same thread ID, to resume.
result = agent.invoke(
Command(resume={"decisions": [{"type": "reject", "message": "Outside the approved scope."}]}),
config=config,
version="v2",
)
Torne a avaliação reproduzível
Mantenha um conjunto compacto de testes sob controle de versão. Cada caso deve especificar a solicitação do usuário, o comportamento esperado da ferramenta, se a revisão é necessária e o status final esperado. Use fixtures inofensivos ou ferramentas simuladas nos testes; não permita que os casos de avaliação escrevam em arquivos reais ou alterem dados de produção.
| Caso | Configuração | Resultado esperado |
|---|---|---|
| Leitura segura | Solicitar informações por meio de read_data | Nenhuma interrupção HITL; o resultado da ferramenta é retornado |
| Escrita revisada | Solicitar uma escrita permitida | A interrupção aparece antes da execução da escrita; a aprovação permite a execução |
| Escrita rejeitada | Solicitar uma escrita e depois rejeitá-la | A ferramenta de escrita não é executada; o feedback da rejeição retorna ao agente |
| Limite de etapas | Usar um fixture que impeça a conclusão do fluxo de trabalho | A execução para no limite configurado e é registrada como incompleta |
Para cada execução, registre o ID do caso, o limite configurado, as chamadas de ferramentas, as decisões de interrupção, o status de conclusão e qualquer erro. Compare esses campos com as expectativas. Evite avaliar apenas a resposta final em linguagem natural: um agente pode produzir uma resposta plausível depois de executar a ação errada.
Tratamento de falhas: pausar, rejeitar ou parar
HITL é uma pausa controlada, não um mecanismo geral de novas tentativas. Um revisor pode aprovar, editar, rejeitar ou responder de acordo com a política configurada. A rejeição ignora a chamada de ferramenta solicitada e retorna feedback de rejeição ao agente. O fato de o agente terminar, solicitar outra ação ou falhar depois disso depende do comportamento subsequente, portanto teste esse caminho.
Se o grafo atingir seu limite de recursão, registre a execução como uma falha por limite e inspecione seu estado e o histórico de ferramentas. Não reproduza automaticamente uma execução que talvez já tenha realizado efeitos colaterais. Torne as ferramentas idempotentes quando for prático ou exija uma verificação separada antes de repetir uma operação. A documentação fornecida descreve a pausa e a retomada com checkpoint; ela não estabelece recuperação automática de falhas arbitrárias de ferramentas ou modelos.
Checklist de solução de problemas
- Nenhuma interrupção aparece: verifique se o nome da ferramenta corresponde ao mapeamento
interrupt_one se a política dela habilita a revisão. - Não é possível localizar a execução pausada ao retomar: confirme que o mesmo checkpointer e o mesmo ID de thread estão sendo usados.
- A execução para cedo demais: inspecione o limite de recursão configurado e o caminho do grafo; aumente o limite somente quando um caso de teste justificar isso.
- Uma ação rejeitada parece ter acontecido: verifique se a ferramenta não foi chamada antes da revisão e se o revisor usou
reject, nãorespond. - Os testes variam entre as execuções: fixe os fixtures das ferramentas e as entradas de teste, e controle ou substitua as respostas do modelo quando a sua configuração permitir. Uma entrada fixa, por si só, não torna a saída do modelo determinística.
A regra prática
Use o limite de recursão para restringir o trabalho do grafo, HITL para controlar chamadas de ferramentas consequenciais e um pequeno conjunto explícito de testes para verificar tanto o caminho esperado quanto os caminhos de falha. Trate as execuções interrompidas, rejeitadas e com limite esgotado como resultados distintos. Essa distinção torna um agente mais fácil de avaliar — e mais seguro de modificar.
Perguntas frequentes
O limite de recursão do LangGraph limita o número de chamadas de ferramentas?
Não exatamente. Ele limita as etapas de execução do grafo, e o número de chamadas de ferramentas que cabe depende da estrutura do grafo. Trate o esgotamento do limite como uma execução incompleta e teste essa fronteira.
O que é necessário para retomar uma chamada de ferramenta revisada por uma pessoa?
Configure um checkpointer, forneça um ID de thread e retome usando a mesma thread e o mesmo contexto de persistência. O revisor fornece uma decisão para cada ação interrompida.
O HITL tenta automaticamente executar novamente uma chamada de ferramenta que falhou?
Não. O fluxo de trabalho HITL documentado pausa para uma decisão humana e depois executa ou ignora a ação revisada. Ele não estabelece novas tentativas automáticas para falhas arbitrárias de ferramentas ou modelos.
Como devo testar uma chamada de ferramenta rejeitada?
Use uma ferramenta inofensiva ou simulada, acione a interrupção, rejeite a ação e verifique se a ferramenta não foi executada e se a execução registrou o feedback da rejeição.
Artigos relacionados
Guides
Crie um agente LangGraph com privacidade, aprovação de ferramentas e recuperação
Um padrão prático para usar revisão humana, checkpoints, execuções limitadas e ferramentas seguras com credenciais em um agente LangGraph que lida com dados sensíveis.
Guides
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.
Guides
Crie um agente LangGraph limitado para diagnosticar incidentes de API
Crie um agente LangGraph para diagnosticar incidentes, com ferramentas de diagnóstico somente leitura, execução limitada, falhas visíveis e pausa antes de ações arriscadas.
Guides
Crie um agente de suporte ao cliente com LangGraph, chamadas de ferramentas, aprovação humana e limites de execução
Um padrão prático de LangGraph para triagem de suporte ao cliente: encaminhe solicitações, chame ferramentas de consulta, pause reembolsos para aprovação humana e limite a execução do grafo.