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/fashionnova/agentic-search/chat-suggestions' \
  --header 'Content-Type: application/json' \
  --header 'x-marqo-index-id: abc123-fashionnova' \
  --data '{
    "documentId": "273301208",
    "sessionId": "session-abc123",
    "userId": "user-28389290",
    "maxSuggestions": 5,
    "minSuggestions": 1,
    "contextFields": ["material", "description"]
  }'

Example Response:

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

The response contains a chatSuggestions 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: POST /indexes/{index_name}/agentic-search/converse

Headers:

Content-Type: application/json
Accept: text/event-stream (required for streaming)
x-marqo-index-id: {index_id} (required)

Request Parameters:

Parameter	Type	Required	Default	Description
`q`	string	Yes	-	User query
`sessionId`	string	Yes	-	Session identifier
`userId`	string	Yes	-	User identifier
`conversationId`	integer	No	-	Conversation identifier 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 -X POST 'https://ecom.marqo-ep.ai/api/v1/indexes/fashionnova/agentic-search/converse' \
  --header 'Content-Type: application/json' \
  --header 'Accept: text/event-stream' \
  --header 'x-marqo-index-id: abc123-fashionnova' \
  --data '{
    "conversationId": 217309279021,
    "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"
    ]
  }'

Example Request: Simple Query

curl -X POST 'https://ecom.marqo-ep.ai/api/v1/indexes/fashionnova/agentic-search/converse' \
  --header 'Content-Type: application/json' \
  --header 'Accept: text/event-stream' \
  --header 'x-marqo-index-id: abc123-fashionnova' \
  --data '{
    "conversationId": 98765,
    "q": "red dress",
    "sessionId": "session-001",
    "userId": "user-456"
  }'

Get Conversation

Retrieve conversation history and details using a conversation ID. This endpoint allows you to fetch the full conversation context, including previous queries and responses.

Endpoint: GET /indexes/{index_name}/agentic-search/conversations/{conversation_id}

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

Path Parameters:

Parameter	Type	Required	Description
`conversation_id`	integer	Yes	The conversation identifier

Example Request:

curl -X GET 'https://ecom.marqo-ep.ai/api/v1/indexes/fashionnova/agentic-search/conversations/217309279021' \
  --header 'x-marqo-index-id: abc123-fashionnova'

Example Response:

{
  "conversationId": 217309279021,
  "userId": "user-123",
  "sessionId": "session-xyz789",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:45:00Z",
  "messages": [
    {
      "query": "I need outfits for a tropical vacation",
      "timestamp": "2025-01-15T10:30:00Z",
      "response": {
        "categories": ["Summer Dresses", "Swimwear", "Beach Accessories"],
        "message": "Perfect! Here are some great options for your tropical vacation:"
      }
    },
    {
      "query": "What about something more formal?",
      "timestamp": "2025-01-15T10:35:00Z",
      "response": {
        "categories": ["Evening Wear", "Cocktail Dresses"],
        "message": "For more formal occasions, here are some elegant options:"
      }
    }
  ]
}

Response Fields:

conversationId: The conversation identifier
userId: User identifier associated with the conversation
sessionId: Session identifier
createdAt: ISO 8601 timestamp when conversation was created
updatedAt: ISO 8601 timestamp when conversation was last updated
messages: Array of conversation messages
query: User's query
timestamp: ISO 8601 timestamp of the message
response: Response details including categories and message

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:

const eventSource = new EventSource(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'text/event-stream',
    'x-marqo-index-id': 'your-index-id'
  },
  body: JSON.stringify(requestData)
});

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.messageHits) {
    // Handle message
    console.log('Message:', data.messageHits);
  }
};