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
Section titled “Type Parameters”Type Parameter |
---|
|
|
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new RunState<TContext, TAgent>( context, originalInput, startingAgent,maxTurns): RunState<TContext, TAgent>
Parameters
Section titled “Parameters”Parameter | Type |
---|---|
|
|
|
| |
|
|
|
|
Returns
Section titled “Returns”RunState
<TContext
, TAgent
>
Properties
Section titled “Properties”_context
Section titled “_context”_context: RunContext<TContext>;
Run context tracking approvals, usage, and other metadata.
_currentAgent
Section titled “_currentAgent”_currentAgent: TAgent;
The agent currently handling the conversation.
_currentAgentSpan
Section titled “_currentAgentSpan”_currentAgentSpan: | undefined| Span<AgentSpanData>;
Active tracing span for the current agent if tracing is enabled.
_currentStep
Section titled “_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
Section titled “_currentTurn”_currentTurn: number;
Current turn number in the conversation.
_generatedItems
Section titled “_generatedItems”_generatedItems: RunItem[];
Items generated by the agent during the run.
_inputGuardrailResults
Section titled “_inputGuardrailResults”_inputGuardrailResults: InputGuardrailResult[];
Results from input guardrails applied to the run.
_lastProcessedResponse
Section titled “_lastProcessedResponse”_lastProcessedResponse: undefined | ProcessedResponse<TContext>;
Parsed model response after applying guardrails and tools.
_lastTurnResponse
Section titled “_lastTurnResponse”_lastTurnResponse: | undefined | ModelResponse;
Last model response for the previous turn.
_maxTurns
Section titled “_maxTurns”_maxTurns: number;
Maximum allowed turns before forcing termination.
_modelResponses
Section titled “_modelResponses”_modelResponses: ModelResponse[];
Responses from the model so far.
_noActiveAgentRun
Section titled “_noActiveAgentRun”_noActiveAgentRun: boolean;
Whether the run has an active agent step in progress.
_originalInput
Section titled “_originalInput”_originalInput: | string | AgentInputItem[];
Original user input prior to any processing.
_outputGuardrailResults
Section titled “_outputGuardrailResults”_outputGuardrailResults: OutputGuardrailResult<OutputGuardrailMetadata, "text">[];
Results from output guardrails applied to the run.
_toolUseTracker
Section titled “_toolUseTracker”_toolUseTracker: AgentToolUseTracker;
Tracks what tools each agent has used.
_trace
Section titled “_trace”_trace: null | Trace;
Trace associated with this run if tracing is enabled.
Methods
Section titled “Methods”approve()
Section titled “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
Section titled “Parameters”Parameter | Type | Description |
---|---|---|
|
The tool call approval item to approve. |
|
|
{ |
Options for the approval. |
|
|
‐ |
Returns
Section titled “Returns”void
reject()
Section titled “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
Section titled “Parameters”Parameter | Type | Description |
---|---|---|
|
The tool call approval item to reject. |
|
|
{ |
Options for the rejection. |
|
|
‐ |
Returns
Section titled “Returns”void
toJSON()
Section titled “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
Section titled “Returns”object
The serialized run state.
$schemaVersion
Section titled “$schemaVersion”$schemaVersion: "1.0";
context
Section titled “context”context: object;
context.approvals
Section titled “context.approvals”approvals: Record<string, { approved: boolean | string[]; rejected: boolean | string[];}>;
context.context
Section titled “context.context”context: Record<string, any>;
context.usage
Section titled “context.usage”usage: object;
context.usage.inputTokens
Section titled “context.usage.inputTokens”inputTokens: number;
context.usage.outputTokens
Section titled “context.usage.outputTokens”outputTokens: number;
context.usage.requests
Section titled “context.usage.requests”requests: number;
context.usage.totalTokens
Section titled “context.usage.totalTokens”totalTokens: number;
currentAgent
Section titled “currentAgent”currentAgent: object;
currentAgent.name
Section titled “currentAgent.name”name: string;
currentAgentSpan?
Section titled “currentAgentSpan?”optional currentAgentSpan: null | SerializedSpanType;
currentStep?
Section titled “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
Section titled “currentTurn”currentTurn: number;
generatedItems
Section titled “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
Section titled “inputGuardrailResults”inputGuardrailResults: object[];
lastModelResponse?
Section titled “lastModelResponse?”optional lastModelResponse: object;
lastModelResponse.output
Section titled “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?
Section titled “lastModelResponse.responseId?”optional responseId: string;
lastModelResponse.usage
Section titled “lastModelResponse.usage”usage: object;
lastModelResponse.usage.inputTokens
Section titled “lastModelResponse.usage.inputTokens”inputTokens: number;
lastModelResponse.usage.outputTokens
Section titled “lastModelResponse.usage.outputTokens”outputTokens: number;
lastModelResponse.usage.requests
Section titled “lastModelResponse.usage.requests”requests: number;
lastModelResponse.usage.totalTokens
Section titled “lastModelResponse.usage.totalTokens”totalTokens: number;
lastProcessedResponse?
Section titled “lastProcessedResponse?”optional lastProcessedResponse: object;
lastProcessedResponse.computerActions
Section titled “lastProcessedResponse.computerActions”computerActions: object[];
lastProcessedResponse.functions
Section titled “lastProcessedResponse.functions”functions: object[];
lastProcessedResponse.handoffs
Section titled “lastProcessedResponse.handoffs”handoffs: object[];
lastProcessedResponse.newItems
Section titled “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
Section titled “lastProcessedResponse.toolsUsed”toolsUsed: string[];
maxTurns
Section titled “maxTurns”maxTurns: number;
modelResponses
Section titled “modelResponses”modelResponses: object[];
noActiveAgentRun
Section titled “noActiveAgentRun”noActiveAgentRun: boolean;
originalInput
Section titled “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
Section titled “outputGuardrailResults”outputGuardrailResults: object[];
toolUseTracker
Section titled “toolUseTracker”toolUseTracker: Record<string, string[]>;
trace: | null | { group_id: null | string; id: string; metadata: Record<string, any>; object: "trace"; workflow_name: string;};
toString()
Section titled “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
Section titled “Returns”string
The serialized run state.
fromString()
Section titled “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
Section titled “Type Parameters”Type Parameter |
---|
|
|
Parameters
Section titled “Parameters”Parameter | Type |
---|---|
|
|
|
|
Returns
Section titled “Returns”Promise
<RunState
<TContext
, TAgent
>>