{"section":"tutorials","requestedLocale":"pt","requestedSlug":"agente-de-colecoes","locale":"pt","slug":"agente-de-colecoes","path":"docs/pt/tutorials/beta/catálogo-beta/agente-de-colecoes.md","branch":"main","content":"> ℹ️ O **Agente de Coleções** está em fase beta, o que significa que estamos trabalhando para aprimorá-lo. Atualmente, a disponibilidade é somente para contas selecionadas. Em caso de dúvidas, entre em contato com nosso [Suporte](https://supporticket.vtex.com/support).\n\nO **Agente de Coleções** é um agente de inteligência artificial que permite criar e gerenciar coleções e sortimentos por meio de uma experiência conversacional no Admin VTEX. Este artigo explica o funcionamento do agente e apresenta quais ações em coleções e sortimentos você pode realizar de forma conversacional.\n\nA [coleção](https://help.vtex.com/pt/docs/tutorials/tipos-de-colecao) é o agrupamento de produtos, enquanto o sortimento é a entidade que agrupa coleções em cenários que utilizam [B2B Buyer Portal](https://help.vtex.com/pt/docs/tutorials/b2b-buyer-portal-pt). Com o **Agente de Coleções**, você fornece uma instrução (prompt) em linguagem natural por meio de uma interface conversacional e o agente operacionaliza isso em uma coleção ou sortimento.\n\n> ⚠️ Atualmente, o sortimento é um recurso exclusivo para lojas que utilizam [B2B Buyer Portal](https://help.vtex.com/pt/docs/tutorials/b2b-buyer-portal-pt).\n\n## Diferença entre o agente e a interface legada\n\nAlém de permitir realizar tudo o que era feito pela [interface legada](https://help.vtex.com/pt/docs/tutorials/criando-colecao-de-produtos), o **Agente de Coleções** oferece outras vantagens:\n\n- Uma experiência conversacional intuitiva.\n- A possibilidade de criar e gerenciar sortimentos\n- A opção de gerenciar coleções usando como critério especificações de produto e especificações de SKU.\n\n> ℹ️ O **Agente de Coleções** não permite alterar diretamente a ordem dos produtos via chat. Para reordená-los, é necessário enviar ao agente uma planilha atualizada com os itens na ordem desejada e no formato `.xls` ou `.xlsx`. Esta opção de ordenação está disponível apenas para coleções estáticas.\n\n## Avisos da fase beta\n\nO **Agente de Coleções** está em beta, e durante este período a funcionalidade tem as seguintes características:\n\n- **Escopo:** inclui, para coleções e sortimentos, as ações de criação, edição, importação/exportação em massa e visualização do plano criado pelo agente antes da confirmação do usuário.\n- **Sortimento restrito:** a criação e o uso de sortimentos estão disponíveis apenas para lojas que utilizam **B2B Buyer Portal**.\n- **Coleção ou sortimento por vez:** o agente atua sobre uma única coleção ou sortimento em cada operação de visualização, criação ou edição.\n- **Tempo de propagação:** uma coleção não fica visível imediatamente após a criação ou edição. O agente informa que a indexação está em andamento e que a propagação dos dados leva cerca de uma hora até que a coleção fique disponível para consulta.\n- **Verificação de pertencimento após a criação:** confirmar se um produto específico faz parte de uma coleção é confiável apenas após a criação e a indexação. Verificações de pertencimento antes da criação estão fora do escopo neste momento.\n\n> ℹ️ As instruções apresentadas sobre coleções e sortimentos são apenas exemplos e não a única forma de interagir com o agente.\n\n## Pré-requisitos\n\nAlém de usar o [B2B Buyer Portal](https://help.vtex.com/pt/docs/tutorials/b2b-buyer-portal-pt), como o **Agente de Coleções** atua sobre coleções e sortimentos, é necessário que a loja tenha cadastrado [marcas](https://help.vtex.com/pt/docs/tutorials/o-que-e-uma-marca), [categorias](https://help.vtex.com/pt/docs/tutorials/cadastrar-uma-categoria), [produtos](https://help.vtex.com/pt/docs/tutorials/adicionar-ou-editar-produto) e [SKUs](https://help.vtex.com/pt/docs/tutorials/adicionar-ou-editar-sku), já que é sobre esses itens que as regras de criação são aplicadas.\n\n## Acessar o agente\n\nNo Admin VTEX, acesse **Catálogo > Agente de Coleções** ou digite **Agente de Coleções** na barra de pesquisa no topo da página. A interface apresentada é composta por uma janela conversacional e uma sugestão de instrução (prompt), como mostra a imagem a seguir:\n\n![collections_agent_interface_pt](https://cdn.statically.io/gh/vtexdocs/help-center-content/refs/heads/main/docs/pt/tutorials/beta/catálogo-beta/collections_agent_interface_pt.png)\n\nAo clicar na sugestão `Crie uma coleção`, ou digitar outra instrução na janela de conversa, o agente inicia o atendimento e conduz a interação até a conclusão da ação desejada.\n\n## Regras do funcionamento\n\nO **Agente de Coleções** opera a partir das seguintes regras:\n\n- **Criação estática ou dinâmica:** cria e edita coleções de forma estática (lista explícita de IDs de produto, de SKUs ou códigos de referência) ou dinâmica (critérios como marcas, categorias, especificações de produto e especificações de SKU).\n- **Regras inclusivas e exclusivas:** combina e exclui coleções por meio de regras inclusivas e exclusivas. As regras exclusivas sempre prevalecem sobre as inclusivas.\n- **Combinações complexas E/OU:** suporta combinações lógicas complexas entre critérios e regras. Você não precisa montar as subcoleções manualmente — o agente apresenta a estrutura lógica final para aprovação.\n- **Propagação automática:** uma mesma coleção pode ser consumida por vários sortimentos. Ao editar uma coleção compartilhada, a alteração é propagada automaticamente para todos os sortimentos que a consomem. Esse é o principal valor do modelo de blocos reutilizáveis.\n- **Ajuste incremental:** o agente adiciona ao que já foi definido em vez de substituir, e entende modificadores relativos como \"desfaça isso\" ou \"troque X por Y\".\n- **Desambiguação conversacional:** quando uma instrução é vaga ou corresponde a mais de uma entidade do catálogo, o agente pausa e apresenta opções em vez de adivinhar.\n- **Confirmação antes de mudanças de alto impacto:** antes de alterações relevantes (por exemplo, editar uma coleção compartilhada por muitos sortimentos), o agente mostra o alcance da mudança e solicita a confirmação do usuário.\n\n## Realizar ações em coleções\n\n> ⚠️ Os exemplos de instruções apresentados a seguir são apenas para fins ilustrativos e não são a única forma de o agente executar uma ação.\n\nVocê pode realizar as seguintes ações:\n\n- Criar coleção usando linguagem natural\n  - Revisar o plano de coleção\n  - Aprovar o plano de coleção\n- Criar coleção por meio de importação de planilha\n- Verificar as relações em coleções\n- Editar e refinar a coleção\n- Buscar, listar e filtrar coleções\n\n### Criar coleção usando linguagem natural\n\nPara criar uma coleção usando linguagem natural, digite na janela de conversa as instruções (prompt) para a criação da coleção com os produtos que deseja reunir. Alguns exemplos de instruções são:\n\n- \"Crie uma coleção com todos os produtos da marca Infotech.\"\n- \"Crie uma coleção com os produtos das categorias Eletrônicos e Informática, exceto os da marca Infotech.\"\n- \"Crie uma coleção com todos os produtos da categoria Verão que têm a especificação Cor igual a Azul.\"\n\nVocê pode usar uma instrução mais completa, como: \"crie uma coleção com os produtos das categorias Eletrônicos e Informática que tenham a especificação Cor igual a Preto, exceto os da marca Infotech.\"\n\nApós inserir as instruções no chat, aperte `Enter` ou clique no botão de seta para cima no chat. O **Agente de Coleções** vai então interpretar a solicitação e montar a coleção com os critérios e as regras correspondentes. Ao terminar o processamento, o agente pode solicitar informações complementares.\n\n**Exemplo:** o agente recebeu o comando \"Monte uma coleção com todos os produtos da categoria de ID 6\". Após o processamento, ele pode solicitar um nome e uma descrição para a coleção, e uma vez que o nome e a descrição forem informados, o agente apresenta um plano do que será feito.\n\n#### Revisar o plano de coleção\n\nO plano de coleção apresentado pelo agente é um resumo que você deve revisar antes de confirmar a operação. Neste plano, existem informações como:\n\n- Nome da coleção sendo criada\n- Descrição da coleção\n- [Regra de criação](#regras-do-funcionamento) a ser utilizada\n- Comportamento futuro para a inclusão de produtos na coleção\n\n#### Aprovar o plano de coleção\n\nDepois de revisar o plano, confirme a operação para que o agente aplique as mudanças. Feito isso, o agente finaliza o processamento e informa, por exemplo:\n\n- O status da operação (sucesso ou erro).\n- O ID da nova coleção.\n- O nome da coleção (caso não tenha sido informado pelo usuário).\n\n> ❗ A propagação dos dados pode levar cerca de uma hora para se refletir no Admin VTEX, mas reflete em alguns minutos na navegação.\n\n### Criar coleção por meio de importação de planilha\n\nVocê pode montar uma nova coleção pela importação de dados via planilha em formato `.csv` ou `.xlsx`. A planilha deve conter uma lista de itens com as seguintes colunas de identificação:\n\n| Coluna da planilha | Descrição |\n| :--- | :--- |\n| Product ID | Código numérico identificador do produto. |\n| Product Reference ID | Código de referência do produto. |\n| SKU ID | Código numérico identificador do SKU. |\n| SKU Reference ID | Código de referência do SKU. |\n\nPara importar a planilha, realize os seguintes passos:\n\n1. Clique no botão de clipe no chat do **Agente de Coleções** para anexar a planilha.\n2. Selecione localmente a planilha em formato `.csv` ou `.xlsx`.\n3. Clique em `Abrir`.\n\nSiga os mesmos passos da criação de coleção via linguagem natural para revisar e aprovar o plano de coleção. O plano é atualizado a cada nova instrução, e você aprova a estrutura final sem precisar montar a lógica interna de subcoleções. As instruções possíveis são:\n\n- **Adicionar** itens à lista existente.\n- **Remover** itens da lista existente.\n- **Substituir** toda a lista.\n\n> ⚠️ A importação nunca é interrompida por falhas em linhas individuais: o agente processa a planilha inteira, seguindo estas regras:\n>\n> - Linhas com IDs encontrados são importadas e registradas.\n> - Linhas com IDs não encontrados são ignoradas, registradas e apresentadas para que você possa corrigi-las (por exemplo, \"Linha 5: SKU '362' não encontrado\").\n> - IDs duplicados são ignorados nas linhas seguintes.\n\n### Verificar as relações em coleções\n\nO **Agente de Coleções** pode ser usado para consultar as relações de pertencimento ou ausência de produtos em uma coleção. Você pode, por exemplo, perguntar pelo chat por que um produto foi incluído em uma coleção ou excluído dela, e o agente explicará o critério ou regra que levou àquela decisão. Exemplo de instrução: \"Por que o produto de ID 74 está na coleção Moda Praia?\".\n\n### Editar e refinar a coleção\n\nEm uma conversa contínua, o **Agente de Coleções** não substitui o estado atual do rascunho, mas sim adiciona as novas instruções ao que já foi definido. Ou seja, você não precisa começar do zero para ajustar uma coleção. O agente entende modificadores relativos como \"desfaça isso\" ou \"troque a marca X pela marca Y\", e o plano de coleção é atualizado a cada interação.\n\nO refinamento de coleções a partir de novas instruções vale tanto para uma coleção sendo montada quanto para uma coleção que já foi criada.\n\n> ℹ️ O **Agente de Coleções** checa o impacto da edição. Ou seja, antes de aplicar alterações de alto impacto, como editar uma coleção compartilhada por vários sortimentos, o agente mostra quais coleções e sortimentos serão afetados e solicita sua confirmação antes de executar.\n\n### Buscar, filtrar e listar coleções\n\nPara localizar e gerenciar a coleção certa, você pode buscá-la por **nome** ou **ID** e ordenar ou filtrar a lista por atributos comuns, como data de criação, nome e ID. Ao abrir uma coleção, é possível visualizar sua definição.\n\n## Realizar ações em sortimentos\n\nVocê pode realizar as seguintes ações:\n\n- Criar um sortimento com linguagem natural\n- Visualizar o resultado\n- Verificar as relações em sortimentos\n- Aprovar o plano de sortimento\n- Editar e refinar o sortimento\n- Buscar, listar e filtrar sortimentos\n\n> ⚠️ Atualmente, o sortimento é um recurso exclusivo para lojas que utilizam **B2B Buyer Portal**.\n\n### Criar um sortimento com linguagem natural\n\nUm sortimento é composto a partir de coleções, com regras inclusivas e exclusivas. Descreva na conversa o conjunto final de produtos que deseja e o agente monta o sortimento correspondente. Exemplos de instruções:\n\n- \"Crie um sortimento que inclua as coleções Eletrônicos e Acessórios, mas exclua a coleção Produtos Apple.\"\n- \"Use as coleções 2 e 3, mas exclua a coleção 4.\"\n\n### Visualizar o resultado\n\nAntes de confirmar, o agente apresenta o plano do sortimento, com um resumo das coleções incluídas e excluídas e da lógica aplicada. O plano é atualizado a cada instrução, e o agente atua sobre um sortimento por vez.\n\n### Verificar as relações em sortimentos\n\nO **Agente de Coleções** pode ser usado para consultar as relações entre coleções e sortimentos, e é possível fazer isso de três formas distintas:\n\n- Listando todas as coleções relacionadas a um sortimento, agrupadas por incluídas e excluídas.\n- Listando todos os sortimentos que consomem uma determinada coleção, agrupados por incluídos e excluídos.\n- Perguntando o motivo de a coleção estar ou não em um sortimento, e o agente explica qual critério ou regra levou àquela decisão. Exemplo de instrução: \"Por que a coleção de ID 463 está no sortimento Filial Norte?\".\n\n### Aprovar o plano de sortimento\n\nApós revisar o plano, confirme a operação para que o agente aplique as mudanças no sortimento.\n\n### Editar e refinar o sortimento\n\nAssim como nas coleções, você pode ajustar um sortimento sem começar do zero. Em uma conversa contínua, o agente adiciona as novas instruções ao rascunho atual em vez de substituí-lo e entende comandos como \"desfaça isso\" ou \"troque a coleção X pela coleção Y\". O refinamento vale tanto para sortimentos já criados quanto para o sortimento em construção.\n\n> ❗ Como uma coleção pode ser consumida por vários sortimentos, editá-la pode afetar todos eles. Antes de mudanças de alto impacto, o agente mostra quais coleções e sortimentos serão afetados e pede confirmação antes de executar.\n\n### Buscar, listar e filtrar sortimentos\n\nPara localizar e gerenciar o sortimento desejado, você pode buscá-lo por nome ou ID, e ordenar ou filtrar a lista por atributos comuns:\n\n- Data de criação do sortimento\n- Nome do sortimento\n- ID do sortimento\n\n## Incluir todos os produtos do catálogo em uma coleção\n\nNão existe, atualmente, uma forma automática de incluir todos os produtos do catálogo em uma coleção de modo que ela se mantenha sincronizada. É possível incluir todos os produtos usando as regras dinâmicas existentes, mas cada uma tem suas limitações:\n\n- **Por categorias:** ao selecionar todas as categorias do catálogo, como todo produto precisa ter uma categoria, todos os produtos são incluídos.\n- **Por marcas:** ao selecionar todas as marcas, como todo produto precisa ter uma marca, todos os produtos são incluídos.\n- **Por especificação de produto:** ao selecionar uma especificação com o mesmo valor presente em todos os produtos. A especificação precisa estar ativa e ser do tipo combo (seleção múltipla) ou rádio (seleção única), pois o tipo texto não é suportado.\n\nPontos de atenção comuns a essas opções:\n\n- Categorias, marcas ou especificações **inativas** entram na coleção, mas seus produtos não aparecem na navegação enquanto estiverem inativos. Se forem ativadas depois, os produtos passam a aparecer (regra do [Intelligent Search](https://help.vtex.com/pt/docs/tutorials/intelligent-search-visao-geral)).\n- Se uma categoria, marca ou especificação for **desativada** após a criação da coleção, seus produtos permanecem na coleção, mas deixam de aparecer na navegação (regra do **Intelligent Search**).\n- Categorias e marcas **criadas após** a coleção não são incluídas automaticamente.\n- Uma categoria, marca ou especificação **removida** do catálogo após a criação da coleção retira seus produtos da coleção.\n- No caso da especificação de produto, produtos sem a especificação, com o valor em branco ou com valor diferente ficam de fora.\n\nNenhuma dessas opções é um espelho permanente do catálogo: o que compõe \"todos os produtos\" hoje pode mudar conforme o catálogo evolui, e nenhum dos caminhos se atualiza sozinho para capturar o que for criado depois. Independentemente da opção escolhida, um plano com a estrutura proposta é gerado para aprovação antes de qualquer alteração ser aplicada."}