Marqo Conversational Agent API

Overview

The Conversational Agent API provides intelligent, conversational product discovery with query expansion, contextual recommendations, and real-time streaming responses. The system understands user intent, asks clarifying questions when needed, and organizes results into meaningful categories with natural language explanations.

Features

Conversational Search: Natural language queries with intelligent query expansion
Context-Aware Suggestions: Product-specific query suggestions on PDP pages
Streaming Responses: Real-time streaming via Server-Sent Events (SSE)
Categorized Results: Products organized into logical categories with descriptions
Clarifying Questions: System asks questions when queries are ambiguous
Context Continuity: Maintains conversation context across interactions

Prerequisites

A Marqo Cloud account
Your Marqo API key (find your API key guide)
An existing ecommerce index with products (add products guide)
Access to the Conversational Agent API (contact Marqo for access)

Endpoints

PDP Query Suggestions

Generate contextual search query suggestions based on a specific product. This endpoint helps users discover related products or learn more about a product they're viewing.

Endpoint: POST /indexes/{index_name}/agentic-search/chat-suggestions

Headers: - Content-Type: application/json - x-marqo-index-id: {index_id} (required)

Request Parameters:

Parameter	Type	Required	Default	Description
`documentId`	string	Yes	-	Product document identifier (`_id` field)
`sessionId`	string	Yes	-	User session identifier
`userId`	string	Yes	-	User identifier
`maxSuggestions`	integer	No	`5`	Maximum number of suggestions to return
`minSuggestions`	integer	No	`1`	Minimum number of suggestions to return
`contextFields`	array	No	All fields	Product fields to use for context (e.g., `["material", "description"]`)

Example Request:

curl -X POST 'https://ecom.marqo-ep.ai/api/v1/indexes/my-ecom-store/agentic-search/chat-suggestions' \
  --header 'Content-Type: application/json' \
  --header 'x-marqo-index-id: abc123-my-ecom-store' \
  --data '{
    "documentId": "273301208",
    "sessionId": "session-abc123",
    "userId": "user-28389290",
    "maxSuggestions": 5,
    "minSuggestions": 1,
    "contextFields": ["material", "description"]
  }'

Example Response:

[
  "What heels would go well with this?",
  "What is the material made out of?",
  "What do people say about this product?"
]

The response is an array of suggested queries that users might want to ask about the product.

Conversational Search

Stream conversational search results with categorized products and intelligent messaging. This is the main endpoint for conversational product discovery.

Endpoint: GET /indexes/{index_name}/agentic-search/converse

Headers:

x-marqo-index-id: {index_id} (required)

Query Parameters:

Parameter	Type	Required	Description
`payload`	string	Yes	Base64-encoded JSON containing the request parameters (see below)

Payload Parameters (JSON, then base64-encoded):

Parameter	Type	Required	Default	Description
`q`	string	Yes	-	User query
`sessionId`	string	Yes	-	Session identifier
`userId`	string	Yes	-	User identifier
`conversationId`	string	No	-	Conversation identifier (hash string returned from previous response) for maintaining context
`categoryResultLimit`	integer	No	`3`	Number of results per category
`filter`	string	No	-	Query filter using Marqo's filter DSL (e.g., `"availability:true"`)
`attributesToRetrieve`	array	No	Default fields	Product fields to return (e.g., `["productTitle", "variantTitle", "price", "variantImageUrl", "_id"]`)
`context`	object	No	-	Context object with `contextType` and `documentId` for product-specific context

Example Request: With Context

curl -G 'https://ecom.marqo-ep.ai/api/v1/indexes/my-ecom-store/agentic-search/converse' \
  --header 'x-marqo-index-id: abc123-my-ecom-store' \
  --data-urlencode "payload=$(echo -n '{
    "conversationId": "3fd8b45def95c8a98da1cfda23543699144cee5d9c89ae143040bca4ff0636e9",
    "context": {
      "contextType": "document",
      "documentId": "1298739082732"
    },
    "q": "I need outfits for a tropical vacation",
    "sessionId": "session-xyz789",
    "userId": "user-123",
    "categoryResultLimit": 3,
    "filter": "availability:true",
    "attributesToRetrieve": [
      "productTitle",
      "variantTitle",
      "price",
      "variantImageUrl",
      "_id"
    ]
  }' | base64 | tr -d '\n')"

Example Request: Simple Query

curl -G 'https://ecom.marqo-ep.ai/api/v1/indexes/my-ecom-store/agentic-search/converse' \
  --header 'x-marqo-index-id: abc123-my-ecom-store' \
  --data-urlencode "payload=$(echo -n '{
    "q": "red dress",
    "sessionId": "session-001",
    "userId": "user-456"
  }' | base64 | tr -d '\n')"

Response Events

The conversational search endpoint streams responses as Server-Sent Events (SSE). Each event contains one of the following response types:

Category Hits

Grouped product results organized by category. Each category includes a descriptive message, the query used to find those products, and the product hits.

{
  "message": "I'd be happy to help you find the perfect jacket! To give you the best recommendations:\n\n- What type of jacket are you looking for (winter coat, rain jacket, casual jacket, work blazer)?\n- What's the primary use (outdoor activities, everyday wear, professional settings)?\n- Any preferences for men's or women's styles?",
  "categoryHits": [
    {
      "category": "Dresses",
      "seeMoreQuery": "Summer floral dresses",
      "hits": [
        {
          "_id": "dress_001",
          "title": "Red Sequin Dress",
          "price": 89.99,
          "blurb": "Sparkles under lights, perfect for evening events and celebrations"
        },
        {
          "_id": "dress_002",
          "title": "Black Silk Gown",
          "price": 129.99,
          "blurb": "Luxurious fabric with elegant drape for formal occasions"
        }
      ]
    }
  ]
}

Fields:

message: Conversational message explaining the results or asking clarifying questions
categoryHits: Array of category groups
category: Category name (e.g., "Dresses", "Jackets")
seeMoreQuery: The query used by the LLM to retrieve these products (enables "see more" functionality)
hits: Array of products in this category
- _id: Product document ID
- title: Product title
- price: Product price
- blurb: LLM-generated description of the product

Single Item Hits

Returns a single product item (not grouped in a category).

{
  "itemHits": {
    "_id": "dress_001",
    "title": "Red Sequin Dress",
    "price": 89.99,
    "blurb": "Sparkles under lights, perfect for evening events and celebrations"
  }
}

Message Hits

Conversational messages in markdown format. These can be introduction messages, clarifying questions, or final summary messages.

Example: Clarifying Question

{
  "messageHits": "I'd be happy to help you find the perfect jacket! To give you the best recommendations:\n\n- What type of jacket are you looking for (winter coat, rain jacket, casual jacket, work blazer)?\n- What's the primary use (outdoor activities, everyday wear, professional settings)?\n- Any preferences for men's or women's styles?"
}

Example: Introduction Message

{
  "messageHits": "Perfect! Here are some great outerwear options to keep you warm and stylish:"
}

Example: Final Message

{
  "messageHits": "All feature stylish designs and features to keep you warm and protected from the elements."
}

Agentic Conversation Behavior Overview

Context Management

The system maintains conversation context across interactions:

Context Continuity: Previous conversation context is used to inform current responses
Product Context: When a context object is provided with contextType: "document" and a documentId, the system uses that product's information to provide more relevant suggestions
Session Tracking: sessionId and userId help maintain context throughout a user's session

Question Triggering - Ambiguous Queries

The system automatically asks clarifying questions when user queries are ambiguous or too broad.

Examples:

Query: "jacket" → System asks: "What type of jacket are you looking for (winter coat, rain jacket, casual jacket, work blazer)?"
Query: "shoes" → System asks clarifying questions about style, occasion, or gender
Query: "dress" → System asks about occasion, style, or fit preferences

When Questions Are Triggered:

Queries that are too broad (single word product categories)
Queries missing important context (style, occasion, gender, features)
Queries that could match many different product types

Implementation Notes

Streaming Response Handling

When using the converse endpoint, you must handle Server-Sent Events (SSE). The response will stream multiple events, each containing different parts of the response.

Example JavaScript handling:

// Build the request payload
const requestData = {
  q: "red dress",
  sessionId: "session-001",
  userId: "user-456"
};

// Base64 encode the payload
const payload = btoa(JSON.stringify(requestData));

// Construct the URL with the encoded payload
const url = `https://ecom.marqo-ep.ai/api/v1/indexes/my-ecom-store/agentic-search/converse?payload=${encodeURIComponent(payload)}`;

// Create EventSource for SSE
const eventSource = new EventSource(url);

// Add custom header via fetch for environments that need it
// Note: EventSource doesn't support custom headers natively
// For custom headers, use fetch with ReadableStream instead

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);

  if (data.categoryHits) {
    // Handle category results
    console.log('Categories:', data.categoryHits);
  } else if (data.itemHits) {
    // Handle single item
    console.log('Item:', data.itemHits);
  } else if (data.message) {
    // Handle message
    console.log('Message:', data.message);
  } else if (data.conversationId) {
    // Store conversation ID for follow-up queries
    console.log('Conversation ID:', data.conversationId);
  }
};

eventSource.onerror = (error) => {
  console.error('SSE Error:', error);
  eventSource.close();
};

Alternative: Using fetch with ReadableStream (supports custom headers):

const requestData = {
  q: "red dress",
  sessionId: "session-001",
  userId: "user-456"
};

const payload = btoa(JSON.stringify(requestData));
const url = `https://ecom.marqo-ep.ai/api/v1/indexes/my-ecom-store/agentic-search/converse?payload=${encodeURIComponent(payload)}`;

const response = await fetch(url, {
  method: 'GET',
  headers: {
    'x-marqo-index-id': 'abc123-my-ecom-store'
  }
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  // Parse SSE events from chunk
  const lines = chunk.split('\n');
  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      // Handle data...
    }
  }
}