Python: [BREAKING] updated structure and samples (#875)

* updated structure and samples

* updated names and removed cross tests

* updated projects etc

* updated tests

* updated test

* test fixes

* removed devui for now

* updated all-tests task

* removed old style configs

* remove coverage from tests

* updated to unit tests with all-tests

* updated foundry everywhere

* fix azure ai tests

* fix merge tests

* fix mypy

python/samples/getting_started/agents/azure_openai/README.md

@@ -0,0 +1,51 @@
+# Azure OpenAI Agent Examples
+
+This folder contains examples demonstrating different ways to create and use agents with the different Azure OpenAI chat client from the `agent_framework.azure` package.
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| [`azure_assistants_basic.py`](azure_assistants_basic.py) | The simplest way to create an agent using `ChatAgent` with `AzureOpenAIAssistantsClient`. Shows both streaming and non-streaming responses with automatic assistant creation and cleanup. |
+| [`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_code_interpreter.py`](azure_assistants_with_code_interpreter.py) | Shows how to use the HostedCodeInterpreterTool with Azure agents to write and execute Python code. Includes helper methods for accessing code interpreter data from response chunks. |
+| [`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_chat_client_basic.py`](azure_chat_client_basic.py) | The simplest way to create an agent using `ChatAgent` 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_responses_client_basic.py`](azure_responses_client_basic.py) | The simplest way to create an agent using `ChatAgent` with `AzureOpenAIResponsesClient`. Shows both streaming and non-streaming responses for structured response generation with Azure OpenAI models. |
+| [`azure_responses_client_with_explicit_settings.py`](azure_responses_client_with_explicit_settings.py) | Shows how to initialize an agent with a specific responses client, configuring settings explicitly including endpoint and deployment name. |
+| [`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_code_interpreter.py`](azure_responses_client_with_code_interpreter.py) | Shows how to use the HostedCodeInterpreterTool with Azure agents to write and execute Python code. Includes helper methods for accessing code interpreter data from response chunks. |
+| [`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. |
+
+## Environment Variables
+
+Make sure to set the following environment variables before running the examples:
+
+- `AZURE_OPENAI_ENDPOINT`: Your Azure OpenAI endpoint
+- `AZURE_OPENAI_CHAT_DEPLOYMENT_NAME`: The name of your Azure OpenAI chat model deployment
+- `AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME`: The name of your Azure OpenAI Responses deployment
+
+Optionally, you can set:
+- `AZURE_OPENAI_API_VERSION`: The API version to use (default is `2024-02-15-preview`)
+- `AZURE_OPENAI_API_KEY`: Your Azure OpenAI API key (if not using `AzureCliCredential`)
+- `AZURE_OPENAI_BASE_URL`: Your Azure OpenAI base URL (if different from the endpoint)
+
+## Authentication
+
+All examples use `AzureCliCredential` for authentication. Run `az login` in your terminal before running the examples, or replace `AzureCliCredential` with your preferred authentication method.
+
+## Required role-based access control (RBAC) roles
+
+To access the Azure OpenAI API, your Azure account or service principal needs one of the following RBAC roles assigned to the Azure OpenAI resource:
+
+- **Cognitive Services OpenAI User**: Provides read access to Azure OpenAI resources and the ability to call the inference APIs. This is the minimum role required for running these examples.
+- **Cognitive Services OpenAI Contributor**: Provides full access to Azure OpenAI resources, including the ability to create, update, and delete deployments and models.
+
+For most scenarios, the **Cognitive Services OpenAI User** role is sufficient. You can assign this role through the Azure portal under the Azure OpenAI resource's "Access control (IAM)" section.
+
+For more detailed information about Azure OpenAI RBAC roles, see: [Role-based access control for Azure OpenAI Service](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/role-based-access-control)

python/samples/getting_started/agents/azure_openai/azure_assistants_basic.py

@@ -0,0 +1,65 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from random import randint
+from typing import Annotated
+
+from agent_framework.azure import AzureOpenAIAssistantsClient
+from azure.identity import AzureCliCredential
+from pydantic import Field
+
+
+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 non_streaming_example() -> None:
+    """Example of non-streaming response (get the complete result at once)."""
+    print("=== Non-streaming Response Example ===")
+
+    # Since no assistant ID is provided, the assistant will be automatically created
+    # and deleted after getting a response
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    async with AzureOpenAIAssistantsClient(credential=AzureCliCredential()).create_agent(
+        instructions="You are a helpful weather agent.",
+        tools=get_weather,
+    ) as agent:
+        query = "What's the weather like in Seattle?"
+        print(f"User: {query}")
+        result = await agent.run(query)
+        print(f"Agent: {result}\n")
+
+
+async def streaming_example() -> None:
+    """Example of streaming response (get results as they are generated)."""
+    print("=== Streaming Response Example ===")
+
+    # Since no assistant ID is provided, the assistant will be automatically created
+    # and deleted after getting a response
+    async with AzureOpenAIAssistantsClient(credential=AzureCliCredential()).create_agent(
+        instructions="You are a helpful weather agent.",
+        tools=get_weather,
+    ) as agent:
+        query = "What's the weather like in Portland?"
+        print(f"User: {query}")
+        print("Agent: ", end="", flush=True)
+        async for chunk in agent.run_stream(query):
+            if chunk.text:
+                print(chunk.text, end="", flush=True)
+        print("\n")
+
+
+async def main() -> None:
+    print("=== Basic Azure OpenAI Assistants Chat Client Agent Example ===")
+
+    await non_streaming_example()
+    await streaming_example()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_openai/azure_assistants_with_code_interpreter.py

@@ -0,0 +1,62 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import AgentRunResponseUpdate, ChatAgent, ChatResponseUpdate, HostedCodeInterpreterTool
+from agent_framework.azure import AzureOpenAIAssistantsClient
+from azure.identity import AzureCliCredential
+from openai.types.beta.threads.runs import (
+    CodeInterpreterToolCallDelta,
+    RunStepDelta,
+    RunStepDeltaEvent,
+    ToolCallDeltaObject,
+)
+from openai.types.beta.threads.runs.code_interpreter_tool_call_delta import CodeInterpreter
+
+
+def get_code_interpreter_chunk(chunk: AgentRunResponseUpdate) -> str | None:
+    """Helper method to access code interpreter data."""
+    if (
+        isinstance(chunk.raw_representation, ChatResponseUpdate)
+        and isinstance(chunk.raw_representation.raw_representation, RunStepDeltaEvent)
+        and isinstance(chunk.raw_representation.raw_representation.delta, RunStepDelta)
+        and isinstance(chunk.raw_representation.raw_representation.delta.step_details, ToolCallDeltaObject)
+        and chunk.raw_representation.raw_representation.delta.step_details.tool_calls
+    ):
+        for tool_call in chunk.raw_representation.raw_representation.delta.step_details.tool_calls:
+            if (
+                isinstance(tool_call, CodeInterpreterToolCallDelta)
+                and isinstance(tool_call.code_interpreter, CodeInterpreter)
+                and tool_call.code_interpreter.input is not None
+            ):
+                return tool_call.code_interpreter.input
+    return None
+
+
+async def main() -> None:
+    """Example showing how to use the HostedCodeInterpreterTool with Azure OpenAI Assistants."""
+    print("=== Azure OpenAI Assistants Agent with Code Interpreter Example ===")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    async with ChatAgent(
+        chat_client=AzureOpenAIAssistantsClient(credential=AzureCliCredential()),
+        instructions="You are a helpful assistant that can write and execute Python code to solve problems.",
+        tools=HostedCodeInterpreterTool(),
+    ) as agent:
+        query = "What is current datetime?"
+        print(f"User: {query}")
+        print("Agent: ", end="", flush=True)
+        generated_code = ""
+        async for chunk in agent.run_stream(query):
+            if chunk.text:
+                print(chunk.text, end="", flush=True)
+            code_interpreter_chunk = get_code_interpreter_chunk(chunk)
+            if code_interpreter_chunk is not None:
+                generated_code += code_interpreter_chunk
+
+        print(f"\nGenerated code:\n{generated_code}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_openai/azure_assistants_with_existing_assistant.py

@@ -0,0 +1,53 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from random import randint
+from typing import Annotated
+
+from agent_framework import ChatAgent
+from agent_framework.azure import AzureOpenAIAssistantsClient
+from azure.identity import AzureCliCredential, get_bearer_token_provider
+from openai import AsyncAzureOpenAI
+from pydantic import Field
+
+
+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 main() -> None:
+    print("=== Azure OpenAI Assistants Chat Client with Existing Assistant ===")
+
+    token_provider = get_bearer_token_provider(AzureCliCredential(), "https://cognitiveservices.azure.com/.default")
+
+    client = AsyncAzureOpenAI(
+        azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
+        azure_ad_token_provider=token_provider,
+        api_version="2025-01-01-preview",
+    )
+
+    # Create an assistant that will persist
+    created_assistant = await client.beta.assistants.create(
+        model=os.environ["AZURE_OPENAI_CHAT_DEPLOYMENT_NAME"], name="WeatherAssistant"
+    )
+
+    try:
+        async with ChatAgent(
+            chat_client=AzureOpenAIAssistantsClient(async_client=client, assistant_id=created_assistant.id),
+            instructions="You are a helpful weather agent.",
+            tools=get_weather,
+        ) as agent:
+            result = await agent.run("What's the weather like in Tokyo?")
+            print(f"Result: {result}\n")
+    finally:
+        # Clean up the assistant manually
+        await client.beta.assistants.delete(created_assistant.id)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_openai/azure_assistants_with_explicit_settings.py

@@ -0,0 +1,39 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from random import randint
+from typing import Annotated
+
+from agent_framework.azure import AzureOpenAIAssistantsClient
+from azure.identity import AzureCliCredential
+from pydantic import Field
+
+
+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 main() -> None:
+    print("=== Azure Assistants Client with Explicit Settings ===")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    async with AzureOpenAIAssistantsClient(
+        endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
+        deployment_name=os.environ["AZURE_OPENAI_CHAT_DEPLOYMENT_NAME"],
+        credential=AzureCliCredential(),
+    ).create_agent(
+        instructions="You are a helpful weather agent.",
+        tools=get_weather,
+    ) as agent:
+        result = await agent.run("What's the weather like in New York?")
+        print(f"Result: {result}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_openai/azure_assistants_with_function_tools.py

@@ -0,0 +1,124 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from datetime import datetime, timezone
+from random import randint
+from typing import Annotated
+
+from agent_framework import ChatAgent
+from agent_framework.azure import AzureOpenAIAssistantsClient
+from azure.identity import AzureCliCredential
+from pydantic import Field
+
+
+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."
+
+
+def get_time() -> str:
+    """Get the current UTC time."""
+    current_time = datetime.now(timezone.utc)
+    return f"The current UTC time is {current_time.strftime('%Y-%m-%d %H:%M:%S')}."
+
+
+async def tools_on_agent_level() -> None:
+    """Example showing tools defined when creating the agent."""
+    print("=== Tools Defined on Agent Level ===")
+
+    # Tools are provided when creating the agent
+    # The agent can use these tools for any query during its lifetime
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    async with ChatAgent(
+        chat_client=AzureOpenAIAssistantsClient(credential=AzureCliCredential()),
+        instructions="You are a helpful assistant that can provide weather and time information.",
+        tools=[get_weather, get_time],  # Tools defined at agent creation
+    ) as agent:
+        # First query - agent can use weather tool
+        query1 = "What's the weather like in New York?"
+        print(f"User: {query1}")
+        result1 = await agent.run(query1)
+        print(f"Agent: {result1}\n")
+
+        # Second query - agent can use time tool
+        query2 = "What's the current UTC time?"
+        print(f"User: {query2}")
+        result2 = await agent.run(query2)
+        print(f"Agent: {result2}\n")
+
+        # Third query - agent can use both tools if needed
+        query3 = "What's the weather in London and what's the current UTC time?"
+        print(f"User: {query3}")
+        result3 = await agent.run(query3)
+        print(f"Agent: {result3}\n")
+
+
+async def tools_on_run_level() -> None:
+    """Example showing tools passed to the run method."""
+    print("=== Tools Passed to Run Method ===")
+
+    # Agent created without tools
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    async with ChatAgent(
+        chat_client=AzureOpenAIAssistantsClient(credential=AzureCliCredential()),
+        instructions="You are a helpful assistant.",
+        # No tools defined here
+    ) as agent:
+        # First query with weather tool
+        query1 = "What's the weather like in Seattle?"
+        print(f"User: {query1}")
+        result1 = await agent.run(query1, tools=[get_weather])  # Tool passed to run method
+        print(f"Agent: {result1}\n")
+
+        # Second query with time tool
+        query2 = "What's the current UTC time?"
+        print(f"User: {query2}")
+        result2 = await agent.run(query2, tools=[get_time])  # Different tool for this query
+        print(f"Agent: {result2}\n")
+
+        # Third query with multiple tools
+        query3 = "What's the weather in Chicago and what's the current UTC time?"
+        print(f"User: {query3}")
+        result3 = await agent.run(query3, tools=[get_weather, get_time])  # Multiple tools
+        print(f"Agent: {result3}\n")
+
+
+async def mixed_tools_example() -> None:
+    """Example showing both agent-level tools and run-method tools."""
+    print("=== Mixed Tools Example (Agent + Run Method) ===")
+
+    # Agent created with some base tools
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    async with ChatAgent(
+        chat_client=AzureOpenAIAssistantsClient(credential=AzureCliCredential()),
+        instructions="You are a comprehensive assistant that can help with various information requests.",
+        tools=[get_weather],  # Base tool available for all queries
+    ) as agent:
+        # Query using both agent tool and additional run-method tools
+        query = "What's the weather in Denver and what's the current UTC time?"
+        print(f"User: {query}")
+
+        # Agent has access to get_weather (from creation) + additional tools from run method
+        result = await agent.run(
+            query,
+            tools=[get_time],  # Additional tools for this specific query
+        )
+        print(f"Agent: {result}\n")
+
+
+async def main() -> None:
+    print("=== Azure OpenAI Assistants Chat Client Agent with Function Tools Examples ===\n")
+
+    await tools_on_agent_level()
+    await tools_on_run_level()
+    await mixed_tools_example()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_openai/azure_assistants_with_thread.py

@@ -0,0 +1,135 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from random import randint
+from typing import Annotated
+
+from agent_framework import AgentThread, ChatAgent
+from agent_framework.azure import AzureOpenAIAssistantsClient
+from azure.identity import AzureCliCredential
+from pydantic import Field
+
+
+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 ===")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    async with ChatAgent(
+        chat_client=AzureOpenAIAssistantsClient(credential=AzureCliCredential()),
+        instructions="You are a helpful weather agent.",
+        tools=get_weather,
+    ) as agent:
+        # 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")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    async with ChatAgent(
+        chat_client=AzureOpenAIAssistantsClient(credential=AzureCliCredential()),
+        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()
+
+        # 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_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")
+
+    # First, create a conversation and capture the thread ID
+    existing_thread_id = None
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    async with ChatAgent(
+        chat_client=AzureOpenAIAssistantsClient(credential=AzureCliCredential()),
+        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()
+        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 ID is set after the first response
+        existing_thread_id = thread.service_thread_id
+        print(f"Thread ID: {existing_thread_id}")
+
+    if existing_thread_id:
+        print("\n--- Continuing with the same thread ID in a new agent instance ---")
+
+        # Create a new agent instance but use the existing thread ID
+        async with ChatAgent(
+            chat_client=AzureOpenAIAssistantsClient(thread_id=existing_thread_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)
+
+            query2 = "What was the last city I asked about?"
+            print(f"User: {query2}")
+            result2 = await agent.run(query2, thread=thread)
+            print(f"Agent: {result2.text}")
+            print("Note: The agent continues the conversation from the previous thread.\n")
+
+
+async def main() -> None:
+    print("=== Azure OpenAI Assistants Chat Client Agent Thread Management Examples ===\n")
+
+    await example_with_automatic_thread_creation()
+    await example_with_thread_persistence()
+    await example_with_existing_thread_id()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_openai/azure_chat_client_basic.py

@@ -0,0 +1,67 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from random import randint
+from typing import Annotated
+
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+from pydantic import Field
+
+
+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 non_streaming_example() -> None:
+    """Example of non-streaming response (get the complete result at once)."""
+    print("=== Non-streaming Response Example ===")
+
+    # Create agent with Azure Chat Client
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = AzureOpenAIChatClient(credential=AzureCliCredential()).create_agent(
+        instructions="You are a helpful weather agent.",
+        tools=get_weather,
+    )
+
+    query = "What's the weather like in Seattle?"
+    print(f"User: {query}")
+    result = await agent.run(query)
+    print(f"Result: {result}\n")
+
+
+async def streaming_example() -> None:
+    """Example of streaming response (get results as they are generated)."""
+    print("=== Streaming Response Example ===")
+
+    # Create agent with Azure Chat Client
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = AzureOpenAIChatClient(credential=AzureCliCredential()).create_agent(
+        instructions="You are a helpful weather agent.",
+        tools=get_weather,
+    )
+
+    query = "What's the weather like in Portland?"
+    print(f"User: {query}")
+    print("Agent: ", end="", flush=True)
+    async for chunk in agent.run_stream(query):
+        if chunk.text:
+            print(chunk.text, end="", flush=True)
+    print("\n")
+
+
+async def main() -> None:
+    print("=== Basic Azure Chat Client Agent Example ===")
+
+    await non_streaming_example()
+    await streaming_example()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_openai/azure_chat_client_with_explicit_settings.py

@@ -0,0 +1,40 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from random import randint
+from typing import Annotated
+
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+from pydantic import Field
+
+
+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 main() -> None:
+    print("=== Azure Chat Client with Explicit Settings ===")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = AzureOpenAIChatClient(
+        deployment_name=os.environ["AZURE_OPENAI_CHAT_DEPLOYMENT_NAME"],
+        endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
+        credential=AzureCliCredential(),
+    ).create_agent(
+        instructions="You are a helpful weather agent.",
+        tools=get_weather,
+    )
+
+    result = await agent.run("What's the weather like in New York?")
+    print(f"Result: {result}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_openai/azure_chat_client_with_function_tools.py

@@ -0,0 +1,127 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from datetime import datetime, timezone
+from random import randint
+from typing import Annotated
+
+from agent_framework import ChatAgent
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+from pydantic import Field
+
+
+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."
+
+
+def get_time() -> str:
+    """Get the current UTC time."""
+    current_time = datetime.now(timezone.utc)
+    return f"The current UTC time is {current_time.strftime('%Y-%m-%d %H:%M:%S')}."
+
+
+async def tools_on_agent_level() -> None:
+    """Example showing tools defined when creating the agent."""
+    print("=== Tools Defined on Agent Level ===")
+
+    # Tools are provided when creating the agent
+    # The agent can use these tools for any query during its lifetime
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = ChatAgent(
+        chat_client=AzureOpenAIChatClient(credential=AzureCliCredential()),
+        instructions="You are a helpful assistant that can provide weather and time information.",
+        tools=[get_weather, get_time],  # Tools defined at agent creation
+    )
+
+    # First query - agent can use weather tool
+    query1 = "What's the weather like in New York?"
+    print(f"User: {query1}")
+    result1 = await agent.run(query1)
+    print(f"Agent: {result1}\n")
+
+    # Second query - agent can use time tool
+    query2 = "What's the current UTC time?"
+    print(f"User: {query2}")
+    result2 = await agent.run(query2)
+    print(f"Agent: {result2}\n")
+
+    # Third query - agent can use both tools if needed
+    query3 = "What's the weather in London and what's the current UTC time?"
+    print(f"User: {query3}")
+    result3 = await agent.run(query3)
+    print(f"Agent: {result3}\n")
+
+
+async def tools_on_run_level() -> None:
+    """Example showing tools passed to the run method."""
+    print("=== Tools Passed to Run Method ===")
+
+    # Agent created without tools
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = ChatAgent(
+        chat_client=AzureOpenAIChatClient(credential=AzureCliCredential()),
+        instructions="You are a helpful assistant.",
+        # No tools defined here
+    )
+
+    # First query with weather tool
+    query1 = "What's the weather like in Seattle?"
+    print(f"User: {query1}")
+    result1 = await agent.run(query1, tools=[get_weather])  # Tool passed to run method
+    print(f"Agent: {result1}\n")
+
+    # Second query with time tool
+    query2 = "What's the current UTC time?"
+    print(f"User: {query2}")
+    result2 = await agent.run(query2, tools=[get_time])  # Different tool for this query
+    print(f"Agent: {result2}\n")
+
+    # Third query with multiple tools
+    query3 = "What's the weather in Chicago and what's the current UTC time?"
+    print(f"User: {query3}")
+    result3 = await agent.run(query3, tools=[get_weather, get_time])  # Multiple tools
+    print(f"Agent: {result3}\n")
+
+
+async def mixed_tools_example() -> None:
+    """Example showing both agent-level tools and run-method tools."""
+    print("=== Mixed Tools Example (Agent + Run Method) ===")
+
+    # Agent created with some base tools
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = ChatAgent(
+        chat_client=AzureOpenAIChatClient(credential=AzureCliCredential()),
+        instructions="You are a comprehensive assistant that can help with various information requests.",
+        tools=[get_weather],  # Base tool available for all queries
+    )
+
+    # Query using both agent tool and additional run-method tools
+    query = "What's the weather in Denver and what's the current UTC time?"
+    print(f"User: {query}")
+
+    # Agent has access to get_weather (from creation) + additional tools from run method
+    result = await agent.run(
+        query,
+        tools=[get_time],  # Additional tools for this specific query
+    )
+    print(f"Agent: {result}\n")
+
+
+async def main() -> None:
+    print("=== Azure Chat Client Agent with Function Tools Examples ===\n")
+
+    await tools_on_agent_level()
+    await tools_on_run_level()
+    await mixed_tools_example()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_openai/azure_chat_client_with_thread.py

@@ -0,0 +1,146 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from random import randint
+from typing import Annotated
+
+from agent_framework import AgentThread, ChatAgent, ChatMessageList
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+from pydantic import Field
+
+
+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 ===")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = ChatAgent(
+        chat_client=AzureOpenAIChatClient(credential=AzureCliCredential()),
+        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")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = ChatAgent(
+        chat_client=AzureOpenAIChatClient(credential=AzureCliCredential()),
+        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 Azure."""
+    print("=== Existing Thread Messages Example ===")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = ChatAgent(
+        chat_client=AzureOpenAIChatClient(credential=AzureCliCredential()),
+        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 = ChatAgent(
+        chat_client=AzureOpenAIChatClient(credential=AzureCliCredential()),
+        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=ChatMessageList(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("=== Azure 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())

python/samples/getting_started/agents/azure_openai/azure_responses_client_basic.py

@@ -0,0 +1,65 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from random import randint
+from typing import Annotated
+
+from agent_framework.azure import AzureOpenAIResponsesClient
+from azure.identity import AzureCliCredential
+from pydantic import Field
+
+
+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 non_streaming_example() -> None:
+    """Example of non-streaming response (get the complete result at once)."""
+    print("=== Non-streaming Response Example ===")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = AzureOpenAIResponsesClient(credential=AzureCliCredential()).create_agent(
+        instructions="You are a helpful weather agent.",
+        tools=get_weather,
+    )
+
+    query = "What's the weather like in Seattle?"
+    print(f"User: {query}")
+    result = await agent.run(query)
+    print(f"Result: {result}\n")
+
+
+async def streaming_example() -> None:
+    """Example of streaming response (get results as they are generated)."""
+    print("=== Streaming Response Example ===")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = AzureOpenAIResponsesClient(credential=AzureCliCredential()).create_agent(
+        instructions="You are a helpful weather agent.",
+        tools=get_weather,
+    )
+
+    query = "What's the weather like in Portland?"
+    print(f"User: {query}")
+    print("Agent: ", end="", flush=True)
+    async for chunk in agent.run_stream(query):
+        if chunk.text:
+            print(chunk.text, end="", flush=True)
+    print("\n")
+
+
+async def main() -> None:
+    print("=== Basic Azure OpenAI Responses Client Agent Example ===")
+
+    await non_streaming_example()
+    await streaming_example()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_openai/azure_responses_client_with_code_interpreter.py

@@ -0,0 +1,41 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import ChatAgent, ChatResponse, HostedCodeInterpreterTool
+from agent_framework.azure import AzureOpenAIResponsesClient
+from azure.identity import AzureCliCredential
+from openai.types.responses.response import Response as OpenAIResponse
+from openai.types.responses.response_code_interpreter_tool_call import ResponseCodeInterpreterToolCall
+
+
+async def main() -> None:
+    """Example showing how to use the HostedCodeInterpreterTool with Azure OpenAI Responses."""
+    print("=== Azure OpenAI Responses Agent with Code Interpreter Example ===")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = ChatAgent(
+        chat_client=AzureOpenAIResponsesClient(credential=AzureCliCredential()),
+        instructions="You are a helpful assistant that can write and execute Python code to solve problems.",
+        tools=HostedCodeInterpreterTool(),
+    )
+
+    query = "Use code to calculate the factorial of 100?"
+    print(f"User: {query}")
+    result = await agent.run(query)
+    print(f"Result: {result}\n")
+
+    if (
+        isinstance(result.raw_representation, ChatResponse)
+        and isinstance(result.raw_representation.raw_representation, OpenAIResponse)
+        and len(result.raw_representation.raw_representation.output) > 0
+        and isinstance(result.raw_representation.raw_representation.output[0], ResponseCodeInterpreterToolCall)
+    ):
+        generated_code = result.raw_representation.raw_representation.output[0].code
+
+        print(f"Generated code:\n{generated_code}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_openai/azure_responses_client_with_explicit_settings.py

@@ -0,0 +1,40 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from random import randint
+from typing import Annotated
+
+from agent_framework.azure import AzureOpenAIResponsesClient
+from azure.identity import AzureCliCredential
+from pydantic import Field
+
+
+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 main() -> None:
+    print("=== Azure Responses Client with Explicit Settings ===")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = AzureOpenAIResponsesClient(
+        deployment_name=os.environ["AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME"],
+        endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
+        credential=AzureCliCredential(),
+    ).create_agent(
+        instructions="You are a helpful weather agent.",
+        tools=get_weather,
+    )
+
+    result = await agent.run("What's the weather like in New York?")
+    print(f"Result: {result}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_openai/azure_responses_client_with_function_tools.py

@@ -0,0 +1,127 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from datetime import datetime, timezone
+from random import randint
+from typing import Annotated
+
+from agent_framework import ChatAgent
+from agent_framework.azure import AzureOpenAIResponsesClient
+from azure.identity import AzureCliCredential
+from pydantic import Field
+
+
+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."
+
+
+def get_time() -> str:
+    """Get the current UTC time."""
+    current_time = datetime.now(timezone.utc)
+    return f"The current UTC time is {current_time.strftime('%Y-%m-%d %H:%M:%S')}."
+
+
+async def tools_on_agent_level() -> None:
+    """Example showing tools defined when creating the agent."""
+    print("=== Tools Defined on Agent Level ===")
+
+    # Tools are provided when creating the agent
+    # The agent can use these tools for any query during its lifetime
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = ChatAgent(
+        chat_client=AzureOpenAIResponsesClient(credential=AzureCliCredential()),
+        instructions="You are a helpful assistant that can provide weather and time information.",
+        tools=[get_weather, get_time],  # Tools defined at agent creation
+    )
+
+    # First query - agent can use weather tool
+    query1 = "What's the weather like in New York?"
+    print(f"User: {query1}")
+    result1 = await agent.run(query1)
+    print(f"Agent: {result1}\n")
+
+    # Second query - agent can use time tool
+    query2 = "What's the current UTC time?"
+    print(f"User: {query2}")
+    result2 = await agent.run(query2)
+    print(f"Agent: {result2}\n")
+
+    # Third query - agent can use both tools if needed
+    query3 = "What's the weather in London and what's the current UTC time?"
+    print(f"User: {query3}")
+    result3 = await agent.run(query3)
+    print(f"Agent: {result3}\n")
+
+
+async def tools_on_run_level() -> None:
+    """Example showing tools passed to the run method."""
+    print("=== Tools Passed to Run Method ===")
+
+    # Agent created without tools
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = ChatAgent(
+        chat_client=AzureOpenAIResponsesClient(credential=AzureCliCredential()),
+        instructions="You are a helpful assistant.",
+        # No tools defined here
+    )
+
+    # First query with weather tool
+    query1 = "What's the weather like in Seattle?"
+    print(f"User: {query1}")
+    result1 = await agent.run(query1, tools=[get_weather])  # Tool passed to run method
+    print(f"Agent: {result1}\n")
+
+    # Second query with time tool
+    query2 = "What's the current UTC time?"
+    print(f"User: {query2}")
+    result2 = await agent.run(query2, tools=[get_time])  # Different tool for this query
+    print(f"Agent: {result2}\n")
+
+    # Third query with multiple tools
+    query3 = "What's the weather in Chicago and what's the current UTC time?"
+    print(f"User: {query3}")
+    result3 = await agent.run(query3, tools=[get_weather, get_time])  # Multiple tools
+    print(f"Agent: {result3}\n")
+
+
+async def mixed_tools_example() -> None:
+    """Example showing both agent-level tools and run-method tools."""
+    print("=== Mixed Tools Example (Agent + Run Method) ===")
+
+    # Agent created with some base tools
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = ChatAgent(
+        chat_client=AzureOpenAIResponsesClient(credential=AzureCliCredential()),
+        instructions="You are a comprehensive assistant that can help with various information requests.",
+        tools=[get_weather],  # Base tool available for all queries
+    )
+
+    # Query using both agent tool and additional run-method tools
+    query = "What's the weather in Denver and what's the current UTC time?"
+    print(f"User: {query}")
+
+    # Agent has access to get_weather (from creation) + additional tools from run method
+    result = await agent.run(
+        query,
+        tools=[get_time],  # Additional tools for this specific query
+    )
+    print(f"Agent: {result}\n")
+
+
+async def main() -> None:
+    print("=== Azure OpenAI Responses Client Agent with Function Tools Examples ===\n")
+
+    await tools_on_agent_level()
+    await tools_on_run_level()
+    await mixed_tools_example()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_openai/azure_responses_client_with_thread.py

@@ -0,0 +1,144 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from random import randint
+from typing import Annotated
+
+from agent_framework import AgentThread, ChatAgent
+from agent_framework.azure import AzureOpenAIResponsesClient
+from azure.identity import AzureCliCredential
+from pydantic import Field
+
+
+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."""
+    print("=== Automatic Thread Creation Example ===")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = ChatAgent(
+        chat_client=AzureOpenAIResponsesClient(credential=AzureCliCredential()),
+        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_in_memory() -> None:
+    """
+    Example showing thread persistence across multiple conversations.
+    In this example, messages are stored in-memory.
+    """
+    print("=== Thread Persistence Example (In-Memory) ===")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = ChatAgent(
+        chat_client=AzureOpenAIResponsesClient(credential=AzureCliCredential()),
+        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_id() -> None:
+    """
+    Example showing how to work with an existing thread ID from the service.
+    In this example, messages are stored on the server using Azure OpenAI conversation state.
+    """
+    print("=== Existing Thread ID Example ===")
+
+    # First, create a conversation and capture the thread ID
+    existing_thread_id = None
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = ChatAgent(
+        chat_client=AzureOpenAIResponsesClient(credential=AzureCliCredential()),
+        instructions="You are a helpful weather agent.",
+        tools=get_weather,
+    )
+
+    # Start a conversation and get the thread ID
+    thread = agent.get_new_thread()
+
+    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)
+    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}")
+
+    if existing_thread_id:
+        print("\n--- Continuing with the same thread ID in a new agent instance ---")
+
+        agent = ChatAgent(
+            chat_client=AzureOpenAIResponsesClient(credential=AzureCliCredential()),
+            instructions="You are a helpful weather agent.",
+            tools=get_weather,
+        )
+
+        # Create a thread with the existing ID
+        thread = AgentThread(service_thread_id=existing_thread_id)
+
+        query2 = "What was the last city I asked about?"
+        print(f"User: {query2}")
+        result2 = await agent.run(query2, thread=thread, store=True)
+        print(f"Agent: {result2.text}")
+        print("Note: The agent continues the conversation from the previous thread by using thread ID.\n")
+
+
+async def main() -> None:
+    print("=== Azure OpenAI Response Client Agent Thread Management Examples ===\n")
+
+    await example_with_automatic_thread_creation()
+    await example_with_thread_persistence_in_memory()
+    await example_with_existing_thread_id()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())