RunState

Serializable snapshot of an agent’s run, including context, usage and trace. While this class has publicly writable properties (prefixed with _), they are not meant to be used directly. To read these properties, use the RunResult instead.

Manipulation of the state directly can lead to unexpected behavior and should be avoided. Instead, use the approve and reject methods to interact with the state.

Type Parameters

Type Parameter
TContext
TAgent extends Agent<any, any>

Constructors

Constructor

new RunState<TContext, TAgent>(
   context,
   originalInput,
   startingAgent,
maxTurns): RunState<TContext, TAgent>

Parameters

Parameter	Type
context	RunContext<TContext>
originalInput	| string | AgentInputItem[]
startingAgent	TAgent
maxTurns	number

Returns

RunState<TContext, TAgent>

Properties

_context

_context: RunContext<TContext>;

Run context tracking approvals, usage, and other metadata.

---

_currentAgent

_currentAgent: TAgent;

The agent currently handling the conversation.

---

_currentAgentSpan

_currentAgentSpan:
  | undefined
| Span<AgentSpanData>;

Active tracing span for the current agent if tracing is enabled.

---

_currentStep

_currentStep:
  | undefined
  | {
  newAgent: any;
  type: "next_step_handoff";
 }
  | {
  output: string;
  type: "next_step_final_output";
 }
  | {
  type: "next_step_run_again";
 }
  | {
  data: Record<string, any>;
  type: "next_step_interruption";
};

Next step computed for the agent to take.

---

_currentTurn

_currentTurn: number;

Current turn number in the conversation.

---

_generatedItems

_generatedItems: RunItem[];

Items generated by the agent during the run.

---

_inputGuardrailResults

_inputGuardrailResults: InputGuardrailResult[];

Results from input guardrails applied to the run.

---

_lastProcessedResponse

_lastProcessedResponse: undefined | ProcessedResponse<TContext>;

Parsed model response after applying guardrails and tools.

---

_lastTurnResponse

_lastTurnResponse:
  | undefined
  | ModelResponse;

Last model response for the previous turn.

---

_maxTurns

_maxTurns: number;

Maximum allowed turns before forcing termination.

---

_modelResponses

_modelResponses: ModelResponse[];

Responses from the model so far.

---

_noActiveAgentRun

_noActiveAgentRun: boolean;

Whether the run has an active agent step in progress.

---

_originalInput

_originalInput:
  | string
  | AgentInputItem[];

Original user input prior to any processing.

---

_outputGuardrailResults

_outputGuardrailResults: OutputGuardrailResult<OutputGuardrailMetadata, "text">[];

Results from output guardrails applied to the run.

---

_toolUseTracker

_toolUseTracker: AgentToolUseTracker;

Tracks what tools each agent has used.

---

_trace

_trace: null | Trace;

Trace associated with this run if tracing is enabled.

Methods

approve()

approve(approvalItem, options?): void

Approves a tool call requested by the agent through an interruption and approval item request.

To approve the request use this method and then run the agent again with the same state object to continue the execution.

By default it will only approve the current tool call. To allow the tool to be used multiple times throughout the run, set the alwaysApprove option to true.

Parameters

Parameter	Type	Description
approvalItem	RunToolApprovalItem	The tool call approval item to approve.
options?	{ alwaysApprove: boolean; }	Options for the approval.
options.alwaysApprove?	boolean	‐

Returns

void

---

reject()

reject(approvalItem, options?): void

Rejects a tool call requested by the agent through an interruption and approval item request.

To reject the request use this method and then run the agent again with the same state object to continue the execution.

By default it will only reject the current tool call. To allow the tool to be used multiple times throughout the run, set the alwaysReject option to true.

Parameters

Parameter	Type	Description
approvalItem	RunToolApprovalItem	The tool call approval item to reject.
options?	{ alwaysReject: boolean; }	Options for the rejection.
options.alwaysReject?	boolean	‐

Returns

void

---

toJSON()

toJSON(): object

Serializes the run state to a JSON object.

This method is used to serialize the run state to a JSON object that can be used to resume the run later.

Returns

object

The serialized run state.

$schemaVersion

$schemaVersion: "1.0";

context

context: object;

context.approvals

approvals: Record<string, {
  approved: boolean | string[];
  rejected: boolean | string[];
}>;

context.context

context: Record<string, any>;

context.usage

usage: object;

context.usage.inputTokens

inputTokens: number;

context.usage.outputTokens

outputTokens: number;

context.usage.requests

requests: number;

context.usage.totalTokens

totalTokens: number;

currentAgent

currentAgent: object;

currentAgent.name

name: string;

currentAgentSpan?

optional currentAgentSpan: null | SerializedSpanType;

currentStep?

optional currentStep:
  | {
  newAgent: any;
  type: "next_step_handoff";
 }
  | {
  output: string;
  type: "next_step_final_output";
 }
  | {
  type: "next_step_run_again";
 }
  | {
  data: Record<string, any>;
  type: "next_step_interruption";
};

currentTurn

currentTurn: number;

generatedItems

generatedItems: (
  | {
  agent: {
     name: string;
    };
  rawItem: {
     content: (
        | {
        providerData: Record<string, any>;
        refusal: string;
        type: "refusal";
       }
        | {
        providerData: Record<string, any>;
        text: string;
        type: "output_text";
       }
        | {
        providerData: Record<string, any>;
        text: string;
        type: "input_text";
       }
        | {
        audio:   | string
           | {
           id: string;
          };
        format: null | string;
        providerData: Record<string, any>;
        transcript: null | string;
        type: "audio";
       }
        | {
        image: string;
        providerData: Record<string, any>;
        type: "image";
       })[];
     id: string;
     providerData: Record<string, any>;
     role: "assistant";
     status: "in_progress" | "completed" | "incomplete";
     type: "message";
    };
  type: "message_output_item";
 }
  | {
  agent: {
     name: string;
    };
  rawItem:   | {
     id: string;
     name: string;
     output: string;
     providerData: Record<string, any>;
     status: string;
     type: "hosted_tool_call";
    }
     | {
     arguments: string;
     callId: string;
     id: string;
     name: string;
     providerData: Record<string, any>;
     status: "in_progress" | "completed" | "incomplete";
     type: "function_call";
    }
     | {
     action:   | {
        type: "screenshot";
       }
        | {
        button: "left" | "right" | "wheel" | "back" | "forward";
        type: "click";
        x: number;
        y: number;
       }
        | {
        type: "double_click";
        x: number;
        y: number;
       }
        | {
        scroll_x: number;
        scroll_y: number;
        type: "scroll";
        x: number;
        y: number;
       }
        | {
        text: string;
        type: "type";
       }
        | {
        type: "wait";
       }
        | {
        type: "move";
        x: number;
        y: number;
       }
        | {
        keys: string[];
        type: "keypress";
       }
        | {
        path: object[];
        type: "drag";
       };
     callId: string;
     id: string;
     providerData: Record<string, any>;
     status: "in_progress" | "completed" | "incomplete";
     type: "computer_call";
    };
  type: "tool_call_item";
 }
  | {
  agent: {
     name: string;
    };
  output: string;
  rawItem: {
     callId: string;
     id: string;
     name: string;
     output:   | {
        providerData: Record<string, any>;
        text: string;
        type: "text";
       }
        | {
        data: string;
        mediaType: string;
        providerData: Record<string, any>;
        type: "image";
       };
     providerData: Record<string, any>;
     status: "in_progress" | "completed" | "incomplete";
     type: "function_call_result";
    };
  type: "tool_call_output_item";
 }
  | {
  agent: {
     name: string;
    };
  rawItem: {
     content: object[];
     id: string;
     providerData: Record<string, any>;
     type: "reasoning";
    };
  type: "reasoning_item";
 }
  | {
  agent: {
     name: string;
    };
  rawItem: {
     arguments: string;
     callId: string;
     id: string;
     name: string;
     providerData: Record<string, any>;
     status: "in_progress" | "completed" | "incomplete";
     type: "function_call";
    };
  type: "handoff_call_item";
 }
  | {
  rawItem: {
     callId: string;
     id: string;
     name: string;
     output:   | {
        providerData: Record<string, any>;
        text: string;
        type: "text";
       }
        | {
        data: string;
        mediaType: string;
        providerData: Record<string, any>;
        type: "image";
       };
     providerData: Record<string, any>;
     status: "in_progress" | "completed" | "incomplete";
     type: "function_call_result";
    };
  sourceAgent: {
     name: string;
    };
  targetAgent: {
     name: string;
    };
  type: "handoff_output_item";
 }
  | {
  agent: {
     name: string;
    };
  rawItem: {
     arguments: string;
     callId: string;
     id: string;
     name: string;
     providerData: Record<string, any>;
     status: "in_progress" | "completed" | "incomplete";
     type: "function_call";
    };
  type: "tool_approval_item";
 })[];

inputGuardrailResults

inputGuardrailResults: object[];

lastModelResponse?

optional lastModelResponse: object;

lastModelResponse.output

output: (
  | {
  content: (
     | {
     providerData: Record<..., ...>;
     refusal: string;
     type: "refusal";
    }
     | {
     providerData: Record<..., ...>;
     text: string;
     type: "output_text";
    }
     | {
     providerData: Record<..., ...>;
     text: string;
     type: "input_text";
    }
     | {
     audio:   | string
        | {
        id: ...;
       };
     format: null | string;
     providerData: Record<..., ...>;
     transcript: null | string;
     type: "audio";
    }
     | {
     image: string;
     providerData: Record<..., ...>;
     type: "image";
    })[];
  id: string;
  providerData: Record<string, any>;
  role: "assistant";
  status: "in_progress" | "completed" | "incomplete";
  type: "message";
 }
  | {
  id: string;
  name: string;
  output: string;
  providerData: Record<string, any>;
  status: string;
  type: "hosted_tool_call";
 }
  | {
  arguments: string;
  callId: string;
  id: string;
  name: string;
  providerData: Record<string, any>;
  status: "in_progress" | "completed" | "incomplete";
  type: "function_call";
 }
  | {
  action:   | {
     type: "screenshot";
    }
     | {
     button: "left" | "right" | "wheel" | "back" | "forward";
     type: "click";
     x: number;
     y: number;
    }
     | {
     type: "double_click";
     x: number;
     y: number;
    }
     | {
     scroll_x: number;
     scroll_y: number;
     type: "scroll";
     x: number;
     y: number;
    }
     | {
     text: string;
     type: "type";
    }
     | {
     type: "wait";
    }
     | {
     type: "move";
     x: number;
     y: number;
    }
     | {
     keys: string[];
     type: "keypress";
    }
     | {
     path: object[];
     type: "drag";
    };
  callId: string;
  id: string;
  providerData: Record<string, any>;
  status: "in_progress" | "completed" | "incomplete";
  type: "computer_call";
 }
  | {
  content: object[];
  id: string;
  providerData: Record<string, any>;
  type: "reasoning";
 }
  | {
  id: string;
  providerData: Record<string, any>;
  type: "unknown";
 })[];

lastModelResponse.responseId?

optional responseId: string;

lastModelResponse.usage

usage: object;

lastModelResponse.usage.inputTokens

inputTokens: number;

lastModelResponse.usage.outputTokens

outputTokens: number;

lastModelResponse.usage.requests

requests: number;

lastModelResponse.usage.totalTokens

totalTokens: number;

lastProcessedResponse?

optional lastProcessedResponse: object;

lastProcessedResponse.computerActions

computerActions: object[];

lastProcessedResponse.functions

functions: object[];

lastProcessedResponse.handoffs

handoffs: object[];

lastProcessedResponse.newItems

newItems: (
  | {
  agent: {
     name: string;
    };
  rawItem: {
     content: (
        | {
        providerData: ... | ...;
        refusal: string;
        type: "refusal";
       }
        | {
        providerData: ... | ...;
        text: string;
        type: "output_text";
       }
        | {
        providerData: ... | ...;
        text: string;
        type: "input_text";
       }
        | {
        audio: ... | ...;
        format: ... | ... | ...;
        providerData: ... | ...;
        transcript: ... | ... | ...;
        type: "audio";
       }
        | {
        image: string;
        providerData: ... | ...;
        type: "image";
       })[];
     id: string;
     providerData: Record<string, any>;
     role: "assistant";
     status: "in_progress" | "completed" | "incomplete";
     type: "message";
    };
  type: "message_output_item";
 }
  | {
  agent: {
     name: string;
    };
  rawItem:   | {
     id: string;
     name: string;
     output: string;
     providerData: Record<string, any>;
     status: string;
     type: "hosted_tool_call";
    }
     | {
     arguments: string;
     callId: string;
     id: string;
     name: string;
     providerData: Record<string, any>;
     status: "in_progress" | "completed" | "incomplete";
     type: "function_call";
    }
     | {
     action:   | {
        type: "screenshot";
       }
        | {
        button: ... | ... | ... | ... | ...;
        type: "click";
        x: number;
        y: number;
       }
        | {
        type: "double_click";
        x: number;
        y: number;
       }
        | {
        scroll_x: number;
        scroll_y: number;
        type: "scroll";
        x: number;
        y: number;
       }
        | {
        text: string;
        type: "type";
       }
        | {
        type: "wait";
       }
        | {
        type: "move";
        x: number;
        y: number;
       }
        | {
        keys: ...[];
        type: "keypress";
       }
        | {
        path: ...[];
        type: "drag";
       };
     callId: string;
     id: string;
     providerData: Record<string, any>;
     status: "in_progress" | "completed" | "incomplete";
     type: "computer_call";
    };
  type: "tool_call_item";
 }
  | {
  agent: {
     name: string;
    };
  output: string;
  rawItem: {
     callId: string;
     id: string;
     name: string;
     output:   | {
        providerData: Record<..., ...>;
        text: string;
        type: "text";
       }
        | {
        data: string;
        mediaType: string;
        providerData: Record<..., ...>;
        type: "image";
       };
     providerData: Record<string, any>;
     status: "in_progress" | "completed" | "incomplete";
     type: "function_call_result";
    };
  type: "tool_call_output_item";
 }
  | {
  agent: {
     name: string;
    };
  rawItem: {
     content: object[];
     id: string;
     providerData: Record<string, any>;
     type: "reasoning";
    };
  type: "reasoning_item";
 }
  | {
  agent: {
     name: string;
    };
  rawItem: {
     arguments: string;
     callId: string;
     id: string;
     name: string;
     providerData: Record<string, any>;
     status: "in_progress" | "completed" | "incomplete";
     type: "function_call";
    };
  type: "handoff_call_item";
 }
  | {
  rawItem: {
     callId: string;
     id: string;
     name: string;
     output:   | {
        providerData: Record<..., ...>;
        text: string;
        type: "text";
       }
        | {
        data: string;
        mediaType: string;
        providerData: Record<..., ...>;
        type: "image";
       };
     providerData: Record<string, any>;
     status: "in_progress" | "completed" | "incomplete";
     type: "function_call_result";
    };
  sourceAgent: {
     name: string;
    };
  targetAgent: {
     name: string;
    };
  type: "handoff_output_item";
 }
  | {
  agent: {
     name: string;
    };
  rawItem: {
     arguments: string;
     callId: string;
     id: string;
     name: string;
     providerData: Record<string, any>;
     status: "in_progress" | "completed" | "incomplete";
     type: "function_call";
    };
  type: "tool_approval_item";
 })[];

lastProcessedResponse.toolsUsed

toolsUsed: string[];

maxTurns

maxTurns: number;

modelResponses

modelResponses: object[];

noActiveAgentRun

noActiveAgentRun: boolean;

originalInput

originalInput:
  | string
  | (
  | {
  content: (
     | {
     providerData: Record<string, any>;
     refusal: string;
     type: "refusal";
    }
     | {
     providerData: Record<string, any>;
     text: string;
     type: "output_text";
    }
     | {
     providerData: Record<string, any>;
     text: string;
     type: "input_text";
    }
     | {
     audio:   | string
        | {
        id: string;
       };
     format: null | string;
     providerData: Record<string, any>;
     transcript: null | string;
     type: "audio";
    }
     | {
     image: string;
     providerData: Record<string, any>;
     type: "image";
    })[];
  id: string;
  providerData: Record<string, any>;
  role: "assistant";
  status: "in_progress" | "completed" | "incomplete";
  type: "message";
 }
  | {
  content:   | string
     | (
     | {
     providerData: Record<..., ...>;
     text: string;
     type: "input_text";
    }
     | {
     image:   | string
        | {
        id: ...;
       };
     providerData: Record<..., ...>;
     type: "input_image";
    }
     | {
     file:   | string
        | {
        id: ...;
       };
     providerData: Record<..., ...>;
     type: "input_file";
    }
     | {
     audio:   | string
        | {
        id: ...;
       };
     format: null | string;
     providerData: Record<..., ...>;
     transcript: null | string;
     type: "audio";
    })[];
  id: string;
  providerData: Record<string, any>;
  role: "user";
  type: "message";
 }
  | {
  content: string;
  id: string;
  providerData: Record<string, any>;
  role: "system";
  type: "message";
 }
  | {
  id: string;
  name: string;
  output: string;
  providerData: Record<string, any>;
  status: string;
  type: "hosted_tool_call";
 }
  | {
  arguments: string;
  callId: string;
  id: string;
  name: string;
  providerData: Record<string, any>;
  status: "in_progress" | "completed" | "incomplete";
  type: "function_call";
 }
  | {
  callId: string;
  id: string;
  name: string;
  output:   | {
     providerData: Record<string, any>;
     text: string;
     type: "text";
    }
     | {
     data: string;
     mediaType: string;
     providerData: Record<string, any>;
     type: "image";
    };
  providerData: Record<string, any>;
  status: "in_progress" | "completed" | "incomplete";
  type: "function_call_result";
 }
  | {
  action:   | {
     type: "screenshot";
    }
     | {
     button: "left" | "right" | "wheel" | "back" | "forward";
     type: "click";
     x: number;
     y: number;
    }
     | {
     type: "double_click";
     x: number;
     y: number;
    }
     | {
     scroll_x: number;
     scroll_y: number;
     type: "scroll";
     x: number;
     y: number;
    }
     | {
     text: string;
     type: "type";
    }
     | {
     type: "wait";
    }
     | {
     type: "move";
     x: number;
     y: number;
    }
     | {
     keys: string[];
     type: "keypress";
    }
     | {
     path: object[];
     type: "drag";
    };
  callId: string;
  id: string;
  providerData: Record<string, any>;
  status: "in_progress" | "completed" | "incomplete";
  type: "computer_call";
 }
  | {
  callId: string;
  id: string;
  output: {
     data: string;
     providerData: Record<string, any>;
     type: "computer_screenshot";
    };
  providerData: Record<string, any>;
  type: "computer_call_result";
 }
  | {
  content: object[];
  id: string;
  providerData: Record<string, any>;
  type: "reasoning";
 }
  | {
  id: string;
  providerData: Record<string, any>;
  type: "unknown";
 })[];

outputGuardrailResults

outputGuardrailResults: object[];

toolUseTracker

toolUseTracker: Record<string, string[]>;

trace

trace:
  | null
  | {
  group_id: null | string;
  id: string;
  metadata: Record<string, any>;
  object: "trace";
  workflow_name: string;
};

---

toString()

toString(): string

Serializes the run state to a string.

This method is used to serialize the run state to a string that can be used to resume the run later.

Returns

string

The serialized run state.

---

fromString()

static fromString<TContext, TAgent>(initialAgent, str): Promise<RunState<TContext, TAgent>>

Deserializes a run state from a string.

This method is used to deserialize a run state from a string that was serialized using the toString method.

Type Parameters

Type Parameter
TContext
TAgent extends Agent<any, any>

Parameters

Parameter	Type
initialAgent	TAgent
str	string

Returns

Promise<RunState<TContext, TAgent>>