WebSocket do construtor de fluxos com IA (novo fluxo)

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ão workflows:update.
  • Sem id: cria um fluxo novo, começando vazio e do tipo messages. Permissão workflows:create.

Limites

LimiteValorAo atingir
Sessões simultâneas por workspace3error e a conexão é encerrada.
Tempo por pedido10 minutosdone com o motivo em summary; a conexão continua aberta.
Tokens por sessão1.000.000done; novos pedidos na mesma conexão recebem o mesmo done.
Saldoprecisa ter saldodone com valid: false e o motivo em summary.

O uso do assistente é cobrado do saldo do workspace.

Mensagens que você envia

Formato: {"type": "...", "data": {...}}.

typedataO 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.
cancelsem dataInterrompe o pedido em andamento, que termina com done e summary: "cancelado".

Mensagens que você recebe

Formato: {"type": "...", "payload": {...}}.

typepayloadQuando
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_donesem payloadFim 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).

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Query Params
string

Ticket de POST /v1/realtime/tickets (alternativa ao cabeçalho Authorization)

string

Workspace usado na checagem de permissão da conexão

Headers
string

Workspace da requisição. Sem ele vale o workspace padrão da pessoa; um workspace do qual ela não participa responde 403 workspace_not_member.

string

Departamento que limita os dados. Quem não participa do departamento recebe 403; donos e administradores escolhem qualquer um.

Responses

Language
Credentials
Header
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
*/*