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.
Resumo · TL;DR
Use o middleware human-in-the-loop do LangGraph para pausar chamadas sensíveis de ferramentas, revisá-las ou rejeitá-las e retomar a execução a partir de um checkpoint. Combine esse fluxo com limites rigorosos para ferramentas, isolamento de credenciais e um limite de execução.
Principais pontos
- Mantenha as credenciais dentro das implementações das ferramentas; passe ao modelo apenas os argumentos mínimos necessários.
- Exija revisão humana para gravações ou consultas sensíveis, permitindo que leituras seguras prossigam.
- Use um checkpointer persistente e um ID de thread estável para retomar o trabalho interrompido.
- Limite a execução do grafo e torne as ferramentas idempotentes ou seguras para novas tentativas de forma independente.
- Trate o estado salvo em checkpoints e os payloads de interrupção como dados sensíveis.
Nesta página (5)
Um agente com foco em privacidade não deve depender do modelo para decidir se uma chamada de ferramenta é segura. Mantenha as credenciais fora da conversa, restrinja o que cada ferramenta pode fazer e pause as ações sensíveis para revisão humana. O middleware human-in-the-loop do LangGraph oferece o mecanismo de pausa e retomada; ainda cabe à sua aplicação definir como os dados serão tratados, como a autorização será aplicada e quais serão os limites de execução.
Este guia apresenta um padrão simples para um agente capaz de consultar registros de clientes e solicitar uma alteração no banco de dados. O código é ilustrativo e não foi testado aqui. Antes da implantação, confira as versões dos pacotes e as assinaturas das ferramentas no seu ambiente.
1. Separe o contexto do modelo das credenciais
Não inclua senhas, chaves de API, cookies de sessão nem credenciais irrestritas de banco de dados em prompts ou argumentos de ferramentas. Em vez disso, ofereça às ferramentas operações restritas e faça com que elas obtenham as credenciais do mecanismo de gerenciamento de segredos da sua aplicação no momento da execução. O modelo deve ter acesso apenas aos dados necessários para escolher uma ação.
Por exemplo, prefira uma ferramenta como find_customer_record(customer_id) a uma ferramenta de uso geral que aceite SQL arbitrário e detalhes de conexão. Valide a autorização na própria ferramenta: o pedido de um usuário não comprova que ele tem permissão para acessar o registro solicitado.
A revisão humana é um controle adicional, não um sistema de autorização. Os revisores devem ver informações suficientes para tomar uma decisão, mas evite exibir dados pessoais ou segredos desnecessários nas telas de revisão e nos logs.
2. Configure a revisão para ações sensíveis
A documentação fornecida do LangChain sobre human-in-the-loop descreve um middleware que verifica chamadas de ferramentas com base em uma política. Chamadas correspondentes podem interromper a execução; um checkpointer salva o estado do grafo para que a execução possa ser retomada mais tarde. As decisões documentadas incluem aprovar, editar argumentos, rejeitar com feedback e responder a uma ferramenta que faz uma pergunta ao usuário.
Veja a seguir uma configuração ilustrativa. Substitua as ferramentas de exemplo por implementações que apliquem as regras de acesso e a validação de entradas da sua aplicação.
from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver
agent = create_agent(
model="YOUR_CONFIGURED_MODEL",
tools=[read_customer_record, update_customer_record],
middleware=[
HumanInTheLoopMiddleware(
interrupt_on={
"read_customer_record": False,
"update_customer_record": {
"allowed_decisions": ["approve", "edit", "reject"]
},
},
description_prefix="Review requested customer-data change",
),
],
# For production, use a persistent checkpointer appropriate to your stack.
checkpointer=InMemorySaver(),
)
InMemorySaver é adequado para prototipagem, mas não para recuperação durável após reinicializações do processo. A documentação exige um checkpointer para interrupções com revisão humana e cita opções persistentes, como AsyncPostgresSaver e MongoDBSaver. Escolha um armazenamento com controles de acesso, regras de retenção e criptografia adequados aos dados salvos em checkpoints. Um checkpoint pode conter mensagens e argumentos de ferramentas e, portanto, pode armazenar dados sensíveis de usuários mesmo quando as credenciais são excluídas.
Se apenas algumas chamadas precisarem de revisão, a documentação também oferece suporte a um predicado when para interrupções condicionais (requer langchain>=1.3.3). Por exemplo, você pode pausar uma gravação fora de um espaço de trabalho aprovado ou uma consulta que não seja somente de leitura. Não considere uma verificação de prefixo de string uma política completa de segurança de SQL; aplique operações seguras também nas camadas do banco de dados e das ferramentas.
3. Pause, revise e retome a mesma execução
Use um ID de thread estável para que a aplicação associe a revisão pendente à conversa correta. Proteja esse identificador e a interface de revisão: ter um ID de thread não deve conceder permissão para aprovar uma ação.
from langgraph.types import Command
config = {"configurable": {"thread_id": "conversation-123"}}
result = agent.invoke(
{"messages": [{"role": "user", "content": "Update this customer's address"}]},
config=config,
version="v2",
)
if result.interrupts:
# Present the requested action to an authenticated reviewer.
# Resume only after recording that reviewer's decision.
result = agent.invoke(
Command(resume={"decisions": [{"type": "reject", "message": "Verify the request first."}]}),
config=config,
version="v2",
)
Quando várias chamadas de ferramentas forem pausadas, a ordem das decisões deve corresponder à ordem das ações na solicitação de interrupção. Use reject para negar uma ação com efeitos colaterais. A documentação alerta que respond fornece um resultado sintético para a ferramenta; essa opção serve para responder a uma ferramenta no estilo “perguntar ao usuário”, não para negar uma gravação.
4. Limite a execução e planeje a recuperação
Uma pausa para revisão, por si só, não impede o modelo de continuar solicitando ferramentas. Defina um limite de recursão para as invocações do grafo e trate o erro resultante do limite como uma interrupção controlada. O limite exato depende da carga de trabalho; escolha-o com base na sequência máxima útil de etapas do modelo e das ferramentas e teste o comportamento ao atingir esse limite.
config = {
"configurable": {"thread_id": "conversation-123"},
"recursion_limit": 12,
}
Essa configuração ilustrativa limita as etapas do grafo; não garante proteção contra ferramentas lentas, saídas grandes ou efeitos externos repetidos. Adicione timeouts às chamadas de rede e de banco de dados, limite a saída das ferramentas e valide as entradas. Para operações que podem ser repetidas, use controles de idempotência ou verifique o estado atual antes de aplicar uma alteração. Se uma execução falhar depois que uma ferramenta for concluída, mas antes que o agente registre o resultado, uma nova tentativa sem verificação poderá executar a operação duas vezes.
Ao recuperar uma execução, retome a mesma thread com checkpoint somente depois de confirmar que a ação pendente e sua autorização continuam válidas. Se as permissões do usuário ou o registro subjacente tiverem mudado enquanto a revisão estava pendente, rejeite a ação ou valide-a novamente em vez de executar argumentos desatualizados.
5. Lista de verificação de privacidade e falhas
Antes de colocar o sistema em produção, confirme que:
- As implementações das ferramentas obtêm as credenciais de forma privada e nunca as retornam em resultados ou erros.
- Cada ferramenta aplica a autorização do usuário e aceita apenas os argumentos mais restritos que sejam úteis.
- Os checkpoints, payloads de interrupção, logs e telas de revisão têm controles de acesso e retenção definidos.
- O revisor consegue identificar o alvo e as consequências sem ver dados pessoais não relacionados.
- As rejeições não executam a ferramenta e as novas tentativas não duplicam efeitos colaterais.
- As execuções têm limites de etapas, timeouts para ferramentas, limites de saída e um procedimento claro para informar trabalho interrompido ou com falha.
A principal decisão de projeto é tratar a aprovação humana como uma etapa de verificação em um fluxo de trabalho seguro — não como substituto do princípio do menor privilégio, da minimização de dados ou da validação no nível das ferramentas.
Perguntas frequentes
O middleware human-in-the-loop do LangGraph armazena o estado pausado do agente?
Ele usa a persistência do LangGraph para salvar o estado durante uma interrupção. É obrigatório usar um checkpointer, e implantações em produção devem escolher um armazenamento persistente e aplicar controles adequados de acesso e retenção.
Devo usar a decisão `respond` para rejeitar uma chamada sensível de ferramenta?
Não. O comportamento documentado trata `respond` como um resultado sintético bem-sucedido da ferramenta, destinado a casos como responder a uma ferramenta que pergunta ao usuário. Use `reject` para negar uma ação com efeitos colaterais.
Como mantenho as credenciais privadas em um agente LangGraph?
Mantenha as credenciais no ambiente de execução da ferramenta ou na camada de gerenciamento de segredos. Não as inclua em prompts, argumentos de ferramentas visíveis ao modelo, resultados de ferramentas, mensagens de interrupção nem logs.
A aprovação humana impede que um agente execute indefinidamente?
Não. O middleware de aprovação cuida da revisão das chamadas de ferramentas configuradas. Defina separadamente um limite de execução, timeouts para ferramentas, limites de saída e um comportamento seguro para novas tentativas.
Artigos relacionados
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
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.
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.