Skip to content

sessions

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History
 
 

sessions

README.md

Sessions & Context Provider Examples

Sessions and context providers are the core building blocks for agent memory in the Agent Framework. Sessions hold conversation state across turns, while context providers add, retrieve, and persist context before and after each agent invocation.

Core Concepts

  • AgentSession: Lightweight state container holding a session_id and a mutable state dict. Pass to agent.run() to maintain conversation across turns.
  • BaseContextProvider: Hook that runs before_run / after_run around each invocation. Use for injecting instructions, RAG context, or metadata.
  • BaseHistoryProvider: Subclass of BaseContextProvider for conversation history storage. Implements get_messages() / save_messages() and handles load/store automatically.
  • InMemoryHistoryProvider: Built-in provider storing messages in session.state. Auto-injected when no providers are configured.

Examples

Session Management

File Description
suspend_resume_session.py Suspend and resume sessions via to_dict() / from_dict() — both service-managed (Azure AI) and in-memory (OpenAI).
custom_history_provider.py Implement a custom BaseHistoryProvider with dict-based storage. Shows serialization/deserialization.
redis_history_provider.py RedisHistoryProvider for persistent storage: basic usage, user sessions, persistence across restarts, serialization, and message trimming.

Custom Context Providers

File Description
simple_context_provider.py Build a custom BaseContextProvider that extracts and stores user information using structured output, then provides dynamic instructions based on stored context.

Azure AI Search

File Description
azure_ai_search/azure_ai_with_search_context_agentic.py Agentic mode — Knowledge Bases with query planning and multi-hop reasoning.
azure_ai_search/azure_ai_with_search_context_semantic.py Semantic mode — fast hybrid search with semantic ranking.

Mem0

File Description
mem0/mem0_basic.py Basic Mem0 integration for user preference memory.
mem0/mem0_sessions.py Session scoping: global scope, per-operation scope, and multi-agent isolation.
mem0/mem0_oss.py Mem0 Open Source (self-hosted) integration.

Redis

File Description
redis/redis_basics.py Standalone provider usage, full-text/hybrid search, preferences, and tool output memory.
redis/redis_conversation.py Conversation persistence across sessions.
redis/redis_sessions.py Session scoping: global, per-operation, and multi-agent isolation.
redis/azure_redis_conversation.py Azure Managed Redis with Entra ID authentication.

Choosing a Provider

Provider Use Case Persistence Search
InMemoryHistoryProvider Prototyping, stateless apps Session state only No
Custom BaseHistoryProvider File/DB-backed storage Your choice Your choice
RedisHistoryProvider Fast persistent chat history Yes (Redis) No
RedisContextProvider Searchable memory / RAG Yes (Redis) Full-text + Hybrid
Mem0ContextProvider Long-term user memory Yes (cloud/self-hosted) Semantic
AzureAISearchContextProvider Enterprise RAG Yes (Azure) Hybrid + Semantic

Building Custom Providers

Custom Context Provider

from agent_framework import AgentSession, BaseContextProvider, SessionContext, Message
from typing import Any

class MyContextProvider(BaseContextProvider):
    def __init__(self):
        super().__init__("my-context")

    async def before_run(self, *, agent: Any, session: AgentSession | None,
                         context: SessionContext, state: dict[str, Any]) -> None:
        context.extend_messages(self.source_id, [Message("system", ["Extra context here"])])

    async def after_run(self, *, agent: Any, session: AgentSession | None,
                        context: SessionContext, state: dict[str, Any]) -> None:
        pass  # Store information, update memory, etc.

Custom History Provider

from agent_framework import BaseHistoryProvider, Message
from collections.abc import Sequence
from typing import Any

class MyHistoryProvider(BaseHistoryProvider):
    def __init__(self):
        super().__init__("my-history")

    async def get_messages(self, session_id: str | None, **kwargs: Any) -> list[Message]:
        ...  # Load from your storage

    async def save_messages(self, session_id: str | None,
                            messages: Sequence[Message], **kwargs: Any) -> None:
        ...  # Persist to your storage

See custom_history_provider.py and simple_context_provider.py for complete examples.