Catalog subagent

Copy the link to the article

Copied

Contents

1. When it connects and who starts it
2. What the subagent can do
3. Task types
4. How the subagent searches for products
5. How the result is returned and communication with the client
6. Configuring behaviour through instructions

The catalog subagent is a separate, specialised assistant that handles searching for products and services in the connected catalog and assembles a list of items from them for the cart or order. The main agent does not work with the catalog: when items need to be selected during the conversation, availability checked, or a cart prepared for creating an order, it passes the task to the subagent, receives the result, and continues the dialog.

An important feature: the subagent does not communicate with the client directly. It is a "silent" performer — it works with the catalog and returns the result to the main agent, and it is the main agent that decides what to say to the client and how. This way a single agent is always responsible for the conversation, while the subagent stays behind the scenes.

When it connects and who starts it

The subagent works only when access to the catalog is enabled in the agent settings — that is also where you choose which store to take products from (see Agent settings). While the catalog is not enabled, there is no subagent and the main agent knows nothing about products.

The subagent is started by the main agent itself. This is part of its instructions: when products need to be selected or a cart assembled, the main agent turns to the subagent rather than searching itself. It formulates the task — what needs to be done and with which products — and passes it on. From the client's point of view, it all looks like a single dialog: they do not see the switch to the subagent.

What the subagent can do

The subagent knows the catalog structure (categories → products → option-offers) and can:

• search for products by name, category, price range, brand, and characteristics;
• parse the catalog structure — get the category tree and the list of available characteristics with their values (for example, which colours and sizes there are and how many products fall under each);
• retrieve product details — the full description, prices, properties, images, and the website link (it supplements the brief search result with details itself before handing it to the main agent);
• check stock — but only if the task explicitly requires it; by default it ignores availability, because stock data can be out of date;
• pull up the client's history — past orders and data from the card, to take them into account when selecting;
• assemble a cart from the found items.

Access to the client's information and the list of their orders is available to the main agent too — so it can check the client's data or an order's status itself, without involving the subagent. The subagent, in turn, uses this history primarily for more accurate product selection.

At the same time, the subagent works strictly by the real catalog data and does not make up products, prices, or characteristics: if something is not there, it tells the main agent so.

Task types

The main agent turns to the subagent by setting a task of one of the following types.

Select and describe products. The subagent searches the catalog for suitable products and returns a detailed text report to the main agent — descriptions, comparisons, recommendations, which options are available. No cart is created in this case: the main agent uses the report to show the products to the client and help with the choice.

Assemble a cart. When a scenario step has a variable of the "Order contents" type, the main agent does not fill it in itself — the cart is assembled by the subagent: it finds the items with the needed quantity and returns it to the main agent, which passes the cart into the step's field. Along with the cart comes a brief summary of its contents, so that the agent can discuss it with the client if needed. Gifts, discounts, or special prices promised to the client are passed to the subagent together with the task.

Besides such structured tasks, the main agent can also pass a request in free form — for example, when the client is simply browsing the range or asking questions about products.

How the subagent searches for products

The search is arranged as a sequential operation, not a one-off one. The subagent first works out the catalog (categories, available characteristics and their values), then searches with specific filters, and only then loads details for the selected items. If needed, it repeats the rounds: narrows or changes the filters, tries other categories, adjusts the price range.

The key technique is to go from broad to narrow: first find at least something by one characteristic, and then filter out the excess with additional filters. This is important because the client's wording almost never matches the catalog word for word: the client says "red t-shirt", while the catalog has "T-shirt Basic Red". If the catalog is kept in another language or with its own abbreviations and names, the subagent first looks through the categories to understand the real names, and only then searches by them.

From this comes a direct dependency: the quality of the selection cannot be better than the catalog itself. The clearer the structure and the fuller the product descriptions and characteristics, the more accurately the subagent finds what is needed (about the opposite situation, see the Anti-patterns section).

How the result is returned and communication with the client

Having finished its work, the subagent returns control to the main agent and passes it the result: the assembled cart, a text report on the search — or a request for clarification. As already mentioned, it does not write to the client itself.

From this follows the way clarifications work. If the subagent lacks information to complete the task (for example, the client did not state the size, or it is unclear which option they mean), the subagent does not ask the client itself — it returns a question to the main agent. The main agent asks the client this question, gets the answer, and passes it back to the subagent, after which it continues working.

It is also the main agent that shows products to the client — usually as cards with an image, name, price, and link, rather than plain text. The products' internal identifiers are not shown to the client — they are only needed for the system to work.

Configuring behaviour through instructions

The subagent's behaviour is configured by two prompt slots (see Instructions):

• "Work with catalog" — instructions for the main agent: in which situations to turn to the catalog, which requests to pass to the subagent, what is important to take into account. If the main agent does not always notice in time that it is time to search for a product, this is the slot to supplement.
• "Product catalog" — instructions for the subagent itself: which fields and characteristics to rely on when searching, which categories and attributes to take into account, the specifics of the catalog structure and non-standard names. This slot is especially useful for catalogs with a complex structure or unusual names — it helps the subagent search more accurately.

Through these slots the subagent is adapted to a specific business and the arrangement of its catalog, without touching the built-in search logic.