Configure agentic search and converse for an index

Agentic search and converse are per-index features that power AI-assisted search flows:

• Agentic search uses the /agentic-search endpoint for query expansion, category searches, and optional generated summaries.
• Converse uses the /agentic-search/converse endpoint for multi-turn chat.

Use this runbook to enable the endpoints and manage the runtime agentic config from Admin Console. Do not edit the legacy root agentic_config map directly for new changes.

Prerequisites

• The target index already exists as an ecommerce index.
• You have the system account ID and index name.
• You have Admin Console access for the target environment.

Enable feature flags

1. Open Admin Console.
2. Go to Indexes and open the target index.
3. Select the Configuration tab.
4. Enable the relevant feature flags:
   • agentic_search for /agentic-search
   • agentic_chat for /agentic-search/converse
   • agentic_customer_support when support mode is being configured
5. Confirm the feature flag change.

Feature flags are stored on the index settings record and exported to Cloudflare KV by ecom_settings_exporter.

Configure the default agentic config

1. Select the index Agentic tab.
2. Click Create.
3. Set Scope to Default base config.
4. Use Form for guided fields, or JSON when pasting a reviewed payload.
5. Set only the fields needed for the index.
6. Confirm Updated By is your email.
7. Enter a specific Reason, such as Enable summary and catalog context for production launch.
8. Click Create.
9. After saving, click the view icon and copy the payload if you need to verify the stored JSON.

The default config is merged over runtime global defaults and is used when the request has no channel query parameter.

Baseline default payload

{
  "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_extra_context_chars": 8000,
      "max_output_tokens": 4096
    }
  },
  "catalog_context": "STORE CONTEXT:\nCATALOG: Example Store sells apparel, accessories, and seasonal collections."
}

Adjust values per customer needs. Prefer catalog_context in this config over hard-coded catalog context entries for new configurations.

Configure a channel override

Use a channel override when one client, experiment, locale, storefront, or surface needs behavior that differs from the index default.

1. Select the index Agentic tab.
2. Click Create.
3. Set Scope to Channel partial override.
4. Enter a Channel ID. It must be at most 64 characters and contain only letters, numbers, hyphens, and underscores.
5. Optionally enter a Channel Label for humans.
6. Set only the fields that should differ from the default config.
7. Enter Updated By and Reason.
8. Click Create.
9. View the saved row and compare Channel Payload with Effective Payload.

Clients select the channel by passing the channel ID as a query parameter:

/api/v1/indexes/{index_name}/agentic-search?payload={base64_payload}&channel=retail_app
/api/v1/indexes/{index_name}/agentic-search/converse?payload={base64_payload}&channel=retail_app

Channel configs are partial. Leave a field unset when the channel should inherit the default value. Arrays and scalar values replace inherited values; nested JSON objects are merged.

If a request specifies a channel that has no matching config row, search_proxy fails the request instead of falling back to the default config.

Example channel payload

{
  "cached_query_percentage": 0,
  "top_customer_queries": ["sale", "new", "trending"],
  "debug": true
}

This channel inherits every default field except the three fields shown above.

Edit, copy, and delete configs

• View shows the saved payload. For channel rows it also shows the effective payload after default and channel merge.
• Edit replaces the saved payload for that scope. For a channel, clearing a field removes the override and exposes the inherited default value again.
• Copy to is available from unchanged channel rows. Copying to the default merges the channel payload over the existing default draft. Copying to another channel starts that channel draft from the source channel payload.
• Delete removes that scope's config row. Deleting a default config leaves runtime global defaults plus any selected channel row. Deleting a channel means requests with that channel fail until clients stop sending it or a new channel row is created.

Every create or edit requires updated_by and change_reason. These values are stored with the record and emitted in admin route logs.

Common fields

Field	Use
enable_summary	Enables generated summaries in agentic search. Runtime default is true.
cached_query_percentage	Percentage of queries eligible for cached query handling. Use 0 to disable cached query use for the config.
cache_filter_fields	Filter field names extracted from the incoming filter to partition cached query keys.
inject_filter_context	Injects request filter context into prompts when a request already contains a filter. Runtime default is false.
filter_facets	Enables automatic filter construction from configured facet fields.
reviews_index_endpoint	Full Marqo endpoint for a reviews index used by reviews-aware flows.
limits.agentic_search.*	Input and output limits for /agentic-search.
limits.converse.*	Input, extra context, and output limits for /agentic-search/converse.
top_customer_queries	Queries such as sale, new, or trending that bypass normal expansion and use the matched term as the category query.
min_hits_threshold	Minimum unique hits required for a category to be kept. Runtime default is 4.
converse_judge_enabled	Enables LLM judging for low-quality converse category results. Runtime default is false.
debug	Persists per-turn debug context in the conversation Durable Object. Runtime default is false.
catalog_context	Store-specific prompt context for converse.
support_resources	Support links that converse can show for matching customer-help topics.
support	Support-mode locale settings, including default_locale and available_locales in lang-region form such as en-us.
division_field and division_map	Division filtering setup. Both must be set in the effective config, or both unset.
size_field and size_map	Size normalization setup. size_map requires size_field; specific division size maps must align with division_map.

The form validates the same constraints as the backend. JSON payloads must be objects and cannot include admin metadata fields such as pk, sk, channel, updated_by, or change_reason.

Aliased indexes

Some indexes use aliases, where the customer-addressed index name points to a different underlying index.

• Enable feature flags and configure agentic config on the index name that search_proxy resolves for the request.
• If both alias and underlying index names can be addressed by clients, configure both records.
• Test both names when changing a production alias setup.

Verify propagation

After saving:

1. Confirm the Admin Console table shows the expected row and updated timestamp.
2. Check Cloudflare KV for the generated key:
   • Default: {system_account_id}-{index_name}#agentic_config
   • Channel: {system_account_id}-{index_name}#channel#{channel_id}#agentic_config
3. Verify the index Overview tab shows the relevant Agentic Search and Agentic Chat feature flags enabled.
4. Send a request through search_proxy. Include channel=<channel_id> only when testing a channel override.

Troubleshooting

Symptom	Check
403 from /agentic-search or /agentic-search/converse	The matching feature flag is off or has not propagated. Enable it in the Configuration tab and check KV sync.
Request fails only when channel is present	The channel ID is invalid, the channel row is missing, or the row has not propagated to KV.
Agentic tab shows missing identifiers	Navigate to the index from the Indexes list instead of building a direct URL with an account ID that contains hyphens.
Save fails with a reserved field error	Remove metadata fields from the JSON payload. The payload should contain runtime config fields only.
Save fails for division or size fields	Ensure division_field and division_map are both present or both absent, and that size_field, size_map, and division_map align in the effective config.
Behavior does not change after save	Check the generated KV key, then tail search_proxy logs for agentic_config_resolved to confirm which default and channel keys were loaded.
Settings are not in KV	Check ecom_settings_exporter logs for DynamoDB stream processing errors.