Catalog Search

Catalog Search lets an agent recommend programs (or similar catalog items) using a structured, descriptor-validated plan — not a hand-built search URL. The agent calls search_catalog(), the platform validates fields against your Search Configuration, and runs the exact search. When the search matches more items than anyone wants to read, summarisation is handed to Search Guide; a short list stays with the agent that ran the search.

Use this guide for catalog / program agents such as EducationPlannerBC and Eastern Florida.

What you configure

Readiness checklist

Open Search Configuration → Catalog Search. The readiness panel reports whether:

1. Backend Search API is enabled
2. At least one scope has AI-facing catalog facets
3. Indexed facet values are available
4. Search Guide (search_guide) exists with a public results URL
5. At least one agent has search_catalog attached
6. Query Building includes {{prompt:Catalog Allowlists}}
7. The allowlist prompt file is present

Use the deep-links on each row to jump to Scopes, Filters, Agents, or Search Guide.

Available to AI toggles

Each non-hierarchy filter on a catalog scope can be marked Available to AI. UI filters stay on for the public search page even when AI is off.

Date and numeric range filters default to off for AI catalog search (website date presets still work on the public search page). Turn them on only when the agent should filter by bounds such as “after July 1” or “under $100”; the allowlist prompt documents range syntax instead of listing every timestamp or number.

Saving facet toggles (including via the sticky Save bar) also refreshes Catalog Allowlists automatically. Use Refresh Catalog Allowlists manually when index values change without facet-toggle edits.

Example: keep Career Interest as a website filter, but turn off AI so the agent uses Academic Community instead.

Refresh Catalog Allowlists

Refresh Catalog Allowlists writes sub_catalog_allowlists.prompt from live index values and ensures Query Building references {{prompt:Catalog Allowlists}}.

Keep language mappings and JSON examples in Query Building. Do not hand-maintain long “Allowed exact values” lists there — refresh the allowlists after facet or index changes. Range-capable facets document op: "range" with gte, lte, gt, and lt bounds instead of indexed values.

Enable Catalog Search (one click)

On an agent’s Configure Agent page:

1. Click Enable Catalog Search
2. Choose the catalog scope (for example programs)
3. Confirm the public results URL used for View-all links
4. Optionally keep standard search attached for discovery

This will:

• Attach search_catalog (and optional search) to the agent’s prompt
• Ensure Query Building + Catalog Allowlists prompt components are registered
• Create or update Search Guide (agent_search_guide.conf)
• Refresh allowlists for the chosen scope
  Conversation prompt wording stays under your control — enablement does not rewrite behavioural copy.

Structured plan test console

Before chatting demos, use the test console on the Catalog Search tab:

• Enter a query and scope
• Provide filters and/or filter_groups as JSON
• Run with Execute search to see hit count, sample titles, and the generated Funnelback / View-all path

Cross-field OR (for example “Melbourne or online”) belongs in filter_groups, not as two top-level filters. Top-level filters are ANDed.

Range filters belong in top-level filters, not filter_groups. Use op: "range" with at least one bound:

{"attribute": "date", "op": "range", "gte": "2026-07-01", "lte": "2026-07-31"}

Presets cover common cases: Melbourne or online, same-attribute OR, date range, and topic-only.

Agent behaviour (summary)

1. Concierge (or similar) builds a plan and calls search_catalog()
2. Invalid values return suggestions; Search Guide is not activated
3. Valid plans run the exact search
4. Many matches — Search Guide is activated, summarises the hits, and ends with the View-all link when provided
5. Few or no matches — the concierge keeps the turn, because only it can broaden a search that found nothing or look up a detail the result cards do not carry. It presents the results itself and still ends with the View-all link

Every result carries its own metadata (dates, campus, duration, and similar) regardless of how many matched, so whichever agent answers can read a specific fact such as an event date from the results.

New catalog agents should use search_catalog only.

Ways to narrow

Only a page of results is returned, but the counts describe the whole match set. On a large result set the platform works out which filters would actually divide it, and passes them to the answering agent so it can offer a useful next question instead of listing the first twenty-five matches.

A filter is offered only when:

• it is enabled for catalog search in your Search Configuration, so a follow-up search can apply the user's answer;
• it has not already been used in this search;
• its largest value leaves enough of the set behind to be worth choosing. A filter where 279 of 306 courses are "on campus" is skipped, because picking it barely changes the count — and so is an even split like domestic/international, for the same reason;
• a short menu of its top values still speaks for a meaningful share of the matches, which rules out filters with hundreds of thinly-spread values.

The three strongest are passed on, with up to six values each and a count of the rest. When nothing qualifies, nothing is passed on, and the agent is instructed to ask an open question rather than invent groupings from the page it can see.

To influence what gets offered, adjust which facets are enabled for catalog search on the scope. Removing near-duplicate facets (two versions of "study level", say) makes the offered questions noticeably cleaner.

Related

• Site Search tabs: Scopes, Filters, Preview
• Developer companion: admin/docs/UNIFIED_CATALOG_SEARCH.md