AGENT_ARCHITECTURE.md

🤖 FastApp Agent — Arquitetura e Guia Técnico

Voltar ao índiceMarkdown rawllms.txt

Public Markdown Document

🤖 FastApp Agent — Arquitetura e Guia Técnico

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.

1639 palavras24 headingsrepository root

🤖 FastApp Agent — Arquitetura e Guia Técnico

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.

1. Os Dois Agentes Atuais

Agente Arquivo Propósito
AI Architect (entrypoint) pages/fastapp/agent.vue Entrada especializada que redireciona para o runtime unificado em modo architect
Agent Playground (runtime unificado) pages/fastapp/agent-playground.vue Ambiente completo: presets, scopes, live data, delta parsing, execução de ações
Frontend AI Copilot components/ai/copilot/FrontendAICopilotSidebar.vue Copilot global da UI (modo client) desacoplado do runtime de arquitetura/playground

O 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.

2. Arquitetura Geral

┌─────────────────────────────────────────┐
│           AGENT PLAYGROUND              │
│                                         │
│  ┌──────────┐   ┌────────────────────┐  │
│  │ Presets  │   │   Scope Selector   │  │
│  │ Architect│   │  App/Módulo/Objeto │  │
│  │ DataAsst │   │    /Propriedade    │  │
│  └────┬─────┘   └────────┬───────────┘  │
│       │                  │              │
│       ▼                  ▼              │
│  ┌─────────────────────────────────┐    │
│  │        System Prompt Builder   │    │
│  │  systemPrompt + deltaFormat    │    │
│  │  + contextJson (scoped schema) │    │
│  │  + liveData (se ativo)         │    │
│  └────────────────┬────────────────┘    │
│                   │                     │
│                   ▼                     │
│         POST /api/fastapp-agent         │
│                   │                     │
│                   ▼                     │
│  ┌────────────────────────────────┐     │
│  │      Delta Parser              │     │
│  │  parseDeltaBlocks() →          │     │
│  │  text | delta cards            │     │
│  └────────────────┬───────────────┘     │
│                   │                     │
│         ┌─────────┴──────────┐          │
│         ▼                    ▼          │
│   Render Markdown      DeltaCard UI     │
│   (marked + shiki)     + Botão Executar │
│                              │          │
│                   ┌──────────┘          │
│                   ▼                     │
│         executeDataAction() →           │
│         /api/v1/data/{object}           │
└─────────────────────────────────────────┘

3. Contexto: O que o Agente Recebe

3.1 System Prompt (composto dinamicamente)

[System Prompt do Preset]
--- FORMAT ---
[Delta Format Prompt]
--- SCHEMA DO APP ---
```json
{ scopedContext } // JSON do escopo selecionado

--- LIVE DATA (se ativo) ---

[ { registros ao vivo } ]

--- APIS DISPONÍVEIS ---

  • GET /api/v1/data/{object}
  • POST /api/v1/data/{object}
  • PATCH /api/v1/data/{object}/{id}
  • DELETE /api/v1/data/{object}/{id}

### 3.2 Escopos de Contexto (`scopedContext`)

O Playground tem 4 escopos configuráveis que determinam **o que o agente vê**:

| Escopo | O que envia para o LLM |
|--------|------------------------|
| `app` | Manifesto completo do app (objetos, módulos, páginas) |
| `module` | Módulo + seus objetos resolvidos |
| `object` | Schema JSON de um único objeto (propriedades, relações, ações) |
| `property` | Definição de uma única propriedade |

> 💡 **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.

---

## 4. Formatos de Output do LLM

O agente aceita **dois formatos** de resposta:

### 4.1 AGENT_DELTA (Schema Mutations)

Usado pelo agente **Architect** para alterar a estrutura do app:

AGENT_DELTA

{
  "action": "ADD_OBJECT",
  "name": "ativo",
  "label": "Ativo Financeiro",
  "properties": [
    { "name": "codigo", "type": "string", "required": true },
    { "name": "valor", "type": "number", "content_type": "currency" }
  ]
}


**Actions disponíveis:**

| Action | O que faz |
|--------|-----------|
| `ADD_OBJECT` | Cria ou atualiza um objeto no draft |
| `ADD_PROPERTY` | Adiciona/atualiza uma propriedade em um objeto |
| `ADD_MODULE` | Cria ou atualiza um módulo |
| `ADD_RELATION` | Adiciona uma relação entre objetos |
| `ADD_ACTION` | Adiciona uma ação customizada a um objeto |
| `ADD_PAGE` | Adiciona uma página ao app |
| `DELETE` | Marca um objeto/módulo para remoção |

### 4.2 DATA_ACTION (Execução de APIs)

Usado pelo agente **Assistente de Dados** para operar em registros reais:

```json
{
  "action": "DATA_ACTION",
  "method": "GET",
  "object_name": "lead",
  "endpoint": "/api/v1/data/lead",
  "payload": {}
}

{
  "action": "INSIGHT",
  "category": "anomalia | padrao | oportunidade | alerta",
  "label": "Título",
  "description": "Análise baseada nos dados",
  "affected_records": [1, 2, 3],
  "recommended_action": "O que fazer"
}

4.3 SUGGESTION (Próximos Passos)

Qualquer agente pode emitir sugestões no formato:

[SUGGESTION: Texto da sugestão]

São coletadas e renderizadas como bloco de navegação ao fim da resposta.

5. Parser: Como Funciona o parseDeltaBlocks()

O parser é um state machine que processa a resposta raw do LLM:

Raw LLM Response
     │
     ├── Tokeniza por regex: ```json {...} ```
     │
     ├── Para cada bloco JSON:
     │     ├── tryParseJson() → tem campo "action"?
     │     │     ├── SIM → DeltaCard (renderizado como card interativo)
     │     │     └── NÃO → Bloco de código normal (renderizado por shiki)
     │
     ├── Para texto plano entre blocos:
     │     └── flush() → busca markers AGENT_DELTA legados
     │           └── Brace-counter para isolar JSON
     │
     └── SUGGESTION extractor → bloco de sugestões

Limpeza de JSON (cleanJson)

O LLM frequentemente gera JSON "sujo" com:

  • Comentários inline (// isso é um campo)
  • Trailing commas ({ "a": 1, })

O cleanJson() remove ambos antes de fazer JSON.parse().

6. Merging Engine (useFastappArchitect)

O draft de schema funciona em camada de sessão sobre a base persistida:

Base (banco de dados)          Session (memória local)
┌────────────────────┐    +    ┌────────────────────┐
│ objects: [...]     │         │ sessionObjects: [...] │
│ modules: [...]     │         │ sessionModules: [...] │
│ pages:   [...]     │         │ sessionPages:   [...] │
└────────────────────┘         └────────────────────┘
              │                          │
              └──────────────────────────┘
                           │
                    mergedApp (computed)
                           │
               (session tem prioridade)

Flags de merge:

  • _is_new: objeto criado na sessão, não existe na base
  • _is_modified: objeto modificado na sessão
  • _deleted: marcado para deleção
  • _full_properties_override: substitui lista inteira em vez de fazer merge

Schema Sanitizer (validateAndSanitizeSchema)

Antes de aceitar qualquer JSON do LLM, o sanitizer:

  1. Resolve name de múltiplos aliases (name, key, entity_name, object_name)
  2. Injeta defaults de Ontologia v3 (semantic, topology, engine, provider)
  3. Filtra propriedades inválidas (nome igual ao objeto, name, key)
  4. Normaliza tipos de relação (inner_collection → has_many)
  5. Auto-deriva foreign_key se não fornecida

7. Agent Presets System

O Playground define um sistema de presets de agente salvos no localStorage:

interface AgentPreset {
  id: string;
  name: string;
  systemPrompt: string;        // Personalidade e regras do agente
  deltaFormatPrompt: string;   // Como o agente deve estruturar outputs
  analysisPrompt: string;      // Para análise de imagens (Vision)
  model: string;               // 'gpt-4o', 'gpt-4o-mini', etc.
  temperature: number;         // 0 = determinístico, 1 = criativo
  liveDataMode?: boolean;      // Se deve buscar dados reais automaticamente
}

Built-in presets:

  • Architect: Foco em schema, usa AGENT_DELTA, temperature 0.2
  • Assistente de Dados: Foco em dados, usa DATA_ACTION, ativa liveDataMode

Presets customizados são salvos no localStorage e persistem entre sessões.

8. Input Multimodal

Voz (Whisper STT)

  1. startRecording() → MediaRecorder captura áudio do microfone
  2. AudioContext + AnalyserNode → waveform visualizer em tempo real
  3. stopRecording() → Blob enviado para POST /api/transcribe
  4. Transcrição populada no input (se estava vazio, dispara sendMessage() automaticamente)

Imagem (Vision)

  1. Upload de imagem → base64 armazenado em uploadedImage
  2. Enviado junto com o prompt para o LLM como conteúdo multimodal
  3. analysisPrompt do preset define o comportamento de análise visual

9. Fluxo Completo de uma Interação

1. Usuário digita/fala → userInput
2. sendMessage():
   a. Monta system prompt (preset + delta format + schema + live data)
   b. POST /api/fastapp-agent com chat_history + new_prompt
   c. SSE streaming → tokens aparecem em tempo real no chat
3. Resposta recebida → parseDeltaBlocks():
   a. Texto → renderizado com marked() + shiki syntax highlighting
   b. DeltaCards → cards interativos com botão "Executar"
4. Usuário clica "Executar" em um DeltaCard:
   a. AGENT_DELTA → applyDelta() → mergedApp atualizado no canvas
   b. DATA_ACTION → executeDataAction() → chamada real para /api/v1/data/{object}
5. Se DATA_ACTION retorna sucesso:
   a. Mensagem automática para o LLM notificando sucesso
   b. liveData atualizado em background

10. O que Funciona Bem Hoje

✅ Parser robusto — suporta markdown, código, AGENT_DELTA legado e action em JSON puro
✅ Merging não-destrutivo — sessão sobre base, nunca perde dados
✅ Schema sanitizer — agente pode enviar aliases variados, sistema normaliza
✅ Presets salvos — agentes customizados persistem no browser
✅ Scoped context — token budget controlado, agente recebe só o necessário
✅ Data Agent vivo — executa CRUD real em qualquer objeto do app
✅ Voz integrada — Whisper STT com feedback visual de áudio
✅ Vision — análise de imagens para modelagem de schema

10.1 Estado Atual da Inteligencia AI

Implementado em 2026-04-16:

  1. 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.
  2. Compiled generic app context: server/utils/agents/compiled-context.ts compila qualquer manifesto em objetos, aliases, propriedades, relacoes, acoes, rotas e campos de lookup.
  3. Context ranking: o backend prioriza os objetos mais relevantes para o prompt e para o escopo ativo antes de enviar contexto ao modelo.
  4. Native tool loop: o agente executa ferramentas estruturadas do catalogo por tool calling, incluindo UI, schema, dados, RBAC, automacao e agentes por objeto.
  5. Write policy seguro: mutacoes backend usam preview/dry-run por padrao e exigem confirmacao explicita para execucao real.
  6. Token optimization: planner e verifier agora sao condicionais; requests simples evitam chamadas auxiliares quando nao agregam valor.
  7. 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.
  8. 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.
  9. 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.
  10. 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.
  11. 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.

Arquivos principais:

  • server/api/fastapp-agent.post.ts
  • server/utils/agents/compiled-context.ts
  • server/utils/agents/data-intelligence-tools.ts
  • server/utils/agents/record-automation-tools.ts
  • app/components/fastapp/FastappAgentChat.vue
  • app/composables/useFastappAgent.ts
  • app/pages/fastapp/agent-playground.vue
  • app/utils/fastapp-agent-orchestration.ts

11. Gaps Atuais e Melhorias Propostas

🔴 Crítico

Gap Impacto Solução Proposta
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
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
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

🟡 Importante

Gap Solução Proposta
RAG vetorial ainda não implementado Indexar objetos/props no pgvector quando o compiled context não for suficiente
Sem streaming de DeltaCards DeltaCards aparecem só no fim da resposta — mostrar incrementalmente
Presets no localStorage Migrar para banco para persistir entre devices
Result cards estruturados parciais Listagens ja tem apresentacao melhor no chat, mas aggregates/profiles ainda dependem mais da resposta textual do modelo
Confirmação visual de writes O backend ja gera dry-run/approval; falta UI dedicada para revisar e confirmar previews

🟢 Futuro

Feature Descrição
Tool: apply_migration Agente propõe e executa migrations de banco via Prisma
Tool: create_dashboard Agente cria widgets de BI a partir de uma pergunta
Agentes autônomos Multi-step planning: agente decompõe tarefa em subtasks, executa em paralelo

12. Plano de Evolução (Roadmap)

Fase 1 — Foundation (próximas semanas)

  • Migrar para Tool Use: catalogo + executor + tool loop em /api/fastapp-agent
  • Context Compression: resumo compacto de historico e prompt server-managed
  • Write Preview Policy: dry-run para writes backend sem confirmacao explicita
  • Frontend Filter Sync: filtros/ordenacao do agente aplicam na tabela generica via ui_apply_filters
  • Generic Data Intelligence Tools: agregacao, perfil de dados e sugestao de filtros para qualquer objeto
  • Dynamic View Capability Context: CRUD dinamico informa capacidades e campos da tela ativa ao agente
  • Embed Mode inicial: Frontend AI Copilot usa o chat em modo client
  • Persistent Context: persistir memoria comprimida entre sessoes/devices
  • Delta Validator: validacao completa contra tipos do schema antes de commit

Fase 2 — RAG & Context Intelligence (trimestre)

  • Compiled Schema Context: ranking generico de objetos/propriedades/relacoes/acoes
  • Schema Embeddings: indexar objetos/props no pgvector
  • Semantic Search: agente busca contexto relevante ao invés de enviar tudo
  • Cross-app Context: agente pode consultar schemas de múltiplos apps

Fase 3 — Autonomous Agents (semestre)

  • Planner Agent inicial: planner condicional para tarefas complexas/architect
  • Executor Loop: executa ferramentas genericas de schema, data, UI e RBAC
  • Approval Flow backend: writes viram preview/dry-run sem confirmacao explicita
  • Executor Agents especializados: Schema Agent, Data Agent, UI Agent independentes
  • Agent Orchestrator paralelo: coordena multiplos agentes em paralelo

Fase 4 — Universal Scope

  • Agent por App: cada app configura seus próprios agentes com regras de negócio
  • Agent API: POST /api/{app}/agent para integrar agentes via webhook externo
  • Trigger-based Agents: agentes ativados por eventos (novo registro, mudança de status)

13. Aplicando em Qualquer App

Para usar o agente em um app específico:

// 1. Selecionar o app
await selectAppContext(appId);

// 2. Definir escopo focado
scopeType.value = 'object';
scopeTargetKey.value = 'ativo';  // Nome do objeto

// 3. Aplicar preset adequado
applyAgent(BUILT_IN_AGENTS.find(a => a.id === 'data-assistant'));

// 4. O agente automaticamente:
//    - Recebe o schema do objeto "ativo"
//    - Lista as APIs disponíveis para esse objeto
//    - Busca registros reais (liveDataMode)
//    - Está pronto para consultas em linguagem natural

14. APIs Backend

Endpoint Método Função
/api/fastapp-agent POST Proxy LLM com SSE streaming
/api/v1/data/{object} GET/POST CRUD genérico
/api/v1/data/{object}/{id} PATCH/DELETE Operações por ID
/api/transcribe POST Whisper STT (áudio → texto)
/api/app/{id} PATCH Atualizar schema do app
/api/system/snapshot POST Gerar static-manifest.ts

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.