Um laboratório para experimentar, discutir e construir primitivas reutilizáveis de agentes de IA.

agents-lab é um espaço de pesquisa e desenvolvimento dedicado ao ecossistema de agentes de IA. O objetivo central é canalizar todo o potencial ao redor em um único local onde possamos:

• 🔬 Experimentar — rodar experimentos controlados com diferentes engines de agentes
• 📚 Documentar — organizar pesquisas, análises e aprendizados de forma acessível
• 🧩 Construir primitivas — criar blocos reutilizáveis que possam ser compartilhados com a comunidade
• 📊 Avaliar — comparar abordagens, frameworks e filosofias de design
• 🚀 Evoluir — superar qualquer engine específica caso o ecossistema avance

A engine primária deste laboratório é o pi — um toolkit altamente extensível para construção de agentes de IA e gerenciamento de LLMs. Pi se prova excelente para "mess around and find out" e serve como engine de sistemas maiores.

• Extensibilidade — projetado para ser a fundação de outros sistemas (ex.: openclaw)
• Filosofia sólida — convergência natural para o que uma engine de agentes precisa ser
• Ecossistema crescente — pacotes disponíveis em constante expansão
• Multi-provider — suporta OpenAI, Anthropic, Google e outros via @mariozechner/pi-ai

Este repositório é a fábrica onde a curadoria nasce. Os pacotes first-party são construídos aqui e distribuídos via npm:

Nota: Apesar do Pi ser a engine principal, a estrutura do laboratório é deliberadamente engine-agnóstica. Caso surjam implementações superiores, podemos migrar sem perder o trabalho acumulado.

agents-lab/
├── packages/
│   ├── pi-stack/       # @aretw0/pi-stack — installer + extensions first-party
│   ├── git-skills/     # @aretw0/git-skills — commit, git-workflow, github, glab
│   ├── web-skills/     # @aretw0/web-skills — web-browser (CDP)
│   ├── pi-skills/      # @aretw0/pi-skills — terminal-setup, create-pi-*, test-pi-extension
│   └── lab-skills/     # @aretw0/lab-skills — evaluate, cultivate, feedback
├── scripts/
│   └── pi-source-switch.mjs  # Alterna entre dev local e pacotes npm
├── docs/
│   ├── research/       # Pesquisas, análises e material de referência
│   ├── guides/         # Guias práticos de uso, configuração e publicação
│   ├── primitives/     # Conceitos e catálogo de primitivas de agentes
│   └── engines/        # Comparações e análises de engines (Pi e alternativas)
├── experiments/        # Experimentos práticos e provas de conceito
├── primitives/         # Código reutilizável de primitivas de agentes
├── .changeset/         # Changesets pendentes para o próximo release
├── .github/workflows/  # CI (conventional commits) e publish (tag → npm)
├── CONTRIBUTING.md     # Como contribuir e como fazer releases
└── ROADMAP.md          # Planejamento e milestones futuros

A stack curada instala cada pacote individualmente no pi (mesmo padrão do oh-pi):

# Stack completa — instala 17 pacotes via pi install
npx @aretw0/pi-stack

# Com versão fixa para @aretw0/*
npx @aretw0/pi-stack --version 0.3.0

# Instalação local (projeto)
npx @aretw0/pi-stack --local

# Remover tudo
npx @aretw0/pi-stack --remove

Ou instale pacotes individuais:

pi install npm:@aretw0/git-skills
pi install npm:@aretw0/pi-skills
pi install npm:@ifi/oh-pi-themes

Via git (sempre atualizado, sem esperar publish):

pi install https://github.com/aretw0/agents-lab

Para desenvolver pacotes do monorepo usando o pi:

git clone https://github.com/aretw0/agents-lab.git
cd agents-lab
npm install

# Apontar pi para os pacotes locais do workspace
npm run pi:local

# Verificar configuração atual
npm run pi:status

# Checar paridade user-like vs laboratório (consumo/quota/superfícies)
npm run pi:parity
npm run pi:parity:project

# Voltar para pacotes publicados no npm
npm run pi:published

# Overlay opcional para pilot de colony (/monitors, /remote, /colony)
# (escopo user por padrão, sem sujar .pi/settings.json do repositório)
npm run pi:pilot:on
npm run pi:pilot:status
npm run pi:pilot:off

# Se quiser alterar o settings do projeto explicitamente
npm run pi:pilot:on:project
npm run pi:pilot:off:project

O .pi/settings.json do projeto já aponta para os pacotes locais automaticamente. Para cenários de pilot, use o overlay opcional acima (explícito e reversível).

Este monorepo usa @marcfargas/pi-test-harness para testes automatizados:

# Rodar todos os testes
npm run test:smoke

# Testes unitários de extensões
npm test

A skill test-pi-extension (em @aretw0/pi-skills) documenta como criar testes para suas próprias extensões.

• pi-mono — repositório oficial
• Guias deste laboratório
  • Web Session Gateway
  • Colony Runtime Recovery
• Pesquisas e análises

Veja CONTRIBUTING.md para como participar deste laboratório.

Veja ROADMAP.md para os próximos passos planejados.

MIT — veja LICENSE.