{"section":"tutorials","requestedLocale":"en","requestedSlug":"collections-agent","locale":"en","slug":"collections-agent","path":"docs/en/tutorials/beta/catalog-beta/collections-agent.md","branch":"main","content":"> ℹ️ The **Collections Agent** is currently in beta, which means we're working on improving it. Availability is currently limited to selected accounts. If you have any questions, contact [our Support team](https://supporticket.vtex.com/support).\n\nThe **Collections Agent** is an artificial intelligence agent that allows you to create and manage collections and assortments through a conversational experience in the VTEX Admin. This article explains how the agent works and shows which actions you can take on collections and assortments conversationally.\n\nA [collection](https://help.vtex.com/docs/tutorials/collection-types) is a grouping of products, while an assortment is the entity that groups collections in scenarios that use [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal). With **Collections Agent**, you provide an instruction (prompt) in natural language through a conversational interface, and the agent turns it into a collection or assortment.\n\n> ⚠️ Assortments are currently available only to stores using the [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal).\n\n## Difference between the agent and the legacy interface\n\nIn addition to all [legacy interface](https://help.vtex.com/docs/tutorials/creating-a-product-collection) features, the **Collections Agent** offers other advantages:\n\n- An intuitive conversational experience\n- The ability to create and manage assortments\n- The option to manage collections using product specifications and SKU specifications as criteria\n\n> ℹ️ The **Collections Agent** doesn't allow you to directly change the order of products via chat. To reorder them, upload an updated spreadsheet to the agent with the items in the desired order and in `.xls` or `.xlsx` format. This sorting option is only available for static collections.\n\n## Beta phase notices\n\nThe **Collections Agent** is in beta. During this phase, the feature has the following characteristics:\n\n- **Scope:** For collections and assortments, includes creation, editing, bulk import/export, and viewing the plan created by the agent before user confirmation.\n- **Restricted assortment:** Creating and using assortments is only available for stores that use the **B2B Buyer Portal**.\n- **One collection or assortment at a time:** The agent works on a single collection or assortment in each view, creation, or editing operation.\n- **Propagation time:** A collection isn't immediately visible after creation or editing. The agent informs you that indexing is in progress and that data propagation takes about an hour before the collection becomes available for querying.\n- **Membership verification after creation:** Confirming whether a specific product belongs to a collection is only reliable once the product has been created and indexed. Membership verification before creation is out of scope at this time.\n\n> ℹ️ The instructions shown for collections and assortments are examples only and aren't the only way to interact with the agent.\n\n## Prerequisites\n\nIn addition to using the [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), as the **Collections Agent** works on collections and assortments, the store must have existing [brands](https://help.vtex.com/docs/tutorials/what-is-a-brand), [categories](https://help.vtex.com/docs/tutorials/registering-a-category), [products](https://help.vtex.com/docs/tutorials/adding-or-editing-products), and [SKUs](https://help.vtex.com/docs/tutorials/adding-or-editing-skus), since these are the items the creation rules apply to.\n\n## Accessing the agent\n\nIn the VTEX Admin, go to **Catalog > Collections Agent**, or type **Collections Agent** in the search bar at the top of the page. The interface includes a conversational window and a prompt suggestion, as shown in the following image:\n\n![collections_agent_interface_en](https://cdn.statically.io/gh/vtexdocs/help-center-content/refs/heads/main/docs/en/tutorials/beta/catalog-beta/collections_agent_interface_en.png)\n\nBy clicking the suggestion `Create a collection`, or typing another instruction in the chat, the agent starts the support chat and guides the interaction until the desired action is completed.\n\n## How it works\n\nThe **Collections Agent** operates based on the following rules:\n\n- **Static or dynamic creation:** Creates and edits collections either statically (explicit list of product IDs, SKUs, or reference codes) or dynamically (criteria such as brands, categories, product specifications, and SKU specifications).\n- **Inclusive and exclusive rules:** Combines and excludes collections through inclusive and exclusive rules. Exclusive rules always take precedence over inclusive ones.\n- **Complex AND/OR combinations:** Supports complex logical combinations between criteria and rules. You don't need to build the subcollections manually — the agent presents the final logical structure for approval.\n- **Automatic propagation:** Multiple assortments can use the same collection. When you edit a shared collection, the update is automatically applied to all assortments that use it. This is the main value of the reusable block model.\n- **Incremental adjustment:** The agent adds to what's already been defined rather than replacing it, and understands relative modifiers such as \"undo that\" or \"swap X for Y\".\n- **Conversational disambiguation:** When an instruction is vague or matches more than one catalog entity, the agent pauses and presents options rather than guessing.\n- **Confirmation before high-impact changes:** Before significant changes (for example, editing a collection shared by many assortments), the agent shows the scope of the change and asks for user confirmation.\n\n## Performing actions on collections\n\n> ⚠️ The instruction examples shown below are for illustration purposes only and aren't the only way the agent can perform an action.\n\nYou can do the following:\n\n- Create a collection using natural language\n  - Review the collection plan\n  - Approve the collection plan\n- Create a collection by importing a spreadsheet\n- Check relationships in collections\n- Edit and refine the collection\n- Search for, list, and filter collections\n\n### Creating a collection using natural language\n\nTo create a collection using natural language, type the instructions (prompt) for creating the collection in the chat, including the products you want to group. Some examples of instructions are:\n\n- \"Create a collection with all products from the Infotech brand.\"\n- \"Create a collection with products from the Electronics and Computing categories, except those from the Infotech brand.\"\n- \"Create a collection with all products from the Summer category that have the Color specification set to Blue.\"\n\nYou can use a more detailed instruction, such as: \"create a collection with products from the Electronics and Computing categories that have the Color specification set to Black, except those from the Infotech brand.\"\n\nAfter entering the instructions in the chat, press `Enter` or click the up arrow button in the chat. The **Collections Agent** will then interpret the request and build the collection based on the relevant criteria and rules. Once processing is complete, the agent may ask for additional information.\n\n**Example:** The agent received the command \"Build a collection with all products from category ID 6.\" After processing, it may ask for a name and description for the collection, and once those are provided, the agent presents a plan for what will be done.\n\n#### Reviewing the collection plan\n\nThe collection plan presented by the agent is a summary you should review before confirming the operation. This plan includes information such as:\n\n- Name of the collection being created\n- Collection description\n- [Creation rule](#how-it-works) to be used\n- Future behavior for adding products to the collection\n\n#### Approving the collection plan\n\nAfter reviewing the plan, confirm the operation so the agent can apply the changes. Once this is done, the agent completes the processing and provides information such as:\n\n- The status of the operation (success or error)\n- The ID of the new collection\n- The collection name (if not provided by the user)\n\n> ❗ Data propagation can take up to an hour to reflect in the VTEX Admin, but it reflects within a few minutes during browsing.\n\n### Creating a collection via spreadsheet import\n\nYou can build a new collection by importing data via a spreadsheet in `.csv` or `.xlsx` format. The spreadsheet must contain a list of items with the following identification columns:\n\n| Spreadsheet column   | Description                              |\n| :------------------- | :--------------------------------------- |\n| Product ID           | Numeric code that identifies the product |\n| Product Reference ID | Product reference code                   |\n| SKU ID               | Numeric code that identifies the SKU     |\n| SKU Reference ID     | SKU reference code                       |\n\nTo import the spreadsheet, follow the steps below:\n\n1. Click the clip button in the **Collections Agent** chat to attach the spreadsheet.\n2. Locally select the spreadsheet in `.csv` or `.xlsx` format.\n3. Click `Open`.\n\nFollow the same steps as creating a collection via natural language to review and approve the collection plan. The plan is updated with each new instruction, and you approve the final structure without needing to build the internal logic of subcollections. Possible instructions are:\n\n- **Add** items to the existing list.\n- **Remove** items from the existing list.\n- **Replace** the entire list.\n\n> ⚠️ Import is never interrupted by failures in individual rows: the agent processes the entire spreadsheet, following these rules:\n>\n> - Rows with matching IDs are imported and logged.\n> - Rows with IDs that aren't found are skipped, logged, and displayed so you can fix them (for example, \"Row 5: SKU '362' not found\").\n> - Duplicate IDs are skipped in the following rows.\n\n### Checking relationships in collections\n\n**Collections Agent** can be used to query the relationships of products belonging to or missing from a collection. For example, you can ask via chat why a product was included in or excluded from a collection, and the agent will explain the criteria or rule that led to that decision. Instruction example: \"Why is the product with ID 74 in the Swimwear collection?\".\n\n### Editing and refining the collection\n\nIn an ongoing conversation, the **Collections Agent** doesn't replace the current draft state — it adds the new instructions to what's already been defined. In other words, you don't need to start from scratch to adjust a collection. The agent understands relative modifiers such as \"undo this\" or \"replace brand X with brand Y,\" and the collection plan is updated with each interaction.\n\nRefining collections based on new instructions works both for a collection that's being built and for one that's already been created.\n\n> ℹ️ The **Collections Agent** checks the impact of the edit. This means that before applying high-impact changes, such as editing a collection shared by multiple assortments, the agent shows which collections and assortments will be affected and asks for your confirmation before proceeding.\n\n### Searching, filtering, and listing collections\n\nTo find and manage the right collection, you can search by **name** or **ID** and sort or filter the list by common attributes, such as created date, name, and ID. When you open a collection, you can view its definition.\n\n## Performing actions on assortments\n\nYou can do the following:\n\n- Create an assortment with natural language\n- View the result\n- Check relationships in assortments\n- Approve the assortment plan\n- Edit and refine the assortment\n- Search, list, and filter assortments\n\n> ⚠️ Assortments are currently available only to stores using the **B2B Buyer Portal**.\n\n### Creating an assortment with natural language\n\nAn assortment is composed of collections, with inclusive and exclusive rules. Describe the final set of products you want in the conversation, and the agent builds the corresponding assortment. Examples of instructions:\n\n- \"Create an assortment that includes the Electronics and Accessories collections, but excludes the Apple Products collection.\"\n- \"Use collections 2 and 3, but exclude collection 4.\"\n\n### Viewing the result\n\nBefore confirming, the agent presents the assortment plan, with a summary of the included and excluded collections and the logic applied. The plan is updated with every instruction, and the agent works on one assortment at a time.\n\n### Checking relationships in assortments\n\nThe **Collections Agent** can be used to query the relationships between collections and assortments, and you can do this in three different ways:\n\n- Listing all collections related to an assortment, grouped by included and excluded.\n- Listing all assortments that consume a given collection, grouped by included and excluded.\n- Asking the reason why a collection is or isn't in an assortment, and the agent explains which criterion or rule led to that decision. Instruction example: \"Why is collection ID 463 in the North Branch assortment?\".\n\n### Approving the assortment plan\n\nAfter reviewing the plan, confirm the operation so the agent applies the changes to the assortment.\n\n### Editing and refining the assortment\n\nJust like with collections, you can adjust an assortment without starting from scratch. In an ongoing conversation, the agent adds new instructions to the current draft instead of replacing it, and understands commands like \"undo that\" or \"swap collection X for collection Y.\" Refinement applies to both existing assortments and assortments currently being built.\n\n> ❗ Since a collection can be used by multiple assortments, editing it may affect all of them. Before high-impact changes, the agent shows which collections and assortments will be affected and asks for confirmation before executing.\n\n### Searching, listing, and filtering assortments\n\nTo find and manage the desired assortment, you can search by name or ID, and sort or filter the list by common attributes:\n\n- Assortment created date\n- Assortment name\n- Assortment ID\n\n## Including all catalog products in a collection\n\nThere's currently no automatic way to include all products from the catalog in a collection so it stays synced. You can include all products using the existing dynamic rules, but each one has its limitations:\n\n- **By categories:** When you select all categories in the catalog, since every product must have a category, all products are included.\n- **By brands:** When you select all brands, since every product must have a brand, all products are included.\n- **By product specification:** When you select a specification with the same value present in all products. The specification must be active and of the combo (multiple selection) or radio (single selection) type, as the text type isn't supported.\n\nCommon points to watch out for with these options:\n\n- **Inactive** categories, brands, or specifications are added to the collection, but their products won't appear in navigation while they're inactive. If they're activated later, the products start appearing (rule of [Intelligent Search](https://help.vtex.com/docs/tutorials/intelligent-search-overview)).\n- If a category, brand, or specification is **deactivated** after the collection is created, its products remain in the collection but stop appearing in navigation (rule of **Intelligent Search**).\n- Categories and brands **created after** the collection aren't automatically included.\n- A category, brand, or specification **removed** from the catalog after the collection is created removes its products from the collection.\n- For product specifications, products without the specification, with a blank value, or with a different value are excluded.\n\nNone of these options is a permanent mirror of the catalog: what constitutes \"all products\" today may change as the catalog evolves, and none of the paths update automatically to capture what's created later. Regardless of the option chosen, a plan with the proposed structure is generated for approval before any changes are applied."}