Editor de Expressoes CEL
O AutoTalk usa expressoes CEL (Common Expression Language) em agentes de IA e workflows para tornar o comportamento dinamico — personalizando mensagens do sistema com nomes de clientes, executando etapas condicionalmente, calculando valores em tempo de execucao e mais.
Esta pagina explica como escrever e testar expressoes CEL usando o editor integrado.
Onde as expressoes aparecem
As expressoes CEL aparecem onde quer que voce veja o emblema CEL na interface de configuracao:
- Agente > Aba Mensagens — conteudo da mensagem do sistema (ex.: injetar o nome do cliente em um prompt)
- Agente > Aba Acoes — o campo Condicao em cada etapa de pre-acao ou pos-acao
- Workflow > Etapas — condicoes de etapas e mapeamentos de saida
O editor de expressoes
Quando voce abre uma etapa de acao para edicao, o campo Condicao mostra o editor de expressoes compacto. Ele possui:
- Destaque de sintaxe — palavras-chave, strings e operadores sao coloridos
- Validacao em tempo real — um emblema verde Valido aparece quando a expressao esta correta; um emblema vermelho de erro aparece com a mensagem de erro exata quando nao esta
- Botao Formatar — formata automaticamente a expressao (atalho de teclado:
Ctrl+Shift+F) - Botao 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 criacao, alternados pelo botao CEL no cabecalho do campo:
| Modo | Exemplo | Quando usar |
|---|---|---|
| CEL Simples (SCEL) | Hello {{client.name}}! | Sintaxe mais simples para texto com substituicoes de variaveis |
| CEL Bruto | "Hello " + client.name + "!" | Sintaxe CEL completa quando voce precisa de logica, condicionais ou chamadas de funcao |
Ambos os modos produzem o mesmo resultado. A sintaxe {{variavel}} e convertida automaticamente para CEL bruto quando voce salva.
Opcoes avancadas de campo
Expanda a gaveta Avancado abaixo de qualquer campo de expressao para configurar:
| Opcao | O que faz |
|---|---|
| Em caso de falha | O que acontece se a expressao gerar um erro em tempo de execucao: parar a acao (throw), retornar vazio (""), ou retornar null |
| Tipo de resultado | Tipo de saida esperado (string, boolean, number, object, array) |
| Fallback | Uma segunda expressao para avaliar se a primaria falhar |
O ambiente de trabalho completo
Clique em Expandir em qualquer editor de expressao para abrir o ambiente de trabalho completo em uma visualizacao dedicada.
Aba Explorador
A aba Explorador mostra tudo disponivel no contexto atual:
- Arvore de variaveis — todas as variaveis que voce pode referenciar nesta expressao, expansiveis para ver campos aninhados. Clique em qualquer variavel ou campo para inseri-lo no cursor.
- Lista de funcoes — todas as funcoes integradas com sua assinatura e descricao. Clique para inserir.
- Caixa de busca — filtra tanto variaveis quanto funcoes conforme voce digita.
As variaveis mostradas dependem de onde a expressao esta localizada:
| Localizacao | Variaveis disponiveis |
|---|---|
| Pre-acoes / pos-acoes do agente | client, contactMessage, conversation, company, step(0), step(1), ... |
| Mensagens do sistema do agente | client, company, employee, e variaveis de sessao definidas por pre-acoes anteriores |
| Etapas do Workflow | _workflow, occurrenceDate, entradas do gatilho, step(0), ... |
Aba Teste
A aba Teste permite avaliar a expressao com valores de variaveis personalizados sem afetar uma conversa real:
- Edite o JSON a esquerda para definir valores de teste para variaveis (ex.: defina
client.namecomo"Alice") - Clique em Executar (ou pressione
Ctrl+Enter) - O resultado aparece a direita — seja o valor calculado ou uma mensagem de erro formatada
Referencia de variaveis
Para uma lista completa de todas as funcoes disponiveis, consulte a Referencia de Funcoes CEL.
Estas variaveis estao disponiveis dentro de expressoes de agentes:
| Variavel | Descricao |
|---|---|
client | O contato que enviou a mensagem — client.name, client.phoneNumber, client.email, client.tags, etc. |
contactMessage | A mensagem recebida — contactMessage.body.text, contactMessage.type, etc. |
conversation | A sessao da conversa — conversation.status, conversation.metadata, etc. |
company | O perfil da sua empresa — company.name, company.options, etc. |
employee | O funcionario/profissional atribuido (disponivel em mensagens do sistema) |
step(N) | Saida de uma etapa anterior no indice N — ex.: step(0).jwt, step(2).data[0], ou get(step(1), 'executionContext.status') |
Verificacoes comuns de resultado de etapas
Use as funcoes auxiliares de etapa para verificacoes 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
Ou use step(N).executionContext diretamente para verificacoes de nivel 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 e destinado para depuracao e ramificacao seguras. Ele nao expoe stack traces brutos, segredos ou payloads de provedores.
Consulte a Referencia de Funcoes CEL para a lista completa de funcoes.
Depurando erros de expressao
Quando uma expressao CEL falha durante uma conversa real, uma bolha de erro aparece no chat — visivel apenas para sua equipe, nao para o cliente.
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.
Visualizacao expandida
O painel expandido possui quatro secoes:
| Secao | Conteudo |
|---|---|
| Expressao CEL | A expressao exata que falhou — copie-a para colar no ambiente de trabalho para teste |
| Metadados | Onde o erro aconteceu: qual secao da configuracao do agente, qual indice de mensagem ou acao |
| Variaveis CEL | (Apenas nivel de log Debug) A lista completa de variaveis e seus valores no momento do erro |
| Payload Completo | Os dados brutos do erro em JSON |
Secao de Variaveis CEL
A secao de Variaveis CEL e a mais util para diagnosticar problemas:
- Use a caixa de filtro para buscar a variavel que sua expressao referencia
- Expanda qualquer variavel para inspecionar seu valor e estrutura reais
- Variaveis rotuladas como truncadas sao objetos grandes que foram abreviados
Nota: Variaveis CEL so aparecem quando o Nivel de Log do agente esta definido como Debug. Va para a aba Avancado do agente para aumentar o nivel de log, depois reduza novamente apos corrigir o problema.
Depuracao passo a passo
- Expanda a bolha de erro com Expandir.
- Em Expressao CEL, copie a expressao com falha.
- Em Metadados, anote a
secaoe oindicepara encontrar o campo correto no editor do agente. - Em Variaveis CEL (requer nivel de log Debug), busque a variavel que a expressao usa e verifique seu valor real.
- Abra o editor do agente, va para a aba relevante e clique em Expandir no campo problematico.
- Cole a expressao na aba Teste, insira valores de variaveis realisticos e execute para reproduzir o erro.
- Corrija a expressao e salve. A bolha de erro deixara de aparecer assim que a expressao for bem-sucedida.