openai 7.24.0 → 7.26.0

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;
+  }
+}

package/src/lib/beta/agents/parse-result.ts

@@ -0,0 +1,133 @@
+import type { RequestOptions } from '../../../internal/request-options';
+import { OpenAIError } from '../../../core/error';
+import type { SessionCreateParams } from '../../../resources/beta/agents/sessions/sessions';
+import type { AgentTurnResult } from './agent-turn-result';
+import type { TextFormatParam } from '../../../resources/beta/agents/agents';
+import type { AgentOutputFormat, AgentResult } from './output-format-types';
+import { ParsedAgentTurnResult } from './parsed-agent-turn-result';
+import { AgentOutputParseError } from './output-parse-error';
+
+/** @internal */
+export function parseAgentResult<T>(result: AgentTurnResult, format?: AgentOutputFormat<T>): AgentResult<T> {
+  try {
+    if (!format) {
+      // SAFETY: Absent formats use the default never/raw overload.
+      return result as AgentResult<T>;
+    }
+    let first: { value: T } | undefined;
+    for (const message of result.messages) {
+      for (const content of message.content) {
+        if (content.type === 'output_text') {
+          const value = format.$parseRaw(content.text);
+          first ??= { value };
+        }
+      }
+    }
+    if (!first) {
+      throw new AgentOutputParseError(result);
+    }
+    // SAFETY: Callers preserve the format's inferred T.
+    return new ParsedAgentTurnResult(result, first.value) as AgentResult<T>;
+  } catch {
+    throw new AgentOutputParseError(result);
+  }
+}
+
+// Inspect only JSON-visible data fields; leave getters and inherited values to normal serialization.
+function ownJSONValue<T extends object, K extends keyof T>(
+  object: T | null | undefined,
+  key: K,
+): T[K] | undefined {
+  const descriptor = object && Object.getOwnPropertyDescriptor(object, key);
+  // SAFETY: The own data descriptor corresponds to the requested property in T.
+  return descriptor?.enumerable && 'value' in descriptor ? (descriptor.value as T[K]) : undefined;
+}
+
+/** @internal */
+export function agentFormatParser<T = unknown>(
+  format: TextFormatParam | null | undefined,
+): AgentOutputFormat<T> | undefined {
+  if (!format) {
+    return undefined;
+  }
+  const descriptor = Object.getOwnPropertyDescriptor(format, '$parseRaw');
+  // oxlint-disable-next-line anti-slop/no-runtime-typeof -- An own parser data property is the explicit opt-in marker.
+  if (!descriptor || !('value' in descriptor) || typeof descriptor.value !== 'function') {
+    return undefined;
+  }
+  // SAFETY: Inspect the schema data descriptor without evaluating a caller getter; validate its discriminator below.
+  const schema = ownJSONValue(format as TextFormatParam.TextFormatParamJSONSchema, 'schema');
+  if (ownJSONValue(format, 'type') !== 'json_schema' || !schema) {
+    throw new OpenAIError('Typed agent formats require own enumerable type and schema data properties');
+  }
+  // SAFETY: The own descriptor was checked for a callable parser; retain its receiver and never reread the property.
+  const parse = descriptor.value as AgentOutputFormat<T>['$parseRaw'];
+  return { type: 'json_schema', schema, $parseRaw: (text) => parse.call(format, text) };
+}
+
+// Materialize JSON-visible envelope getters once without evaluating unrelated properties.
+function snapshotJSONProperty<T extends object, K extends keyof T>(
+  object: T,
+  key: K,
+  capture: (value: T[K]) => T[K] = (value) => value,
+): T {
+  const descriptor = Object.getOwnPropertyDescriptor(object, key);
+  if (!descriptor?.enumerable) {
+    return object;
+  }
+  const value = capture(object[key]);
+  if ('value' in descriptor && value === descriptor.value) {
+    return object;
+  }
+  // SAFETY: Preserve the original properties/prototype, replacing only this captured property's value.
+  return Object.create(Object.getPrototypeOf(object), {
+    ...Object.getOwnPropertyDescriptors(object),
+    [key]: { value, enumerable: true, configurable: descriptor.configurable, writable: true },
+  }) as T;
+}
+
+/** @internal */
+export function captureAgentOutput(input: SessionCreateParams, options?: RequestOptions) {
+  const body = snapshotJSONProperty(input, 'agent', (agent) =>
+    agent
+      ? snapshotJSONProperty(agent, 'text', (text) => (text ? snapshotJSONProperty(text, 'format') : text))
+      : agent,
+  );
+  const agent = ownJSONValue(body, 'agent');
+  const text = ownJSONValue(agent, 'text');
+  const format = agentFormatParser(ownJSONValue(text, 'format'));
+  if (!format) {
+    return { body, options };
+  }
+  const schema = structuredClone(format.schema);
+  for (const envelope of [body, agent, text]) {
+    if (envelope && 'toJSON' in envelope) {
+      throw new OpenAIError('Typed agent requests cannot customize body, agent, or text serialization');
+    }
+  }
+  // Snapshot options once, matching the own enumerable fields native request spreading uses.
+  const capturedOptions = { ...options };
+  if (ownJSONValue(capturedOptions, 'body') !== undefined) {
+    throw new OpenAIError('Typed agent requests cannot override the body in request options');
+  }
+  delete capturedOptions.body;
+  return {
+    options: capturedOptions,
+    body: {
+      ...body,
+      agent: {
+        ...agent,
+        text: { ...text, format: { type: 'json_schema', schema } },
+      },
+    },
+    format,
+  };
+}
+
+/** @internal */
+export async function parseAgentResultPromise<T>(
+  result: Promise<AgentTurnResult>,
+  format?: AgentOutputFormat<T>,
+): Promise<AgentResult<T>> {
+  return parseAgentResult(await result, format);
+}

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

@@ -0,0 +1,12 @@
+import { AgentTurnResult } from './agent-turn-result';
+
+/** Beta: a completed hosted turn whose output passed the local parser. */
+export class ParsedAgentTurnResult<T> extends AgentTurnResult {
+  readonly output_parsed: T;
+  readonly raw_result: AgentTurnResult;
+  constructor(result: AgentTurnResult, parsed: T) {
+    super(result.turn, result.messages);
+    this.raw_result = result;
+    this.output_parsed = parsed;
+  }
+}