@openai/agents-core/dist/runner/errorHandlers.d.ts

The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows.

import { Agent, AgentOutputType } from '../agent';
import { MaxTurnsExceededError, ModelBehaviorError, ModelRefusalError } from '../errors';
import { RunItem, RunMessageOutputItem } from '../items';
import { ModelResponse } from '../model';
import { StreamedRunResult } from '../result';
import { RunContext } from '../runContext';
import { RunState } from '../runState';
import type { AgentInputItem, AgentOutputItem, ResolvedAgentOutput } from '../types';
/**
 * Error kinds supported by run error handlers.
 */
export type RunErrorKind = 'maxTurns' | 'modelRefusal' | 'invalidFinalOutput';
/**
 * Snapshot of run data passed to error handlers.
 */
export type RunErrorData<TContext, TAgent extends Agent<any, any>> = {
    input: string | AgentInputItem[];
    newItems: RunItem[];
    history: AgentInputItem[];
    output: AgentOutputItem[];
    rawResponses: ModelResponse[];
    lastAgent?: TAgent;
    state?: RunState<TContext, TAgent>;
};
export type RunErrorHandlerInput<TContext, TAgent extends Agent<any, any>> = {
    error: MaxTurnsExceededError | ModelRefusalError | ModelBehaviorError;
    context: RunContext<TContext>;
    runData: RunErrorData<TContext, TAgent>;
};
export type RunErrorHandlerResult<TAgent extends Agent<any, any>> = {
    /**
     * The final output to return for the run.
     */
    finalOutput: ResolvedAgentOutput<TAgent['outputType']>;
    /**
     * Whether to append the synthesized output to history for subsequent runs.
     */
    includeInHistory?: boolean;
};
export type RunErrorHandler<TContext, TAgent extends Agent<any, any>> = (input: RunErrorHandlerInput<TContext, TAgent>) => RunErrorHandlerResult<TAgent> | void | Promise<RunErrorHandlerResult<TAgent> | void>;
export type RunErrorHandlers<TContext, TAgent extends Agent<any, any>> = Partial<Record<RunErrorKind, RunErrorHandler<TContext, TAgent>>> & {
    /**
     * Fallback handler for supported error kinds.
     */
    default?: RunErrorHandler<TContext, TAgent>;
};
type TryHandleRunErrorArgs<TContext, TAgent extends Agent<any, any>> = {
    error: unknown;
    state: RunState<TContext, TAgent>;
    errorHandlers?: RunErrorHandlers<TContext, TAgent>;
    streamResult?: StreamedRunResult<TContext, TAgent>;
    responseAccepted: boolean;
    attemptedErrors?: WeakSet<object>;
};
export type PreparedRunErrorFinalOutput = {
    deferredItem?: RunMessageOutputItem;
};
type ResolveRunErrorHandlerArgs<TContext, TAgent extends Agent<any, any>> = {
    error: unknown;
    errorKind?: RunErrorKind;
    errorHandlers?: RunErrorHandlers<TContext, TAgent>;
    context: RunContext<TContext>;
    runData: RunErrorData<TContext, TAgent>;
    attemptedErrors?: WeakSet<object>;
};
export declare function preserveInvalidFinalOutputRedaction<T>(callback: (redactFromStart: boolean) => T | Promise<T>, inheritedRedaction?: boolean): Promise<T>;
/**
 * Attaches the active run state to errors that need resumable caller context.
 */
export declare const attachRunStateToError: <TContext, TAgent extends Agent<any, any>>(error: unknown, state: RunState<TContext, TAgent>) => void;
declare function validateRunErrorFinalOutput<TAgent extends Agent<any, any>>(agent: TAgent, outputText: string, redactInvalidOutputDetails?: boolean, redactFromStart?: boolean): void;
export declare const formatRunErrorFinalOutput: <TAgent extends Agent<any, any>>(agent: TAgent, finalOutput: ResolvedAgentOutput<TAgent["outputType"]>) => string;
export declare const createRunErrorFinalOutputItem: <TAgent extends Agent<any, any>>(agent: TAgent, outputText: string) => RunMessageOutputItem;
export declare const validateRunErrorHandlerFinalOutput: typeof validateRunErrorFinalOutput;
export declare function invalidateAcceptedResponseReplayEvidence(state: RunState<any, any> | undefined): void;
export declare const resolveRunErrorHandler: <TContext, TAgent extends Agent<any, any>>({ error, errorKind, errorHandlers, context, runData, attemptedErrors, }: ResolveRunErrorHandlerArgs<TContext, TAgent>) => Promise<RunErrorHandlerResult<TAgent> | undefined>;
export declare const prepareRunErrorFinalOutput: <TContext, TAgent extends Agent<TContext, AgentOutputType>>({ error, state, errorHandlers, streamResult, responseAccepted, attemptedErrors, }: TryHandleRunErrorArgs<TContext, TAgent>) => Promise<PreparedRunErrorFinalOutput | undefined>;
export {};