Python: [BREAKING] PR2 — Wire context provider pipeline, remove old types, update all consumers (#3850)

* PR2: Wire context provider pipeline and update all internal consumers - Replace AgentThread with AgentSession across all packages - Replace ContextProvider with BaseContextProvider across all packages - Replace context_provider param with context_providers (Sequence) - Replace thread= with session= in run() signatures - Replace get_new_thread() with create_session() - Add get_session(service_session_id) to agent interface - DurableAgentThread -> DurableAgentSession - Remove _notify_thread_of_new_messages from WorkflowAgent - Wire before_run/after_run context provider pipeline in RawAgent - Auto-inject InMemoryHistoryProvider when no providers configured * fix: update all tests for context provider pipeline, fix lazy-loaders, remove old test files * refactor: update all sample files for context provider pipeline (AgentThread→AgentSession, ContextProvider→BaseContextProvider) * fix: update remaining ag-ui references (client docstring, getting_started sample) * fix: make get_session service_session_id keyword-only to avoid confusion with session_id * refactor: rename _RunContext.thread_messages to session_messages * refactor: remove _threads.py, _memory.py, and old provider files; migrate devui to use plain message lists * rename: remove _new_ prefix from test files * refactor: rewrite SlidingWindowChatMessageStore as SlidingWindowHistoryProvider(InMemoryHistoryProvider) * fix: read full history from session state directly instead of reaching into provider internals * fix: update stale .pyi stubs, sample imports, and README references for new provider types * fix: remove stale message_store, _notify_thread_of_new_messages, and session_id.key references in samples * refactor: merge context_providers and sessions sample folders into sessions, remove aggregate_context_provider * refactor: UserInfoMemory stores state in session.state instead of instance attributes * feat: add Pydantic BaseModel support to session state serialization Pydantic models stored in session.state are now automatically serialized via model_dump() and restored via model_validate() during to_dict()/from_dict() round-trips. Models are auto-registered on first serialization; use register_state_type() for cold-start deserialization. Also export register_state_type as a public API. * fix mem0 * Update sample README links and descriptions for session terminology - Replace 'thread' with 'session' in sample descriptions across all READMEs - Update file links for renamed samples (mem0_sessions, redis_sessions, etc.) - Fix Threads section → Sessions section in main samples/README.md - Update tools, middleware, workflows, durabletask, azure_functions READMEs - Update architecture diagrams in concepts/tools/README.md - Update migration guides (autogen, semantic-kernel) * Fix broken Redis README link to renamed sample * Fix Mem0 OSS client search: pass scoping params as direct kwargs AsyncMemory (OSS) expects user_id/agent_id/run_id as direct kwargs, while AsyncMemoryClient (Platform) expects them in a filters dict. Adds tests for both client types. Port of fix from #3844 to new Mem0ContextProvider. * Fix rebase issues: restore missing _conversation_state.py and checkpoint decode logic - Add back _conversation_state.py (encode/decode_chat_messages) lost in rebase - Fix on_checkpoint_restore to decode cache/conversation with decode_chat_messages - Fix on_checkpoint_restore to use decode_checkpoint_value for pending requests - Add tests/workflow/__init__.py for relative import support - Fix test_agent_executor checkpoint selection (checkpoints[1] not superstep) * Add STORES_BY_DEFAULT ClassVar to skip redundant InMemoryHistoryProvider injection Chat clients that store history server-side by default (OpenAI Responses API, Azure AI Agent) now declare STORES_BY_DEFAULT = True. The agent checks this during auto-injection and skips InMemoryHistoryProvider unless the user explicitly sets store=False. * Fix broken markdown links in azure_ai and redis READMEs * Fix getting-started samples to use session API instead of removed thread/ContextProvider API * updates to workflow as agent * fix group chat import * Rename Thread→Session throughout, fix service_session_id propagation, remove stale AGUIThread - Fix: Propagate conversation_id from ChatResponse back to session.service_session_id in both streaming and non-streaming paths in _agents.py - Rename AgentThreadException → AgentSessionException - Remove stale AGUIThread from ag_ui lazy-loader - Rename use_service_thread → use_service_session in ag-ui package - Rename test functions from *_thread_* to *_session_* - Rename sample files from *_thread* to *_session* - Update docstrings and comments: thread → session - Update _mcp.py kwargs filter: add 'session' alongside 'thread' - Fix ContinuationToken docstring example: thread=thread → session=session - Fix _clients.py docstring: 'Agent threads' → 'Agent sessions' * Fix broken markdown links after thread→session file renames * fix azure ai test
2026-06-16 21:04:09 +08:00 · 2026-02-12 22:00:32 +01:00
parent 0c67dbbce5
commit 1e350ea22f
312 changed files with 6669 additions and 11423 deletions
@@ -14,7 +14,7 @@ This sample demonstrates using Anthropic with an agent and a single custom tool.
 """


-# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, "The location to get the weather for."],
@@ -66,31 +66,31 @@ async def example_with_session_persistence() -> None:
    )

    async with agent:
-        # Create a thread to maintain conversation context
-        thread = agent.get_new_thread()
+        # Create a session to maintain conversation context
+        session = agent.create_session()

        # First query
        query1 = "What's the weather like in Tokyo?"
        print(f"User: {query1}")
-        result1 = await agent.run(query1, thread=thread)
+        result1 = await agent.run(query1, session=session)
        print(f"Agent: {result1.text}")

        # Second query - using same thread maintains context
        query2 = "How about London?"
        print(f"\nUser: {query2}")
-        result2 = await agent.run(query2, thread=thread)
+        result2 = await agent.run(query2, session=session)
        print(f"Agent: {result2.text}")

        # Third query - agent should remember both previous cities
        query3 = "Which of the cities I asked about has better weather?"
        print(f"\nUser: {query3}")
-        result3 = await agent.run(query3, thread=thread)
+        result3 = await agent.run(query3, session=session)
        print(f"Agent: {result3.text}")
        print("Note: The agent remembers context from previous messages in the same session.\n")


 async def example_with_existing_session_id() -> None:
-    """Resume session in new agent instance using service_thread_id."""
+    """Resume session in new agent instance using service_session_id."""
    print("=== Existing Session ID Example ===")

    existing_session_id = None
@@ -102,15 +102,15 @@ async def example_with_existing_session_id() -> None:
    )

    async with agent1:
-        thread = agent1.get_new_thread()
+        session = agent1.create_session()

        query1 = "What's the weather in Paris?"
        print(f"User: {query1}")
-        result1 = await agent1.run(query1, thread=thread)
+        result1 = await agent1.run(query1, session=session)
        print(f"Agent: {result1.text}")

        # Capture the session ID for later use
-        existing_session_id = thread.service_thread_id
+        existing_session_id = session.service_session_id
        print(f"Session ID: {existing_session_id}")

    if existing_session_id:
@@ -123,12 +123,12 @@ async def example_with_existing_session_id() -> None:
        )

        async with agent2:
-            # Create thread with existing session ID
-            thread = agent2.get_new_thread(service_thread_id=existing_session_id)
+            # Create session with existing session ID
+            session = agent2.create_session(service_session_id=existing_session_id)

            query2 = "What was the last city I asked about?"
            print(f"User: {query2}")
-            result2 = await agent2.run(query2, thread=thread)
+            result2 = await agent2.run(query2, session=session)
            print(f"Agent: {result2.text}")
            print("Note: The agent continues the conversation using the session ID.\n")

@@ -20,7 +20,7 @@ This folder contains examples demonstrating different ways to create and use age
 | [`azure_ai_with_code_interpreter_file_download.py`](azure_ai_with_code_interpreter_file_download.py) | Shows how to download files generated by code interpreter using the OpenAI containers API. |
 | [`azure_ai_with_content_filtering.py`](azure_ai_with_content_filtering.py) | Shows how to enable content filtering (RAI policy) on Azure AI agents using `RaiConfig`. Requires creating an RAI policy in Azure AI Foundry portal first. |
 | [`azure_ai_with_existing_agent.py`](azure_ai_with_existing_agent.py) | Shows how to work with a pre-existing agent by providing the agent name and version to the Azure AI client. Demonstrates agent reuse patterns for production scenarios. |
-| [`azure_ai_with_existing_conversation.py`](azure_ai_with_existing_conversation.py) | Demonstrates how to use an existing conversation created on the service side with Azure AI agents. Shows two approaches: specifying conversation ID at the client level and using AgentThread with an existing conversation ID. |
+| [`azure_ai_with_existing_conversation.py`](azure_ai_with_existing_conversation.py) | Demonstrates how to use an existing conversation created on the service side with Azure AI agents. Shows two approaches: specifying conversation ID at the client level and using AgentSession with an existing conversation ID. |
 | [`azure_ai_with_application_endpoint.py`](azure_ai_with_application_endpoint.py) | Demonstrates calling the Azure AI application-scoped endpoint. |
 | [`azure_ai_with_explicit_settings.py`](azure_ai_with_explicit_settings.py) | Shows how to create an agent with explicitly configured `AzureAIClient` settings, including project endpoint, model deployment, and credentials rather than relying on environment variable defaults. |
 | [`azure_ai_with_file_search.py`](azure_ai_with_file_search.py) | Shows how to use `AzureAIClient.get_file_search_tool()` with Azure AI agents to upload files, create vector stores, and enable agents to search through uploaded documents to answer user questions. |
@@ -31,7 +31,7 @@ This folder contains examples demonstrating different ways to create and use age
 | [`azure_ai_with_search_context_agentic.py`](../../context_providers/azure_ai_search/azure_ai_with_search_context_agentic.py) | Shows how to use AzureAISearchContextProvider with agentic mode. Uses Knowledge Bases for multi-hop reasoning across documents with query planning. Recommended for most scenarios - slightly slower with more token consumption for query planning, but more accurate results. |
 | [`azure_ai_with_search_context_semantic.py`](../../context_providers/azure_ai_search/azure_ai_with_search_context_semantic.py) | Shows how to use AzureAISearchContextProvider with semantic mode. Fast hybrid search with vector + keyword search and semantic ranking for RAG. Best for simple queries where speed is critical. |
 | [`azure_ai_with_sharepoint.py`](azure_ai_with_sharepoint.py) | Shows how to use SharePoint grounding with Azure AI agents to search through SharePoint content and answer user questions with proper citations. Requires a SharePoint connection configured in your Azure AI project. |
-| [`azure_ai_with_thread.py`](azure_ai_with_thread.py) | Demonstrates thread management with Azure AI agents, including automatic thread creation for stateless conversations and explicit thread management for maintaining conversation context across multiple interactions. |
+| [`azure_ai_with_session.py`](azure_ai_with_session.py) | Demonstrates session management with Azure AI agents, including automatic session creation for stateless conversations and explicit session management for maintaining conversation context across multiple interactions. |
 | [`azure_ai_with_image_generation.py`](azure_ai_with_image_generation.py) | Shows how to use `AzureAIClient.get_image_generation_tool()` with Azure AI agents to generate images based on text prompts. |
 | [`azure_ai_with_memory_search.py`](azure_ai_with_memory_search.py) | Shows how to use memory search functionality with Azure AI agents for conversation persistence. Demonstrates creating memory stores and enabling agents to search through conversation history. |
 | [`azure_ai_with_microsoft_fabric.py`](azure_ai_with_microsoft_fabric.py) | Shows how to use Microsoft Fabric with Azure AI agents to query Fabric data sources and provide responses based on data analysis. Requires a Microsoft Fabric connection configured in your Azure AI project. |
@@ -92,4 +92,4 @@ python azure_ai_with_code_interpreter.py
 # ... etc
 ```

-The examples demonstrate various patterns for working with Azure AI agents, from basic usage to advanced scenarios like thread management and structured outputs.
+The examples demonstrate various patterns for working with Azure AI agents, from basic usage to advanced scenarios like session management and structured outputs.
@@ -19,7 +19,7 @@ Shows both streaming and non-streaming responses with function tools.

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -29,7 +29,7 @@ Each method returns a Agent that can be used for conversations.

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -20,7 +20,7 @@ while subsequent calls with `get_agent()` reuse the latest agent version.

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -19,7 +19,7 @@ This sample demonstrates usage of AzureAIProjectAgentProvider with existing conv

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -61,9 +61,9 @@ async def example_with_conversation_id() -> None:
        print(f"Agent: {result.text}\n")


-async def example_with_thread() -> None:
-    """This example shows how to specify existing conversation ID with AgentThread."""
-    print("=== Azure AI Agent With Existing Conversation and Thread ===")
+async def example_with_session() -> None:
+    """This example shows how to specify existing conversation ID with AgentSession."""
+    print("=== Azure AI Agent With Existing Conversation and Session ===")
    async with (
        AzureCliCredential() as credential,
        AIProjectClient(endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], credential=credential) as project_client,
@@ -81,23 +81,23 @@ async def example_with_thread() -> None:
        conversation_id = conversation.id
        print(f"Conversation ID: {conversation_id}")

-        # Create a thread with the existing ID
-        thread = agent.get_new_thread(service_thread_id=conversation_id)
+        # Create a session with the existing ID
+        session = agent.create_session(service_session_id=conversation_id)

        query = "What's the weather like in Seattle?"
        print(f"User: {query}")
-        result = await agent.run(query, thread=thread)
+        result = await agent.run(query, session=session)
        print(f"Agent: {result.text}\n")

        query = "What was my last question?"
        print(f"User: {query}")
-        result = await agent.run(query, thread=thread)
+        result = await agent.run(query, session=session)
        print(f"Agent: {result.text}\n")


 async def main() -> None:
    await example_with_conversation_id()
-    await example_with_thread()
+    await example_with_session()


 if __name__ == "__main__":
@@ -20,7 +20,7 @@ settings rather than relying on environment variable defaults.

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -3,7 +3,7 @@
 import asyncio
 from typing import Any

-from agent_framework import AgentResponse, AgentThread, Message, SupportsAgentRun
+from agent_framework import AgentResponse, AgentSession, Message, SupportsAgentRun
 from agent_framework.azure import AzureAIClient, AzureAIProjectAgentProvider
 from azure.identity.aio import AzureCliCredential

@@ -14,8 +14,8 @@ This sample demonstrates integrating hosted Model Context Protocol (MCP) tools w
 """


-async def handle_approvals_without_thread(query: str, agent: "SupportsAgentRun") -> AgentResponse:
-    """When we don't have a thread, we need to ensure we return with the input, approval request and approval."""
+async def handle_approvals_without_session(query: str, agent: "SupportsAgentRun") -> AgentResponse:
+    """When we don't have a session, we need to ensure we return with the input, approval request and approval."""

    result = await agent.run(query, store=False)
    while len(result.user_input_requests) > 0:
@@ -35,10 +35,10 @@ async def handle_approvals_without_thread(query: str, agent: "SupportsAgentRun")
    return result


-async def handle_approvals_with_thread(query: str, agent: "SupportsAgentRun", thread: "AgentThread") -> AgentResponse:
-    """Here we let the thread deal with the previous responses, and we just rerun with the approval."""
+async def handle_approvals_with_session(query: str, agent: "SupportsAgentRun", session: "AgentSession") -> AgentResponse:
+    """Here we let the session deal with the previous responses, and we just rerun with the approval."""

-    result = await agent.run(query, thread=thread)
+    result = await agent.run(query, session=session)
    while len(result.user_input_requests) > 0:
        new_input: list[Any] = []
        for user_input_needed in result.user_input_requests:
@@ -53,7 +53,7 @@ async def handle_approvals_with_thread(query: str, agent: "SupportsAgentRun", th
                    contents=[user_input_needed.to_function_approval_response(user_approval.lower() == "y")],
                )
            )
-        result = await agent.run(new_input, thread=thread)
+        result = await agent.run(new_input, session=session)
    return result


@@ -82,13 +82,13 @@ async def run_hosted_mcp_without_approval() -> None:

        query = "How to create an Azure storage account using az cli?"
        print(f"User: {query}")
-        result = await handle_approvals_without_thread(query, agent)
+        result = await handle_approvals_without_session(query, agent)
        print(f"{agent.name}: {result}\n")


-async def run_hosted_mcp_with_approval_and_thread() -> None:
-    """Example showing MCP Tools with approvals using a thread."""
-    print("=== MCP with approvals and with thread ===")
+async def run_hosted_mcp_with_approval_and_session() -> None:
+    """Example showing MCP Tools with approvals using a session."""
+    print("=== MCP with approvals and with session ===")

    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
    # authentication option.
@@ -111,10 +111,10 @@ async def run_hosted_mcp_with_approval_and_thread() -> None:
            tools=[mcp_tool],
        )

-        thread = agent.get_new_thread()
+        session = agent.create_session()
        query = "Please summarize the Azure REST API specifications Readme"
        print(f"User: {query}")
-        result = await handle_approvals_with_thread(query, agent, thread)
+        result = await handle_approvals_with_session(query, agent, session)
        print(f"{agent.name}: {result}\n")


@@ -122,7 +122,7 @@ async def main() -> None:
    print("=== Azure AI Agent with Hosted MCP Tools Example ===\n")

    await run_hosted_mcp_without_approval()
-    await run_hosted_mcp_with_approval_and_thread()
+    await run_hosted_mcp_with_approval_and_session()


 if __name__ == "__main__":
@@ -10,17 +10,17 @@ from azure.identity.aio import AzureCliCredential
 from pydantic import Field

 """
-Azure AI Agent with Thread Management Example
+Azure AI Agent with Session Management Example

-This sample demonstrates thread management with Azure AI Agent, showing
-persistent conversation capabilities using service-managed threads as well as storing messages in-memory.
+This sample demonstrates session management with Azure AI Agent, showing
+persistent conversation capabilities using service-managed sessions as well as storing messages in-memory.
 """


 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production
 # See:
 # samples/02-agents/tools/function_tool_with_approval.py
-# samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -30,9 +30,9 @@ def get_weather(
    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."


-async def example_with_automatic_thread_creation() -> None:
-    """Example showing automatic thread creation."""
-    print("=== Automatic Thread Creation Example ===")
+async def example_with_automatic_session_creation() -> None:
+    """Example showing automatic session creation."""
+    print("=== Automatic Session Creation Example ===")

    async with (
        AzureCliCredential() as credential,
@@ -44,26 +44,26 @@ async def example_with_automatic_thread_creation() -> None:
            tools=get_weather,
        )

-        # First conversation - no thread provided, will be created automatically
+        # First conversation - no session provided, will be created automatically
        query1 = "What's the weather like in Seattle?"
        print(f"User: {query1}")
        result1 = await agent.run(query1)
        print(f"Agent: {result1.text}")

-        # Second conversation - still no thread provided, will create another new thread
+        # Second conversation - still no session provided, will create another new session
        query2 = "What was the last city I asked about?"
        print(f"\nUser: {query2}")
        result2 = await agent.run(query2)
        print(f"Agent: {result2.text}")
-        print("Note: Each call creates a separate thread, so the agent doesn't remember previous context.\n")
+        print("Note: Each call creates a separate session, so the agent doesn't remember previous context.\n")


-async def example_with_thread_persistence_in_memory() -> None:
+async def example_with_session_persistence_in_memory() -> None:
    """
-    Example showing thread persistence across multiple conversations.
+    Example showing session persistence across multiple conversations.
    In this example, messages are stored in-memory.
    """
-    print("=== Thread Persistence Example (In-Memory) ===")
+    print("=== Session Persistence Example (In-Memory) ===")

    async with (
        AzureCliCredential() as credential,
@@ -75,38 +75,38 @@ async def example_with_thread_persistence_in_memory() -> None:
            tools=get_weather,
        )

-        # Create a new thread that will be reused
-        thread = agent.get_new_thread()
+        # Create a new session that will be reused
+        session = agent.create_session()

        # First conversation
        first_query = "What's the weather like in Tokyo?"
        print(f"User: {first_query}")
-        first_result = await agent.run(first_query, thread=thread, options={"store": False})
+        first_result = await agent.run(first_query, session=session, options={"store": False})
        print(f"Agent: {first_result.text}")

-        # Second conversation using the same thread - maintains context
+        # Second conversation using the same session - maintains context
        second_query = "How about London?"
        print(f"\nUser: {second_query}")
-        second_result = await agent.run(second_query, thread=thread, options={"store": False})
+        second_result = await agent.run(second_query, session=session, options={"store": False})
        print(f"Agent: {second_result.text}")

        # Third conversation - agent should remember both previous cities
        third_query = "Which of the cities I asked about has better weather?"
        print(f"\nUser: {third_query}")
-        third_result = await agent.run(third_query, thread=thread, options={"store": False})
+        third_result = await agent.run(third_query, session=session, options={"store": False})
        print(f"Agent: {third_result.text}")
-        print("Note: The agent remembers context from previous messages in the same thread.\n")
+        print("Note: The agent remembers context from previous messages in the same session.\n")


-async def example_with_existing_thread_id() -> None:
+async def example_with_existing_session_id() -> None:
    """
-    Example showing how to work with an existing thread ID from the service.
+    Example showing how to work with an existing session ID from the service.
    In this example, messages are stored on the server.
    """
-    print("=== Existing Thread ID Example ===")
+    print("=== Existing Session ID Example ===")

-    # First, create a conversation and capture the thread ID
-    existing_thread_id = None
+    # First, create a conversation and capture the session ID
+    existing_session_id = None

    async with (
        AzureCliCredential() as credential,
@@ -118,20 +118,20 @@ async def example_with_existing_thread_id() -> None:
            tools=get_weather,
        )

-        # Start a conversation and get the thread ID
-        thread = agent.get_new_thread()
+        # Start a conversation and get the session ID
+        session = agent.create_session()

        first_query = "What's the weather in Paris?"
        print(f"User: {first_query}")
-        first_result = await agent.run(first_query, thread=thread)
+        first_result = await agent.run(first_query, session=session)
        print(f"Agent: {first_result.text}")

-        # The thread ID is set after the first response
-        existing_thread_id = thread.service_thread_id
-        print(f"Thread ID: {existing_thread_id}")
+        # The session ID is set after the first response
+        existing_session_id = session.service_session_id
+        print(f"Session ID: {existing_session_id}")

-        if existing_thread_id:
-            print("\n--- Continuing with the same thread ID in a new agent instance ---")
+        if existing_session_id:
+            print("\n--- Continuing with the same session ID in a new agent instance ---")

            # Create a new agent instance from the same provider
            second_agent = await provider.create_agent(
@@ -140,22 +140,22 @@ async def example_with_existing_thread_id() -> None:
                tools=get_weather,
            )

-            # Create a thread with the existing ID
-            thread = second_agent.get_new_thread(service_thread_id=existing_thread_id)
+            # Create a session with the existing ID
+            session = second_agent.create_session(service_session_id=existing_session_id)

            second_query = "What was the last city I asked about?"
            print(f"User: {second_query}")
-            second_result = await second_agent.run(second_query, thread=thread)
+            second_result = await second_agent.run(second_query, session=session)
            print(f"Agent: {second_result.text}")
-            print("Note: The agent continues the conversation from the previous thread by using thread ID.\n")
+            print("Note: The agent continues the conversation from the previous session by using session ID.\n")


 async def main() -> None:
-    print("=== Azure AI Agent Thread Management Examples ===\n")
+    print("=== Azure AI Agent Session Management Examples ===\n")

-    await example_with_automatic_thread_creation()
-    await example_with_thread_persistence_in_memory()
-    await example_with_existing_thread_id()
+    await example_with_automatic_session_creation()
+    await example_with_session_persistence_in_memory()
+    await example_with_existing_session_id()


 if __name__ == "__main__":
@@ -38,7 +38,7 @@ async with (
 | [`azure_ai_with_code_interpreter_file_generation.py`](azure_ai_with_code_interpreter_file_generation.py) | Shows how to retrieve file IDs from code interpreter generated files using both streaming and non-streaming approaches. |
 | [`azure_ai_with_code_interpreter.py`](azure_ai_with_code_interpreter.py) | Shows how to use `AzureAIAgentClient.get_code_interpreter_tool()` with Azure AI agents to write and execute Python code. Includes helper methods for accessing code interpreter data from response chunks. |
 | [`azure_ai_with_existing_agent.py`](azure_ai_with_existing_agent.py) | Shows how to work with an existing SDK Agent object using `provider.as_agent()`. This wraps the agent without making HTTP calls. |
-| [`azure_ai_with_existing_thread.py`](azure_ai_with_existing_thread.py) | Shows how to work with a pre-existing thread by providing the thread ID. Demonstrates proper cleanup of manually created threads. |
+| [`azure_ai_with_existing_session.py`](azure_ai_with_existing_session.py) | Shows how to work with a pre-existing session by providing the session ID. Demonstrates proper cleanup of manually created sessions. |
 | [`azure_ai_with_explicit_settings.py`](azure_ai_with_explicit_settings.py) | Shows how to create an agent with explicitly configured provider settings, including project endpoint and model deployment name. |
 | [`azure_ai_with_azure_ai_search.py`](azure_ai_with_azure_ai_search.py) | Demonstrates how to use Azure AI Search with Azure AI agents. Shows how to create an agent with search tools using the SDK directly and wrap it with `provider.get_agent()`. |
 | [`azure_ai_with_file_search.py`](azure_ai_with_file_search.py) | Demonstrates how to use `AzureAIAgentClient.get_file_search_tool()` with Azure AI agents to search through uploaded documents. Shows file upload, vector store creation, and querying document content. |
@@ -46,9 +46,9 @@ async with (
 | [`azure_ai_with_hosted_mcp.py`](azure_ai_with_hosted_mcp.py) | Shows how to use `AzureAIAgentClient.get_mcp_tool()` with hosted Model Context Protocol (MCP) servers for enhanced functionality and tool integration. Demonstrates remote MCP server connections and tool discovery. |
 | [`azure_ai_with_local_mcp.py`](azure_ai_with_local_mcp.py) | Shows how to integrate Azure AI agents with local Model Context Protocol (MCP) servers for enhanced functionality and tool integration. Demonstrates both agent-level and run-level tool configuration. |
 | [`azure_ai_with_multiple_tools.py`](azure_ai_with_multiple_tools.py) | Demonstrates how to use multiple tools together with Azure AI agents, including web search, MCP servers, and function tools using client static methods. Shows coordinated multi-tool interactions and approval workflows. |
-| [`azure_ai_with_openapi_tools.py`](azure_ai_with_openapi_tools.py) | Demonstrates how to use OpenAPI tools with Azure AI agents to integrate external REST APIs. Shows OpenAPI specification loading, anonymous authentication, thread context management, and coordinated multi-API conversations. |
+| [`azure_ai_with_openapi_tools.py`](azure_ai_with_openapi_tools.py) | Demonstrates how to use OpenAPI tools with Azure AI agents to integrate external REST APIs. Shows OpenAPI specification loading, anonymous authentication, session context management, and coordinated multi-API conversations. |
 | [`azure_ai_with_response_format.py`](azure_ai_with_response_format.py) | Demonstrates how to use structured outputs with Azure AI agents using Pydantic models. |
-| [`azure_ai_with_thread.py`](azure_ai_with_thread.py) | Demonstrates thread management with Azure AI agents, including automatic thread creation for stateless conversations and explicit thread management for maintaining conversation context across multiple interactions. |
+| [`azure_ai_with_session.py`](azure_ai_with_session.py) | Demonstrates session management with Azure AI agents, including automatic session creation for stateless conversations and explicit session management for maintaining conversation context across multiple interactions. |

 ## Environment Variables

@@ -17,7 +17,7 @@ lifecycle management. Shows both streaming and non-streaming responses with func
 """


-# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -21,7 +21,7 @@ This sample demonstrates the methods available on the AzureAIAgentsProvider clas
 """


-# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -12,16 +12,16 @@ from azure.identity.aio import AzureCliCredential
 from pydantic import Field

 """
-Azure AI Agent with Existing Thread Example
+Azure AI Agent with Existing Session Example

-This sample demonstrates working with pre-existing conversation threads
-by providing thread IDs for thread reuse patterns.
+This sample demonstrates working with pre-existing conversation sessions
+by providing session IDs for session reuse patterns.
 """


 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -32,7 +32,7 @@ def get_weather(


 async def main() -> None:
-    print("=== Azure AI Agent with Existing Thread ===")
+    print("=== Azure AI Agent with Existing Session ===")

    # Create the client and provider
    async with (
@@ -40,7 +40,7 @@ async def main() -> None:
        AgentsClient(endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], credential=credential) as agents_client,
        AzureAIAgentsProvider(agents_client=agents_client) as provider,
    ):
-        # Create a thread that will persist
+        # Create a session that will persist
        created_thread = await agents_client.threads.create()

        try:
@@ -51,12 +51,11 @@ async def main() -> None:
                tools=get_weather,
            )

-            thread = agent.get_new_thread(service_thread_id=created_thread.id)
-            assert thread.is_initialized
-            result = await agent.run("What's the weather like in Tokyo?", thread=thread)
+            session = agent.get_session(service_session_id=created_thread.id)
+            result = await agent.run("What's the weather like in Tokyo?", session=session)
            print(f"Result: {result}\n")
        finally:
-            # Clean up the thread manually
+            # Clean up the session manually
            await agents_client.threads.delete(created_thread.id)


@@ -20,7 +20,7 @@ settings rather than relying on environment variable defaults.

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -20,7 +20,7 @@ showing both agent-level and query-level tool configuration patterns.

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -3,7 +3,7 @@
 import asyncio
 from typing import Any

-from agent_framework import AgentResponse, AgentThread, SupportsAgentRun
+from agent_framework import AgentResponse, AgentSession, SupportsAgentRun
 from agent_framework.azure import AzureAIAgentClient, AzureAIAgentsProvider
 from azure.identity.aio import AzureCliCredential

@@ -15,11 +15,11 @@ servers, including user approval workflows for function call security.
 """


-async def handle_approvals_with_thread(query: str, agent: "SupportsAgentRun", thread: "AgentThread") -> AgentResponse:
-    """Here we let the thread deal with the previous responses, and we just rerun with the approval."""
+async def handle_approvals_with_session(query: str, agent: "SupportsAgentRun", session: "AgentSession") -> AgentResponse:
+    """Here we let the session deal with the previous responses, and we just rerun with the approval."""
    from agent_framework import Message

-    result = await agent.run(query, thread=thread, store=True)
+    result = await agent.run(query, session=session, store=True)
    while len(result.user_input_requests) > 0:
        new_input: list[Any] = []
        for user_input_needed in result.user_input_requests:
@@ -34,7 +34,7 @@ async def handle_approvals_with_thread(query: str, agent: "SupportsAgentRun", th
                    contents=[user_input_needed.to_function_approval_response(user_approval.lower() == "y")],
                )
            )
-        result = await agent.run(new_input, thread=thread, store=True)
+        result = await agent.run(new_input, session=session, store=True)
    return result


@@ -58,17 +58,17 @@ async def main() -> None:
            instructions="You are a helpful assistant that can help with microsoft documentation questions.",
            tools=[mcp_tool],
        )
-        thread = agent.get_new_thread()
+        session = agent.create_session()
        # First query
        query1 = "How to create an Azure storage account using az cli?"
        print(f"User: {query1}")
-        result1 = await handle_approvals_with_thread(query1, agent, thread)
+        result1 = await handle_approvals_with_session(query1, agent, session)
        print(f"{agent.name}: {result1}\n")
        print("\n=======================================\n")
        # Second query
        query2 = "What is Microsoft Agent Framework?"
        print(f"User: {query2}")
-        result2 = await handle_approvals_with_thread(query2, agent, thread)
+        result2 = await handle_approvals_with_session(query2, agent, session)
        print(f"{agent.name}: {result2}\n")


@@ -5,7 +5,7 @@ from datetime import datetime, timezone
 from typing import Any

 from agent_framework import (
-    AgentThread,
+    AgentSession,
    SupportsAgentRun,
    tool,
 )
@@ -35,7 +35,7 @@ To set up Bing Grounding:

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_time() -> str:
    """Get the current UTC time."""
@@ -43,11 +43,11 @@ def get_time() -> str:
    return f"The current UTC time is {current_time.strftime('%Y-%m-%d %H:%M:%S')}."


-async def handle_approvals_with_thread(query: str, agent: "SupportsAgentRun", thread: "AgentThread"):
-    """Here we let the thread deal with the previous responses, and we just rerun with the approval."""
+async def handle_approvals_with_session(query: str, agent: "SupportsAgentRun", session: "AgentSession"):
+    """Here we let the session deal with the previous responses, and we just rerun with the approval."""
    from agent_framework import Message

-    result = await agent.run(query, thread=thread, store=True)
+    result = await agent.run(query, session=session, store=True)
    while len(result.user_input_requests) > 0:
        new_input: list[Any] = []
        for user_input_needed in result.user_input_requests:
@@ -62,7 +62,7 @@ async def handle_approvals_with_thread(query: str, agent: "SupportsAgentRun", th
                    contents=[user_input_needed.to_function_approval_response(user_approval.lower() == "y")],
                )
            )
-        result = await agent.run(new_input, thread=thread, store=True)
+        result = await agent.run(new_input, session=session, store=True)
    return result


@@ -91,17 +91,17 @@ async def main() -> None:
                get_time,
            ],
        )
-        thread = agent.get_new_thread()
+        session = agent.create_session()
        # First query
        query1 = "How to create an Azure storage account using az cli and what time is it?"
        print(f"User: {query1}")
-        result1 = await handle_approvals_with_thread(query1, agent, thread)
+        result1 = await handle_approvals_with_session(query1, agent, session)
        print(f"{agent.name}: {result1}\n")
        print("\n=======================================\n")
        # Second query
        query2 = "What is Microsoft Agent Framework and use a web search to see what is Reddit saying about it?"
        print(f"User: {query2}")
-        result2 = await handle_approvals_with_thread(query2, agent, thread)
+        result2 = await handle_approvals_with_session(query2, agent, session)
        print(f"{agent.name}: {result2}\n")


@@ -76,16 +76,16 @@ async def main() -> None:
            tools=[*openapi_countries.definitions, *openapi_weather.definitions],
        )

-        # 5. Simulate conversation with the agent maintaining thread context
+        # 5. Simulate conversation with the agent maintaining session context
        print("=== Azure AI Agent with OpenAPI Tools ===\n")

-        # Create a thread to maintain conversation context across multiple runs
-        thread = agent.get_new_thread()
+        # Create a session to maintain conversation context across multiple runs
+        session = agent.create_session()

        for user_input in USER_INPUTS:
            print(f"User: {user_input}")
-            # Pass the thread to maintain context across multiple agent.run() calls
-            response = await agent.run(user_input, thread=thread)
+            # Pass the session to maintain context across multiple agent.run() calls
+            response = await agent.run(user_input, session=session)
            print(f"Agent: {response.text}\n")


@@ -4,22 +4,22 @@ import asyncio
 from random import randint
 from typing import Annotated

-from agent_framework import AgentThread, tool
+from agent_framework import AgentSession, tool
 from agent_framework.azure import AzureAIAgentsProvider
 from azure.identity.aio import AzureCliCredential
 from pydantic import Field

 """
-Azure AI Agent with Thread Management Example
+Azure AI Agent with Session Management Example

-This sample demonstrates thread management with Azure AI Agents, comparing
-automatic thread creation with explicit thread management for persistent context.
+This sample demonstrates session management with Azure AI Agents, comparing
+automatic session creation with explicit session management for persistent context.
 """


 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -29,9 +29,9 @@ def get_weather(
    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."


-async def example_with_automatic_thread_creation() -> None:
-    """Example showing automatic thread creation (service-managed thread)."""
-    print("=== Automatic Thread Creation Example ===")
+async def example_with_automatic_session_creation() -> None:
+    """Example showing automatic session creation (service-managed session)."""
+    print("=== Automatic Session Creation Example ===")

    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
    # authentication option.
@@ -45,24 +45,24 @@ async def example_with_automatic_thread_creation() -> None:
            tools=get_weather,
        )

-        # First conversation - no thread provided, will be created automatically
+        # First conversation - no session provided, will be created automatically
        first_query = "What's the weather like in Seattle?"
        print(f"User: {first_query}")
        first_result = await agent.run(first_query)
        print(f"Agent: {first_result.text}")

-        # Second conversation - still no thread provided, will create another new thread
+        # Second conversation - still no session provided, will create another new session
        second_query = "What was the last city I asked about?"
        print(f"\nUser: {second_query}")
        second_result = await agent.run(second_query)
        print(f"Agent: {second_result.text}")
-        print("Note: Each call creates a separate thread, so the agent doesn't remember previous context.\n")
+        print("Note: Each call creates a separate session, so the agent doesn't remember previous context.\n")


-async def example_with_thread_persistence() -> None:
-    """Example showing thread persistence across multiple conversations."""
-    print("=== Thread Persistence Example ===")
-    print("Using the same thread across multiple conversations to maintain context.\n")
+async def example_with_session_persistence() -> None:
+    """Example showing session persistence across multiple conversations."""
+    print("=== Session Persistence Example ===")
+    print("Using the same session across multiple conversations to maintain context.\n")

    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
    # authentication option.
@@ -76,36 +76,36 @@ async def example_with_thread_persistence() -> None:
            tools=get_weather,
        )

-        # Create a new thread that will be reused
-        thread = agent.get_new_thread()
+        # Create a new session that will be reused
+        session = agent.create_session()

        # First conversation
        first_query = "What's the weather like in Tokyo?"
        print(f"User: {first_query}")
-        first_result = await agent.run(first_query, thread=thread)
+        first_result = await agent.run(first_query, session=session)
        print(f"Agent: {first_result.text}")

-        # Second conversation using the same thread - maintains context
+        # Second conversation using the same session - maintains context
        second_query = "How about London?"
        print(f"\nUser: {second_query}")
-        second_result = await agent.run(second_query, thread=thread)
+        second_result = await agent.run(second_query, session=session)
        print(f"Agent: {second_result.text}")

        # Third conversation - agent should remember both previous cities
        third_query = "Which of the cities I asked about has better weather?"
        print(f"\nUser: {third_query}")
-        third_result = await agent.run(third_query, thread=thread)
+        third_result = await agent.run(third_query, session=session)
        print(f"Agent: {third_result.text}")
-        print("Note: The agent remembers context from previous messages in the same thread.\n")
+        print("Note: The agent remembers context from previous messages in the same session.\n")


-async def example_with_existing_thread_id() -> None:
-    """Example showing how to work with an existing thread ID from the service."""
-    print("=== Existing Thread ID Example ===")
-    print("Using a specific thread ID to continue an existing conversation.\n")
+async def example_with_existing_session_id() -> None:
+    """Example showing how to work with an existing session ID from the service."""
+    print("=== Existing Session ID Example ===")
+    print("Using a specific session ID to continue an existing conversation.\n")

-    # First, create a conversation and capture the thread ID
-    existing_thread_id = None
+    # First, create a conversation and capture the session ID
+    existing_session_id = None

    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
    # authentication option.
@@ -119,21 +119,21 @@ async def example_with_existing_thread_id() -> None:
            tools=get_weather,
        )

-        # Start a conversation and get the thread ID
-        thread = agent.get_new_thread()
+        # Start a conversation and get the session ID
+        session = agent.create_session()
        first_query = "What's the weather in Paris?"
        print(f"User: {first_query}")
-        first_result = await agent.run(first_query, thread=thread)
+        first_result = await agent.run(first_query, session=session)
        print(f"Agent: {first_result.text}")

-        # The thread ID is set after the first response
-        existing_thread_id = thread.service_thread_id
-        print(f"Thread ID: {existing_thread_id}")
+        # The session ID is set after the first response
+        existing_session_id = session.service_session_id
+        print(f"Session ID: {existing_session_id}")

-    if existing_thread_id:
-        print("\n--- Continuing with the same thread ID in a new agent instance ---")
+    if existing_session_id:
+        print("\n--- Continuing with the same session ID in a new agent instance ---")

-        # Create a new provider and agent but use the existing thread ID
+        # Create a new provider and agent but use the existing session ID
        async with (
            AzureCliCredential() as credential,
            AzureAIAgentsProvider(credential=credential) as provider,
@@ -144,22 +144,22 @@ async def example_with_existing_thread_id() -> None:
                tools=get_weather,
            )

-            # Create a thread with the existing ID
-            thread = AgentThread(service_thread_id=existing_thread_id)
+            # Create a session with the existing ID
+            session = AgentSession(service_session_id=existing_session_id)

            second_query = "What was the last city I asked about?"
            print(f"User: {second_query}")
-            second_result = await agent.run(second_query, thread=thread)
+            second_result = await agent.run(second_query, session=session)
            print(f"Agent: {second_result.text}")
-            print("Note: The agent continues the conversation from the previous thread.\n")
+            print("Note: The agent continues the conversation from the previous session.\n")


 async def main() -> None:
-    print("=== Azure AI Chat Client Agent Thread Management Examples ===\n")
+    print("=== Azure AI Chat Client Agent Session Management Examples ===\n")

-    await example_with_automatic_thread_creation()
-    await example_with_thread_persistence()
-    await example_with_existing_thread_id()
+    await example_with_automatic_session_creation()
+    await example_with_session_persistence()
+    await example_with_existing_session_id()


 if __name__ == "__main__":
@@ -11,11 +11,11 @@ This folder contains examples demonstrating different ways to create and use age
 | [`azure_assistants_with_existing_assistant.py`](azure_assistants_with_existing_assistant.py) | Shows how to work with a pre-existing assistant by providing the assistant ID to the Azure Assistants client. Demonstrates proper cleanup of manually created assistants. |
 | [`azure_assistants_with_explicit_settings.py`](azure_assistants_with_explicit_settings.py) | Shows how to initialize an agent with a specific assistants client, configuring settings explicitly including endpoint and deployment name. |
 | [`azure_assistants_with_function_tools.py`](azure_assistants_with_function_tools.py) | Demonstrates how to use function tools with agents. Shows both agent-level tools (defined when creating the agent) and query-level tools (provided with specific queries). |
-| [`azure_assistants_with_thread.py`](azure_assistants_with_thread.py) | Demonstrates thread management with Azure agents, including automatic thread creation for stateless conversations and explicit thread management for maintaining conversation context across multiple interactions. |
+| [`azure_assistants_with_session.py`](azure_assistants_with_session.py) | Demonstrates session management with Azure agents, including automatic session creation for stateless conversations and explicit session management for maintaining conversation context across multiple interactions. |
 | [`azure_chat_client_basic.py`](azure_chat_client_basic.py) | The simplest way to create an agent using `Agent` with `AzureOpenAIChatClient`. Shows both streaming and non-streaming responses for chat-based interactions with Azure OpenAI models. |
 | [`azure_chat_client_with_explicit_settings.py`](azure_chat_client_with_explicit_settings.py) | Shows how to initialize an agent with a specific chat client, configuring settings explicitly including endpoint and deployment name. |
 | [`azure_chat_client_with_function_tools.py`](azure_chat_client_with_function_tools.py) | Demonstrates how to use function tools with agents. Shows both agent-level tools (defined when creating the agent) and query-level tools (provided with specific queries). |
-| [`azure_chat_client_with_thread.py`](azure_chat_client_with_thread.py) | Demonstrates thread management with Azure agents, including automatic thread creation for stateless conversations and explicit thread management for maintaining conversation context across multiple interactions. |
+| [`azure_chat_client_with_session.py`](azure_chat_client_with_session.py) | Demonstrates session management with Azure agents, including automatic session creation for stateless conversations and explicit session management for maintaining conversation context across multiple interactions. |
 | [`azure_responses_client_basic.py`](azure_responses_client_basic.py) | The simplest way to create an agent using `Agent` with `AzureOpenAIResponsesClient`. Shows both streaming and non-streaming responses for structured response generation with Azure OpenAI models. |
 | [`azure_responses_client_code_interpreter_files.py`](azure_responses_client_code_interpreter_files.py) | Demonstrates using `AzureOpenAIResponsesClient.get_code_interpreter_tool()` with file uploads for data analysis. Shows how to create, upload, and analyze CSV files using Python code execution with Azure OpenAI Responses. |
 | [`azure_responses_client_image_analysis.py`](azure_responses_client_image_analysis.py) | Shows how to use Azure OpenAI Responses for image analysis and vision tasks. Demonstrates multi-modal messages combining text and image content using remote URLs. |
@@ -26,7 +26,7 @@ This folder contains examples demonstrating different ways to create and use age
 | [`azure_responses_client_with_function_tools.py`](azure_responses_client_with_function_tools.py) | Demonstrates how to use function tools with agents. Shows both agent-level tools (defined when creating the agent) and query-level tools (provided with specific queries). |
 | [`azure_responses_client_with_hosted_mcp.py`](azure_responses_client_with_hosted_mcp.py) | Shows how to integrate Azure OpenAI Responses Client with hosted Model Context Protocol (MCP) servers using `AzureOpenAIResponsesClient.get_mcp_tool()` for extended functionality. |
 | [`azure_responses_client_with_local_mcp.py`](azure_responses_client_with_local_mcp.py) | Shows how to integrate Azure OpenAI Responses Client with local Model Context Protocol (MCP) servers using MCPStreamableHTTPTool for extended functionality. |
-| [`azure_responses_client_with_thread.py`](azure_responses_client_with_thread.py) | Demonstrates thread management with Azure agents, including automatic thread creation for stateless conversations and explicit thread management for maintaining conversation context across multiple interactions. |
+| [`azure_responses_client_with_session.py`](azure_responses_client_with_session.py) | Demonstrates session management with Azure agents, including automatic session creation for stateless conversations and explicit session management for maintaining conversation context across multiple interactions. |

 ## Environment Variables

@@ -17,7 +17,7 @@ assistant lifecycle management, showing both streaming and non-streaming respons
 """


-# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -21,7 +21,7 @@ using existing assistant IDs rather than creating new ones.

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -20,7 +20,7 @@ settings rather than relying on environment variable defaults.

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -20,7 +20,7 @@ showing both agent-level and query-level tool configuration patterns.

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -4,22 +4,22 @@ import asyncio
 from random import randint
 from typing import Annotated

-from agent_framework import Agent, AgentThread, tool
+from agent_framework import Agent, AgentSession, tool
 from agent_framework.azure import AzureOpenAIAssistantsClient
 from azure.identity import AzureCliCredential
 from pydantic import Field

 """
-Azure OpenAI Assistants with Thread Management Example
+Azure OpenAI Assistants with Session Management Example

-This sample demonstrates thread management with Azure OpenAI Assistants, comparing
-automatic thread creation with explicit thread management for persistent context.
+This sample demonstrates session management with Azure OpenAI Assistants, comparing
+automatic session creation with explicit session management for persistent context.
 """


 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -29,9 +29,9 @@ def get_weather(
    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."


-async def example_with_automatic_thread_creation() -> None:
-    """Example showing automatic thread creation (service-managed thread)."""
-    print("=== Automatic Thread Creation Example ===")
+async def example_with_automatic_session_creation() -> None:
+    """Example showing automatic session creation (service-managed session)."""
+    print("=== Automatic Session Creation Example ===")

    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
    # authentication option.
@@ -40,24 +40,24 @@ async def example_with_automatic_thread_creation() -> None:
        instructions="You are a helpful weather agent.",
        tools=get_weather,
    ) as agent:
-        # First conversation - no thread provided, will be created automatically
+        # First conversation - no session provided, will be created automatically
        query1 = "What's the weather like in Seattle?"
        print(f"User: {query1}")
        result1 = await agent.run(query1)
        print(f"Agent: {result1.text}")

-        # Second conversation - still no thread provided, will create another new thread
+        # Second conversation - still no session provided, will create another new session
        query2 = "What was the last city I asked about?"
        print(f"\nUser: {query2}")
        result2 = await agent.run(query2)
        print(f"Agent: {result2.text}")
-        print("Note: Each call creates a separate thread, so the agent doesn't remember previous context.\n")
+        print("Note: Each call creates a separate session, so the agent doesn't remember previous context.\n")


-async def example_with_thread_persistence() -> None:
-    """Example showing thread persistence across multiple conversations."""
-    print("=== Thread Persistence Example ===")
-    print("Using the same thread across multiple conversations to maintain context.\n")
+async def example_with_session_persistence() -> None:
+    """Example showing session persistence across multiple conversations."""
+    print("=== Session Persistence Example ===")
+    print("Using the same session across multiple conversations to maintain context.\n")

    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
    # authentication option.
@@ -66,36 +66,36 @@ async def example_with_thread_persistence() -> None:
        instructions="You are a helpful weather agent.",
        tools=get_weather,
    ) as agent:
-        # Create a new thread that will be reused
-        thread = agent.get_new_thread()
+        # Create a new session that will be reused
+        session = agent.create_session()

        # First conversation
        query1 = "What's the weather like in Tokyo?"
        print(f"User: {query1}")
-        result1 = await agent.run(query1, thread=thread)
+        result1 = await agent.run(query1, session=session)
        print(f"Agent: {result1.text}")

-        # Second conversation using the same thread - maintains context
+        # Second conversation using the same session - maintains context
        query2 = "How about London?"
        print(f"\nUser: {query2}")
-        result2 = await agent.run(query2, thread=thread)
+        result2 = await agent.run(query2, session=session)
        print(f"Agent: {result2.text}")

        # Third conversation - agent should remember both previous cities
        query3 = "Which of the cities I asked about has better weather?"
        print(f"\nUser: {query3}")
-        result3 = await agent.run(query3, thread=thread)
+        result3 = await agent.run(query3, session=session)
        print(f"Agent: {result3.text}")
-        print("Note: The agent remembers context from previous messages in the same thread.\n")
+        print("Note: The agent remembers context from previous messages in the same session.\n")


-async def example_with_existing_thread_id() -> None:
-    """Example showing how to work with an existing thread ID from the service."""
-    print("=== Existing Thread ID Example ===")
-    print("Using a specific thread ID to continue an existing conversation.\n")
+async def example_with_existing_session_id() -> None:
+    """Example showing how to work with an existing session ID from the service."""
+    print("=== Existing Session ID Example ===")
+    print("Using a specific session ID to continue an existing conversation.\n")

-    # First, create a conversation and capture the thread ID
-    existing_thread_id = None
+    # First, create a conversation and capture the session ID
+    existing_session_id = None

    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
    # authentication option.
@@ -104,42 +104,42 @@ async def example_with_existing_thread_id() -> None:
        instructions="You are a helpful weather agent.",
        tools=get_weather,
    ) as agent:
-        # Start a conversation and get the thread ID
-        thread = agent.get_new_thread()
+        # Start a conversation and get the session ID
+        session = agent.create_session()
        query1 = "What's the weather in Paris?"
        print(f"User: {query1}")
-        result1 = await agent.run(query1, thread=thread)
+        result1 = await agent.run(query1, session=session)
        print(f"Agent: {result1.text}")

-        # The thread ID is set after the first response
-        existing_thread_id = thread.service_thread_id
-        print(f"Thread ID: {existing_thread_id}")
+        # The session ID is set after the first response
+        existing_session_id = session.service_session_id
+        print(f"Session ID: {existing_session_id}")

-    if existing_thread_id:
-        print("\n--- Continuing with the same thread ID in a new agent instance ---")
+    if existing_session_id:
+        print("\n--- Continuing with the same session ID in a new agent instance ---")

-        # Create a new agent instance but use the existing thread ID
+        # Create a new agent instance but use the existing session ID
        async with Agent(
-            client=AzureOpenAIAssistantsClient(thread_id=existing_thread_id, credential=AzureCliCredential()),
+            client=AzureOpenAIAssistantsClient(thread_id=existing_session_id, credential=AzureCliCredential()),
            instructions="You are a helpful weather agent.",
            tools=get_weather,
        ) as agent:
-            # Create a thread with the existing ID
-            thread = AgentThread(service_thread_id=existing_thread_id)
+            # Create a session with the existing ID
+            session = AgentSession(service_session_id=existing_session_id)

            query2 = "What was the last city I asked about?"
            print(f"User: {query2}")
-            result2 = await agent.run(query2, thread=thread)
+            result2 = await agent.run(query2, session=session)
            print(f"Agent: {result2.text}")
-            print("Note: The agent continues the conversation from the previous thread.\n")
+            print("Note: The agent continues the conversation from the previous session.\n")


 async def main() -> None:
-    print("=== Azure OpenAI Assistants Chat Client Agent Thread Management Examples ===\n")
+    print("=== Azure OpenAI Assistants Chat Client Agent Session Management Examples ===\n")

-    await example_with_automatic_thread_creation()
-    await example_with_thread_persistence()
-    await example_with_existing_thread_id()
+    await example_with_automatic_session_creation()
+    await example_with_session_persistence()
+    await example_with_existing_session_id()


 if __name__ == "__main__":
@@ -19,7 +19,7 @@ interactions, showing both streaming and non-streaming responses.

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -20,7 +20,7 @@ settings rather than relying on environment variable defaults.

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -20,7 +20,7 @@ showing both agent-level and query-level tool configuration patterns.

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -4,22 +4,22 @@ import asyncio
 from random import randint
 from typing import Annotated

-from agent_framework import Agent, AgentThread, ChatMessageStore, tool
+from agent_framework import Agent, AgentSession, tool
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
 from pydantic import Field

 """
-Azure OpenAI Chat Client with Thread Management Example
+Azure OpenAI Chat Client with Session Management Example

-This sample demonstrates thread management with Azure OpenAI Chat Client, comparing
-automatic thread creation with explicit thread management for persistent context.
+This sample demonstrates session management with Azure OpenAI Chat Client, comparing
+automatic session creation with explicit session management for persistent context.
 """


 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -29,9 +29,9 @@ def get_weather(
    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."


-async def example_with_automatic_thread_creation() -> None:
-    """Example showing automatic thread creation (service-managed thread)."""
-    print("=== Automatic Thread Creation Example ===")
+async def example_with_automatic_session_creation() -> None:
+    """Example showing automatic session creation (service-managed session)."""
+    print("=== Automatic Session Creation Example ===")

    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
    # authentication option.
@@ -41,24 +41,24 @@ async def example_with_automatic_thread_creation() -> None:
        tools=get_weather,
    )

-    # First conversation - no thread provided, will be created automatically
+    # First conversation - no session provided, will be created automatically
    query1 = "What's the weather like in Seattle?"
    print(f"User: {query1}")
    result1 = await agent.run(query1)
    print(f"Agent: {result1.text}")

-    # Second conversation - still no thread provided, will create another new thread
+    # Second conversation - still no session provided, will create another new session
    query2 = "What was the last city I asked about?"
    print(f"\nUser: {query2}")
    result2 = await agent.run(query2)
    print(f"Agent: {result2.text}")
-    print("Note: Each call creates a separate thread, so the agent doesn't remember previous context.\n")
+    print("Note: Each call creates a separate session, so the agent doesn't remember previous context.\n")


-async def example_with_thread_persistence() -> None:
-    """Example showing thread persistence across multiple conversations."""
-    print("=== Thread Persistence Example ===")
-    print("Using the same thread across multiple conversations to maintain context.\n")
+async def example_with_session_persistence() -> None:
+    """Example showing session persistence across multiple conversations."""
+    print("=== Session Persistence Example ===")
+    print("Using the same session across multiple conversations to maintain context.\n")

    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
    # authentication option.
@@ -68,32 +68,32 @@ async def example_with_thread_persistence() -> None:
        tools=get_weather,
    )

-    # Create a new thread that will be reused
-    thread = agent.get_new_thread()
+    # Create a new session that will be reused
+    session = agent.create_session()

    # First conversation
    query1 = "What's the weather like in Tokyo?"
    print(f"User: {query1}")
-    result1 = await agent.run(query1, thread=thread)
+    result1 = await agent.run(query1, session=session)
    print(f"Agent: {result1.text}")

-    # Second conversation using the same thread - maintains context
+    # Second conversation using the same session - maintains context
    query2 = "How about London?"
    print(f"\nUser: {query2}")
-    result2 = await agent.run(query2, thread=thread)
+    result2 = await agent.run(query2, session=session)
    print(f"Agent: {result2.text}")

    # Third conversation - agent should remember both previous cities
    query3 = "Which of the cities I asked about has better weather?"
    print(f"\nUser: {query3}")
-    result3 = await agent.run(query3, thread=thread)
+    result3 = await agent.run(query3, session=session)
    print(f"Agent: {result3.text}")
-    print("Note: The agent remembers context from previous messages in the same thread.\n")
+    print("Note: The agent remembers context from previous messages in the same session.\n")


-async def example_with_existing_thread_messages() -> None:
-    """Example showing how to work with existing thread messages for Azure."""
-    print("=== Existing Thread Messages Example ===")
+async def example_with_existing_session_messages() -> None:
+    """Example showing how to work with existing session messages for Azure."""
+    print("=== Existing Session Messages Example ===")

    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
    # authentication option.
@@ -104,53 +104,53 @@ async def example_with_existing_thread_messages() -> None:
    )

    # Start a conversation and build up message history
-    thread = agent.get_new_thread()
+    session = agent.create_session()

    query1 = "What's the weather in Paris?"
    print(f"User: {query1}")
-    result1 = await agent.run(query1, thread=thread)
+    result1 = await agent.run(query1, session=session)
    print(f"Agent: {result1.text}")

-    # The thread now contains the conversation history in memory
-    if thread.message_store:
-        messages = await thread.message_store.list_messages()
-        print(f"Thread contains {len(messages or [])} messages")
+    # The session now contains the conversation history in state
+    memory_state = session.state.get("memory", {})
+    messages = memory_state.get("messages", [])
+    if messages:
+        print(f"Session contains {len(messages)} messages")

-    print("\n--- Continuing with the same thread in a new agent instance ---")
+    print("\n--- Continuing with the same session in a new agent instance ---")

-    # Create a new agent instance but use the existing thread with its message history
+    # Create a new agent instance but use the existing session with its message history
    new_agent = Agent(
        client=AzureOpenAIChatClient(credential=AzureCliCredential()),
        instructions="You are a helpful weather agent.",
        tools=get_weather,
    )

-    # Use the same thread object which contains the conversation history
+    # Use the same session object which contains the conversation history
    query2 = "What was the last city I asked about?"
    print(f"User: {query2}")
-    result2 = await new_agent.run(query2, thread=thread)
+    result2 = await new_agent.run(query2, session=session)
    print(f"Agent: {result2.text}")
    print("Note: The agent continues the conversation using the local message history.\n")

-    print("\n--- Alternative: Creating a new thread from existing messages ---")
+    print("\n--- Alternative: Creating a new session from existing messages ---")

-    # You can also create a new thread from existing messages
-    messages = await thread.message_store.list_messages() if thread.message_store else []
-    new_thread = AgentThread(message_store=ChatMessageStore(messages))
+    # You can also create a new session from existing messages
+    new_session = AgentSession()

    query3 = "How does the Paris weather compare to London?"
    print(f"User: {query3}")
-    result3 = await new_agent.run(query3, thread=new_thread)
+    result3 = await new_agent.run(query3, session=new_session)
    print(f"Agent: {result3.text}")
-    print("Note: This creates a new thread with the same conversation history.\n")
+    print("Note: This creates a new session with the same conversation history.\n")


 async def main() -> None:
-    print("=== Azure Chat Client Agent Thread Management Examples ===\n")
+    print("=== Azure Chat Client Agent Session Management Examples ===\n")

-    await example_with_automatic_thread_creation()
-    await example_with_thread_persistence()
-    await example_with_existing_thread_messages()
+    await example_with_automatic_session_creation()
+    await example_with_session_persistence()
+    await example_with_existing_session_messages()


 if __name__ == "__main__":
@@ -19,7 +19,7 @@ response generation, showing both streaming and non-streaming responses.

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -20,7 +20,7 @@ settings rather than relying on environment variable defaults.

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -28,7 +28,7 @@ This requires:
 load_dotenv()  # Load environment variables from .env file if present


-# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -20,7 +20,7 @@ showing both agent-level and query-level tool configuration patterns.

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -15,11 +15,11 @@ Azure OpenAI Responses Client, including user approval workflows for function ca
 """

 if TYPE_CHECKING:
-    from agent_framework import AgentThread, SupportsAgentRun
+    from agent_framework import AgentSession, SupportsAgentRun


-async def handle_approvals_without_thread(query: str, agent: "SupportsAgentRun"):
-    """When we don't have a thread, we need to ensure we return with the input, approval request and approval."""
+async def handle_approvals_without_session(query: str, agent: "SupportsAgentRun"):
+    """When we don't have a session, we need to ensure we return with the input, approval request and approval."""
    from agent_framework import Message

    result = await agent.run(query)
@@ -43,11 +43,11 @@ async def handle_approvals_without_thread(query: str, agent: "SupportsAgentRun")
    return result


-async def handle_approvals_with_thread(query: str, agent: "SupportsAgentRun", thread: "AgentThread"):
-    """Here we let the thread deal with the previous responses, and we just rerun with the approval."""
+async def handle_approvals_with_session(query: str, agent: "SupportsAgentRun", session: "AgentSession"):
+    """Here we let the session deal with the previous responses, and we just rerun with the approval."""
    from agent_framework import Message

-    result = await agent.run(query, thread=thread, store=True)
+    result = await agent.run(query, session=session, store=True)
    while len(result.user_input_requests) > 0:
        new_input: list[Any] = []
        for user_input_needed in result.user_input_requests:
@@ -62,12 +62,12 @@ async def handle_approvals_with_thread(query: str, agent: "SupportsAgentRun", th
                    contents=[user_input_needed.to_function_approval_response(user_approval.lower() == "y")],
                )
            )
-        result = await agent.run(new_input, thread=thread, store=True)
+        result = await agent.run(new_input, session=session, store=True)
    return result


-async def handle_approvals_with_thread_streaming(query: str, agent: "SupportsAgentRun", thread: "AgentThread"):
-    """Here we let the thread deal with the previous responses, and we just rerun with the approval."""
+async def handle_approvals_with_session_streaming(query: str, agent: "SupportsAgentRun", session: "AgentSession"):
+    """Here we let the session deal with the previous responses, and we just rerun with the approval."""
    from agent_framework import Message

    new_input: list[Message] = []
@@ -75,7 +75,7 @@ async def handle_approvals_with_thread_streaming(query: str, agent: "SupportsAge
    while new_input_added:
        new_input_added = False
        new_input.append(Message(role="user", text=query))
-        async for update in agent.run(new_input, thread=thread, options={"store": True}, stream=True):
+        async for update in agent.run(new_input, session=session, options={"store": True}, stream=True):
            if update.user_input_requests:
                for user_input_needed in update.user_input_requests:
                    print(
@@ -94,9 +94,9 @@ async def handle_approvals_with_thread_streaming(query: str, agent: "SupportsAge
                yield update


-async def run_hosted_mcp_without_thread_and_specific_approval() -> None:
-    """Example showing Mcp Tools with approvals without using a thread."""
-    print("=== Mcp with approvals and without thread ===")
+async def run_hosted_mcp_without_session_and_specific_approval() -> None:
+    """Example showing Mcp Tools with approvals without using a session."""
+    print("=== Mcp with approvals and without session ===")
    credential = AzureCliCredential()
    client = AzureOpenAIResponsesClient(credential=credential)

@@ -120,13 +120,13 @@ async def run_hosted_mcp_without_thread_and_specific_approval() -> None:
        # First query
        query1 = "How to create an Azure storage account using az cli?"
        print(f"User: {query1}")
-        result1 = await handle_approvals_without_thread(query1, agent)
+        result1 = await handle_approvals_without_session(query1, agent)
        print(f"{agent.name}: {result1}\n")
        print("\n=======================================\n")
        # Second query
        query2 = "What is Microsoft Agent Framework?"
        print(f"User: {query2}")
-        result2 = await handle_approvals_without_thread(query2, agent)
+        result2 = await handle_approvals_without_session(query2, agent)
        print(f"{agent.name}: {result2}\n")


@@ -157,19 +157,19 @@ async def run_hosted_mcp_without_approval() -> None:
        # First query
        query1 = "How to create an Azure storage account using az cli?"
        print(f"User: {query1}")
-        result1 = await handle_approvals_without_thread(query1, agent)
+        result1 = await handle_approvals_without_session(query1, agent)
        print(f"{agent.name}: {result1}\n")
        print("\n=======================================\n")
        # Second query
        query2 = "What is Microsoft Agent Framework?"
        print(f"User: {query2}")
-        result2 = await handle_approvals_without_thread(query2, agent)
+        result2 = await handle_approvals_without_session(query2, agent)
        print(f"{agent.name}: {result2}\n")


-async def run_hosted_mcp_with_thread() -> None:
-    """Example showing Mcp Tools with approvals using a thread."""
-    print("=== Mcp with approvals and with thread ===")
+async def run_hosted_mcp_with_session() -> None:
+    """Example showing Mcp Tools with approvals using a session."""
+    print("=== Mcp with approvals and with session ===")
    credential = AzureCliCredential()
    client = AzureOpenAIResponsesClient(credential=credential)

@@ -190,22 +190,22 @@ async def run_hosted_mcp_with_thread() -> None:
        tools=[mcp_tool],
    ) as agent:
        # First query
-        thread = agent.get_new_thread()
+        session = agent.create_session()
        query1 = "How to create an Azure storage account using az cli?"
        print(f"User: {query1}")
-        result1 = await handle_approvals_with_thread(query1, agent, thread)
+        result1 = await handle_approvals_with_session(query1, agent, session)
        print(f"{agent.name}: {result1}\n")
        print("\n=======================================\n")
        # Second query
        query2 = "What is Microsoft Agent Framework?"
        print(f"User: {query2}")
-        result2 = await handle_approvals_with_thread(query2, agent, thread)
+        result2 = await handle_approvals_with_session(query2, agent, session)
        print(f"{agent.name}: {result2}\n")


-async def run_hosted_mcp_with_thread_streaming() -> None:
-    """Example showing Mcp Tools with approvals using a thread."""
-    print("=== Mcp with approvals and with thread ===")
+async def run_hosted_mcp_with_session_streaming() -> None:
+    """Example showing Mcp Tools with approvals using a session."""
+    print("=== Mcp with approvals and with session ===")
    credential = AzureCliCredential()
    client = AzureOpenAIResponsesClient(credential=credential)

@@ -226,11 +226,11 @@ async def run_hosted_mcp_with_thread_streaming() -> None:
        tools=[mcp_tool],
    ) as agent:
        # First query
-        thread = agent.get_new_thread()
+        session = agent.create_session()
        query1 = "How to create an Azure storage account using az cli?"
        print(f"User: {query1}")
        print(f"{agent.name}: ", end="")
-        async for update in handle_approvals_with_thread_streaming(query1, agent, thread):
+        async for update in handle_approvals_with_session_streaming(query1, agent, session):
            print(update, end="")
        print("\n")
        print("\n=======================================\n")
@@ -238,7 +238,7 @@ async def run_hosted_mcp_with_thread_streaming() -> None:
        query2 = "What is Microsoft Agent Framework?"
        print(f"User: {query2}")
        print(f"{agent.name}: ", end="")
-        async for update in handle_approvals_with_thread_streaming(query2, agent, thread):
+        async for update in handle_approvals_with_session_streaming(query2, agent, session):
            print(update, end="")
        print("\n")

@@ -247,9 +247,9 @@ async def main() -> None:
    print("=== OpenAI Responses Client Agent with Hosted Mcp Tools Examples ===\n")

    await run_hosted_mcp_without_approval()
-    await run_hosted_mcp_without_thread_and_specific_approval()
-    await run_hosted_mcp_with_thread()
-    await run_hosted_mcp_with_thread_streaming()
+    await run_hosted_mcp_without_session_and_specific_approval()
+    await run_hosted_mcp_with_session()
+    await run_hosted_mcp_with_session_streaming()


 if __name__ == "__main__":
@@ -4,22 +4,22 @@ import asyncio
 from random import randint
 from typing import Annotated

-from agent_framework import Agent, AgentThread, tool
+from agent_framework import Agent, AgentSession, tool
 from agent_framework.azure import AzureOpenAIResponsesClient
 from azure.identity import AzureCliCredential
 from pydantic import Field

 """
-Azure OpenAI Responses Client with Thread Management Example
+Azure OpenAI Responses Client with Session Management Example

-This sample demonstrates thread management with Azure OpenAI Responses Client, comparing
-automatic thread creation with explicit thread management for persistent context.
+This sample demonstrates session management with Azure OpenAI Responses Client, comparing
+automatic session creation with explicit session management for persistent context.
 """


 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -29,9 +29,9 @@ def get_weather(
    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."


-async def example_with_automatic_thread_creation() -> None:
-    """Example showing automatic thread creation."""
-    print("=== Automatic Thread Creation Example ===")
+async def example_with_automatic_session_creation() -> None:
+    """Example showing automatic session creation."""
+    print("=== Automatic Session Creation Example ===")

    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
    # authentication option.
@@ -41,26 +41,26 @@ async def example_with_automatic_thread_creation() -> None:
        tools=get_weather,
    )

-    # First conversation - no thread provided, will be created automatically
+    # First conversation - no session provided, will be created automatically
    query1 = "What's the weather like in Seattle?"
    print(f"User: {query1}")
    result1 = await agent.run(query1)
    print(f"Agent: {result1.text}")

-    # Second conversation - still no thread provided, will create another new thread
+    # Second conversation - still no session provided, will create another new session
    query2 = "What was the last city I asked about?"
    print(f"\nUser: {query2}")
    result2 = await agent.run(query2)
    print(f"Agent: {result2.text}")
-    print("Note: Each call creates a separate thread, so the agent doesn't remember previous context.\n")
+    print("Note: Each call creates a separate session, so the agent doesn't remember previous context.\n")


-async def example_with_thread_persistence_in_memory() -> None:
+async def example_with_session_persistence_in_memory() -> None:
    """
-    Example showing thread persistence across multiple conversations.
+    Example showing session persistence across multiple conversations.
    In this example, messages are stored in-memory.
    """
-    print("=== Thread Persistence Example (In-Memory) ===")
+    print("=== Session Persistence Example (In-Memory) ===")

    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
    # authentication option.
@@ -70,38 +70,38 @@ async def example_with_thread_persistence_in_memory() -> None:
        tools=get_weather,
    )

-    # Create a new thread that will be reused
-    thread = agent.get_new_thread()
+    # Create a new session that will be reused
+    session = agent.create_session()

    # First conversation
    query1 = "What's the weather like in Tokyo?"
    print(f"User: {query1}")
-    result1 = await agent.run(query1, thread=thread)
+    result1 = await agent.run(query1, session=session)
    print(f"Agent: {result1.text}")

-    # Second conversation using the same thread - maintains context
+    # Second conversation using the same session - maintains context
    query2 = "How about London?"
    print(f"\nUser: {query2}")
-    result2 = await agent.run(query2, thread=thread)
+    result2 = await agent.run(query2, session=session)
    print(f"Agent: {result2.text}")

    # Third conversation - agent should remember both previous cities
    query3 = "Which of the cities I asked about has better weather?"
    print(f"\nUser: {query3}")
-    result3 = await agent.run(query3, thread=thread)
+    result3 = await agent.run(query3, session=session)
    print(f"Agent: {result3.text}")
-    print("Note: The agent remembers context from previous messages in the same thread.\n")
+    print("Note: The agent remembers context from previous messages in the same session.\n")


-async def example_with_existing_thread_id() -> None:
+async def example_with_existing_session_id() -> None:
    """
-    Example showing how to work with an existing thread ID from the service.
+    Example showing how to work with an existing session ID from the service.
    In this example, messages are stored on the server using Azure OpenAI conversation state.
    """
-    print("=== Existing Thread ID Example ===")
+    print("=== Existing Session ID Example ===")

-    # First, create a conversation and capture the thread ID
-    existing_thread_id = None
+    # First, create a conversation and capture the session ID
+    existing_session_id = None

    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
    # authentication option.
@@ -111,21 +111,21 @@ async def example_with_existing_thread_id() -> None:
        tools=get_weather,
    )

-    # Start a conversation and get the thread ID
-    thread = agent.get_new_thread()
+    # Start a conversation and get the session ID
+    session = agent.create_session()

    query1 = "What's the weather in Paris?"
    print(f"User: {query1}")
    # Enable Azure OpenAI conversation state by setting `store` parameter to True
-    result1 = await agent.run(query1, thread=thread, store=True)
+    result1 = await agent.run(query1, session=session, store=True)
    print(f"Agent: {result1.text}")

-    # The thread ID is set after the first response
-    existing_thread_id = thread.service_thread_id
-    print(f"Thread ID: {existing_thread_id}")
+    # The session ID is set after the first response
+    existing_session_id = session.service_session_id
+    print(f"Session ID: {existing_session_id}")

-    if existing_thread_id:
-        print("\n--- Continuing with the same thread ID in a new agent instance ---")
+    if existing_session_id:
+        print("\n--- Continuing with the same session ID in a new agent instance ---")

        agent = Agent(
            client=AzureOpenAIResponsesClient(credential=AzureCliCredential()),
@@ -133,22 +133,22 @@ async def example_with_existing_thread_id() -> None:
            tools=get_weather,
        )

-        # Create a thread with the existing ID
-        thread = AgentThread(service_thread_id=existing_thread_id)
+        # Create a session with the existing ID
+        session = AgentSession(service_session_id=existing_session_id)

        query2 = "What was the last city I asked about?"
        print(f"User: {query2}")
-        result2 = await agent.run(query2, thread=thread, store=True)
+        result2 = await agent.run(query2, session=session, store=True)
        print(f"Agent: {result2.text}")
-        print("Note: The agent continues the conversation from the previous thread by using thread ID.\n")
+        print("Note: The agent continues the conversation from the previous session by using session ID.\n")


 async def main() -> None:
-    print("=== Azure OpenAI Response Client Agent Thread Management Examples ===\n")
+    print("=== Azure OpenAI Response Client Agent Session Management Examples ===\n")

-    await example_with_automatic_thread_creation()
-    await example_with_thread_persistence_in_memory()
-    await example_with_existing_thread_id()
+    await example_with_automatic_session_creation()
+    await example_with_session_persistence_in_memory()
+    await example_with_existing_session_id()


 if __name__ == "__main__":
@@ -6,7 +6,7 @@ This folder contains examples demonstrating how to implement custom agents and c

 | File | Description |
 |------|-------------|
-| [`custom_agent.py`](custom_agent.py) | Shows how to create custom agents by extending the `BaseAgent` class. Demonstrates the `EchoAgent` implementation with both streaming and non-streaming responses, proper thread management, and message history handling. |
+| [`custom_agent.py`](custom_agent.py) | Shows how to create custom agents by extending the `BaseAgent` class. Demonstrates the `EchoAgent` implementation with both streaming and non-streaming responses, proper session management, and message history handling. |
 | [`custom_chat_client.py`](../../chat_client/custom_chat_client.py) | Demonstrates how to create custom chat clients by extending the `BaseChatClient` class. Shows a `EchoingChatClient` implementation and how to integrate it with `Agent` using the `as_agent()` method. |

 ## Key Takeaways
@@ -15,7 +15,7 @@ This folder contains examples demonstrating how to implement custom agents and c
 - Custom agents give you complete control over the agent's behavior
 - You must implement both `run()` for both the `stream=True` and `stream=False` cases
 - Use `self._normalize_messages()` to handle different input message formats
- Use `self._notify_thread_of_new_messages()` to properly manage conversation history
+- Store messages in `session.state` to properly manage conversation history

 ### Custom Chat Clients
 - Custom chat clients allow you to integrate any backend service or create new LLM providers
@@ -7,7 +7,7 @@ from typing import Any
 from agent_framework import (
    AgentResponse,
    AgentResponseUpdate,
-    AgentThread,
+    AgentSession,
    BaseAgent,
    Content,
    Message,
@@ -60,7 +60,7 @@ class EchoAgent(BaseAgent):
        messages: str | Message | list[str] | list[Message] | None = None,
        *,
        stream: bool = False,
-        thread: AgentThread | None = None,
+        session: AgentSession | None = None,
        **kwargs: Any,
    ) -> "AsyncIterable[AgentResponseUpdate] | asyncio.Future[AgentResponse]":
        """Execute the agent and return a response.
@@ -68,7 +68,7 @@ class EchoAgent(BaseAgent):
        Args:
            messages: The message(s) to process.
            stream: If True, return an async iterable of updates. If False, return an awaitable response.
-            thread: The conversation thread (optional).
+            session: The conversation session (optional).
            **kwargs: Additional keyword arguments.

        Returns:
@@ -76,14 +76,14 @@ class EchoAgent(BaseAgent):
            When stream=True: An async iterable of AgentResponseUpdate objects.
        """
        if stream:
-            return self._run_stream(messages=messages, thread=thread, **kwargs)
-        return self._run(messages=messages, thread=thread, **kwargs)
+            return self._run_stream(messages=messages, session=session, **kwargs)
+        return self._run(messages=messages, session=session, **kwargs)

    async def _run(
        self,
        messages: str | Message | list[str] | list[Message] | None = None,
        *,
-        thread: AgentThread | None = None,
+        session: AgentSession | None = None,
        **kwargs: Any,
    ) -> AgentResponse:
        """Non-streaming implementation."""
@@ -105,9 +105,11 @@ class EchoAgent(BaseAgent):

            response_message = Message(role=Role.ASSISTANT, contents=[Content.from_text(text=echo_text)])

-        # Notify the thread of new messages if provided
-        if thread is not None:
-            await self._notify_thread_of_new_messages(thread, normalized_messages, response_message)
+        # Store messages in session state if provided
+        if session is not None:
+            stored = session.state.setdefault("memory", {}).setdefault("messages", [])
+            stored.extend(normalized_messages)
+            stored.append(response_message)

        return AgentResponse(messages=[response_message])

@@ -115,7 +117,7 @@ class EchoAgent(BaseAgent):
        self,
        messages: str | Message | list[str] | list[Message] | None = None,
        *,
-        thread: AgentThread | None = None,
+        session: AgentSession | None = None,
        **kwargs: Any,
    ) -> AsyncIterable[AgentResponseUpdate]:
        """Streaming implementation."""
@@ -146,10 +148,12 @@ class EchoAgent(BaseAgent):
            # Small delay to simulate streaming
            await asyncio.sleep(0.1)

-        # Notify the thread of the complete response if provided
-        if thread is not None:
+        # Store messages in session state if provided
+        if session is not None:
            complete_response = Message(role=Role.ASSISTANT, contents=[Content.from_text(text=response_text)])
-            await self._notify_thread_of_new_messages(thread, normalized_messages, complete_response)
+            stored = session.state.setdefault("memory", {}).setdefault("messages", [])
+            stored.extend(normalized_messages)
+            stored.append(complete_response)


 async def main() -> None:
@@ -180,26 +184,27 @@ async def main() -> None:
            print(chunk.text, end="", flush=True)
    print()

-    # Example with threads
-    print("\n--- Using Custom Agent with Thread ---")
-    thread = echo_agent.get_new_thread()
+    # Example with sessions
+    print("\n--- Using Custom Agent with Session ---")
+    session = echo_agent.create_session()

    # First message
-    result1 = await echo_agent.run("First message", thread=thread)
+    result1 = await echo_agent.run("First message", session=session)
    print("User: First message")
    print(f"Agent: {result1.messages[0].text}")

    # Second message in same thread
-    result2 = await echo_agent.run("Second message", thread=thread)
+    result2 = await echo_agent.run("Second message", session=session)
    print("User: Second message")
    print(f"Agent: {result2.messages[0].text}")

    # Check conversation history
-    if thread.message_store:
-        messages = await thread.message_store.list_messages()
-        print(f"\nThread contains {len(messages)} messages in history")
+    memory_state = session.state.get("memory", {})
+    messages = memory_state.get("messages", [])
+    if messages:
+        print(f"\nSession contains {len(messages)} messages in history")
    else:
-        print("\nThread has no message store configured")
+        print("\nSession has no messages stored")


 if __name__ == "__main__":
@@ -29,7 +29,7 @@ The following environment variables can be configured:
 | File | Description |
 |------|-------------|
 | [`github_copilot_basic.py`](github_copilot_basic.py) | The simplest way to create an agent using `GitHubCopilotAgent`. Demonstrates both streaming and non-streaming responses with function tools. |
-| [`github_copilot_with_session.py`](github_copilot_with_session.py) | Shows session management with automatic creation, persistence via thread objects, and resuming sessions by ID. |
+| [`github_copilot_with_session.py`](github_copilot_with_session.py) | Shows session management with automatic creation, persistence via session objects, and resuming sessions by ID. |
 | [`github_copilot_with_shell.py`](github_copilot_with_shell.py) | Shows how to enable shell command execution permissions. Demonstrates running system commands like listing files and getting system information. |
 | [`github_copilot_with_file_operations.py`](github_copilot_with_file_operations.py) | Shows how to enable file read and write permissions. Demonstrates reading file contents and creating new files. |
 | [`github_copilot_with_url.py`](github_copilot_with_url.py) | Shows how to enable URL fetching permissions. Demonstrates fetching and processing web content. |
@@ -22,7 +22,7 @@ from agent_framework.github import GitHubCopilotAgent
 from pydantic import Field


-# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -17,7 +17,7 @@ from agent_framework.github import GitHubCopilotAgent
 from pydantic import Field


-# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -61,31 +61,31 @@ async def example_with_session_persistence() -> None:
    )

    async with agent:
-        # Create a thread to maintain conversation context
-        thread = agent.get_new_thread()
+        # Create a session to maintain conversation context
+        session = agent.create_session()

        # First query
        query1 = "What's the weather like in Tokyo?"
        print(f"User: {query1}")
-        result1 = await agent.run(query1, thread=thread)
+        result1 = await agent.run(query1, session=session)
        print(f"Agent: {result1}")

        # Second query - using same thread maintains context
        query2 = "How about London?"
        print(f"\nUser: {query2}")
-        result2 = await agent.run(query2, thread=thread)
+        result2 = await agent.run(query2, session=session)
        print(f"Agent: {result2}")

        # Third query - agent should remember both previous cities
        query3 = "Which of the cities I asked about has better weather?"
        print(f"\nUser: {query3}")
-        result3 = await agent.run(query3, thread=thread)
+        result3 = await agent.run(query3, session=session)
        print(f"Agent: {result3}")
        print("Note: The agent remembers context from previous messages in the same session.\n")


 async def example_with_existing_session_id() -> None:
-    """Resume session in new agent instance using service_thread_id."""
+    """Resume session in new agent instance using service_session_id."""
    print("=== Existing Session ID Example ===")

    existing_session_id = None
@@ -97,15 +97,15 @@ async def example_with_existing_session_id() -> None:
    )

    async with agent1:
-        thread = agent1.get_new_thread()
+        session = agent1.create_session()

        query1 = "What's the weather in Paris?"
        print(f"User: {query1}")
-        result1 = await agent1.run(query1, thread=thread)
+        result1 = await agent1.run(query1, session=session)
        print(f"Agent: {result1}")

        # Capture the session ID for later use
-        existing_session_id = thread.service_thread_id
+        existing_session_id = session.service_session_id
        print(f"Session ID: {existing_session_id}")

    if existing_session_id:
@@ -118,12 +118,12 @@ async def example_with_existing_session_id() -> None:
        )

        async with agent2:
-            # Create thread with existing session ID
-            thread = agent2.get_new_thread(service_thread_id=existing_session_id)
+            # Create session with existing session ID
+            session = agent2.create_session(service_session_id=existing_session_id)

            query2 = "What was the last city I asked about?"
            print(f"User: {query2}")
-            result2 = await agent2.run(query2, thread=thread)
+            result2 = await agent2.run(query2, session=session)
            print(f"Agent: {result2}")
            print("Note: The agent continues the conversation using the session ID.\n")

@@ -19,7 +19,7 @@ https://ollama.com/
 """


-# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_time(location: str) -> str:
    """Get the current time."""
@@ -19,7 +19,7 @@ https://ollama.com/
 """


-# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_time():
    """Get the current time."""
@@ -21,7 +21,7 @@ Environment Variables:
 """


-# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, "The location to get the weather for."],
@@ -14,12 +14,12 @@ This folder contains examples demonstrating different ways to create and use age
 | [`openai_assistants_with_file_search.py`](openai_assistants_with_file_search.py) | Using `OpenAIAssistantsClient.get_file_search_tool()` with `OpenAIAssistantProvider` for file search capabilities. |
 | [`openai_assistants_with_function_tools.py`](openai_assistants_with_function_tools.py) | Function tools with `OpenAIAssistantProvider` at both agent-level and query-level. |
 | [`openai_assistants_with_response_format.py`](openai_assistants_with_response_format.py) | Structured outputs with `OpenAIAssistantProvider` using Pydantic models. |
-| [`openai_assistants_with_thread.py`](openai_assistants_with_thread.py) | Thread management with `OpenAIAssistantProvider` for conversation context persistence. |
+| [`openai_assistants_with_session.py`](openai_assistants_with_session.py) | Session management with `OpenAIAssistantProvider` for conversation context persistence. |
 | [`openai_chat_client_basic.py`](openai_chat_client_basic.py) | The simplest way to create an agent using `Agent` with `OpenAIChatClient`. Shows both streaming and non-streaming responses for chat-based interactions with OpenAI models. |
 | [`openai_chat_client_with_explicit_settings.py`](openai_chat_client_with_explicit_settings.py) | Shows how to initialize an agent with a specific chat client, configuring settings explicitly including API key and model ID. |
 | [`openai_chat_client_with_function_tools.py`](openai_chat_client_with_function_tools.py) | Demonstrates how to use function tools with agents. Shows both agent-level tools (defined when creating the agent) and query-level tools (provided with specific queries). |
 | [`openai_chat_client_with_local_mcp.py`](openai_chat_client_with_local_mcp.py) | Shows how to integrate OpenAI agents with local Model Context Protocol (MCP) servers for enhanced functionality and tool integration. |
-| [`openai_chat_client_with_thread.py`](openai_chat_client_with_thread.py) | Demonstrates thread management with OpenAI agents, including automatic thread creation for stateless conversations and explicit thread management for maintaining conversation context across multiple interactions. |
+| [`openai_chat_client_with_session.py`](openai_chat_client_with_session.py) | Demonstrates session management with OpenAI agents, including automatic session creation for stateless conversations and explicit session management for maintaining conversation context across multiple interactions. |
 | [`openai_chat_client_with_web_search.py`](openai_chat_client_with_web_search.py) | Shows how to use `OpenAIChatClient.get_web_search_tool()` for web search capabilities with OpenAI agents. |
 | [`openai_chat_client_with_runtime_json_schema.py`](openai_chat_client_with_runtime_json_schema.py) | Shows how to supply a runtime JSON Schema via `additional_chat_options` for structured output without defining a Pydantic model. |
 | [`openai_responses_client_basic.py`](openai_responses_client_basic.py) | The simplest way to create an agent using `Agent` with `OpenAIResponsesClient`. Shows both streaming and non-streaming responses for structured response generation with OpenAI models. |
@@ -37,7 +37,7 @@ This folder contains examples demonstrating different ways to create and use age
 | [`openai_responses_client_with_local_mcp.py`](openai_responses_client_with_local_mcp.py) | Shows how to integrate OpenAI agents with local Model Context Protocol (MCP) servers for enhanced functionality and tool integration. |
 | [`openai_responses_client_with_runtime_json_schema.py`](openai_responses_client_with_runtime_json_schema.py) | Shows how to supply a runtime JSON Schema via `additional_chat_options` for structured output without defining a Pydantic model. |
 | [`openai_responses_client_with_structured_output.py`](openai_responses_client_with_structured_output.py) | Demonstrates how to use structured outputs with OpenAI agents to get structured data responses in predefined formats. |
-| [`openai_responses_client_with_thread.py`](openai_responses_client_with_thread.py) | Demonstrates thread management with OpenAI agents, including automatic thread creation for stateless conversations and explicit thread management for maintaining conversation context across multiple interactions. |
+| [`openai_responses_client_with_session.py`](openai_responses_client_with_session.py) | Demonstrates session management with OpenAI agents, including automatic session creation for stateless conversations and explicit session management for maintaining conversation context across multiple interactions. |
 | [`openai_responses_client_with_web_search.py`](openai_responses_client_with_web_search.py) | Shows how to use `OpenAIResponsesClient.get_web_search_tool()` for web search capabilities. |

 ## Environment Variables
@@ -20,7 +20,7 @@ assistant lifecycle management, showing both streaming and non-streaming respons

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -22,7 +22,7 @@ This sample demonstrates the methods available on the OpenAIAssistantProvider cl

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -18,7 +18,7 @@ using the provider's get_agent() and as_agent() methods.
 """


-# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -20,7 +20,7 @@ settings rather than relying on environment variable defaults.

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -19,7 +19,7 @@ showing both agent-level and query-level tool configuration patterns.
 """


-# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -5,22 +5,22 @@ import os
 from random import randint
 from typing import Annotated

-from agent_framework import AgentThread, tool
+from agent_framework import AgentSession, tool
 from agent_framework.openai import OpenAIAssistantProvider
 from openai import AsyncOpenAI
 from pydantic import Field

 """
-OpenAI Assistants with Thread Management Example
+OpenAI Assistants with Session Management Example

-This sample demonstrates thread management with OpenAI Assistants, showing
-persistent conversation threads and context preservation across interactions.
+This sample demonstrates session management with OpenAI Assistants, showing
+persistent conversation sessions and context preservation across interactions.
 """


 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -30,9 +30,9 @@ def get_weather(
    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}C."


-async def example_with_automatic_thread_creation() -> None:
-    """Example showing automatic thread creation (service-managed thread)."""
-    print("=== Automatic Thread Creation Example ===")
+async def example_with_automatic_session_creation() -> None:
+    """Example showing automatic session creation (service-managed session)."""
+    print("=== Automatic Session Creation Example ===")

    client = AsyncOpenAI()
    provider = OpenAIAssistantProvider(client)
@@ -45,26 +45,26 @@ async def example_with_automatic_thread_creation() -> None:
    )

    try:
-        # First conversation - no thread provided, will be created automatically
+        # First conversation - no session provided, will be created automatically
        query1 = "What's the weather like in Seattle?"
        print(f"User: {query1}")
        result1 = await agent.run(query1)
        print(f"Agent: {result1.text}")

-        # Second conversation - still no thread provided, will create another new thread
+        # Second conversation - still no session provided, will create another new session
        query2 = "What was the last city I asked about?"
        print(f"\nUser: {query2}")
        result2 = await agent.run(query2)
        print(f"Agent: {result2.text}")
-        print("Note: Each call creates a separate thread, so the agent doesn't remember previous context.\n")
+        print("Note: Each call creates a separate session, so the agent doesn't remember previous context.\n")
    finally:
        await client.beta.assistants.delete(agent.id)


-async def example_with_thread_persistence() -> None:
-    """Example showing thread persistence across multiple conversations."""
-    print("=== Thread Persistence Example ===")
-    print("Using the same thread across multiple conversations to maintain context.\n")
+async def example_with_session_persistence() -> None:
+    """Example showing session persistence across multiple conversations."""
+    print("=== Session Persistence Example ===")
+    print("Using the same session across multiple conversations to maintain context.\n")

    client = AsyncOpenAI()
    provider = OpenAIAssistantProvider(client)
@@ -77,41 +77,41 @@ async def example_with_thread_persistence() -> None:
    )

    try:
-        # Create a new thread that will be reused
-        thread = agent.get_new_thread()
+        # Create a new session that will be reused
+        session = agent.create_session()

        # First conversation
        query1 = "What's the weather like in Tokyo?"
        print(f"User: {query1}")
-        result1 = await agent.run(query1, thread=thread)
+        result1 = await agent.run(query1, session=session)
        print(f"Agent: {result1.text}")

-        # Second conversation using the same thread - maintains context
+        # Second conversation using the same session - maintains context
        query2 = "How about London?"
        print(f"\nUser: {query2}")
-        result2 = await agent.run(query2, thread=thread)
+        result2 = await agent.run(query2, session=session)
        print(f"Agent: {result2.text}")

        # Third conversation - agent should remember both previous cities
        query3 = "Which of the cities I asked about has better weather?"
        print(f"\nUser: {query3}")
-        result3 = await agent.run(query3, thread=thread)
+        result3 = await agent.run(query3, session=session)
        print(f"Agent: {result3.text}")
-        print("Note: The agent remembers context from previous messages in the same thread.\n")
+        print("Note: The agent remembers context from previous messages in the same session.\n")
    finally:
        await client.beta.assistants.delete(agent.id)


-async def example_with_existing_thread_id() -> None:
-    """Example showing how to work with an existing thread ID from the service."""
-    print("=== Existing Thread ID Example ===")
-    print("Using a specific thread ID to continue an existing conversation.\n")
+async def example_with_existing_session_id() -> None:
+    """Example showing how to work with an existing session ID from the service."""
+    print("=== Existing Session ID Example ===")
+    print("Using a specific session ID to continue an existing conversation.\n")

    client = AsyncOpenAI()
    provider = OpenAIAssistantProvider(client)

-    # First, create a conversation and capture the thread ID
-    existing_thread_id = None
+    # First, create a conversation and capture the session ID
+    existing_session_id = None
    assistant_id = None

    agent = await provider.create_agent(
@@ -123,19 +123,19 @@ async def example_with_existing_thread_id() -> None:
    assistant_id = agent.id

    try:
-        # Start a conversation and get the thread ID
-        thread = agent.get_new_thread()
+        # Start a conversation and get the session ID
+        session = agent.create_session()
        query1 = "What's the weather in Paris?"
        print(f"User: {query1}")
-        result1 = await agent.run(query1, thread=thread)
+        result1 = await agent.run(query1, session=session)
        print(f"Agent: {result1.text}")

-        # The thread ID is set after the first response
-        existing_thread_id = thread.service_thread_id
-        print(f"Thread ID: {existing_thread_id}")
+        # The session ID is set after the first response
+        existing_session_id = session.service_session_id
+        print(f"Session ID: {existing_session_id}")

-        if existing_thread_id:
-            print("\n--- Continuing with the same thread ID using get_agent ---")
+        if existing_session_id:
+            print("\n--- Continuing with the same session ID using get_agent ---")

            # Get the existing assistant by ID
            agent2 = await provider.get_agent(
@@ -143,25 +143,25 @@ async def example_with_existing_thread_id() -> None:
                tools=[get_weather],  # Must provide function implementations
            )

-            # Create a thread with the existing ID
-            thread = AgentThread(service_thread_id=existing_thread_id)
+            # Create a session with the existing ID
+            session = AgentSession(service_session_id=existing_session_id)

            query2 = "What was the last city I asked about?"
            print(f"User: {query2}")
-            result2 = await agent2.run(query2, thread=thread)
+            result2 = await agent2.run(query2, session=session)
            print(f"Agent: {result2.text}")
-            print("Note: The agent continues the conversation from the previous thread.\n")
+            print("Note: The agent continues the conversation from the previous session.\n")
    finally:
        if assistant_id:
            await client.beta.assistants.delete(assistant_id)


 async def main() -> None:
-    print("=== OpenAI Assistants Provider Thread Management Examples ===\n")
+    print("=== OpenAI Assistants Provider Session Management Examples ===\n")

-    await example_with_automatic_thread_creation()
-    await example_with_thread_persistence()
-    await example_with_existing_thread_id()
+    await example_with_automatic_session_creation()
+    await example_with_session_persistence()
+    await example_with_existing_session_id()


 if __name__ == "__main__":
@@ -17,7 +17,7 @@ interactions, showing both streaming and non-streaming responses.

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, "The location to get the weather for."],
@@ -19,7 +19,7 @@ settings rather than relying on environment variable defaults.

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -19,7 +19,7 @@ showing both agent-level and query-level tool configuration patterns.

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -0,0 +1,149 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from random import randint
+from typing import Annotated
+
+from agent_framework import Agent, AgentSession, tool
+from agent_framework.openai import OpenAIChatClient
+from pydantic import Field
+
+"""
+OpenAI Chat Client with Session Management Example
+
+This sample demonstrates session management with OpenAI Chat Client, showing
+conversation sessions and message history preservation across interactions.
+"""
+
+
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
+# see samples/02-agents/tools/function_tool_with_approval.py
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
+@tool(approval_mode="never_require")
+def get_weather(
+    location: Annotated[str, Field(description="The location to get the weather for.")],
+) -> str:
+    """Get the weather for a given location."""
+    conditions = ["sunny", "cloudy", "rainy", "stormy"]
+    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
+
+
+async def example_with_automatic_session_creation() -> None:
+    """Example showing automatic session creation (service-managed session)."""
+    print("=== Automatic Session Creation Example ===")
+
+    agent = Agent(
+        client=OpenAIChatClient(),
+        instructions="You are a helpful weather agent.",
+        tools=get_weather,
+    )
+
+    # First conversation - no session provided, will be created automatically
+    query1 = "What's the weather like in Seattle?"
+    print(f"User: {query1}")
+    result1 = await agent.run(query1)
+    print(f"Agent: {result1.text}")
+
+    # Second conversation - still no session provided, will create another new session
+    query2 = "What was the last city I asked about?"
+    print(f"\nUser: {query2}")
+    result2 = await agent.run(query2)
+    print(f"Agent: {result2.text}")
+    print("Note: Each call creates a separate session, so the agent doesn't remember previous context.\n")
+
+
+async def example_with_session_persistence() -> None:
+    """Example showing session persistence across multiple conversations."""
+    print("=== Session Persistence Example ===")
+    print("Using the same session across multiple conversations to maintain context.\n")
+
+    agent = Agent(
+        client=OpenAIChatClient(),
+        instructions="You are a helpful weather agent.",
+        tools=get_weather,
+    )
+
+    # Create a new session that will be reused
+    session = agent.create_session()
+
+    # First conversation
+    query1 = "What's the weather like in Tokyo?"
+    print(f"User: {query1}")
+    result1 = await agent.run(query1, session=session)
+    print(f"Agent: {result1.text}")
+
+    # Second conversation using the same session - maintains context
+    query2 = "How about London?"
+    print(f"\nUser: {query2}")
+    result2 = await agent.run(query2, session=session)
+    print(f"Agent: {result2.text}")
+
+    # Third conversation - agent should remember both previous cities
+    query3 = "Which of the cities I asked about has better weather?"
+    print(f"\nUser: {query3}")
+    result3 = await agent.run(query3, session=session)
+    print(f"Agent: {result3.text}")
+    print("Note: The agent remembers context from previous messages in the same session.\n")
+
+
+async def example_with_existing_session_messages() -> None:
+    """Example showing how to work with existing session messages for OpenAI."""
+    print("=== Existing Session Messages Example ===")
+
+    agent = Agent(
+        client=OpenAIChatClient(),
+        instructions="You are a helpful weather agent.",
+        tools=get_weather,
+    )
+
+    # Start a conversation and build up message history
+    session = agent.create_session()
+
+    query1 = "What's the weather in Paris?"
+    print(f"User: {query1}")
+    result1 = await agent.run(query1, session=session)
+    print(f"Agent: {result1.text}")
+
+    # The session now contains the conversation history in state
+    memory_state = session.state.get("memory", {})
+    messages = memory_state.get("messages", [])
+    if messages:
+        print(f"Session contains {len(messages)} messages")
+
+    print("\n--- Continuing with the same session in a new agent instance ---")
+
+    # Create a new agent instance but use the existing session with its message history
+    new_agent = Agent(
+        client=OpenAIChatClient(),
+        instructions="You are a helpful weather agent.",
+        tools=get_weather,
+    )
+
+    # Use the same session object which contains the conversation history
+    query2 = "What was the last city I asked about?"
+    print(f"User: {query2}")
+    result2 = await new_agent.run(query2, session=session)
+    print(f"Agent: {result2.text}")
+    print("Note: The agent continues the conversation using the local message history.\n")
+
+    print("\n--- Alternative: Creating a new session from existing messages ---")
+
+    new_session = AgentSession()
+
+    query3 = "How does the Paris weather compare to London?"
+    print(f"User: {query3}")
+    result3 = await new_agent.run(query3, session=new_session)
+    print(f"Agent: {result3.text}")
+    print("Note: This creates a new session with the same conversation history.\n")
+
+
+async def main() -> None:
+    print("=== OpenAI Chat Client Agent Session Management Examples ===\n")
+
+    await example_with_automatic_session_creation()
+    await example_with_session_persistence()
+    await example_with_existing_session_messages()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -1,151 +0,0 @@
-# Copyright (c) Microsoft. All rights reserved.
-
-import asyncio
-from random import randint
-from typing import Annotated
-
-from agent_framework import Agent, AgentThread, ChatMessageStore, tool
-from agent_framework.openai import OpenAIChatClient
-from pydantic import Field
-
-"""
-OpenAI Chat Client with Thread Management Example
-
-This sample demonstrates thread management with OpenAI Chat Client, showing
-conversation threads and message history preservation across interactions.
-"""
-
-
-# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
-# see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
-@tool(approval_mode="never_require")
-def get_weather(
-    location: Annotated[str, Field(description="The location to get the weather for.")],
-) -> str:
-    """Get the weather for a given location."""
-    conditions = ["sunny", "cloudy", "rainy", "stormy"]
-    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
-
-
-async def example_with_automatic_thread_creation() -> None:
-    """Example showing automatic thread creation (service-managed thread)."""
-    print("=== Automatic Thread Creation Example ===")
-
-    agent = Agent(
-        client=OpenAIChatClient(),
-        instructions="You are a helpful weather agent.",
-        tools=get_weather,
-    )
-
-    # First conversation - no thread provided, will be created automatically
-    query1 = "What's the weather like in Seattle?"
-    print(f"User: {query1}")
-    result1 = await agent.run(query1)
-    print(f"Agent: {result1.text}")
-
-    # Second conversation - still no thread provided, will create another new thread
-    query2 = "What was the last city I asked about?"
-    print(f"\nUser: {query2}")
-    result2 = await agent.run(query2)
-    print(f"Agent: {result2.text}")
-    print("Note: Each call creates a separate thread, so the agent doesn't remember previous context.\n")
-
-
-async def example_with_thread_persistence() -> None:
-    """Example showing thread persistence across multiple conversations."""
-    print("=== Thread Persistence Example ===")
-    print("Using the same thread across multiple conversations to maintain context.\n")
-
-    agent = Agent(
-        client=OpenAIChatClient(),
-        instructions="You are a helpful weather agent.",
-        tools=get_weather,
-    )
-
-    # Create a new thread that will be reused
-    thread = agent.get_new_thread()
-
-    # First conversation
-    query1 = "What's the weather like in Tokyo?"
-    print(f"User: {query1}")
-    result1 = await agent.run(query1, thread=thread)
-    print(f"Agent: {result1.text}")
-
-    # Second conversation using the same thread - maintains context
-    query2 = "How about London?"
-    print(f"\nUser: {query2}")
-    result2 = await agent.run(query2, thread=thread)
-    print(f"Agent: {result2.text}")
-
-    # Third conversation - agent should remember both previous cities
-    query3 = "Which of the cities I asked about has better weather?"
-    print(f"\nUser: {query3}")
-    result3 = await agent.run(query3, thread=thread)
-    print(f"Agent: {result3.text}")
-    print("Note: The agent remembers context from previous messages in the same thread.\n")
-
-
-async def example_with_existing_thread_messages() -> None:
-    """Example showing how to work with existing thread messages for OpenAI."""
-    print("=== Existing Thread Messages Example ===")
-
-    agent = Agent(
-        client=OpenAIChatClient(),
-        instructions="You are a helpful weather agent.",
-        tools=get_weather,
-    )
-
-    # Start a conversation and build up message history
-    thread = agent.get_new_thread()
-
-    query1 = "What's the weather in Paris?"
-    print(f"User: {query1}")
-    result1 = await agent.run(query1, thread=thread)
-    print(f"Agent: {result1.text}")
-
-    # The thread now contains the conversation history in memory
-    if thread.message_store:
-        messages = await thread.message_store.list_messages()
-        print(f"Thread contains {len(messages or [])} messages")
-
-    print("\n--- Continuing with the same thread in a new agent instance ---")
-
-    # Create a new agent instance but use the existing thread with its message history
-    new_agent = Agent(
-        client=OpenAIChatClient(),
-        instructions="You are a helpful weather agent.",
-        tools=get_weather,
-    )
-
-    # Use the same thread object which contains the conversation history
-    query2 = "What was the last city I asked about?"
-    print(f"User: {query2}")
-    result2 = await new_agent.run(query2, thread=thread)
-    print(f"Agent: {result2.text}")
-    print("Note: The agent continues the conversation using the local message history.\n")
-
-    print("\n--- Alternative: Creating a new thread from existing messages ---")
-
-    # You can also create a new thread from existing messages
-    messages = await thread.message_store.list_messages() if thread.message_store else []
-
-    new_thread = AgentThread(message_store=ChatMessageStore(messages))
-
-    query3 = "How does the Paris weather compare to London?"
-    print(f"User: {query3}")
-    result3 = await new_agent.run(query3, thread=new_thread)
-    print(f"Agent: {result3.text}")
-    print("Note: This creates a new thread with the same conversation history.\n")
-
-
-async def main() -> None:
-    print("=== OpenAI Chat Client Agent Thread Management Examples ===\n")
-
-    await example_with_automatic_thread_creation()
-    await example_with_thread_persistence()
-    await example_with_existing_thread_messages()
-
-
-if __name__ == "__main__":
-    asyncio.run(main())
@@ -68,7 +68,7 @@ async def security_and_override_middleware(

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -19,7 +19,7 @@ settings rather than relying on environment variable defaults.

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -19,7 +19,7 @@ showing both agent-level and query-level tool configuration patterns.

 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -14,11 +14,11 @@ OpenAI Responses Client, including user approval workflows for function call sec
 """

 if TYPE_CHECKING:
-    from agent_framework import AgentThread, SupportsAgentRun
+    from agent_framework import AgentSession, SupportsAgentRun


-async def handle_approvals_without_thread(query: str, agent: "SupportsAgentRun"):
-    """When we don't have a thread, we need to ensure we return with the input, approval request and approval."""
+async def handle_approvals_without_session(query: str, agent: "SupportsAgentRun"):
+    """When we don't have a session, we need to ensure we return with the input, approval request and approval."""
    from agent_framework import Message

    result = await agent.run(query)
@@ -42,11 +42,11 @@ async def handle_approvals_without_thread(query: str, agent: "SupportsAgentRun")
    return result


-async def handle_approvals_with_thread(query: str, agent: "SupportsAgentRun", thread: "AgentThread"):
-    """Here we let the thread deal with the previous responses, and we just rerun with the approval."""
+async def handle_approvals_with_session(query: str, agent: "SupportsAgentRun", session: "AgentSession"):
+    """Here we let the session deal with the previous responses, and we just rerun with the approval."""
    from agent_framework import Message

-    result = await agent.run(query, thread=thread, store=True)
+    result = await agent.run(query, session=session, store=True)
    while len(result.user_input_requests) > 0:
        new_input: list[Any] = []
        for user_input_needed in result.user_input_requests:
@@ -61,12 +61,12 @@ async def handle_approvals_with_thread(query: str, agent: "SupportsAgentRun", th
                    contents=[user_input_needed.to_function_approval_response(user_approval.lower() == "y")],
                )
            )
-        result = await agent.run(new_input, thread=thread, store=True)
+        result = await agent.run(new_input, session=session, store=True)
    return result


-async def handle_approvals_with_thread_streaming(query: str, agent: "SupportsAgentRun", thread: "AgentThread"):
-    """Here we let the thread deal with the previous responses, and we just rerun with the approval."""
+async def handle_approvals_with_session_streaming(query: str, agent: "SupportsAgentRun", session: "AgentSession"):
+    """Here we let the session deal with the previous responses, and we just rerun with the approval."""
    from agent_framework import Message

    new_input: list[Message] = []
@@ -74,7 +74,7 @@ async def handle_approvals_with_thread_streaming(query: str, agent: "SupportsAge
    while new_input_added:
        new_input_added = False
        new_input.append(Message(role="user", text=query))
-        async for update in agent.run(new_input, thread=thread, stream=True, options={"store": True}):
+        async for update in agent.run(new_input, session=session, stream=True, options={"store": True}):
            if update.user_input_requests:
                for user_input_needed in update.user_input_requests:
                    print(
@@ -93,9 +93,9 @@ async def handle_approvals_with_thread_streaming(query: str, agent: "SupportsAge
                yield update


-async def run_hosted_mcp_without_thread_and_specific_approval() -> None:
-    """Example showing Mcp Tools with approvals without using a thread."""
-    print("=== Mcp with approvals and without thread ===")
+async def run_hosted_mcp_without_session_and_specific_approval() -> None:
+    """Example showing Mcp Tools with approvals without using a session."""
+    print("=== Mcp with approvals and without session ===")

    client = OpenAIResponsesClient()
    # Create MCP tool with specific approval mode
@@ -116,13 +116,13 @@ async def run_hosted_mcp_without_thread_and_specific_approval() -> None:
        # First query
        query1 = "How to create an Azure storage account using az cli?"
        print(f"User: {query1}")
-        result1 = await handle_approvals_without_thread(query1, agent)
+        result1 = await handle_approvals_without_session(query1, agent)
        print(f"{agent.name}: {result1}\n")
        print("\n=======================================\n")
        # Second query
        query2 = "What is Microsoft Agent Framework?"
        print(f"User: {query2}")
-        result2 = await handle_approvals_without_thread(query2, agent)
+        result2 = await handle_approvals_without_session(query2, agent)
        print(f"{agent.name}: {result2}\n")


@@ -148,19 +148,19 @@ async def run_hosted_mcp_without_approval() -> None:
        # First query
        query1 = "How to create an Azure storage account using az cli?"
        print(f"User: {query1}")
-        result1 = await handle_approvals_without_thread(query1, agent)
+        result1 = await handle_approvals_without_session(query1, agent)
        print(f"{agent.name}: {result1}\n")
        print("\n=======================================\n")
        # Second query
        query2 = "What is Microsoft Agent Framework?"
        print(f"User: {query2}")
-        result2 = await handle_approvals_without_thread(query2, agent)
+        result2 = await handle_approvals_without_session(query2, agent)
        print(f"{agent.name}: {result2}\n")


-async def run_hosted_mcp_with_thread() -> None:
-    """Example showing Mcp Tools with approvals using a thread."""
-    print("=== Mcp with approvals and with thread ===")
+async def run_hosted_mcp_with_session() -> None:
+    """Example showing Mcp Tools with approvals using a session."""
+    print("=== Mcp with approvals and with session ===")

    client = OpenAIResponsesClient()
    # Create MCP tool that always requires approval
@@ -178,22 +178,22 @@ async def run_hosted_mcp_with_thread() -> None:
        tools=mcp_tool,
    ) as agent:
        # First query
-        thread = agent.get_new_thread()
+        session = agent.create_session()
        query1 = "How to create an Azure storage account using az cli?"
        print(f"User: {query1}")
-        result1 = await handle_approvals_with_thread(query1, agent, thread)
+        result1 = await handle_approvals_with_session(query1, agent, session)
        print(f"{agent.name}: {result1}\n")
        print("\n=======================================\n")
        # Second query
        query2 = "What is Microsoft Agent Framework?"
        print(f"User: {query2}")
-        result2 = await handle_approvals_with_thread(query2, agent, thread)
+        result2 = await handle_approvals_with_session(query2, agent, session)
        print(f"{agent.name}: {result2}\n")


-async def run_hosted_mcp_with_thread_streaming() -> None:
-    """Example showing Mcp Tools with approvals using a thread."""
-    print("=== Mcp with approvals and with thread ===")
+async def run_hosted_mcp_with_session_streaming() -> None:
+    """Example showing Mcp Tools with approvals using a session."""
+    print("=== Mcp with approvals and with session ===")

    client = OpenAIResponsesClient()
    # Create MCP tool that always requires approval
@@ -211,11 +211,11 @@ async def run_hosted_mcp_with_thread_streaming() -> None:
        tools=mcp_tool,
    ) as agent:
        # First query
-        thread = agent.get_new_thread()
+        session = agent.create_session()
        query1 = "How to create an Azure storage account using az cli?"
        print(f"User: {query1}")
        print(f"{agent.name}: ", end="")
-        async for update in handle_approvals_with_thread_streaming(query1, agent, thread):
+        async for update in handle_approvals_with_session_streaming(query1, agent, session):
            print(update, end="")
        print("\n")
        print("\n=======================================\n")
@@ -223,7 +223,7 @@ async def run_hosted_mcp_with_thread_streaming() -> None:
        query2 = "What is Microsoft Agent Framework?"
        print(f"User: {query2}")
        print(f"{agent.name}: ", end="")
-        async for update in handle_approvals_with_thread_streaming(query2, agent, thread):
+        async for update in handle_approvals_with_session_streaming(query2, agent, session):
            print(update, end="")
        print("\n")

@@ -232,9 +232,9 @@ async def main() -> None:
    print("=== OpenAI Responses Client Agent with Hosted Mcp Tools Examples ===\n")

    await run_hosted_mcp_without_approval()
-    await run_hosted_mcp_without_thread_and_specific_approval()
-    await run_hosted_mcp_with_thread()
-    await run_hosted_mcp_with_thread_streaming()
+    await run_hosted_mcp_without_session_and_specific_approval()
+    await run_hosted_mcp_with_session()
+    await run_hosted_mcp_with_session_streaming()


 if __name__ == "__main__":
@@ -4,21 +4,21 @@ import asyncio
 from random import randint
 from typing import Annotated

-from agent_framework import Agent, AgentThread, tool
+from agent_framework import Agent, AgentSession, tool
 from agent_framework.openai import OpenAIResponsesClient
 from pydantic import Field

 """
-OpenAI Responses Client with Thread Management Example
+OpenAI Responses Client with Session Management Example

-This sample demonstrates thread management with OpenAI Responses Client, showing
+This sample demonstrates session management with OpenAI Responses Client, showing
 persistent conversation context and simplified response handling.
 """


 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -28,9 +28,9 @@ def get_weather(
    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."


-async def example_with_automatic_thread_creation() -> None:
-    """Example showing automatic thread creation."""
-    print("=== Automatic Thread Creation Example ===")
+async def example_with_automatic_session_creation() -> None:
+    """Example showing automatic session creation."""
+    print("=== Automatic Session Creation Example ===")

    agent = Agent(
        client=OpenAIResponsesClient(),
@@ -38,26 +38,26 @@ async def example_with_automatic_thread_creation() -> None:
        tools=get_weather,
    )

-    # First conversation - no thread provided, will be created automatically
+    # First conversation - no session provided, will be created automatically
    query1 = "What's the weather like in Seattle?"
    print(f"User: {query1}")
    result1 = await agent.run(query1)
    print(f"Agent: {result1.text}")

-    # Second conversation - still no thread provided, will create another new thread
+    # Second conversation - still no session provided, will create another new session
    query2 = "What was the last city I asked about?"
    print(f"\nUser: {query2}")
    result2 = await agent.run(query2)
    print(f"Agent: {result2.text}")
-    print("Note: Each call creates a separate thread, so the agent doesn't remember previous context.\n")
+    print("Note: Each call creates a separate session, so the agent doesn't remember previous context.\n")


-async def example_with_thread_persistence_in_memory() -> None:
+async def example_with_session_persistence_in_memory() -> None:
    """
-    Example showing thread persistence across multiple conversations.
+    Example showing session persistence across multiple conversations.
    In this example, messages are stored in-memory.
    """
-    print("=== Thread Persistence Example (In-Memory) ===")
+    print("=== Session Persistence Example (In-Memory) ===")

    agent = Agent(
        client=OpenAIResponsesClient(),
@@ -65,38 +65,38 @@ async def example_with_thread_persistence_in_memory() -> None:
        tools=get_weather,
    )

-    # Create a new thread that will be reused
-    thread = agent.get_new_thread()
+    # Create a new session that will be reused
+    session = agent.create_session()

    # First conversation
    query1 = "What's the weather like in Tokyo?"
    print(f"User: {query1}")
-    result1 = await agent.run(query1, thread=thread, store=False)
+    result1 = await agent.run(query1, session=session, store=False)
    print(f"Agent: {result1.text}")

-    # Second conversation using the same thread - maintains context
+    # Second conversation using the same session - maintains context
    query2 = "How about London?"
    print(f"\nUser: {query2}")
-    result2 = await agent.run(query2, thread=thread, store=False)
+    result2 = await agent.run(query2, session=session, store=False)
    print(f"Agent: {result2.text}")

    # Third conversation - agent should remember both previous cities
    query3 = "Which of the cities I asked about has better weather?"
    print(f"\nUser: {query3}")
-    result3 = await agent.run(query3, thread=thread, store=False)
+    result3 = await agent.run(query3, session=session, store=False)
    print(f"Agent: {result3.text}")
-    print("Note: The agent remembers context from previous messages in the same thread.\n")
+    print("Note: The agent remembers context from previous messages in the same session.\n")


-async def example_with_existing_thread_id() -> None:
+async def example_with_existing_session_id() -> None:
    """
-    Example showing how to work with an existing thread ID from the service.
+    Example showing how to work with an existing session ID from the service.
    In this example, messages are stored on the server using OpenAI conversation state.
    """
-    print("=== Existing Thread ID Example ===")
+    print("=== Existing Session ID Example ===")

-    # First, create a conversation and capture the thread ID
-    existing_thread_id = None
+    # First, create a conversation and capture the session ID
+    existing_session_id = None

    agent = Agent(
        client=OpenAIResponsesClient(),
@@ -104,20 +104,20 @@ async def example_with_existing_thread_id() -> None:
        tools=get_weather,
    )

-    # Start a conversation and get the thread ID
-    thread = agent.get_new_thread()
+    # Start a conversation and get the session ID
+    session = agent.create_session()

    query1 = "What's the weather in Paris?"
    print(f"User: {query1}")
-    result1 = await agent.run(query1, thread=thread)
+    result1 = await agent.run(query1, session=session)
    print(f"Agent: {result1.text}")

-    # The thread ID is set after the first response
-    existing_thread_id = thread.service_thread_id
-    print(f"Thread ID: {existing_thread_id}")
+    # The session ID is set after the first response
+    existing_session_id = session.service_session_id
+    print(f"Session ID: {existing_session_id}")

-    if existing_thread_id:
-        print("\n--- Continuing with the same thread ID in a new agent instance ---")
+    if existing_session_id:
+        print("\n--- Continuing with the same session ID in a new agent instance ---")

        agent = Agent(
            client=OpenAIResponsesClient(),
@@ -125,22 +125,22 @@ async def example_with_existing_thread_id() -> None:
            tools=get_weather,
        )

-        # Create a thread with the existing ID
-        thread = AgentThread(service_thread_id=existing_thread_id)
+        # Create a session with the existing ID
+        session = AgentSession(service_session_id=existing_session_id)

        query2 = "What was the last city I asked about?"
        print(f"User: {query2}")
-        result2 = await agent.run(query2, thread=thread)
+        result2 = await agent.run(query2, session=session)
        print(f"Agent: {result2.text}")
-        print("Note: The agent continues the conversation from the previous thread by using thread ID.\n")
+        print("Note: The agent continues the conversation from the previous session by using session ID.\n")


 async def main() -> None:
-    print("=== OpenAI Response Client Agent Thread Management Examples ===\n")
+    print("=== OpenAI Response Client Agent Session Management Examples ===\n")

-    await example_with_automatic_thread_creation()
-    await example_with_thread_persistence_in_memory()
-    await example_with_existing_thread_id()
+    await example_with_automatic_session_creation()
+    await example_with_session_persistence_in_memory()
+    await example_with_existing_session_id()


 if __name__ == "__main__":