Conversa com o assistente que monta e corrige fluxos. Você descreve o que quer; o assistente adiciona nós, liga as saídas e valida o fluxo, enviando cada passo em tempo real.
Conectar
wss://SUA_URL_BASE/ws/workflows/{id}/ai-builder?ticket=SEU_TICKET
wss://SUA_URL_BASE/ws/workflows/ai-builder?ticket=SEU_TICKET- Com
id: edita um fluxo existente. Permissãoworkflows:update. - Sem
id: cria um fluxo novo, começando vazio e do tipomessages. Permissãoworkflows:create.
Limites
| Limite | Valor | Ao atingir |
|---|---|---|
| Sessões simultâneas por workspace | 3 | error e a conexão é encerrada. |
| Tempo por pedido | 10 minutos | done com o motivo em summary; a conexão continua aberta. |
| Tokens por sessão | 1.000.000 | done; novos pedidos na mesma conexão recebem o mesmo done. |
| Saldo | precisa ter saldo | done com valid: false e o motivo em summary. |
O uso do assistente é cobrado do saldo do workspace.
Mensagens que você envia
Formato: {"type": "...", "data": {...}}.
| type | data | O que faz |
|---|---|---|
user_prompt | {"text": string, "graph"?: Graph} | Pede uma alteração. Se graph vier, ele substitui o fluxo atual antes do pedido. Pedidos enviados durante outro pedido entram na fila. |
set_workflow_type | {"type": "messages" | "voice"} | Troca o tipo do fluxo. Responde com graph_snapshot. |
set_model | {"model": string, "reasoning"?: string} | Escolhe o modelo de IA dos próximos pedidos e, opcionalmente, o nível de raciocínio: um dos reasoning.levels do modelo em GET /agents/options. Sem reasoning, vale o padrão do modelo. O assistente precisa de ferramentas, então o modelo é conferido no catálogo na escolha e antes de cada pedido: sem uso de ferramentas confirmado, com um nível que ele não oferece ou com o catálogo ilegível, nada vai ao provedor e a resposta é done com valid: false, o motivo em summary e o código em code. |
hydrate_graph | {"graph": Graph} | Substitui o fluxo (por exemplo, depois de edições manuais) e responde com graph_snapshot. |
cancel | sem data | Interrompe o pedido em andamento, que termina com done e summary: "cancelado". |
Mensagens que você recebe
Formato: {"type": "...", "payload": {...}}.
| type | payload | Quando |
|---|---|---|
builder_ready | {"workflowType": "messages" | "voice", "nodeCount": number, "mode": "create" | "edit", "model": string} | Logo após conectar. |
graph_snapshot | {"graph": Graph, "issues": LintIssue[], "valid": boolean} | Após conectar, após trocar o tipo ou o fluxo, e a cada passo do assistente. |
iteration | {"n": number, "max": number, "tokensUsed": number, "tokenBudget": number} | Início de cada passo do assistente. |
reasoning_delta | {"text": string} | Trecho do raciocínio do assistente. |
reasoning_done | sem payload | Fim do raciocínio do passo. |
assistant_delta | {"text": string} | Trecho da resposta do assistente. |
assistant_done | {"tools": number} | Fim da resposta; tools é o número de ações do passo. |
assistant_retry | {"attempt": number, "of": number, "text"?: string, "reasoning"?: string} | A conexão com o provedor de IA caiu e o mesmo passo vai ser repetido, sem refazer as ações já feitas. Apague do fim da resposta o text e do fim do raciocínio o reasoning que esse passo já tinha enviado. |
tool | {"name": string, "summary": string, "ok": boolean} | Cada ação no fluxo. ok: false traz o motivo em summary. |
resource_resolved | {"kind": string, "query": string, "matches": [{"id": string, "name": string}]} | O assistente buscou um recurso do workspace (agentes, mídias, filas, troncos...). |
meta | {"name": string, "description": string, "workflowType": string} | O assistente definiu nome, descrição ou tipo do fluxo. |
idle | {"valid": boolean} | O assistente respondeu sem alterar o fluxo e espera o próximo pedido. |
done | {"valid": boolean, "summary": string, "code"?: string, "residualIssues"?: LintIssue[]} | O pedido terminou: o fluxo foi validado, um limite foi atingido, foi cancelado ou houve erro do provedor de IA. Quando o modelo é recusado, code traz model_without_tools, model_catalog_unavailable ou reasoning_level_unsupported. |
error | {"error": string} | Não foi possível abrir a sessão (limite de sessões, fluxo inexistente ou de outro workspace). A conexão é encerrada. |
Valores de tool.name: get_node_spec, find_resource, add_node, connect, update_node, remove_node, remove_edge, set_meta, declare_variable (declara ou ajusta um dado da conversa no catálogo do workspace, com as mesmas regras de PUT /conversation-variables/{name}), set_flow_variable, remove_flow_variable (Dados do fluxo em graph.variables) e finish. summary não repete o nome da ação e chama os dados da conversa pelo nome amigável.
Tipos usados nas mensagens
{
"Graph": {"nodes": ["Node"], "edges": ["Edge"], "variables": [{"name": "string", "default": "string (opcional)"}]},
"Node": {"id": "string", "type": "string", "position": {"x": 0, "y": 0}, "config": {}},
"Edge": {"source": "string", "target": "string", "label": "string (opcional)"},
"LintIssue": {
"code": "string",
"severity": "blocking | advisory",
"nodeId": "string (opcional)",
"field": "string (opcional)",
"edgeRef": "string (opcional)",
"message": "string",
"hint": "string (opcional)"
}
}Os tipos de nó e os campos de config são os de GET /workflows/node-types. Problemas blocking impedem ativar o fluxo; advisory são sugestões.
Autenticação
Abra a conexão com um ticket de tempo real no parâmetro ticket: peça um em POST /v1/realtime/tickets logo antes de conectar. O ticket vale 30 segundos e abre uma única conexão; a cada reconexão, peça outro. Clientes fora do navegador também podem enviar o cabeçalho Authorization: Bearer SEU_ACCESS_TOKEN. O token na URL (?token=) e o cookie accessToken não abrem WebSockets. Um ticket inválido, vencido ou já usado recusa a conexão com realtime_ticket_invalid.
Workspace
Com o ticket, o workspace e o departamento são os do pedido do ticket (cabeçalhos X-Workspace-ID e X-Department-ID): não é preciso repeti-los na URL, e um workspaceId, workspace_id ou departmentId diferente é recusado com workspace_mismatch ou department_mismatch. Com o cabeçalho Authorization, informe o workspace em X-Workspace-ID, como nas rotas HTTP.
Formato das mensagens
Cada quadro de texto carrega um único objeto JSON com o tipo da mensagem. Datas são strings RFC 3339. Antes de abrir o WebSocket, erros de autenticação, workspace e permissão voltam como HTTP comum (401, 400, 403, 429, 501).
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||