Orquestrador de agentes para automação e evolução da Fábrica de Software.
O projeto tem como objetivo transformar gradualmente um processo de desenvolvimento assistido por IA em um sistema orquestrado, controlado, observável e, posteriormente, multiagente.
A arquitetura segue uma abordagem Spec Driven Agents, na qual o comportamento dos agentes é definido por contratos declarativos em Markdown, enquanto um runtime em Python é responsável por interpretar esses contratos e controlar a execução.
O ai-orchestrator será responsável por coordenar o ciclo de
desenvolvimento de uma feature dentro da Fábrica de Software.
O fluxo desejado, em sua versão completa, será aproximadamente:
HU / HUs
↓
Planner A
↓
Planner B
↓
Consensus
↓
Planejamento aprovado?
├── Não → Refinar planejamento
└── Sim
↓
Factory Planner
↓
Executor da Etapa
↓
Quality Gate
├── Tests
├── Lint
└── Audit
↓
Quality Gate aprovado?
├── Não → Executor → Quality Gate
└── Sim
↓
Reviewer
↓
Review aprovado?
├── Não → Executor → Quality Gate → Reviewer
└── Sim
↓
Próxima etapa
↓
...
↓
Concluído
O princípio fundamental é:
Toda alteração realizada pelo Executor deve obrigatoriamente passar novamente pelo Quality Gate antes de ser submetida ao Reviewer.
O projeto está atualmente em sua primeira fase de implementação.
Nesta versão já existem:
- contratos declarativos em Markdown;
- configurações estruturadas em YAML;
- carregamento dos contratos pelo Python;
- estado compartilhado da execução;
- runtime básico;
- Agent Loop inicial;
- Executor simulado;
- Quality Gate simulado;
- Reviewer simulado;
- limites contra loops infinitos;
- execução utilizando Docker.
Ainda não existem nesta versão:
- integração com LLM;
- integração com Codex;
- integração com Claude;
- execução real de testes;
- execução real de lint;
- execução real de audit;
- alteração automática de código;
- Planner A;
- Planner B;
- Consensus;
- persistência entre execuções;
- tracing;
- memória de longo prazo;
- integração com MCP.
Essas funcionalidades serão adicionadas progressivamente.
O comportamento dos agentes não deve ficar espalhado pelo código Python.
Ele deve ser descrito principalmente através dos contratos existentes em:
contracts/
Os contratos definem identidade, objetivos, responsabilidades, limites, permissões, critérios de parada, ferramentas disponíveis e comportamento esperado.
O runtime Python não deve conhecer regras específicas de uma feature.
Sua responsabilidade é:
Carregar contratos
↓
Construir estado
↓
Executar ciclo
↓
Avaliar resultados
↓
Aplicar regras
↓
Continuar ou finalizar
Isso permite reutilizar o mesmo runtime para diferentes agentes e diferentes features.
A LLM será utilizada posteriormente como mecanismo de raciocínio.
A arquitetura ao redor dela continuará sendo responsável por controle, permissões, estado, execução, ferramentas, segurança, observabilidade e critérios de parada.
LLM = raciocínio
Contratos = comportamento e limites
Runtime = execução e orquestração
Tools = ações disponíveis
State = estado da execução
ai-orchestrator/
│
├── contracts/
│ ├── agent.md
│ ├── loop.md
│ ├── executor.md
│ ├── reviewer.md
│ ├── toolbox.md
│ └── rules.md
│
├── src/
│ ├── __init__.py
│ ├── main.py
│ ├── contracts.py
│ ├── state.py
│ └── runtime.py
│
├── Dockerfile
├── docker-compose.yml
├── .dockerignore
├── .env.example
├── requirements.txt
└── README.md
Os contratos utilizam Markdown para documentação e YAML para configurações interpretáveis pelo runtime.
Define a identidade principal do agente: nome, descrição, tipo, objetivo e resultado esperado.
Define o comportamento do Agent Loop: número máximo de iterações, tentativas de QA, reviews e condições de parada. É fundamental para impedir loops infinitos.
Define o comportamento esperado do Executor. Ele executará a etapa atual, implementará alterações e corrigirá problemas. Toda execução ou correção deve ser seguida pelo Quality Gate.
Define o comportamento do Reviewer, que deve ser somente leitura. Ele analisa a implementação, identifica problemas, verifica aderência à especificação e às rules e aprova ou reprova.
Reviewer encontra problema
↓
Executor recebe feedback
↓
Executor corrige
↓
Quality Gate
↓
Reviewer novamente
Define quais ferramentas estão efetivamente disponíveis ao agente. Na primeira versão: tests, lint e audit. Futuramente poderão existir read_file, write_file, search_code, git_diff, git_status, APIs e MCP.
Define limites e regras obrigatórias, funcionando como guardrails do sistema.
O arquivo src/state.py define o AgentState, que representa a memória
de trabalho da execução atual.
Todos os componentes trabalham sobre esse mesmo estado:
AgentState
│
┌──────────┼──────────┐
▼ ▼ ▼
Executor QA Reviewer
Nesta fase, o estado existe apenas durante a execução atual. Persistência entre diferentes execuções será implementada posteriormente.
O arquivo src/contracts.py é responsável por carregar os contratos:
contracts/*.md
↓
Leitura Markdown
↓
Localização de ~~~yaml
↓
PyYAML
↓
dict Python
↓
Runtime
O arquivo src/runtime.py é o motor da aplicação.
Executor
↓
Quality Gate
↓
Passou?
┌───────┐
Não Sim
↓ ↓
Executor Reviewer
↓
Aprovou?
┌────────┐
Não Sim
↓ ↓
Executor Finaliza
O runtime também aplica limites para impedir execução infinita.
O Quality Gate representa validações determinísticas da implementação:
Tests + Lint + Audit
Sempre que possível, o resultado deve ser determinado por comandos reais e seus respectivos exit codes, não por uma LLM.
Se qualquer validação falhar, o fluxo retorna ao Executor. Depois da correção, o Quality Gate é executado novamente.
O Reviewer representa uma avaliação semântica da implementação.
Futuramente poderá utilizar uma LLM para analisar HU, especificação, plano de implementação, rules, código alterado, git diff e resultados do Quality Gate.
O Reviewer não modifica código. Quando reprova, fornece feedback ao Executor.
Autonomia não significa execução ilimitada.
Quando o sistema não conseguir avançar de forma segura, deverá
interromper a execução com human_intervention_required.
Isso será utilizado para falhas repetidas, divergências arquiteturais, alterações críticas, mudanças de contrato, segurança, operações destrutivas e situações sem progresso.
Inicialmente:
created
running
approved
human_intervention_required
Futuramente poderão ser adicionados:
planning
implementing
quality_gate
reviewing
failed
paused
completed
docker compose builddocker compose run --rm orchestratorDurante desenvolvimento, o diretório atual é montado em /app dentro do
container.
Nesta fase os resultados de Executor, Quality Gate e Reviewer são simulados.
Uma execução deverá produzir aproximadamente:
=================================
AI SOFTWARE FACTORY ORCHESTRATOR
=================================
Agente: factory-development-agent
Executor
Feature: feature-teste
Etapa: 1
Iteração: 1
Quality Gate
Executando testes...
Executando lint...
Executando audit...
Reviewer
Revisando implementação...
Etapa aprovada.
=================================
RESULTADO FINAL
=================================
Feature: feature-teste
Etapa: 1
Status: approved
Tentativas QA: 1
Tentativas Review: 1
Total de iterações: 1
Contratos, estado, runtime, Executor simulado, Quality Gate simulado, Reviewer simulado e limites de execução.
Status: em desenvolvimento.
Substituir a simulação pela execução real de tests, lint e audit, usando exit codes.
Registrar percepção, decisão, ação, resultado, avaliação, tempo e
tentativas. Gerar um trace.json por execução.
Integrar uma LLM ao Reviewer, mantendo-o read-only e com saída estruturada.
Integrar um agente capaz de ler, pesquisar e modificar código. Toda alteração continuará passando obrigatoriamente pelo Quality Gate.
Implementar o ciclo Executor → Quality Gate → Reviewer → feedback → Executor, com limites máximos de tentativas.
Adicionar Planner A, Planner B e Consensus. Os planejadores deverão analisar criticamente os resultados um do outro até atingir os critérios de aprovação.
Transformar o planejamento aprovado nas etapas operacionais da Fábrica de Software.
HU
↓
Planning
↓
Consensus
↓
Factory Planning
↓
Etapa
↓
Executor
↓
Quality Gate
↓
Reviewer
↓
Próxima etapa
↓
...
↓
Concluído
Adicionar persistência do estado, histórico de execuções, memória episódica, memória contextual e recuperação de experiências anteriores.
Integrar Filesystem, Git, GitLab, REST APIs, banco de dados e MCP.
Criar avaliações automatizadas para medir taxa de conclusão, qualidade, número de iterações, erros, escolha de ferramentas, custo, latência e intervenção humana.
HU / HUs
│
▼
PLANNING SYSTEM
/ \
Planner A Planner B
\ /
── Consensus ──
│
▼
Factory Planner
│
▼
Executor
│
▼
Quality Gate
/ | \
Tests Lint Audit
\ | /
│
▼
Reviewer
/ \
Reprovado Aprovado
│ │
▼ ▼
Executor Próxima etapa
│ │
└─────── ... ─┘
│
▼
Concluído
Todo o processo será governado por:
Contracts
+
Rules
+
State
+
Runtime
+
Observability
+
Human-in-the-loop
O objetivo não é eliminar o engenheiro do processo.
O objetivo é automatizar tarefas repetitivas e ciclos de análise, implementação e revisão, mantendo controle, rastreabilidade, qualidade e possibilidade de intervenção humana.