{"id":"repo/agent-architecture","source":"repo","sourceLabel":"repository root","sourcePath":"AGENT_ARCHITECTURE.md","routePath":"/fastapp/public-docs/page/repo/agent-architecture","rawPath":"/fastapp/public-docs/raw/repo/agent-architecture","slug":["repo","agent-architecture"],"slugPath":"repo/agent-architecture","title":"🤖 FastApp Agent — Arquitetura e Guia Técnico","description":"Visão: O FastApp Agent não é apenas um chatbot. É uma camada de inteligência que lê, entende e modifica a própria estrutura de um app em tempo real — com parsing de linguagem natural, execução de APIs e feedback visual imediato.","headings":["🤖 FastApp Agent — Arquitetura e Guia Técnico","1. Os Dois Agentes Atuais","2. Arquitetura Geral","3. Contexto: O que o Agente Recebe","3.1 System Prompt (composto dinamicamente)","3.2 Escopos de Contexto (scopedContext)","4. Formatos de Output do LLM","4.1 AGENT DELTA (Schema Mutations)","AGENT DELTA","4.2 DATA ACTION (Execução de APIs)","4.3 SUGGESTION (Próximos Passos)","5. Parser: Como Funciona o parseDeltaBlocks()","Limpeza de JSON (cleanJson)","6. Merging Engine (useFastappArchitect)","Schema Sanitizer (validateAndSanitizeSchema)","7. Agent Presets System","8. Input Multimodal","Voz (Whisper STT)","Imagem (Vision)","9. Fluxo Completo de uma Interação","10. O que Funciona Bem Hoje","10.1 Estado Atual da Inteligencia AI","11. Gaps Atuais e Melhorias Propostas","🔴 Crítico"],"wordCount":1639,"markdown":"# 🤖 FastApp Agent — Arquitetura e Guia Técnico\r\n\r\n> **Visão:** O FastApp Agent não é apenas um chatbot. É uma camada de inteligência que lê, entende e modifica a própria estrutura de um app em tempo real — com parsing de linguagem natural, execução de APIs e feedback visual imediato.\r\n\r\n---\r\n\r\n## 1. Os Dois Agentes Atuais\r\n\r\n| Agente | Arquivo | Propósito |\r\n|--------|---------|-----------|\r\n| **AI Architect (entrypoint)** | `pages/fastapp/agent.vue` | Entrada especializada que redireciona para o runtime unificado em modo `architect` |\r\n| **Agent Playground (runtime unificado)** | `pages/fastapp/agent-playground.vue` | Ambiente completo: presets, scopes, live data, delta parsing, execução de ações |\r\n| **Frontend AI Copilot** | `components/ai/copilot/FrontendAICopilotSidebar.vue` | Copilot global da UI (modo `client`) desacoplado do runtime de arquitetura/playground |\r\n\r\nO **Playground é a evolução** — é nele que o roteamento de agentes, os formatos de delta e a execução de APIs estão implementados de forma mais robusta.\r\n\r\n---\r\n\r\n## 2. Arquitetura Geral\r\n\r\n```\r\n┌─────────────────────────────────────────┐\r\n│           AGENT PLAYGROUND              │\r\n│                                         │\r\n│  ┌──────────┐   ┌────────────────────┐  │\r\n│  │ Presets  │   │   Scope Selector   │  │\r\n│  │ Architect│   │  App/Módulo/Objeto │  │\r\n│  │ DataAsst │   │    /Propriedade    │  │\r\n│  └────┬─────┘   └────────┬───────────┘  │\r\n│       │                  │              │\r\n│       ▼                  ▼              │\r\n│  ┌─────────────────────────────────┐    │\r\n│  │        System Prompt Builder   │    │\r\n│  │  systemPrompt + deltaFormat    │    │\r\n│  │  + contextJson (scoped schema) │    │\r\n│  │  + liveData (se ativo)         │    │\r\n│  └────────────────┬────────────────┘    │\r\n│                   │                     │\r\n│                   ▼                     │\r\n│         POST /api/fastapp-agent         │\r\n│                   │                     │\r\n│                   ▼                     │\r\n│  ┌────────────────────────────────┐     │\r\n│  │      Delta Parser              │     │\r\n│  │  parseDeltaBlocks() →          │     │\r\n│  │  text | delta cards            │     │\r\n│  └────────────────┬───────────────┘     │\r\n│                   │                     │\r\n│         ┌─────────┴──────────┐          │\r\n│         ▼                    ▼          │\r\n│   Render Markdown      DeltaCard UI     │\r\n│   (marked + shiki)     + Botão Executar │\r\n│                              │          │\r\n│                   ┌──────────┘          │\r\n│                   ▼                     │\r\n│         executeDataAction() →           │\r\n│         /api/v1/data/{object}           │\r\n└─────────────────────────────────────────┘\r\n```\r\n\r\n---\r\n\r\n## 3. Contexto: O que o Agente Recebe\r\n\r\n### 3.1 System Prompt (composto dinamicamente)\r\n\r\n```\r\n[System Prompt do Preset]\r\n--- FORMAT ---\r\n[Delta Format Prompt]\r\n--- SCHEMA DO APP ---\r\n```json\r\n{ scopedContext } // JSON do escopo selecionado\r\n```\r\n--- LIVE DATA (se ativo) ---\r\n```json\r\n[ { registros ao vivo } ]\r\n```\r\n--- APIS DISPONÍVEIS ---\r\n- GET /api/v1/data/{object}\r\n- POST /api/v1/data/{object}\r\n- PATCH /api/v1/data/{object}/{id}\r\n- DELETE /api/v1/data/{object}/{id}\r\n```\r\n\r\n### 3.2 Escopos de Contexto (`scopedContext`)\r\n\r\nO Playground tem 4 escopos configuráveis que determinam **o que o agente vê**:\r\n\r\n| Escopo | O que envia para o LLM |\r\n|--------|------------------------|\r\n| `app` | Manifesto completo do app (objetos, módulos, páginas) |\r\n| `module` | Módulo + seus objetos resolvidos |\r\n| `object` | Schema JSON de um único objeto (propriedades, relações, ações) |\r\n| `property` | Definição de uma única propriedade |\r\n\r\n> 💡 **Regra de ouro:** sempre use o menor escopo possível. Enviar o schema de um único objeto é muito mais eficiente do que todo o app.\r\n\r\n---\r\n\r\n## 4. Formatos de Output do LLM\r\n\r\nO agente aceita **dois formatos** de resposta:\r\n\r\n### 4.1 AGENT_DELTA (Schema Mutations)\r\n\r\nUsado pelo agente **Architect** para alterar a estrutura do app:\r\n\r\n```\r\n### AGENT_DELTA\r\n```json\r\n{\r\n  \"action\": \"ADD_OBJECT\",\r\n  \"name\": \"ativo\",\r\n  \"label\": \"Ativo Financeiro\",\r\n  \"properties\": [\r\n    { \"name\": \"codigo\", \"type\": \"string\", \"required\": true },\r\n    { \"name\": \"valor\", \"type\": \"number\", \"content_type\": \"currency\" }\r\n  ]\r\n}\r\n```\r\n```\r\n\r\n**Actions disponíveis:**\r\n\r\n| Action | O que faz |\r\n|--------|-----------|\r\n| `ADD_OBJECT` | Cria ou atualiza um objeto no draft |\r\n| `ADD_PROPERTY` | Adiciona/atualiza uma propriedade em um objeto |\r\n| `ADD_MODULE` | Cria ou atualiza um módulo |\r\n| `ADD_RELATION` | Adiciona uma relação entre objetos |\r\n| `ADD_ACTION` | Adiciona uma ação customizada a um objeto |\r\n| `ADD_PAGE` | Adiciona uma página ao app |\r\n| `DELETE` | Marca um objeto/módulo para remoção |\r\n\r\n### 4.2 DATA_ACTION (Execução de APIs)\r\n\r\nUsado pelo agente **Assistente de Dados** para operar em registros reais:\r\n\r\n```json\r\n{\r\n  \"action\": \"DATA_ACTION\",\r\n  \"method\": \"GET\",\r\n  \"object_name\": \"lead\",\r\n  \"endpoint\": \"/api/v1/data/lead\",\r\n  \"payload\": {}\r\n}\r\n```\r\n\r\n```json\r\n{\r\n  \"action\": \"INSIGHT\",\r\n  \"category\": \"anomalia | padrao | oportunidade | alerta\",\r\n  \"label\": \"Título\",\r\n  \"description\": \"Análise baseada nos dados\",\r\n  \"affected_records\": [1, 2, 3],\r\n  \"recommended_action\": \"O que fazer\"\r\n}\r\n```\r\n\r\n### 4.3 SUGGESTION (Próximos Passos)\r\n\r\nQualquer agente pode emitir sugestões no formato:\r\n```\r\n[SUGGESTION: Texto da sugestão]\r\n```\r\nSão coletadas e renderizadas como bloco de navegação ao fim da resposta.\r\n\r\n---\r\n\r\n## 5. Parser: Como Funciona o `parseDeltaBlocks()`\r\n\r\nO parser é um **state machine** que processa a resposta raw do LLM:\r\n\r\n```\r\nRaw LLM Response\r\n     │\r\n     ├── Tokeniza por regex: ```json {...} ```\r\n     │\r\n     ├── Para cada bloco JSON:\r\n     │     ├── tryParseJson() → tem campo \"action\"?\r\n     │     │     ├── SIM → DeltaCard (renderizado como card interativo)\r\n     │     │     └── NÃO → Bloco de código normal (renderizado por shiki)\r\n     │\r\n     ├── Para texto plano entre blocos:\r\n     │     └── flush() → busca markers AGENT_DELTA legados\r\n     │           └── Brace-counter para isolar JSON\r\n     │\r\n     └── SUGGESTION extractor → bloco de sugestões\r\n```\r\n\r\n### Limpeza de JSON (`cleanJson`)\r\n\r\nO LLM frequentemente gera JSON \"sujo\" com:\r\n- Comentários inline (`// isso é um campo`)\r\n- Trailing commas (`{ \"a\": 1, }`)\r\n\r\nO `cleanJson()` remove ambos antes de fazer `JSON.parse()`.\r\n\r\n---\r\n\r\n## 6. Merging Engine (`useFastappArchitect`)\r\n\r\nO draft de schema funciona em **camada de sessão sobre a base persistida**:\r\n\r\n```\r\nBase (banco de dados)          Session (memória local)\r\n┌────────────────────┐    +    ┌────────────────────┐\r\n│ objects: [...]     │         │ sessionObjects: [...] │\r\n│ modules: [...]     │         │ sessionModules: [...] │\r\n│ pages:   [...]     │         │ sessionPages:   [...] │\r\n└────────────────────┘         └────────────────────┘\r\n              │                          │\r\n              └──────────────────────────┘\r\n                           │\r\n                    mergedApp (computed)\r\n                           │\r\n               (session tem prioridade)\r\n```\r\n\r\n**Flags de merge:**\r\n- `_is_new`: objeto criado na sessão, não existe na base\r\n- `_is_modified`: objeto modificado na sessão\r\n- `_deleted`: marcado para deleção\r\n- `_full_properties_override`: substitui lista inteira em vez de fazer merge\r\n\r\n### Schema Sanitizer (`validateAndSanitizeSchema`)\r\n\r\nAntes de aceitar qualquer JSON do LLM, o sanitizer:\r\n1. Resolve `name` de múltiplos aliases (`name`, `key`, `entity_name`, `object_name`)\r\n2. Injeta defaults de Ontologia v3 (`semantic`, `topology`, `engine`, `provider`)\r\n3. Filtra propriedades inválidas (nome igual ao objeto, `name`, `key`)\r\n4. Normaliza tipos de relação (`inner_collection` → `has_many`)\r\n5. Auto-deriva `foreign_key` se não fornecida\r\n\r\n---\r\n\r\n## 7. Agent Presets System\r\n\r\nO Playground define um sistema de **presets de agente** salvos no `localStorage`:\r\n\r\n```typescript\r\ninterface AgentPreset {\r\n  id: string;\r\n  name: string;\r\n  systemPrompt: string;        // Personalidade e regras do agente\r\n  deltaFormatPrompt: string;   // Como o agente deve estruturar outputs\r\n  analysisPrompt: string;      // Para análise de imagens (Vision)\r\n  model: string;               // 'gpt-4o', 'gpt-4o-mini', etc.\r\n  temperature: number;         // 0 = determinístico, 1 = criativo\r\n  liveDataMode?: boolean;      // Se deve buscar dados reais automaticamente\r\n}\r\n```\r\n\r\n**Built-in presets:**\r\n- **Architect**: Foco em schema, usa AGENT_DELTA, temperature 0.2\r\n- **Assistente de Dados**: Foco em dados, usa DATA_ACTION, ativa liveDataMode\r\n\r\n**Presets customizados** são salvos no localStorage e persistem entre sessões.\r\n\r\n---\r\n\r\n## 8. Input Multimodal\r\n\r\n### Voz (Whisper STT)\r\n1. `startRecording()` → `MediaRecorder` captura áudio do microfone\r\n2. `AudioContext + AnalyserNode` → waveform visualizer em tempo real\r\n3. `stopRecording()` → Blob enviado para `POST /api/transcribe`\r\n4. Transcrição populada no input (se estava vazio, dispara `sendMessage()` automaticamente)\r\n\r\n### Imagem (Vision)\r\n1. Upload de imagem → base64 armazenado em `uploadedImage`\r\n2. Enviado junto com o prompt para o LLM como conteúdo multimodal\r\n3. `analysisPrompt` do preset define o comportamento de análise visual\r\n\r\n---\r\n\r\n## 9. Fluxo Completo de uma Interação\r\n\r\n```\r\n1. Usuário digita/fala → userInput\r\n2. sendMessage():\r\n   a. Monta system prompt (preset + delta format + schema + live data)\r\n   b. POST /api/fastapp-agent com chat_history + new_prompt\r\n   c. SSE streaming → tokens aparecem em tempo real no chat\r\n3. Resposta recebida → parseDeltaBlocks():\r\n   a. Texto → renderizado com marked() + shiki syntax highlighting\r\n   b. DeltaCards → cards interativos com botão \"Executar\"\r\n4. Usuário clica \"Executar\" em um DeltaCard:\r\n   a. AGENT_DELTA → applyDelta() → mergedApp atualizado no canvas\r\n   b. DATA_ACTION → executeDataAction() → chamada real para /api/v1/data/{object}\r\n5. Se DATA_ACTION retorna sucesso:\r\n   a. Mensagem automática para o LLM notificando sucesso\r\n   b. liveData atualizado em background\r\n```\r\n\r\n---\r\n\r\n## 10. O que Funciona Bem Hoje\r\n\r\n✅ **Parser robusto** — suporta markdown, código, AGENT_DELTA legado e `action` em JSON puro  \r\n✅ **Merging não-destrutivo** — sessão sobre base, nunca perde dados  \r\n✅ **Schema sanitizer** — agente pode enviar aliases variados, sistema normaliza  \r\n✅ **Presets salvos** — agentes customizados persistem no browser  \r\n✅ **Scoped context** — token budget controlado, agente recebe só o necessário  \r\n✅ **Data Agent vivo** — executa CRUD real em qualquer objeto do app  \r\n✅ **Voz integrada** — Whisper STT com feedback visual de áudio  \r\n✅ **Vision** — análise de imagens para modelagem de schema  \r\n\r\n---\r\n\r\n## 10.1 Estado Atual da Inteligencia AI\r\n\r\nImplementado em 2026-04-16:\r\n\r\n1. **Prompt server-managed**: o frontend envia apenas um hint curto; `/api/fastapp-agent` monta o prompt completo com contexto, regras, ferramentas e politica de escrita.\r\n2. **Compiled generic app context**: `server/utils/agents/compiled-context.ts` compila qualquer manifesto em objetos, aliases, propriedades, relacoes, acoes, rotas e campos de lookup.\r\n3. **Context ranking**: o backend prioriza os objetos mais relevantes para o prompt e para o escopo ativo antes de enviar contexto ao modelo.\r\n4. **Native tool loop**: o agente executa ferramentas estruturadas do catalogo por tool calling, incluindo UI, schema, dados, RBAC, automacao e agentes por objeto.\r\n5. **Write policy seguro**: mutacoes backend usam preview/dry-run por padrao e exigem confirmacao explicita para execucao real.\r\n6. **Token optimization**: planner e verifier agora sao condicionais; requests simples evitam chamadas auxiliares quando nao agregam valor.\r\n7. **Generic app/data handling**: o playground e a automacao usam rotas app-scoped e inferencia semantica de campos, sem depender de nomes hardcoded de apps ou objetos.\r\n8. **Frontend table/filter sync**: `ui_apply_filters` aplica filtros, busca e ordenacao na rota/query da tabela ativa; no playground, leituras continuam retornando a lista filtrada no chat.\r\n9. **Generic data intelligence tools**: `aggregate_records`, `profile_object_data` e `suggest_filters` calculam metricas, agrupamentos, perfis de campos e candidatos de filtro para qualquer objeto.\r\n10. **Dynamic view capability context**: o CRUD dinamico publica capacidades genericas da tela ativa (`canFilter`, `canSort`, `canSearch`, `canCreate`, `canUpdate`), campos ativos, campos de metrica, datas, relacoes e query atual.\r\n11. **Agent routing resiliente**: `/api/fastapp-agent` cai para `fastapp-generic-app-operator` quando um `agent_id` salvo no browser nao existe no app ativo; o Copilot tambem escopa o execution agent salvo por app para evitar vazamento entre apps.\r\n\r\nArquivos principais:\r\n\r\n- `server/api/fastapp-agent.post.ts`\r\n- `server/utils/agents/compiled-context.ts`\r\n- `server/utils/agents/data-intelligence-tools.ts`\r\n- `server/utils/agents/record-automation-tools.ts`\r\n- `app/components/fastapp/FastappAgentChat.vue`\r\n- `app/composables/useFastappAgent.ts`\r\n- `app/pages/fastapp/agent-playground.vue`\r\n- `app/utils/fastapp-agent-orchestration.ts`\r\n\r\n---\r\n\r\n## 11. Gaps Atuais e Melhorias Propostas\r\n\r\n### 🔴 Crítico\r\n\r\n| Gap | Impacto | Solução Proposta |\r\n|----|---------|-----------------|\r\n| **Memória persistente ainda limitada** | O backend comprime histórico e aceita `conversation_memory`, mas não persiste memória longa por app/usuário | Persistir resumos e preferências por app, usuário e agente |\r\n| **Delta legado ainda existe** | O fluxo moderno usa tools, mas o playground ainda precisa suportar AGENT_DELTA para compatibilidade | Migrar gradualmente cards legados para previews/tool calls estruturados |\r\n| **Validação schema ainda parcial** | Algumas mutações passam por sanitizer, mas nem toda regra de `PropSchema` é validada antes do commit | Validator server-side completo antes de aplicar schema/data mutations |\r\n\r\n### 🟡 Importante\r\n\r\n| Gap | Solução Proposta |\r\n|----|-----------------|\r\n| **RAG vetorial ainda não implementado** | Indexar objetos/props no pgvector quando o compiled context não for suficiente |\r\n| **Sem streaming de DeltaCards** | DeltaCards aparecem só no fim da resposta — mostrar incrementalmente |\r\n| **Presets no localStorage** | Migrar para banco para persistir entre devices |\r\n| **Result cards estruturados parciais** | Listagens ja tem apresentacao melhor no chat, mas aggregates/profiles ainda dependem mais da resposta textual do modelo |\r\n| **Confirmação visual de writes** | O backend ja gera dry-run/approval; falta UI dedicada para revisar e confirmar previews |\r\n\r\n### 🟢 Futuro\r\n\r\n| Feature | Descrição |\r\n|---------|-----------|\r\n| **Tool: `apply_migration`** | Agente propõe e executa migrations de banco via Prisma |\r\n| **Tool: `create_dashboard`** | Agente cria widgets de BI a partir de uma pergunta |\r\n| **Agentes autônomos** | Multi-step planning: agente decompõe tarefa em subtasks, executa em paralelo |\r\n\r\n---\r\n\r\n## 12. Plano de Evolução (Roadmap)\r\n\r\n### Fase 1 — Foundation (próximas semanas)\r\n- [x] **Migrar para Tool Use**: catalogo + executor + tool loop em `/api/fastapp-agent`\r\n- [x] **Context Compression**: resumo compacto de historico e prompt server-managed\r\n- [x] **Write Preview Policy**: dry-run para writes backend sem confirmacao explicita\r\n- [x] **Frontend Filter Sync**: filtros/ordenacao do agente aplicam na tabela generica via `ui_apply_filters`\r\n- [x] **Generic Data Intelligence Tools**: agregacao, perfil de dados e sugestao de filtros para qualquer objeto\r\n- [x] **Dynamic View Capability Context**: CRUD dinamico informa capacidades e campos da tela ativa ao agente\r\n- [x] **Embed Mode inicial**: Frontend AI Copilot usa o chat em modo `client`\r\n- [ ] **Persistent Context**: persistir memoria comprimida entre sessoes/devices\r\n- [ ] **Delta Validator**: validacao completa contra tipos do schema antes de commit\r\n\r\n### Fase 2 — RAG & Context Intelligence (trimestre)  \r\n- [x] **Compiled Schema Context**: ranking generico de objetos/propriedades/relacoes/acoes\r\n- [ ] **Schema Embeddings**: indexar objetos/props no pgvector\r\n- [ ] **Semantic Search**: agente busca contexto relevante ao invés de enviar tudo\r\n- [ ] **Cross-app Context**: agente pode consultar schemas de múltiplos apps\r\n\r\n### Fase 3 — Autonomous Agents (semestre)\r\n- [x] **Planner Agent inicial**: planner condicional para tarefas complexas/architect\r\n- [x] **Executor Loop**: executa ferramentas genericas de schema, data, UI e RBAC\r\n- [x] **Approval Flow backend**: writes viram preview/dry-run sem confirmacao explicita\r\n- [ ] **Executor Agents especializados**: Schema Agent, Data Agent, UI Agent independentes\r\n- [ ] **Agent Orchestrator paralelo**: coordena multiplos agentes em paralelo\r\n\r\n### Fase 4 — Universal Scope\r\n- [ ] **Agent por App**: cada app configura seus próprios agentes com regras de negócio\r\n- [ ] **Agent API**: `POST /api/{app}/agent` para integrar agentes via webhook externo\r\n- [ ] **Trigger-based Agents**: agentes ativados por eventos (novo registro, mudança de status)\r\n\r\n---\r\n\r\n## 13. Aplicando em Qualquer App\r\n\r\nPara usar o agente em um app específico:\r\n\r\n```typescript\r\n// 1. Selecionar o app\r\nawait selectAppContext(appId);\r\n\r\n// 2. Definir escopo focado\r\nscopeType.value = 'object';\r\nscopeTargetKey.value = 'ativo';  // Nome do objeto\r\n\r\n// 3. Aplicar preset adequado\r\napplyAgent(BUILT_IN_AGENTS.find(a => a.id === 'data-assistant'));\r\n\r\n// 4. O agente automaticamente:\r\n//    - Recebe o schema do objeto \"ativo\"\r\n//    - Lista as APIs disponíveis para esse objeto\r\n//    - Busca registros reais (liveDataMode)\r\n//    - Está pronto para consultas em linguagem natural\r\n```\r\n\r\n---\r\n\r\n## 14. APIs Backend\r\n\r\n| Endpoint | Método | Função |\r\n|----------|--------|--------|\r\n| `/api/fastapp-agent` | POST | Proxy LLM com SSE streaming |\r\n| `/api/v1/data/{object}` | GET/POST | CRUD genérico |\r\n| `/api/v1/data/{object}/{id}` | PATCH/DELETE | Operações por ID |\r\n| `/api/transcribe` | POST | Whisper STT (áudio → texto) |\r\n| `/api/app/{id}` | PATCH | Atualizar schema do app |\r\n| `/api/system/snapshot` | POST | Gerar static-manifest.ts |\r\n\r\n---\r\n\r\n> **Princípio Guia:** O agente é uma **interface de linguagem sobre o schema**. Qualquer coisa que um usuário possa configurar manualmente no Architect deve poder ser solicitada em linguagem natural ao agente — e executada com um clique de confirmação.\r\n"}