TurnState Class

Default Turn State

This class manages various AgentState objects and provides a simple interface for setting and retrieving state values.

Constructor

TurnState()

Methods

__init__

Initializes a new instance of the TurnState class.
__new__
add

Adds a new agent state to the turn state.
clear

Clears a state scope.
delete_value

Deletes a value from state.
get_scope

Gets a scope by type.
get_scope_by_name

Gets a scope by name.
get_value

Gets a value from state.
has_value

Checks if a value exists at the specified path.
load

Loads a TurnState instance with the default states.
save

Saves all agent state changes in parallel.
set_value

Sets a value in state.
with_storage

Creates TurnState with default ConversationState and UserState.

__init__

Initializes a new instance of the TurnState class.

__init__(*agent_states: AgentState) -> None

Parameters

Name Description
agent_states
Required
AgentState

Initial list of AgentState objects to manage.

Returns

Type Description
None

__new__ 

__new__(**kwargs)

add

Adds a new agent state to the turn state.

add(agent_state: AgentState) -> TurnState

Parameters

Name Description
agent_state
Required
AgentState

The agent state to add.

Returns

Type Description
TurnState

This instance for chaining.

Exceptions

Type Description
ValueError

If the agent state is None.

clear

Clears a state scope.

clear(turn_context: TurnContext, scope: str = None) -> None

Parameters

Name Description
scope
str

The name of the scope to clear.

Default value: None
turn_context
Required
TurnContext

Returns

Type Description
None

delete_value

Deletes a value from state.

delete_value(path: str) -> None

Parameters

Name Description
path
Required
str

The path to delete, in the format 'scope.property'.

Returns

Type Description
None

get_scope

Gets a scope by type.

get_scope(scope_type: Type[T]) -> T

Parameters

Name Description
scope_type
Required
Type[<xref:microsoft_agents.hosting.core.app.state.turn_state.T>]

The type of scope to get.

Returns

Type Description
<xref:microsoft_agents.hosting.core.app.state.turn_state.T>

The scope object.

Exceptions

Type Description
ValueError

If the scope doesn't exist.

get_scope_by_name

Gets a scope by name.

get_scope_by_name(scope: str) -> AgentState

Parameters

Name Description
scope
Required
str

The name of the scope to get.

Returns

Type Description
AgentState

The scope object.

Exceptions

Type Description
ValueError

If the scope doesn't exist.

get_value

Gets a value from state.

get_value(name: str, default_value_factory: Callable[[], T] | None = None, *, target_cls: Type[T] = None) -> T

Parameters

Name Description
name
Required
str

The name of the value to get, in the format 'scope.property'.
default_value_factory
Callable[[], <xref:microsoft_agents.hosting.core.app.state.turn_state.T>] | None

A function that returns a default value if the value doesn't exist.

Default value: None
target_cls
Required
Type[<xref:microsoft_agents.hosting.core.app.state.turn_state.T>]

Keyword-Only Parameters

Name Description
target_cls
Default value: None

Returns

Type Description
<xref:microsoft_agents.hosting.core.app.state.turn_state.T>

The value, or the default value if it doesn't exist.

has_value

Checks if a value exists at the specified path.

has_value(path: str) -> bool

Parameters

Name Description
path
Required
str

The path to check, in the format 'scope.property'.

Returns

Type Description
bool

True if the value exists, False otherwise.

load

Loads a TurnState instance with the default states.

async load(context: TurnContext, storage: Storage) -> TurnState

Parameters

Name Description
context
Required
TurnContext

The turn context.
storage
Required
Storage

Optional storage to use for the states.

Returns

Type Description
TurnState

A new TurnState instance with loaded states.

save

Saves all agent state changes in parallel.

async save(turn_context: TurnContext, force: bool = False) -> None

Parameters

Name Description
turn_context
Required
TurnContext

The turn context.
force
bool

Whether data should be forced to save even if no change was detected.

Default value: False

Returns

Type Description
None

set_value

Sets a value in state.

set_value(path: str, value: Any) -> None

Parameters

Name Description
path
Required
str

The path to set, in the format 'scope.property'.
value
Required
Any

The value to set.

Returns

Type Description
None

with_storage

Creates TurnState with default ConversationState and UserState.

with_storage(storage: Storage, *agent_states: AgentState) -> TurnState

Parameters

Name Description
storage
Required
Storage

Storage to use for the states.
agent_states
Required
AgentState

Additional list of AgentState objects to manage.

Returns

Type Description
TurnState

A new TurnState instance with the default states.

Attributes

conversation

Gets the conversation state.

temp

Gets the temporary state.

user

Gets the user state.