| # Agent OS - Documentacao Tecnica |
|
|
| ## Visao Geral |
|
|
| Agent OS e um sistema operacional de agentes IA. Uma interface desktop-like (macOS-style) que orquestra multiplos modelos de IA especializados atraves de um modelo gestor central. Cada agente e um "slot" plugavel que pode ser trocado, adicionado ou removido facilmente. |
|
|
| ## Arquitetura |
|
|
| ``` |
| ┌──────────────────────────────────────────────────────────────┐ |
| │ AGENT OS (Frontend React) │ |
| │ ┌─────────┬──────────┬──────────┬────────┬────────┬───────┐ │ |
| │ │ Browser │ Terminal │ Inbox │Mission │ Agents │Finder │ │ |
| │ │ │ │ │Control │ │ │ │ |
| │ └─────────┴──────────┴──────────┴────────┴────────┴───────┘ │ |
| ├──────────────────────────────────────────────────────────────┤ |
| │ SERVER (Node.js + Express) │ |
| │ ┌──────────┬──────────┬──────────┬──────────┬─────────────┐ │ |
| │ │ Browser │ PM2 │ Supabase │ GitHub │ SmolAgent │ │ |
| │ │ Manager │ API │ API │ CLI │ Daemon │ │ |
| │ └──────────┴──────────┴──────────┴──────────┴─────────────┘ │ |
| ├──────────────────────────────────────────────────────────────┤ |
| │ CAMADA DE ORQUESTRACAO │ |
| │ ┌──────────────────────────────────────────────────────────┐ │ |
| │ │ MODELO GESTOR (Orchestrator) │ │ |
| │ │ Recebe tarefa → Classifica → Roteia → Retorna │ │ |
| │ │ Llama 3.3 70B via HF Inference API (gratis, Pro) │ │ |
| │ └─────────────┬────────────┬───────────────┬───────────────┘ │ |
| │ │ │ │ │ |
| │ ┌─────────────┴┐ ┌───────┴──────┐ ┌─────┴──────────────┐ │ |
| │ │ Agent Slot 1 │ │ Agent Slot 2 │ │ Agent Slot N │ │ |
| │ │ Coding │ │ SQL/Data │ │ (plugavel) │ │ |
| │ │ Opus 4.6 API │ │ 1.5B local │ │ qualquer modelo │ │ |
| │ └──────────────┘ └──────────────┘ └────────────────────┘ │ |
| ├──────────────────────────────────────────────────────────────┤ |
| │ MEMORIA CENTRAL │ |
| │ ┌──────────────────────────────────────────────────────────┐ │ |
| │ │ Basic Memory (MCP Server) │ │ |
| │ │ Markdown files + SQLite + Vector Embeddings │ │ |
| │ │ Persistente entre sessoes e agentes │ │ |
| │ └──────────────────────────────────────────────────────────┘ │ |
| └──────────────────────────────────────────────────────────────┘ |
| ``` |
|
|
| ## Stack Atual |
|
|
| ### Frontend (React + TypeScript + Vite) |
| - **Desktop**: Interface macOS-style com janelas arrastáveis, dock, menu bar |
| - **Window Manager**: Zustand store (`useAppStore`) com persist |
| - **Apps**: Registry plugavel (`appRegistry.ts`) |
| - **Componentes**: Desktop, Dock, MenuBar, WindowFrame |
|
|
| ### Backend (Node.js + Express) |
| - **Porta**: 3000 |
| - **APIs implementadas**: |
| - `/api/browsers/*` - Browser automation via Playwright (criar, navegar, clicar, digitar, screenshot) |
| - `/api/pm2/*` - Process manager (listar, restart, stop, logs) |
| - `/api/supabase/*` - Supabase CLI proxy (auth, projetos, tabelas, SQL) |
| - `/api/github/*` - GitHub CLI proxy (auth, repos, issues, PRs, notificacoes) |
| - `/api/smol/chat` - SmolAgent daemon proxy (porta 8082) |
| - `/api/launcher/*` - Proxy pro claude-launcher-web (porta 3002) |
| - `/ws` - WebSocket para terminal, browser streaming, file watching |
|
|
| ### Infra (Vultr - 207.246.65.100) |
| - **OS**: Ubuntu, 4 CPU, 8GB RAM, sem GPU |
| - **Processos ativos**: |
| - `server.js` (porta 3000) - Frontend + API |
| - `smol-daemon.py` (porta 8082) - SmolAgent backend |
| - `llama-server` (porta 8080) - Modelo 1.5B local CPU |
| - `launcher/server.js` (porta 3002) - Claude launcher |
| - `agent-bot` (porta 9090) - Bot auxiliar |
|
|
| ## App Registry |
|
|
| O sistema de apps e plugavel. Cada app registrado no `appRegistry.ts`: |
|
|
| | App | ID | Status | Descricao | |
| |-----|----|--------|-----------| |
| | Browser | `browser` | Funcional | Web browser com Playwright | |
| | Terminal | `terminal` | Funcional | Terminal session via launcher | |
| | Inbox | `inbox` | Placeholder | Task inbox com comments | |
| | Mission Control | `mission-control` | Placeholder | Kanban board de tarefas | |
| | Agents | `agents` | Placeholder | Org chart de agentes | |
| | Finder | `finder` | Placeholder | File browser de workspaces | |
| | Settings | `settings` | Placeholder | Configuracoes do sistema | |
|
|
| ### Interface de um App |
| ```typescript |
| interface AppRegistryEntry { |
| id: string; // ID unico |
| name: string; // Nome exibido |
| icon: string; // Icone do dock |
| description: string; // Descricao |
| component: React.LazyExoticComponent; // Componente React |
| defaultSize: { width, height }; |
| minSize?: { width, height }; |
| allowMultiple?: boolean; // Multiplas instancias |
| dockPinned?: boolean; // Fixado no dock |
| } |
| ``` |
|
|
| ## Agent Registry (A IMPLEMENTAR) |
|
|
| Sistema de registro de agentes especializados. Cada agente e um slot plugavel: |
|
|
| ```typescript |
| interface AgentSlot { |
| id: string; // "coder", "sql", "text", "frontend" |
| name: string; // "Coding Agent" |
| description: string; // "Especializado em..." |
| provider: "anthropic" | "openai" | "openrouter" | "huggingface" | "local"; |
| config: { |
| model: string; // "claude-opus-4-6" ou "agent-os-1b5" |
| endpoint?: string; // URL do endpoint (local ou API) |
| apiKey?: string; // Chave da API |
| temperature?: number; |
| maxTokens?: number; |
| }; |
| capabilities: string[]; // ["code", "sql", "text", "reasoning"] |
| active: boolean; // Ativado/desativado |
| } |
| ``` |
|
|
| ### Agentes Planejados |
|
|
| | Slot | Modelo | Provider | Funcao | |
| |------|--------|----------|--------| |
| | **Gestor/Orquestrador** | Llama 3.3 70B | HF Inference API (gratis Pro) | Roteia tarefas, classifica intencao, coordena agentes | |
| | **Coding** | Claude Opus 4.6 | Anthropic API | Escreve/refatora codigo | |
| | **SQL/Data** | agent-os-1b5 (custom) | Local llama-server | Queries SQL, Supabase, information_schema | |
| | **Frontend** | (a definir) | (a definir) | UI/UX, componentes React | |
| | **Texto** | (a definir) | (a definir) | Criacao de conteudo, copywriting | |
| | **Pesquisa** | (a definir) | (a definir) | Web search, analise de dados | |
| |
| ### Fluxo de Orquestracao |
| |
| ``` |
| 1. Usuario digita mensagem no chat |
| 2. Gestor (Llama 70B) analisa a intencao: |
| - "escreve uma funcao que..." → routing: coder |
| - "quantas vms ativas..." → routing: sql |
| - "cria um texto sobre..." → routing: text |
| 3. Gestor envia pra o agente especializado |
| 4. Agente processa e retorna resultado |
| 5. Gestor formata e entrega ao usuario |
| 6. Memoria Central registra a interacao |
| ``` |
| |
| ### Troca de Agentes |
| O usuario pode a qualquer momento: |
| - Trocar o modelo de um slot (ex: mudar coder de Opus pra GPT-4) |
| - Adicionar novo slot |
| - Desativar um slot |
| - Escolher manualmente qual agente usar |
| |
| ## Memoria Central: Basic Memory |
| |
| ### O que e |
| Sistema de memoria persistente baseado em Markdown + SQLite + Vector Embeddings. Opera como MCP Server. |
| |
| ### Arquitetura |
| ``` |
| ┌──────────────────────────────────────┐ |
| │ Markdown Files │ |
| │ - YAML frontmatter (metadata) │ |
| │ - [category] observations │ |
| │ - [[wiki-links]] relations │ |
| ├──────────────────────────────────────┤ |
| │ SQLite Index │ |
| │ - Full-text search │ |
| │ - Vector embeddings (FastEmbed) │ |
| │ - Hybrid search │ |
| ├──────────────────────────────────────┤ |
| │ MCP Server │ |
| │ - memory:// URLs │ |
| │ - CRUD de notas │ |
| │ - Navegacao semantica │ |
| │ - Context building │ |
| └──────────────────────────────────────┘ |
| ``` |
| |
| ### Uso no Agent OS |
| - **Contexto entre sessoes**: Agentes mantem conhecimento entre conversas |
| - **Knowledge graph**: Relacoes entre entidades (projetos, decisoes, aprendizados) |
| - **Multi-agente**: Todos os agentes leem/escrevem na mesma memoria |
| - **Orquestrador documenta**: O gestor registra cada interacao e decisao |
| - **Humano edita**: Usuario pode editar arquivos Markdown diretamente |
| |
| ### Claude Session Logger |
| Complementa o Basic Memory registrando automaticamente: |
| - Sessoes de conversa com Claude |
| - Ferramentas utilizadas |
| - Decisoes tomadas |
| - Erros e solucoes |
| |
| ## Modelos Treinados (Custom) |
| |
| ### agent-os-adapter-1.5b |
| - **Base**: Qwen 2.5 1.5B Instruct |
| - **Treino**: LoRA (r=32, alpha=64), 7 epochs, 415 exemplos x4 |
| - **Funcao**: Converter linguagem natural → JSON (SQL, CLI, shell) |
| - **Deploy**: GGUF Q8 no llama-server (CPU, 1.6GB RAM, ~3s/query) |
| - **Repos**: |
| - Adapter: `devsomosahub/agent-os-adapter-1.5b` |
| - Merged: `devsomosahub/agent-os-1b5-merged` |
| |
| ### agent-os-adapter-7b |
| - **Base**: Qwen 2.5 7B Instruct |
| - **Treino**: LoRA Q4, mesma config |
| - **Funcao**: Mesma, mas mais preciso |
| - **Repos**: |
| - Adapter: `devsomosahub/agent-os-adapter-7b` |
| - Merged: `devsomosahub/agent-os-7b-merged` |
| |
| ### Limitacao conhecida |
| Modelos custom inventam nomes de colunas baseados no dataset de treino quando fazem queries diretas. Solucao: fluxo de 2 passos (information_schema primeiro, depois query com colunas reais). |
|
|
| ## APIs Externas Utilizadas |
|
|
| | Servico | Uso | Autenticacao | |
| |---------|-----|-------------| |
| | HuggingFace (Pro) | Inference API gratis (Llama 70B), treinamento, endpoints | Token HF | |
| | Anthropic | Claude Opus 4.6 para coding agent | API Key | |
| | OpenRouter | LLMs alternativos, fallback | API Key | |
| | Vultr | Servidores (VMs dos boards, server Agent OS) | API Key | |
| | Supabase | Banco de dados dos projetos (Cloud-Hub, Hubia) | Access Token | |
| | GitHub | Repos, issues, PRs | gh CLI token | |
|
|
| ## Portas do Server (207.246.65.100) |
|
|
| | Porta | Servico | Acesso | |
| |-------|---------|--------| |
| | 3000 | Agent OS (frontend + API) | Publico | |
| | 3002 | Claude Launcher Web | Interno | |
| | 8080 | llama-server (modelo 1.5B) | Interno | |
| | 8082 | SmolAgent daemon | Interno | |
| | 9090 | Agent bot | Interno | |
|
|
| ## Proximos Passos |
|
|
| 1. **Implementar Agent Registry** - Config JSON de agentes plugaveis |
| 2. **Implementar Orquestrador** - Gestor que roteia entre agentes |
| 3. **Integrar Basic Memory** - MCP Server como memoria central |
| 4. **Integrar Session Logger** - Log automatico de sessoes |
| 5. **Implementar apps Placeholder** - Inbox, Mission Control, Agents, Finder, Settings |
| 6. **Modelo guia/assistente** - Treinar modelo que explica o sistema ao usuario |
| 7. **Dashboard de agentes** - UI para ver/trocar/configurar agentes em tempo real |
|
|
