ResponsesCodec

ResponsesCodec is the pre-built codec for the OpenAI Responses API. It implements Codec<OpenAIInput, OpenAIOutput, OpenAIProjection, OpenAIMessage>, so a session encodes a ResponseStreamEvent stream out and decodes it back into OpenAIMessage objects without a custom implementation.

It is a single codec value, so you pass ResponsesCodec itself and never call it. It takes no type parameters, and one instance serves every session in the process.

On the agent, bind it to the session:

import { createAgentSession } from '@ably/ai-transport';
import { ResponsesCodec } from '@ably/ai-transport/openai';

const session = createAgentSession({
  client: ably,
  channelName: invocation.sessionName,
  codec: ResponsesCodec,
});

On the client, the same value goes to the React provider:

'use client';

import { ClientSessionProvider } from '@ably/ai-transport/react';
import { ResponsesCodec } from '@ably/ai-transport/openai';

<ClientSessionProvider channelName="conversations:demo" codec={ResponsesCodec}>
  <Chat />
</ClientSessionProvider>

You rarely call the methods below yourself. A session drives init, fold, createEncoder, createDecoder, and getMessages for you. The methods you do call are createUserMessage, to send a user turn, and the three tool factories, to answer a tool call from the client.

Properties

Tool payloads

The three tool factories take a payload keyed by OpenAI's snake_case call_id, taken from the function_call being answered. The Vercel codec uses toolCallId for the same purpose, so the two are not interchangeable.

An approval records a decision and produces no output, so the agent runs an approved call server-side when it resumes. A denial needs no server execution, because the reducer folds a rejection function_call_output on the client. Conversation helpers covers reading that state back.

Types

The event inventory is total, so an event outside it throws at the encoder rather than being dropped. An agent that enables a hosted tool (web or file search, code interpreter, image generation, MCP, custom tools) or audio must filter those events out of the stream before piping it, as Scope and trade-offs describes.

The well-known input variants (UserMessage, Regenerate, ToolResult, ToolResultError, ToolApprovalResponse) are documented on the Codec reference page.

Example

Decode a single Ably message and fold the resulting events into a fresh projection. ReducerMeta.serial is required, because the reducer uses it as the high-water-mark for idempotency.

import { ResponsesCodec } from '@ably/ai-transport/openai';

const decoder = ResponsesCodec.createDecoder();
let projection = ResponsesCodec.init();

channel.subscribe((message) => {
  if (!message.serial) return; // live channel-subscribe messages always carry one
  const { inputs, outputs } = decoder.decode(message);
  for (const input of inputs) {
    projection = ResponsesCodec.fold(projection, input, { serial: message.serial });
  }
  for (const output of outputs) {
    projection = ResponsesCodec.fold(projection, output, { serial: message.serial });
  }
  render(ResponsesCodec.getMessages(projection).map((entry) => entry.message));
});

Read next

• Conversation helpers: toResponsesInput and the correlation readers that drive the agent loop.
• OpenAI Responses: how the codec fits an agent, including the tool and approval flow.
• Codec: the generic Codec interface and the well-known input variants.