Skip to content

Enable agentic search and agentic chat for an index

Background

Agentic search and agentic chat are per-index features that power AI-enhanced search endpoints:

  • Agentic search (agentic_search feature flag) enables the /agentic-search endpoint, which returns AI-summarized search results.
  • Agentic chat (agentic_chat feature flag) enables the /converse endpoint, which provides a conversational shopping assistant (the on-site chat widget demo).

Both are controlled by feature flags in the EcomIndexSettingsTable DynamoDB record for the index, and optionally configured with an agentic_config block for limits and behavior tuning.

Additionally, for the converse/chat feature, a catalog context entry in the codebase provides store-specific instructions to the LLM (e.g. what the store sells, how to guide the shopper).

Prerequisites

  • The index must already exist as an ecommerce index in the EcomIndexSettingsTable.
  • You need the system account ID and index name.
  • For the catalog context PR, you need write access to the cloud_control_plane repository.

Process

There are two parts: (1) enabling the feature flags and agentic config in DynamoDB, and (2) adding a catalog context entry via a code change.

Part 1: Enable feature flags and agentic config

  1. Use Escalator: Self-Service Admin to get admin access to the production Controller account.
  2. Navigate to the prod-EcomIndexSettingsTable item explorer.
  3. Find the target index record by querying with pk = system account ID. Select the record with sk = INDEX#<index_name>.
  4. Click the pk value to open the record for editing.

  5. Add or update the feature_flags field (type: Map): 

    {
  "agentic_search": true,
  "agentic_chat": true
}
    If feature_flags already exists with other values, merge in the two new keys without removing existing ones.

  6. Add or update the agentic_config field (type: Map). Use a baseline config like this (adjust values per customer needs): 

    {
  "enable_summary": true,
  "cached_query_percentage": 15,
  "inject_filter_context": true,
  "limits": {
    "agentic_search": {
      "max_input_chars": 4000,
      "max_output_tokens": 2048
    },
    "converse": {
      "max_input_chars": 8000,
      "max_output_tokens": 4096
    }
  }
}

  7. Click Save to commit the changes.

Aliased indexes

Some indexes use aliases, where the index the user addresses (e.g. mejuri-prod) is an alias and the actual underlying index is a different name (e.g. mejuri-prod-20260112). The alias index's settings are read first, with retrieval happening from the actual index.

  • Feature flags and agentic config: Set these on both the alias index record (e.g. mejuri-prod) and the actual underlying index record (e.g. mejuri-prod-20260112).
  • Catalog context (Part 2): Add entries for both the alias name and the actual underlying index name, as well as staging. For example, Mejuri needs entries for mejuri-prod, mejuri-prod-20260112, and mejuri-staging.

Verify the change propagated

Settings are synced from DynamoDB to Cloudflare KV via the ecom_settings_exporter Lambda (triggered by DDB Streams). To verify:

  1. Check prod-search-proxy-kv in the Production Cloudflare account.
  2. Search for key <system_account_id>:<index_name> and confirm feature_flags and agentic_config are present.
  3. In the Admin Console, go to the index's Overview tab and confirm the "Agentic Search" and "Agentic Chat" feature rows show as enabled.

Part 2: Add catalog context (for converse/chat)

Catalog context provides the LLM with store-specific knowledge so it can guide shoppers effectively. This is a code change that requires a PR.

File to edit

components/agentic_search/src/converse/catalog-context.ts

Steps

  1. Write a store context description. Follow the existing pattern: 

    STORE CONTEXT:
CATALOG: <Store name> is <what the store is>. The store carries <main product categories>.

Beyond <core categories>, <Store name> offers <additional categories>. <Target audience and positioning statement>.

  2. If the context will be reused across multiple index entries (prod, staging, aliased indexes), define it as a shared constant at the top of the file: 

    const MY_STORE_CONTEXT = `

STORE CONTEXT:
CATALOG: ...`;

  3. Add entries to the CATALOG_CONTEXTS map, keyed by {accountId}#{indexName}. Add entries for all index names that should use this context (production, staging, aliased target indexes): 

    // My Store
"abc123#my-store-prod": MY_STORE_CONTEXT,
"abc123#my-store-prod-20260301": MY_STORE_CONTEXT,  // alias target
"abc123#my-store-staging": MY_STORE_CONTEXT,

  4. Open a PR with the change. This deploys with the agentic_search Cloudflare Worker.

Example: Mejuri

Mejuri's context is already set up as a reference. Account ID j3grp7ot, with entries for mejuri-prod, mejuri-prod-20260112 (alias target), and mejuri-staging.

Agentic config reference

All fields in agentic_config are optional. The full schema:

Field Type Default Description
enable_summary boolean true Enable AI summary in agentic search results
cached_query_percentage number (0-100) 100 Percentage of queries to cache
cached_query_inclusion_substrings string[] all eligible Filter which queries are cached by matching substrings
inject_filter_context boolean false Inject filter context into LLM prompts for better filtering
filter_facets object - Configuration for automatic filter construction from facets
reviews_index_endpoint string - Full Marqo endpoint for a reviews index (e.g. https://dns/indexes/reviews-1)
limits.agentic_search.max_input_chars number - Max input characters for agentic search
limits.agentic_search.max_output_tokens number - Max output tokens for agentic search
limits.converse.max_input_chars number - Max input characters for converse/chat
limits.converse.max_output_tokens number - Max output tokens for converse/chat

Staging vs production

For staging environments, use the staging DynamoDB table (staging-EcomIndexSettingsTable) and staging Cloudflare KV. The catalog context code is the same across environments since it's deployed as part of the worker.

Troubleshooting

  • 403 on /agentic-search or /converse: The feature flag is not set or hasn't propagated to KV yet. Check both DynamoDB and KV.
  • Chat doesn't know about the store: Catalog context entry is missing or the key doesn't match {accountId}#{indexName} exactly.
  • Aliased index not working: Make sure both the primary index name AND the alias target index name have entries in CATALOG_CONTEXTS if the converse endpoint is used.
  • Settings not in KV: Check the ecom_settings_exporter Lambda logs in CloudWatch for errors on the DDB stream event.