test

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

@@ -0,0 +1,95 @@
+# Azure AI Agent Examples
+
+This folder contains examples demonstrating different ways to create and use agents with the Azure AI client from the `agent_framework.azure` package. These examples use the `AzureAIClient` with the `azure-ai-projects` 2.x (V2) API surface (see [changelog](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-projects/CHANGELOG.md#200b1-2025-11-11)). For V1 (`azure-ai-agents` 1.x) samples using `AzureAIAgentClient`, see the [Azure AI V1 examples folder](../azure_ai_agent/).
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| [`azure_ai_basic.py`](azure_ai_basic.py) | The simplest way to create an agent using `AzureAIProjectAgentProvider`. Demonstrates both streaming and non-streaming responses with function tools. Shows automatic agent creation and basic weather functionality. |
+| [`azure_ai_provider_methods.py`](azure_ai_provider_methods.py) | Comprehensive guide to `AzureAIProjectAgentProvider` methods: `create_agent()` for creating new agents, `get_agent()` for retrieving existing agents (by name, reference, or details), and `as_agent()` for wrapping SDK objects without HTTP calls. |
+| [`azure_ai_use_latest_version.py`](azure_ai_use_latest_version.py) | Demonstrates how to reuse the latest version of an existing agent instead of creating a new agent version on each instantiation by using `provider.get_agent()` to retrieve the latest version. |
+| [`azure_ai_with_agent_as_tool.py`](azure_ai_with_agent_as_tool.py) | Shows how to use the agent-as-tool pattern with Azure AI agents, where one agent delegates work to specialized sub-agents wrapped as tools using `as_tool()`. Demonstrates hierarchical agent architectures. |
+| [`azure_ai_with_agent_to_agent.py`](azure_ai_with_agent_to_agent.py) | Shows how to use Agent-to-Agent (A2A) capabilities with Azure AI agents to enable communication with other agents using the A2A protocol. Requires an A2A connection configured in your Azure AI project. |
+| [`azure_ai_with_azure_ai_search.py`](azure_ai_with_azure_ai_search.py) | Shows how to use Azure AI Search with Azure AI agents to search through indexed data and answer user questions with proper citations. Requires an Azure AI Search connection and index configured in your Azure AI project. |
+| [`azure_ai_with_bing_grounding.py`](azure_ai_with_bing_grounding.py) | Shows how to use Bing Grounding search with Azure AI agents to search the web for current information and provide grounded responses with citations. Requires a Bing connection configured in your Azure AI project. |
+| [`azure_ai_with_bing_custom_search.py`](azure_ai_with_bing_custom_search.py) | Shows how to use Bing Custom Search with Azure AI agents to search custom search instances and provide responses with relevant results. Requires a Bing Custom Search connection and instance configured in your Azure AI project. |
+| [`azure_ai_with_browser_automation.py`](azure_ai_with_browser_automation.py) | Shows how to use Browser Automation with Azure AI agents to perform automated web browsing tasks and provide responses based on web interactions. Requires a Browser Automation connection configured in your Azure AI project. |
+| [`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 for mathematical problem solving and data analysis. |
+| [`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_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_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 the `HostedFileSearchTool` with Azure AI agents to upload files, create vector stores, and enable agents to search through uploaded documents to answer user questions. |
+| [`azure_ai_with_hosted_mcp.py`](azure_ai_with_hosted_mcp.py) | Shows how to integrate hosted Model Context Protocol (MCP) tools with Azure AI Agent. |
+| [`azure_ai_with_local_mcp.py`](azure_ai_with_local_mcp.py) | Shows how to integrate local Model Context Protocol (MCP) tools with Azure AI agents. |
+| [`azure_ai_with_response_format.py`](azure_ai_with_response_format.py) | Shows how to use structured outputs (response format) with Azure AI agents using Pydantic models to enforce specific response schemas. |
+| [`azure_ai_with_runtime_json_schema.py`](azure_ai_with_runtime_json_schema.py) | Shows how to use structured outputs (response format) with Azure AI agents using a JSON schema to enforce specific response schemas. |
+| [`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_image_generation.py`](azure_ai_with_image_generation.py) | Shows how to use the `ImageGenTool` 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. |
+| [`azure_ai_with_openapi.py`](azure_ai_with_openapi.py) | Shows how to integrate OpenAPI specifications with Azure AI agents using dictionary-based tool configuration. Demonstrates using external REST APIs for dynamic data lookup. |
+| [`azure_ai_with_reasoning.py`](azure_ai_with_reasoning.py) | Shows how to enable reasoning for a model that supports it. |
+| [`azure_ai_with_web_search.py`](azure_ai_with_web_search.py) | Shows how to use the `HostedWebSearchTool` with Azure AI agents to perform web searches and retrieve up-to-date information from the internet. |
+
+## Environment Variables
+
+Before running the examples, you need to set up your environment variables. You can do this in one of two ways:
+
+### Option 1: Using a .env file (Recommended)
+
+1. Copy the `.env.example` file from the `python` directory to create a `.env` file:
+
+   ```bash
+   cp ../../../../.env.example ../../../../.env
+   ```
+
+2. Edit the `.env` file and add your values:
+
+   ```env
+   AZURE_AI_PROJECT_ENDPOINT="your-project-endpoint"
+   AZURE_AI_MODEL_DEPLOYMENT_NAME="your-model-deployment-name"
+   ```
+
+### Option 2: Using environment variables directly
+
+Set the environment variables in your shell:
+
+```bash
+export AZURE_AI_PROJECT_ENDPOINT="your-project-endpoint"
+export AZURE_AI_MODEL_DEPLOYMENT_NAME="your-model-deployment-name"
+```
+
+### Required Variables
+
+- `AZURE_AI_PROJECT_ENDPOINT`: Your Azure AI project endpoint (required for all examples)
+- `AZURE_AI_MODEL_DEPLOYMENT_NAME`: The name of your model deployment (required for all examples)
+
+## Authentication
+
+All examples use `AzureCliCredential` for authentication by default. Before running the examples:
+
+1. Install the Azure CLI
+2. Run `az login` to authenticate with your Azure account
+3. Ensure you have appropriate permissions to the Azure AI project
+
+Alternatively, you can replace `AzureCliCredential` with other authentication options like `DefaultAzureCredential` or environment-based credentials.
+
+## Running the Examples
+
+Each example can be run independently. Navigate to this directory and run any example:
+
+```bash
+python azure_ai_basic.py
+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.

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

@@ -0,0 +1,82 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from random import randint
+from typing import Annotated
+
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.identity.aio import AzureCliCredential
+from pydantic import Field
+
+"""
+Azure AI Agent Basic Example
+
+This sample demonstrates basic usage of AzureAIProjectAgentProvider.
+Shows both streaming and non-streaming responses with function tools.
+"""
+
+
+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.
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="BasicWeatherAgent",
+            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"Agent: {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.
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="BasicWeatherAgent",
+            instructions="You are a helpful weather agent.",
+            tools=get_weather,
+        )
+
+        query = "What's the weather like in Tokyo?"
+        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_provider_methods.py

@@ -0,0 +1,249 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from random import randint
+from typing import Annotated
+
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.ai.projects.aio import AIProjectClient
+from azure.ai.projects.models import AgentReference, PromptAgentDefinition
+from azure.identity.aio import AzureCliCredential
+from pydantic import Field
+
+"""
+Azure AI Project Agent Provider Methods Example
+
+This sample demonstrates the three main methods of AzureAIProjectAgentProvider:
+1. create_agent() - Create a new agent on the Azure AI service
+2. get_agent() - Retrieve an existing agent from the service
+3. as_agent() - Wrap an SDK agent version object without making HTTP calls
+
+It also shows how to use a single provider instance to spawn multiple agents
+with different configurations, which is efficient for multi-agent scenarios.
+
+Each method returns a ChatAgent that can be used for conversations.
+"""
+
+
+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 create_agent_example() -> None:
+    """Example of using provider.create_agent() to create a new agent.
+
+    This method creates a new agent version on the Azure AI service and returns
+    a ChatAgent. Use this when you want to create a fresh agent with
+    specific configuration.
+    """
+    print("=== provider.create_agent() Example ===")
+
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        # Create a new agent with custom configuration
+        agent = await provider.create_agent(
+            name="WeatherAssistant",
+            instructions="You are a helpful weather assistant. Always be concise.",
+            description="An agent that provides weather information.",
+            tools=get_weather,
+        )
+
+        print(f"Created agent: {agent.name}")
+        print(f"Agent ID: {agent.id}")
+
+        query = "What's the weather in Paris?"
+        print(f"User: {query}")
+        result = await agent.run(query)
+        print(f"Agent: {result}\n")
+
+
+async def get_agent_by_name_example() -> None:
+    """Example of using provider.get_agent(name=...) to retrieve an agent by name.
+
+    This method fetches the latest version of an existing agent from the service.
+    Use this when you know the agent name and want to use the most recent version.
+    """
+    print("=== provider.get_agent(name=...) Example ===")
+
+    async with (
+        AzureCliCredential() as credential,
+        AIProjectClient(endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], credential=credential) as project_client,
+    ):
+        # First, create an agent using the SDK directly
+        created_agent = await project_client.agents.create_version(
+            agent_name="TestAgentByName",
+            description="Test agent for get_agent by name example.",
+            definition=PromptAgentDefinition(
+                model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+                instructions="You are a helpful assistant. End each response with '- Your Assistant'.",
+            ),
+        )
+
+        try:
+            # Get the agent using the provider by name (fetches latest version)
+            provider = AzureAIProjectAgentProvider(project_client=project_client)
+            agent = await provider.get_agent(name=created_agent.name)
+
+            print(f"Retrieved agent: {agent.name}")
+
+            query = "Hello!"
+            print(f"User: {query}")
+            result = await agent.run(query)
+            print(f"Agent: {result}\n")
+        finally:
+            # Clean up the agent
+            await project_client.agents.delete_version(
+                agent_name=created_agent.name, agent_version=created_agent.version
+            )
+
+
+async def get_agent_by_reference_example() -> None:
+    """Example of using provider.get_agent(reference=...) to retrieve a specific agent version.
+
+    This method fetches a specific version of an agent using an AgentReference.
+    Use this when you need to use a particular version of an agent.
+    """
+    print("=== provider.get_agent(reference=...) Example ===")
+
+    async with (
+        AzureCliCredential() as credential,
+        AIProjectClient(endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], credential=credential) as project_client,
+    ):
+        # First, create an agent using the SDK directly
+        created_agent = await project_client.agents.create_version(
+            agent_name="TestAgentByReference",
+            description="Test agent for get_agent by reference example.",
+            definition=PromptAgentDefinition(
+                model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+                instructions="You are a helpful assistant. Always respond in uppercase.",
+            ),
+        )
+
+        try:
+            # Get the agent using an AgentReference with specific version
+            provider = AzureAIProjectAgentProvider(project_client=project_client)
+            reference = AgentReference(name=created_agent.name, version=created_agent.version)
+            agent = await provider.get_agent(reference=reference)
+
+            print(f"Retrieved agent: {agent.name} (version via reference)")
+
+            query = "Say hello"
+            print(f"User: {query}")
+            result = await agent.run(query)
+            print(f"Agent: {result}\n")
+        finally:
+            # Clean up the agent
+            await project_client.agents.delete_version(
+                agent_name=created_agent.name, agent_version=created_agent.version
+            )
+
+
+async def multiple_agents_example() -> None:
+    """Example of using a single provider to spawn multiple agents.
+
+    A single provider instance can create multiple agents with different
+    configurations.
+    """
+    print("=== Multiple Agents from Single Provider Example ===")
+
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        # Create multiple specialized agents from the same provider
+        weather_agent = await provider.create_agent(
+            name="WeatherExpert",
+            instructions="You are a weather expert. Provide brief weather information.",
+            tools=get_weather,
+        )
+
+        translator_agent = await provider.create_agent(
+            name="Translator",
+            instructions="You are a translator. Translate any text to French. Only output the translation.",
+        )
+
+        poet_agent = await provider.create_agent(
+            name="Poet",
+            instructions="You are a poet. Respond to everything with a short haiku.",
+        )
+
+        print(f"Created agents: {weather_agent.name}, {translator_agent.name}, {poet_agent.name}\n")
+
+        # Use each agent for its specialty
+        weather_query = "What's the weather in London?"
+        print(f"User to WeatherExpert: {weather_query}")
+        weather_result = await weather_agent.run(weather_query)
+        print(f"WeatherExpert: {weather_result}\n")
+
+        translate_query = "Hello, how are you today?"
+        print(f"User to Translator: {translate_query}")
+        translate_result = await translator_agent.run(translate_query)
+        print(f"Translator: {translate_result}\n")
+
+        poet_query = "Tell me about the morning sun"
+        print(f"User to Poet: {poet_query}")
+        poet_result = await poet_agent.run(poet_query)
+        print(f"Poet: {poet_result}\n")
+
+
+async def as_agent_example() -> None:
+    """Example of using provider.as_agent() to wrap an SDK object without HTTP calls.
+
+    This method wraps an existing AgentVersionDetails into a ChatAgent without
+    making additional HTTP calls. Use this when you already have the full
+    AgentVersionDetails from a previous SDK operation.
+    """
+    print("=== provider.as_agent() Example ===")
+
+    async with (
+        AzureCliCredential() as credential,
+        AIProjectClient(endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], credential=credential) as project_client,
+    ):
+        # Create an agent using the SDK directly - this returns AgentVersionDetails
+        agent_version_details = await project_client.agents.create_version(
+            agent_name="TestAgentAsAgent",
+            description="Test agent for as_agent example.",
+            definition=PromptAgentDefinition(
+                model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+                instructions="You are a helpful assistant. Keep responses under 20 words.",
+            ),
+        )
+
+        try:
+            # Wrap the SDK object directly without any HTTP calls
+            provider = AzureAIProjectAgentProvider(project_client=project_client)
+            agent = provider.as_agent(agent_version_details)
+
+            print(f"Wrapped agent: {agent.name} (no HTTP call needed)")
+            print(f"Agent version: {agent_version_details.version}")
+
+            query = "What can you do?"
+            print(f"User: {query}")
+            result = await agent.run(query)
+            print(f"Agent: {result}\n")
+        finally:
+            # Clean up the agent
+            await project_client.agents.delete_version(
+                agent_name=agent_version_details.name, agent_version=agent_version_details.version
+            )
+
+
+async def main() -> None:
+    print("=== Azure AI Project Agent Provider Methods Example ===\n")
+
+    await create_agent_example()
+    await get_agent_by_name_example()
+    await get_agent_by_reference_example()
+    await as_agent_example()
+    await multiple_agents_example()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,64 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from random import randint
+from typing import Annotated
+
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.identity.aio import AzureCliCredential
+from pydantic import Field
+
+"""
+Azure AI Agent Latest Version Example
+
+This sample demonstrates how to reuse the latest version of an existing agent
+instead of creating a new agent version on each instantiation. The first call creates a new agent,
+while subsequent calls with `get_agent()` reuse the latest agent version.
+"""
+
+
+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:
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        # First call creates a new agent
+        agent = await provider.create_agent(
+            name="MyWeatherAgent",
+            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"Agent: {result}\n")
+
+        # Second call retrieves the existing agent (latest version) instead of creating a new one
+        # This is useful when you want to reuse an agent that was created earlier
+        agent2 = await provider.get_agent(
+            name="MyWeatherAgent",
+            tools=get_weather,  # Tools must be provided for function tools
+        )
+
+        query = "What's the weather like in Tokyo?"
+        print(f"User: {query}")
+        result = await agent2.run(query)
+        print(f"Agent: {result}\n")
+
+        print(f"First agent ID with version: {agent.id}")
+        print(f"Second agent ID with version: {agent2.id}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,70 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from collections.abc import Awaitable, Callable
+
+from agent_framework import FunctionInvocationContext
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent-as-Tool Example
+
+Demonstrates hierarchical agent architectures where one agent delegates
+work to specialized sub-agents wrapped as tools using as_tool().
+
+This pattern is useful when you want a coordinator agent to orchestrate
+multiple specialized agents, each focusing on specific tasks.
+"""
+
+
+async def logging_middleware(
+    context: FunctionInvocationContext,
+    next: Callable[[FunctionInvocationContext], Awaitable[None]],
+) -> None:
+    """Middleware that logs tool invocations to show the delegation flow."""
+    print(f"[Calling tool: {context.function.name}]")
+    print(f"[Request: {context.arguments}]")
+
+    await next(context)
+
+    print(f"[Response: {context.result}]")
+
+
+async def main() -> None:
+    print("=== Azure AI Agent-as-Tool Pattern ===")
+
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        # Create a specialized writer agent
+        writer = await provider.create_agent(
+            name="WriterAgent",
+            instructions="You are a creative writer. Write short, engaging content.",
+        )
+
+        # Convert writer agent to a tool using as_tool()
+        writer_tool = writer.as_tool(
+            name="creative_writer",
+            description="Generate creative content like taglines, slogans, or short copy",
+            arg_name="request",
+            arg_description="What to write",
+        )
+
+        # Create coordinator agent with writer as a tool
+        coordinator = await provider.create_agent(
+            name="CoordinatorAgent",
+            instructions="You coordinate with specialized agents. Delegate writing tasks to the creative_writer tool.",
+            tools=[writer_tool],
+            middleware=[logging_middleware],
+        )
+
+        query = "Create a tagline for a coffee shop"
+        print(f"User: {query}")
+        result = await coordinator.run(query)
+        print(f"Coordinator: {result}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,53 @@
+# Copyright (c) Microsoft. All rights reserved.
+import asyncio
+import os
+
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent with Agent-to-Agent (A2A) Example
+
+This sample demonstrates usage of AzureAIProjectAgentProvider with Agent-to-Agent (A2A) capabilities
+to enable communication with other agents using the A2A protocol.
+
+Prerequisites:
+1. Set AZURE_AI_PROJECT_ENDPOINT and AZURE_AI_MODEL_DEPLOYMENT_NAME environment variables.
+2. Ensure you have an A2A connection configured in your Azure AI project
+   and set A2A_PROJECT_CONNECTION_ID environment variable.
+3. (Optional) A2A_ENDPOINT - If the connection is missing target (e.g., "Custom keys" type),
+   set the A2A endpoint URL directly.
+"""
+
+
+async def main() -> None:
+    # Configure A2A tool with connection ID
+    a2a_tool = {
+        "type": "a2a_preview",
+        "project_connection_id": os.environ["A2A_PROJECT_CONNECTION_ID"],
+    }
+
+    # If the connection is missing a target, we need to set the A2A endpoint URL
+    if os.environ.get("A2A_ENDPOINT"):
+        a2a_tool["base_url"] = os.environ["A2A_ENDPOINT"]
+
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="MyA2AAgent",
+            instructions="""You are a helpful assistant that can communicate with other agents.
+            Use the A2A tool when you need to interact with other agents to complete tasks
+            or gather information from specialized agents.""",
+            tools=a2a_tool,
+        )
+
+        query = "What can the secondary agent do?"
+        print(f"User: {query}")
+        result = await agent.run(query)
+        print(f"Result: {result}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,39 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+
+from agent_framework import ChatAgent
+from agent_framework.azure import AzureAIClient
+from azure.ai.projects.aio import AIProjectClient
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent with Application Endpoint Example
+
+This sample demonstrates working with pre-existing Azure AI Agents by providing
+application endpoint instead of project endpoint.
+"""
+
+
+async def main() -> None:
+    # Create the client
+    async with (
+        AzureCliCredential() as credential,
+        # Endpoint here should be application endpoint with format:
+        # /api/projects/<project-name>/applications/<application-name>/protocols
+        AIProjectClient(endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], credential=credential) as project_client,
+        ChatAgent(
+            chat_client=AzureAIClient(
+                project_client=project_client,
+            ),
+        ) as agent,
+    ):
+        query = "How are you?"
+        print(f"User: {query}")
+        result = await agent.run(query)
+        print(f"Agent: {result}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,52 @@
+# Copyright (c) Microsoft. All rights reserved.
+import asyncio
+import os
+
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent with Azure AI Search Example
+
+This sample demonstrates usage of AzureAIProjectAgentProvider with Azure AI Search
+to search through indexed data and answer user questions about it.
+
+Prerequisites:
+1. Set AZURE_AI_PROJECT_ENDPOINT and AZURE_AI_MODEL_DEPLOYMENT_NAME environment variables.
+2. Ensure you have an Azure AI Search connection configured in your Azure AI project
+    and set AI_SEARCH_PROJECT_CONNECTION_ID and AI_SEARCH_INDEX_NAME environment variable.
+"""
+
+
+async def main() -> None:
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="MySearchAgent",
+            instructions="""You are a helpful assistant. You must always provide citations for
+            answers using the tool and render them as: `[message_idx:search_idx†source]`.""",
+            tools={
+                "type": "azure_ai_search",
+                "azure_ai_search": {
+                    "indexes": [
+                        {
+                            "project_connection_id": os.environ["AI_SEARCH_PROJECT_CONNECTION_ID"],
+                            "index_name": os.environ["AI_SEARCH_INDEX_NAME"],
+                            # For query_type=vector, ensure your index has a field with vectorized data.
+                            "query_type": "simple",
+                        }
+                    ]
+                },
+            },
+        )
+
+        query = "Tell me about insurance options"
+        print(f"User: {query}")
+        result = await agent.run(query)
+        print(f"Result: {result}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,50 @@
+# Copyright (c) Microsoft. All rights reserved.
+import asyncio
+import os
+
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent with Bing Custom Search Example
+
+This sample demonstrates usage of AzureAIProjectAgentProvider with Bing Custom Search
+to search custom search instances and provide responses with relevant results.
+
+Prerequisites:
+1. Set AZURE_AI_PROJECT_ENDPOINT and AZURE_AI_MODEL_DEPLOYMENT_NAME environment variables.
+2. Ensure you have a Bing Custom Search connection configured in your Azure AI project
+   and set BING_CUSTOM_SEARCH_PROJECT_CONNECTION_ID and BING_CUSTOM_SEARCH_INSTANCE_NAME environment variables.
+"""
+
+
+async def main() -> None:
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="MyCustomSearchAgent",
+            instructions="""You are a helpful agent that can use Bing Custom Search tools to assist users.
+            Use the available Bing Custom Search tools to answer questions and perform tasks.""",
+            tools={
+                "type": "bing_custom_search_preview",
+                "bing_custom_search_preview": {
+                    "search_configurations": [
+                        {
+                            "project_connection_id": os.environ["BING_CUSTOM_SEARCH_PROJECT_CONNECTION_ID"],
+                            "instance_name": os.environ["BING_CUSTOM_SEARCH_INSTANCE_NAME"],
+                        }
+                    ]
+                },
+            },
+        )
+
+        query = "Tell me more about foundry agent service"
+        print(f"User: {query}")
+        result = await agent.run(query)
+        print(f"Result: {result}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,56 @@
+# Copyright (c) Microsoft. All rights reserved.
+import asyncio
+import os
+
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent with Bing Grounding Example
+
+This sample demonstrates usage of AzureAIProjectAgentProvider with Bing Grounding
+to search the web for current information and provide grounded responses.
+
+Prerequisites:
+1. Set AZURE_AI_PROJECT_ENDPOINT and AZURE_AI_MODEL_DEPLOYMENT_NAME environment variables.
+2. Ensure you have a Bing connection configured in your Azure AI project
+   and set BING_PROJECT_CONNECTION_ID environment variable.
+
+To get your Bing connection ID:
+- Go to Azure AI Foundry portal (https://ai.azure.com)
+- Navigate to your project's "Connected resources" section
+- Add a new connection for "Grounding with Bing Search"
+- Copy the connection ID and set it as the BING_PROJECT_CONNECTION_ID environment variable
+"""
+
+
+async def main() -> None:
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="MyBingGroundingAgent",
+            instructions="""You are a helpful assistant that can search the web for current information.
+            Use the Bing search tool to find up-to-date information and provide accurate, well-sourced answers.
+            Always cite your sources when possible.""",
+            tools={
+                "type": "bing_grounding",
+                "bing_grounding": {
+                    "search_configurations": [
+                        {
+                            "project_connection_id": os.environ["BING_PROJECT_CONNECTION_ID"],
+                        }
+                    ]
+                },
+            },
+        )
+
+        query = "What is today's date and weather in Seattle?"
+        print(f"User: {query}")
+        result = await agent.run(query)
+        print(f"Result: {result}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,54 @@
+# Copyright (c) Microsoft. All rights reserved.
+import asyncio
+import os
+
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent with Browser Automation Example
+
+This sample demonstrates usage of AzureAIProjectAgentProvider with Browser Automation
+to perform automated web browsing tasks and provide responses based on web interactions.
+
+Prerequisites:
+1. Set AZURE_AI_PROJECT_ENDPOINT and AZURE_AI_MODEL_DEPLOYMENT_NAME environment variables.
+2. Ensure you have a Browser Automation connection configured in your Azure AI project
+   and set BROWSER_AUTOMATION_PROJECT_CONNECTION_ID environment variable.
+"""
+
+
+async def main() -> None:
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="MyBrowserAutomationAgent",
+            instructions="""You are an Agent helping with browser automation tasks.
+            You can answer questions, provide information, and assist with various tasks
+            related to web browsing using the Browser Automation tool available to you.""",
+            tools={
+                "type": "browser_automation_preview",
+                "browser_automation_preview": {
+                    "connection": {
+                        "project_connection_id": os.environ["BROWSER_AUTOMATION_PROJECT_CONNECTION_ID"],
+                    }
+                },
+            },
+        )
+
+        query = """Your goal is to report the percent of Microsoft year-to-date stock price change.
+        To do that, go to the website finance.yahoo.com.
+        At the top of the page, you will find a search bar.
+        Enter the value 'MSFT', to get information about the Microsoft stock price.
+        At the top of the resulting page you will see a default chart of Microsoft stock price.
+        Click on 'YTD' at the top of that chart, and report the percent value that shows up just below it."""
+
+        print(f"User: {query}")
+        result = await agent.run(query)
+        print(f"Result: {result}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,58 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import ChatResponse, HostedCodeInterpreterTool
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.identity.aio import AzureCliCredential
+from openai.types.responses.response import Response as OpenAIResponse
+from openai.types.responses.response_code_interpreter_tool_call import ResponseCodeInterpreterToolCall
+
+"""
+Azure AI Agent Code Interpreter Example
+
+This sample demonstrates using HostedCodeInterpreterTool with AzureAIProjectAgentProvider
+for Python code execution and mathematical problem solving.
+"""
+
+
+async def main() -> None:
+    """Example showing how to use the HostedCodeInterpreterTool with AzureAIProjectAgentProvider."""
+
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="MyCodeInterpreterAgent",
+            instructions="You are a helpful assistant that can write and execute Python code to solve problems.",
+            tools=HostedCodeInterpreterTool(),
+        )
+
+        query = "Use code to get 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
+        ):
+            # Find the first ResponseCodeInterpreterToolCall item
+            code_interpreter_item = next(
+                (
+                    item
+                    for item in result.raw_representation.raw_representation.output
+                    if isinstance(item, ResponseCodeInterpreterToolCall)
+                ),
+                None,
+            )
+
+            if code_interpreter_item is not None:
+                generated_code = code_interpreter_item.code
+                print(f"Generated code:\n{generated_code}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,219 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import tempfile
+from pathlib import Path
+
+from agent_framework import (
+    AgentResponseUpdate,
+    ChatAgent,
+    CitationAnnotation,
+    HostedCodeInterpreterTool,
+    HostedFileContent,
+    TextContent,
+)
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI V2 Code Interpreter File Download Sample
+
+This sample demonstrates how the AzureAIProjectAgentProvider handles file annotations
+when code interpreter generates text files. It shows:
+1. How to extract file IDs and container IDs from annotations
+2. How to download container files using the OpenAI containers API
+3. How to save downloaded files locally
+
+Note: Code interpreter generates files in containers, which require both
+file_id and container_id to download via client.containers.files.content.retrieve().
+"""
+
+QUERY = (
+    "Write a simple Python script that creates a text file called 'sample.txt' containing "
+    "'Hello from the code interpreter!' and save it to disk."
+)
+
+
+async def download_container_files(
+    file_contents: list[CitationAnnotation | HostedFileContent], agent: ChatAgent
+) -> list[Path]:
+    """Download container files using the OpenAI containers API.
+
+    Code interpreter generates files in containers, which require both file_id
+    and container_id to download. The container_id is stored in additional_properties.
+
+    This function works for both streaming (HostedFileContent) and non-streaming
+    (CitationAnnotation) responses.
+
+    Args:
+        file_contents: List of CitationAnnotation or HostedFileContent objects
+                      containing file_id and container_id.
+        agent: The ChatAgent instance with access to the AzureAIClient.
+
+    Returns:
+        List of Path objects for successfully downloaded files.
+    """
+    if not file_contents:
+        return []
+
+    # Create output directory in system temp folder
+    temp_dir = Path(tempfile.gettempdir())
+    output_dir = temp_dir / "agent_framework_downloads"
+    output_dir.mkdir(exist_ok=True)
+
+    print(f"\nDownloading {len(file_contents)} container file(s) to {output_dir.absolute()}...")
+
+    # Access the OpenAI client from AzureAIClient
+    openai_client = agent.chat_client.client
+
+    downloaded_files: list[Path] = []
+
+    for content in file_contents:
+        file_id = content.file_id
+
+        # Extract container_id from additional_properties
+        if not content.additional_properties or "container_id" not in content.additional_properties:
+            print(f"  File {file_id}: ✗ Missing container_id")
+            continue
+
+        container_id = content.additional_properties["container_id"]
+
+        # Extract filename based on content type
+        if isinstance(content, CitationAnnotation):
+            filename = content.url or f"{file_id}.txt"
+            # Extract filename from sandbox URL if present (e.g., sandbox:/mnt/data/sample.txt)
+            if filename.startswith("sandbox:"):
+                filename = filename.split("/")[-1]
+        else:  # HostedFileContent
+            filename = content.additional_properties.get("filename") or f"{file_id}.txt"
+
+        output_path = output_dir / filename
+
+        try:
+            # Download using containers API
+            print(f"  Downloading {filename}...", end="", flush=True)
+            file_content = await openai_client.containers.files.content.retrieve(
+                file_id=file_id,
+                container_id=container_id,
+            )
+
+            # file_content is HttpxBinaryResponseContent, read it
+            content_bytes = file_content.read()
+
+            # Save to disk
+            output_path.write_bytes(content_bytes)
+            file_size = output_path.stat().st_size
+            print(f"({file_size} bytes)")
+
+            downloaded_files.append(output_path)
+
+        except Exception as e:
+            print(f"Failed: {e}")
+
+    return downloaded_files
+
+
+async def non_streaming_example() -> None:
+    """Example of downloading files from non-streaming response using CitationAnnotation."""
+    print("=== Non-Streaming Response Example ===")
+
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="V2CodeInterpreterFileAgent",
+            instructions="You are a helpful assistant that can write and execute Python code to create files.",
+            tools=HostedCodeInterpreterTool(),
+        )
+
+        print(f"User: {QUERY}\n")
+
+        result = await agent.run(QUERY)
+        print(f"Agent: {result.text}\n")
+
+        # Check for annotations in the response
+        annotations_found: list[CitationAnnotation] = []
+        # AgentResponse has messages property, which contains ChatMessage objects
+        for message in result.messages:
+            for content in message.contents:
+                if isinstance(content, TextContent) and content.annotations:
+                    for annotation in content.annotations:
+                        if isinstance(annotation, CitationAnnotation) and annotation.file_id:
+                            annotations_found.append(annotation)
+                            print(f"Found file annotation: file_id={annotation.file_id}")
+                            if annotation.additional_properties and "container_id" in annotation.additional_properties:
+                                print(f"  container_id={annotation.additional_properties['container_id']}")
+
+        if annotations_found:
+            print(f"SUCCESS: Found {len(annotations_found)} file annotation(s)")
+
+            # Download the container files
+            downloaded_paths = await download_container_files(annotations_found, agent)
+
+            if downloaded_paths:
+                print("\nDownloaded files available at:")
+                for path in downloaded_paths:
+                    print(f"  - {path.absolute()}")
+        else:
+            print("WARNING: No file annotations found in non-streaming response")
+
+
+async def streaming_example() -> None:
+    """Example of downloading files from streaming response using HostedFileContent."""
+    print("\n=== Streaming Response Example ===")
+
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="V2CodeInterpreterFileAgentStreaming",
+            instructions="You are a helpful assistant that can write and execute Python code to create files.",
+            tools=HostedCodeInterpreterTool(),
+        )
+
+        print(f"User: {QUERY}\n")
+        file_contents_found: list[HostedFileContent] = []
+        text_chunks: list[str] = []
+
+        async for update in agent.run_stream(QUERY):
+            if isinstance(update, AgentResponseUpdate):
+                for content in update.contents:
+                    if isinstance(content, TextContent):
+                        if content.text:
+                            text_chunks.append(content.text)
+                        if content.annotations:
+                            for annotation in content.annotations:
+                                if isinstance(annotation, CitationAnnotation) and annotation.file_id:
+                                    print(f"Found streaming CitationAnnotation: file_id={annotation.file_id}")
+                    elif isinstance(content, HostedFileContent):
+                        file_contents_found.append(content)
+                        print(f"Found streaming HostedFileContent: file_id={content.file_id}")
+                        if content.additional_properties and "container_id" in content.additional_properties:
+                            print(f"  container_id={content.additional_properties['container_id']}")
+
+        print(f"\nAgent response: {''.join(text_chunks)[:200]}...")
+
+        if file_contents_found:
+            print(f"SUCCESS: Found {len(file_contents_found)} file reference(s) in streaming")
+
+            # Download the container files
+            downloaded_paths = await download_container_files(file_contents_found, agent)
+
+            if downloaded_paths:
+                print("\n✓ Downloaded files available at:")
+                for path in downloaded_paths:
+                    print(f"  - {path.absolute()}")
+        else:
+            print("WARNING: No file annotations found in streaming response")
+
+
+async def main() -> None:
+    print("AzureAIClient Code Interpreter File Download Sample\n")
+    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_file_generation.py

@@ -0,0 +1,112 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import (
+    AgentResponseUpdate,
+    HostedCodeInterpreterTool,
+)
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI V2 Code Interpreter File Generation Sample
+
+This sample demonstrates how the AzureAIProjectAgentProvider handles file annotations
+when code interpreter generates text files. It shows both non-streaming
+and streaming approaches to verify file ID extraction.
+"""
+
+QUERY = (
+    "Write a simple Python script that creates a text file called 'sample.txt' containing "
+    "'Hello from the code interpreter!' and save it to disk."
+)
+
+
+async def non_streaming_example() -> None:
+    """Example of extracting file annotations from non-streaming response."""
+    print("=== Non-Streaming Response Example ===")
+
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="V2CodeInterpreterFileAgent",
+            instructions="You are a helpful assistant that can write and execute Python code to create files.",
+            tools=HostedCodeInterpreterTool(),
+        )
+
+        print(f"User: {QUERY}\n")
+
+        result = await agent.run(QUERY)
+        print(f"Agent: {result.text}\n")
+
+        # Check for annotations in the response
+        annotations_found: list[str] = []
+        # AgentResponse has messages property, which contains ChatMessage objects
+        for message in result.messages:
+            for content in message.contents:
+                if content.type == "text" and content.annotations:
+                    for annotation in content.annotations:
+                        if annotation.file_id:
+                            annotations_found.append(annotation.file_id)
+                            print(f"Found file annotation: file_id={annotation.file_id}")
+
+        if annotations_found:
+            print(f"SUCCESS: Found {len(annotations_found)} file annotation(s)")
+        else:
+            print("WARNING: No file annotations found in non-streaming response")
+
+
+async def streaming_example() -> None:
+    """Example of extracting file annotations from streaming response."""
+    print("\n=== Streaming Response Example ===")
+
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="V2CodeInterpreterFileAgentStreaming",
+            instructions="You are a helpful assistant that can write and execute Python code to create files.",
+            tools=HostedCodeInterpreterTool(),
+        )
+
+        print(f"User: {QUERY}\n")
+        annotations_found: list[str] = []
+        text_chunks: list[str] = []
+        file_ids_found: list[str] = []
+
+        async for update in agent.run_stream(QUERY):
+            if isinstance(update, AgentResponseUpdate):
+                for content in update.contents:
+                    if content.type == "text":
+                        if content.text:
+                            text_chunks.append(content.text)
+                        if content.annotations:
+                            for annotation in content.annotations:
+                                if annotation.file_id:
+                                    annotations_found.append(annotation.file_id)
+                                    print(f"Found streaming annotation: file_id={annotation.file_id}")
+                    elif content.type == "hosted_file":
+                        file_ids_found.append(content.file_id)
+                        print(f"Found streaming HostedFileContent: file_id={content.file_id}")
+
+        print(f"\nAgent response: {''.join(text_chunks)[:200]}...")
+
+        if annotations_found or file_ids_found:
+            total = len(annotations_found) + len(file_ids_found)
+            print(f"SUCCESS: Found {total} file reference(s) in streaming")
+        else:
+            print("WARNING: No file annotations found in streaming response")
+
+
+async def main() -> None:
+    print("AzureAIClient Code Interpreter File Generation Sample\n")
+    await non_streaming_example()
+    await streaming_example()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,66 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.ai.projects.models import RaiConfig
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent with Content Filtering (RAI Policy) Example
+
+This sample demonstrates how to enable content filtering on Azure AI agents using RaiConfig.
+
+Prerequisites:
+1. Create an RAI Policy in Azure AI Foundry portal:
+   - Go to Azure AI Foundry > Your Project > Guardrails + Controls > Content Filters
+   - Create a new content filter or use an existing one
+   - Note the policy name
+
+2. Set environment variables:
+   - AZURE_AI_PROJECT_ENDPOINT: Your Azure AI Foundry project endpoint
+   - AZURE_AI_MODEL_DEPLOYMENT_NAME: Your model deployment name
+
+3. Run `az login` to authenticate
+"""
+
+
+async def main() -> None:
+    print("=== Azure AI Agent with Content Filtering ===\n")
+
+    # Replace with your RAI policy from Azure AI Foundry portal
+    rai_policy_name = (
+        "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/"
+        "Microsoft.CognitiveServices/accounts/{accountName}/raiPolicies/{policyName}"
+    )
+
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        # Create agent with content filtering enabled via default_options
+        agent = await provider.create_agent(
+            name="ContentFilteredAgent",
+            instructions="You are a helpful assistant.",
+            default_options={"rai_config": RaiConfig(rai_policy_name=rai_policy_name)},
+        )
+
+        # Test with a normal query
+        query = "What is the capital of France?"
+        print(f"User: {query}")
+        result = await agent.run(query)
+        print(f"Agent: {result}\n")
+
+        # Test with a query that might trigger content filtering
+        # (depending on your RAI policy configuration)
+        query2 = "Tell me something inappropriate."
+        print(f"User: {query2}")
+        try:
+            result2 = await agent.run(query2)
+            print(f"Agent: {result2}\n")
+        except Exception as e:
+            print(f"Content filter triggered: {e}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,66 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.ai.projects.aio import AIProjectClient
+from azure.ai.projects.models import PromptAgentDefinition
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent with Existing Agent Example
+
+This sample demonstrates working with pre-existing Azure AI Agents by using provider.get_agent() method,
+showing agent reuse patterns for production scenarios.
+"""
+
+
+async def using_provider_get_agent() -> None:
+    print("=== Get existing Azure AI agent with provider.get_agent() ===")
+
+    # Create the client
+    async with (
+        AzureCliCredential() as credential,
+        AIProjectClient(endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], credential=credential) as project_client,
+    ):
+        # Create remote agent using SDK directly
+        azure_ai_agent = await project_client.agents.create_version(
+            agent_name="MyNewTestAgent",
+            description="Agent for testing purposes.",
+            definition=PromptAgentDefinition(
+                model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+                # Setting specific requirements to verify that this agent is used.
+                instructions="End each response with [END].",
+            ),
+        )
+
+        try:
+            # Get newly created agent as ChatAgent by using provider.get_agent()
+            provider = AzureAIProjectAgentProvider(project_client=project_client)
+            agent = await provider.get_agent(name=azure_ai_agent.name)
+
+            # Verify agent properties
+            print(f"Agent ID: {agent.id}")
+            print(f"Agent name: {agent.name}")
+            print(f"Agent description: {agent.description}")
+
+            query = "How are you?"
+            print(f"User: {query}")
+            result = await agent.run(query)
+            # Response that indicates that previously created agent was used:
+            # "I'm here and ready to help you! How can I assist you today? [END]"
+            print(f"Agent: {result}\n")
+        finally:
+            # Clean up the agent manually
+            await project_client.agents.delete_version(
+                agent_name=azure_ai_agent.name, agent_version=azure_ai_agent.version
+            )
+
+
+async def main() -> None:
+    await using_provider_get_agent()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,99 @@
+# Copyright (c) Microsoft. All rights reserved.
+import asyncio
+import os
+from random import randint
+from typing import Annotated
+
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.ai.projects.aio import AIProjectClient
+from azure.identity.aio import AzureCliCredential
+from pydantic import Field
+
+"""
+Azure AI Agent Existing Conversation Example
+
+This sample demonstrates usage of AzureAIProjectAgentProvider with existing conversation created on service side.
+"""
+
+
+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_conversation_id() -> None:
+    """Example shows how to use existing conversation ID with the provider."""
+    print("=== Azure AI Agent With Existing Conversation ===")
+    async with (
+        AzureCliCredential() as credential,
+        AIProjectClient(endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], credential=credential) as project_client,
+    ):
+        # Create a conversation using OpenAI client
+        openai_client = project_client.get_openai_client()
+        conversation = await openai_client.conversations.create()
+        conversation_id = conversation.id
+        print(f"Conversation ID: {conversation_id}")
+
+        provider = AzureAIProjectAgentProvider(project_client=project_client)
+        agent = await provider.create_agent(
+            name="BasicAgent",
+            instructions="You are a helpful agent.",
+            tools=get_weather,
+        )
+
+        # Pass conversation_id at run level
+        query = "What's the weather like in Seattle?"
+        print(f"User: {query}")
+        result = await agent.run(query, conversation_id=conversation_id)
+        print(f"Agent: {result.text}\n")
+
+        query = "What was my last question?"
+        print(f"User: {query}")
+        result = await agent.run(query, conversation_id=conversation_id)
+        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 with (
+        AzureCliCredential() as credential,
+        AIProjectClient(endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], credential=credential) as project_client,
+    ):
+        provider = AzureAIProjectAgentProvider(project_client=project_client)
+        agent = await provider.create_agent(
+            name="BasicAgent",
+            instructions="You are a helpful agent.",
+            tools=get_weather,
+        )
+
+        # Create a conversation using OpenAI client
+        openai_client = project_client.get_openai_client()
+        conversation = await openai_client.conversations.create()
+        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)
+
+        query = "What's the weather like in Seattle?"
+        print(f"User: {query}")
+        result = await agent.run(query, thread=thread)
+        print(f"Agent: {result.text}\n")
+
+        query = "What was my last question?"
+        print(f"User: {query}")
+        result = await agent.run(query, thread=thread)
+        print(f"Agent: {result.text}\n")
+
+
+async def main() -> None:
+    await example_with_conversation_id()
+    await example_with_thread()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_ai/azure_ai_with_explicit_settings.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.azure import AzureAIProjectAgentProvider
+from azure.identity.aio import AzureCliCredential
+from pydantic import Field
+
+"""
+Azure AI Agent with Explicit Settings Example
+
+This sample demonstrates creating Azure AI Agents with explicit configuration
+settings rather than relying on environment variable defaults.
+"""
+
+
+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:
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(
+            project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+            model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            credential=credential,
+        ) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="WeatherAgent",
+            instructions="You are a helpful weather agent.",
+            tools=get_weather,
+        )
+
+        query = "What's the weather like in New York?"
+        print(f"User: {query}")
+        result = await agent.run(query)
+        print(f"Agent: {result}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,75 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from pathlib import Path
+
+from agent_framework import HostedFileSearchTool, HostedVectorStoreContent
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.ai.agents.aio import AgentsClient
+from azure.ai.agents.models import FileInfo, VectorStore
+from azure.identity.aio import AzureCliCredential
+
+"""
+The following sample demonstrates how to create a simple, Azure AI agent that
+uses a file search tool to answer user questions.
+"""
+
+
+# Simulate a conversation with the agent
+USER_INPUTS = [
+    "Who is the youngest employee?",
+    "Who works in sales?",
+    "I have a customer request, who can help me?",
+]
+
+
+async def main() -> None:
+    """Main function demonstrating Azure AI agent with file search capabilities."""
+    file: FileInfo | None = None
+    vector_store: VectorStore | None = None
+
+    async with (
+        AzureCliCredential() as credential,
+        AgentsClient(endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], credential=credential) as agents_client,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        try:
+            # 1. Upload file and create vector store
+            pdf_file_path = Path(__file__).parent.parent / "resources" / "employees.pdf"
+            print(f"Uploading file from: {pdf_file_path}")
+
+            file = await agents_client.files.upload_and_poll(file_path=str(pdf_file_path), purpose="assistants")
+            print(f"Uploaded file, file ID: {file.id}")
+
+            vector_store = await agents_client.vector_stores.create_and_poll(file_ids=[file.id], name="my_vectorstore")
+            print(f"Created vector store, vector store ID: {vector_store.id}")
+
+            # 2. Create file search tool with uploaded resources
+            file_search_tool = HostedFileSearchTool(inputs=[HostedVectorStoreContent(vector_store_id=vector_store.id)])
+
+            # 3. Create an agent with file search capabilities using the provider
+            agent = await provider.create_agent(
+                name="EmployeeSearchAgent",
+                instructions=(
+                    "You are a helpful assistant that can search through uploaded employee files "
+                    "to answer questions about employees."
+                ),
+                tools=file_search_tool,
+            )
+
+            # 4. Simulate conversation with the agent
+            for user_input in USER_INPUTS:
+                print(f"# User: '{user_input}'")
+                response = await agent.run(user_input)
+                print(f"# Agent: {response.text}")
+        finally:
+            # 5. Cleanup: Delete the vector store and file in case of earlier failure to prevent orphaned resources.
+            if vector_store:
+                await agents_client.vector_stores.delete(vector_store.id)
+            if file:
+                await agents_client.files.delete(file.id)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,119 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Any
+
+from agent_framework import AgentProtocol, AgentResponse, AgentThread, ChatMessage, HostedMCPTool
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent with Hosted MCP Example
+
+This sample demonstrates integrating hosted Model Context Protocol (MCP) tools with Azure AI Agent.
+"""
+
+
+async def handle_approvals_without_thread(query: str, agent: "AgentProtocol") -> AgentResponse:
+    """When we don't have a thread, 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:
+        new_inputs: list[Any] = [query]
+        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}"
+            )
+            new_inputs.append(ChatMessage(role="assistant", contents=[user_input_needed]))
+            user_approval = input("Approve function call? (y/n): ")
+            new_inputs.append(
+                ChatMessage(role="user", contents=[user_input_needed.create_response(user_approval.lower() == "y")])
+            )
+
+        result = await agent.run(new_inputs, store=False)
+    return result
+
+
+async def handle_approvals_with_thread(query: str, agent: "AgentProtocol", thread: "AgentThread") -> AgentResponse:
+    """Here we let the thread deal with the previous responses, and we just rerun with the approval."""
+
+    result = await agent.run(query, thread=thread)
+    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)
+    return result
+
+
+async def run_hosted_mcp_without_approval() -> None:
+    """Example showing MCP Tools without approval."""
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="MyLearnDocsAgent",
+            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",
+                approval_mode="never_require",
+            ),
+        )
+
+        query = "How to create an Azure storage account using az cli?"
+        print(f"User: {query}")
+        result = await handle_approvals_without_thread(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 ===")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="MyApiSpecsAgent",
+            instructions="You are a helpful agent that can use MCP tools to assist users.",
+            tools=HostedMCPTool(
+                name="api-specs",
+                url="https://gitmcp.io/Azure/azure-rest-api-specs",
+                approval_mode="always_require",
+            ),
+        )
+
+        thread = agent.get_new_thread()
+        query = "Please summarize the Azure REST API specifications Readme"
+        print(f"User: {query}")
+        result = await handle_approvals_with_thread(query, agent, thread)
+        print(f"{agent.name}: {result}\n")
+
+
+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()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,110 @@
+# Copyright (c) Microsoft. All rights reserved.
+import asyncio
+import base64
+import tempfile
+from pathlib import Path
+from urllib import request as urllib_request
+
+import aiofiles
+from agent_framework import HostedImageGenerationTool
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent with Image Generation Example
+
+This sample demonstrates basic usage of AzureAIProjectAgentProvider to create an agent
+that can generate images based on user requirements.
+
+Pre-requisites:
+- Make sure to set up the AZURE_AI_PROJECT_ENDPOINT and AZURE_AI_MODEL_DEPLOYMENT_NAME
+  environment variables before running this sample.
+"""
+
+
+async def main() -> None:
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="ImageGenAgent",
+            instructions="Generate images based on user requirements.",
+            tools=[
+                HostedImageGenerationTool(
+                    options={
+                        "model_id": "gpt-image-1",
+                        "image_size": "1024x1024",
+                        "media_type": "png",
+                    },
+                    additional_properties={
+                        "quality": "low",
+                        "background": "opaque",
+                    },
+                )
+            ],
+        )
+
+        query = "Generate an image of Microsoft logo."
+        print(f"User: {query}")
+        result = await agent.run(
+            query,
+            # These additional options are required for image generation
+            options={
+                "extra_headers": {"x-ms-oai-image-generation-deployment": "gpt-image-1-mini"},
+            },
+        )
+        print(f"Agent: {result}\n")
+
+        # Save the image to a file
+        print("Downloading generated image...")
+        image_data = [
+            content.outputs
+            for content in result.messages[0].contents
+            if content.type == "image_generation_tool_result" and content.outputs is not None
+        ]
+        if image_data and image_data[0]:
+            # Save to the OS temporary directory
+            filename = "microsoft.png"
+            file_path = Path(tempfile.gettempdir()) / filename
+            # outputs can be a list of Content items (data/uri) or a single item
+            out = image_data[0][0] if isinstance(image_data[0], list) else image_data[0]
+            data_bytes: bytes | None = None
+            uri = getattr(out, "uri", None)
+            if isinstance(uri, str):
+                if ";base64," in uri:
+                    try:
+                        b64 = uri.split(";base64,", 1)[1]
+                        data_bytes = base64.b64decode(b64)
+                    except Exception:
+                        data_bytes = None
+                else:
+                    try:
+                        data_bytes = await asyncio.to_thread(lambda: urllib_request.urlopen(uri).read())
+                    except Exception:
+                        data_bytes = None
+
+            if data_bytes is None:
+                raise RuntimeError("Image output present but could not retrieve bytes.")
+
+            async with aiofiles.open(file_path, "wb") as f:
+                await f.write(data_bytes)
+
+            print(f"Image downloaded and saved to: {file_path}")
+        else:
+            print("No image data found in the agent response.")
+
+    """
+    Sample output:
+    User: Generate an image of Microsoft logo.
+    Agent: Here is the Microsoft logo image featuring its iconic four quadrants.
+
+    Downloading generated image...
+    Image downloaded and saved to: .../microsoft.png
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,56 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import MCPStreamableHTTPTool
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent with Local MCP Example
+
+This sample demonstrates integration of Azure AI Agents with local Model Context Protocol (MCP)
+servers.
+
+Pre-requisites:
+- Make sure to set up the AZURE_AI_PROJECT_ENDPOINT and AZURE_AI_MODEL_DEPLOYMENT_NAME
+  environment variables before running this sample.
+"""
+
+
+async def main() -> None:
+    """Example showing use of Local MCP Tool with AzureAIProjectAgentProvider."""
+    print("=== Azure AI Agent with Local MCP Tools Example ===\n")
+
+    mcp_tool = MCPStreamableHTTPTool(
+        name="Microsoft Learn MCP",
+        url="https://learn.microsoft.com/api/mcp",
+    )
+
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="DocsAgent",
+            instructions="You are a helpful assistant that can help with Microsoft documentation questions.",
+            tools=mcp_tool,
+        )
+
+        # Use agent as context manager to ensure proper cleanup
+        async with agent:
+            # First query
+            first_query = "How to create an Azure storage account using az cli?"
+            print(f"User: {first_query}")
+            first_result = await agent.run(first_query)
+            print(f"Agent: {first_result}")
+            print("\n=======================================\n")
+            # Second query
+            second_query = "What is Microsoft Agent Framework?"
+            print(f"User: {second_query}")
+            second_result = await agent.run(second_query)
+            print(f"Agent: {second_result}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,88 @@
+# Copyright (c) Microsoft. All rights reserved.
+import asyncio
+import os
+import uuid
+
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.ai.projects.aio import AIProjectClient
+from azure.ai.projects.models import MemoryStoreDefaultDefinition, MemoryStoreDefaultOptions
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent with Memory Search Example
+
+This sample demonstrates usage of AzureAIProjectAgentProvider with memory search capabilities
+to retrieve relevant past user messages and maintain conversation context across sessions.
+It shows explicit memory store creation using Azure AI Projects client and agent creation
+using the Agent Framework.
+
+Prerequisites:
+1. Set AZURE_AI_PROJECT_ENDPOINT and AZURE_AI_MODEL_DEPLOYMENT_NAME environment variables.
+2. Set AZURE_AI_CHAT_MODEL_DEPLOYMENT_NAME for the memory chat model.
+3. Set AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME for the memory embedding model.
+4. Deploy both a chat model (e.g. gpt-4.1) and an embedding model (e.g. text-embedding-3-small).
+"""
+
+
+async def main() -> None:
+    endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]
+    # Generate a unique memory store name to avoid conflicts
+    memory_store_name = f"agent_framework_memory_store_{uuid.uuid4().hex[:8]}"
+
+    async with AzureCliCredential() as credential:
+        # Create the memory store using Azure AI Projects client
+        async with AIProjectClient(endpoint=endpoint, credential=credential) as project_client:
+            # Create a memory store using proper model classes
+            memory_store_definition = MemoryStoreDefaultDefinition(
+                chat_model=os.environ["AZURE_AI_CHAT_MODEL_DEPLOYMENT_NAME"],
+                embedding_model=os.environ["AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME"],
+                options=MemoryStoreDefaultOptions(user_profile_enabled=True, chat_summary_enabled=True),
+            )
+
+            memory_store = await project_client.memory_stores.create(
+                name=memory_store_name,
+                description="Memory store for Agent Framework conversations",
+                definition=memory_store_definition,
+            )
+            print(f"Created memory store: {memory_store.name} ({memory_store.id}): {memory_store.description}")
+
+        # Then, create the agent using Agent Framework provider
+        async with AzureAIProjectAgentProvider(credential=credential) as provider:
+            agent = await provider.create_agent(
+                name="MyMemoryAgent",
+                instructions="""You are a helpful assistant that remembers past conversations.
+                Use the memory search tool to recall relevant information from previous interactions.""",
+                tools={
+                    "type": "memory_search",
+                    "memory_store_name": memory_store.name,
+                    "scope": "user_123",
+                    "update_delay": 1,  # Wait 1 second before updating memories (use higher value in production)
+                },
+            )
+
+            # First interaction - establish some preferences
+            print("=== First conversation ===")
+            query1 = "I prefer dark roast coffee"
+            print(f"User: {query1}")
+            result1 = await agent.run(query1)
+            print(f"Agent: {result1}\n")
+
+            # Wait for memories to be processed
+            print("Waiting for memories to be stored...")
+            await asyncio.sleep(5)  # Reduced wait time for demo purposes
+
+            # Second interaction - test memory recall
+            print("=== Second conversation ===")
+            query2 = "Please order my usual coffee"
+            print(f"User: {query2}")
+            result2 = await agent.run(query2)
+            print(f"Agent: {result2}\n")
+
+        # Clean up - delete the memory store
+        async with AIProjectClient(endpoint=endpoint, credential=credential) as project_client:
+            await project_client.memory_stores.delete(memory_store_name)
+            print("Memory store deleted")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,48 @@
+# Copyright (c) Microsoft. All rights reserved.
+import asyncio
+import os
+
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent with Microsoft Fabric Example
+
+This sample demonstrates usage of AzureAIProjectAgentProvider with Microsoft Fabric
+to query Fabric data sources and provide responses based on data analysis.
+
+Prerequisites:
+1. Set AZURE_AI_PROJECT_ENDPOINT and AZURE_AI_MODEL_DEPLOYMENT_NAME environment variables.
+2. Ensure you have a Microsoft Fabric connection configured in your Azure AI project
+   and set FABRIC_PROJECT_CONNECTION_ID environment variable.
+"""
+
+
+async def main() -> None:
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="MyFabricAgent",
+            instructions="You are a helpful assistant.",
+            tools={
+                "type": "fabric_dataagent_preview",
+                "fabric_dataagent_preview": {
+                    "project_connections": [
+                        {
+                            "project_connection_id": os.environ["FABRIC_PROJECT_CONNECTION_ID"],
+                        }
+                    ]
+                },
+            },
+        )
+
+        query = "Tell me about sales records"
+        print(f"User: {query}")
+        result = await agent.run(query)
+        print(f"Result: {result}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,56 @@
+# Copyright (c) Microsoft. All rights reserved.
+import asyncio
+import json
+from pathlib import Path
+
+import aiofiles
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent with OpenAPI Tool Example
+
+This sample demonstrates usage of AzureAIProjectAgentProvider with OpenAPI tools
+to call external APIs defined by OpenAPI specifications.
+
+Prerequisites:
+1. Set AZURE_AI_PROJECT_ENDPOINT and AZURE_AI_MODEL_DEPLOYMENT_NAME environment variables.
+2. The countries.json OpenAPI specification is included in the resources folder.
+"""
+
+
+async def main() -> None:
+    # Load the OpenAPI specification
+    resources_path = Path(__file__).parent.parent / "resources" / "countries.json"
+
+    async with aiofiles.open(resources_path, "r") as f:
+        content = await f.read()
+        openapi_countries = json.loads(content)
+
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="MyOpenAPIAgent",
+            instructions="""You are a helpful assistant that can use country APIs to provide information.
+            Use the available OpenAPI tools to answer questions about countries, currencies, and demographics.""",
+            tools={
+                "type": "openapi",
+                "openapi": {
+                    "name": "get_countries",
+                    "spec": openapi_countries,
+                    "description": "Retrieve information about countries by currency code",
+                    "auth": {"type": "anonymous"},
+                },
+            },
+        )
+
+        query = "What is the name and population of the country that uses currency with abbreviation THB?"
+        print(f"User: {query}")
+        result = await agent.run(query)
+        print(f"Agent: {result}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,94 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.ai.projects.models import Reasoning
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent with Reasoning Example
+
+Demonstrates how to enable reasoning capabilities using the Reasoning option.
+Shows both non-streaming and streaming approaches, including how to access
+reasoning content (type="text_reasoning") separately from answer content.
+
+Requires a reasoning-capable model (e.g., gpt-5.2) deployed in your Azure AI Project configured
+as `AZURE_AI_MODEL_DEPLOYMENT_NAME` in your environment.
+"""
+
+
+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.
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="ReasoningWeatherAgent",
+            instructions="You are a helpful weather agent who likes to understand the underlying physics.",
+            default_options={"reasoning": Reasoning(effort="medium", summary="concise")},
+        )
+
+        query = "How does the Bernoulli effect work?"
+        print(f"User: {query}")
+        result = await agent.run(query)
+
+        for msg in result.messages:
+            for content in msg.contents:
+                if content.type == "text_reasoning":
+                    print(f"[Reasoning]: {content.text}")
+                elif content.type == "text":
+                    print(f"[Answer]: {content.text}")
+            print()
+
+
+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.
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="ReasoningWeatherAgent",
+            instructions="You are a helpful weather agent who likes to understand the underlying physics.",
+            default_options={"reasoning": Reasoning(effort="medium", summary="concise")},
+        )
+
+        query = "Help explain how air updrafts work?"
+        print(f"User: {query}")
+
+        shown_reasoning_label = False
+        shown_text_label = False
+        async for chunk in agent.run_stream(query):
+            for content in chunk.contents:
+                if content.type == "text_reasoning":
+                    if not shown_reasoning_label:
+                        print("[Reasoning]: ", end="", flush=True)
+                        shown_reasoning_label = True
+                    print(content.text, end="", flush=True)
+                elif content.type == "text":
+                    if not shown_text_label:
+                        print("\n\n[Answer]: ", end="", flush=True)
+                        shown_text_label = True
+                    print(content.text, end="", flush=True)
+        print("\n")
+
+
+async def main() -> None:
+    print("=== Azure AI Agent with Reasoning Example ===")
+
+    # await non_streaming_example()
+    await streaming_example()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,54 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.identity.aio import AzureCliCredential
+from pydantic import BaseModel, ConfigDict
+
+"""
+Azure AI Agent Response Format Example
+
+This sample demonstrates basic usage of AzureAIProjectAgentProvider with response format,
+also known as structured outputs.
+"""
+
+
+class ReleaseBrief(BaseModel):
+    feature: str
+    benefit: str
+    launch_date: str
+    model_config = ConfigDict(extra="forbid")
+
+
+async def main() -> None:
+    """Example of using response_format property."""
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="ProductMarketerAgent",
+            instructions="Return launch briefs as structured JSON.",
+            # Specify Pydantic model for structured output via default_options
+            default_options={"response_format": ReleaseBrief},
+        )
+
+        query = "Draft a launch brief for the Contoso Note app."
+        print(f"User: {query}")
+        result = await agent.run(query)
+
+        if release_brief := result.try_parse_value(ReleaseBrief):
+            print("Agent:")
+            print(f"Feature: {release_brief.feature}")
+            print(f"Benefit: {release_brief.benefit}")
+            print(f"Launch date: {release_brief.launch_date}")
+        else:
+            print(f"Failed to parse response: {result.text}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,64 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent Response Format Example with Runtime JSON Schema
+
+This sample demonstrates basic usage of AzureAIProjectAgentProvider with response format,
+also known as structured outputs.
+"""
+
+
+runtime_schema = {
+    "title": "WeatherDigest",
+    "type": "object",
+    "properties": {
+        "location": {"type": "string"},
+        "conditions": {"type": "string"},
+        "temperature_c": {"type": "number"},
+        "advisory": {"type": "string"},
+    },
+    # OpenAI strict mode requires every property to appear in required.
+    "required": ["location", "conditions", "temperature_c", "advisory"],
+    "additionalProperties": False,
+}
+
+
+async def main() -> None:
+    """Example of using response_format property with a runtime JSON schema."""
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        # Pass response_format via default_options using dict schema format
+        agent = await provider.create_agent(
+            name="WeatherDigestAgent",
+            instructions="Return sample weather digest as structured JSON.",
+            default_options={
+                "response_format": {
+                    "type": "json_schema",
+                    "json_schema": {
+                        "name": runtime_schema["title"],
+                        "strict": True,
+                        "schema": runtime_schema,
+                    },
+                }
+            },
+        )
+
+        query = "Draft a sample weather digest."
+        print(f"User: {query}")
+        result = await agent.run(query)
+
+        print(result.text)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,49 @@
+# Copyright (c) Microsoft. All rights reserved.
+import asyncio
+import os
+
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent with SharePoint Example
+
+This sample demonstrates usage of AzureAIProjectAgentProvider with SharePoint
+to search through SharePoint content and answer user questions about it.
+
+Prerequisites:
+1. Set AZURE_AI_PROJECT_ENDPOINT and AZURE_AI_MODEL_DEPLOYMENT_NAME environment variables.
+2. Ensure you have a SharePoint connection configured in your Azure AI project
+    and set SHAREPOINT_PROJECT_CONNECTION_ID environment variable.
+"""
+
+
+async def main() -> None:
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="MySharePointAgent",
+            instructions="""You are a helpful agent that can use SharePoint tools to assist users.
+            Use the available SharePoint tools to answer questions and perform tasks.""",
+            tools={
+                "type": "sharepoint_grounding_preview",
+                "sharepoint_grounding_preview": {
+                    "project_connections": [
+                        {
+                            "project_connection_id": os.environ["SHAREPOINT_PROJECT_CONNECTION_ID"],
+                        }
+                    ]
+                },
+            },
+        )
+
+        query = "What is Contoso whistleblower policy?"
+        print(f"User: {query}")
+        result = await agent.run(query)
+        print(f"Result: {result}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,156 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from random import randint
+from typing import Annotated
+
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.identity.aio import AzureCliCredential
+from pydantic import Field
+
+"""
+Azure AI Agent with Thread 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.
+"""
+
+
+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 ===")
+
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="BasicWeatherAgent",
+            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) ===")
+
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="BasicWeatherAgent",
+            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, store=False)
+        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, 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)
+        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.
+    """
+    print("=== Existing Thread ID Example ===")
+
+    # First, create a conversation and capture the thread ID
+    existing_thread_id = None
+
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="BasicWeatherAgent",
+            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}")
+        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 from the same provider
+            agent2 = await provider.create_agent(
+                name="BasicWeatherAgent",
+                instructions="You are a helpful weather agent.",
+                tools=get_weather,
+            )
+
+            # Create a thread with the existing ID
+            thread = agent2.get_new_thread(service_thread_id=existing_thread_id)
+
+            query2 = "What was the last city I asked about?"
+            print(f"User: {query2}")
+            result2 = await agent2.run(query2, thread=thread)
+            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 AI 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())

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

@@ -0,0 +1,49 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import HostedWebSearchTool
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent With Web Search
+
+This sample demonstrates basic usage of AzureAIProjectAgentProvider to create an agent
+that can perform web searches using the HostedWebSearchTool.
+
+Pre-requisites:
+- Make sure to set up the AZURE_AI_PROJECT_ENDPOINT and AZURE_AI_MODEL_DEPLOYMENT_NAME
+  environment variables before running this sample.
+"""
+
+
+async def main() -> None:
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIProjectAgentProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="WebsearchAgent",
+            instructions="You are a helpful assistant that can search the web",
+            tools=[HostedWebSearchTool()],
+        )
+
+        query = "What's the weather today in Seattle?"
+        print(f"User: {query}")
+        result = await agent.run(query)
+        print(f"Agent: {result}\n")
+
+    """
+    Sample output:
+    User: What's the weather today in Seattle?
+    Agent: Here is the updated weather forecast for Seattle: The current temperature is approximately 57°F,
+           mostly cloudy conditions, with light winds and a chance of rain later tonight. Check out more details
+           at the [National Weather Service](https://forecast.weather.gov/zipcity.php?inputstring=Seattle%2CWA).
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())