agents-lab

Local-first lab for reusable AI-agent primitives and the curated pi-stack.

View on GitHub

Governança de Provider/Modelo para Colônia e Multi-Agentes

Guia para reduzir fricção ao usar ant_colony com múltiplos providers (Copilot/Codex/etc.) no @aretw0/pi-stack.

Objetivo

Garantir que o uso de multi-agentes fique previsível para:

Superfícies de configuração (quem controla o quê)

Superfície Onde configurar Impacto
Sessão principal defaultProvider / defaultModel em settings Modelo usado pela sessão atual do pi
Classifiers de monitor piStack.monitorProviderPatch.* + /monitor-provider Saúde dos monitores (hedge, fragility, etc.)
Colônia (ant_colony) modelo atual da sessão + overrides por caste Scout/worker/soldier e classes específicas
Governança de execução da colônia piStack.colonyPilot.preflight.* + /colony-pilot Gate de capacidades/executáveis antes de rodar
Governança de orçamento da colônia piStack.colonyPilot.budgetPolicy.* + /colony-pilot Exigir/injetar maxCost, cap de custo e mínimo operacional

Estado atual no agents-lab

1) Monitores (davidorex)

Resolvido com patch provider-aware:

2) Colônia (@ifi/oh-pi-ant-colony)

Comportamento importante:

3) Pilot de orquestração (colony-pilot first-party)

/colony-pilot check agora cobre:

Convenção: /doctor é saúde global. /colony-pilot e /monitor-provider são diagnósticos de domínio.

Modelos recomendados (baseline prático)

Perfil Copilot

Perfil Codex

Heurística: scout mais barato/rápido, worker/soldier mais fortes.

Spark gating policy (OpenAI Codex)

Para preservar a cota PRO separada de gpt-5.3-codex-spark, a política operacional é:

Config recomendada em .pi/settings.json:

{
  "piStack": {
    "colonyPilot": {
      "modelPolicy": {
        "sparkGateEnabled": true,
        "sparkAllowedGoalTriggers": ["planning recovery", "scout burst"],
        "sparkScoutOnlyTrigger": "scout burst"
      }
    }
  }
}

Policy de retenção de candidate churn (first-party)

Para reduzir perda de contexto quando mirrors/worktrees desaparecem (cleanup externo), o colony-pilot mantém retenção local em .pi/colony-retention/*.json para sinais terminais.

Configuração em .pi/settings.json:

{
  "piStack": {
    "colonyPilot": {
      "candidateRetention": {
        "enabled": true,
        "maxEntries": 40,
        "maxAgeDays": 14
      }
    }
  }
}

Notas operacionais:

Checklist operacional (usuário pi-stack)

  1. /doctor (saúde global)
  2. /monitor-provider status
  3. /monitor-provider apply (se houver drift)
  4. /colony-pilot models apply codex (perfil generic-first para ambiente Codex-only)
  5. /colony-pilot models status
  6. /colony-pilot check
  7. /colony-pilot preflight
  8. rodar colônia com budget explícito (ant_colony com maxCost)
  9. monitorar janela/limite com /usage + histórico com /quota-visibility windows

Se quiser observabilidade web local:

Diretriz atual: generic-first

No estado atual do laboratório (especialmente quando só há Codex disponível), a recomendação é:

Isso evita crescimento acidental de complexidade e melhora coesão da arquitetura.

Perfis rápidos de model policy

Esses perfis escrevem piStack.colonyPilot.modelPolicy no .pi/settings.json e ativam hard-gate no tool_call de ant_colony.

A baseline também pode configurar piStack.colonyPilot.budgetPolicy para exigir/injetar maxCost e bloquear caps acima do limite definido.

Perfis rígidos para fábrica de agentes:

Todos eles:

No factory-strict-hybrid, a mistura de provider é controlada por papel (allowedProvidersByRole), por exemplo:

Exemplo de ant_colony com overrides explícitos

{
  "goal": "Refatorar módulo X com testes",
  "maxAnts": 3,
  "maxCost": 2,
  "scoutModel": "openai-codex/gpt-5.4-mini",
  "workerModel": "openai-codex/gpt-5.3-codex",
  "soldierModel": "openai-codex/gpt-5.2-codex"
}

Diretrizes para devs do agents-lab

  1. Não usar chaves reservadas com shape inválido em settings
    • extensions em settings é lista de paths (string[]), não objeto de config.
    • Config first-party deve ficar em namespace próprio: piStack.<extensão>.
  2. Sempre tratar provider/model como referência completa
    • usar provider/model em defaults e docs.
  3. Separar responsabilidades
    • /doctor: runtime global
    • comandos de domínio (/monitor-provider, /colony-pilot): validação específica
  4. Pensar em swarms como uma abordagem, não dogma
    • colony é um estilo de orquestração útil hoje
    • primitivas first-party futuras devem manter contrato de configuração claro e intercambiável

Relação com referências externas (ex.: tuts)

As referências de padrões multi-agente (incluindo exemplos tipo “tuts”) são úteis para desenho de arquitetura, mas no agents-lab o critério operacional é:

Ou seja, padrão conceitual externo entra, mas governança operacional segue os contratos do pi-stack.