Schema de Definição de Workflow

O objeto workflow_definition passado para Create from Definition e Update Agent define o grafo de conversa completo. É a mesma estrutura que o construtor visual de workflows do painel lê e escreve — construir um agente na UI produz um workflow_definition nos bastidores, e qualquer coisa que você puder configurar visualmente pode igualmente ser expressa aqui como JSON.

{
  "nodes": [...],
  "edges": [...]
}

Nós

Cada nó representa uma etapa da conversa.

{
  "id": "uuid-string",
  "type": "agentNode",
  "position": { "x": 100, "y": 200 },
  "data": { ... }
}

Campo	Tipo	Descrição
`id`	string	ID único do nó (UUID recomendado)
`type`	string	Um dos tipos de nó abaixo
`position`	object	Coordenadas visuais no construtor de workflows
`data`	object	Configuração do nó — os campos variam por tipo

Tipos de nó

Tipo	Descrição
`startCall`	Ponto de entrada para chamadas telefônicas
`endCall`	Encerra a chamada
`agentNode`	Etapa de conversa com tecnologia de LLM
`globalNode`	Configuração global aplicada a todos os nós de agente
`trigger`	Ponto de entrada para execuções disparadas por API (não telefônicas)
`webhook`	Envia uma requisição HTTP quando alcançado
`qa`	Executa análise de qualidade na chamada concluída

Campos de dados do nó

Campos comuns (todos os tipos de nó)

Campo	Tipo	Padrão	Descrição
`name`	string	obrigatório	Nome de exibição do nó
`prompt`	string	obrigatório*	Prompt de sistema do LLM. *Não obrigatório para nós `trigger`, `webhook`, `qa`
`allow_interrupt`	boolean	`false`	Permitir que o chamador interrompa o agente no meio da fala
`wait_for_user_response`	boolean	`false`	Pausar e aguardar a entrada do chamador antes de continuar
`wait_for_user_response_timeout`	number	`null`	Segundos para aguardar a entrada antes do timeout
`delayed_start`	boolean	`false`	Atrasar a execução deste nó
`delayed_start_duration`	number	`null`	Atraso em segundos
`add_global_prompt`	boolean	`true`	Mesclar o prompt do `globalNode` no prompt deste nó

agentNode — extração de dados

Campo	Tipo	Padrão	Descrição
`extraction_enabled`	boolean	`false`	Extrair dados estruturados da conversa
`extraction_prompt`	string	`null`	Prompt personalizado para orientar a extração
`extraction_variables`	array	`[]`	Variáveis a extrair (veja abaixo)

Schema da variável de extração:

{
  "name": "customer_intent",
  "type": "string",
  "prompt": "What did the customer want to achieve?"
}

type é um dos string, number ou boolean.

agentNode — ferramentas

Campo	Tipo	Descrição
`tool_uuids`	string[]	IDs das ferramentas (HTTP API, transferência de chamada etc.) a anexar a este nó
`document_uuids`	string[]	IDs dos documentos da base de conhecimento disponíveis para este nó

nó trigger

Campo	Tipo	Descrição

nó webhook

Campo	Tipo	Padrão	Descrição
`enabled`	boolean	`true`	Se este webhook dispara quando alcançado
`http_method`	string	—	`GET`, `POST`, `PUT`, `PATCH` ou `DELETE`
`endpoint_url`	string	—	URL de destino
`credential_uuid`	string	`null`	UUID de uma credencial de autenticação armazenada
`custom_headers`	array	`[]`	Cabeçalhos de requisição adicionais `[{"key": "...", "value": "..."}]`
`payload_template`	object	`null`	Template do corpo da requisição (suporta variáveis de contexto)

nó qa

Campo	Tipo	Padrão	Descrição
`qa_enabled`	boolean	`true`	Ativar análise de QA
`qa_system_prompt`	string	`null`	Prompt de avaliação personalizado
`qa_model`	string	`null`	Modelo de LLM a usar para avaliação
`qa_min_call_duration`	integer	`15`	Duração mínima da chamada em segundos para executar QA
`qa_voicemail_calls`	boolean	`false`	Incluir chamadas de caixa postal no QA
`qa_sample_rate`	integer	`100`	Porcentagem de chamadas a analisar (1–100)

Arestas

Cada aresta conecta dois nós e define quando a transição dispara.

{
  "id": "edge-uuid",
  "source": "node-uuid-a",
  "target": "node-uuid-b",
  "data": {
    "label": "Customer confirms",
    "condition": "The customer has confirmed their appointment",
    "transition_speech": "Great, I've got that noted."
  }
}

Campo	Tipo	Descrição
`id`	string	ID único da aresta
`source`	string	ID do nó de origem
`target`	string	ID do nó de destino
`data.label`	string	Rótulo curto mostrado no construtor de workflows
`data.condition`	string	Condição em linguagem natural que o LLM avalia para disparar esta aresta
`data.transition_speech`	string	Fala opcional que o agente diz antes de fazer a transição

Regras de validação

Todos os IDs de source e target nas arestas devem referenciar IDs de nós existentes
Todos os nós, exceto trigger, webhook e qa, devem ter um prompt não vazio
Os IDs dos nós devem ser únicos dentro do workflow
Cada workflow deve ter exatamente um nó startCall ou trigger como ponto de entrada

Exemplo mínimo

{
  "nodes": [
    {
      "id": "start-1",
      "type": "startCall",
      "position": { "x": 0, "y": 0 },
      "data": {
        "name": "Start",
        "prompt": "You are a friendly assistant. Greet the caller and ask how you can help."
      }
    },
    {
      "id": "end-1",
      "type": "endCall",
      "position": { "x": 400, "y": 0 },
      "data": {
        "name": "End",
        "prompt": "Thank the caller and say goodbye."
      }
    }
  ],
  "edges": [
    {
      "id": "edge-1",
      "source": "start-1",
      "target": "end-1",
      "data": {
        "label": "Done",
        "condition": "The caller's question has been answered and they want to end the call"
      }
    }
  ]
}

​Nós

​Tipos de nó

​Campos de dados do nó

​Campos comuns (todos os tipos de nó)

​agentNode — extração de dados

​agentNode — ferramentas

​nó trigger

​nó webhook

​nó qa

​Arestas

​Regras de validação

​Exemplo mínimo

Nós