ADR-0026 SDK e API de Extensões | Wiki
ADR-0026 SDK e API de Extensões
- *Status:* Aceito
- *Data:* 2026-06-10
Contexto
Atualmente temos um ACI Harness em apps/gbr-ai/agent, contendo componentes reutilizáveis em apps/gbr-ai/core e compartilhados em apps/gbr-ai/shared. Precisávamos analisar a viabilidade de criar um SDK e API de Extensões para o agente, além de refatorar nossa estrutura para separar adequadamente a camada de biblioteca (SDK) da camada executável (Harness).
A análise também se debruçou sobre modelos de mercado, como o Memlite (memória episódica com SQLite) e o Zeptoclaw (arquitetura segura por padrão, single-binary e sandboxed), buscando inspiração para a evolução da arquitetura de IA do ecossistema Gleam-BR.
Decisão
Optamos por refatorar e separar as responsabilidades do atual apps/gbr-ai/* nas seguintes frentes:
-
**
packages/gbr_ai_sdk(SDK)**: A lógica genérica, abstração de provedores (Gemini, Claude, etc), contratos de Prompt, Tool Calling e componentes de memória episódica (inspirados pelo Memlite) residirão neste pacote. Ele será o fundamento padrão de IA reutilizável por qualquer projeto dentro e fora do monorepo. -
**
apps/gbr_ai_harness(Harness)**: Toda a lógica de execução, ciclo de vida (agent) e interface de usuário do terminal (etui) ficará contida nesta aplicação. Inspirado no Zeptoclaw, atua como o "motor" ou "host" confiável e seguro para os agentes. O módulo de TUI (etui) será integrado preservando-se sua natureza de submódulo sem alterações de código-fonte desnecessárias. -
*API de Extensões via MCP: A principal via de extensibilidade para os agentes construídos sobre essa infraestrutura será o *Model Context Protocol (MCP)**. Extensões locais ou remotas, inclusive ferramentas "built-in", utilizarão o modelo MCP para integração. Prevê-se a evolução futura do modelo de transporte de stdio para uma malha P2P (Discovery via Gossipsub).
Consequências
- *Positivas*: - Isolamento limpo entre o motor de integração/regras de IA (SDK) e o ambiente de execução (Harness). - Padronização da comunicação com ferramentas usando MCP, unificando a integração de extensões internas e externas. - Fornece um fundamento seguro e bem arquitetado para o projeto Gleam Architect (ADR-0023).
-
*Negativas / Desafios*:
- Obriga a atualização de topologia em projetos dependentes (como
gbr_gleam_ai). - Adaptação das ferramentas e fluxos construídos localmente para que correspondam de forma estrita ao contrato do Model Context Protocol.