Editor de expressões CEL
Use CEL em mensagens de agentes, condições de ações, saídas de workflows e
comportamento de formulários. O AutoTalk usa CEL-Go no navegador e no servidor.
Funções compartilhadas usam <family>.<camelCase>; funções importadas
do tenant usam <slug>.<function>. A referência
mostra sintaxe e disponibilidade por contexto.
A geração 4 mantém o descritor {expr, ...options} e usa nomes mais curtos.
Escritas CEL na API enviam X-Autotalk-Cel-Schema: 4; ferramentas MCP que
recebem código CEL usam celSchemaGeneration: "4". Código com os prefixos
antigos precisa da migração revisada antes de executar nesta geração.
Onde aparecem as expressões
O emblema CEL identifica o campo de expressão. Os locais comuns incluem mensagens/pré-ações/pós-ações de agentes, etapas de workflow, templates e rótulos/visibilidade/previews de Custom Types. Nomes de campos e identificadores literais de abas/referências não são expressões automaticamente.
Editor compacto
O editor compacto oferece destaque de sintaxe, validação, formatação e
Expandir. Use Ctrl+Shift+F para formatar. Diagnósticos de sintaxe/tipos
ajudam a localizar problemas; testes verificam o comportamento com valores reais.
Nomes de chamadas recebem destaque pela sintaxe, inclusive chamadas desconhecidas.
A cor do namespace usa os metadados atuais de funções/importações; uma seleção
como values.name continua sendo dado. A cor não confirma disponibilidade nem
validade de uma função.
A chamada equivalente na geração 4 é labels.normalizeName na versão v1 fixada.
As capturas abaixo usam dados sintéticos da geração 3; seus rótulos
autotalk.*/tenant.* são anteriores aos nomes curtos dos exemplos desta página.
CEL nativo e texto literal
Cada campo de expressão armazena uma única expressão CEL nativa. Para texto
simples, escreva uma string CEL entre aspas e escape aspas ou quebras de linha
dentro dela. O editor expandido mostra essa mesma expressão. Para texto dinâmico,
escreva "Hello " + contact.name + "!",
ou use uma chamada explícita de template:
text.template("Hello {name}!", {
"name": values.coalesce(maps.get(contact, "name"), "Guest")
})
Chaves como {{contact.name}} dentro de uma string continuam sendo texto literal.
"Hello {{contact.name}}" é texto literal; as chaves não substituem um valor.
JSON e MCP usam o mesmo descritor em todos os lugares, incluindo rótulos de Custom Types, abas, previews e condições de monitores:
{"expr": "\"Hello \" + contact.name + \"!\"", "onFailure": "throw"}
Opções avançadas
| Opção | Finalidade |
|---|---|
| Em caso de falha | Gerar erro, retornar null, usar texto literal alternativo ou manter a expressão original |
| Tipo do resultado | Resultado esperado: any, string, number, boolean, date, array ou object |
| Valor alternativo | Texto literal usado pela política de fallback |
Um fallback não torna correta uma expressão inválida. Teste os resultados esperados e as falhas antes de depender dele.
Ambiente de trabalho completo
Expanda o campo para abrir o editor completo. A barra abre Explorador e Teste. Os editores compacto e expandido compartilham as importações exatas do documento; validação, sugestões e Teste usam as mesmas versões. Salve o agente, workflow, Custom Type ou rascunho da biblioteca para persistir a expressão e suas versões fixadas.
Explorador
O Explorador lista variáveis do contexto e funções com assinaturas. Funções
compartilhadas são agrupadas por família, como maps e text; recursos CEL
padrão mantêm sua sintaxe. Importações exatas acrescentam funções na raiz do
slug, como labels.normalizeName. Pesquise e
selecione entradas para inseri-las; funções indisponíveis no contexto são excluídas.
O Explorador filtra as funções disponíveis no campo atual e mostra suas assinaturas.
| Contexto | Entradas comuns |
|---|---|
| Agente | contact, contactMessage, conversation, company, parâmetros de ferramenta declarados |
| Workflow | _workflow, occurrenceDate, entradas manuais e doc, prev, op, model do trigger |
| Formulário | values, item, args, company, employee quando fornecidos pelo formulário |
| Função de biblioteca | Somente parâmetros nomeados declarados e variáveis locais |
A variável de contato é contact. Entradas manuais/de ferramenta são nomes no
nível superior, não um mapa parameters implícito. Quando um agente precisa de
dados de funcionário, obtenha-os com uma ação de dados e leia a saída declarada.
Teste
- Forneça valores JSON representativos para as variáveis.
- Execute pelo botão ou
Ctrl+Enter. - Compare valor/tipo ou examine o diagnóstico.
Teste avalia a função pura fixada e retorna example label.
Inclua dados ausentes/null/vazios e casos de limite. Teste não executa ações de workflow automaticamente para produzir saídas de etapas; funções de contexto e bibliotecas precisam do contexto do campo e do conjunto exato de importações.
Valores opcionais e lógica tipada
Raízes ausentes e acesso direto a campos ausentes geram erro. Use caminhos seguros ou seleção opcional:
values.coalesce(maps.get(contact, "name"), "Guest")
contact.?nickname.orValue("Guest")
cel.bind(name, maps.get(contact, "name"),
values.present(name) ? name : "Guest")
Presença e null são diferentes: um null presente não usa fallback opcional.
has(contact.name) verifica presença; maps.has(contact,"name")
verifica um caminho não null. Conversões nativas usam tipos CEL e podem falhar.
Preserve unidades externas com datetime.fromMillis / toMillis;
timestamp(int) nativo usa segundos Unix.
Exemplos de saídas de etapas
workflow.stepOk(0)
workflow.stepData(0, "title", "Unknown")
workflow.stepData(1, "choices.0.message.content", "")
workflow.stepError(2)
O caminho é relativo a data quando esse envelope existe; não repita data.
Ações com saída na raiz usam seus campos declarados. Veja dados da etapa
e saídas na raiz.
Executar código publica result, então workflow.stepData(N,"count")
lê workflow.step(N).result.count. Campos raiz files, logs e
executionTimeMs precisam de maps.get(workflow.step(N),"files",[]).
Caminhos ausentes usam o padrão, mas índices inexistentes geram erro.
Bibliotecas do tenant
Bibliotecas permitem reutilizar regras sem repetir uma expressão grande. Abra Automações → Bibliotecas e escolha Nova biblioteca → CEL. Informe o nome e um namespace (slug) estável e escolha Criar biblioteca para abrir o editor de funções. Adicione funções tipadas e fixtures e use Verificar para conferir compilação e testes. Salve o rascunho com o botão Salvar da página. Publicar vN publica a revisão salva e verifica novamente compilação e fixtures configuradas.
Cada função possui parâmetros nomeados, tipo de retorno e corpo CEL. Só lê parâmetros, variáveis locais, funções puras compartilhadas e funções puras importadas. Passe contatos, relógios e outros dados explicitamente; bibliotecas não leem estado ambiente de agente/formulário/etapa nem realizam I/O.
Rascunho de exemplo
{
"imports": [],
"functions": [{
"name": "normalizeName",
"parameters": [{"name": "value", "type": "string"}],
"returnType": "string",
"body": {"expr": "text.nameKey(value)"},
"tests": [
{"name": "accents-and-spaces", "args": {"value": " Álice Silva "}, "expected": "alice silva"},
{"name": "empty", "args": {"value": ""}, "expected": ""}
]
}]
}
Use esse rascunho em uma biblioteca de slug labels. Fixtures fornecem
exatamente os argumentos nomeados e um único expected ou expectedError.
Erros esperados correspondem a códigos do avaliador. Os tipos aceitam primitivas
CEL, list<T>, map<K,V> e optional<T>. Valores JSON especiais usam o codec
$cel, por exemplo:
{"$cel": "timestamp", "seconds": "1705276800", "nanos": 0}
Publicar e selecionar uma versão exata
Versões publicadas são imutáveis. Para a primeira importação, selecione uma função do tenant legível e ainda não importada nas sugestões ou aplique a correção de importação ausente; isso adiciona a versão exata ao documento. Com importações existentes, abra a contagem de bibliotecas ao lado do título do documento/página para gerenciá-las e escolher outra versão publicada. Uma expressão que chama uma função importada também oferece Gerenciar no chip de biblioteca do rodapé. O gerenciador compartilha as importações atuais com os editores compacto e expandido. Salve o documento para persistir mudanças. Por MCP/API ou no modo JSON, use os IDs exatos retornados:
{"celLibraries": [{"libraryId": "000000000000000000000001", "releaseId": "000000000000000000000002"}]}
Quando o documento omite celLibraries, ele usa as importações padrão da empresa.
Uma lista própria substitui esses padrões; [] os desativa explicitamente.
Documentos existentes com uma lista vazia continuam sem herdar os padrões.
Mensagens de agentes/Workflows usam as importações resolvidas de quem as executou,
e templates usam as importações do próprio template. Mensagens enviadas pela API,
por contacts.sendMessage ou pela interface de conversas do funcionário salvam as
versões exatas no envio. Alterações posteriores na empresa não mudam as ações de
opções das mensagens já enviadas. O agente atribuído à conversa não fornece as
importações de uma mensagem do funcionário.
A autoria direta de ações executáveis em opções exige acesso de leitura às
bibliotecas importadas. A ferramenta MCP send_message não aceita actions nas
opções e as rejeita antes do envio; use contacts.sendMessage com
automation:admin para essas mensagens.
Substitua pelos seus IDs. Depois é possível chamar:
labels.normalizeName(
values.coalesce(maps.get(contact, "name"), ""))
Editar ou publicar não atualiza chamadores automaticamente. Selecione outra versão exata deliberadamente; dependências também fixam versões exatas. Recarregue um rascunho desatualizado antes de salvar/publicar novamente.
labels.normalizeName(value) é uma função definida pelo tenant neste exemplo. Cada tenant precisa definir e importar sua biblioteca labels; o namespace não fornece uma função global do AutoTalk nem a implementação de outro tenant.
Criação por MCP e API
Clientes MCP usam create_document / update_document com type:"cel_libraries".
Atualizações incluem o draftRevision lido. Descubra as ações com list_functions
e use execute_function para validateDraft, testDraft e publish:
Em escritas de bibliotecas com código CEL, passe celSchemaGeneration: "4"
ao lado de type e document/data, nunca dentro do rascunho salvo. Exemplo:
create_document({type: "cel_libraries", document, celSchemaGeneration: "4"}).
Um rascunho candidate em execute_function também precisa desse argumento;
a leitura get_cel_reference não precisa.
{"type":"cel_libraries","id":"LIBRARY_ID","functionName":"publish","args":{"expectedDraftRevision":1},"celSchemaGeneration":"4"}
Use o ID e a revisão atuais. Validação/testes aceitam candidate não salvo.
get_cel_reference com context:"library" e importações celLibraries exatas
retorna assinaturas compartilhadas e importadas permitidas.
A API pública autenticada oferece as mesmas ações:
POST /v1/dynadata/type/cel_libraries/item/{id}/executeFunction/{functionName}.
O JSON do corpo contém os argumentos, como expectedDraftRevision para publicar.
Escritas HTTP com código CEL incluem X-Autotalk-Cel-Schema: 4, também em
clientes fora do navegador. CRUD usa os endpoints e permissões Dynadata normais.
Diagnosticar uma expressão em execução
Erros visíveis para a equipe identificam a expressão e sua origem. Expanda, copie a expressão e examine seção/índice e diagnóstico. Com logs de depuração, valores disponíveis ajudam a criar uma fixture representativa.
Um diagnóstico recolhido de demonstração identifica o erro e mostra uma prévia curta.
Expanda o diagnóstico para ver expressão, origem, seção e índice.
A aba Variáveis CEL mostra os valores capturados para o diagnóstico. Estes cartões
de demonstração ilustram contact.nickname ausente; não contêm registros de clientes.
Corrija a expressão no agente/workflow/formulário ou rascunho correspondente. Teste e salve; no caso de bibliotecas, publique e atualize deliberadamente a importação exata do chamador. Rascunhos não alteram comportamento ativo até que o chamador importe uma versão.