Agentic Search

This tutorial covers how to enable agentic search on search requests, interpret the results, and manage exclusions through the Admin Preview API.

For a conceptual overview, see Agentic Search concepts.

Prerequisites

Before using agentic search, ensure the following:

1. BAIA is configured — The Bizzkit AI Assistant must be set up and connected to your ECS environment
2. AI Search instructions configured — BAIA instructions should be set up via the AI search settings in the Admin API (same instructions used for semantic search)

Enabling agentic search on a request

To use agentic search, set agenticSearch to true in your unified search request:

1
2
3
4
5
6
7
8
9

POST /search
Content-Type: application/json

{
    "segmentId": "merch-b2c-en",
    "scopeId": "full-search",
    "phrase": "something to keep my coffee warm at my desk",
    "agenticSearch": true
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
    "products": [
        {
            "id": "travel-mug-001",
            "title": "Insulated Travel Mug 350ml",
            "score": 1.0
        },
        {
            "id": "mug-warmer-002",
            "title": "USB Desktop Mug Warmer",
            "score": 0.95
        },
        {
            "id": "thermos-003",
            "title": "Stainless Steel Thermos Flask",
            "score": 0.90
        }
    ],
    "totalProducts": 3,
    "originalPhrase": "something to keep my coffee warm at my desk",
    "usedPhrase": "something to keep my coffee warm at my desk"
}

Important constraints

• forceSearch must be false (the default) for agentic search to activate
• If a Did You Mean correction is applied, agentic search will not trigger (since the corrected phrase may yield results)
• An empty search phrase will not trigger agentic search

Managing product exclusions

Product exclusions prevent specific products from being suggested by agentic search. All exclusion endpoints use the Admin Preview API (v26-preview).

Adding a product exclusion

1
2
3
4
5
6
7

POST /api/segments/{segmentId}/agentic-search/product-exclusions
Content-Type: application/json
Authorization: Bearer {token}

{
    "productId": "discontinued-product-123"
}

1
2
3
4

{
    "id": "excl-abc-123",
    "productId": "discontinued-product-123"
}

Searching excluded products

Use the search endpoint to find currently excluded products:

1
2
3
4
5

POST /api/segments/{segmentId}/agentic-search/product-exclusions/search
Content-Type: application/json
Authorization: Bearer {token}

{}

Searching products available for exclusion

To find products that can be excluded:

1
2
3
4
5

POST /api/segments/{segmentId}/agentic-search/product-exclusions/search-products
Content-Type: application/json
Authorization: Bearer {token}

{}

Removing a product exclusion

1
2

DELETE /api/segments/{segmentId}/agentic-search/product-exclusions/{productExclusionId}
Authorization: Bearer {token}

Managing field exclusions

Field exclusions remove specific field values from the context BAIA uses for reasoning. This helps refine what information the AI considers when suggesting products.

Adding a field exclusion

1
2
3
4
5
6
7
8

POST /api/segments/{segmentId}/agentic-search/field-exclusions
Content-Type: application/json
Authorization: Bearer {token}

{
    "fieldName": "color",
    "fieldValueId": "neon-pink"
}

1
2
3
4
5

{
    "id": "excl-field-456",
    "fieldName": "color",
    "fieldValueId": "neon-pink"
}

Listing available fields

To see which fields are available for exclusion:

1
2
3
4
5

POST /api/segments/{segmentId}/agentic-search/field-exclusions/available
Content-Type: application/json
Authorization: Bearer {token}

{}

Searching field exclusions

1
2
3
4
5

POST /api/segments/{segmentId}/agentic-search/field-exclusions/search
Content-Type: application/json
Authorization: Bearer {token}

{}

Removing a field exclusion

1
2

DELETE /api/segments/{segmentId}/agentic-search/field-exclusions/{fieldExclusionId}
Authorization: Bearer {token}

Best practices

1. Use exclusions proactively — If you notice agentic search suggesting inappropriate products, add them to the exclusion list rather than disabling the feature entirely.

2. Combine with semantic search — Agentic search and semantic search complement each other. Semantic search improves results for popular phrases, while agentic search handles complex natural-language queries.

3. Monitor zero-result rates — Agentic search is most valuable for reducing zero-result searches. Use the Findability dashboard to track improvements.

4. Field exclusions for noise reduction — If certain field values consistently lead to poor suggestions, exclude them to improve AI reasoning quality.

Limitations

• Agentic search is a Preview feature and may change in future versions
• It requires an active BAIA connection — if BAIA is unavailable, the fallback returns the original (possibly empty) search results
• Response times may be longer when agentic search activates, as it involves an additional AI reasoning step
• The feature operates on the v26-preview API version