Responses

npm i @xsai-ext/responses

The xsAI Responses API implementation, primarily targeting Open Responses.

Responses API support is experimental and may change significantly in minor version updates.

Usage

Use this package when you explicitly need Responses API semantics instead of Chat Completions.

Basic

import {  } from '@xsai-ext/responses'
import {  } from 'node:process'

const { , , ,  } = ({
  : .!,
  : 'https://api.openai.com/v1/',
  : 'Why is the sky blue?',
  : 'You are a helpful assistant.',
  : 'gpt-5.5',
  : { : 'low' },
})

let  = ''
for await (const  of ) {
   += 
}

let  = ''
for await (const  of ) {
   += 
}

.()
.()
.(await )
.(await )

Input

import {  } from '@xsai-ext/responses'
import {  } from 'node:process'

const {  } = ({
  : .!,
  : 'https://api.openai.com/v1/',
  : [
    {
      : [{
        : 'Answer briefly and mention only what is clearly visible.',
        : 'input_text',
      }],
      : 'developer',
      : 'message',
    },
    {
      : [
        {
          : 'What is in this image?',
          : 'input_text',
        },
        {
          : 'https://upload.wikimedia.org/wikipedia/commons/3/3f/Fronalpstock_big.jpg',
          : 'input_image',
        },
      ],
      : 'user',
      : 'message',
    },
  ],
  : 'gpt-5.5',
})

let  = ''
for await (const  of ) {
   += 
}

.()

Tool calling

@xsai-ext/responses can automatically execute tools and feed the tool results back into the next Responses step.

import { ,  } from '@xsai-ext/responses'
import {  } from '@xsai/tool'
import {  } from 'node:process'
import * as  from 'zod'

const  = await ({
  : 'Adds two numbers',
  : ({ ,  }) => (.() + .()).(),
  : 'add',
  : .({
    : .().('First number'),
    : .().('Second number'),
  }),
})

const { ,  } = ({
  : .!,
  : 'https://api.openai.com/v1/',
  : 'What is 12 + 30? Use the add tool.',
  : 'You are a helpful assistant.',
  : 'gpt-5.5',
  : (2), 
  : 'required', 
  : [], 
})

let  = ''
for await (const  of ) {
   += 
}

.()
.(await )

Event streams

This package exposes two event layers:

fullStream: raw Responses API streaming events
eventStream: normalized xsAI events such as text.delta, reasoning.delta, tool-call.start, and step.done

Use fullStream if you need protocol-level fidelity. Use eventStream if you want a smaller, implementation-oriented event surface.

import {  } from '@xsai-ext/responses'
import {  } from 'node:process'

const { ,  } = ({
  : .!,
  : 'https://api.openai.com/v1/',
  : 'Give me a one sentence answer.',
  : 'gpt-5.5',
})

for await (const  of ) {
  .(.)
}

for await (const  of ) {
  .(.)
}

Return value

responses() returns:

textStream: streamed assistant text deltas
reasoningTextStream: streamed reasoning deltas when the model emits them
eventStream: normalized xsAI events
fullStream: raw Responses API events
input: normalized Responses input items
steps: completed step list with text, tool calls, tool results, finish reason, and usage
usage: usage for the latest completed step
totalUsage: accumulated usage across all steps

Notes

This package only supports streaming mode. Do not pass stream.
input accepts either a plain string or Responses API item arrays.
tools uses the same Tool shape as the rest of xsAI.
stopWhen and related helpers such as stepCountAtLeast, and, or, not, and hasToolCall are re-exported from this package.