> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tela.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tags

> Categorize e organize as execuções do seu Canvas com etiquetas estáticas ou dinâmicas baseadas nas respostas da IA

## 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:

| Tipo               | Descrição                                           | Exemplo                                   |
| ------------------ | --------------------------------------------------- | ----------------------------------------- |
| **Tags Estáticas** | Valores fixos definidos por você                    | `atendimento`, `urgente`, `cliente-vip`   |
| **Tags Dinâmicas** | Valores 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:

```json theme={null}
{
    "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.

<Frame>
  <img src="https://mintcdn.com/meistrari/p1ep1dn0vOxriVI1/images/canvas-custom-tags-menu.png?fit=max&auto=format&n=p1ep1dn0vOxriVI1&q=85&s=46ac7a62397a314725a7ce4eac4bcdc6" alt="Menu de Tags Personalizadas nas configurações do Canvas" width="1440" height="454" data-path="images/canvas-custom-tags-menu.png" />
</Frame>

### Passo 2: Adicione suas tags

Você pode adicionar dois tipos de tags:

<Frame>
  <img src="https://mintcdn.com/meistrari/p1ep1dn0vOxriVI1/images/custom-tags-modal.png?fit=max&auto=format&n=p1ep1dn0vOxriVI1&q=85&s=e19288d19c6d25dccb33ef652b71f917" alt="Modal de Tags Personalizadas" width="1014" height="808" data-path="images/custom-tags-modal.png" />
</Frame>

<Tabs>
  <Tab title="Tags Estáticas">
    Digite o nome da tag diretamente:

    ```
    minha-tag
    categoria-fixa
    processo-automatico
    ```
  </Tab>

  <Tab title="Tags Dinâmicas">
    Use o prefixo `$output.` seguido do caminho do valor na resposta:

    ```
    $output.tipo
    $output.dados.categoria
    $output.resultado.status
    ```
  </Tab>
</Tabs>

### 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

```json theme={null}
{
    "messages": [...],
    "tags": [
        "origem-api",
        "cliente-123",
        "tipo-$output.categoria"
    ]
}
```

### Como funciona a combinação

| Origem              | Tags                                                            |
| ------------------- | --------------------------------------------------------------- |
| Canvas              | `processo-automatico`, `$output.status`                         |
| API                 | `origem-api`, `cliente-123`                                     |
| **Resultado Final** | `processo-automatico`, `concluido`, `origem-api`, `cliente-123` |

<Note>
  Se a mesma tag aparecer tanto no Canvas quanto na API, ela será registrada apenas uma vez (sem duplicação).
</Note>

## 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

<AccordionGroup>
  <Accordion title="Classificação de Atendimentos">
    **Cenário:** Canvas que analisa mensagens de clientes

    **Tags configuradas:**

    * `atendimento` (estática)
    * `sentimento-$output.sentimento`
    * `assunto-$output.assunto`

    **Resultado:** Permite filtrar atendimentos por sentimento (positivo, negativo, neutro) e assunto.
  </Accordion>

  <Accordion title="Processamento de Documentos">
    **Cenário:** Canvas que analisa contratos

    **Tags 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.
  </Accordion>

  <Accordion title="Análise de Leads">
    **Cenário:** Canvas que qualifica leads

    **Tags 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.
  </Accordion>
</AccordionGroup>

## Boas Práticas

<CardGroup cols={2}>
  <Card title="Faça" icon="check" color="#22c55e">
    * 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
  </Card>

  <Card title="Evite" icon="xmark" color="#ef4444">
    * 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
  </Card>
</CardGroup>

## Comportamento em Casos Especiais

| Situação                            | Comportamento                                       |
| ----------------------------------- | --------------------------------------------------- |
| Campo não existe na resposta        | A tag dinâmica é ignorada (não gera erro)           |
| Campo retorna valor vazio           | A tag é ignorada                                    |
| Valor muito longo (+256 caracteres) | O valor é truncado                                  |
| Erro ao processar tag               | A tag é ignorada, outras tags continuam funcionando |

## Perguntas Frequentes

<AccordionGroup>
  <Accordion title="As tags afetam o funcionamento do Canvas?">
    Não. As tags são apenas para organização e rastreamento. Elas não alteram a execução do Canvas.
  </Accordion>

  <Accordion title="Posso alterar as tags de uma execução já realizada?">
    Não. As tags são registradas no momento da execução e ficam associadas permanentemente àquele registro.
  </Accordion>

  <Accordion title="Existe limite de quantidade de tags?">
    Não há um limite rígido, mas recomendamos usar entre 3 a 10 tags por execução para manter a organização.
  </Accordion>

  <Accordion title="Tags dinâmicas funcionam com qualquer formato de resposta?">
    Sim, desde que a resposta seja um JSON válido. O sistema consegue navegar por objetos aninhados e arrays.
  </Accordion>

  <Accordion title="As tags enviadas via API substituem as do Canvas?">
    Não. As tags são combinadas. As tags da API são adicionadas às tags do Canvas, sem substituição.
  </Accordion>
</AccordionGroup>

## Resumo

| Recurso            | Descrição                                            |
| ------------------ | ---------------------------------------------------- |
| **Tags Estáticas** | Valores fixos definidos no Canvas                    |
| **Tags Dinâmicas** | Valores extraídos da resposta usando `$output.campo` |
| **Via API**        | Tags adicionais enviadas na requisição               |
| **Registro**       | Todas as tags ficam no Usage do Canvas               |
| **Uso**            | Filtrar, 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.