Node.js SDKAgents (Research preview)

Responses

The Responses class provides methods to reason over the content in a knowledge store and generate responses.

Methods

Create a response

Description: This method uses Jockey to reason over content in a knowledge store and create a response. It uses Open Responses conventions for input items and streaming events.

Before you use this method, you must create an asset, create a knowledge store, and add the asset to the knowledge store as an item.

Multi-turn conversations: Supported via a session identifier. The first request implicitly creates a session; subsequent requests pass the returned identifier to continue the conversation.

Selections: By default, Jockey reasons over every item in the knowledge store. To narrow the scope, set the optional selections parameter to specific items or item collections, then reference each one with a {{sel:N}} token in the content field of an input item (N is the zero-based position in the selections array). The narrowing is applied at the prompt level; the knowledge store does not block access to other items.

Streaming: To receive the response as Server-Sent Events (SSE), use Stream a response.

Function signature and example:

create(
  request: TwelvelabsApi.ResponsesCreateRequest,
  requestOptions?: Responses.RequestOptions
): Promise<TwelvelabsApi.ResponseObject>

Parameters

NameTypeRequiredDescription
knowledgeStoreIdstringYesThe unique identifier of the knowledge store to reason over.
inputResponseInputItem[]YesProvides context to Jockey for this request. Uses Open Responses input item conventions.
sessionIdstringNoThe session identifier for a multi-turn conversation. Pass the session identifier returned from a previous response to continue that conversation. Omit to start a new session. When provided, the knowledgeStoreId field must match the knowledge store the session was originally created against, or the request returns 400.
instructionsstringNoAdditional guidance for Jockey, acting as a per-request system prompt.
includeResponsesCreate
RequestIncludeItem[]		NoAdditional items to include in the response’s output array. By default, the output array contains only Jockey’s final reply.
- intermediate_outputs: Also includes the steps Jockey took to produce the reply.
selectionsResponseSelection[]NoRestricts the request to specific knowledge store items or item collections. The restriction is applied at the prompt level; the knowledge store does not block access to other items. Treat it as a strong preference, not a hard access boundary. Omit to run against every item. Selections persist for the session. Selections sent on later turns add to the set, so you can keep referencing earlier {{sel:N}} tokens without resending them.
textTextParamNoControls the output text format for the response.
requestOptionsResponses.
RequestOptions		NoPer-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

The ResponseInputItem object contains the following properties:

NameTypeRequiredDescription
typeResponseInput
ItemType		YesThe type of input item. Values: message.
roleResponseInput
ItemRole		YesThe role of the message author. Values: user.
contentstringYesThe message text, as a plain string. Must be between 1 and 10,000 characters. To narrow the message to a specific knowledge store item or item collection, include a {{sel:N}} token in the content, where N is the zero-based position in the selections array.

The ResponseSelection object contains the following properties:

NameTypeRequiredDescription
kindResponseSelectionKindYesThe type of resource to select.
- item: A single knowledge store item.
- collection: A knowledge store item collection. All items in the collection are included in the request.
idstringYesThe unique identifier of the selected resource. Must use the prefix that matches the kind field: ksi_ for items and ksic_ for collections.

The TextParam object contains the following property:

NameTypeRequiredDescription
formatTextParamFormatNoThe output format for the response text. Defaults to plain text. Set type to json_schema to receive a structured JSON object conforming to a provided schema.

When format.type is json_schema, the format object contains the following properties:

NameTypeRequiredDescription
namestringYesThe name of the schema.
schemaRecord
<string, unknown>		YesThe JSON Schema the response must conform to.
descriptionstringNoAn optional description of the schema.
strictbooleanNoWhether Jockey must strictly conform to the schema.

Return value

Returns a ResponseObject object. The ResponseObject object contains the following properties:

NameTypeDescription
idstringA unique identifier for this response.
knowledgeStoreIdstringThe unique identifier of the knowledge store this response was generated against.
sessionIdstringThe session identifier for this conversation. Pass this value in subsequent requests to continue the multi-turn conversation.
typeResponseObjectTypeThe object type. Always response.
objectResponseObjectObjectThe object type, always response. It has the same value as the type field.

Only the response itself has an object field. Output items, annotations, and stream events are identified by type alone and have no object field.
statusResponseStatusThe status of the response. Values: completed, failed, in_progress, incomplete.
outputResponseOutputItem[]The response output items. By default, only the final message is included. Set include to ["intermediate_outputs"] in the request to receive function call items. Each message item has a phase field: the commentary value identifies intermediate output, and the final_answer value identifies the answer. A message without the phase field is the final answer.
incompleteDetailsResponseIncompleteDetailsThe reason the response was truncated before the answer was complete. Always sent. Contains a value only when the status field is incomplete; the value is null on every other status, including in_progress and failed. A null value means the answer was not truncated.

If the reason field contains a value you do not recognize, treat the response as truncated for an unknown reason, not as an error. The text in the response is an incomplete answer, not the full one.
usageResponseUsageToken usage for the response.
createdAtstringThe timestamp when the response was created.

The ResponseOutputItem object contains the following properties:

NameTypeDescription
typeResponseOutputItemTypeThe type of output item. Values: message, function_call, function_call_output.
idstringA unique identifier for this item.
statusResponseStatusThe status of the item. Values: completed, failed, in_progress, incomplete.
roleResponseOutputItemRoleThe role of the message author. Present when type is message. Values: assistant.
phasestringWhich part of the turn this message contains: intermediate output or the answer. Present when the type field is message. Treat an unrecognized phase value as intermediate output, not as the answer.
contentResponseOutputContentPart[]The content parts of the message. Present when type is message.
namestringThe name of the function. Present when type is function_call.
callIdstringThe unique identifier for the function call. Present when type is function_call.
argumentsstringThe JSON-encoded arguments for the function call. Present when type is function_call.
outputstringThe function call output. Present when type is function_call_output.

The ResponseOutputContentPart object contains the following properties:

NameTypeDescription
typeResponseOutputContentPartTypeThe type of content part. Values: output_text.
textstringThe text content. It may contain citation markers, each a number in square brackets such as [1]. The start_index and end_index fields of a citation indicate the location of its marker. To resolve a marker, find the citation at that location. Not every marker has a matching citation; when a marker has none, treat it as a citation you cannot display, not as an error.
annotationsResponseAnnotation[]Citations that tie spans of the text field to what they cite, in order of appearance. Always present, and may be empty. The start_index and end_index fields locate the marker within the text field of this content part, not within the whole response.

For the full list of fields on each citation in the annotations array, see Create a response.

API Reference

Create a response.

Create a response.

Stream a response

Description: This method uses Jockey to reason over content in a knowledge store and create a response, streamed as Server-Sent Events (SSE). It returns an async-iterable stream of ResponseStreamEvent objects. For the non-streaming variant, see Create a response.

Function signature and example:

createStream(
  request: TwelvelabsApi.ResponsesCreateStreamRequest,
  requestOptions?: Responses.RequestOptions
): Promise<core.Stream<TwelvelabsApi.ResponseStreamEvent>>

Parameters

This method accepts the same parameters as Create a response.

Return value

Returns an async-iterable Stream<ResponseStreamEvent>. Each event has a type field that identifies the event; unlike the response object, events have no object field. For example, response.output_text.delta events deliver incremental output text in a delta field, and a response.completed event signals the end of the stream. When you request intermediate outputs, the response.output_item.added event delivers each message with its phase field already set, so you can identify intermediate output or the answer before any of its text streams in. Citations do not stream in with the text: the annotations array is empty while a content part is being generated, and the response.content_part.done event contains the completed part with all of its citations.

API Reference

Create a response.

Streaming.