> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fire.rest/llms.txt
> Use this file to discover all available pages before exploring further.
# Agente de catálogo
> Um chat com inteligência artificial que propõe etiquetas para seus produtos e não toca em nenhuma até você aprovar a mudança.
Chega uma campanha nova e é preciso etiquetar quarenta produtos com `campaign=SEMANA_PICANTE` antes do lançamento, espalhados entre vários países. Fazer isso produto por produto na tela de **Products** é lento, e a inconsistência sai cara: alguém digita `picante` em um produto e `Picante` em outro, e o filtro que a campanha usa deixa metade de fora.
O **Agente de catálogo** existe para isso. Você conversa com ele ou envia um arquivo, ele mostra exatamente qual etiqueta vai mudar em cada produto, e não toca em nada até você aprovar. Está disponível pelo botão flutuante 🤖 no canto inferior direito, em qualquer tela do backoffice.
***
## O mínimo que você precisa saber
**1. Precisa de conta, país e vendor selecionados no seletor de contexto.** Sem os três, o painel não abre: não há como propor uma etiqueta sem saber sobre qual catálogo.
**2. O agente propõe, nunca aplica sozinho.** Enquanto o cartão da proposta disser **Pending approval**, nenhum produto mudou. Aplicar é um clique seu.
**3. Não existe um modo que apague por ausência.** Um produto que não aparece no seu arquivo não perde nenhuma etiqueta, seja qual for o modo escolhido.
**4. Um termo novo ou um alias sempre são perguntados a você.** O agente não adivinha se `picante` e `Picante` são a mesma coisa, nem traduz ou embeleza um valor que não conhece. Essa decisão é sua.
***
## O caminho simples
Para um ajuste pontual em poucos produtos:
1. Abra o botão flutuante 🤖.
2. Conte ao agente o que você quer mudar, com nomes ou códigos de produto.
3. Revise a proposta: qual produto, qual etiqueta, qual valor.
4. **Approve and apply**.
Se o seu caso é esse — poucos produtos, uma mudança pontual, você conversa e aprova — pronto. O resto deste manual cobre cargas em massa por arquivo e as decisões que o agente vai te pedir pelo caminho.
***
## Duas formas de usar
### Conversando
Para ajustes pontuais em poucos produtos. Ao abrir o painel sem nada selecionado, o agente oferece dois atalhos para começar: **Show me the current tag vocabulary** e **Help me prepare a bulk tag upload**.
Cada resposta traz embaixo os passos que o agente seguiu para chegar até ela, como chips de ferramenta (`MCP · tags context`, `MCP · products search`). Não é preciso entendê-los para usar o agente: eles estão ali para que você possa confiar na resposta sem precisar aceitá-la de olhos fechados.
### Com um arquivo
Para carga em massa. Anexe um CSV, JSON ou Excel pelo campo de mensagem do painel, e diga ao agente o que fazer com ele.
**Limites do arquivo:** 5 MB, 5.000 linhas e 100 colunas. Um arquivo que passa de qualquer um dos três não é processado.
***
## As decisões que o agente vai te perguntar
### Modo: adicionar ou substituir
| Modo | O que faz |
| - | - |
| **Add values** | Soma os valores do arquivo às etiquetas de cada produto. Nunca remove nada, nem dessas etiquetas nem de outras que o produto já tinha. |
| **Replace mentioned keys** | Substitui o valor das etiquetas que o arquivo nomeia. As etiquetas que o arquivo não menciona ficam exatamente como estavam. |
**Não existe um modo que apague por ausência.** Um produto que não está no arquivo não perde nada, em nenhum dos dois modos. Para esvaziar uma etiqueta é preciso nomeá-la explicitamente no arquivo com **Replace mentioned keys**.
### Termos novos
Se um valor do arquivo não existe no vocabulário aprovado, o agente não traduz nem embeleza: mostra exatamente como veio escrito no arquivo, e pergunta se você aprova como termo novo.
### Alias
Que um valor do arquivo signifique na verdade um que já está aprovado — por exemplo, que o `Picante` do arquivo seja o mesmo `picante` do vocabulário — é uma decisão sua. O agente nunca assume isso por semelhança: dois valores escritos de forma diferente ficam como dois valores distintos até você decidir que são alias.
***
## A proposta: nada muda até você aprovar
Antes de mudar qualquer produto, o agente monta uma proposta com o detalhe de cada mudança e a deixa esperando sua decisão.
**A regra que organiza tudo: enquanto o cartão disser "Pending approval", nenhum produto foi tocado.** O agente propõe; aplicar a mudança é o seu clique em **Approve and apply**. Você pode fechar o painel, pensar com calma, ou **Decline** sem que nada no catálogo tenha mudado.
Expandindo **Product changes** você vê o detalhe linha por linha, com o status de cada uma e os problemas que o agente encontrou, se houver.
### Os problemas que ele pode reportar, e que nunca adivinha
| Problema | O que significa | O que fazer |
| - | - | - |
| **Ambíguo** | O identificador da linha coincide com mais de um produto. | Precisar o identificador ou o código exato no arquivo. |
| **Não encontrado** | Nenhum produto tem esse identificador. | Verificar se o código está escrito certo e pertence a esta conta, país e vendor. |
| **Fora do vocabulário** | O valor não está entre os aprovados e ainda não foi aprovado como termo novo. | Decidir se é um termo novo ou um alias de um que já existe. |
| **Linha inválida** | A linha não pode ser lida: faltam colunas ou o formato está quebrado. | Corrigir a linha no arquivo original e enviar de novo. |
Nenhum desses casos é resolvido pelo agente por conta própria. Ele os deixa na proposta para você decidir.
***
## O que acontece ao aprovar: os três finais possíveis
Ao clicar em **Approve and apply** pode acontecer uma de três coisas:
* **Aplicado a todos.** Cada produto da proposta ficou com a etiqueta que você viu. O agente deixa o link para cada um.
* **Aplicado parcialmente.** Alguém editou um desses produtos enquanto você revisava a proposta, então esse não mudou e os demais sim.
* **Nada aplicado.** O mesmo motivo, mas para todos os produtos da proposta.
**Isto não é um erro: é a proteção.** A aprovação vale para o diff que você viu, não para um que mudou por baixo enquanto você pensava. Se alguém mexeu no produto entre a montagem da proposta e sua aprovação, o sistema prefere avisar em vez de sobrescrever essa mudança às cegas. A solução é simples: envie o arquivo de novo ou repita o pedido, e o agente monta a proposta novamente com o estado atual do produto.
***
## O histórico de conversas
O ícone do relógio abre **Conversation history**, com cada pedido anterior e sua data. Serve para voltar a uma proposta que você não chegou a aprovar, ou para lembrar o que foi pedido ao agente na semana passada.
***
## Receitas: como os casos reais são resolvidos
1. Abra o botão flutuante 🤖.
2. Digite algo como: "Adicione `campaign=SEMANA_PICANTE` aos produtos P-084, P-086 e P-087".
3. Revise a proposta: três produtos, um valor cada.
4. **Approve and apply**.
Para um punhado de produtos não é preciso montar nenhum arquivo.
1. Anexe o CSV com a coluna de identificador e a etiqueta a mudar.
2. Peça o modo **Add values**, para não arriscar nenhuma etiqueta existente.
3. Confira os contadores da proposta: quantas linhas ficaram prontas, quantas não foram encontradas.
4. Resolva os problemas sinalizados, se houver, e **Approve and apply**.
Os produtos que não estão no arquivo não são tocados.
1. Monte o arquivo com o identificador de cada produto e o valor correto da etiqueta.
2. Peça o modo **Replace mentioned keys**, nomeando só essa etiqueta.
3. Revise a proposta: o valor antigo desaparece, o novo o substitui. O resto das etiquetas do produto fica igual.
4. **Approve and apply**.
1. Envie o arquivo e deixe o agente processá-lo.
2. Quando ele mostrar o termo novo, confira se está escrito como você quer ver no catálogo: é aprovado exatamente como vem, sem tradução nem correção.
3. Aprove como termo novo.
4. **Approve and apply**.
Se o valor tiver um erro de digitação, corrija no arquivo antes de aprovar: uma vez aceito como termo novo, ele fica no vocabulário com essa grafia.
1. Quando o agente marcar o valor como fora do vocabulário, diga explicitamente que é um alias do valor existente.
2. Confirme qual dos dois nomes fica como o aprovado.
3. **Approve and apply**.
O agente nunca une os dois valores sozinho, por mais parecidos que sejam — precisa dessa confirmação.
1. Você aprova a proposta e o resultado diz **Partially applied** ou **Nothing applied**.
2. Verifique qual produto mudou nesse meio-tempo — a mensagem do agente indica.
3. Envie o mesmo arquivo de novo, ou repita o pedido por conversa.
4. O agente monta uma proposta nova com o estado atual do produto, e você aprova de novo.
Não é preciso procurar o que deu errado no produto: repetir o pedido basta.
***
## Um exemplo com números
Um arquivo `etiquetas-manual.csv` com quatro linhas, no modo **Add values**, adicionando `preparacao` a cada produto:
| externalId | Antes | Depois | Resultado |
| - | - | - | - |
| 822 | sem `preparacao` | `preparacao=grelhado` | Aplicado |
| 848 | sem `preparacao` | `preparacao=grelhado` | Aplicado |
| 91184 | sem `preparacao` | `preparacao=frito` | Aplicado |
| PRD-NAO-EXISTE-0000 | — | — | Não encontrado |
Três produtos ficam prontos (`productsReady: 3`) e uma linha fica marcada como não encontrada (`notFound: 1`) porque esse código não existe nesta conta. `grelhado` e `frito` são aprovados como termos novos porque não estavam antes no vocabulário.
***
## Erros que saem caros
**Confundir o agente com uma ferramenta de menu ou de preços.** O Agente de catálogo só muda etiquetas de produto. Ele não sincroniza nada com os canais de venda por conta própria.
**Achar que "Pending approval" já foi aplicado.** Nada mudou ainda. Se você fechar o painel sem clicar em **Approve and apply**, a proposta fica ali, sem efeito sobre o catálogo.
**Presumir que o agente une valores parecidos por conta própria.** `Picante` e `picante` ficam como dois valores distintos até você marcar explicitamente que são alias. Sem isso, você acaba com um termo novo redundante no vocabulário.
**Aprovar uma proposta antiga depois de editar produtos manualmente.** O resultado pode sair parcial, ou nada ser aplicado. É a proteção funcionando, não um erro: envie o arquivo de novo para que a proposta seja montada com o estado atual.
**Enviar um arquivo esperando que o tamanho não importe.** Acima de 5 MB, 5.000 linhas ou 100 colunas, o arquivo não é processado. Divida-o em partes menores.
***
## Glossário
| Termo | O que significa |
| - | - |
| **Agente de catálogo** | O chat com inteligência artificial que propõe etiquetas de produto e as aplica só com aprovação. |
| **Vocabulário aprovado** | O conjunto de etiquetas (keys e valores) que já existem no catálogo. |
| **Termo novo** | Um valor que não está no vocabulário aprovado. Aprovado com o texto exatamente como vem no arquivo. |
| **Alias** | Um valor do arquivo que na verdade significa um valor já aprovado. Exige decisão explícita. |
| **Add values** | Modo que soma valores novos às etiquetas do produto, sem remover nada. |
| **Replace mentioned keys** | Modo que substitui o valor das etiquetas que o arquivo nomeia; o resto fica igual. |
| **Proposta** | O detalhe das mudanças que o agente preparou, antes de serem aplicadas. |
| **Pending approval** | Status de uma proposta que ainda não foi aprovada. Nenhum produto mudou. |
| **Approve and apply** | A ação que aplica a proposta aos produtos. |
| **Ambíguo** | Problema: o identificador de uma linha coincide com mais de um produto. |
| **Não encontrado** | Problema: nenhum produto tem o identificador da linha. |
| **Fora do vocabulário** | Problema: o valor não está entre os aprovados e não foi decidido se é termo novo ou alias. |
| **Linha inválida** | Problema: a linha não pode ser lida. |
| **Contexto** | A conta, o país e o vendor escolhidos no seletor acima. O agente precisa dos três completos para começar. |
***
## Perguntas frequentes
Não. Enquanto a proposta disser **Pending approval**, nenhum produto mudou. Aplicar é sempre um clique em **Approve and apply**.
O painel não abre. O agente precisa saber sobre qual catálogo está trabalhando antes de propor qualquer coisa, então faltando qualquer um dos três não há proposta possível.
Não. Não existe um modo que apague por ausência. Um produto ausente do arquivo não perde nenhuma etiqueta, seja qual for o modo escolhido entre **Add values** e **Replace mentioned keys**.
Ele não decide: mostra o valor exatamente como está escrito no arquivo e pergunta se você aprova como termo novo. Nunca traduz nem corrige por conta própria.
Não. Se um valor é alias de um já aprovado é uma decisão explícita sua. Dois valores escritos de forma diferente ficam separados até você confirmar que são o mesmo.
Alguém editou um desses produtos enquanto você revisava a proposta, então essa mudança não foi aplicada para te proteger de sobrescrever uma edição que você não viu. Envie o arquivo de novo ou repita o pedido: o agente monta a proposta de novo a partir do estado atual.
Não. Ele só muda as etiquetas do produto. Não modifica menus nem preços, e não dispara nenhuma publicação para os canais de venda.
Em **Conversation history**, o ícone do relógio acima do painel. Todos os pedidos anteriores estão ali, com sua data.
***
## Alcance: o que o agente não faz
O Agente de catálogo **só** muda as etiquetas do produto. Não mexe em menus, não mexe em preços, e não dispara sincronização com os canais de venda. Se a mudança que você precisa é outra — uma tabela de preços, um menu, a disponibilidade em um canal — esta tela não é a ferramenta.