> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tigyai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Schema de Definição de Workflow

> Referência de schema para o objeto workflow_definition usado na API de Agents

O objeto `workflow_definition` passado para [Create from Definition](/pt/api-reference/agents/create-from-definition) e [Update Agent](/pt/api-reference/agents/update) 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.

```json theme={null}
{
  "nodes": [...],
  "edges": [...]
}
```

***

## Nós

Cada nó representa uma etapa da conversa.

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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.

```json theme={null}
{
  "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

```json theme={null}
{
  "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"
      }
    }
  ]
}
```