Skip to main content

​
O que são Tags?

Tags são etiquetas que você pode adicionar às execuções do seu Canvas para organizá-las. Por exemplo, se você tem um Canvas que analisa documentos, pode querer marcar cada execução com:
  • O tipo de documento analisado
  • O status da análise
  • A categoria do conteúdo
Existem dois tipos de tags:
TipoDescriçãoExemplo
Tags EstáticasValores fixos definidos por vocêatendimento, urgente, cliente-vip
Tags DinâmicasValores extraídos automaticamente da resposta da IA$output.categoria, $output.prioridade

​
Como funcionam as Tags Dinâmicas?

As tags dinâmicas usam a variável especial $output para acessar valores da resposta da IA. Quando a execução termina, o sistema substitui automaticamente a variável pelo valor real.

​
Exemplo prático

Imagine que seu Canvas analisa tickets de suporte e retorna a seguinte resposta: 
{
    "categoria": "financeiro",
    "prioridade": "alta",
    "departamento": "cobranca"
}
Se você configurou as seguintes tags dinâmicas:
  • setor-$output.categoria
  • prioridade-$output.prioridade
Após a execução, as tags registradas serão:
  • setor-financeiro
  • prioridade-alta

​
Configurando Tags no Canvas

​
Passo 1: Acesse as configurações do Canvas

Na tela de edição do Canvas, localize a seção de Tags Personalizadas (Custom Tags) nas configurações.
Menu de Tags Personalizadas nas configurações do Canvas

​
Passo 2: Adicione suas tags

Você pode adicionar dois tipos de tags:
Modal de Tags Personalizadas
Digite o nome da tag diretamente:
minha-tag
categoria-fixa
processo-automatico

​
Passo 3: Salve o Canvas

As tags serão aplicadas automaticamente em todas as próximas execuções.

​
Sintaxe das Tags Dinâmicas

​
Formato básico

$output.campo
Onde campo é o nome do valor que você quer extrair da resposta.

​
Acessando valores aninhados

Se a resposta tiver estrutura mais complexa, use pontos para navegar: 
$output.dados.cliente.nome
$output.analise.resultado.score

​
Acessando itens de listas

Para acessar um item específico de uma lista, use colchetes com o número da posição (começando em 0): 
$output.itens[0].nome      // primeiro item
$output.itens[1].categoria // segundo item

​
Combinando com texto fixo

Você pode combinar texto fixo com valores dinâmicos: 
cliente-$output.cliente_id
status-$output.resultado
tipo-$output.categoria-$output.prioridade

​
Enviando Tags via API

Além das tags configuradas no Canvas, você também pode enviar tags adicionais diretamente pela chamada de API. Essas tags serão combinadas com as tags do Canvas.

​
Exemplo de requisição

{
    "messages": [...],
    "tags": [
        "origem-api",
        "cliente-123",
        "tipo-$output.categoria"
    ]
}

​
Como funciona a combinação

OrigemTags
Canvasprocesso-automatico, $output.status
APIorigem-api, cliente-123
Resultado Finalprocesso-automatico, concluido, origem-api, cliente-123
Se a mesma tag aparecer tanto no Canvas quanto na API, ela será registrada apenas uma vez (sem duplicação).

​
Visualizando Tags no Usage

Todas as tags (estáticas e dinâmicas já processadas) são registradas na seção de Usage do Canvas.

​
Onde encontrar

  1. Acesse o Canvas desejado
  2. Vá para a aba Usage ou Histórico de Execuções
  3. Cada execução mostrará suas tags associadas

​
Filtrando por tags

Você pode filtrar as execuções por tags específicas para:
  • Analisar uso por categoria
  • Identificar padrões de comportamento
  • Gerar relatórios segmentados
  • Monitorar tipos específicos de requisições

​
Casos de Uso Comuns

Cenário: Canvas que analisa mensagens de clientesTags configuradas:
  • atendimento (estática)
  • sentimento-$output.sentimento
  • assunto-$output.assunto
Resultado: Permite filtrar atendimentos por sentimento (positivo, negativo, neutro) e assunto.
Cenário: Canvas que analisa contratosTags configuradas:
  • documento (estática)
  • tipo-$output.tipo_contrato
  • valor-$output.faixa_valor
  • risco-$output.nivel_risco
Resultado: Facilita encontrar contratos por tipo, faixa de valor ou nível de risco.
Cenário: Canvas que qualifica leadsTags configuradas:
  • lead (estática)
  • score-$output.qualificacao
  • origem-$output.canal
  • produto-$output.interesse
Resultado: Permite segmentar leads por qualificação, canal de origem e produto de interesse.

​
Boas Práticas

Faça

  • Use nomes de tags descritivos e padronizados
  • Combine tags estáticas para contexto fixo com tags dinâmicas para dados variáveis
  • Configure o Output Format do seu Canvas para retornar os campos que você quer usar como tags
  • Teste as tags em ambiente de desenvolvimento antes de ir para produção

Evite

  • Criar tags muito longas (limite de 256 caracteres)
  • Usar espaços nos nomes das tags (use hífen ou underscore)
  • Depender de campos que podem não existir na resposta (a tag será ignorada se o campo não existir)
  • Criar muitas tags diferentes que dificultem a organização

​
Comportamento em Casos Especiais

SituaçãoComportamento
Campo não existe na respostaA tag dinâmica é ignorada (não gera erro)
Campo retorna valor vazioA tag é ignorada
Valor muito longo (+256 caracteres)O valor é truncado
Erro ao processar tagA tag é ignorada, outras tags continuam funcionando

​
Perguntas Frequentes

Não. As tags são apenas para organização e rastreamento. Elas não alteram a execução do Canvas.
Não. As tags são registradas no momento da execução e ficam associadas permanentemente àquele registro.
Não há um limite rígido, mas recomendamos usar entre 3 a 10 tags por execução para manter a organização.
Sim, desde que a resposta seja um JSON válido. O sistema consegue navegar por objetos aninhados e arrays.
Não. As tags são combinadas. As tags da API são adicionadas às tags do Canvas, sem substituição.

​
Resumo

RecursoDescrição
Tags EstáticasValores fixos definidos no Canvas
Tags DinâmicasValores extraídos da resposta usando $output.campo
Via APITags adicionais enviadas na requisição
RegistroTodas as tags ficam no Usage do Canvas
UsoFiltrar, organizar e analisar execuções
As tags são uma ferramenta para transformar dados das respostas da IA em informações organizadas e pesquisáveis, facilitando o acompanhamento e análise do uso dos seus Canvas.