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 passá-la para outro agente. Você o constrói num canvas colocando 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 roteamento determinístico baseado nas respostas do chamador (não «a IA geralmente acerta»), ou quando um agente devia passar parte do trabalho a um especialista.
Um prompt é uma instrução longa. O agente lê-a uma vez e usa-a durante toda a chamada. Um workflow são várias instruções pequenas, uma por nó, com transições explícitas entre elas. O grafo conduz a chamada — o agente de cada nó só é dono do seu pedaço.
Se o seu agente já funciona bem com um único prompt, não precisa de um workflow. Recorra aos workflows quando começar a empilhar regras «se X então Y» no prompt e elas deixarem de ser fiáveis.
O editor
O editor de workflow vive na sua própria aba na página do agente. Vê um canvas com um nó Start e um nó End por defeito. Adiciona nós pela toolbar, arrasta-os para o canvas e liga-os com arestas.
O painel direito muda conforme o que selecciona:
- Clique num nó — abre o seu painel de definições (prompt, campos, variáveis de extracção, etc.).
- Clique numa aresta — abre as definições do seu trigger (AI decides / Condition / Always).
- O painel Variables (botão da toolbar) lista cada variável do workflow com salto num clique para o nó que a fixa ou lê.
Execute uma Test Call no browser directamente do editor — um pirilampo brilhante segue a posição ao vivo para ver exactamente que nó está activo a cada momento.
Workflows têm três estados:
- Draft — editável, ainda não em produção. Use Test Call para o testar.
- Active — em produção para chamadas reais. O agente usa este workflow a partir da próxima chamada.
- Template — template reutilizável, nunca ligado directamente a um agente. Pode instanciá-lo em vários agentes.
Nós
Cada nó é um passo na conversa. Tipos de nó diferentes fazem coisas diferentes — uns falam, outros ouvem, outros roteiam, outros 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 desencadeie uma transição.
Configura a personalidade e tarefa do nó Agent directamente no canvas (a tab Prompt abre ao clicar no nó) — este é o prompt para aquela porção da conversa, não para a chamada toda. Também pode anexar bases de conhecimento e ferramentas por nó.
Greeting — a linha de abertura. Se este for o nó de entrada (a primeira paragem depois de Start), é a primeira coisa que o chamador ouve.
Quando um grafo governa uma chamada, o prompt principal do agente (o da tab Model) é substituído pelo prompt do nó activo. É intencional — o grafo é dono da personalidade e tarefa por etapa, não um único prompt fixo a competir.
Subagent
Um subagent é um ajudante que corre inline — pega a conversa para uma tarefa específica e depois devolve o resultado a quem o invocou.
Subagents funcionam bem quando uma peça de trabalho é reutilizável ou se sente distinta: «verificar a identidade do chamador», «recolher morada de entrega», «qualificar um lead com o método SPIN». O agente pai chama o subagent, o subagent faz o seu, reporta um resultado, o pai retoma onde estava.
Os nós Subagent têm as mesmas tabs de um nó Agent (Prompt, Knowledge, Tools, Actions) — o editor cria automaticamente um agente backing escondido para si. Não vê este agente escondido na sua lista principal e ele não conta para o limite de agentes do seu plano.
Return variable — o campo onde guardar o resultado do subagent (p. ex. identity_verified, lead_score).
Message (Say)
O nó Say diz uma linha fixa — sem turno de IA, sem improviso. Use-o para transições («Um momento, transfiro-o…»), avisos legais obrigatórios ou confirmações predefinidas onde as palavras importam.
Text — o que dizer. Suporta tokens {{variable}} para injectar valores capturados, p. ex. "Obrigado {{first_name}}, reservei para si às {{appointment_time}}."
Um nó Say consome o turno — o agente não acrescentará nada por cima.
Gather Input
Um nó Gather Input faz uma pergunta e captura a resposta do chamador numa variável.
Prompt — a pergunta a fazer. Suporta {{tokens}}.
Variable — o nome do campo onde guardar a resposta.
Use-o sempre que precisar de um valor concreto antes de continuar — email, número de conta, número de pessoas, categoria do problema. O próximo turno do chamador 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 nem perguntar. Use para pré-definir defaults, marcar flags de progresso ou compor valores a partir de passos anteriores.
Variable / Value — um par chave-valor. More variables (optional) — pares chave-valor adicionais.
Tanto chaves como valores suportam {{tokens}}, então pode compor novos valores a partir dos existentes.
Condition
O nó Condition é um nó só-de-roteamento — não fala, não pergunta, simplesmente envia a chamada pela ramificação de saída que matchou.
A condição em si vive em cada aresta de saída, não no nó — ver arestas Condition abaixo.
Use um nó Condition quando quiser um ponto claro de «fan-out» no seu grafo: várias ramificações que dependem do valor de uma variável. Comparado com pôr condições nas arestas de nós Agent, um nó Condition dedicado torna a lógica de roteamento visualmente óbvia.
Tool
O nó Tool executa uma das ferramentas ligadas do agente como passo do grafo — sem que a IA opine sobre chamá-la. Use-o quando quiser um facto, não uma conversa: «procura este cliente», «verifica stock», «GET do tempo actual».
Pode:
- Escolher uma das ferramentas existentes do agente (consulta de calendário, pesquisa em base de conhecimento, acção específica de uma integração), ou
- Configurar uma chamada HTTP inline directamente no nó (URL, método, cabeçalhos, parâmetros, body).
A resposta da ferramenta fica disponível a todos os nós a jusante. Se a resposta for um objecto JSON, cada campo de primeiro nível torna-se a sua própria variável — uma resposta como {"is_known": true, "tier": "gold"} escreve tanto is_known como tier para ramificar sobre eles.
Cada campo de texto no nó Tool — URL, valores de cabeçalho, body — suporta {{tokens}}. Mete uma variável no path de URL, num cabeçalho ou no body sem escrever código.
Se uma chamada de ferramenta falhar (erro HTTP, timeout, rede), o nó loga a falha e o grafo continua — sem os dados. Planeie as suas condições a jusante para lidar com o caso «sem valor».
Integration
O nó Integration é uma variante focada de Tool, para serviços externos ligados — Google Calendar, Outlook, HubSpot. Escolhe o provider e a acção específica (p. ex. check_availability, create_event), passa os parâmetros, e o nó chama a integração deterministicamente.
Se a integração não estiver ligada neste agente, o nó passa sem fazer nada — o seu grafo continua. Verifique condições a jusante para o caso «não correu».
Phone Transfer
O nó Phone Transfer transfere a chamada (warm transfer) para um número telefónico 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 + à frente (p. ex. +15551234567). Suporta {{tokens}} para que o destino possa vir de um passo anterior (p. ex. a resposta a «com que escritório o ligamos?»).
Se a transferência não se concretizar (número inválido, sem resposta, ligação telefónica não configurada), o grafo recua e o agente actual continua em linha. A conversa prossegue normalmente — o agente pode pedir desculpa e tentar outro caminho.
End Call
O nó End Call fecha — o agente diz o encerramento configurado e depois desliga. Use como terminus limpo para ramos «tudo feito» ou para o ramo «não podemos ajudar, lamentamos» de uma Condition difícil.
Não requer configuração além de uma aresta de entrada.
Reutilizar um workflow (Sub-workflow)
O nó Sub-workflow está reservado para embeber outro workflow como sub-grafo. Este nó está no editor mas ainda não está totalmente ligado — o grafo passa por ele sem fazer nada. Não conte com ele para chamadas em produção. Vamos activá-lo quando publicarmos os sub-grafos reutilizáveis.
Arestas (Conexões)
Liga um nó ao seguinte através de uma aresta. O trigger da aresta decide quando a transição dispara.
Há três triggers:
| Trigger | 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 matcha uma regra que escreveu. Avaliado antes da IA responder. |
| Always | O runtime | Incondicionalmente — assim que o nó origem termina. Sem input do chamador, sem IA. |
AI decides (baseado em intenção)
Use AI decides quando só a IA pode decidir quando mudar — «se o chamador pergunta sobre preços, transfere para o agente de vendas», «se soa a queixa, executa o subagent de desculpas».
Escreve uma breve descrição de intent na aresta (p. ex. «O chamador pergunta sobre preços ou quer fazer upgrade»). A IA vê-a como uma ferramenta etiquetada com esse intent e decide se a chama com base na conversa. Se houver várias arestas AI-decides, a IA escolhe no máximo uma por turno.
Condition (ramificação determinística)
Use Condition quando quiser que o grafo — não a IA — decida com base num facto conhecido: «se lead_score > 7, manda ao closer; senão, termina educadamente».
As Conditions são avaliadas antes da IA responder, portanto sempre ganham à IA nesse turno. A IA não pode sobrescrever uma condição que matcha.
Pode construir uma condição com estes operadores:
| Operador | Significado | Exemplo |
|---|---|---|
| equals | match exacto (case-insensitive para texto) | intent equals "billing" |
| not equals | não matcha | status not equals "active" |
| contains | match de substring (case-insensitive) | feedback contains "broken" |
| greater than | numérico > | lead_score greater than 7 |
| less than | numérico < | wait_minutes less than 5 |
Também pode combinar cláusulas com All (todas têm de matchar — AND) ou Any (pelo menos uma tem de matchar — OR), e aninhá-las. Uma regra como «o chamador é conhecido e o seu tier é gold ou premium» torna-se:
All:
- is_known equals true
- Any:
- tier equals gold
- tier equals premium
Se referenciar uma variável que ainda não foi fixada (p. ex. a IA nunca a recolheu), as condições sobre ela falham sempre — sem erro, simplesmente não matcham. Então loyalty_tier equals "gold" devolve falso se loyalty_tier nunca foi fixado. Desenhe os seus ramos para lidar com isto — geralmente com um ramo else (ver abaixo).
Ramo else — quando nenhuma condição matcha
Se tiver várias arestas Condition a sair de um nó e nenhuma matchar, a chamada cai na aresta não-Condition de menor prioridade (Always ou uma aresta AI-decides). Se não houver fallback algum, a IA retoma o controlo e pode continuar livremente.
Padrão comum: várias Conditions para os caminhos conhecidos, mais uma aresta Always a um catch-all (dizer algo, depois End Call ou transferir).
Always (auto-advance)
Use Always quando o próximo passo é incondicional — sem decisão, sem input de chamador. Dois usos naturais:
- Encadear passos: SAY → UPDATE_STATE → SAY → TOOL → Condition. Cada passo termina e a aresta Always avança imediatamente.
- Auto-avançar depois do agente acabar de falar: um nó Agent com uma aresta Always de saída significa «assim que a IA parar de falar, avança» — sem precisar que o chamador responda. Útil para fluxos tipo monólogo como um agente apresentador que entrega e passa à próxima secção.
Condition e Always (os determinísticos) ganham sempre a AI decides. Se uma Condition matchar, as ferramentas de transição da IA são ignoradas nesse turno. Isso permite-lhe escrever regras que a IA não pode saltar.
Variáveis
As variáveis são a memória do workflow. A maior parte das coisas num workflow ou fixam uma variável ou lêem uma.
Declarar variáveis
O painel Variables (botão da toolbar) mostra cada variável do workflow com os passos que a fixam ou lêem. Clique numa variável para saltar para um setter; é a forma mais rápida de encontrar onde algo dá errado.
Pode declarar uma variável com um valor por defeito no painel — útil para flags como escalated=false que precisam de existir desde o início para que as suas condições não falhem silenciosamente por «ausência».
Como as variáveis se fixam
| Fonte | Exemplo |
|---|---|
| Valores por defeito (declarados no painel Variables) | escalated = false fixado antes da chamada começar |
| Gather Input | A resposta falada do chamador é capturada na variável do nó |
| Update State | Escreve um valor (literal ou composto com {{tokens}}) directamente |
| Resultado de Tool / Integration | A resposta inteira é guardada sob o nome do nó; se a resposta for um objecto JSON, cada campo de primeiro nível também se torna a sua própria variável |
| Return de Subagent | O que o subagent finaliza é guardado na variável de retorno do nó subagent |
Ler variáveis — {{tokens}}
Onde puder escrever texto num nó — prompt de Agent, texto de Say, prompt de Gather, URL/body/cabeçalhos de Tool, número de Phone Transfer, valor de Update State, valores de condição — pode meter {{variable}} e será substituído em runtime.
Paths com ponto também funcionam para dados aninhados — p. ex. se uma resposta de Tool foi {"customer": {"name": "Anna", "tier": "gold"}}, pode ler {{customer.name}} ou {{customer.tier}}.
Se um token referencia uma variável que não existe, o texto literal {{name}} é deixado como está (não é apagado). É intencional — torna templates partidos fáceis de detectar numa test call, em vez de os engolir em silêncio.
Padrões comuns
Qualificar → Ramificar → Rotear
Start
└─ Agent (greeting + qualify)
└─ Gather Input (intent)
└─ Condition: intent == "sales" → Agent (sales)
└─ Condition: intent == "support" → Subagent (triage)
└─ Always (catch-all) → Say "Let me connect you" → Phone Transfer
Procurar → Personalizar
Start
└─ Tool (CRM lookup, writes is_known, name, tier)
└─ Condition: is_known == true → Agent (warm greeting with {{name}})
└─ Always (else) → Agent (cold greeting)
Helper reutilizável (Subagent side-trip)
Agent (main conversation)
└─ AI decides: "Caller mentions an address" → Subagent (address collector)
└─ on finish: result = full_address
└─ Agent continues with {{full_address}}
O que está bloqueado durante uma chamada com workflow
Alguns defaults mudam quando um grafo governa a chamada:
- A língua está bloqueada na que usa o primeiro agente do workflow. A IA não pode mudar de língua a meio da chamada. Isto previne que o modelo derive para a língua errada num turno ruidoso.
- O prompt principal do agente é substituído pelo prompt do nó activo. É a regra «o grafo é dono da persona» — ver warning sob Agent.
- A primeira mensagem vem do greeting do nó de entrada, não do campo «Begin Message» do agente.
Segurança anti-loop — Step Budget
Cada workflow tem um número máximo de transições por chamada (por defeito 25). Sempre que o grafo passa para um novo nó, o contador desce um. Quando chega a zero, o workflow pára de saltar entre nós para prevenir loops descontrolados. Pode escolher um nó de fallback para este caso (tipicamente um Phone Transfer ou End Call) — a chamada é desviada para lá assim que o orçamento acaba. Senão, a IA retoma o controlo e o grafo efectivamente congela pelo resto da chamada.
Raramente precisa de pensar nisto — é uma rede de segurança para grafos que acidentalmente lopam. Se chegar lá em uso normal, provavelmente tem um ciclo algures.
Testar
O botão Test Call do editor abre uma chamada de browser com o draft actual do workflow. Enquanto corre, um pirilampo brilhante move-se entre os nós do canvas para ver exactamente onde está a chamada. O editor é bloqueado durante uma test call para impedir que mudanças desincronizem o estado ao vivo.
Use Test Call para verificar:
- As suas condições matcham os valores que espera (veja se o pirilampo salta um ramo que pensou que dispararia).
- Os seus tokens são substituídos bem (oiça por um
{{name}}pendurado se um valor não tivesse sido fixado). - As falhas de ferramenta degradam graciosamente (a sua rota de fallback dispara mesmo).
Falhas a conhecer
| Situação | O que acontece |
|---|---|
| Chamada Tool / Integration falha | O grafo continua sem os dados. As suas condições a jusante devem lidar com a variável ausente. |
| Phone Transfer falha (número inválido, sem resposta, ligação telefónica em falta) | O grafo recua, o agente actual fica em linha e a conversa continua normalmente. |
| Subagent falha ao arrancar | O desvio é cancelado, o agente pai mantém-se em linha, e uma curta linha de falha é falada. |
{{missing_variable}} em texto | Deixado literal na saída — fácil de detectar em test calls. |
| Nó Sub-workflow | Actualmente passa sem fazer nada. Não conte com ele ainda. |
| Step budget esgotado | Desvia para o nó de fallback se estiver definido, senão a IA retoma o controlo. |
Quando NÃO usar um Workflow
Workflows são poderosos mas não são a resposta certa para cada agente. Fique com um único prompt quando:
- A conversa é aberta («responder a perguntas do chamador 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.
- Só escreveria um nó Agent e um End Call — é só um prompt com passos extra.
Recorra a um workflow quando:
- Consegue esquematizar a chamada como um fluxograma com três ou mais etapas distintas.
- Precisa de pelo menos uma ramificação determinística sobre uma variável (uma Condition).
- Quer reutilizar um pedaço de conversa entre vários agentes (um subagent).
- Já está a empilhar regras «se o chamador disser X então fazer Y» num prompt e não são fiáveis.