Agentic Search API Specification
Overview
The Agentic Search API facilitates deep, intent-focused search patterns. A user’s query is comprehended by a generative AI agent, which designs a set of search queries around it. The agent retrieves items from a Marqo index and returns a collection of result categories. Clients can then render these categories and offer relevant options to the user.
The API supports both streaming and non-streaming modes. Streaming provides real-time feedback to the user. Developers can override features like the number of results per category, max number of categories, agent parameters, and search settings.
Use Cases
This API is ideal for situations where a user’s query could span multiple, potentially non-overlapping product categories. The system interprets a high-level query and generates sub-queries ("head queries") that organize results by category.
Best suited for:
- Marqo users with diverse product catalogs
- Applications handling ambiguous or broad user queries
API Endpoint
Paths
- Streaming:
GET /indexes/{index_name}/agentic-search/stream
- Non-streaming:
POST /indexes/{index_name}/agentic-search
Supported HTTP Methods
GET
(for streaming)POST
(for non-streaming)
Authentication
- API key or token-based authentication
Request Format
- Streaming: Use
GET
with URL query parameters due to SSE constraints. - Non-streaming: Use
POST
with parameters in the request body.
Agentic Search Parameters
Parameter | Type | Default | Description |
---|---|---|---|
q |
String | (required) | The user's query |
agenticSearchLimit |
Integer | 12 |
Number of results per category (distinct from searchSettings.limit ) |
maxCategories |
Integer | 5 |
Maximum number of categories the agent will attempt to return |
clickableSummary |
Boolean | true |
Defines if the summary will contain markdown content for interaction |
suggestFilters |
Boolean | false |
When enabled, returns suggested filter objects based on user query |
searchSettings |
Dict | see below | Configuration used during search (see below) |
Clickable Summary
The agent will incorporate suggested follow-up queries in its summary. If this is set to true, the agent will implant this pattern in the summary: [[button:query=<your_query>]]
. Custom markdown renderers can then display that text as a button or other element.
Search Settings
Parameter | Type | Default | Description |
---|---|---|---|
limit |
Integer | 10 |
Maximum number of products to return |
offset |
Integer | 0 |
Number of products to skip (for pagination) |
filter |
String | null |
Filter string using Marqo's query DSL to narrow search results |
attributesToRetrieve |
List[String] | ["productTitle", "variantTitle", "price", "variantImageUrl", "collections", "_id", "_score"] |
Specific product fields to return. If not specified, returns the default core product fields |
facets |
Dict | null |
Facet configuration for aggregated results |
sortBy |
Dict | null |
Sort configuration for results ordering |
userId |
String | null |
User ID for personalization |
sessionId |
String | null |
Session ID for personalization |
Example Requests
1. Non-Streaming POST Request (with updated searchSettings
)
POST /indexes/my-first-index/agentic-search HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{
"q": "I need something to wear to a wedding",
"sessionId": "session-abc123",
"userId": "user-456",
"agenticSearchLimit": 10,
"maxCategories": 4,
"clickableSummary": true,
"suggestFilters": true,
"searchSettings": {
"limit": 24,
"offset": 0,
"filter": "availability:true",
"attributesToRetrieve": [
"productTitle",
"variantTitle",
"price",
"variantImageUrl",
"collections",
"_id",
"_score"
],
"facets": null,
"sortBy": null,
"userId": "user-456",
"sessionId": "session-abc123"
}
}
2. Streaming GET Request with Base64-Encoded Query Parameters (SSE)
Step 1: Compose JSON payload (pretty-printed here for readability)
{
"q": "I need something to wear to a wedding",
"sessionId": "session-abc123",
"userId": "user-456",
"agenticSearchLimit": 10,
"maxCategories": 4,
"clickableSummary": true,
"suggestFilters": true,
"searchSettings": {
"limit": 24,
"offset": 0,
"filter": "availability:true",
"attributesToRetrieve": [
"productTitle",
"variantTitle",
"price",
"variantImageUrl",
"collections",
"_id",
"_score"
],
"facets": null,
"sortBy": null,
"userId": "user-456",
"sessionId": "session-abc123"
}
}
Step 2: Base64 encode this JSON (URL-safe, no padding)
eyJxIjogIkkgbmVlZCBzb21ldGhpbmcgdG8gd2VhciB0byBhIHdlZGRpbmciLCAic2Vzc2lvbklk\nIjogInNlc3Npb24tYWJjMTIzIiwgInVzZXJJZCI6ICJ1c2VyLTQ1NiIsICJhZ2VudGljU2VhcmNo\nTGltaXQiOiAxMCwgIm1heENhdGVnb3JpZXMiOiA0LCAiY2xpY2thYmxlU3VtbWFyeSI6IHRydWUs\nICJzZWFyY2hTZXR0aW5ncyI6IHsibGltaXQiOiAxMCwgIm9mZnNldCI6IDAsICJmaWx0ZXIiOiAi\nYXZhaWxhYmlsaXR5OnRydWUiLCAiYXR0cmlidXRlc1RvUmV0cmlldmUiOiBbInByb2R1Y3RUaXRs\nZSIsICJ2YXJpYW50VGl0bGUiLCAicHJpY2UiLCAidmFyaWFudEltYWdlVXJsIiwgImNvbGxlY3Rp\nb25zIiwgIl9pZCIsICJfc2NvcmUiXSwgImZhY2V0cyI6IG51bGwsICJzb3J0QnkiOiBudWxsLCAi\ndXNlcklkIjogInVzZXItNDU2IiwgInNlc3Npb25JZCI6ICJzZXNzaW9uLWFiYzEyMyJ9fQ==\n
Step 3: Use in the URL query param payload
GET /indexes/my-first-index/agentic-search/stream?payload=eyJxIjogIkkgbmVlZCBzb21ldGhpbmcgdG8gd2VhciB0byBhIHdlZGRpbmciLCAic2Vzc2lvbklk\nIjogInNlc3Npb24tYWJjMTIzIiwgInVzZXJJZCI6ICJ1c2VyLTQ1NiIsICJhZ2VudGljU2VhcmNo\nTGltaXQiOiAxMCwgIm1heENhdGVnb3JpZXMiOiA0LCAiY2xpY2thYmxlU3VtbWFyeSI6IHRydWUs\nICJzZWFyY2hTZXR0aW5ncyI6IHsibGltaXQiOiAxMCwgIm9mZnNldCI6IDAsICJmaWx0ZXIiOiAi\nYXZhaWxhYmlsaXR5OnRydWUiLCAiYXR0cmlidXRlc1RvUmV0cmlldmUiOiBbInByb2R1Y3RUaXRs\nZSIsICJ2YXJpYW50VGl0bGUiLCAicHJpY2UiLCAidmFyaWFudEltYWdlVXJsIiwgImNvbGxlY3Rp\nb25zIiwgIl9pZCIsICJfc2NvcmUiXSwgImZhY2V0cyI6IG51bGwsICJzb3J0QnkiOiBudWxsLCAi\ndXNlcklkIjogInVzZXItNDU2IiwgInNlc3Npb25JZCI6ICJzZXNzaW9uLWFiYzEyMyJ9fQ==\n HTTP/1.1
Host: api.example.com
Accept: text/event-stream
Authorization: Bearer YOUR_API_KEY
Rules and Actions
The Agentic Search API can trigger actions based on user queries or detected intents. This allows chatbots and frontends to perform tasks beyond product search, such as navigating to pages, fetching dynamic data, showing content, or triggering workflows. Actions are executed by the frontend based on the API response.
How Rules Work
Each rule combines a match
pattern and the action it triggers. The match
field is human-readable (e.g., "intent:the user intends to understand the shipping policies") for easy understanding, but can also support structured identifiers or regex patterns.
Example Rule Object:
{
"match": "the user intends to understand the shipping policies",
"action": {
"type": "redirect",
"url": "/policies/shipping"
}
"action": "navigate to shipping policy page"
}
Action Types
The system supports five main action types for e-commerce use cases:
Action Type | Description |
---|---|
redirect |
Navigate the user to another page or URL (e.g., shipping policy, returns page) |
http |
Make an API call to fetch dynamic data (e.g., order status, shipping rates) |
static_content |
Display pre-defined text or FAQ snippet directly in the chat/UI |
workflow |
Trigger a business process or internal workflow (e.g., create support ticket) |
ui_element |
Instruct the frontend to render a special component (e.g., store hours, product carousel) |
Code Example
Here's an example of how to use rules and actions with a redirect action:
Example UX Flow: - Query: "What's your shipping policy?" - Action triggered: redirect to /policies/shipping page - UX: Chatbot shows "View Shipping Policy" button → user clicks → navigates to page
{
"q": "What's your shipping policy?",
"rules":
{
"match": "the user intends to understand the shipping policies",
"action": {
"type": "redirect",
"url": "/policies/shipping"
}
},
{
"match": "the user intends to track their order",
"action": {
"type": "http",
"method": "GET",
"endpoint": "https://api.example.com/orders/${orderId}/status",
"headers": {
"Authorization": "Bearer ${API_KEY}"
}
}
}
}
This provides a top-5 actionable framework for e-commerce agents, combining clarity, flexibility, and practical frontend handling.
Example UX Flow
Query: "What's your shipping policy?" Action triggered: redirect to /policies/shipping page UX: Chatbot shows "View Shipping Policy" button → user clicks → navigates to page
Response
JSON Response Structure
Field | Type | Description |
---|---|---|
summary |
String | AI-generated summary of the category results (may include links/buttons) |
categoryHits |
List | List of result categories and associated items (see below) |
hits |
List | Non-agentic search results using the provided query |
facets |
Dict | Optional facets metadata (if configured) |
filters |
Dict | Optional suggested filter objects (if suggestFilters enabled) |
redirect |
Dict | Optional redirect (see below) |
categoryHits
Structure
Field | Type | Description |
---|---|---|
category |
String | The category label |
hits |
List | Documents returned for this category query |
filters
Structure
Field | Type | Description |
---|---|---|
fields |
Dict | Filter fields with their configuration |
Filter Field Types:
- Number fields: Support range filters with ranges
array
- String fields: Support exact value matches with values
array
- Array fields: Support array contains filters
redirect
Structure
Field | Type | Description |
---|---|---|
reason |
String | Reason for redirect |
url |
String | URL to redirect the user to |
Streaming Response
- Delivered via Server-Sent Events (SSE).
- Each event sends the entire current snapshot of the full response schema.
- Snapshots should be treated as stateful replacements, not deltas.
- The final event is of type
stream-end
indicate the end of the stream
Example Stream Output
event: message
data: {
"summary": "Here are some options you might like for party wear.",
"categoryResults": [
{
"category": "Dresses",
"hits": [
{"_id": "dress_001", "title": "Red Sequin Dress", "price": 89.99},
{"_id": "dress_002", "title": "Black Silk Gown", "price": 129.99}
]
}
]
}
event: message
data: {
"summary": "Here are some options you might like for party wear. Try searching for [[button:query=Casual party outfits]], [[button:query=Formal party attire]] or [[button:query=Accessories for a party]] for more options.",
"categoryResults": [
{
"category": "Dresses",
"hits": [
{"_id": "dress_001", "title": "Red Sequin Dress", "price": 89.99},
{"_id": "dress_002", "title": "Black Silk Gown", "price": 129.99},
{"_id": "dress_003", "title": "Blue Off-Shoulder Dress", "price": 99.99}
]
},
{
"category": "Shoes",
"hits": [
{"_id": "shoe_001", "title": "Silver Heels", "price": 59.99},
{"_id": "shoe_002", "title": "Strappy Sandals", "price": 49.99}
]
}
]
}
event: stream-end
data: {}
Filter Suggestions
When suggestFilters
is set to true
, the API analyzes the user's query and returns structured filter objects that can be automatically applied to search results. This helps users refine their search without manually selecting filters.
How Filter Suggestions Work
The system analyzes user queries to intelligently suggest relevant filters for price ranges, brands, colors, categories, or other product attributes. When enabled, this returns structured filter objects that can be automatically applied to search results.
Example Filter Response:
{
"filters": {
"price": {
"type": "number",
"ranges": [
{"from": 0, "to": 50}
]
},
"brand": {
"type": "string",
"values": ["Nike", "Adidas"]
},
"color": {
"type": "string",
"values": ["black", "white"]
}
}
}
The filter object follows the same structure as Marqo's facet configuration, making it easy to integrate with existing filter UI components.
Filter Types
The system can suggest various types of filters based on the user's query and product catalog. These are examples of common filter types - the system works with whatever attributes exist in your product catalog:
Filter Type | Description | Example Use Cases | Structure |
---|---|---|---|
Price Range | Numeric range filters for price fields | "under $50", "between $100-200" | {"type": "number", "ranges": [{"from": 0, "to": 50}]} |
Brand | Exact string matches for brand fields | "Nike shoes", "Apple products" | {"type": "string", "values": ["Nike", "Adidas"]} |
Color | String values for color attributes | "black dress", "red shoes" | {"type": "string", "values": ["black", "red"]} |
Category | Product category or collection filters | "electronics", "clothing" | {"type": "string", "values": ["electronics"]} |
Size | Size or dimension filters | "large shirts", "size 10 shoes" | {"type": "string", "values": ["L", "XL"]} |
Availability | Stock or availability status | "in stock items", "available now" | {"type": "string", "values": ["in_stock"]} |
Rating | Product rating or review filters | "highly rated", "4+ stars" | {"type": "number", "ranges": [{"from": 4}]} |
Material | Product material or composition | "cotton shirts", "leather bags" | {"type": "string", "values": ["cotton", "leather"]} |