Skip to content

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 Parameter

TContext

TAgent extends Agent<any, any>

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

context

RunContext<TContext>

originalInput

| string | AgentInputItem[]

startingAgent

TAgent

maxTurns

number

RunState<TContext, TAgent>

_context: RunContext<TContext>;

Run context tracking approvals, usage, and other metadata.


_currentAgent: TAgent;

The agent currently handling the conversation.


_currentAgentSpan:
| undefined
| Span<AgentSpanData>;

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


_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: number;

Current turn number in the conversation.


_generatedItems: RunItem[];

Items generated by the agent during the run.


_inputGuardrailResults: InputGuardrailResult[];

Results from input guardrails applied to the run.


_lastProcessedResponse: undefined | ProcessedResponse<TContext>;

Parsed model response after applying guardrails and tools.


_lastTurnResponse:
| undefined
| ModelResponse;

Last model response for the previous turn.


_maxTurns: number;

Maximum allowed turns before forcing termination.


_modelResponses: ModelResponse[];

Responses from the model so far.


_noActiveAgentRun: boolean;

Whether the run has an active agent step in progress.


_originalInput:
| string
| AgentInputItem[];

Original user input prior to any processing.


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

Results from output guardrails applied to the run.


_toolUseTracker: AgentToolUseTracker;

Tracks what tools each agent has used.


_trace: null | Trace;

Trace associated with this run if tracing is enabled.

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.

Parameter Type Description

approvalItem

RunToolApprovalItem

The tool call approval item to approve.

options?

{ alwaysApprove: boolean; }

Options for the approval.

options.alwaysApprove?

boolean

void


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.

Parameter Type Description

approvalItem

RunToolApprovalItem

The tool call approval item to reject.

options?

{ alwaysReject: boolean; }

Options for the rejection.

options.alwaysReject?

boolean

void


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.

object

The serialized run state.

$schemaVersion: "1.0";
context: object;
approvals: Record<string, {
approved: boolean | string[];
rejected: boolean | string[];
}>;
context: Record<string, any>;
usage: object;
inputTokens: number;
outputTokens: number;
requests: number;
totalTokens: number;
currentAgent: object;
name: string;
optional currentAgentSpan: null | SerializedSpanType;
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: number;
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: object[];
optional lastModelResponse: object;
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";
})[];
optional responseId: string;
usage: object;
inputTokens: number;
outputTokens: number;
requests: number;
totalTokens: number;
optional lastProcessedResponse: object;
computerActions: object[];
functions: object[];
handoffs: object[];
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";
})[];
toolsUsed: string[];
maxTurns: number;
modelResponses: object[];
noActiveAgentRun: boolean;
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: object[];
toolUseTracker: Record<string, string[]>;
trace:
| null
| {
group_id: null | string;
id: string;
metadata: Record<string, any>;
object: "trace";
workflow_name: string;
};

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.

string

The serialized run state.


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 Parameter

TContext

TAgent extends Agent<any, any>

Parameter Type

initialAgent

TAgent

str

string

Promise<RunState<TContext, TAgent>>