Explicações de funções 01: Motor de orquestração

Do primeiro pedido ao patch verificado

O Agent Argo não consiste em um único modelo que trabalha em uma tarefa pelo maior tempo possível. É um sistema que traduz o trabalho de software em etapas compreensíveis: planejar, dividir, executar, verificar, corrigir e só então submeter para adoção.

Com esta publicação começa a série “Explicações de funções”. Ela torna compreensíveis os mecanismos centrais do Agent Argo – não como promessa de marketing, mas ao longo de seu uso real. A abertura é feita pelo Motor de Orquestração: o fluxo que transforma um requisito em um processo de trabalho controlado.

1. Antes do início: definir qualidade, custos e autonomia

Antes de o Argo processar uma tarefa, duas decisões são importantes. Elas são deliberadamente separadas uma da outra:

1. Como o Argo deve ponderar entre custos e qualidade do resultado?
2. Quão independente o Argo pode agir no projeto?

Isso evita um conflito de objetivos típico: uma execução minuciosa não precisa receber automaticamente mais direitos de escrita. E uma execução autônoma não precisa selecionar automaticamente modelos caros.

As três faixas para custos e qualidade

O roteador de modelos conhece três modos compreensíveis. Eles alteram o quanto preço e nível de modelo entram na seleção; a habilidade necessária permanece sempre central.

Faixa	Modo do roteador	Adequado para
Econômico	economy	Tarefas de rotina, extração, mudanças claramente delimitadas. Custos pesam fortemente.
Equilibrado	balanced	O padrão para a maioria das execuções: o ajuste de habilidade, custos e nível de qualidade permanecem em equilíbrio.
Exigente	expert	Arquitetura, pesquisa, análises complexas e revisões exigentes. Nível de modelo pesa significativamente mais, custos menos.

Os perfis operacionais Rápido e barato, Equilibrado e Minucioso agrupam este modo do roteador com outras decisões: por exemplo, se o pensamento compartilhado é apenas observado ou executado ativamente, se a verificação é obrigatória e se o Argo pode escalar mais forte em caso de tentativa falha.

As três faixas de autonomia

A autonomia não regula o que o Argo considera correto, mas quando ele precisa de um humano para isso.

Faixa	Comportamento
Seguro	O Argo analisa e planeja. Mudanças ficam para revisão; antes de ações de escrita ou arriscadas, pergunta-se.
Equilibrado	Mudanças normais podem surgir em um estado de trabalho isolado. Em caso de exclusão, comandos, downloads, acesso de rede ou caminhos protegidos, o Argo continua perguntando.
Totalmente autônomo	A execução trabalha sem perguntas habituais. Limites rígidos de segurança, política e orçamento continuam valendo.

No código, essas regras são implementadas com mais precisão como readonly, confirm_write, auto_write e bypass. As três faixas as tornam operáveis; a política do projeto, porém, continua sendo sempre a instância final. Ela pode, por exemplo, excluir provedores de nuvem, permitir apenas modelos locais, bloquear acessos de rede, limitar comandos, proteger segredos ou definir um limite de custos.

2. A camada CEO transforma o pedido em um plano

O usuário descreve primeiro o objetivo em linguagem normal. A camada CEO do Argo recebe um panorama limitado do projeto, o catálogo de modelos disponível e informações relevantes do projeto. Ela pode, em caso de dúvidas em aberto, primeiro perguntar ou gerar um plano.

Um plano contém não apenas uma lista de tarefas. Cada tarefa recebe uma função, uma descrição, dependências e habilidades necessárias – por exemplo coding, planning, qa_review ou context_comprehension. Para tarefas difíceis, também pode ser anotada uma dificuldade maior. A camada CEO não nomeia rigidamente um modelo: ela descreve o trabalho, o roteador decide depois por tarefa o modelo adequado.

O plano permanece assim o acordo legível por humanos sobre o empreendimento, enquanto a execução pode permanecer adaptativa.

3. Do plano surge um grafo de tarefas

Após a liberação do plano, o Argo transforma as tarefas em um grafo de tarefas. Um nó só pode rodar quando suas dependências forem concluídas com sucesso. Tarefas independentes podem rodar em paralelo.

O agendador ordena nós prontos por uma heurística de utilidade compreensível: qualidade esperada menos penalidade de custo, tempo e risco. Se um nó está no caminho crítico, recebe prioridade em caso de empate, pois determina a duração total da execução.

Em caso de alta incerteza ou alto risco, o Argo pode selecionar antes do processamento um modo de pensamento compartilhado: múltiplas perspectivas desenvolvem abordagens, criticam-se mutuamente e entregam uma abordagem de trabalho fundamentada para o worker. Se isso é apenas registrado ou realmente executado, decide o perfil operacional escolhido antes da execução.

4. Antes de cada tarefa: contexto adequado, habilidades adequadas, modelo adequado

Antes de um worker iniciar, o Argo constrói um contexto adaptado à função e à tarefa. Isso inclui arquivos relevantes, resultados de dependências e – se ativado – um pacote de memória compacto e instruções de habilidade adequadas. O Argo não incorpora cegamente todo o conhecimento do projeto no prompt. Memória e habilidades são selecionadas por relevância, origem, atualidade, custo e status de segurança.

Então o roteador de modelos seleciona um modelo. Primeiro, candidatos são excluídos que não estão acessíveis, não têm janela de contexto suficiente, cujo contingente está esgotado ou que violam a política ativa. Dos modelos restantes, o Argo avalia quatro fatores:

• Ajuste de habilidade: Quão bem um modelo é avaliado para as habilidades necessárias? Com múltiplas habilidades, considera-se a média.
• Custos: Quão caro é o pedido – ou, com roteamento de custo ativo, o resultado provavelmente bem-sucedido?
• Nível de modelo: Tarefas difíceis, críticas de segurança, de arquitetura e de revisão podem preferir uma faixa flagship.
• Valores de experiência: Após resultados reais suficientes, entram a taxa de sucesso e de repetição mais recente de uma combinação modelo/habilidade.

Para o cálculo de custos, o Argo pode usar o Custo Esperado de Sucesso: preço direto, repetições esperadas, esforço de verificação, possível retrabalho e uma pequena penalidade de latência. Uma chamada única barata não é, portanto, automaticamente a solução mais barata, se falha com mais frequência ou dispara retrabalho.

Uma recomendação de modelo explícita só é aceita se estiver disponível, for permitida pela política e for grande o suficiente para o contexto. Planejamento, delegação e compreensão de contexto da camada CEO usam, por sua vez, um modelo forte, selecionado especificamente para essas três habilidades.

5. O worker processa a tarefa em passos pequenos e verificáveis

Um worker não trabalha com uma única resposta. Ele percorre um loop ReAct limitado:

1. O modelo propõe ações estruturadas – como ler arquivos, pesquisar, executar testes ou escrever mudanças.
2. O executor verifica permissão, caminho, risco de comando e política ativa.
3. O Argo executa apenas ações permitidas.
4. Resultados, diffs e mensagens de erro retornam como observação ao modelo.
5. Com base nisso, o worker corrige seu próximo passo ou conclui a tarefa.

Assim, um agente pode, por exemplo, primeiro ler o código afetado, depois fazer uma mudança, executar um teste e incluir um resultado de teste na próxima decisão. O fluxo completo permanece visível no log de execução.

Também a saída em si é verificada. Se um modelo entrega JSON de ação inválido, o Argo pode solicitar um loop de reparo limitado. No modo estrito, uma saída permanentemente defeituosa é rejeitada de forma controlada, em vez de interpretar texto ambíguo como ação.

6. Em erros: corrigir direcionadamente em vez de repetir cegamente

Nem toda tarefa falha significa que a execução inteira fracassou. O Motor de Orquestração distingue causas de erro e reage de forma controlada:

• Um erro temporário pode ser tentado novamente dentro de limites fixos.
• Um resultado de verificação rígido entrega sua objeção concreta como pedido para a próxima tentativa.
• Com cascata ativada, a próxima tentativa assume as percepções da anterior, em vez de começar do zero.
• Após uma tentativa falha, o Argo pode preferir um modelo mais forte.
• Se um orçamento se esgota, nenhuma tentativa cega cara é iniciada: o nó termina com um resultado parcial documentado ou é escalado visivelmente.

A estratégia de nó decide finalmente se uma tarefa pode ser pulada, falha de forma controlada ou precisa de uma decisão do usuário. Tarefas dependentes recebem exclusivamente resultados parciais confirmados. Assim, de um erro local não surge um erro silencioso que se propaga pelo resto do plano.

7. Após a implementação: revisão, verificação e um possível ciclo adicional

Quando as tarefas planejadas são processadas, o Argo verifica o estado integrado sob múltiplos ângulos:

• O agente QA pode ler arquivos e executar comandos de teste.
• O agente de arquitetura verifica a estrutura em modo de leitura e permanece deliberadamente sem direitos de escrita.
• Verificadores determinísticos podem executar testes, checagem de tipos ou linting como oráculos objetivos.
• Constatações baseadas em modelo e determinísticas são reunidas em um veredito geral.

Se QA, arquitetura ou um verificador obrigatório encontram problemas, o Argo atribui as constatações às tarefas afetadas. Apenas essas tarefas são reprocessadas com o feedback concreto. Depois segue nova revisão e verificação. Sem modo de consenso, esse loop é limitado; em um modo de consenso expressamente escolhido, ele continua até o usuário parar ou os revisores concordarem.

Um verificador em modo de observação documenta constatações, mas não bloqueia. No modo obrigatório, uma constatação rígida pode impedir que o resultado conte como bem-sucedido. Assim, a rigorosidade pode ser escolhida por perfil operacional, sem abrir mão da rastreabilidade.

8. Só quando o estado é verificado: documentação e resumo da CEO

Após um ciclo de trabalho e verificação concluído, um agente de documentação pode registrar as mudanças. Em seguida, a camada CEO elabora o resumo para o usuário: O que foi concluído? O que ficou em aberto? Quais verificações rodaram? Quais arquivos ou decisões são afetados?

O resultado é mais que um texto de chat. A execução carrega uma identificação comum para plano, escolha de modelo, custos, ações, vereditos de verificação, interrupções do usuário e decisões de patch posteriores. Assim, pode-se rastrear como o Argo chegou a um resultado.

9. Ao final, o humano decide sobre o workspace real

Por padrão, o Argo trabalha em um worktree isolado. As mudanças ficam lá como patch, não silenciosamente no projeto real. Conforme a faixa de autonomia, acontece então uma de três coisas:

• O patch fica pronto para adoção, adoção parcial, edição ou descarte.
• Um patch bem-sucedido é adotado automaticamente.
• Em caso de conflitos com arquivos alterados nesse meio tempo, o Argo para visivelmente; não sobrescreve mudanças alheias.

Uma execução falha não é aplicada automaticamente. Mesmo uma configuração muito autônoma não revoga a política: proteção de segredos, regras de comando, limites de provedor, limites de orçamento e gates humanos necessários continuam vigentes.

O que o Motor de Orquestração realiza

O Motor de Orquestração não decide apenas qual modelo responde a seguir. Ele conecta intenção do usuário, configurações, planejamento, paralelização, escolha de modelo, uso de ferramentas, correção de erros, garantia de qualidade e adoção segura em um fluxo coerente.

A medida não é “o máximo de agentes possível”. Trabalho adicional surge apenas onde é justificado: um modelo mais forte para uma decisão de arquitetura difícil, uma segunda abordagem de pensamento em incerteza, um retry direcionado após objeção de verificador ou uma liberação humana antes de um efeito arriscado.

O rumo está assim traçado.