LangGraph Human in the Loop: pause, revise e retome sem duplicar ações

ANÁLISE EDITORIAL

Um agente pode preparar uma resposta, uma alteração de banco ou uma ação externa e ainda precisar de uma decisão humana antes de avançar. A Skill LangGraph Human in the Loop organiza esse ponto de parada: como interromper um grafo, mostrar o que será decidido e retomá-lo com a resposta da mesma pessoa e da mesma execução. O detalhe decisivo não é exibir um botão de aprovação. É preservar o estado correto, impedir que a retomada repita efeitos colaterais e distinguir aprovação de uma nova instrução.

O que esta Skill faz de verdade

O SKILL.md oficial ensina padrões com interrupt() e Command(resume=...) em Python e TypeScript. Ele cobre aprovação ou rejeição de um rascunho, edição humana, validação de entrada, várias interrupções simultâneas e erros frequentes de retomada. É uma instrução para o agente de programação, não um serviço de aprovação pronto, uma interface de usuário ou um mecanismo de autorização implantado. Para funcionar em um projeto real, o desenvolvedor ainda precisa construir o fluxo, o armazenamento de estado, a identidade do revisor e as regras de acesso.

A documentação atual do LangGraph sobre interrupções confirma os três componentes essenciais: um checkpointer, um thread_id estável e um valor serializável em JSON para o ponto de parada. Ao retomar, Command(resume=...) entrega a resposta ao interrupt(). O nó que parou recomeça desde o início, portanto o código anterior à interrupção pode rodar outra vez. Essa característica torna perigoso criar registros, enviar mensagens ou cobrar pagamentos antes da pausa sem uma estratégia de idempotência.

O repositório langchain-ai/langchain-skills tinha 1.286 estrelas em 13 de outubro de 2026. A autoria é da organização LangChain, a licença é MIT e o commit desta curadoria é fixo. Estrelas são um sinal de adoção do repositório, não prova de qualidade, segurança ou compatibilidade com a versão instalada no seu projeto. O próprio README informa que o conjunto ainda está em desenvolvimento inicial e pode mudar.

Para quem serve

Serve a equipes que constroem agentes ou fluxos com LangGraph e precisam inserir revisão antes de enviar uma resposta, gravar um dado, acionar uma API ou decidir o tratamento de uma exceção recuperável. Também é útil para quem revisa uma implementação existente que parece “perder” o pedido de aprovação depois de reiniciar o processo. O roteiro ajuda a verificar se o mesmo identificador de thread está sendo usado na pausa e na retomada, se o estado foi persistido e se o valor aprovado corresponde à ação que será executada.

Há um limite importante: a Skill não determina quem tem autoridade para aprovar. A aplicação precisa autenticar o revisor, associar a decisão à tarefa correta e registrar o que foi mostrado no momento da escolha. Um True entregue ao grafo não constitui, sozinho, uma aprovação válida de uma pessoa autorizada. Se a operação tiver impacto financeiro, jurídico ou em produção, use também as políticas do seu sistema, trilha de auditoria e testes de falha. A documentação de padrões trata a interrupção como componente de um fluxo maior, não como substituta de governança.

Compatibilidade e pré-requisitos

O arquivo traz exemplos para Python e TypeScript e pressupõe um projeto que use as bibliotecas LangGraph correspondentes. Ele não fixa no frontmatter uma versão mínima do runtime. Consulte a instalação oficial em Python ou a entrada oficial em JavaScript para escolher as dependências atuais do seu projeto. Não copie uma versão desta página para um manifesto sem conferir a documentação e o lockfile. A Skill pode ser lida por um cliente compatível com Agent Skills; seu conteúdo não exige token, mas um aplicativo que chame modelos, armazenamento ou serviços externos pode exigir credenciais próprias.

Antes do primeiro teste, tenha um grafo simples, um estado serializável, um checkpointer e um identificador de thread que você consiga reutilizar. O exemplo da Skill usa InMemorySaver para desenvolvimento. Um processo reiniciado perde o estado apenas em memória, portanto não o trate como persistência durável de produção. O guia de persistência explica a relação entre threads, checkpoints e backends. Separe também um cenário fictício sem efeito externo para observar a pausa e a retomada com segurança.

Instalação recomendada

1. Baixe o ZIP documental pelo cartão de download local desta página. Antes de abrir, calcule seu SHA-256 e compare com 0d99f5cb6fc718090b9e12ac217b9c3837c358b431f2e6995520ed7c49dab670. Uma diferença indica que o arquivo não é o pacote auditado aqui.
2. Extraia e leia ORIGEM.md, LICENSE e SKILL.md. Os três arquivos são texto; o pacote não inclui executáveis, dependências ou credenciais. A versão fixada da instrução é o commit indicado abaixo.
3. Crie uma pasta chamada langgraph-human-in-the-loop no diretório de Skills que seu agente reconhece e coloque nela os três arquivos. A configuração desse diretório varia por cliente. O README oficial documenta a instalação pelo comando npx skills e opções para Codex; consulte-o se preferir a origem completa.
4. Abra uma conversa de teste no projeto e peça um plano para pausar um grafo antes de uma ação fictícia. O agente deve identificar checkpointer, thread_id, payload mostrado ao revisor, valor de retomada e possíveis efeitos repetidos. Não conecte esse teste a uma API de produção.

O botão para abrir o repositório oficial é separado do download próprio. O primeiro mostra o histórico e as instruções mais recentes; o segundo entrega exatamente o recorte documental e o checksum desta curadoria. Instalar a Skill não instala o pacote LangGraph nem habilita aprovação em um aplicativo existente.

Configuração antes do primeiro uso

Defina qual ação deverá esperar uma pessoa. Em vez de “aprovar qualquer resposta”, formule uma fronteira verificável: por exemplo, “antes de enviar um e-mail, mostre destinatário, assunto e corpo final ao revisor autorizado”. O estado salvo precisa conter o material que será revisado e o identificador da execução. O valor passado ao interrupt() deve ser serializável em JSON e não precisa incluir segredos ou dados além do necessário para a decisão. Verifique como o checkpointer guarda e protege esse material, sobretudo quando a revisão envolver conteúdo sensível.

Associe cada solicitação de aprovação a um thread_id estável e diferente dos demais trabalhos. Ao receber a resposta humana, confira a identidade, a validade da decisão e se o conteúdo ainda é o mesmo que foi exibido. Só então retome o grafo com Command(resume=...) usando o mesmo identificador. O guia oficial adverte que uma nova thread começa do zero em vez de continuar a pausa anterior. Se houver várias interrupções em ramos paralelos, associe cada resposta ao ID da interrupção correspondente, conforme o exemplo da Skill; não presuma que a ordem de exibição seja suficiente.

Primeiro uso seguro e resultado esperado

Monte um grafo de laboratório que produza um texto fictício e pare imediatamente antes de marcá-lo como aprovado. Inicie com um estado de teste e uma thread identificada. Confirme que o primeiro resultado contém uma interrupção e o texto proposto, sem registrar envio algum. Responda com uma decisão de rejeição na mesma thread e observe se o fluxo termina sem a ação. Repita em outra thread de teste com aprovação. O resultado esperado é uma transição explícita e reproduzível, não uma mensagem genérica de “aprovado” sem relação com o conteúdo mostrado.

Para testar uma edição, peça que o revisor devolva o texto corrigido e confira se o próximo nó usa essa versão, não o rascunho anterior. Depois introduza uma entrada inválida para observar o laço de validação e uma nova interrupção. Os exemplos do manual de retomada distinguem Command(resume=...) de Command(update=...): o segundo não deve ser passado como entrada de invoke() para continuar uma pausa. Não alegamos ter executado esses testes no seu ambiente; são verificações que você deve fazer antes de integrar um fluxo real.

Permissões e riscos

A leitura do SKILL.md não concede acesso a arquivos, banco ou rede. O risco aparece nas ferramentas e credenciais que o agente ou a aplicação já possuem. Um fluxo que envia mensagem ou altera dados precisa limitar o que acontece após a decisão humana, não apenas mostrar um pedido de confirmação. A aprovação deve ser vinculada ao objeto e à versão revisados. Uma interface que mostra um resumo incompleto e executa outro payload cria uma falsa sensação de controle. Também não exponha chaves de API no estado do grafo, no payload de interrupção ou no log de revisão.

O risco técnico mais sutil é a repetição: ao retomar, o nó recomeça desde o início. Se ele tiver criado um registro antes de interrupt(), poderá criá-lo de novo. A Skill recomenda mover efeitos para depois da pausa, isolá-los em nós próprios ou usar operações idempotentes, como um upsert com chave estável. Em subgrafos, a execução do nó pai também pode se repetir. O guia de regras e armadilhas é a referência para revisar essas consequências antes de ligar o grafo a sistemas de produção.

Erros comuns e como investigar

A pausa não ocorre ou não pode ser retomada. Verifique se o grafo foi compilado com checkpointer e se a configuração inclui thread_id. Confirme que a mesma thread chega à chamada de retomada. Um identificador novo não recupera o checkpoint antigo. Inspecione a resposta da primeira execução antes de concluir que o código “ignorou” a interrupção; em invoke(), o valor aparece em __interrupt__, enquanto APIs de streaming expõem projeções próprias.

A ação aconteceu duas vezes. Procure operações de escrita antes de interrupt() no nó e, se houver subgrafo, também no nó que o chama. Simule uma retomada após falha e compare os registros. Faça a operação posterior à aprovação ou use idempotência documentada. O agente retomou a tarefa errada. Confira a associação entre usuário, solicitação, thread_id e ID da interrupção. Não resolva trocando nomes aleatoriamente; preserve a trilha da decisão.

A Skill não aparece no cliente. Confira a pasta e o nome SKILL.md, a convenção de descoberta e a necessidade de reiniciar a sessão. O diretório original ajuda a conferir o arquivo. Se o pacote local for lido mas um exemplo não corresponder à API instalada, consulte a documentação da sua versão e adapte o projeto em ambiente de teste, sem editar silenciosamente a fonte auditada.

Versão, licença e download local

Esta página fixa o commit 16a992f09ab3ccfb642dd4f08d350d833d1990bf de langchain-ai/langchain-skills. O SKILL.md consultado não declara uma versão própria no frontmatter; por isso, o commit é a referência reprodutível, não um número inventado. A licença MIT da origem permite redistribuição com preservação do aviso, incluído no ZIP. O pacote contém somente os três documentos listados em ORIGEM.md. O SHA-256 do arquivo SKILL.md é 8e9047e81a4506c3a12814ea6d4f4ec2a2e7e941122ba715c152de46b920d2ec.

Não confunda este download com as dependências de Python ou JavaScript, nem com um ambiente de execução. A política de aprovação real pertence ao aplicativo que você constrói. Revalide a documentação e os requisitos antes de atualizar bibliotecas; o repositório avisa que o conteúdo ainda pode mudar. Se o seu fluxo exige persistência após reinício, use um checkpointer durável compatível com a sua implantação, em vez de copiar sem reflexão o exemplo em memória.

Fontes primárias

Foram consultados o arquivo da Skill fixado no commit, o README do mantenedor, a documentação de interrupções, o guia de persistência e a instalação oficial. O texto acima é uma leitura crítica desses materiais, não um benchmark ou relato de teste executado no projeto do leitor.