A orquestração de agentes de IA está pronta para produção quando oito critérios são atendidos: agentes executam em workspaces isolados, cada alteração passa por verificação automatizada, uma pessoa aprova em checkpoints definidos, os custos são atribuídos por unidade de trabalho integrada (merged), as instruções dos agentes são arquivos versionados, o orquestrador não está acoplado a um único fornecedor de modelos, a residência dos dados é conhecida e uma execução com falha possui um fluxo de recuperação bem estruturado. Um projeto piloto não precisa de nenhum desses itens e ainda assim parece impressionante. A produção exige todos os oito, porque cada um representa um modo de falha que só surge em escala. Este artigo apresenta o checklist, os exemplos de respostas inadequadas e como testar cada ponto em um sistema que você já opera.

O checklist

#	Requisito	A pergunta a ser feita	Uma resposta inadequada
1	Isolamento de workspace	Onde cada agente escreve?	"No diretório de trabalho do repositório"
2	Verificação automatizada	O que precisa passar antes da revisão humana?	"O revisor executa os testes"
3	Checkpoints humanos	Onde exatamente uma pessoa toma decisões?	"Os revisores olham os PRs"
4	Atribuição de custos	Quanto custou a última alteração integrada?	"Acompanhamos a fatura mensal da API"
5	Instruções versionadas	Onde ficam as instruções do agente?	"Em um prompt colado no chat"
6	Portabilidade de modelos	O que quebra se o modelo for descontinuado?	"Nós reescreveríamos os prompts"
7	Residência de dados	Quais partes possuem uma cópia do código?	"O fornecedor cuida disso"
8	Recuperação de falhas	O que acontece quando uma execução falha no meio?	"Alguém percebe e limpa o ambiente"

A ordem é fundamental. Os itens 1 a 3 garantem a correção: sem eles, o volume de trabalho gera defeitos mais rápido do que a revisão é capaz de capturar. Os itens 4 a 6 garantem a sustentabilidade: sem eles, o sistema funciona, mas não pode ser analisado com clareza nem migrado. Os itens 7 e 8 são as questões que a auditoria de segurança e o engenheiro de plantão levantarão, invariavelmente após o rollout.

1. Isolamento de workspace

Dois agentes editando o mesmo diretório de trabalho vão intercalar gravações, e o diff resultante não pertencerá ao plano de nenhum dos dois. A unidade de isolamento recomendada é o git worktree: um diretório de trabalho independente com seu próprio branch e índice, compartilhando o armazenamento de objetos com o repositório principal. Criar um worktree é um checkout, não um clone; portanto, leva uma fração de segundo em vez do tempo de baixar todo o histórico novamente.

# Um diretório e um branch por plano.
git worktree add ../work/plan-4812 -b plan/4812
git -C ../work/plan-4812 status --short
git worktree remove ../work/plan-4812

Contêineres fornecem uma barreira mais rígida quando o agente executa código não confiável, e o modelo de segurança do Docker especifica o que essa fronteira realmente garante. Para um agente confiável operando no seu próprio repositório, o worktree é geralmente a melhor opção: isolamento por plano sem o custo de inicialização de contêineres no caminho crítico. Git worktrees para agentes de IA paralelos detalha esses modos de falha, incluindo hooks compartilhados e submódulos que costumam surpreender os times.

Como testar: Inicie dois planos que toquem no mesmo arquivo e confirme se ambos produzem diffs limpos e separados.

2. Verificação automatizada antes da revisão humana

Um revisor analisando um diff que sequer compila é um revisor que teve seu tempo desperdiçado. Testes, linters, checagem de tipos, build e validação de escopo em relação ao plano devem rodar dentro do worktree do agente, anexando os resultados à alteração. Trata-se de integração contínua aplicada por plano em vez de apenas por branch.

Dois filtros de validação são específicos para o código de agentes. A verificação de escopo (scope check) compara os arquivos modificados com os arquivos previstos no plano, pois um agente solicitado para corrigir uma checagem de nulo pode, por vezes, reformatar o arquivo inteiro e renomear variáveis sem necessidade. A varredura de segurança busca as vulnerabilidades do OWASP Top 10 for LLM Applications: tratamento inseguro de saídas, dependências maliciosas na cadeia de suprimentos ou credenciais expostas. Filtros de verificação para código gerado por IA estabelece quais validações devem bloquear a entrega e quais devem apenas informar.

Como testar: Pergunte qual porcentagem das alterações geradas por agentes chega aos humanos com testes falhando. Se ninguém souber responder, o filtro não existe na prática.

3. Checkpoints humanos em exatamente dois pontos

Zero checkpoints significa que o agente faz merge direto na main e os erros são descobertos por outras pessoas. Dez checkpoints significa aprovar cada chamada de ferramenta individualmente, tornando o humano o gargalo do fluxo e treinando os revisores a aprovar tudo por puro reflexo.

Dois checkpoints colocam o discernimento humano exatamente onde ele altera o resultado final. O checkpoint do plano é onde um mal-entendido é mais barato de corrigir, pois nenhum código foi escrito e o plano é apenas uma página de texto. O checkpoint do diff é onde a correção é validada com base nos resultados da verificação. O que é uma software factory descreve o fluxo completo.

Como testar: Identifique os dois momentos exatos em que uma pessoa decide. Se a resposta for uma série difusa de atividades em vez de dois marcos pontuais, não há checkpoint real, apenas supervisão constante.

4. Custos atribuídos por alteração integrada

A fatura mensal da API não oferece dados acionáveis. O indicador que você precisa monitorar é o custo por pull request integrado: o gasto total no período, incluindo planos rejeitados ou abandonados, dividido pelos pull requests integrados com sucesso. O trabalho descartado é parte integrante do custo do trabalho aceito.

Avalie esse número em conjunto com a taxa de rejeição (denial rate), a fatia de pull requests fechados sem merge. Qualquer uma dessas métricas isoladas pode ser maquiada à custa de piorar a outra, razão pela qual as métricas DORA são sempre reportadas em pares. Medindo o rendimento de agentes de codificação por IA define cada métrica e o que leituras desfavoráveis indicam.

Como testar: Pergunte o custo médio por PR integrado no mês passado. Se ele só puder ser estimado manualmente a partir de faturas, significa que não está sendo gerenciado.

5. Instruções como arquivos versionados

O comportamento do agente que reside em um prompt colado na janela de chat não pode ser revisado, comparado por diff nem revertido. Instruções devem viver no repositório, pelo mesmo motivo que a configuração vive nele de acordo com The Twelve-Factor App: uma mudança vira um diff em um pull request que um engenheiro sênior pode avaliar e rejeitar.

// Instruções e memória são arquivos lidos pelo orquestrador, não
// strings compiladas no binário. Uma convenção aprendida na segunda-feira
// é aplicada por todos os agentes e desenvolvedores na terça-feira.
interface Promptware {
  program: string; // Program.md - instruções do estágio
  memory: string[]; // Memory/    - aprendizados sobre este repositório
  tools: string[]; // Tools/     - permissões e ferramentas delimitadas
  logs: string[]; // Logs/      - histórico de execução imutável
}

O risco é o desvio de comportamento (drift): um agente com permissão para editar suas próprias instruções também pode degradá-las, por exemplo adicionando "repetir testes com falha até três vezes" após uma execução instável. O controle de versões é o mecanismo de proteção, pois a revisão é um diff visível para os revisores. Promptware: agentes que melhoram suas próprias instruções aborda esse risco e o inchaço de memória de contexto.

Como testar: Execute git log no diretório que contém as instruções dos seus agentes. Um histórico vazio indica que as instruções operam fora do ciclo de engenharia de software.

6. Portabilidade entre modelos e agentes

Modelos são descontinuados no cronograma dos fornecedores, não no seu. Um orquestrador que depende exclusivamente de um único provedor transforma qualquer aviso de depreciação em um projeto emergencial de migração. A camada que vale a pena possuir é o fluxo de trabalho: fases, filtros de verificação, checkpoints e memória. O motor de execução subjacente deve ser intercambiável por plano, e o acesso a ferramentas deve adotar interfaces abertas como o Model Context Protocol, em vez de integrações proprietárias para cada agente.

A portabilidade também viabiliza o roteamento por custo. Uma etapa de triagem não requer um modelo de fronteira; um plano arquitetural complexo pode exigir. Essa flexibilidade só é viável se a troca de modelo for uma simples configuração, e não uma reescrita do código.

Como testar: Troque o modelo de um plano específico e execute-o. Se isso exigir alterar código em vez de configuração, você possui uma dependência rígida, não uma arquitetura desacoplada.

7. Residência de dados conhecida

Cada cópia do seu repositório fora do seu controle precisa ser inventariada, protegida contratualmente e, por fim, descartada. Um agente hospedado em nuvem clona o repositório no ambiente do fornecedor, introduzindo pelo menos dois operadores sobre o seu código-fonte: o fornecedor do agente e o provedor do modelo de linguagem. Um orquestrador local-first possui apenas um operador externo, e estritamente para os fragmentos de código incluídos nos prompts.

Essa questão vai além da segurança: é uma questão de conformidade legal. Ela determina quantos acordos de processamento de dados (DPA) uma auditoria de GDPR precisa contemplar e se a residência dos dados na União Europeia é um parâmetro de configuração ou uma negociação contratual complexa. Desenvolvimento de IA local-first detalha as perguntas que sua equipe de segurança fará.

Como testar: Liste todas as partes que mantêm uma cópia do seu código durante uma única execução de agente. Se a lista for maior do que o esperado, a auditoria de segurança chegará à mesma conclusão.

8. Um fluxo de recuperação definido

Em escala, execuções inevitavelmente falham: quedas de conexão no meio do processo, agentes em loop infinito, etapas de verificação que travam. O orquestrador precisa de uma resposta formal para cada cenário, e essa resposta não pode ser "alguém vai perceber e limpar".

Falha na verificação: A tarefa retorna ao agente com a saída real do erro anexada — e não um resumo genérico —, sendo reexecutada no mesmo worktree até um limite de tentativas.
Execução abandonada: O worktree e o branch correspondente são removidos, evitando que um plano travado deixe resquícios que prejudiquem execuções futuras.
Custos descontrolados ou loops: Um orçamento de tokens e tempo por plano que interrompe a execução ativamente, em vez de gerar alertas tardios após o ocorrido.
Estado parcial inconsistente: Como cada plano possui seu próprio worktree e branch, descartar uma execução com falha resume-se a deletar uma única pasta. Nenhum arquivo compartilhado é afetado.

Como testar: Finalize forçadamente o processo de um agente no meio de um plano. O que sobra no disco e como isso impacta o próximo plano da fila?

Como o Ivy Tendril atende aos oito critérios

O Ivy Tendril é um aplicativo desktop local-first para macOS, Windows e Linux que orquestra agentes de codificação desde a concepção do plano até o pull request revisado. Oferece worktree por plano (1), execução de testes, linter e inspeção de diff acoplados a cada mudança com suporte a importação de CI no plano Pro (2), os dois checkpoints humanos rigorosos (3), controle de custos por plano e por tarefa (4), unidades de promptware como arquivos versionados no Git (5), flexibilidade total para escolher qualquer CLI de agente e modelo por plano (6), código e logs que nunca saem da sua máquina (7), além de fluxo de recuperação com saída detalhada de erros e limpeza automática de worktrees (8).

curl -sSf https://cdn.ivy.app/install-tendril.sh | sh

No Windows, execute irm https://cdn.ivy.app/install-tendril.ps1 | iex. O Tendril é gratuito e tem código aberto sob a Functional Source License; recursos de equipe, hospedagem on-premise, SSO e importação de verificações de CI estão disponíveis nos planos Pro e Enterprise.

Perguntas frequentes

Qual dos oito critérios um time deve priorizar primeiro?

Primeiro isolamento, depois verificação e, em seguida, checkpoints. Problemas de custo e memória são frustrantes; no entanto, dois agentes gravando no mesmo diretório de trabalho geram conflitos e defeitos impossíveis de rastrear, o que é muito mais destrutivo e complexo de depurar.

Este checklist é exclusivo para agentes de código?

Os modos de falha apresentados aqui, sim. Isolamento, verificações de escopo e revisões de diff existem porque o produto final é uma alteração direta em uma base de código compartilhada. Um agente que apenas lê dados ou escreve em seu próprio banco de dados possui dinâmicas diferentes.

Quantos agentes podem rodar em paralelo antes que isso se torne crítico?

Exatamente dois. Um único agente em um diretório isolado não precisa de nada disso. A partir do momento em que um segundo agente executa concorrentemente, o isolamento e o controle de custos deixam de ser opcionais, e a capacidade de revisão humana torna-se o gargalo do rendimento global, antes mesmo da velocidade de execução.

Aumentar o paralelismo eleva o rendimento indefinidamente?

Não. A revisão humana é sequencial. De acordo com a Lei de Amdahl, a fração sequencial estabelece o teto do sistema: adicionar agentes além do ponto de saturação dos revisores humanos apenas aumenta custos e taxas de rejeição, sem ampliar o volume de pull requests efetivamente integrados.

Primeiros passos com o Ivy Tendril

Pronto para a orquestração paralela de agentes em nível de engenharia?

Explore o código: Confira o Ivy Tendril no GitHub (Código aberto).
Consulte a documentação: Encontre guias de integração em tendril.ivy.app.
Agende uma sessão técnica: Entre em contato pelo e-mail renco@ivy.app para uma consultoria de arquitetura de 30 minutos.

Orquestração de agentes de IA pronta para produção: Checklist de 8 pontos para CTOs