Crie um fluxo de alterações de código no n8n com aprovação humana e verificação de testes

Visão geral do fluxo

Use o n8n para permitir que um agente de IA proponha uma alteração em um repositório, mas coloque a operação de gravação atrás de uma aprovação humana. Depois que a gravação for aprovada, execute testes no commit exato resultante e informe o resultado. Mantenha a mesclagem ou a implantação como decisões separadas.

A distinção fundamental é entre aprovação de ferramenta e aprovação de resultado. No n8n, uma etapa de revisão humana pode pausar um AI Agent antes da execução de uma ferramenta selecionada. O revisor vê a ferramenta proposta e seus parâmetros; ao aprovar, a chamada é executada; ao negar, ela é cancelada e o agente é informado. Esse comportamento está documentado no guia do n8n sobre humano no loop.

O OneMux oferece acesso a modelos de IA por meio de uma única API compatível com OpenAI. É uma possível forma de acesso a modelos para este projeto, não uma integração com o n8n verificada. Confira a documentação da API do OneMux e as configurações do nó do n8n em relação ao endpoint e aos parâmetros que pretende usar.

O que é necessário antes de começar

• Uma instância do n8n com um AI Agent, uma conexão adequada a um modelo de chat e acesso a um canal de revisão humana, como Slack ou n8n Chat.
• Uma integração com o repositório ou um serviço personalizado capaz de ler uma revisão especificada e aplicar um patch a um branch que não seja de produção. Limite a credencial de gravação ao acesso necessário para esse repositório e branch.
• Um runner de testes isolado das credenciais e dos sistemas de produção. Ele deve aceitar um identificador de commit exato e retornar um status e um link ou referência aos resultados.
• Uma conta OneMux e acesso à API, caso escolha o OneMux para chamadas ao modelo. Consulte o guia de início rápido para ver as informações de conexão atuais e o catálogo de modelos ao escolher um modelo disponível.
• Um repositório com um comando de teste conhecido, um branch padrão protegido e uma pessoa autorizada a revisar as alterações propostas.

Este é um padrão de implementação, não um fluxo de trabalho pronto para importar. As ferramentas de repositório, a integração com o runner, a escolha do modelo e os campos exatos do n8n dependem do seu ambiente. Em particular, a documentação fornecida não confirma que um modelo específico do OneMux seja compatível com o comportamento de chamada de ferramentas exigido por um AI Agent do n8n. Verifique esse suporte antes de depender deste projeto.

Projete o fluxo em torno de uma revisão exata

Uma sequência prática é:

1. Receba uma solicitação. Capture o repositório, a descrição do problema, o branch de trabalho de destino, o commit-base e o comando de teste permitido, definidos na configuração confiável do fluxo.
2. Leia e proponha. Permita que o agente examine os arquivos relevantes no commit-base e prepare um patch. O acesso de leitura não deve permitir alterações no repositório.
3. Revise a gravação. Encaminhe a ferramenta de aplicação do patch para a revisão humana do n8n. O revisor aprova ou nega a chamada de ferramenta proposta.
4. Aplique e identifique. Se aprovada, o serviço de gravação verifica se o branch ainda aponta para o commit-base aprovado, aplica o patch aprovado e retorna o novo ID do commit. Se a base tiver mudado, interrompa a operação e solicite uma nova proposta e aprovação.
5. Verifique. Execute os testes configurados nesse novo commit exato, usando um runner isolado. Registre o comando, o commit, o status e a referência aos resultados.
6. Informe. Envie ao revisor e a quem fez a solicitação o commit e o resultado dos testes. Um resultado de teste com falha, cancelado ou ausente não representa aprovação.

Esses controles são recomendações, não recursos garantidos pela etapa de revisão humana do n8n. Em particular, o serviço do repositório precisa aplicar a verificação do commit-base e garantir que o patch aprovado seja o mesmo que será aplicado.

Configure a conexão com o modelo

No n8n, escolha uma configuração de modelo de chat que aceite um endpoint compatível com OpenAI configurável e o comportamento de chamada de ferramentas necessário ao seu AI Agent. Use o endpoint, o método de autenticação e o identificador do modelo especificados na documentação atual do OneMux. Armazene as credenciais no sistema de credenciais do n8n, não em prompts ou mensagens do fluxo.

Antes de conectar o acesso ao repositório, faça uma solicitação de teste simples e confira se a resposta chega no formato esperado pelo nó do n8n. Em seguida, teste uma chamada de ferramenta inofensiva. Compatibilidade com OpenAI não significa que todos os endpoints, parâmetros ou formatos de chamada de ferramentas sejam intercambiáveis: a compatibilidade depende de ambos os lados oferecerem suporte às solicitações e respostas necessárias. Esta configuração não foi testada para este artigo.

Se a conexão de modelo disponível não oferecer suporte às chamadas de ferramentas do agente, não contorne a aprovação concedendo ao modelo credenciais diretas de gravação. Use uma configuração compatível ou crie uma transferência separada e explicitamente revisada para o serviço de gravação.

Adicione uma etapa de aprovação humana à gravação no repositório

No nó AI Agent, abra o conector Tools e encontre Human review no Tools Panel. Selecione um canal de aprovação e configure as credenciais. Conecte a ferramenta de gravação no repositório ao conector de ferramentas da etapa de revisão. Quando apropriado, mantenha as ferramentas somente de leitura separadas e coloque quaisquer outras ferramentas capazes de alterar o estado de sistemas externos atrás de suas próprias etapas de revisão ou controles equivalentes.

A documentação do n8n informa que o revisor pode receber o nome da ferramenta e os parâmetros fornecidos pela IA. Por exemplo, configure a mensagem de revisão com:

Proposed tool: {{ $tool.name }}
Proposed parameters:
{{ JSON.stringify($tool.parameters, null, 2) }}

Use uma ferramenta de gravação cujos campos revisáveis incluam o repositório, o branch, o commit-base e o patch completo ou uma referência imutável ao patch com um digest. Se o patch for grande demais para o canal, forneça um local seguro e acessível para revisão e verifique se o serviço de gravação aplica o mesmo conteúdo. Uma instrução vaga, como “corrija os testes”, não basta para aprovar uma alteração específica no repositório.

Os valores $tool.parameters documentados incluem campos configurados com expressões $fromAI(); não presuma que a mensagem exiba todas as credenciais fixas, configurações ocultas ou efeitos posteriores. Mantenha as configurações fixas restritas e ofereça aos revisores outra forma de examiná-las. Evite incluir segredos nos parâmetros da ferramenta, pois eles podem aparecer nas mensagens de aprovação.

Adicione uma instrução de sistema que identifique a ferramenta sujeita à aprovação e diga ao agente o que fazer caso a solicitação seja negada. Por exemplo:

Repository writes require human approval. Propose a patch against the
specified base commit and request the write tool only for that patch.
If approval is denied, do not retry the write or use another tool to make
the change. Tell the requester it was denied and ask for clarification.
Report test results only when supplied by the test runner.

Essa instrução ajuda o agente a lidar com a revisão; não é uma barreira de segurança. Aplique as permissões e as restrições de branch fora do prompt.

Verifique a alteração aprovada

Acione o runner de testes somente depois que o serviço de gravação retornar um ID de commit. Configure o runner para fazer checkout desse ID, não da versão mais recente do branch, e executar um comando permitido definido pela sua equipe. Para um repositório cujos mantenedores tenham escolhido esse comando, este poderia ser um exemplo:

npm test

Esse comando é apenas ilustrativo; use as instruções de teste reais do projeto. Trate o código do repositório, os scripts de instalação de dependências e a saída dos testes como conteúdo não confiável. Execute-os com acesso restrito à rede e ao sistema de arquivos, sem segredos de produção e com limites de tempo e recursos. Uma suíte de testes aprovada demonstra apenas que as verificações selecionadas passaram nesse ambiente; não prova que a alteração seja segura ou correta.

Retorne um resultado conciso com a base aprovada, o novo commit, o comando de teste, o status de aprovação ou falha e um link para os logs. Se os testes falharem, o agente pode propor um patch revisado, mas uma nova gravação precisa de aprovação própria. Não faça a mesclagem automaticamente porque um revisor aprovou uma chamada de ferramenta anterior.

Solução de problemas e limites operacionais

A solicitação de aprovação não tem contexto útil

Confira quais entradas são fornecidas pela IA e ficam visíveis em $tool.parameters. Inclua a identidade do patch, o branch e a revisão-base na entrada da ferramenta sujeita à revisão ou forneça um artefato de revisão seguro e imutável. Se o revisor não conseguir identificar a gravação exata, negue a solicitação.

O agente não consegue chamar a ferramenta

Primeiro, teste uma ferramenta inofensiva independentemente das permissões do repositório. Confira a configuração do nó do n8n, o endpoint do OneMux, o modelo selecionado e os parâmetros necessários para chamadas de ferramentas, consultando a documentação atual. As fontes fornecidas não verificam uma combinação específica de modelo e nó.

O branch mudou ou os testes não terminaram

Rejeite uma gravação desatualizada em vez de aplicar um patch a uma base diferente. Em caso de timeout, erro no runner ou log ausente, informe que a verificação está incompleta. Quando apropriado, execute novamente os testes no mesmo commit; se a gravação proposta mudar, solicite uma nova aprovação.

Conclusão

O limite útil é bem definido: uma pessoa aprova uma gravação específica no repositório, e um runner isolado verifica o commit resultante. O n8n oferece a pausa e o fluxo de aprovação de ferramentas documentados; o serviço do repositório, o runner, as permissões e o processo de revisão fornecem as demais proteções. Use o OneMux como camada de acesso a modelos somente depois de confirmar que o endpoint e os parâmetros escolhidos funcionam com a sua configuração do n8n.

Fontes

• n8n: Human-in-the-loop for tools — comportamento de aprovação de ferramentas, configuração, canais de revisão e variáveis da mensagem de revisão.
• Documentação do OneMux — consulte as informações atuais para conectar à API.