Class AgentRunState
The resumable state of an agent run: everything a new process needs to continue it, on any instance of the model. It holds the conversation (its history, never a KV image: a resumed run re-reads its history), the tool round the run stopped in with the results already recorded, the budgets spent and the run's metadata. Written at every checkpoint when a run has an IAgentRunStore, and returned on RunState when a run stops waiting for a decision or an input.
public sealed class AgentRunState
- Inheritance
-
AgentRunState
- Inherited Members
Remarks
A state carries SchemaVersion. A release reads every version up to its own (CurrentSchemaVersion), migrating older ones forward, and refuses a newer one with AgentRunStateVersionException, never a silent misread.
Resuming is an authorization boundary: the host re-checks, at every resume, that the caller may still run the agent and its tools. The state records what happened; it grants nothing.
Fields
- CurrentSchemaVersion
The schema version this release writes.
- MaxTimelineEvents
The most entries Timeline keeps; older ones give way to newer ones.
Properties
- Agent
Gets or sets the name of the agent the run belongs to.
- ApprovalDeadlineUtc
Gets or sets when the approvals the run waits for are due, or null for no deadline.
- ApprovalTimeoutAction
Gets or sets what happens to undecided approvals past ApprovalDeadlineUtc.
- ChildRuns
Gets or sets, for a workflow run, the run of each
workflowstep's child workflow that has not finished, by the step's position: kept in the parent's checkpoint, so the child resumes with the parent, on the revision it started on.
- Compensations
Gets or sets, for a workflow run, the completed steps whose effect is undone if the run fails, in the order they completed, with where each compensation stands; null when none was recorded.
- CompletedSteps
Gets or sets, for a workflow run, the steps already done (by position: a step inside a loop is named with its pass), so a resumed workflow replays them instead of running them again.
- CreatedUtc
Gets or sets when the run started.
- ForeachProgress
Gets or sets, for a workflow run, how far each
foreachstep has gone, by its position.
- History
Gets or sets the conversation history, as Serialize() writes it.
- InferenceCount
Gets or sets the model calls the run has made.
- Input
Gets or sets the user input the run answers.
- IsResumable
Gets whether a run in this state can be resumed.
- Iteration
Gets or sets the planning iteration the run reached.
- LoopIterations
Gets or sets, for a workflow run, the pass each loop has reached, by loop step id.
- Metadata
Gets or sets host data carried with the run (an owner, an agent revision, a tenant).
- NodePath
Gets or sets the path of the orchestration node the run stands at (for instance the stage of a pipeline), outermost first; empty for a lone agent.
- Output
Gets or sets the final answer once the run completed, or null.
- PendingRound
Gets or sets the tool round the run stopped in (the calls of one model turn, each with its result once it ran), or null when the run is not inside a round.
- Question
Gets or sets the question the run asked when it waits for an input, or null.
- ReceivedEvents
Gets or sets, for a workflow run, the payload of each event delivered and not yet read, by the waiting step's position.
- ResumeAfterUtc
Gets or sets, for a workflow run parked until its next attempt is due, when to resume it: the host plays it again then, and nothing holds a worker meanwhile. Null when the run waits for nothing in time.
- RunId
Gets or sets the run's identifier, stable across every checkpoint and resume.
- SchemaVersion
Gets or sets the schema version the state was written with.
- SideEffects
Gets or sets the side-effecting tool calls the run dispatched, with their outcome.
- Status
Gets or sets where the run stands: Suspended while it runs or after it was interrupted, AwaitingApproval, AwaitingInput, or the outcome once it ended.
- StepAttempts
Gets or sets, for a workflow run, the attempts of each step that was tried again or failed, by position (a step inside a loop is named with its pass).
- StepErrors
Gets or sets, for a workflow run, the error of each step that failed for good, by step id: what its error steps read as
steps.<id>.error.
- StepOutputs
Gets or sets, for a workflow run, the latest output of each step by step id, so the workflow's later steps and conditions read them after a resume.
- StepRun
Gets or sets, for a workflow stopped inside an agent step, that agent's own stopped run: its approvals and question are the workflow's, and resuming the workflow resumes it.
- Timeline
Gets or sets what happened in the run, oldest first: starts and resumptions, steps, tool calls (with duration, outcome and idempotency key), approvals asked and decided, questions, the hand-off and the end. Bounded by MaxTimelineEvents.
- Timers
Gets or sets, for a workflow run, when each
waitstep's wait ends, by its position, fixed at its first run.
- ToolCallsUsed
Gets or sets the tool calls the current user turn has spent.
- UpdatedUtc
Gets or sets when the state was last written.
- Variables
Gets or sets, for a workflow run, the values the host passed (read as
vars.<name>).
- WaitingFor
Gets or sets, for a workflow run waiting for an event, what it waits for; null otherwise.
Methods
- FromJson(string)
Reads a state written by ToJson(), by this release or an earlier one.
- IsApprovalOverdue(DateTime)
Gets whether the run waits for approvals past their deadline.
- Record(AgentRunEvent)
Adds an entry to Timeline, dropping the oldest past MaxTimelineEvents.
- ToJson()
Writes the state as JSON.