Skip to main content

​
Overview

The Agent module provides an interface to Constructor.io’s AI Agent service through Server-Sent Events (SSE). It allows you to retrieve streaming responses based on user intents, enabling real-time conversational search experiences. This module replaces the previous Assistant module and provides enhanced functionality for intent-based recommendations.

​
Accessing the Agent Module

The Agent module is accessible via the agent property on the Constructor.io client instance: 
const ConstructorIO = require('@constructor-io/constructorio-client-javascript');

const constructorio = new ConstructorIO({
  apiKey: 'YOUR_API_KEY',
  version: 'cio-js-1.0.0'
});

// Access agent module
const agentStream = constructorio.agent.getAgentResultsStream('I want to get shoes', {
  domain: 'nike_sportswear'
});

​
Event Types

The Agent module provides several event types that can be emitted during a streaming response:
​
EventTypes
object
Static property containing all possible event types that may be emitted during an agent response stream.
​
START
string
default:"start"
Denotes the start of the stream
​
GROUP
string
default:"group"
Represents a semantic grouping of search results, optionally having textual explanation
​
SEARCH_RESULT
string
default:"search_result"
Represents a set of results with metadata (used to show results with search refinements)
​
ARTICLE_REFERENCE
string
default:"article_reference"
Represents a set of content with metadata
​
RECIPE_INFO
string
default:"recipe_info"
Represents recipes’ auxiliary information like cooking times & serving sizes
​
RECIPE_INSTRUCTIONS
string
default:"recipe_instructions"
Represents recipe instructions
​
SERVER_ERROR
string
default:"server_error"
Server Error event
​
IMAGE_META
string
default:"image_meta"
Event type used for enhancing recommendations with media content such as images
​
END
string
default:"end"
Represents the end of data stream

​
Example: Accessing Event Types

const Agent = require('@constructor-io/constructorio-client-javascript/lib/modules/agent');

console.log(Agent.EventTypes.START); // 'start'
console.log(Agent.EventTypes.SEARCH_RESULT); // 'search_result'
console.log(Agent.EventTypes.END); // 'end'

​
Methods

getAgentResultsStream

Retrieve a stream of agent results based on user intent

​
Common Use Cases

const stream = constructorio.agent.getAgentResultsStream('I want running shoes for marathons', {
  domain: 'athletic_footwear'
});

const reader = stream.getReader();

while (true) {
  const { value, done } = await reader.read();
  
  if (done) break;
  
  console.log('Event type:', value.type);
  console.log('Event data:', value.data);
}

​
Handling Specific Event Types

const stream = constructorio.agent.getAgentResultsStream('show me pasta recipes', {
  domain: 'recipes',
  numResultsPerPage: 10
});

const reader = stream.getReader();

while (true) {
  const { value, done } = await reader.read();
  
  if (done) break;
  
  switch (value.type) {
    case 'search_result':
      // Handle search results
      console.log('Search results:', value.data);
      break;
    case 'recipe_info':
      // Handle recipe metadata
      console.log('Recipe info:', value.data);
      break;
    case 'recipe_instructions':
      // Handle recipe instructions
      console.log('Instructions:', value.data);
      break;
    case 'server_error':
      // Handle errors
      console.error('Error:', value.data);
      break;
  }
}

​
Error Handling

try {
  const stream = constructorio.agent.getAgentResultsStream('find me laptops', {
    domain: 'electronics'
  });
  
  const reader = stream.getReader();
  
  while (true) {
    const { value, done } = await reader.read();
    
    if (done) break;
    
    if (value.type === 'server_error') {
      console.error('Server error occurred:', value.data);
      break;
    }
    
    // Process other event types
  }
} catch (error) {
  console.error('Failed to get agent results:', error.message);
}

​
Notes

  • The Agent module uses Server-Sent Events (SSE) to provide real-time streaming responses
  • All events are delivered through a ReadableStream that can be consumed using the Streams API
  • The stream automatically closes when the END event is received
  • Always handle potential errors by checking for server_error event types
  • The domain parameter is required for all agent requests

Build docs developers (and LLMs) love

Get started for freeTalk to us