Session Stores

AgentSessionStore implementations for persisting Agent Framework sessions between requests.

tac_microsoft.agent_framework_types

Type definitions for TAC Agent Framework integration.

AgentSessionStore

Bases: Protocol

Protocol for persisting AgentSession between requests.

Implementations store and retrieve AgentSession objects keyed by session_id (which maps to TAC's conversation_id). This enables conversation continuity across SMS messages regardless of which provider is used:

• Foundry Agent Service: persists the server-side thread_id (stored as session.service_session_id) so subsequent messages reuse the same thread.
• Responses API / Chat Completions: persists session state (including message history from InMemoryHistoryProvider) so conversation context is available across messages.

The default :class:InMemoryAgentSessionStore works for single-instance deployments. For horizontal scaling, provide an implementation backed by Redis, CosmosDB, or another shared store. AgentSession supports serialisation via to_dict() / from_dict().

load async

load(session_id: str) -> AgentSession | None

Load a previously saved session, or None if not found.

save async

save(session_id: str, session: AgentSession) -> None

Persist a session after an agent run.

In-memory

tac_microsoft.stores.in_memory

In-memory AgentSessionStore implementation.

InMemoryAgentSessionStore

InMemoryAgentSessionStore()

In-memory session store for single-instance deployments.

Stores sessions in a plain dict. Suitable for development and single-instance production. For horizontal scaling, replace with a persistent implementation (Redis, CosmosDB, etc.).

File

tac_microsoft.stores.file

File-based AgentSessionStore implementation.

FileAgentSessionStore

FileAgentSessionStore(
    storage_dir: str | Path = "/tmp/tac_sessions",
)

Persist sessions as JSON files on the local filesystem.

Each session is written to {storage_dir}/{session_id}.json using Agent Framework's built-in AgentSession.to_dict() / from_dict() serialisation.

Suitable for single-instance deployments and local development. For horizontal scaling, use :class:CosmosDBAgentSessionStore or another shared store.

Parameters:

Name	Type	Description	Default
storage_dir	str | Path	Directory to store session files. Created automatically if it doesn't exist.	'/tmp/tac_sessions'

load async

load(session_id: str) -> AgentSession | None

Load a session from disk, or return None if not found.

save async

save(session_id: str, session: AgentSession) -> None

Persist a session to disk as JSON.

delete async

delete(session_id: str) -> None

Remove a session file if it exists.

Cosmos DB

Requires the cosmos extra.

tac_microsoft.stores.cosmos

CosmosDB-based AgentSessionStore implementation.

CosmosDBAgentSessionStore

CosmosDBAgentSessionStore(
    endpoint: str,
    credential: Any,
    database_name: str = "tac",
    container_name: str = "sessions",
    ttl: int | None = None,
)

Persist sessions in Azure Cosmos DB for NoSQL.

Uses the async Cosmos client for non-blocking operations. The database and container are created automatically on first use via create_database_if_not_exists / create_container_if_not_exists.

Each session is stored as a document with id set to the session_id and partition key /id, giving optimal point read/write performance.

Parameters:

Name	Type	Description	Default
endpoint	str	Cosmos DB account endpoint URL.	required
credential	Any	Account key (str) or Azure credential object (e.g. DefaultAzureCredential).	required
database_name	str	Database name (created if it doesn't exist).	'tac'
container_name	str	Container name (created if it doesn't exist).	'sessions'
ttl	int | None	Optional time-to-live in seconds for session documents. When set, Cosmos automatically expires old sessions.	None

Example::

from azure.identity.aio import DefaultAzureCredential
from tac_microsoft.stores import CosmosDBAgentSessionStore

store = CosmosDBAgentSessionStore(
    endpoint="https://my-account.documents.azure.com:443/",
    credential=DefaultAzureCredential(),
    database_name="tac",
    container_name="sessions",
    ttl=86400,  # 24 hours
)
connector = AgentFrameworkConnector(tac=tac, ..., session_store=store)

load async

load(session_id: str) -> AgentSession | None

Load a session from Cosmos DB, or return None if not found.

save async

save(session_id: str, session: AgentSession) -> None

Persist a session to Cosmos DB (upsert).

delete async

delete(session_id: str) -> None

Delete a session from Cosmos DB if it exists.

close async

close() -> None

Close the async Cosmos client.