Interface: AgentStateInterface
@providerprotocol/agents / index / AgentStateInterface
Interface: AgentStateInterface
Section titled “Interface: AgentStateInterface”Defined in: src/state/types.ts:262
Interface defining the contract for agent state operations.
All methods follow immutable patterns, returning new state instances rather than mutating the existing state. This enables safe state management, easy rollback, and predictable behavior.
Remarks
Section titled “Remarks”Implementations should ensure thread-safety by never mutating internal data structures.
AgentState for the concrete implementation
Properties
Section titled “Properties”
readonlyid:string
Defined in: src/state/types.ts:264
Unique identifier for this state snapshot (UUIDv4)
messages
Section titled “messages”
readonlymessages: readonlyMessage[]
Defined in: src/state/types.ts:267
Immutable conversation history containing UPP Messages
metadata
Section titled “metadata”
readonlymetadata:Readonly<Record<string,unknown>>
Defined in: src/state/types.ts:273
User-defined metadata for storing arbitrary state
readonlyplan: readonlyPlanStep[] |undefined
Defined in: src/state/types.ts:279
Execution plan for Plan-strategy agents (undefined if not using Plan strategy)
reasoning
Section titled “reasoning”
readonlyreasoning: readonlystring[]
Defined in: src/state/types.ts:276
Reasoning traces captured during ReAct-style execution
readonlystep:number
Defined in: src/state/types.ts:270
Current step number in the agent’s execution lifecycle
subagentTraces
Section titled “subagentTraces”
readonlysubagentTraces: readonlySubagentExecutionTrace[]
Defined in: src/state/types.ts:282
Sub-agent execution traces per UAP spec Section 8.8
Methods
Section titled “Methods”toJSON()
Section titled “toJSON()”toJSON():
AgentStateJSON
Defined in: src/state/types.ts:358
Serializes the state to JSON for persistence.
Returns
Section titled “Returns”A JSON-serializable representation of the state
withContext()
Section titled “withContext()”withContext(
messages):AgentStateInterface
Defined in: src/state/types.ts:310
Creates a new state with the entire message context replaced.
Parameters
Section titled “Parameters”messages
Section titled “messages”Message[]
The new complete message history
Returns
Section titled “Returns”AgentStateInterface
A new AgentState instance with the replaced context
Remarks
Section titled “Remarks”Use this for context window management operations like pruning or summarization, where you need to replace the entire history.
withMessage()
Section titled “withMessage()”withMessage(
message):AgentStateInterface
Defined in: src/state/types.ts:290
Creates a new state with the given message appended.
Parameters
Section titled “Parameters”message
Section titled “message”Message
The message to add to the conversation history
Returns
Section titled “Returns”AgentStateInterface
A new AgentState instance with the message appended
withMessages()
Section titled “withMessages()”withMessages(
messages):AgentStateInterface
Defined in: src/state/types.ts:298
Creates a new state with multiple messages appended.
Parameters
Section titled “Parameters”messages
Section titled “messages”Message[]
The messages to add to the conversation history
Returns
Section titled “Returns”AgentStateInterface
A new AgentState instance with all messages appended
withMetadata()
Section titled “withMetadata()”withMetadata(
key,value):AgentStateInterface
Defined in: src/state/types.ts:327
Creates a new state with a metadata entry added or updated.
Parameters
Section titled “Parameters”string
The metadata key
unknown
The value to store
Returns
Section titled “Returns”AgentStateInterface
A new AgentState instance with the updated metadata
withPlan()
Section titled “withPlan()”withPlan(
plan):AgentStateInterface
Defined in: src/state/types.ts:343
Creates a new state with the execution plan set.
Parameters
Section titled “Parameters”PlanStep[]
The execution plan steps
Returns
Section titled “Returns”AgentStateInterface
A new AgentState instance with the plan set
withReasoning()
Section titled “withReasoning()”withReasoning(
reasoning):AgentStateInterface
Defined in: src/state/types.ts:335
Creates a new state with a reasoning trace appended.
Parameters
Section titled “Parameters”reasoning
Section titled “reasoning”string
The reasoning trace to add
Returns
Section titled “Returns”AgentStateInterface
A new AgentState instance with the reasoning appended
withStep()
Section titled “withStep()”withStep(
step):AgentStateInterface
Defined in: src/state/types.ts:318
Creates a new state with an updated step number.
Parameters
Section titled “Parameters”number
The new step number
Returns
Section titled “Returns”AgentStateInterface
A new AgentState instance with the updated step
withSubagentTrace()
Section titled “withSubagentTrace()”withSubagentTrace(
trace):AgentStateInterface
Defined in: src/state/types.ts:351
Creates a new state with a sub-agent execution trace appended.
Parameters
Section titled “Parameters”The sub-agent execution trace to add
Returns
Section titled “Returns”AgentStateInterface
A new AgentState instance with the trace appended