flowral.docs
Início/Agentes & IA

Flowral Agents — painel de chat e agentes

Decisão aprovada: Rust + Slint como UI. Fluxo ACP primeiro, com integração explícita ao OpenCode V2 ou superior. O painel é aplicativo separado, aberto sob demanda, mas compartilha crates e temas com a Central de Controle.

Não confundir versões

  • OpenCode V2+ = versões suportadas do programa OpenCode. Integração/configuração com sintaxe atual de V2.
  • ACP = protocolo entre cliente Flowral e agente de código. O Rust SDK oferece ACP v1 estável e v2 experimental. A versão do ACP será negociada por capabilities, não automaticamente igual a V2 do OpenCode.
  • MCP = protocolo agente→servidor de ferramentas. Gerenciar MCP não significa que Flowral executará diretamente ferramentas sem usuário/agent.

Arquitetura

flowral-agents (Slint UI)
  ↕ models: session, prompt, messages, permission_requests, tool_calls, diffs
flowral-acp (Rust, SDK oficial + child process)
  ↕ JSON-RPC stdio/transport negociado
opencode acp   |   outro agente ACP verificado
  ↕ provider configurado e MCPs autorizados
modelos / ferramentas / arquivos do workspace

OpenCode também possui APIs próprias; usar adapter OpenCode V2 quando um recurso específico não está disponível no ACP. Não depender de scraping da TUI ou comportamento indefinido.

Fluxos

  1. Abrir workspace/projeto, escolher agent executável detectado e profile de provider, criar sessão.
  2. Negociar capabilities, context roots, workspace, limites e permissões.
  3. Enviar prompt, apresentar streaming, status do agente, chamadas a ferramentas e orçamento quando disponível.
  4. Mostrar alterações de arquivos/diffs com indicação de risco, antes de aplicar quando o agente/protocolo permitir.
  5. Confirmar ferramentas com efeitos (executar shell, gravar arquivo, remover diretório, network, MCP).
  6. Persistir histórico e metadados locais, sem copiar tokens de autenticação para logs.
  7. Encerrar subprocesso com protocolo de shutdown, liberar handles e detectar órfãos.

Telas

  • Welcome: projetos recentes, agentes instalados, provider/modelo ativo.
  • Chat: mensagens e Markdown com alta legibilidade, blocos de código, anexos suportados pelo agente.
  • Tool activity: ação, argumento resumido, status, duração, permissão, cancel.
  • Changes: diff agrupado por arquivo, staged/unstaged e aprovação explícita.
  • Sessions: nomes, busca e restore somente quando suportado.
  • Settings: integrador de MCP e providers (abre a mesma tela do Control Center).
  • Diagnostics: handshake ACP, versões, compatibilidade e logs com redaction.

Múltiplos agentes

Somente após MVP: várias sessões lado a lado, coordenação explícita, não executar dois agentes escrevendo no mesmo workspace sem isolamento; considerar git worktrees por sessão. Nunca executar prompts em paralelo sem escolha do usuário.

Provider management

Tela embutida ou reuso do módulo da Central; custom OpenAI-compatible endpoint e variantes, API key / auth, metadados de custo, test de conexão e seleção por projeto. Respeitar providers.

Critérios de aceite

  • Cliente ACP real consegue conversar com opencode acp V2+ usando SDK Rust e negociar versão suportada.
  • UI lida com cancelamento, reconexão/falhas e mensagens de progresso.
  • Prompts e arquivos são autorizados no escopo do projeto; nunca vazar chave em crash dump.
  • Agent encerrado não deixa processos ativos indevidos.
  • Medição do sistema em repouso considera painel fechado; não exigir serviço HTTP permanentemente aberto.
  • Não alegar compatibilidade ACP com Claude Code/Codex/Hermes/etc sem teste específico do adapter ou proxy.

Fontes