Skip to main content

​
Method Signature

constructorio.agent.getAgentResultsStream(intent, parameters)
Retrieve a stream of agent results from Constructor.io API. This method returns a ReadableStream that emits various event types containing search results, content, and metadata based on the provided user intent.

​
Parameters

​
intent
string
required
The user’s intent or query to use for performing intent-based recommendations. This should be a natural language description of what the user is looking for.Example: "I want to get shoes", "show me running gear for marathons"
​
parameters
object
Additional parameters to refine the result set
​
parameters.domain
string
required
Domain name to scope the search results. Examples: "swimming_sports_gear", "groceries", "nike_sportswear"
​
parameters.numResultsPerPage
number
The total number of results to return per page
​
parameters.filters
object
Additional filters to apply to the search results

​
Returns

​
ReadableStream
ReadableStream
Returns a ReadableStream that emits events as they are received from the server. Each chunk in the stream contains:
​
type
string
The event type. Possible values: "start", "group", "search_result", "article_reference", "recipe_info", "recipe_instructions", "server_error", "image_meta", "end"
​
data
object
The event data payload. Structure varies based on event type.

​
Example: Basic Usage

const ConstructorIO = require('@constructor-io/constructorio-client-javascript');

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

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

const reader = stream.getReader();
const { value, done } = await reader.read();

if (!done) {
  console.log('Event type:', value.type);
  console.log('Event data:', value.data);
}

​
Example: Processing All Events

const stream = constructorio.agent.getAgentResultsStream(
  'show me running shoes for women',
  {
    domain: 'athletic_footwear',
    numResultsPerPage: 20
  }
);

const reader = stream.getReader();

try {
  while (true) {
    const { value, done } = await reader.read();
    
    if (done) {
      console.log('Stream completed');
      break;
    }
    
    // Process each event
    console.log(`Received event: ${value.type}`);
    
    switch (value.type) {
      case 'start':
        console.log('Stream started');
        break;
      case 'search_result':
        console.log('Search results:', value.data);
        break;
      case 'group':
        console.log('Result group:', value.data);
        break;
      case 'server_error':
        console.error('Server error:', value.data);
        break;
    }
  }
} catch (error) {
  console.error('Stream error:', error);
}

​
Example: With Filters

const stream = constructorio.agent.getAgentResultsStream(
  'find me laptops for gaming',
  {
    domain: 'electronics',
    numResultsPerPage: 15,
    filters: {
      brand: ['Dell', 'HP', 'Lenovo'],
      price_range: '1000-2000'
    }
  }
);

const reader = stream.getReader();
const { value, done } = await reader.read();

​
Example: Recipe Search with Multiple Event Types

const stream = constructorio.agent.getAgentResultsStream(
  'pasta carbonara recipe',
  {
    domain: 'recipes',
    numResultsPerPage: 5
  }
);

const reader = stream.getReader();
const results = [];

while (true) {
  const { value, done } = await reader.read();
  
  if (done) break;
  
  if (value.type === 'recipe_info') {
    console.log('Cooking time:', value.data.cookingTime);
    console.log('Servings:', value.data.servings);
  }
  
  if (value.type === 'recipe_instructions') {
    console.log('Instructions:', value.data.steps);
  }
  
  if (value.type === 'search_result') {
    results.push(value.data);
  }
}

console.log('Total results:', results.length);

​
Example: Early Stream Cancellation

const stream = constructorio.agent.getAgentResultsStream(
  'show me all products',
  { domain: 'general' }
);

const reader = stream.getReader();
let eventCount = 0;

try {
  while (true) {
    const { value, done } = await reader.read();
    
    if (done) break;
    
    eventCount++;
    console.log(`Event ${eventCount}:`, value.type);
    
    // Cancel stream after 5 events
    if (eventCount >= 5) {
      await reader.cancel();
      console.log('Stream cancelled early');
      break;
    }
  }
} catch (error) {
  console.error('Error:', error);
}

​
Error Handling

The method throws an error if:
  • intent is not provided or is not a string
  • parameters.domain is not provided or is not a string
  • The EventSource connection fails
try {
  const stream = constructorio.agent.getAgentResultsStream('find shoes', {
    domain: 'footwear'
  });
  
  const reader = stream.getReader();
  
  while (true) {
    const { value, done } = await reader.read();
    
    if (done) break;
    
    // Check for server errors
    if (value.type === 'server_error') {
      console.error('Server returned an error:', value.data);
      await reader.cancel();
      break;
    }
  }
} catch (error) {
  // Handle client-side errors
  console.error('Failed to get agent results:', error.message);
}

​
Event Types Reference

Refer to the Agent Overview for detailed information about all available event types.

​
Notes

  • The domain parameter is required and must be a string
  • The stream uses Server-Sent Events (SSE) under the hood via EventSource
  • The stream automatically closes when the END event is received
  • You can cancel the stream at any time using reader.cancel()
  • All events except END and errors are enqueued into the stream
  • The method is asynchronous and returns immediately with a ReadableStream

Build docs developers (and LLMs) love

Get started for freeTalk to us