Explicações de Funcionalidades 01: Motor de Orquestração

Do primeiro pedido ao patch verificado

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

Com este artigo começa a série “Explicações de Funcionalidades”. Ela torna compreensíveis os mecanismos centrais do Agent Argo – não como promessa de marketing, mas ao longo do seu uso efetivo. A abertura é feita pelo Motor de Orquestração: o fluxo que transforma um requisito num 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. Estão deliberadamente separadas uma da outra:

1. Como deve o Argo ponderar entre custos e qualidade do resultado?
2. Com que independência pode o Argo atuar no projeto?

Isto evita um conflito de objetivos típico: uma execução cuidadosa não tem de receber automaticamente mais direitos de escrita. E uma execução autónoma não tem de escolher automaticamente modelos caros.

Os três níveis para custos e qualidade

O router de modelos conhece três modos compreensíveis. Alteram a forma como preço e nível de modelo influenciam a seleção; a competência necessária permanece sempre central.

Os perfis operacionais Rápido e barato, Equilibrado e Cuidadoso agrupam este modo do router com outras decisões: por exemplo, se o pensamento partilhado é apenas observado ou executado ativamente, se a verificação é obrigatória e se o Argo pode escalar mais perante uma tentativa falhada.

Os três níveis de autonomia

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

No código estas regras estão implementadas com mais detalhe como readonly, confirm_write, auto_write e bypass. Os três níveis tornam-nas operáveis; a política do projeto continua, porém, sempre a instância final. Pode, por exemplo, excluir fornecedores de nuvem, permitir apenas modelos locais, bloquear acessos de rede, limitar comandos, proteger segredos ou definir um limite de custos.

2. O nível CEO transforma o pedido num plano

O utilizador descreve primeiro o objetivo em linguagem normal. O nível CEO do Argo recebe para isso uma visão limitada do projeto, o catálogo de modelos disponível e informações relevantes do projeto. Pode, perante dúvidas em aberto, primeiro questionar ou gerar um plano.

Um plano não contém apenas uma lista de tarefas. Cada tarefa recebe uma função, uma descrição, dependências e capacidades necessárias – por exemplo coding, planning, qa_review ou context_comprehension. Para tarefas difíceis pode também ser assinalada uma dificuldade superior. O nível CEO não indica rigidamente um modelo: descreve o trabalho, o router decide depois por tarefa o modelo adequado.

O plano mantém-se assim o acordo legível por humanos sobre o empreendimento, enquanto a execução pode permanecer adaptativa.

3. Do plano nasce um grafo de tarefas

Após a aprovação do plano, o Argo transforma as tarefas num grafo de tarefas. Um nó só pode executar quando as suas dependências estão concluídas com sucesso. Tarefas independentes podem correr em paralelo.

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

Perante alta incerteza ou alto risco, o Argo pode selecionar antes do processamento um modo de pensamento partilhado: várias perspetivas desenvolvem abordagens, criticam-se mutuamente e fornecem uma abordagem de trabalho fundamentada para o worker. Se isso é apenas registado ou realmente executado decide o perfil operacional escolhido antes da execução.

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

Antes de um worker arrancar, o Argo constrói um contexto adaptado à função e tarefa. Isto inclui ficheiros relevantes, resultados de dependências e – se ativado – um pacote de memória compacto bem como instruções de skill adequadas. O Argo não assume cegamente todo o conhecimento do projeto no prompt. Memória e skills são selecionados por relevância, origem, atualidade, custos e estado de segurança.

Depois o router de modelos escolhe um modelo. Primeiro são excluídos candidatos 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 capacidade: Quão bem é um modelo avaliado para as skills necessárias? Com várias skills considera-se a média.
• Custos: Quão caro é o pedido – ou com routing 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 um nível flagship.
• Valores de experiência: Após resultados reais suficientes entram a taxa de sucesso e repetição recente de uma combinação modelo/skill.

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 penalização de latência. Uma chamada individual barata não é, portanto, automaticamente a solução mais barata se falha com mais frequência ou provoca retrabalho.

Uma recomendação de modelo explícita só é aceite se estiver disponível, permitida pela política e for grande o suficiente para o contexto. Planeamento, delegação e compreensão de contexto do nível CEO usam, por seu turno, um modelo forte selecionado especificamente para estas três capacidades.

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

Um worker não trabalha com uma única resposta. Percorre um ciclo ReAct limitado:

1. O modelo propõe ações estruturadas – como ler ficheiros, pesquisar, executar testes ou escrever alterações.
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 regressam como observação ao modelo.
5. Com base nisto o worker corrige o próximo passo ou conclui a tarefa.

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

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

6. Perante erros: corrigir com precisão em vez de repetir cegamente

Nem toda a tarefa falhada significa que a execução inteira falhou. 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 fornece a sua objeção concreta como pedido para a próxima tentativa.
• Com cascata ativada a próxima tentativa assume as conclusões da anterior, em vez de começar do zero.
• Após uma tentativa falhada o Argo pode preferir um modelo mais forte.
• Se um orçamento esgotar, não se inicia uma tentativa cega cara: o nó termina com um resultado parcial documentado ou é escalado visivelmente.

A estratégia de nó decide finalmente se uma tarefa pode ser ignorada, falha de forma controlada ou necessita de decisão do utilizador. Tarefas dependentes recebem exclusivamente resultados parciais confirmados. Assim de um erro local não nasce 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

Estão as tarefas planeadas processadas, o Argo verifica o estado integrado sob vários ângulos:

• O Agente QA pode ler ficheiros e executar comandos de teste.
• O Agente de Arquitetura verifica a estrutura em leitura e permanece deliberadamente sem direitos de escrita.
• Verificadores determinísticos podem executar testes, verificação de tipos ou linting como oráculos objetivos.
• Resultados baseados em modelo e determinísticos são reunidos num veredito global.

Se QA, Arquitetura ou um verificador obrigatório encontram problemas, o Argo atribui os resultados às tarefas afetadas. Apenas estas tarefas são reprocessadas com o feedback concreto. Depois segue-se nova revisão e verificação. Sem modo de consenso este ciclo é limitado; num modo de consenso expressamente escolhido corre até o utilizador parar ou os revisores concordarem.

Um verificador em modo de observação documenta resultados, mas não bloqueia. No modo obrigatório um resultado rígido pode impedir que o resultado conte como bem-sucedido. Assim a rigorosidade pode ser escolhida por perfil operacional, sem perder a rastreabilidade.

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

Após um ciclo de trabalho e verificação concluído um agente de documentação pode registar as alterações. Em seguida o nível CEO cria o resumo para o utilizador: O que foi concluído? O que ficou em aberto? Que verificações decorreram? Que ficheiros ou decisões estão afetados?

O resultado é mais do que um texto de chat. A execução conduz uma identificação comum para plano, escolha de modelo, custos, ações, vereditos de verificação, interrupções do utilizador e decisões de patch posteriores. Isto permite compreender como o Argo chegou a um resultado.

9. No final o humano decide sobre o workspace real

Por padrão o Argo trabalha num worktree isolado. As alterações ficam lá como patch, não silenciosamente no projeto real. Conforme o nível de autonomia acontece depois uma de três coisas:

• O patch fica pronto para aceitação, adoção parcial, edição ou rejeição.
• Um patch bem-sucedido é adotado automaticamente.
• Em conflitos com ficheiros entretanto alterados o Argo para visivelmente; não sobrepõe alterações alheias.

Uma execução falhada 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 fornecedor, limites de orçamento e gates humanos necessários permanecem ativos.

O que o Motor de Orquestração realiza

O Motor de Orquestração não decide apenas qual modelo responde a seguir. Liga intenção do utilizador, definições, planeamento, paralelização, escolha de modelo, uso de ferramentas, correção de erros, garantia de qualidade e adoção segura num fluxo coerente.

A medida não é “o maior número 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 perante incerteza, um retry direcionado após objeção de verificador ou uma autorização humana antes de um efeito arriscado.

O rumo está assim traçado.