Tags do contato

O que é

Tags do contato é a ferramenta nativa manage_tags. Ela permite ao agente listar as tags aplicadas ao contato externo da conversa atual, aplicar uma tag existente, criar e aplicar uma tag nova ou remover uma associação.

As tags formam um catálogo compartilhado pela organização. Uma tag aplicada ao contato pode ser usada pela equipe para filtrar e priorizar atendimentos. A ferramenta não renomeia, recolore nem exclui tags do catálogo.

Tag do contato ou tag da conversa

Use Tags do contato para uma característica da pessoa, como cliente, lead quente ou aguardando pagamento. A associação acompanha o mesmo registro de contato em suas conversas.

Use Tags da conversa para classificar apenas o assunto ou processo daquele atendimento, como negociação ou reembolso. Contatos representados por registros separados não compartilham automaticamente tags, mesmo que sejam da mesma pessoa; primeiro é preciso unificar esses registros.

Veja Tags de Contato para entender catálogo, cores, filtros e unificação. Para tags limitadas à conversa, veja Tags de Conversa.

Antes de conectar

Salve o agente. Em modo de criação, a seção Ferramentas mostra Salve o agente primeiro até existir um agente ao qual conectar a ferramenta.
Tenha permissão de escrita nesse agente (agents.write). A leitura do vínculo usa agents.view.
Escolha um modelo com suporte a ferramentas. Conectar a ferramenta a disponibiliza para o modelo, mas não obriga o modelo a chamá-la.

Conectar ao agente

Abra o agente e entre em Ferramentas.
Selecione Adicionar Ferramenta.
Em Ferramentas Nativas, selecione Tags do contato.

A seleção cria um vínculo ativo imediatamente e volta à lista de ferramentas. Não há formulário nem configuração adicional. Para desconectar, remova Tags do contato da lista do agente.

Orientar o prompt

Na seção Prompt, abra Ferramentas disponíveis, selecione Tags do contato e use a sugestão com {{tool:manage_tags}}. A referência não conecta nem autoriza a ferramenta; ela identifica o contrato técnico no prompt e evita o alerta de ferramenta não referenciada em Insights.

Especifique a condição, o nome canônico da tag e o resultado esperado. Para remover, mande listar antes e confirmar a lista depois. Exemplo:

Quando o cliente pedir uma proposta, use {{tool:manage_tags}} para listar as tags. Se lead quente ainda não estiver aplicada, adicione-a. Quando o pagamento for confirmado, liste novamente, remova aguardando pagamento somente se ela estiver presente, adicione cliente e confira a lista final.

Padronize a grafia no prompt. O catálogo não diferencia maiúsculas de minúsculas para unicidade, portanto Cliente e cliente representam o mesmo nome. Evite criar variantes como lead-quente e lead quente e, enquanto a correspondência literal não estiver corrigida no produto atual, não use % ou _ em nomes enviados à ferramenta.

Ações disponíveis

Ação	Entrada	Resultado
`list`	nenhuma	Retorna as tags aplicadas ao contato atual, com `id`, `name` e `color`.
`add`	`name` obrigatório	Remove espaços nas extremidades, cria a tag no catálogo quando necessário e aplica a associação. Repetir a mesma adição é idempotente.
`remove`	`name` obrigatório	Remove apenas a associação entre a tag e o contato. A tag continua no catálogo da organização.

Ao criar uma tag, o SquadOS escolhe uma cor determinística entre as oito cores do catálogo. O agente recebe o resultado da ação e pode usá-lo para continuar a resposta.

Limites e verificação

É necessário um contato externo. Se a conversa não tiver external_contact_id, como em um contexto interno do Hub, a ferramenta devolve erro e não altera tags.
A associação é do registro de contato. Ela aparece em outras conversas ligadas ao mesmo registro, não em toda identidade ou canal que pareça pertencer à mesma pessoa.
Confirme remoções. No produto atual, remove pode responder sucesso quando a tag existe no catálogo, mas não estava aplicada ao contato. Listar antes e depois impede o agente de afirmar uma mudança que não ocorreu.
Atualize a tela quando outra origem alterar tags. Uma ação do agente pode não atualizar o painel de contato que já está aberto. Troque de conversa ou recarregue antes de tentar corrigir a associação manualmente.
Gerencie o catálogo pela API. O diálogo Gerenciar tags existe no produto, mas não pode ser aberto pela interface atual de Conversas. Use Tags na API para listar, renomear, recolorir ou excluir tags. Excluir do catálogo remove a tag de todos os contatos e não pode ser desfeito.
Teste antes de ligar um canal. Salve o prompt e use Testar Agente com casos de adição, repetição e remoção. O teste usa a ferramenta real, persiste mudanças e pode consumir créditos.