AgentState class
Manages the state of an Agent across turns in a conversation.
Remarks
AgentState provides functionality to persist and retrieve state data using a storage provider. It handles caching state in the turn context for performance, calculating change hashes to detect modifications, and managing property accessors for typed access to state properties.
Constructors
| Agent |
Creates a new instance of AgentState. |
Methods
| clear(Turn |
Clears the state by setting it to an empty object in the turn context. Note: This does not remove the state from storage, it only clears the in-memory representation. Call saveChanges() after this to persist the empty state to storage. |
| create |
Creates a property accessor for the specified property. Property accessors provide typed access to properties within the state object. |
| delete(Turn |
Deletes the state from both the turn context and storage. |
| get(Turn |
Gets the state from the turn context without loading it from storage. |
| load(Turn |
Loads the state from storage into the turn context. If state is already cached in the turn context and force is not set, the cached version will be used. |
| save |
Saves the state to storage if it has changed since it was loaded. Change detection uses a hash of the state object to determine if saving is necessary. |
Constructor Details
AgentState(Storage, StorageKeyFactory)
Creates a new instance of AgentState.
new AgentState(storage: Storage, storageKey: StorageKeyFactory)Parameters
- storage
- Storage
The storage provider used to persist state between turns
- storageKey
- StorageKeyFactory
A factory function that generates keys for storing state data
Method Details
clear(TurnContext)
Clears the state by setting it to an empty object in the turn context. Note: This does not remove the state from storage, it only clears the in-memory representation. Call saveChanges() after this to persist the empty state to storage.
function clear(context: TurnContext): Promise<void>Parameters
- context
- TurnContext
The turn context containing the state to clear
Returns
Promise<void>
A promise that resolves when the clear operation is complete
createProperty<T>(string)
Creates a property accessor for the specified property. Property accessors provide typed access to properties within the state object.
function createProperty<T>(name: string): AgentStatePropertyAccessor<T>Parameters
- name
-
string
The name of the property to access
Returns
A property accessor for the specified property
delete(TurnContext, CustomKey)
Deletes the state from both the turn context and storage.
function delete(context: TurnContext, customKey?: CustomKey): Promise<void>Parameters
- context
- TurnContext
The turn context containing the state to delete
- customKey
- CustomKey
Optional custom storage key to use instead of the default
Returns
Promise<void>
A promise that resolves when the delete operation is complete
get(TurnContext)
Gets the state from the turn context without loading it from storage.
function get(context: TurnContext): anyParameters
- context
- TurnContext
The turn context containing the state to get
Returns
any
The state object, or undefined if no state is found in the turn context
load(TurnContext, boolean, CustomKey)
Loads the state from storage into the turn context. If state is already cached in the turn context and force is not set, the cached version will be used.
function load(context: TurnContext, force?: boolean, customKey?: CustomKey): Promise<any>Parameters
- context
- TurnContext
The turn context to load state into
- force
-
boolean
If true, forces a reload from storage even if state is cached
- customKey
- CustomKey
Optional custom storage key to use instead of the default
Returns
Promise<any>
A promise that resolves to the loaded state object
saveChanges(TurnContext, boolean, CustomKey)
Saves the state to storage if it has changed since it was loaded. Change detection uses a hash of the state object to determine if saving is necessary.
function saveChanges(context: TurnContext, force?: boolean, customKey?: CustomKey): Promise<void>Parameters
- context
- TurnContext
The turn context containing the state to save
- force
-
boolean
If true, forces a save to storage even if no changes are detected
- customKey
- CustomKey
Optional custom storage key to use instead of the default
Returns
Promise<void>
A promise that resolves when the save operation is complete