openai 7.25.0 → 7.26.0

package/src/internal/ws.ts

@@ -1,6 +1,7 @@
 import { concatBytes, encodeUTF8 } from './utils/bytes';
 import { OpenAIError } from '../core/error';
 import type { WebSocketLike } from './ws-adapter';
+import type { OpenAI } from '../client';
 
 const webSocketErrors = new WeakMap<WebSocketLike, Error>();
 
@@ -73,7 +74,7 @@ export type ReconnectingOverrides<Parameters = Record<string, unknown>> =
  */
 export type RawWebSocketData = string | ArrayBufferLike | ArrayBufferView | ArrayBufferView[];
 
-interface CredentialedWebSocketOptions {
+export interface CredentialedWebSocketOptions {
   auth?: string | null | undefined;
   followRedirects?: boolean | undefined;
   headers?: object | null | undefined;
@@ -99,19 +100,57 @@ const REDIRECT_SAFE_WEBSOCKET_HEADERS = new Set([
   'x-trace-id',
 ]);
 
+const WEBSOCKET_METADATA_HEADER_NAMES = new Set([
+  'accept',
+  'accept-encoding',
+  'accept-language',
+  'content-type',
+  'x-request-id',
+  'x-client-request-id',
+  'x-correlation-id',
+  'traceparent',
+  'tracestate',
+  'sentry-trace',
+  'x-amzn-trace-id',
+  'x-cloud-trace-context',
+  'x-datadog-trace-id',
+  'x-datadog-parent-id',
+  'x-datadog-sampling-priority',
+  'x-datadog-origin',
+  'x-datadog-tags',
+  'baggage',
+  'b3',
+]);
+
+// Request and tracing metadata do not authenticate a Responses socket, but remain protected on redirects.
+export const WEBSOCKET_METADATA_HEADERS = {
+  has: (name: string, values: readonly unknown[]): boolean =>
+    WEBSOCKET_METADATA_HEADER_NAMES.has(name) ||
+    name.startsWith('x-b3-') ||
+    (name === 'sec-websocket-protocol' &&
+      !values.some(
+        (value) =>
+          typeof value === 'string' &&
+          value.split(',').some((protocol) => protocol.trim().startsWith('openai-insecure-api-key.')),
+      )),
+};
+
 function isWebSocketCredentialHeader(name: string): boolean {
   return !REDIRECT_SAFE_WEBSOCKET_HEADERS.has(name.toLowerCase().split('_').join('-'));
 }
 
 /**
  * Snapshots credential values in final socket options before validation and dispatch.
- * Reports potential caller authentication, including custom headers; the server
- * remains responsible for validating credentials. Noncredential headers are left intact.
+ * Reports potential caller authentication, excluding additional metadata when requested.
+ * The server remains responsible for validating credentials. Noncredential headers are left intact.
  */
-export function snapshotWebSocketCredentials(options: {
-  auth?: unknown;
-  headers?: Record<string, unknown> | undefined;
-}): boolean {
+export function snapshotWebSocketCredentials(
+  options: {
+    auth?: unknown;
+    headers?: Record<string, unknown> | undefined;
+  },
+  metadataHeaders?: { has: (name: string, values: readonly unknown[]) => boolean },
+): boolean {
   if (options.auth !== null && options.auth !== undefined) {
     options.auth = String(options.auth);
   }
@@ -135,10 +174,12 @@ export function snapshotWebSocketCredentials(options: {
     }
     headers[name] = snapshot;
     const values = Array.isArray(snapshot) ? snapshot : [snapshot];
-    credentials.set(
-      name.toLowerCase(),
-      values.some((item) => typeof item === 'string' && item.trim().length > 0),
-    );
+    if (!metadataHeaders?.has(normalizedName, values)) {
+      credentials.set(
+        name.toLowerCase(),
+        values.some((item) => typeof item === 'string' && item.trim().length > 0),
+      );
+    }
   }
   // Node applies header names case-insensitively, and Authorization overrides Basic auth.
   return (
@@ -147,6 +188,93 @@ export function snapshotWebSocketCredentials(options: {
   );
 }
 
+/** Merge transport authentication before explicit caller overrides and header removals. */
+export function mergeWebSocketAuthHeaders<Options extends CredentialedWebSocketOptions>(
+  options: Options,
+  authHeaders: Record<string, string>,
+  removedHeaders: ReadonlySet<string>,
+) {
+  const headers = new Map(Object.entries(authHeaders).map(([name, value]) => [name.toLowerCase(), value]));
+  for (const name of removedHeaders) {
+    headers.delete(name);
+  }
+  for (const [name, value] of Object.entries(options.headers ?? {})) {
+    headers.set(name, value);
+  }
+  return { ...options, headers: Object.fromEntries(headers) };
+}
+
+/** Removal sink for one synchronous header-hook call, including legacy one-argument overrides. */
+export const webSocketHeaderRemovals = new WeakMap<
+  OpenAI,
+  { removedHeaders: Set<string> | undefined; baseHeaders: Record<string, string> | undefined }
+>();
+const preparedWebSocketHeaders = new WeakMap<
+  object,
+  { baseHeaders: Record<string, string> | undefined; transportHeaders: Map<string, boolean> }
+>();
+
+/** Build a WebSocket handshake with explicit caller headers applied after the client defaults. */
+export function buildWebSocketOptions<Options extends Pick<CredentialedWebSocketOptions, 'headers'>>(
+  client: OpenAI,
+  authHeaders: Record<string, string>,
+  options: Options | null | undefined,
+  removedHeaders?: Set<string>,
+  usePreparedHeaders = false,
+) {
+  // Capture the base result even through older overrides that forward only one argument.
+  const previous = webSocketHeaderRemovals.get(client);
+  const prepared = usePreparedHeaders && options ? preparedWebSocketHeaders.get(options) : undefined;
+  const context: NonNullable<ReturnType<typeof webSocketHeaderRemovals.get>> = {
+    removedHeaders,
+    baseHeaders: prepared?.baseHeaders,
+  };
+  webSocketHeaderRemovals.set(client, context);
+  let headers: Map<string, string>;
+  try {
+    headers = new Map(
+      Object.entries(client._buildWebSocketHeaders(authHeaders, removedHeaders)).map(([name, value]) => [
+        name.toLowerCase(),
+        value,
+      ]),
+    );
+  } finally {
+    if (previous) {
+      webSocketHeaderRemovals.set(client, previous);
+    } else {
+      webSocketHeaderRemovals.delete(client);
+    }
+  }
+  // The first hook output is not a caller override of the final, credentialed hook.
+  // Save transport names and explicit nulls separately, then reuse their validated values.
+  const transportHeaders = new Map<string, boolean>();
+  const currentHeaders = new Map(Object.entries(options?.headers ?? {}));
+  const overrides = prepared
+    ? [...prepared.transportHeaders].map(
+        ([name, removed]) => [name, removed ? null : currentHeaders.get(name)] as const,
+      )
+    : currentHeaders;
+  for (const [name, value] of overrides) {
+    const normalizedName = name.toLowerCase();
+    if (value === null) {
+      headers.delete(normalizedName);
+      removedHeaders?.add(normalizedName);
+      transportHeaders.set(normalizedName, true);
+    } else if (value !== undefined) {
+      headers.set(normalizedName, value);
+      removedHeaders?.delete(normalizedName);
+      transportHeaders.set(normalizedName, false);
+    }
+  }
+  const result = {
+    ...options,
+    headers: Object.fromEntries(headers),
+    followRedirects: false,
+  };
+  preparedWebSocketHeaders.set(result, { baseHeaders: context.baseHeaders, transportHeaders });
+  return result;
+}
+
 /** Prevents WebSocket redirects from forwarding caller or SDK credentials to another origin. */
 export function protectWebSocketOptionsFromCredentialRedirects<Options extends CredentialedWebSocketOptions>(
   options: Options,

package/src/lib/agents/agent-session-stream.ts

@@ -1,17 +1,20 @@
+import type { AgentOutputFormat, AgentResult } from '../beta/agents/output-format-types';
 import { TurnState } from './turn-state';
+import { agentFormatParser, parseAgentResultPromise } from '../beta/agents/parse-result';
+import { ResultCollection } from '../beta/agents/result-collection';
 import { APIUserAbortError, BadRequestError, OpenAIError } from '../../core/error';
 import type { Stream } from '../../core/streaming';
 import { buildHeaders } from '../../internal/headers';
 import type { RequestOptions } from '../../internal/request-options';
 import { uuid4 } from '../../internal/utils/uuid';
-import { hasOwn, isObj } from '../../internal/utils/values';
+import { isObj } from '../../internal/utils/values';
+import { isInputContent } from '../beta/agents/tool-output';
 import type {
   AgentFunctionCallItem,
   AgentFunctionCallOutputParam,
   AgentSessionEvent,
   AgentSessionInputMessageParam,
   AgentSessionInputParam,
-  InputContentParam,
 } from '../../resources/beta/agents/agents';
 import type { Sessions } from '../../resources/beta/agents/sessions/sessions';
 
@@ -23,33 +26,19 @@ export type AgentToolHandler = (
 ) => AgentToolOutput | PromiseLike<AgentToolOutput>;
 
 /** Input and optional sequential tool handlers for one turn on an idle session. */
-export interface AgentSessionStreamParams {
+export type AgentSessionStreamParams<T = never> = {
+  /** Beta: parse this turn locally; does not change the existing session schema. */
+  outputFormat?: AgentOutputFormat<T>;
   /** User messages, or text normalized to a single user message. Must not be empty. */
   input: string | AgentSessionInputMessageParam[];
   /** Registered functions run after their call event is yielded; unknown functions remain manual. */
   toolHandlers?: Record<string, AgentToolHandler>;
   /** Key for the input submission only; request headers take precedence, case-insensitively. */
   idempotencyKey?: string;
-}
+} & ([T] extends [never] ? unknown : { outputFormat: AgentOutputFormat<T> });
 
 type ToolResult = AgentSessionInputParam.SessionInputParamAgentSessionInputToolResult;
 
-function isInputContent(value: unknown): value is InputContentParam {
-  if (!isObj(value)) {
-    return false;
-  }
-  const content = value;
-  let field: string;
-  if (content['type'] === 'input_text') {
-    field = 'text';
-  } else if (content['type'] === 'input_image') {
-    field = 'image_url';
-  } else {
-    return false;
-  }
-  return hasOwn(content, 'type') && hasOwn(content, field) && typeof content[field] === 'string';
-}
-
 function normalizedOutput(value: unknown): AgentFunctionCallOutputParam | null {
   if (value === null) {
     return null;
@@ -98,10 +87,13 @@ async function cancelBody(response: Response | undefined): Promise<void> {
  * idempotency key. Breaking iteration or calling abort closes local requests;
  * neither cancels the backend turn. No work starts until iteration begins.
  */
-export class AgentSessionStream implements AsyncIterable<AgentSessionEvent> {
+export class AgentSessionStream<T = never> implements AsyncIterable<AgentSessionEvent> {
   /** Aborts local requests and iteration without cancelling the backend turn. */
   readonly controller = new AbortController();
   #consumed = false;
+  #format: AgentOutputFormat<T> | undefined;
+  #parsedResult: Promise<AgentResult<T>> | undefined;
+  #collection: ResultCollection;
   #stream: Stream<AgentSessionEvent> | undefined;
   #response: Response | undefined;
   #reading = false;
@@ -116,7 +108,7 @@ export class AgentSessionStream implements AsyncIterable<AgentSessionEvent> {
   constructor(
     sessions: Sessions,
     sessionID: string,
-    params: AgentSessionStreamParams,
+    params: AgentSessionStreamParams<T>,
     options?: RequestOptions,
   ) {
     const input: AgentSessionInputMessageParam[] =
@@ -126,6 +118,10 @@ export class AgentSessionStream implements AsyncIterable<AgentSessionEvent> {
     if (params.input.length === 0) {
       throw new OpenAIError('input must not be empty');
     }
+    this.#format = agentFormatParser<T>(params.outputFormat);
+    if (params.outputFormat && !this.#format) {
+      throw new OpenAIError('outputFormat must have its own parser function');
+    }
     this.#sessions = sessions;
     this.#sessionID = sessionID;
     this.#input = { type: 'agent.session.input.message', input };
@@ -141,6 +137,11 @@ export class AgentSessionStream implements AsyncIterable<AgentSessionEvent> {
     headers.nulls.delete('idempotency-key');
     const { idempotencyKey: _key, ...rest } = options ?? {};
     this.#options = { ...rest, headers };
+    this.#collection = new ResultCollection(
+      () => this.#iterate(),
+      (name) => this.#handlers.has(name),
+      sessionID,
+    );
   }
 
   /** Closes local requests without cancelling the turn; an optional reason becomes the abort error's cause. */
@@ -158,7 +159,18 @@ export class AgentSessionStream implements AsyncIterable<AgentSessionEvent> {
       throw new OpenAIError('An AgentSessionStream can only be consumed once');
     }
     this.#consumed = true;
-    return this.#iterate();
+    return this.#collection.iterate();
+  }
+
+  /** Beta: opt into retaining completed final messages before iterating progress events. */
+  withResultCollection(): this {
+    this.#collection.enable();
+    return this;
+  }
+
+  /** Beta: drain this turn, dispatch registered tools, and collect its final assistant messages. */
+  finalResult(): Promise<AgentResult<T>> {
+    return (this.#parsedResult ??= parseAgentResultPromise(this.#collection.finalResult(), this.#format));
   }
 
   async *#iterate(): AsyncGenerator<AgentSessionEvent> {
@@ -268,7 +280,7 @@ export class AgentSessionStream implements AsyncIterable<AgentSessionEvent> {
     return error;
   }
 
-  async #wait<T>(action: () => T | PromiseLike<T>): Promise<T> {
+  async #wait<Value>(action: () => Value | PromiseLike<Value>): Promise<Value> {
     let onAbort: (() => void) | undefined;
     // oxlint-disable-next-line promise/avoid-new -- Bridge the caller's AbortSignal while a handler or registration delay is pending.
     const aborted = new Promise<never>((_resolve, reject) => {

package/src/lib/beta/agents/agent-session-create-stream.ts

@@ -0,0 +1,36 @@
+import type { AgentOutputFormat, AgentResult } from './output-format-types';
+import type { Stream } from '../../../core/streaming';
+import type { AgentSessionEvent } from '../../../resources/beta/agents/agents';
+import { parseAgentResultPromise } from './parse-result';
+import { ResultCollection } from './result-collection';
+
+/** Beta: the original creation stream with optional collection of its initial root turn. */
+export type AgentSessionCreateStream<T = never> = Stream<AgentSessionEvent> & {
+  /** Drain through the selected turn's completion and idle event, then return its final messages. */
+  finalResult: () => Promise<AgentResult<T>>;
+  /** Opt into retaining completed final messages before iterating progress events. */
+  withResultCollection: () => AgentSessionCreateStream<T>;
+};
+
+/** Add beta result collection without replacing custom stream instances.
+ * @internal
+ */
+export function withAgentTurnResult<T = never>(
+  stream: Stream<AgentSessionEvent>,
+  format?: AgentOutputFormat<T>,
+): AgentSessionCreateStream<T> {
+  let collection: ResultCollection;
+  stream.__betaTransformIterator((source) => {
+    collection = new ResultCollection(source, undefined, undefined, stream.controller.signal);
+    return () => collection.iterate();
+  });
+  let parsed: Promise<AgentResult<T>> | undefined;
+  const result: AgentSessionCreateStream<T> = Object.assign(stream, {
+    finalResult: () => (parsed ??= parseAgentResultPromise(collection.finalResult(), format)),
+    withResultCollection: (): AgentSessionCreateStream<T> => {
+      collection.enable();
+      return result;
+    },
+  });
+  return result;
+}

package/src/lib/beta/agents/agent-turn-result-collector.ts

@@ -0,0 +1,122 @@
+import type {
+  AgentSession,
+  AgentSessionEvent,
+  AgentSessionAssistantMessage,
+} from '../../../resources/beta/agents/agents';
+import type { Turn } from '../../../resources/beta/agents/sessions/turns';
+import { AgentTurnResult } from './agent-turn-result';
+import { AgentTurnResultError } from './agent-turn-result-error';
+
+/** Accumulates completed items independently of transport and tool execution.
+ * @internal
+ */
+export class AgentTurnResultCollector {
+  #sessionID: string | undefined;
+  #turn: Turn | undefined;
+  #messages = new Map<string, { index: number; message: AgentSessionAssistantMessage }>();
+  #requiredActions: AgentSession['required_actions'] = [];
+  #sessionFailed = false;
+  #terminal = false;
+  #idle = false;
+
+  constructor(sessionID?: string) {
+    this.#sessionID = sessionID;
+  }
+
+  accept(event: AgentSessionEvent): void {
+    if (this.ready) {
+      return;
+    }
+    if ('session' in event) {
+      this.#sessionID ??= event.session.id;
+      this.#requiredActions = structuredClone(event.session.required_actions ?? []);
+      this.#sessionFailed ||= event.type === 'agent.session.failed';
+      this.#idle ||= event.type === 'agent.session.idle' && this.#terminal;
+    }
+    if (event.type === 'agent.session.turn.created' && event.turn.subagent_id === null && !this.#turn) {
+      this.#turn = structuredClone(event.turn);
+      this.#sessionID = event.turn.session_id;
+    }
+    let turnID = 'turn_id' in event ? event.turn_id : undefined;
+    if ('item' in event) {
+      turnID = event.item.turn_id;
+    }
+    if (!this.#turn || turnID !== this.#turn.id) {
+      return;
+    }
+    this.#acceptTurn(event);
+  }
+
+  #acceptTurn(event: AgentSessionEvent): void {
+    if ('turn' in event) {
+      this.#turn = structuredClone(event.turn);
+      this.#terminal ||=
+        event.type === 'agent.session.turn.completed' ||
+        event.type === 'agent.session.turn.failed' ||
+        event.type === 'agent.session.turn.cancelled';
+    }
+    this.#acceptOutput(event);
+  }
+
+  #acceptOutput(event: AgentSessionEvent): void {
+    if (
+      event.type !== 'agent.session.turn.item.done' ||
+      event.item.type !== 'message' ||
+      event.item.status !== 'completed' ||
+      event.item.phase === 'commentary' ||
+      this.#messages.has(event.item.id)
+    ) {
+      return;
+    }
+    this.#messages.set(event.item.id, { index: event.output_index, message: structuredClone(event.item) });
+  }
+
+  #finalMessages(): AgentSessionAssistantMessage[] {
+    return (
+      [...this.#messages.values()]
+        // oxlint-disable-next-line unicorn/no-array-sort -- Sort a fresh array; ES2020 declarations do not include toSorted.
+        .sort((a, b) => a.index - b.index)
+        .map(({ message }) => message)
+    );
+  }
+
+  error(reason: AgentTurnResultError['reason'], cause?: unknown): AgentTurnResultError {
+    return new AgentTurnResultError(
+      reason,
+      this.#sessionID,
+      this.#turn,
+      this.#finalMessages(),
+      this.#requiredActions,
+      cause,
+    );
+  }
+
+  checkAction(canHandle: (name: string) => boolean): void {
+    if (this.#sessionFailed || this.#turn?.status === 'failed') {
+      throw this.error('failed');
+    }
+    if (this.#turn?.status === 'cancelled') {
+      throw this.error('cancelled');
+    }
+    if (this.#requiredActions.some((action) => action.type !== 'function_call' || !canHandle(action.name))) {
+      throw this.error('requires_action');
+    }
+  }
+
+  get ready(): boolean {
+    return this.#terminal && this.#idle;
+  }
+
+  release(): void {
+    this.#messages.clear();
+    this.#requiredActions = [];
+  }
+
+  finish(): AgentTurnResult {
+    this.checkAction(() => this.ready);
+    if (!this.#terminal || this.#turn?.status !== 'completed' || !this.#idle) {
+      throw this.error('observation');
+    }
+    return new AgentTurnResult(this.#turn, this.#finalMessages());
+  }
+}

package/src/lib/beta/agents/agent-turn-result-error.ts

@@ -0,0 +1,33 @@
+import { OpenAIError } from '../../../core/error';
+import type { AgentSession, AgentSessionAssistantMessage } from '../../../resources/beta/agents/agents';
+import type { Turn } from '../../../resources/beta/agents/sessions/turns';
+
+/** Beta: final collection failed; partial state is evidence, not a successful result. */
+export class AgentTurnResultError extends OpenAIError {
+  override name = 'AgentTurnResultError';
+  readonly reason: 'failed' | 'cancelled' | 'requires_action' | 'observation';
+  readonly session_id: string | undefined;
+  readonly turn: Turn | undefined;
+  readonly messages: AgentSessionAssistantMessage[];
+  readonly required_actions: AgentSession['required_actions'];
+  readonly cause: unknown;
+  constructor(
+    reason: 'failed' | 'cancelled' | 'requires_action' | 'observation',
+    session_id: string | undefined,
+    turn: Turn | undefined,
+    messages: AgentSessionAssistantMessage[],
+    required_actions: AgentSession['required_actions'] = [],
+    cause?: unknown,
+  ) {
+    super(`Could not collect the agent turn result: ${reason}`);
+    this.reason = reason;
+    this.session_id = session_id;
+    this.turn = turn;
+    this.messages = messages;
+    this.required_actions = required_actions;
+    this.cause = cause;
+  }
+  get turn_id(): string | undefined {
+    return this.turn?.id;
+  }
+}

package/src/lib/beta/agents/agent-turn-result.ts

@@ -0,0 +1,22 @@
+import type { AgentSessionAssistantMessage } from '../../../resources/beta/agents/agents';
+import type { Turn } from '../../../resources/beta/agents/sessions/turns';
+import { outputText } from '../../agents/output-text';
+
+/** Beta: the completed final assistant messages from one hosted root turn. */
+export class AgentTurnResult {
+  readonly turn: Turn;
+  readonly messages: AgentSessionAssistantMessage[];
+  constructor(turn: Turn, messages: AgentSessionAssistantMessage[]) {
+    this.turn = turn;
+    this.messages = messages;
+  }
+  get session_id(): string {
+    return this.turn.session_id;
+  }
+  get turn_id(): string {
+    return this.turn.id;
+  }
+  get output_text(): string {
+    return this.messages.map(outputText).join('');
+  }
+}

package/src/lib/beta/agents/function-tool.ts

@@ -0,0 +1,60 @@
+import { OpenAIError } from '../../../core/error';
+import type { AgentToolHandler } from '../../agents/agent-session-stream';
+import type { AutoParseableResponseTool } from '../../ResponsesParser';
+import type { AgentToolParam } from '../../../resources/beta/agents/agents';
+import { isInputContent } from './tool-output';
+
+/** A beta Agents function definition paired with its local, validating handler. */
+export interface AgentFunctionTool {
+  /** Model-visible function name, also used as the key in `toolHandlers`. */
+  readonly name: string;
+  /** Hosted configuration for `agent.tools`; contains no local callback or parser. */
+  readonly definition: AgentToolParam.AgentToolConfigParamFunction;
+  /** Validates arguments before invoking the callback through the existing stream dispatcher. */
+  readonly handler: AgentToolHandler;
+}
+
+/**
+ * Adapts a `zodResponsesFunction` or `standardResponsesFunction` to beta Agents.
+ * Pass `definition` to `agent.tools` and register `handler` under `name` in
+ * `sessions.stream()`'s `toolHandlers`. Creating a definition does not execute it.
+ * The existing dispatcher handles callback results, failures, and submission retries.
+ * Scalar results and business-data arrays become JSON text; `undefined` becomes
+ * the text `undefined`. Supported text/image content arrays retain their format.
+ *
+ * @throws {OpenAIError} If the tool has no callback or argument schema.
+ */
+export function functionTool<Arguments>(
+  tool: AutoParseableResponseTool<{ name: string; arguments: Arguments }>,
+): AgentFunctionTool {
+  const execute = tool.$callback;
+  const parse = tool.$parseRaw;
+  if (!execute || !tool.parameters) {
+    throw new OpenAIError('Agents function tools require a callback and argument schema');
+  }
+  return {
+    name: tool.name,
+    definition: {
+      type: 'function',
+      name: tool.name,
+      description: tool.description ?? '',
+      parameters: tool.parameters,
+      ...(tool.defer_loading === undefined ? {} : { defer_loading: tool.defer_loading }),
+    },
+    handler: async (arguments_) => {
+      const result: unknown = await execute(parse(JSON.stringify(arguments_)));
+      if (Array.isArray(result)) {
+        return result.length > 0 && result.every(isInputContent) ? result : JSON.stringify(result);
+      }
+      // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Existing schema-tool callbacks return arbitrary application values; adapt them to the Agents dispatcher's output contract.
+      if (typeof result === 'object' || typeof result === 'string') {
+        return result;
+      }
+      const text = result === undefined ? 'undefined' : JSON.stringify(result);
+      if (text === undefined) {
+        throw new OpenAIError('Tool output must be JSON serializable');
+      }
+      return text;
+    },
+  };
+}

package/src/lib/beta/agents/output-format-types.ts

@@ -0,0 +1,12 @@
+import type { TextFormatParam } from '../../../resources/beta/agents/agents';
+import type { AgentTurnResult } from './agent-turn-result';
+import type { ParsedAgentTurnResult } from './parsed-agent-turn-result';
+
+/** Beta: an Agents JSON Schema format with a local output validator. */
+export interface AgentOutputFormat<T> extends TextFormatParam.TextFormatParamJSONSchema {
+  /** SDK-only parser; omitted from serialized requests. */
+  $parseRaw: (text: string) => T;
+}
+
+/** Beta: raw results remain unchanged unless a typed format is supplied. */
+export type AgentResult<T> = [T] extends [never] ? AgentTurnResult : ParsedAgentTurnResult<T>;

package/src/lib/beta/agents/output-format.ts

@@ -0,0 +1,20 @@
+import type { AgentOutputFormat } from './output-format-types';
+
+import type { JSONSchema } from '../../jsonschema';
+
+export type { AgentOutputFormat, AgentResult } from './output-format-types';
+
+export { ParsedAgentTurnResult } from './parsed-agent-turn-result';
+export { AgentOutputParseError } from './output-parse-error';
+
+/** Beta: bind a JSON schema to its local output parser; the API validates schema support. */
+export function agentOutputFormat<T>(schema: JSONSchema, parse: (text: string) => T): AgentOutputFormat<T> {
+  // Keep spread-compatible parsing without exposing caller-owned serialization hooks.
+  const parser = Object.defineProperty((text: string) => parse(text), 'toJSON', {
+    value: () => {
+      /* Parser metadata is omitted from JSON requests. */
+    },
+  });
+  // SAFETY: The API schema type exposes JSON Schema keywords as a record; preserve the supplied schema unchanged.
+  return { type: 'json_schema', schema: schema as AgentOutputFormat<T>['schema'], $parseRaw: parser };
+}

package/src/lib/beta/agents/output-parse-error.ts

@@ -0,0 +1,16 @@
+import { OpenAIError } from '../../../core/error';
+import type { AgentTurnResult } from './agent-turn-result';
+
+/** Beta: hosted execution completed, but local output parsing failed. */
+export class AgentOutputParseError extends OpenAIError {
+  override name = 'AgentOutputParseError';
+  readonly #rawResult: AgentTurnResult;
+  constructor(result: AgentTurnResult) {
+    super('The completed agent output could not be parsed');
+    this.#rawResult = result;
+  }
+  /** Inspect the completed output explicitly; ordinary error logging omits it. */
+  get raw_result(): AgentTurnResult {
+    return this.#rawResult;
+  }
+}