Guia de Conexão & Especificação Técnica
Documentação completa para conectar agentes autônomos ao back4agents via Model Context Protocol (MCP) e REST v1.
1. Autenticação & Chaves de API
O back4agents utiliza chaves de API com prefixo b4a_ geradas no Console Web. O segredo é exibido apenas uma vez no momento da criação e armazenado de forma segura com hash.
2. Conexão MCP (Model Context Protocol)
Suportamos dois transportes para compatibilidade máxima com ecossistemas de agentes:
A. Streamable HTTP (Recomendado / Moderno)
Ponto de extremidade único stateful com suporte a streaming de chunks e header Mcp-Session-Id.
POST /api/mcpB. SSE Dual Transport (Legado)
Conexão Server-Sent Events com endpoint dedicado de mensagens para clientes compatíveis com a especificação original.
3. Catálogo de 13 Ferramentas MCP
Collections & Documents
create_collection: Cria coleção isolada.list_collections: Listagem paginada de coleções com contagem.insert_document: Inserção de documento JSON único (≤100KB).insert_documents_bulk: Inserção atômica de até 100 docs (soma ≤1MB).query_collection: Busca documentos com filtros e cursor.delete_document: Remove documento por ID.
Canvases & Versões
create_canvas: Inicia canvas (markdown, code, react).update_canvas: Atualiza conteúdo gerando nova versão.get_canvas: Consulta versão atual ou histórica.
Dashboards & Widgets (Layout Atômico)
create_dashboard: Novo dashboard com grade de 12 colunas.add_widget_to_dashboard: Insere widget e faz append atômico no layout.delete_widget: Remove widget e efetua prune no layoutConfig.update_dashboard_layout: Atualiza coordenadas completas da grade.
4. Real-Time Domain Events (SSE)
O frontend console e integrações externas podem assinar eventos em tempo real via:
Suporta cabeçalho Last-Event-ID para replay de eventos perdidos em desconexões temporárias e heartbeat a cada 25s.