Python SDKAgents (Research preview)

Responses

The ResponsesClient 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:

1def create(
2    self,
3    *,
4    knowledge_store_id: str,
5    input: typing.Sequence[ResponseInputItem],
6    session_id: typing.Optional[str] = OMIT,
7    instructions: typing.Optional[str] = OMIT,
8    include: typing.Optional[typing.Sequence[ResponsesCreateRequestIncludeItem]] = OMIT,
9    selections: typing.Optional[typing.Sequence[ResponseSelection]] = OMIT,
10    text: typing.Optional[TextParam] = OMIT,
11    request_options: typing.Optional[RequestOptions] = None,
12) -> ResponseObject:

Parameters

NameTypeRequiredDescription
knowledge_store_idstrYesThe unique identifier of the knowledge store to reason over.
inputtyping.
Sequence
[ResponseInputItem]		YesProvides context to Jockey for this request. Uses Open Responses input item conventions.
session_idtyping.
Optional[str]		NoThe 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 knowledge_store_id field must match the knowledge store the session was originally created against, or the request returns 400.
instructionstyping.
Optional[str]		NoAdditional guidance for Jockey, acting as a per-request system prompt.
includetyping.
Optional
[typing.Sequence
[...IncludeItem]]		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.
selectionstyping.
Optional
[typing.Sequence
[ResponseSelection]]		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.
texttyping.
Optional
[TextParam]		NoControls the output text format for the response.
request_optionstyping.
Optional
[RequestOptions]		NoPer-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

The ResponseInputItem class contains the following properties:

NameTypeRequiredDescription
typeResponseInput
ItemType		YesThe type of input item. Values: message.
roleResponseInput
ItemRole		YesThe role of the message author. Values: user.
contentstrYesThe 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 class 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.
idstrYesThe unique identifier of the selected resource. Must use the prefix that matches the kind field: ksi_ for items and ksic_ for collections.

The TextParam class contains the following property:

NameTypeRequiredDescription
formatOptional
[TextParamFormat]		NoThe output format for the response text. Defaults to plain text. Use TextParamFormat_JsonSchema to receive a structured JSON object conforming to a provided schema.

The TextParamFormat_JsonSchema class contains the following properties:

NameTypeRequiredDescription
namestrYesThe name of the schema.
schema_typing.Dict
[str, Any]		YesThe JSON Schema the response must conform to. Sent on the wire as schema.
descriptionOptional[str]NoAn optional description of the schema.
strictOptional[bool]NoWhether Jockey must strictly conform to the schema.

Return value

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

NameTypeDescription
idOptional[str]A unique identifier for this response.
knowledge_store_idOptional[str]The unique identifier of the knowledge store this response was generated against.
session_idOptional[str]The session identifier for this conversation. Pass this value in subsequent requests to continue the multi-turn conversation.
typeOptional
[ResponseObjectType]		The object type. Always response.
statusOptional
[ResponseStatus]		The status of the response. Values: completed, failed, in_progress, incomplete.
outputOptional
[typing.List
[ResponseOutputItem]]		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.
usageOptional
[ResponseUsage]		Token usage for the response.
created_atOptional
[datetime]		The timestamp when the response was created.

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 iterator of ResponseStreamEvent objects. For the non-streaming variant, see Create a response.

Function signature and example:

1def create_stream(
2    self,
3    *,
4    knowledge_store_id: str,
5    input: typing.Sequence[ResponseInputItem],
6    session_id: typing.Optional[str] = OMIT,
7    instructions: typing.Optional[str] = OMIT,
8    include: typing.Optional[typing.Sequence[ResponsesCreateStreamRequestIncludeItem]] = OMIT,
9    selections: typing.Optional[typing.Sequence[ResponseSelection]] = OMIT,
10    text: typing.Optional[TextParam] = OMIT,
11    request_options: typing.Optional[RequestOptions] = None,
12) -> typing.Iterator[ResponseStreamEvent]:

Parameters

This method accepts the same parameters as Create a response.

Return value

Returns an iterator of ResponseStreamEvent objects. Each event carries a type field that identifies the event. For example, response.output_text.delta events carry incremental output text in a delta field, and a response.completed event signals the end of the stream.

API Reference

Create a response.

Streaming.