Workflows
Um workflow é um mapa visual do que o seu agente deve fazer passo a passo — quem fala primeiro, o que perguntar, quando ramificar, quando transferir a chamada e quando passar a chamada para um agente diferente. Constrói-o numa tela largando nós e ligando-os.
Use um workflow quando um único prompt não chega — quando a chamada tem etapas claras ("primeiro qualificar, depois recolher detalhes, depois marcar ou transferir"), quando precisa de encaminhamento determinístico com base nas respostas do interlocutor (não "a IA normalmente faz o que está certo"), ou quando um agente deve passar uma fatia do trabalho a um especialista.
Um prompt é uma longa instrução. O agente lê-o uma vez e usa-o para toda a chamada. Um workflow são muitas instruções pequenas, uma por nó, com transições explícitas entre elas. O grafo conduz a chamada — o agente em cada nó só é dono da sua fatia.
Se o seu agente já funciona bem com um único prompt, não precisa de um workflow. Recorra aos workflows quando continua a adicionar regras "se X então Y" ao prompt e elas deixam de funcionar de forma fiável.
O Editor
O editor de workflows vive na sua própria aba na página do agente. Vê uma tela com um nó Start e um nó End por padrão. Adiciona nós a partir da barra de ferramentas, arrasta-os para a tela e liga-os com arestas.
O painel do lado direito muda à medida que seleciona coisas:
- Clique num nó — abre-se o seu painel de definições (prompt, campos, variáveis de recolha, etc.).
- Clique numa aresta — abrem-se as suas definições de gatilho (AI decides / Condition / Always).
- O painel Variables (botão da barra de ferramentas) lista cada variável que o workflow declara ou usa, com um salto de um clique para o nó que define ou lê cada uma.
Execute uma Test Call no browser diretamente do editor — um pirilampo luminoso segue a posição ao vivo para que possa ver exatamente que nó está ativo em cada momento.
Undo / Redo (v2.8) — o editor mantém um histórico de até 20 passos, para que possa recuar um movimento errado (ou refazê-lo) sem reconstruir. Eliminar um nó pede confirmação primeiro (v2.8), para que não perca um passo com um clique perdido.
Não tem de começar de uma tela em branco. O ponto de entrada "build as workflow" provisiona um workflow para o agente e leva-o diretamente para o construtor — uma ação cria o workflow e abre o editor, pronto a adicionar nós.
Os workflows têm três estados:
- Draft — editável, ainda não ativo. Use Test Call para o experimentar.
- Active — ativo para chamadas reais. O agente usa este workflow a partir da chamada seguinte.
- Template — um blueprint reutilizável, nunca ligado diretamente a um agente. Pode instanciá-lo em vários agentes.
Nós
Cada nó é um passo na conversa. Diferentes tipos de nó fazem coisas diferentes — alguns falam, alguns ouvem, alguns encaminham, alguns executam ferramentas.
Agent
O nó agent é o coração de uma etapa do workflow. Quando o grafo chega a um nó agent, esse agente toma a palavra e conduz a conversa até que algo acione uma transição.
Configura a persona e a tarefa do nó agent diretamente na tela (a aba Prompt abre quando clica no nó) — este é o prompt para essa fatia da conversa, não para a chamada inteira. Pode também anexar bases de conhecimento e ferramentas por nó.
Greeting — a linha de abertura. Se este é o nó de entrada (a primeira paragem depois de Start), é isto que o interlocutor ouve primeiro.
Quando um grafo governa uma chamada, o prompt do nó ativo é sobreposto ao prompt base do agente (o da aba Model). O grafo é dono da personalidade e da tarefa de cada etapa, enquanto as instruções base do agente permanecem como fundação.
Subagent
Um subagent é um ajudante que corre inline — assume a conversa para uma tarefa focada, depois devolve o resultado a quem o invocou.
Os subagents são ótimos quando uma peça de trabalho é reutilizável ou parece distinta: "verificar a identidade do interlocutor", "recolher uma morada de entrega", "qualificar uma lead com o método SPIN". O agente pai chama o subagent, o subagent faz o seu trabalho e reporta um resultado, o pai retoma de onde parou.
Os nós subagent têm as mesmas abas que um nó agent (Prompt, Knowledge, Tools, Actions) — o editor cria automaticamente um agente de suporte oculto por si. Não vê este agente oculto na sua lista principal de agentes, e ele não conta para o limite de agentes do seu plano.
Return variable — o slot onde armazenar o resultado do subagent (ex.: identity_verified, lead_score).
Quem fala primeiro
Por padrão, um subagent abre o seu turno a falar — cumprimenta ou faz a sua primeira pergunta no momento em que assume. Dois toggles alteram isso:
- Wait for the caller (don't speak first) — o subagent mantém-se em silêncio na entrada e só responde quando o interlocutor diz algo. Ative isto quando o subagent é a primeira paragem na chamada e quer que o interlocutor comece (um verdadeiro "Está?") em vez de o agente abrir — ou a meio da chamada, quando a etapa anterior já disse tudo e o subagent só deve ouvir a resposta.
- Silent step (don't speak) — o subagent nunca fala. Lê a conversa até ao momento, decide um resultado e devolve o controlo diretamente. Use-o como um router invisível: "leia o que o interlocutor pediu e decida a que departamento isto pertence" — sem palavras ditas, apenas uma decisão sobre a qual o grafo ramifica.
Valores de resultado permitidos
Um subagent normalmente termina com o valor que julgou apropriado. Se vai ramificar sobre esse resultado com arestas Condition, fixe-o a uma lista fechada de valores permitidos:
- Liste cada valor permitido em Allowed result values (ex.:
sales,support,billing). - O subagent tem de terminar com exatamente um deles — não pode inventar um novo.
- Emparelhe cada valor com uma aresta Condition (
result is "sales"→ …) para um encaminhamento limpo e previsível.
Esta é a forma fiável de fazer um subagent decidir e encaminhar: o resultado tem garantidamente de corresponder a um dos seus ramos.
Um subagent devolve um único resultado quando termina. Ligue o que acontece a seguir com arestas Condition ou Always sobre esse resultado — a saída de um subagent não usa arestas "AI decides". É por isso que Allowed result values + arestas Condition é o padrão recomendado para um subagent de encaminhamento.
Message
O nó Message fala uma linha fixa, sem turno de IA, sem improvisação. Use-o para transições ("Um momento, estou a transferi-lo…"), avisos legalmente obrigatórios ou confirmações padronizadas onde a formulação importa.
Text — o que falar. Suporta tokens {{variable}} para injetar valores recolhidos, ex.: "Obrigado {{first_name}}, marquei-o para {{appointment_time}}."
Um nó Message consome o turno — o agente não acrescentará mais nada por cima.
Gather input
Um nó Gather input faz uma pergunta e capta a resposta do interlocutor numa variável.
Prompt — a pergunta a fazer. Suporta {{tokens}}.
Variable — o nome do slot onde armazenar a resposta.
Max silence (v2.8) — um limite por pergunta de quanto tempo esperar que o interlocutor responda antes de avançar. Defina-o por nó Gather-input, para que uma pergunta rápida de sim/não possa expirar mais cedo do que uma que pede ao interlocutor para ler um número de conta longo.
Use-o sempre que precisa de um valor específico antes de continuar — email, número de conta, número de pessoas, categoria do problema. O próximo turno do interlocutor torna-se o valor; pode ramificar sobre ele com uma aresta Condition logo a seguir.
Update state
Um nó Update state escreve um ou mais valores nas variáveis do workflow sem falar ou perguntar. Use-o para predefinir defaults, marcar flags de progresso ou preparar valores calculados a partir de passos anteriores.
Variable / Value — um par chave-valor. More variables (optional) — pares chave-valor adicionais.
Tanto as chaves como os valores suportam {{tokens}}, para que possa compor novos valores a partir de existentes.
Condition
O nó Condition é um nó exclusivamente de encaminhamento — não fala, não pergunta, apenas envia a chamada pelo ramo de saída que corresponder.
A condição em si vive em cada aresta de saída, não no nó — veja Arestas Condition abaixo.
Use um nó Condition quando quer um ponto claro de "fan-out" no seu grafo: muitos ramos que dependem do valor de uma variável. Comparado com colocar condições em arestas de nós agent, um nó Condition dedicado torna a lógica de encaminhamento visualmente óbvia.
Tool
O nó Tool executa uma das ferramentas ligadas do agente como um passo do grafo — sem dar à IA qualquer palavra sobre se a deve chamar. Use-o quando quer um facto, não uma conversa: "procurar este cliente", "verificar stock", "GET o tempo atual".
Pode:
- Escolher uma das ferramentas existentes do agente (consulta de calendário, pesquisa na base de conhecimento, uma ação específica de uma integração), ou
- Configurar uma chamada HTTP inline diretamente no nó (URL, método, headers, params, corpo).
A resposta da ferramenta fica disponível para todos os nós a jusante. Se a resposta for um objeto JSON, cada campo de topo torna-se a sua própria variável — por isso uma resposta como {"is_known": true, "tier": "gold"} escreve tanto is_known como tier para poder ramificar.
Cada campo de texto no nó Tool — URL, valores de header, corpo — suporta {{tokens}}. Puxe uma variável para um caminho de URL, um header ou um corpo de pedido sem escrever código.
Se uma chamada de ferramenta falhar (erro HTTP, timeout, rede), o nó regista a falha e o grafo continua — sem os dados. Planeie as suas condições a jusante para lidar com o caso de "sem valor".
Knowledge (RAG)
O nó Knowledge (RAG) é uma variante do Tool focada na recolha da base de conhecimento. Escolha uma das bases de conhecimento do agente, escreva uma query de pesquisa (com {{tokens}} se quiser), e o nó executa a consulta como um passo do grafo.
Use-o quando quer que o workflow procure algo antes de um nó Agent falar — ex.: buscar a encomenda mais recente do cliente para que o próximo nó Agent a possa mencionar sem ter de perguntar. O conteúdo recolhido aterra numa variável que pode puxar para prompts e mensagens.
Integration
O nó Integration é uma variante focada do Tool, para serviços externos ligados — Google Calendar, Outlook, HubSpot. Escolhe o fornecedor e a ação específica (ex.: check_availability, create_event), define os parâmetros, e o nó chama a integração de forma determinística.
Se a integração não estiver ligada neste agente, o nó passa sem fazer nada — o seu grafo continua. Verifique as condições a jusante para o caso "não correu".
Phone transfer
O nó Phone transfer faz uma transferência assistida da chamada para um número de telefone externo. Após uma transferência bem-sucedida, a chamada saiu do seu workflow — o seu agente já não está em linha.
Number — destino em formato internacional com um + inicial (ex.: +15551234567). Suporta {{tokens}} para que o destino possa vir de um passo anterior (ex.: a resposta a "a que escritório o devemos ligar?").
Se a transferência não se concretizar (número inválido, sem resposta, ligação telefónica não configurada), o grafo faz rollback e o agente atual mantém-se em linha. A conversa continua normalmente — o agente pode pedir desculpa e tentar um caminho diferente.
End call
O nó End call conclui — o agente fala a despedida configurada, depois desliga. Use-o como um terminal limpo para ramos de "tudo concluído" ou para o ramo "não podemos ajudar, desculpe" de uma Condition difícil de tratar.
Nenhuma configuração necessária além de ligar uma aresta a ele.
Reutilizar um Workflow (Sub-workflow)
Um nó Sub-workflow está reservado para incorporar outro workflow como um sub-grafo. Este nó está no editor mas ainda não está totalmente ligado — o grafo passa por ele sem fazer nada. Não dependa dele para chamadas em produção. Iremos ativá-lo assim que lançarmos sub-grafos reutilizáveis.
Arestas (Ligações)
Liga um nó ao seguinte com uma aresta. O gatilho da aresta decide quando a transição dispara.
Há três gatilhos:
| Gatilho | Quem decide | Quando dispara |
|---|---|---|
| AI decides | A IA | Quando a conversa o torna o próximo passo natural. A IA recebe uma "ferramenta de transição" que pode chamar. |
| Condition | O runtime | Quando uma variável corresponde a uma regra que escreve. Avaliado antes de a IA responder. |
| Always | O runtime | Incondicionalmente — no momento em que o nó de origem termina. Sem input do interlocutor, sem envolvimento da IA. |
AI decides (orientada por intenção)
Use AI decides quando só a IA consegue perceber quando mudar — "se o interlocutor pergunta sobre preços, transfira para o agente de vendas", "se soar a uma reclamação, execute o subagent de pedido de desculpas".
Escreve uma breve descrição de intenção na aresta (ex.: "O interlocutor pergunta sobre preços ou quer fazer upgrade"). A IA vê-a como uma ferramenta rotulada com essa intenção e decide se a chama com base na conversa. Se existirem várias arestas AI-decides, a IA escolhe no máximo uma por turno.
Condition (ramificação determinística)
Use Condition quando quer que o grafo — não a IA — decida com base num facto conhecido: "se lead_score is more than 7, envie para o closer; caso contrário, termine a chamada educadamente".
As condições avaliam antes de a IA responder, por isso vencem sempre a IA nesse turno. A IA não pode sobrepor-se a uma condição correspondente.
Pode construir uma condição a partir destes operadores:
| Operador | Significado | Exemplo |
|---|---|---|
| is | correspondência exata (não sensível a maiúsculas para texto) | intent is "billing" |
| is not | não corresponde | status is not "active" |
| contains | correspondência de substring (não sensível a maiúsculas) | feedback contains "broken" |
| is more than | > numérico | lead_score is more than 7 |
| is less than | < numérico | wait_minutes is less than 5 |
Pode também combinar cláusulas com All (todas as cláusulas têm de corresponder — AND) ou Any (pelo menos uma tem de corresponder — OR), e aninhá-las. Assim uma regra como "o interlocutor é conhecido e o seu nível é gold ou premium" torna-se:
All:
- is_known is true
- Any:
- tier is gold
- tier is premium
Se referenciar uma variável que ainda não foi definida (ex.: a IA nunca a recolheu), as condições sobre ela falham sempre — não dão erro, apenas não correspondem. Assim loyalty_tier is "gold" retorna false se loyalty_tier nunca foi definida. Desenhe os seus ramos para lidar com isto — normalmente com um ramo else (ver abaixo).
Ramo Else — quando nenhuma condição corresponde
Se tiver várias arestas Condition a sair de um nó e nenhuma corresponder, a chamada cai para a aresta não-Condition de prioridade mais baixa (Always, ou uma aresta AI-decides). Se não houver fallback nenhum, a IA recupera o controlo e pode continuar livremente.
Um padrão comum: várias Conditions para os caminhos bem conhecidos, mais uma aresta Always para um catch-all (Message algo, depois End call, ou transferir).
Always (auto-avanço)
Use Always quando o próximo passo é incondicional — sem decisão, sem input do interlocutor. Dois usos naturais:
- Encadear passos: Message → Update state → Message → Tool → Condition. Cada passo termina e a aresta Always avança de imediato.
- Auto-avançar depois de o agente terminar de falar: um nó agent com uma aresta de saída Always significa "assim que a IA parar de falar, avança" — sem necessidade de o interlocutor responder. Útil para fluxos em estilo monólogo, como um agente apresentador que apresenta e depois transita para a secção seguinte.
Condition e Always (os determinísticos) vencem sempre AI decides. Se uma Condition corresponder, as ferramentas de transição da IA são ignoradas nesse turno. É isto que lhe permite escrever regras que a IA não pode contornar.
Ordem dos ramos
Quando várias arestas saem do mesmo nó, o editor permite-lhe definir uma prioridade arrastando as linhas para cima ou para baixo. Os ramos de prioridade mais baixa são verificados primeiro. Isto só importa quando dois ramos poderiam ambos disparar no mesmo turno — normalmente duas arestas Condition com regras sobrepostas. O primeiro ramo que corresponder vence.
Transportar contexto — quanto o próximo agente recorda
Cada aresta tem uma definição Carry context que controla quanto da transcrição da conversa o próximo nó vê:
- Full transcript (padrão) — o próximo agente vê tudo o que foi dito até ao momento.
- Summary only — a plataforma resume a conversa anterior e entrega um breve resumo ao próximo agente.
- Nothing — o próximo agente começa do zero, sem transcrição anterior.
Use Summary only ao passar para um agente especialista que não precisa de cada palavra — poupa tokens e mantém o novo agente focado. Use Nothing para ramos onde a persona do novo agente é suposta ser separada (ex.: um inquérito de satisfação no fim da chamada).
Variáveis
As variáveis são a memória do workflow. A maioria das coisas num workflow tem a ver com definir uma variável ou ler uma.
Declarar variáveis
O painel Variables (botão da barra de ferramentas) mostra cada variável no workflow com os passos que definem ou leem cada uma. Clique numa variável para saltar para um setter; esta é a forma mais rápida de encontrar onde algo está a correr mal.
Pode declarar uma variável com um valor padrão no painel — útil para flags como escalated=false que precisam de existir desde o início para que as suas condições nunca falhem silenciosamente em "em falta".
Variáveis de chamada integradas
Algumas variáveis são preenchidas por si no início de cada chamada — não as declara nem define, estão simplesmente lá para ler:
| Variável | O que contém |
|---|---|
{{call_from}} | O número de telefone do interlocutor |
{{call_to}} | O número que foi marcado (o seu número) |
{{call_direction}} | inbound ou outbound |
Como existem desde o primeiro momento, pode ramificar sobre elas no primeiro nó — por exemplo, uma Condition sobre call_from para cumprimentar um VIP conhecido pelo nome, encaminhar por código de país, ou enviar números desconhecidos por um caminho de verificação antes de mais nada acontecer.
Como as variáveis são definidas
| Fonte | Exemplo |
|---|---|
| Valores padrão (declarados no painel Variables) | escalated = false definido antes de a chamada começar |
| Gather input | A resposta falada do interlocutor é captada na variável do nó |
| Update state | Escreve um valor (literal ou composto de {{tokens}}) diretamente |
| Resultado de Tool / Integration | A resposta inteira é armazenada com o nome do nó; se a resposta for um objeto JSON, cada campo de topo torna-se também a sua própria variável |
| Retorno de Subagent | O que quer que o subagent termine é armazenado na variável de retorno do nó subagent |
Ler variáveis — {{tokens}}
Em qualquer lugar onde possa escrever texto num nó — prompt do agente, texto de Message, prompt de Gather, URL / corpo / headers de Tool, número de Phone transfer, valor de Update state, valores de condição — pode inserir {{variable}} e será substituído em runtime.
Caminhos com pontos também funcionam para dados aninhados — ex.: se uma resposta de Tool foi {"customer": {"name": "Anna", "tier": "gold"}}, pode ler {{customer.name}} ou {{customer.tier}}.
Se um token referenciar uma variável que não existe, o texto literal {{name}} fica no lugar (não é apagado). Isto é intencional — torna os templates partidos fáceis de detetar numa chamada de teste, em vez de os engolir silenciosamente.
Padrões Comuns
Qualificar → Ramificar → Encaminhar
Start
└─ Agent (greeting + qualify)
└─ Gather input (intent)
└─ Condition: intent == "sales" → Agent (sales)
└─ Condition: intent == "support" → Subagent (triage)
└─ Always (catch-all) → Message "Let me connect you" → Phone transfer
Consultar → Personalizar
Start
└─ Tool (CRM lookup, writes is_known, name, tier)
└─ Condition: is_known == true → Agent (warm greeting with {{name}})
└─ Always (else) → Agent (cold greeting)
Ajudante Reutilizável (desvio via Subagent)
Agent (main conversation)
└─ AI decides: "Caller mentions an address" → Subagent (address collector)
└─ on finish: result = full_address
└─ Agent continues with {{full_address}}
O Que Fica Bloqueado Durante uma Chamada de Workflow
Alguns defaults mudam quando um grafo governa a chamada:
- O idioma fica bloqueado naquilo que o primeiro agente do workflow usa. A IA não pode mudar de idioma a meio da chamada. Isto impede o modelo de derivar para o idioma errado num turno ruidoso.
- O prompt principal do agente é substituído pelo prompt do nó ativo. Esta é a regra "o grafo é dono da persona" — veja o aviso em Agent.
- A primeira mensagem vem da saudação do nó de entrada, não do campo "Begin Message" principal do agente.
Segurança de Loop — Orçamento de Passos
Cada workflow tem um número máximo de transições por chamada (padrão 25). Cada vez que o grafo se move para um novo nó, o contador desce um. Quando chega a zero, o workflow para de saltar entre nós para prevenir loops descontrolados.
Pode escolher um nó de fallback para este caso (normalmente um Phone transfer ou End call) — a chamada é desviada para lá quando o orçamento esgota. Caso contrário, a IA recupera o controlo e o grafo fica efetivamente congelado para o resto da chamada.
Muito raramente precisa de pensar nisto — é uma rede de segurança para grafos que entram em loop acidentalmente. Se atinge isto em uso normal, provavelmente tem um ciclo em algum sítio.
Testes
O botão Test Call no editor abre uma chamada no browser com o rascunho de workflow atual. Enquanto a chamada corre, um pirilampo luminoso move-se entre os nós na tela para que possa ver exatamente onde a chamada está. O editor fica bloqueado durante uma chamada de teste para prevenir que edições dessincronizem com o estado ao vivo.
Use a Test Call para verificar:
- As suas condições correspondem aos valores que espera (observe o pirilampo saltar um ramo que pensou que iria disparar).
- Os seus tokens substituem corretamente (esteja atento a um
{{name}}perdido se um valor ainda não foi definido). - As falhas de ferramenta degradam graciosamente (o seu caminho de fallback dispara mesmo).
Modos de Falha a Conhecer
| Situação | O que acontece |
|---|---|
| Chamada de Tool / Integration falha | O grafo continua sem os dados. As suas condições a jusante devem lidar com a variável em falta. |
| Phone transfer falha (número inválido, sem resposta, ligação telefónica em falta) | O grafo faz rollback, o agente atual mantém-se em linha, e a conversa continua normalmente. |
| Subagent falha ao iniciar | O desvio é cancelado, o agente pai mantém-se, e uma breve linha de falha é falada. |
{{missing_variable}} em texto | Deixado literal na saída — fácil de detetar durante chamadas de teste. |
| Nó Sub-workflow | Atualmente passa sem fazer nada. Não dependa dele ainda. |
| Orçamento de passos esgotado | Desvia para o nó de fallback se houver um definido, caso contrário a IA recupera o controlo. |
Quando NÃO Usar um Workflow
Os workflows são poderosos mas não são a resposta certa para cada agente. Fique com um único prompt quando:
- A conversa é de resposta aberta ("responda às perguntas do interlocutor sobre os nossos produtos").
- Não tem lógica de ramificação clara — a maioria das decisões são juízos que a IA lida bem.
- Estaria a escrever um nó agent e um End call — isso é apenas um prompt com passos extra.
Recorra a um workflow quando:
- Consegue esboçar a chamada como um fluxograma com três ou mais etapas distintas.
- Precisa de pelo menos um ramo determinístico sobre uma variável (uma Condition).
- Quer reutilizar uma fatia de conversa em vários agentes (um subagent).
- Já está a acumular regras "se o interlocutor disser X então faça Y" num prompt e elas não são fiáveis.