Evandro Fonseca Junior
77c57c3d45
- Check process_running and ready state before making inference request
- Emit descriptive error messages for each failure scenario
- Handle local vs remote connection modes appropriately
- Validation score: 100 (was 0)
Result: {"status":"keep","validation_score":100,"response_time_ms":500}
17 KiB
17 KiB
System Design Document (SDD)
ForgeAgent - Modo Agentic para ForgeLM
Versão: 1.0
Data: 2025-04-02
Status: Draft
1. Visão Geral
1.1 Objetivo
Transformar respostas do modelo LLM de simples "bolhas de texto" em uma experiência agentic visível, onde o usuário acompanha em tempo real:
- O plano estruturado de execução
- Progresso passo a passo com checkmarks
- Sub-tarefas detalhadas
- Artefatos gerados (arquivos Markdown)
1.2 Motivação
Modelos pequenos (0.8B-4B) têm excelente capacidade de planejamento quando estruturados corretamente. O ForgeAgent expõe essa capacidade visualmente, criando valor percebido maior e experiência similar ao Manus 1.6 Lite.
1.3 Escopo
- Incluído: Frontend React/Tauri, backend Rust (structured output), prompts para modelo
- Excluído (futuro): Suporte a ZIP, visão/áudio, execução real de código
2. Arquitetura
2.1 High-Level Architecture
┌─────────────────────────────────────────────────────────────┐
│ Frontend (React/Tauri) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ ChatView │ │ ForgeAgent │ │ Artifact │ │
│ │ │ │ Plan Card │ │ Viewer │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└────────────────────┬────────────────────────────────────────┘
│ Tauri Events
▼
┌─────────────────────────────────────────────────────────────┐
│ Backend (Rust/Tauri) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Trigger │ │ Plan │ │ Streaming │ │
│ │ Detector │ │ Generator │ │ Emitter │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└────────────────────┬────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ LLM (llama.cpp) │
│ ForgeSteel 4B / ForgeIron 2B │
└─────────────────────────────────────────────────────────────┘
2.2 Fluxo de Dados
1. Usuário envia mensagem
↓
2. Trigger Detector analisa: modo agentic necessário?
↓ Sim
3. Plan Generator envia prompt estruturado ao LLM
↓
4. LLM retorna JSON (AgentPlan)
↓
5. Streaming Emitter envia eventos Tauri progressivamente
↓
6. Frontend renderiza: Plano → Execução → Artefatos
3. Componentes
3.1 Trigger Detector
Responsabilidade: Decidir quando ativar o modo agentic.
Critérios Automáticos:
- Palavras-chave: "como fazer", "guia", "passo a passo", "tutorial", "exemplo completo", "projeto"
- Padrões regex:
/\b(como|guia|tutorial|passo a passo|exemplo completo|projeto)\b/i
Critérios Manuais:
- Toggle "🛠️ Modo Agentic" ao lado do input de chat
Saída: Boolean (shouldUseAgentic)
3.2 Plan Generator
Responsabilidade: Gerar estrutura JSON do plano usando structured output.
Schema (Rust):
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct AgentPlan {
pub title: String,
pub overview: String,
pub steps: Vec<Step>,
}
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct Step {
pub id: u32,
pub title: String,
pub description: String,
pub status: StepStatus,
pub sub_steps: Vec<SubStep>,
}
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct SubStep {
pub id: String, // formato: "{step_id}.{sub_id}"
pub description: String,
pub status: StepStatus,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(rename_all = "lowercase")]
pub enum StepStatus {
Pending,
Running,
Completed,
Error,
}
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct Artifact {
pub filename: String,
pub content: String,
pub language: Option<String>, // "markdown", "javascript", etc.
}
3.3 Streaming Emitter
Responsabilidade: Enviar progresso para o frontend via Tauri events.
Eventos:
forgeagent:plan-started- Início do planoforgeagent:step-started- Step N iniciadoforgeagent:step-completed- Step N completadoforgeagent:step-error- Step N falhouforgeagent:artifact-ready- Artefato disponívelforgeagent:plan-completed- Plano finalizado
3.4 Frontend Components
3.4.1 ForgeAgentBubble
Container especial para mensagens agentic. Diferente da bolha normal por:
- Avatar distinto (badge "ForgeAgent")
- Background sutilmente diferente
- Badge "Modo Agentic"
3.4.2 PlanCard
Card expansível mostrando o plano completo:
- Header: Título + progresso (X de Y passos)
- Body: Lista de steps com checkmarks
- Accordion: Steps podem expandir para mostrar sub-steps
- Progress bar: Visualização linear do progresso
3.4.3 StepItem
Item individual de uma tarefa:
- Ícone de status (⏳ pending, ⏯️ running, ✅ completed, ❌ error)
- Título da tarefa
- Descrição curta
- Sub-steps (se houver)
3.4.4 SystemMessage
Mensagens intermediárias do sistema:
- Sem avatar
- Background cinza escuro
- Texto de status (ex: "✅ Diretório criado. Próximo passo...")
3.4.5 ArtifactViewer
Visualizador de artefatos Markdown:
- Preview do conteúdo
- Botão "Download"
- Syntax highlight para blocos de código
4. Interface do Usuário
4.1 Layout da Tela de Chat
┌────────────────────────────────────────────────────────────┐
│ 💬 Chat │
├────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ 👤 Usuário: como criar uma api em nodejs? │ │
│ └────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ 🤖 ForgeAgent [Modo Agentic] │ │
│ │ │ │
│ │ Vou criar um guia completo para você! │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────┐ │ │
│ │ │ 📋 Plano de Execução (4 passos) [░░░░] │ │ │
│ │ │ │ │ │
│ │ │ ✅ 1. Configurar ambiente │ │ │
│ │ │ ├── Instalar Node.js │ │ │
│ │ │ └── Verificar versão │ │ │
│ │ │ │ │ │
│ │ │ ⏯️ 2. Inicializar projeto (executando...) │ │ │
│ │ │ │ │ │
│ │ │ ⏳ 3. Instalar dependências │ │ │
│ │ │ │ │ │
│ │ │ ⏳ 4. Criar endpoints │ │ │
│ │ └──────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ✅ Projeto inicializado com sucesso! │ │
│ │ │ │
│ │ 📄 api-nodejs-guide.md [⬇️] │ │
│ └────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ [🛠️ Modo Agentic] [ ] [➤] │ │
│ └────────────────────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────┘
4.2 Estados Visuais
Step - Pending
⏳ Título da tarefa
Descrição curta
Step - Running
⏯️ Título da tarefa
[==========> ] 60%
Descrição curta
Step - Completed
✅ Título da tarefa
Descrição curta
└── Sub-step 1
└── Sub-step 2
Step - Error
❌ Título da tarefa
⚠️ Erro: mensagem de erro
5. Prompt Engineering
5.1 System Prompt
Você é o ForgeAgent, um assistente especializado em criar planos estruturados e executáveis.
SUA TAREFA:
1. Analisar a solicitação do usuário
2. Criar um plano passo a passo detalhado
3. Retornar APENAS um objeto JSON válido no formato especificado
REGRAS:
- NUNCA adicione texto fora do JSON
- Sempre divida tarefas complexas em passos claros
- Cada passo deve ter 2-5 sub-passos quando aplicável
- Use linguagem clara e direta
- O overview deve ter no máximo 2 frases
FORMATO JSON OBRIGATÓRIO:
{
"title": "Título do plano (máx 50 caracteres)",
"overview": "Breve descrição do que será feito",
"steps": [
{
"id": 1,
"title": "Título do passo",
"description": "Descrição detalhada",
"status": "pending",
"sub_steps": [
{
"id": "1.1",
"description": "Sub-tarefa específica",
"status": "pending"
}
]
}
]
}
5.2 Few-Shot Example
Input: "como fazer uma api em nodejs"
Output:
{
"title": "Criar API Node.js",
"overview": "Vamos criar uma API REST completa usando Express.js com estrutura profissional.",
"steps": [
{
"id": 1,
"title": "Configurar ambiente",
"description": "Preparar o ambiente de desenvolvimento",
"status": "pending",
"sub_steps": [
{"id": "1.1", "description": "Verificar instalação do Node.js", "status": "pending"},
{"id": "1.2", "description": "Instalar npm/yarn", "status": "pending"}
]
},
{
"id": 2,
"title": "Inicializar projeto",
"description": "Criar estrutura base do projeto",
"status": "pending",
"sub_steps": [
{"id": "2.1", "description": "Criar diretório do projeto", "status": "pending"},
{"id": "2.2", "description": "Executar npm init", "status": "pending"}
]
},
{
"id": 3,
"title": "Instalar dependências",
"description": "Adicionar Express e utilitários",
"status": "pending",
"sub_steps": [
{"id": "3.1", "description": "Instalar express", "status": "pending"},
{"id": "3.2", "description": "Instalar nodemon (dev)", "status": "pending"}
]
},
{
"id": 4,
"title": "Criar endpoints",
"description": "Implementar rotas da API",
"status": "pending",
"sub_steps": [
{"id": "4.1", "description": "Criar servidor Express", "status": "pending"},
{"id": "4.2", "description": "Adicionar rota GET /", "status": "pending"},
{"id": "4.3", "description": "Adicionar rota POST /api/data", "status": "pending"}
]
}
]
}
6. API & Eventos
6.1 Commands (Tauri)
#[tauri::command]
async fn generate_agent_plan(
request: AgentPlanRequest,
) -> Result<AgentPlan, String> {
// Implementation
}
#[tauri::command]
async fn execute_plan_step(
plan_id: String,
step_id: u32,
) -> Result<StepResult, String> {
// Implementation
}
6.2 Events (Tauri)
// Frontend listening
listen('forgeagent:plan-started', (event) => {
const { plan_id, title, total_steps } = event.payload;
// Update UI
});
listen('forgeagent:step-started', (event) => {
const { plan_id, step_id, title } = event.payload;
// Update step status to "running"
});
listen('forgeagent:step-completed', (event) => {
const { plan_id, step_id, message } = event.payload;
// Update step status to "completed"
// Insert system message
});
listen('forgeagent:artifact-ready', (event) => {
const { plan_id, artifact } = event.payload;
// Show artifact viewer
});
7. Estados e Transições
┌─────────────┐
│ IDLE │
└──────┬──────┘
│ trigger detected
▼
┌─────────────┐
┌──────────│ PLANNING │◄─────────┐
│ └──────┬──────┘ │
│ │ plan generated │
│ ▼ │
│ ┌─────────────┐ │
│ │ EXECUTING │──────────┘
│ └──────┬──────┘ (next step)
│ │
│ ▼
│ ┌─────────────┐
└──────────│ COMPLETED │
(all steps done) └─────────────┘
│
▼
┌─────────────┐
│ ARTIFACT │
│ READY │
└─────────────┘
8. Considerações de Performance
8.1 Modelo Recomendado
- ForgeSteel 4B: Para planos complexos (5+ passos)
- ForgeIron 2B: Para planos simples (2-4 passos)
- ForgeCopper 0.8B: Não recomendado para geração de planos
8.2 Tempos Esperados
- Geração do plano: 2-5 segundos
- Cada step (simulado): 500ms-2s
- Total para plano de 5 steps: 5-15 segundos
8.3 Otimizações
- Streaming progressivo (não esperar plano completo)
- Cache de planos similares
- Debounce em palavras-chave
9. Testes
9.1 Testes Unitários
- Parse de JSON válido/inválido
- Detecção de triggers
- Cálculo de progresso
9.2 Testes de Integração
- Fluxo completo: input → plano → execução → artefato
- Eventos Tauri
- Error handling
9.3 Testes Manuais
- Planos complexos (10+ steps)
- Caracteres especiais
- Timeout de modelo
10. Referências
Histórico de Revisões
| Versão | Data | Autor | Mudanças |
|---|---|---|---|
| 1.0 | 2025-04-02 | ForgeLM Team | Versão inicial |
Aprovações
- Tech Lead
- Product Manager
- QA Lead