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_ai/README.md

@@ -0,0 +1,25 @@
+# Azure AI Agent Examples
+
+This folder contains examples demonstrating different ways to create and use agents with the Azure AI chat client from the `agent_framework.azure` package.
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| [`azure_ai_basic.py`](azure_ai_basic.py) | The simplest way to create an agent using `ChatAgent` with `AzureAIAgentClient`. It automatically handles all configuration using environment variables. |
+| [`azure_ai_with_explicit_settings.py`](azure_ai_with_explicit_settings.py) | Shows how to create an agent with explicitly configured `AzureAIAgentClient` settings, including project endpoint, model deployment, credentials, and agent name. |
+| [`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 ID to the Azure AI chat client. This example also demonstrates proper cleanup of manually created agents. |
+| [`azure_ai_with_function_tools.py`](azure_ai_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_ai_with_code_interpreter.py`](azure_ai_with_code_interpreter.py) | Shows how to use the HostedCodeInterpreterTool with Azure AI agents to write and execute Python code. Includes helper methods for accessing code interpreter data from response chunks. |
+| [`azure_ai_with_local_mcp.py`](azure_ai_with_local_mcp.py) | Shows how to integrate Azure AI agents with Model Context Protocol (MCP) servers for enhanced functionality and tool integration. Demonstrates both agent-level and run-level tool configuration. |
+| [`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. |
+
+## Environment Variables
+
+Make sure to set the following environment variables before running the examples:
+
+- `AZURE_AZURE_FOUNDRY_PROJECT_ENDPOINT`: Your Azure AI project endpoint
+- `AZURE_AZURE_FOUNDRY_MODEL_DEPLOYMENT_NAME`: The name of your model deployment
+
+Optionally, you can set:
+- `AZURE_AZURE_FOUNDRY_AGENT_NAME`: The name of your agent, this can also be set programmatically when creating the agent.

python/samples/getting_started/agents/azure_ai/azure_ai_basic.py

@@ -0,0 +1,75 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from random import randint
+from typing import Annotated
+
+from agent_framework.azure import AzureAIAgentClient
+from azure.identity.aio 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 Agent ID is provided, the agent 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 (
+        AzureCliCredential() as credential,
+        AzureAIAgentClient(async_credential=credential).create_agent(
+            name="WeatherAgent",
+            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 Agent ID is provided, the agent 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 (
+        AzureCliCredential() as credential,
+        AzureAIAgentClient(async_credential=credential).create_agent(
+            name="WeatherAgent",
+            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 AI Chat Client Agent Example ===")
+
+    await non_streaming_example()
+    await streaming_example()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_ai/azure_ai_with_code_interpreter.py

@@ -0,0 +1,51 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import AgentRunResponse, ChatResponseUpdate, HostedCodeInterpreterTool
+from agent_framework.azure import AzureAIAgentClient
+from azure.ai.agents.models import (
+    RunStepDeltaCodeInterpreterDetailItemObject,
+)
+from azure.identity.aio import AzureCliCredential
+
+
+def print_code_interpreter_inputs(response: AgentRunResponse) -> None:
+    """Helper method to access code interpreter data."""
+
+    print("\nCode Interpreter Inputs during the run:")
+    if response.raw_representation is None:
+        return
+    for chunk in response.raw_representation:
+        if isinstance(chunk, ChatResponseUpdate) and isinstance(
+            chunk.raw_representation, RunStepDeltaCodeInterpreterDetailItemObject
+        ):
+            print(chunk.raw_representation.input, end="")
+    print("\n")
+
+
+async def main() -> None:
+    """Example showing how to use the HostedCodeInterpreterTool with Azure AI."""
+    print("=== Azure AI Agent with Code Interpreter Example ===")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentClient(async_credential=credential) as chat_client,
+    ):
+        agent = chat_client.create_agent(
+            name="CodingAgent",
+            instructions="You are a helpful assistant that can write and execute Python code to solve problems.",
+            tools=HostedCodeInterpreterTool(),
+        )
+        query = "Generate the factorial of 100 using python code, show the code and execute it."
+        print(f"User: {query}")
+        response = await AgentRunResponse.from_agent_response_generator(agent.run_stream(query))
+        print(f"Agent: {response}")
+        # To review the code interpreter outputs, you can access them from the response raw_representations, just uncomment the next line:
+        # print_code_interpreter_inputs(response)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_ai/azure_ai_with_existing_agent.py

@@ -0,0 +1,52 @@
+# 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 AzureAIAgentClient
+from azure.ai.projects.aio import AIProjectClient
+from azure.identity.aio 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 AI Chat Client with Existing Agent ===")
+
+    # Create the client
+    async with (
+        AzureCliCredential() as credential,
+        AIProjectClient(endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], credential=credential) as client,
+    ):
+        # Create an agent that will persist
+        created_agent = await client.agents.create_agent(
+            model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"], name="WeatherAgent"
+        )
+
+        try:
+            async with ChatAgent(
+                # passing in the client is optional here, so if you take the agent_id from the portal
+                # you can use it directly without the two lines above.
+                chat_client=AzureAIAgentClient(client=client, agent_id=created_agent.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 agent manually
+            await client.agents.delete_agent(created_agent.id)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_ai/azure_ai_with_explicit_settings.py

@@ -0,0 +1,47 @@
+# 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 AzureAIAgentClient
+from azure.identity.aio 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 AI Chat Client with Explicit Settings ===")
+
+    # Since no Agent ID is provided, the agent 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 (
+        AzureCliCredential() as credential,
+        ChatAgent(
+            chat_client=AzureAIAgentClient(
+                project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+                model_deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+                async_credential=credential,
+                agent_name="WeatherAgent",
+            ),
+            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_ai/azure_ai_with_function_tools.py

@@ -0,0 +1,133 @@
+# 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 AzureAIAgentClient
+from azure.identity.aio 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 (
+        AzureCliCredential() as credential,
+        ChatAgent(
+            chat_client=AzureAIAgentClient(async_credential=credential),
+            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 (
+        AzureCliCredential() as credential,
+        ChatAgent(
+            chat_client=AzureAIAgentClient(async_credential=credential),
+            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 (
+        AzureCliCredential() as credential,
+        ChatAgent(
+            chat_client=AzureAIAgentClient(async_credential=credential),
+            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 AI 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_ai/azure_ai_with_hosted_mcp.py

@@ -0,0 +1,65 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Any
+
+from agent_framework import AgentProtocol, AgentThread, HostedMCPTool
+from agent_framework.azure import AzureAIAgentClient
+from azure.identity.aio import AzureCliCredential
+
+
+async def handle_approvals_with_thread(query: str, agent: "AgentProtocol", thread: "AgentThread"):
+    """Here we let the thread deal with the previous responses, and we just rerun with the approval."""
+    from agent_framework import ChatMessage
+
+    result = await agent.run(query, thread=thread, store=True)
+    while len(result.user_input_requests) > 0:
+        new_input: list[Any] = []
+        for user_input_needed in result.user_input_requests:
+            print(
+                f"User Input Request for function from {agent.name}: {user_input_needed.function_call.name}"
+                f" with arguments: {user_input_needed.function_call.arguments}"
+            )
+            user_approval = input("Approve function call? (y/n): ")
+            new_input.append(
+                ChatMessage(
+                    role="user",
+                    contents=[user_input_needed.create_response(user_approval.lower() == "y")],
+                )
+            )
+        result = await agent.run(new_input, thread=thread, store=True)
+    return result
+
+
+async def main() -> None:
+    """Example showing Hosted MCP tools for a Azure AI Agent."""
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentClient(async_credential=credential) as chat_client,
+    ):
+        # enable azure-ai observability
+        await chat_client.setup_observability()
+        agent = chat_client.create_agent(
+            name="DocsAgent",
+            instructions="You are a helpful assistant that can help with microsoft documentation questions.",
+            tools=HostedMCPTool(
+                name="Microsoft Learn MCP",
+                url="https://learn.microsoft.com/api/mcp",
+            ),
+        )
+        thread = agent.get_new_thread()
+        # 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)
+        print(f"{agent.name}: {result1}\n")
+        print("\n=======================================\n")
+        # Second query
+        query2 = "What is Microsoft Semantic Kernel?"
+        print(f"User: {query2}")
+        result2 = await handle_approvals_with_thread(query2, agent, thread)
+        print(f"{agent.name}: {result2}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_ai/azure_ai_with_local_mcp.py

@@ -0,0 +1,81 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import ChatAgent, MCPStreamableHTTPTool
+from agent_framework.azure import AzureAIAgentClient
+from azure.identity.aio import AzureCliCredential
+
+
+async def mcp_tools_on_run_level() -> None:
+    """Example showing MCP tools defined when running the agent."""
+    print("=== Tools Defined on Run Level ===")
+
+    # Tools are provided when running the agent
+    # This means we have to ensure we connect to the MCP server before running the agent
+    # and pass the tools to the run method.
+    async with (
+        AzureCliCredential() as credential,
+        MCPStreamableHTTPTool(
+            name="Microsoft Learn MCP",
+            url="https://learn.microsoft.com/api/mcp",
+        ) as mcp_server,
+        ChatAgent(
+            chat_client=AzureAIAgentClient(async_credential=credential),
+            name="DocsAgent",
+            instructions="You are a helpful assistant that can help with microsoft documentation questions.",
+        ) as agent,
+    ):
+        # First query
+        query1 = "How to create an Azure storage account using az cli?"
+        print(f"User: {query1}")
+        result1 = await agent.run(query1, tools=mcp_server)
+        print(f"{agent.name}: {result1}\n")
+        print("\n=======================================\n")
+        # Second query
+        query2 = "What is Microsoft Semantic Kernel?"
+        print(f"User: {query2}")
+        result2 = await agent.run(query2, tools=mcp_server)
+        print(f"{agent.name}: {result2}\n")
+
+
+async def mcp_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
+    # The agent will connect to the MCP server through its context manager.
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentClient(async_credential=credential).create_agent(
+            name="DocsAgent",
+            instructions="You are a helpful assistant that can help with microsoft documentation questions.",
+            tools=MCPStreamableHTTPTool(  # Tools defined at agent creation
+                name="Microsoft Learn MCP",
+                url="https://learn.microsoft.com/api/mcp",
+            ),
+        ) as agent,
+    ):
+        # First query
+        query1 = "How to create an Azure storage account using az cli?"
+        print(f"User: {query1}")
+        result1 = await agent.run(query1)
+        print(f"{agent.name}: {result1}\n")
+        print("\n=======================================\n")
+        # Second query
+        query2 = "What is Microsoft Semantic Kernel?"
+        print(f"User: {query2}")
+        result2 = await agent.run(query2)
+        print(f"{agent.name}: {result2}\n")
+
+
+async def main() -> None:
+    print("=== Azure AI Chat Client Agent with MCP Tools Examples ===\n")
+
+    await mcp_tools_on_agent_level()
+    await mcp_tools_on_run_level()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_ai/azure_ai_with_multiple_tools.py

@@ -0,0 +1,82 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from datetime import datetime, timezone
+from typing import Any
+
+from agent_framework import (
+    AgentProtocol,
+    AgentThread,
+    HostedMCPTool,
+    HostedWebSearchTool,
+)
+from agent_framework.azure import AzureAIAgentClient
+from azure.identity.aio import AzureCliCredential
+
+
+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 handle_approvals_with_thread(query: str, agent: "AgentProtocol", thread: "AgentThread"):
+    """Here we let the thread deal with the previous responses, and we just rerun with the approval."""
+    from agent_framework import ChatMessage
+
+    result = await agent.run(query, thread=thread, store=True)
+    while len(result.user_input_requests) > 0:
+        new_input: list[Any] = []
+        for user_input_needed in result.user_input_requests:
+            print(
+                f"User Input Request for function from {agent.name}: {user_input_needed.function_call.name}"
+                f" with arguments: {user_input_needed.function_call.arguments}"
+            )
+            user_approval = input("Approve function call? (y/n): ")
+            new_input.append(
+                ChatMessage(
+                    role="user",
+                    contents=[user_input_needed.create_response(user_approval.lower() == "y")],
+                )
+            )
+        result = await agent.run(new_input, thread=thread, store=True)
+    return result
+
+
+async def main() -> None:
+    """Example showing Hosted MCP tools for a Azure AI Agent."""
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentClient(async_credential=credential) as chat_client,
+    ):
+        # enable azure-ai observability
+        await chat_client.setup_observability()
+        agent = chat_client.create_agent(
+            name="DocsAgent",
+            instructions="You are a helpful assistant that can help with microsoft documentation questions.",
+            tools=[
+                HostedMCPTool(
+                    name="Microsoft Learn MCP",
+                    url="https://learn.microsoft.com/api/mcp",
+                ),
+                # needs BING_CONNECTION_ID set in the env
+                HostedWebSearchTool(count=5),
+                get_time,
+            ],
+        )
+        thread = agent.get_new_thread()
+        # 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)
+        print(f"{agent.name}: {result1}\n")
+        print("\n=======================================\n")
+        # Second query
+        query2 = "What is Microsoft Semantic Kernel 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)
+        print(f"{agent.name}: {result2}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_ai/azure_ai_with_thread.py

@@ -0,0 +1,147 @@
+# 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 AzureAIAgentClient
+from azure.identity.aio 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 (
+        AzureCliCredential() as credential,
+        ChatAgent(
+            chat_client=AzureAIAgentClient(async_credential=credential),
+            instructions="You are a helpful weather agent.",
+            tools=get_weather,
+        ) as agent,
+    ):
+        # First conversation - no thread 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_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")
+
+
+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 (
+        AzureCliCredential() as credential,
+        ChatAgent(
+            chat_client=AzureAIAgentClient(async_credential=credential),
+            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
+        first_query = "What's the weather like in Tokyo?"
+        print(f"User: {first_query}")
+        first_result = await agent.run(first_query, thread=thread)
+        print(f"Agent: {first_result.text}")
+
+        # Second conversation using the same thread - maintains context
+        second_query = "How about London?"
+        print(f"\nUser: {second_query}")
+        second_result = await agent.run(second_query, thread=thread)
+        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)
+        print(f"Agent: {third_result.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 (
+        AzureCliCredential() as credential,
+        ChatAgent(
+            chat_client=AzureAIAgentClient(async_credential=credential),
+            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()
+        first_query = "What's the weather in Paris?"
+        print(f"User: {first_query}")
+        first_result = await agent.run(first_query, thread=thread)
+        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}")
+
+    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 (
+            AzureCliCredential() as credential,
+            ChatAgent(
+                chat_client=AzureAIAgentClient(thread_id=existing_thread_id, async_credential=credential),
+                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)
+
+            second_query = "What was the last city I asked about?"
+            print(f"User: {second_query}")
+            second_result = await agent.run(second_query, thread=thread)
+            print(f"Agent: {second_result.text}")
+            print("Note: The agent continues the conversation from the previous thread.\n")
+
+
+async def main() -> None:
+    print("=== Azure AI 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())