Atualizado em Sep 17, 2026

Editor de Expressões CEL

O AutoTalk usa expressões CEL (Common Expression Language) em agentes de IA e workflows para tornar o comportamento dinâmico — personalizando mensagens do sistema com nomes de contatos, executando etapas condicionalmente e calculando valores em tempo de execução.

Esta página explica como escrever e testar expressões CEL usando o editor integrado.

---

Onde as expressões aparecem

As expressões CEL aparecem onde quer que você veja o emblema CEL na interface de configuração:

• Agente > Aba Mensagens — conteúdo da mensagem do sistema (ex.: injetar o nome do contato em um prompt)
• Agente > Aba Ações — o campo Condição em cada etapa de pré-ação ou pós-ação
• Workflow > Etapas — condições de etapas e mapeamentos de saída

---

O editor de expressões

Quando você abre uma etapa de ação para edição, o campo Condição mostra o editor de expressões compacto. Ele possui:

• Destaque de sintaxe — palavras-chave, strings e operadores são coloridos
• Validação em tempo real — um emblema vermelho de erro aparece com a mensagem de erro exata quando a expressão é inválida (o emblema verde Válido fica no ambiente de trabalho expandido, não no campo compacto)
• Botão Formatar — formata automaticamente a expressão (atalho de teclado: Ctrl+Shift+F)
• Botão Expandir — abre o ambiente de trabalho completo (veja abaixo)

---

CEL simples vs CEL bruto

Campos de mensagem do sistema (e outros campos de texto) oferecem dois modos de criação, alternados pelo botão CEL no cabeçalho do campo:

Modo	Exemplo	Quando usar
CEL Simples (SCEL)	Hello {{contact.name}}!	Sintaxe mais simples para texto com substituições de variáveis
CEL Bruto	"Hello " + contact.name + "!"	Sintaxe CEL completa quando você precisa de lógica, condicionais ou chamadas de função

Ambos os modos produzem o mesmo resultado. A sintaxe {{variavel}} é convertida automaticamente para CEL bruto quando você salva.

Opções avançadas de campo

Expanda a gaveta Avançado abaixo de qualquer campo de expressão para configurar:

Opção	O que faz
Em caso de erro	O que acontece se a expressão gerar um erro em tempo de execução: lançar o erro (throw, o padrão), retornar null, usar fallback para uma string, ou manter a expressão original
Tipo de resultado	Tipo de saída esperado (any — o padrão — string, number, boolean, date, array ou object)
Valor de fallback	Uma string literal usada como resultado quando Em caso de erro está definido como Fallback para string

---

O ambiente de trabalho completo

Clique em Expandir em qualquer editor de expressão para abrir o ambiente de trabalho completo em uma visualização dedicada. Sua barra de ferramentas tem botões de alternância Explorer e Teste que abrem um painel flutuante sobre o editor.

Explorer

O painel Explorer mostra tudo disponível no contexto atual:

• Árvore de variáveis — todas as variáveis que você pode referenciar nesta expressão, expansíveis para ver campos aninhados. Clique em qualquer variável ou campo para inseri-lo no cursor.
• Lista de funções — todas as funções integradas com sua assinatura e descrição. Clique para inserir.
• Caixa de busca — filtra tanto variáveis quanto funções conforme você digita.

As variáveis mostradas dependem de onde a expressão está localizada:

Localização	Variáveis disponíveis
Pré-ações / pós-ações do agente	contact, contactMessage, conversation, company, step(0), step(1), ...
Mensagens do sistema do agente	company, contact, contactMessage, conversation, e quaisquer resultados de ferramentas em context.tools.*
Etapas do Workflow	_workflow, occurrenceDate, entradas do gatilho, step(0), ...

Nota: o contato é exposto como a variável contact — escreva contact.name nas expressões. (Versões antigas rotulavam o contato como client na árvore do Explorer; a chave em tempo de execução sempre foi contact.)

Teste

O painel Teste permite avaliar a expressão com valores de variáveis personalizados sem afetar uma conversa real:

1. Edite o JSON à esquerda para definir valores de teste para variáveis (ex.: defina contact.name como "Alice")
2. Clique em Executar (ou pressione Ctrl+Enter)
3. O resultado aparece à direita — seja o valor calculado ou uma mensagem de erro formatada

---

Referência de variáveis

Para uma lista completa de todas as funções disponíveis, consulte a Referência de Funções CEL.

Estas variáveis estão disponíveis dentro de expressões de agentes:

Variável	Descrição
contact	O contato que enviou a mensagem — contact.name, contact.contactIdentification, contact.tags, contact.customAttributes, etc.
contactMessage	A mensagem recebida — contactMessage.body.text, contactMessage.type, etc.
conversation	A sessão da conversa — conversation.contactId, conversation.lastMessageAt, conversation.isGroup, etc.
company	O perfil da sua empresa — company.companyName, company.options, etc.
step(N)	Saída de uma etapa anterior no índice N — ex.: step(0).jwt, step(2).data[0], ou get(step(1), 'executionContext.status')

Não existe uma variável employee de nível superior nos contextos de agentes. Busque os dados de funcionário/profissional por meio de uma etapa de dados e leia-os de step(N).data[0].

---

Verificações comuns de resultado de etapas

Use as funções auxiliares de etapa para verificações concisas de status de etapas:

step_ok(0)                                          // true se a etapa 0 completou com sucesso
step_data(0, "title")                               // obter data.title da etapa 0
step_data(1, "choices.0.message.content", "")        // resposta do LLM com fallback
step_error(2)                                        // {code, user_message, retryable} ou null

O caminho de step_data é relativo ao data da etapa, então step_data(0, "title") é get(step(0), "data.title") — nunca escreva step_data(0, "data.title"). Muitas ações publicam na raiz da etapa e não têm data nenhum — incluindo actions/ai/llm/chat/generate, actions/data/company/resource/count e todas as actions/media/storage/* — então leia essas com get(step(N), "field"). Um caminho que não existe devolve o valor padrão em silêncio enquanto step_ok(N) continua true, então verifique antes as saídas declaradas da ação — a lista completa está em Ações que publicam na raiz da etapa.

Executar Código é um terceiro caso: ele publica um result no topo, então step_data(N, "count") lê step(N).result.count, enquanto os irmãos na raiz files, logs e executionTimeMs só são alcançáveis com get(step(N), "files").

Ou use step(N).executionContext diretamente para verificações de nível mais baixo:

get(step(0), 'executionContext.status') == 'completed'
get(step(1), 'executionContext.safeError.code') == 'unsupported_media_format'
get(step(2), 'executionContext.safeResult.reason') == 'condition_false'

safeError é destinado para depuração e ramificação seguras. Ele não expõe stack traces brutos, segredos ou payloads de provedores.

Consulte a Referência de Funções CEL para a lista completa de funções.

Depurando erros de expressão

Quando uma expressão CEL falha durante uma conversa real, uma bolha de erro aparece no chat — visível apenas para sua equipe, não para o contato.

Lendo a bolha de erro

A bolha colapsada mostra o tipo de erro e uma mensagem de uma linha. Clique em ▼ Expandir para ver o painel de detalhes completo.

Visualização expandida

O painel expandido possui quatro seções:

Seção	Conteúdo
Expressão CEL	A expressão exata que falhou — copie-a para colar no ambiente de trabalho para teste
Metadados	Onde o erro aconteceu: qual seção da configuração do agente, qual índice de mensagem ou ação
Variáveis CEL	(Apenas nível de log Debug) A lista completa de variáveis e seus valores no momento do erro
Payload Completo	Os dados brutos do erro em JSON

Seção de Variáveis CEL

A seção de Variáveis CEL é a mais útil para diagnosticar problemas:

• Use a caixa de filtro para buscar a variável que sua expressão referencia
• Expanda qualquer variável para inspecionar seu valor e estrutura reais
• Variáveis rotuladas como truncadas são objetos grandes que foram abreviados

Nota: Variáveis CEL só aparecem quando o Nível de Log do agente está definido como Debug. Vá para a aba Opções do agente para aumentar o nível de log, depois reduza novamente após corrigir o problema.

Depuração passo a passo

1. Expanda a bolha de erro com ▼.
2. Em Expressão CEL, copie a expressão com falha.
3. Em Metadados, anote a secao e o indice para encontrar o campo correto no editor do agente.
4. Em Variáveis CEL (requer nível de log Debug), busque a variável que a expressão usa e verifique seu valor real.
5. Abra o editor do agente, vá para a aba relevante e clique em Expandir no campo problemático.
6. Cole a expressão na aba Teste, insira valores de variáveis realísticos e execute para reproduzir o erro.
7. Corrija a expressão e salve. A bolha de erro deixará de aparecer assim que a expressão for bem-sucedida.