test

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

@@ -0,0 +1,114 @@
+# Azure AI Agent Examples
+
+This folder contains examples demonstrating different ways to create and use agents with Azure AI using the `AzureAIAgentsProvider` from the `agent_framework.azure` package. These examples use the `azure-ai-agents` 1.x (V1) API surface. For updated V2 (`azure-ai-projects` 2.x) samples, see the [Azure AI V2 examples folder](../azure_ai/).
+
+## Provider Pattern
+
+All examples in this folder use the `AzureAIAgentsProvider` class which provides a high-level interface for agent operations:
+
+- **`create_agent()`** - Create a new agent on the Azure AI service
+- **`get_agent()`** - Retrieve an existing agent by ID or from a pre-fetched Agent object
+- **`as_agent()`** - Wrap an SDK Agent object as a ChatAgent without HTTP calls
+
+```python
+from agent_framework.azure import AzureAIAgentsProvider
+from azure.identity.aio import AzureCliCredential
+
+async with (
+    AzureCliCredential() as credential,
+    AzureAIAgentsProvider(credential=credential) as provider,
+):
+    agent = await provider.create_agent(
+        name="MyAgent",
+        instructions="You are a helpful assistant.",
+        tools=my_function,
+    )
+    result = await agent.run("Hello!")
+```
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| [`azure_ai_provider_methods.py`](azure_ai_provider_methods.py) | Comprehensive example demonstrating all `AzureAIAgentsProvider` methods: `create_agent()`, `get_agent()`, `as_agent()`, and managing multiple agents from a single provider. |
+| [`azure_ai_basic.py`](azure_ai_basic.py) | The simplest way to create an agent using `AzureAIAgentsProvider`. It automatically handles all configuration using environment variables. Shows both streaming and non-streaming responses. |
+| [`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 find real-time information from the web using custom search configurations. Demonstrates how to set up and use HostedWebSearchTool with custom search instances. |
+| [`azure_ai_with_bing_grounding.py`](azure_ai_with_bing_grounding.py) | Shows how to use Bing Grounding search with Azure AI agents to find real-time information from the web. Demonstrates web search capabilities with proper source citations and comprehensive error handling. |
+| [`azure_ai_with_bing_grounding_citations.py`](azure_ai_with_bing_grounding_citations.py) | Demonstrates how to extract and display citations from Bing Grounding search responses. Shows how to collect citation annotations (title, URL, snippet) during streaming responses, enabling users to verify sources and access referenced content. |
+| [`azure_ai_with_code_interpreter_file_generation.py`](azure_ai_with_code_interpreter_file_generation.py) | Shows how to retrieve file IDs from code interpreter generated files using both streaming and non-streaming approaches. |
+| [`azure_ai_with_code_interpreter.py`](azure_ai_with_code_interpreter.py) | Shows how to use the HostedCodeInterpreterTool with Azure AI agents to write and execute Python code. Includes helper methods for accessing code interpreter data from response chunks. |
+| [`azure_ai_with_existing_agent.py`](azure_ai_with_existing_agent.py) | Shows how to work with an existing SDK Agent object using `provider.as_agent()`. This wraps the agent without making HTTP calls. |
+| [`azure_ai_with_existing_thread.py`](azure_ai_with_existing_thread.py) | Shows how to work with a pre-existing thread by providing the thread ID. Demonstrates proper cleanup of manually created threads. |
+| [`azure_ai_with_explicit_settings.py`](azure_ai_with_explicit_settings.py) | Shows how to create an agent with explicitly configured provider settings, including project endpoint and model deployment name. |
+| [`azure_ai_with_azure_ai_search.py`](azure_ai_with_azure_ai_search.py) | Demonstrates how to use Azure AI Search with Azure AI agents. Shows how to create an agent with search tools using the SDK directly and wrap it with `provider.get_agent()`. |
+| [`azure_ai_with_file_search.py`](azure_ai_with_file_search.py) | Demonstrates how to use the HostedFileSearchTool with Azure AI agents to search through uploaded documents. Shows file upload, vector store creation, and querying document content. |
+| [`azure_ai_with_function_tools.py`](azure_ai_with_function_tools.py) | Demonstrates how to use function tools with agents. Shows both agent-level tools (defined when creating the agent) and query-level tools (provided with specific queries). |
+| [`azure_ai_with_hosted_mcp.py`](azure_ai_with_hosted_mcp.py) | Shows how to integrate Azure AI agents with hosted Model Context Protocol (MCP) servers for enhanced functionality and tool integration. Demonstrates remote MCP server connections and tool discovery. |
+| [`azure_ai_with_local_mcp.py`](azure_ai_with_local_mcp.py) | Shows how to integrate Azure AI agents with local Model Context Protocol (MCP) servers for enhanced functionality and tool integration. Demonstrates both agent-level and run-level tool configuration. |
+| [`azure_ai_with_multiple_tools.py`](azure_ai_with_multiple_tools.py) | Demonstrates how to use multiple tools together with Azure AI agents, including web search, MCP servers, and function tools. Shows coordinated multi-tool interactions and approval workflows. |
+| [`azure_ai_with_openapi_tools.py`](azure_ai_with_openapi_tools.py) | Demonstrates how to use OpenAPI tools with Azure AI agents to integrate external REST APIs. Shows OpenAPI specification loading, anonymous authentication, thread context management, and coordinated multi-API conversations. |
+| [`azure_ai_with_response_format.py`](azure_ai_with_response_format.py) | Demonstrates how to use structured outputs with Azure AI agents using Pydantic models. |
+| [`azure_ai_with_thread.py`](azure_ai_with_thread.py) | Demonstrates thread management with Azure AI agents, including automatic thread creation for stateless conversations and explicit thread management for maintaining conversation context across multiple interactions. |
+
+## 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:
+   ```
+   AZURE_AI_PROJECT_ENDPOINT="your-project-endpoint"
+   AZURE_AI_MODEL_DEPLOYMENT_NAME="your-model-deployment-name"
+   ```
+
+3. For samples using Bing Grounding search (like `azure_ai_with_bing_grounding.py` and `azure_ai_with_multiple_tools.py`), you'll also need:
+   ```
+   BING_CONNECTION_ID="your-bing-connection-id"
+   ```
+
+   To get your Bing connection details:
+   - 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 ID
+
+4. For samples using Bing Custom Search (like `azure_ai_with_bing_custom_search.py`), you'll also need:
+   ```
+   BING_CUSTOM_CONNECTION_ID="your-bing-custom-connection-id"
+   BING_CUSTOM_INSTANCE_NAME="your-bing-custom-instance-name"
+   ```
+
+   To get your Bing Custom Search connection details:
+   - 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 Custom Search"
+   - Copy the connection ID and instance 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"
+export BING_CONNECTION_ID="your-bing-connection-id"
+export BING_CUSTOM_CONNECTION_ID="your-bing-custom-connection-id"
+export BING_CUSTOM_INSTANCE_NAME="your-bing-custom-instance-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)
+
+### Optional Variables
+
+- `BING_CONNECTION_ID`: Your Bing connection ID (required for `azure_ai_with_bing_grounding.py` and `azure_ai_with_multiple_tools.py`)
+- `BING_CUSTOM_CONNECTION_ID`: Your Bing Custom Search connection ID (required for `azure_ai_with_bing_custom_search.py`)
+- `BING_CUSTOM_INSTANCE_NAME`: Your Bing Custom Search instance name (required for `azure_ai_with_bing_custom_search.py`)

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

@@ -0,0 +1,80 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from random import randint
+from typing import Annotated
+
+from agent_framework.azure import AzureAIAgentsProvider
+from azure.identity.aio import AzureCliCredential
+from pydantic import Field
+
+"""
+Azure AI Agent Basic Example
+
+This sample demonstrates basic usage of AzureAIAgentsProvider to create agents with automatic
+lifecycle management. 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,
+        AzureAIAgentsProvider(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 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,
+        AzureAIAgentsProvider(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 Portland?"
+        print(f"User: {query}")
+        print("Agent: ", end="", flush=True)
+        async for chunk in agent.run_stream(query):
+            if chunk.text:
+                print(chunk.text, end="", flush=True)
+        print("\n")
+
+
+async def main() -> None:
+    print("=== Basic Azure AI Chat Client Agent Example ===")
+
+    await non_streaming_example()
+    await streaming_example()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_ai_agent/azure_ai_provider_methods.py

@@ -0,0 +1,142 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from random import randint
+from typing import Annotated
+
+from agent_framework.azure import AzureAIAgentsProvider
+from azure.ai.agents.aio import AgentsClient
+from azure.identity.aio import AzureCliCredential
+from pydantic import Field
+
+"""
+Azure AI Agent Provider Methods Example
+
+This sample demonstrates the methods available on the AzureAIAgentsProvider class:
+- create_agent(): Create a new agent on the service
+- get_agent(): Retrieve an existing agent by ID
+- as_agent(): Wrap an SDK Agent object without making HTTP calls
+"""
+
+
+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:
+    """Create a new agent using provider.create_agent()."""
+    print("\n--- create_agent() ---")
+
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentsProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="WeatherAgent",
+            instructions="You are a helpful weather assistant.",
+            tools=get_weather,
+        )
+
+        print(f"Created: {agent.name} (ID: {agent.id})")
+        result = await agent.run("What's the weather in Seattle?")
+        print(f"Response: {result}")
+
+
+async def get_agent_example() -> None:
+    """Retrieve an existing agent by ID using provider.get_agent()."""
+    print("\n--- get_agent() ---")
+
+    async with (
+        AzureCliCredential() as credential,
+        AgentsClient(endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], credential=credential) as agents_client,
+        AzureAIAgentsProvider(agents_client=agents_client) as provider,
+    ):
+        # Create an agent directly with SDK (simulating pre-existing agent)
+        sdk_agent = await agents_client.create_agent(
+            model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            name="ExistingAgent",
+            instructions="You always respond with 'Hello!'",
+        )
+
+        try:
+            # Retrieve using provider
+            agent = await provider.get_agent(sdk_agent.id)
+            print(f"Retrieved: {agent.name} (ID: {agent.id})")
+
+            result = await agent.run("Hi there!")
+            print(f"Response: {result}")
+        finally:
+            await agents_client.delete_agent(sdk_agent.id)
+
+
+async def as_agent_example() -> None:
+    """Wrap an SDK Agent object using provider.as_agent()."""
+    print("\n--- as_agent() ---")
+
+    async with (
+        AzureCliCredential() as credential,
+        AgentsClient(endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], credential=credential) as agents_client,
+        AzureAIAgentsProvider(agents_client=agents_client) as provider,
+    ):
+        # Create agent using SDK
+        sdk_agent = await agents_client.create_agent(
+            model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            name="WrappedAgent",
+            instructions="You respond with poetry.",
+        )
+
+        try:
+            # Wrap synchronously (no HTTP call)
+            agent = provider.as_agent(sdk_agent)
+            print(f"Wrapped: {agent.name} (ID: {agent.id})")
+
+            result = await agent.run("Tell me about the sunset.")
+            print(f"Response: {result}")
+        finally:
+            await agents_client.delete_agent(sdk_agent.id)
+
+
+async def multiple_agents_example() -> None:
+    """Create and manage multiple agents with a single provider."""
+    print("\n--- Multiple Agents ---")
+
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentsProvider(credential=credential) as provider,
+    ):
+        weather_agent = await provider.create_agent(
+            name="WeatherSpecialist",
+            instructions="You are a weather specialist.",
+            tools=get_weather,
+        )
+
+        greeter_agent = await provider.create_agent(
+            name="GreeterAgent",
+            instructions="You are a friendly greeter.",
+        )
+
+        print(f"Created: {weather_agent.name}, {greeter_agent.name}")
+
+        greeting = await greeter_agent.run("Hello!")
+        print(f"Greeter: {greeting}")
+
+        weather = await weather_agent.run("What's the weather in Tokyo?")
+        print(f"Weather: {weather}")
+
+
+async def main() -> None:
+    print("Azure AI Agent Provider Methods")
+
+    await create_agent_example()
+    await get_agent_example()
+    await as_agent_example()
+    await multiple_agents_example()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,116 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+
+from agent_framework import Annotation
+from agent_framework.azure import AzureAIAgentsProvider
+from azure.ai.agents.aio import AgentsClient
+from azure.ai.projects.aio import AIProjectClient
+from azure.ai.projects.models import ConnectionType
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent with Azure AI Search Example
+
+This sample demonstrates how to create an Azure AI agent that uses Azure AI Search
+to search through indexed hotel data and answer user questions about hotels.
+
+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
+3. The search index "hotels-sample-index" should exist in your Azure AI Search service
+   (you can create this using the Azure portal with sample hotel data)
+
+NOTE: To ensure consistent search tool usage:
+- Include explicit instructions for the agent to use the search tool
+- Mention the search requirement in your queries
+- Use `tool_choice="required"` to force tool usage
+
+More info on `query type` can be found here:
+https://learn.microsoft.com/en-us/python/api/azure-ai-agents/azure.ai.agents.models.aisearchindexresource?view=azure-python-preview
+"""
+
+
+async def main() -> None:
+    """Main function demonstrating Azure AI agent with raw Azure AI Search tool."""
+    print("=== Azure AI Agent with Raw Azure AI Search Tool ===")
+
+    # Create the client and manually create an agent with Azure AI Search tool
+    async with (
+        AzureCliCredential() as credential,
+        AIProjectClient(endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], credential=credential) as project_client,
+        AgentsClient(endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], credential=credential) as agents_client,
+        AzureAIAgentsProvider(agents_client=agents_client) as provider,
+    ):
+        ai_search_conn_id = ""
+        async for connection in project_client.connections.list():
+            if connection.type == ConnectionType.AZURE_AI_SEARCH:
+                ai_search_conn_id = connection.id
+                break
+
+        # 1. Create Azure AI agent with the search tool using SDK directly
+        # (Azure AI Search tool requires special tool_resources configuration)
+        azure_ai_agent = await agents_client.create_agent(
+            model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            name="HotelSearchAgent",
+            instructions=(
+                "You are a helpful agent that searches hotel information using Azure AI Search. "
+                "Always use the search tool and index to find hotel data and provide accurate information."
+            ),
+            tools=[{"type": "azure_ai_search"}],
+            tool_resources={
+                "azure_ai_search": {
+                    "indexes": [
+                        {
+                            "index_connection_id": ai_search_conn_id,
+                            "index_name": "hotels-sample-index",
+                            "query_type": "vector",
+                        }
+                    ]
+                }
+            },
+        )
+
+        try:
+            # 2. Use provider.as_agent() to wrap the existing agent
+            agent = provider.as_agent(agent=azure_ai_agent)
+
+            print("This agent uses raw Azure AI Search tool to search hotel data.\n")
+
+            # 3. Simulate conversation with the agent
+            user_input = (
+                "Use Azure AI search knowledge tool to find detailed information about a winter hotel."
+                " Use the search tool and index."  # You can modify prompt to force tool usage
+            )
+            print(f"User: {user_input}")
+            print("Agent: ", end="", flush=True)
+            # Stream the response and collect citations
+            citations: list[Annotation] = []
+            async for chunk in agent.run_stream(user_input):
+                if chunk.text:
+                    print(chunk.text, end="", flush=True)
+                # Collect citations from Azure AI Search responses
+                for content in getattr(chunk, "contents", []):
+                    annotations = getattr(content, "annotations", [])
+                    if annotations:
+                        citations.extend(annotations)
+
+            print()
+
+            # Display collected citation
+            if citations:
+                print("\n\nCitation:")
+                for i, citation in enumerate(citations, 1):
+                    print(f"[{i}] {citation.get('url')}")
+
+            print("\n" + "=" * 50 + "\n")
+            print("Hotel search conversation completed!")
+
+        finally:
+            # Clean up the agent manually
+            await agents_client.delete_agent(azure_ai_agent.id)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,64 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import HostedWebSearchTool
+from agent_framework.azure import AzureAIAgentsProvider
+from azure.identity.aio import AzureCliCredential
+
+"""
+The following sample demonstrates how to create an Azure AI agent that
+uses Bing Custom Search to find real-time information from the web.
+
+More information on Bing Custom Search and difference from Bing Grounding can be found here:
+https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/bing-custom-search
+
+Prerequisites:
+1. A connected Grounding with Bing Custom Search resource in your Azure AI project
+2. Set BING_CUSTOM_CONNECTION_ID environment variable
+   Example: BING_CUSTOM_CONNECTION_ID="your-bing-custom-connection-id"
+3. Set BING_CUSTOM_INSTANCE_NAME environment variable
+   Example: BING_CUSTOM_INSTANCE_NAME="your-bing-custom-instance-name"
+
+To set up Bing Custom Search:
+1. Go to Azure AI Foundry portal (https://ai.azure.com)
+2. Navigate to your project's "Connected resources" section
+3. Add a new connection for "Grounding with Bing Custom Search"
+4. Copy the connection ID and instance name and set the appropriate environment variables
+"""
+
+
+async def main() -> None:
+    """Main function demonstrating Azure AI agent with Bing Custom Search."""
+    # 1. Create Bing Custom Search tool using HostedWebSearchTool
+    # The connection ID and instance name will be automatically picked up from environment variables
+    bing_search_tool = HostedWebSearchTool(
+        name="Bing Custom Search",
+        description="Search the web for current information using Bing Custom Search",
+    )
+
+    # 2. Use AzureAIAgentsProvider for agent creation and management
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentsProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="BingSearchAgent",
+            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=bing_search_tool,
+        )
+
+        # 3. Demonstrate agent capabilities with bing custom search
+        print("=== Azure AI Agent with Bing Custom Search ===\n")
+
+        user_input = "Tell me more about foundry agent service"
+        print(f"User: {user_input}")
+        response = await agent.run(user_input)
+        print(f"Agent: {response.text}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,60 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import HostedWebSearchTool
+from agent_framework.azure import AzureAIAgentsProvider
+from azure.identity.aio import AzureCliCredential
+
+"""
+The following sample demonstrates how to create an Azure AI agent that
+uses Bing Grounding search to find real-time information from the web.
+
+Prerequisites:
+1. A connected Grounding with Bing Search resource in your Azure AI project
+2. Set BING_CONNECTION_ID environment variable
+   Example: BING_CONNECTION_ID="your-bing-connection-id"
+
+To set up Bing Grounding:
+1. Go to Azure AI Foundry portal (https://ai.azure.com)
+2. Navigate to your project's "Connected resources" section
+3. Add a new connection for "Grounding with Bing Search"
+4. Copy either the connection name or ID and set the appropriate environment variable
+"""
+
+
+async def main() -> None:
+    """Main function demonstrating Azure AI agent with Bing Grounding search."""
+    # 1. Create Bing Grounding search tool using HostedWebSearchTool
+    # The connection ID will be automatically picked up from environment variable
+    bing_search_tool = HostedWebSearchTool(
+        name="Bing Grounding Search",
+        description="Search the web for current information using Bing",
+    )
+
+    # 2. Use AzureAIAgentsProvider for agent creation and management
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentsProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="BingSearchAgent",
+            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=bing_search_tool,
+        )
+
+        # 3. Demonstrate agent capabilities with web search
+        print("=== Azure AI Agent with Bing Grounding Search ===\n")
+
+        user_input = "What is the most popular programming language?"
+        print(f"User: {user_input}")
+        response = await agent.run(user_input)
+        print(f"Agent: {response.text}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_bing_grounding_citations.py

@@ -0,0 +1,87 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import Annotation, HostedWebSearchTool
+from agent_framework.azure import AzureAIAgentsProvider
+from azure.identity.aio import AzureCliCredential
+
+"""
+This sample demonstrates how to create an Azure AI agent that uses Bing Grounding
+search to find real-time information from the web with comprehensive citation support.
+It shows how to extract and display citations (title, URL, and snippet) from Bing
+Grounding responses, enabling users to verify sources and explore referenced content.
+
+Prerequisites:
+1. A connected Grounding with Bing Search resource in your Azure AI project
+2. Set BING_CONNECTION_ID environment variable
+   Example: BING_CONNECTION_ID="your-bing-connection-id"
+
+To set up Bing Grounding:
+1. Go to Azure AI Foundry portal (https://ai.azure.com)
+2. Navigate to your project's "Connected resources" section
+3. Add a new connection for "Grounding with Bing Search"
+4. Copy the connection ID and set the BING_CONNECTION_ID environment variable
+"""
+
+
+async def main() -> None:
+    """Main function demonstrating Azure AI agent with Bing Grounding search."""
+    # 1. Create Bing Grounding search tool using HostedWebSearchTool
+    # The connection ID will be automatically picked up from environment variable
+    bing_search_tool = HostedWebSearchTool(
+        name="Bing Grounding Search",
+        description="Search the web for current information using Bing",
+    )
+
+    # 2. Use AzureAIAgentsProvider for agent creation and management
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentsProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="BingSearchAgent",
+            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=bing_search_tool,
+        )
+
+        # 3. Demonstrate agent capabilities with web search
+        print("=== Azure AI Agent with Bing Grounding Search ===\n")
+
+        user_input = "What is the most popular programming language?"
+        print(f"User: {user_input}")
+        print("Agent: ", end="", flush=True)
+
+        # Stream the response and collect citations
+        citations: list[Annotation] = []
+        async for chunk in agent.run_stream(user_input):
+            if chunk.text:
+                print(chunk.text, end="", flush=True)
+
+            # Collect citations from Bing Grounding responses
+            for content in getattr(chunk, "contents", []):
+                annotations = getattr(content, "annotations", [])
+                if annotations:
+                    citations.extend(annotations)
+
+        print()
+
+        # Display collected citations
+        if citations:
+            print("\n\nCitations:")
+            for i, citation in enumerate(citations, 1):
+                print(f"[{i}] {citation['title']}: {citation.get('url')}")
+                if "snippet" in citation:
+                    print(f"    Snippet: {citation.get('snippet')}")
+        else:
+            print("\nNo citations found in the response.")
+
+        print()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

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

python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_code_interpreter_file_generation.py

@@ -0,0 +1,106 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+
+from agent_framework import (
+    AgentResponseUpdate,
+    HostedCodeInterpreterTool,
+    HostedFileContent,
+)
+from agent_framework.azure import AzureAIAgentsProvider
+from azure.ai.agents.aio import AgentsClient
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent Code Interpreter File Generation Example
+
+This sample demonstrates using HostedCodeInterpreterTool with AzureAIAgentsProvider
+to generate a text file and then retrieve it.
+
+The test flow:
+1. Create an agent with code interpreter tool
+2. Ask the agent to generate a txt file using Python code
+3. Capture the file_id from HostedFileContent in the response
+4. Retrieve the file using the agents_client.files API
+"""
+
+
+async def main() -> None:
+    """Test file generation and retrieval with code interpreter."""
+
+    async with (
+        AzureCliCredential() as credential,
+        AgentsClient(endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], credential=credential) as agents_client,
+        AzureAIAgentsProvider(agents_client=agents_client) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="CodeInterpreterAgent",
+            instructions=(
+                "You are a Python code execution assistant. "
+                "ALWAYS use the code interpreter tool to execute Python code when asked to create files. "
+                "Write actual Python code to create files, do not just describe what you would do."
+            ),
+            tools=[HostedCodeInterpreterTool()],
+        )
+
+        # Be very explicit about wanting code execution and a download link
+        query = (
+            "Use the code interpreter to execute this Python code and then provide me "
+            "with a download link for the generated file:\n"
+            "```python\n"
+            "with open('/mnt/data/sample.txt', 'w') as f:\n"
+            "    f.write('Hello, World! This is a test file.')\n"
+            "'/mnt/data/sample.txt'\n"  # Return the path so it becomes downloadable
+            "```"
+        )
+        print(f"User: {query}\n")
+        print("=" * 60)
+
+        # Collect file_ids from the response
+        file_ids: list[str] = []
+
+        async for chunk in agent.run_stream(query):
+            if not isinstance(chunk, AgentResponseUpdate):
+                continue
+
+            for content in chunk.contents:
+                if content.type == "text":
+                    print(content.text, end="", flush=True)
+                elif content.type == "hosted_file" and isinstance(content, HostedFileContent):
+                    file_ids.append(content.file_id)
+                    print(f"\n[File generated: {content.file_id}]")
+
+        print("\n" + "=" * 60)
+
+        # Attempt to retrieve discovered files
+        if file_ids:
+            print(f"\nAttempting to retrieve {len(file_ids)} file(s):")
+            for file_id in file_ids:
+                try:
+                    file_info = await agents_client.files.get(file_id)
+                    print(f"  File {file_id}: Retrieved successfully")
+                    print(f"    Filename: {file_info.filename}")
+                    print(f"    Purpose: {file_info.purpose}")
+                    print(f"    Bytes: {file_info.bytes}")
+                except Exception as e:
+                    print(f"  File {file_id}: FAILED to retrieve - {e}")
+        else:
+            print("No file IDs were captured from the response.")
+
+        # List all files to see if any exist
+        print("\nListing all files in the agent service:")
+        try:
+            files_list = await agents_client.files.list()
+            count = 0
+            for file_info in files_list.data:
+                count += 1
+                print(f"  - {file_info.id}: {file_info.filename} ({file_info.purpose})")
+            if count == 0:
+                print("  No files found.")
+        except Exception as e:
+            print(f"  Failed to list files: {e}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,48 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+
+from agent_framework.azure import AzureAIAgentsProvider
+from azure.ai.agents.aio import AgentsClient
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent with Existing Agent Example
+
+This sample demonstrates working with pre-existing Azure AI Agents by providing
+agent IDs, showing agent reuse patterns for production scenarios.
+"""
+
+
+async def main() -> None:
+    print("=== Azure AI Agent with Existing Agent ===")
+
+    # Create the client and provider
+    async with (
+        AzureCliCredential() as credential,
+        AgentsClient(endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], credential=credential) as agents_client,
+        AzureAIAgentsProvider(agents_client=agents_client) as provider,
+    ):
+        # Create an agent on the service with default instructions
+        # These instructions will persist on created agent for every run.
+        azure_ai_agent = await agents_client.create_agent(
+            model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            instructions="End each response with [END].",
+        )
+
+        try:
+            # Wrap existing agent instance using provider.as_agent()
+            agent = provider.as_agent(azure_ai_agent)
+
+            query = "How are you?"
+            print(f"User: {query}")
+            result = await agent.run(query)
+            print(f"Agent: {result}\n")
+        finally:
+            # Clean up the agent manually
+            await agents_client.delete_agent(azure_ai_agent.id)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_existing_thread.py

@@ -0,0 +1,59 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from random import randint
+from typing import Annotated
+
+from agent_framework.azure import AzureAIAgentsProvider
+from azure.ai.agents.aio import AgentsClient
+from azure.identity.aio import AzureCliCredential
+from pydantic import Field
+
+"""
+Azure AI Agent with Existing Thread Example
+
+This sample demonstrates working with pre-existing conversation threads
+by providing thread IDs for thread reuse patterns.
+"""
+
+
+def get_weather(
+    location: Annotated[str, Field(description="The location to get the weather for.")],
+) -> str:
+    """Get the weather for a given location."""
+    conditions = ["sunny", "cloudy", "rainy", "stormy"]
+    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
+
+
+async def main() -> None:
+    print("=== Azure AI Agent with Existing Thread ===")
+
+    # Create the client and provider
+    async with (
+        AzureCliCredential() as credential,
+        AgentsClient(endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], credential=credential) as agents_client,
+        AzureAIAgentsProvider(agents_client=agents_client) as provider,
+    ):
+        # Create a thread that will persist
+        created_thread = await agents_client.threads.create()
+
+        try:
+            # Create agent using provider
+            agent = await provider.create_agent(
+                name="WeatherAgent",
+                instructions="You are a helpful weather agent.",
+                tools=get_weather,
+            )
+
+            thread = agent.get_new_thread(service_thread_id=created_thread.id)
+            assert thread.is_initialized
+            result = await agent.run("What's the weather like in Tokyo?", thread=thread)
+            print(f"Result: {result}\n")
+        finally:
+            # Clean up the thread manually
+            await agents_client.threads.delete(created_thread.id)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,51 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from random import randint
+from typing import Annotated
+
+from agent_framework.azure import AzureAIAgentsProvider
+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:
+    print("=== Azure AI Agent with Explicit Settings ===")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentsProvider(
+            project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+            credential=credential,
+        ) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="WeatherAgent",
+            model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            instructions="You are a helpful weather agent.",
+            tools=get_weather,
+        )
+        result = await agent.run("What's the weather like in New York?")
+        print(f"Result: {result}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,80 @@
+# 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 AzureAIAgentsProvider
+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,
+        AzureAIAgentsProvider(agents_client=agents_client) 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
+            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
+            try:
+                if vector_store:
+                    await agents_client.vector_stores.delete(vector_store.id)
+                if file:
+                    await agents_client.files.delete(file.id)
+            except Exception:
+                # Ignore cleanup errors to avoid masking issues
+                pass
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_function_tools.py

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

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

@@ -0,0 +1,70 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Any
+
+from agent_framework import AgentProtocol, AgentResponse, AgentThread, HostedMCPTool
+from agent_framework.azure import AzureAIAgentsProvider
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent with Hosted MCP Example
+
+This sample demonstrates integration of Azure AI Agents with hosted Model Context Protocol (MCP)
+servers, including user approval workflows for function call security.
+"""
+
+
+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."""
+    from agent_framework import ChatMessage
+
+    result = await agent.run(query, thread=thread, store=True)
+    while len(result.user_input_requests) > 0:
+        new_input: list[Any] = []
+        for user_input_needed in result.user_input_requests:
+            print(
+                f"User Input Request for function from {agent.name}: {user_input_needed.function_call.name}"
+                f" with arguments: {user_input_needed.function_call.arguments}"
+            )
+            user_approval = input("Approve function call? (y/n): ")
+            new_input.append(
+                ChatMessage(
+                    role="user",
+                    contents=[user_input_needed.create_response(user_approval.lower() == "y")],
+                )
+            )
+        result = await agent.run(new_input, thread=thread, store=True)
+    return result
+
+
+async def main() -> None:
+    """Example showing Hosted MCP tools for a Azure AI Agent."""
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentsProvider(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=HostedMCPTool(
+                name="Microsoft Learn MCP",
+                url="https://learn.microsoft.com/api/mcp",
+            ),
+        )
+        thread = agent.get_new_thread()
+        # First query
+        query1 = "How to create an Azure storage account using az cli?"
+        print(f"User: {query1}")
+        result1 = await handle_approvals_with_thread(query1, agent, thread)
+        print(f"{agent.name}: {result1}\n")
+        print("\n=======================================\n")
+        # Second query
+        query2 = "What is Microsoft Agent Framework?"
+        print(f"User: {query2}")
+        result2 = await handle_approvals_with_thread(query2, agent, thread)
+        print(f"{agent.name}: {result2}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

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

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

@@ -0,0 +1,99 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from datetime import datetime, timezone
+from typing import Any
+
+from agent_framework import (
+    AgentProtocol,
+    AgentThread,
+    HostedMCPTool,
+    HostedWebSearchTool,
+)
+from agent_framework.azure import AzureAIAgentsProvider
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent with Multiple Tools Example
+
+This sample demonstrates integrating multiple tools (MCP and Web Search) with Azure AI Agents,
+including user approval workflows for function call security.
+
+Prerequisites:
+1. Set AZURE_AI_PROJECT_ENDPOINT and AZURE_AI_MODEL_DEPLOYMENT_NAME environment variables
+2. For Bing search functionality, set BING_CONNECTION_ID environment variable to your Bing connection ID
+   Example: BING_CONNECTION_ID="/subscriptions/{subscription-id}/resourceGroups/{resource-group}/
+            providers/Microsoft.CognitiveServices/accounts/{ai-service-name}/projects/{project-name}/
+            connections/{connection-name}"
+
+To set up Bing Grounding:
+1. Go to Azure AI Foundry portal (https://ai.azure.com)
+2. Navigate to your project's "Connected resources" section
+3. Add a new connection for "Grounding with Bing Search"
+4. Copy the connection ID and set it as the BING_CONNECTION_ID environment variable
+"""
+
+
+def get_time() -> str:
+    """Get the current UTC time."""
+    current_time = datetime.now(timezone.utc)
+    return f"The current UTC time is {current_time.strftime('%Y-%m-%d %H:%M:%S')}."
+
+
+async def handle_approvals_with_thread(query: str, agent: "AgentProtocol", thread: "AgentThread"):
+    """Here we let the thread deal with the previous responses, and we just rerun with the approval."""
+    from agent_framework import ChatMessage
+
+    result = await agent.run(query, thread=thread, store=True)
+    while len(result.user_input_requests) > 0:
+        new_input: list[Any] = []
+        for user_input_needed in result.user_input_requests:
+            print(
+                f"User Input Request for function from {agent.name}: {user_input_needed.function_call.name}"
+                f" with arguments: {user_input_needed.function_call.arguments}"
+            )
+            user_approval = input("Approve function call? (y/n): ")
+            new_input.append(
+                ChatMessage(
+                    role="user",
+                    contents=[user_input_needed.create_response(user_approval.lower() == "y")],
+                )
+            )
+        result = await agent.run(new_input, thread=thread, store=True)
+    return result
+
+
+async def main() -> None:
+    """Example showing Hosted MCP tools for a Azure AI Agent."""
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentsProvider(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=[
+                HostedMCPTool(
+                    name="Microsoft Learn MCP",
+                    url="https://learn.microsoft.com/api/mcp",
+                ),
+                HostedWebSearchTool(count=5),
+                get_time,
+            ],
+        )
+        thread = agent.get_new_thread()
+        # First query
+        query1 = "How to create an Azure storage account using az cli and what time is it?"
+        print(f"User: {query1}")
+        result1 = await handle_approvals_with_thread(query1, agent, thread)
+        print(f"{agent.name}: {result1}\n")
+        print("\n=======================================\n")
+        # Second query
+        query2 = "What is Microsoft Agent Framework and use a web search to see what is Reddit saying about it?"
+        print(f"User: {query2}")
+        result2 = await handle_approvals_with_thread(query2, agent, thread)
+        print(f"{agent.name}: {result2}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_openapi_tools.py

@@ -0,0 +1,93 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import json
+from pathlib import Path
+from typing import Any
+
+from agent_framework.azure import AzureAIAgentsProvider
+from azure.ai.agents.models import OpenApiAnonymousAuthDetails, OpenApiTool
+from azure.identity.aio import AzureCliCredential
+
+"""
+The following sample demonstrates how to create a simple, Azure AI agent that
+uses OpenAPI tools to answer user questions.
+"""
+
+# Simulate a conversation with the agent
+USER_INPUTS = [
+    "What is the name and population of the country that uses currency with abbreviation THB?",
+    "What is the current weather in the capital city of that country?",
+]
+
+
+def load_openapi_specs() -> tuple[dict[str, Any], dict[str, Any]]:
+    """Load OpenAPI specification files."""
+    resources_path = Path(__file__).parent.parent / "resources"
+
+    with open(resources_path / "weather.json") as weather_file:
+        weather_spec = json.load(weather_file)
+
+    with open(resources_path / "countries.json") as countries_file:
+        countries_spec = json.load(countries_file)
+
+    return weather_spec, countries_spec
+
+
+async def main() -> None:
+    """Main function demonstrating Azure AI agent with OpenAPI tools."""
+    # 1. Load OpenAPI specifications (synchronous operation)
+    weather_openapi_spec, countries_openapi_spec = load_openapi_specs()
+
+    # 2. Use AzureAIAgentsProvider for agent creation and management
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentsProvider(credential=credential) as provider,
+    ):
+        # 3. Create OpenAPI tools using Azure AI's OpenApiTool
+        auth = OpenApiAnonymousAuthDetails()
+
+        openapi_weather = OpenApiTool(
+            name="get_weather",
+            spec=weather_openapi_spec,
+            description="Retrieve weather information for a location using wttr.in service",
+            auth=auth,
+        )
+
+        openapi_countries = OpenApiTool(
+            name="get_country_info",
+            spec=countries_openapi_spec,
+            description="Retrieve country information including population and capital city",
+            auth=auth,
+        )
+
+        # 4. Create an agent with OpenAPI tools
+        # Note: We need to pass the Azure AI native OpenApiTool definitions directly
+        # since the agent framework doesn't have a HostedOpenApiTool wrapper yet
+        agent = await provider.create_agent(
+            name="OpenAPIAgent",
+            instructions=(
+                "You are a helpful assistant that can search for country information "
+                "and weather data using APIs. When asked about countries, use the country "
+                "API to find information. When asked about weather, use the weather API. "
+                "Provide clear, informative answers based on the API results."
+            ),
+            # Pass the raw tool definitions from Azure AI's OpenApiTool
+            tools=[*openapi_countries.definitions, *openapi_weather.definitions],
+        )
+
+        # 5. Simulate conversation with the agent maintaining thread context
+        print("=== Azure AI Agent with OpenAPI Tools ===\n")
+
+        # Create a thread to maintain conversation context across multiple runs
+        thread = agent.get_new_thread()
+
+        for user_input in USER_INPUTS:
+            print(f"User: {user_input}")
+            # Pass the thread to maintain context across multiple agent.run() calls
+            response = await agent.run(user_input, thread=thread)
+            print(f"Agent: {response.text}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,85 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework.azure import AzureAIAgentsProvider
+from azure.identity.aio import AzureCliCredential
+from pydantic import BaseModel, ConfigDict
+
+"""
+Azure AI Agent Provider Response Format Example
+
+This sample demonstrates using AzureAIAgentsProvider with response_format
+for structured outputs in two ways:
+1. Setting default response_format at agent creation time (default_options)
+2. Overriding response_format at runtime (options parameter in agent.run)
+"""
+
+
+class WeatherInfo(BaseModel):
+    """Structured weather information."""
+
+    location: str
+    temperature: int
+    conditions: str
+    recommendation: str
+    model_config = ConfigDict(extra="forbid")
+
+
+class CityInfo(BaseModel):
+    """Structured city information."""
+
+    city_name: str
+    population: int
+    country: str
+    model_config = ConfigDict(extra="forbid")
+
+
+async def main() -> None:
+    """Example of using response_format at creation time and runtime."""
+
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentsProvider(credential=credential) as provider,
+    ):
+        # Create agent with default response_format (WeatherInfo)
+        agent = await provider.create_agent(
+            name="StructuredReporter",
+            instructions="Return structured JSON based on the requested format.",
+            default_options={"response_format": WeatherInfo},
+        )
+
+        # Request 1: Uses default response_format from agent creation
+        print("--- Request 1: Using default response_format (WeatherInfo) ---")
+        query1 = "What's the weather like in Paris today?"
+        print(f"User: {query1}")
+
+        result1 = await agent.run(query1)
+
+        if weather := result1.try_parse_value(WeatherInfo):
+            print("Agent:")
+            print(f"  Location: {weather.location}")
+            print(f"  Temperature: {weather.temperature}")
+            print(f"  Conditions: {weather.conditions}")
+            print(f"  Recommendation: {weather.recommendation}")
+        else:
+            print(f"Failed to parse response: {result1.text}")
+
+        # Request 2: Override response_format at runtime with CityInfo
+        print("\n--- Request 2: Runtime override with CityInfo ---")
+        query2 = "Tell me about Tokyo."
+        print(f"User: {query2}")
+
+        result2 = await agent.run(query2, options={"response_format": CityInfo})
+
+        if city := result2.try_parse_value(CityInfo):
+            print("Agent:")
+            print(f"  City: {city.city_name}")
+            print(f"  Population: {city.population}")
+            print(f"  Country: {city.country}")
+        else:
+            print(f"Failed to parse response: {result2.text}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,162 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from random import randint
+from typing import Annotated
+
+from agent_framework import AgentThread
+from agent_framework.azure import AzureAIAgentsProvider
+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 Agents, comparing
+automatic thread creation with explicit thread management for persistent context.
+"""
+
+
+def get_weather(
+    location: Annotated[str, Field(description="The location to get the weather for.")],
+) -> str:
+    """Get the weather for a given location."""
+    conditions = ["sunny", "cloudy", "rainy", "stormy"]
+    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
+
+
+async def example_with_automatic_thread_creation() -> None:
+    """Example showing automatic thread creation (service-managed thread)."""
+    print("=== Automatic Thread Creation Example ===")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentsProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="WeatherAgent",
+            instructions="You are a helpful weather agent.",
+            tools=get_weather,
+        )
+
+        # First conversation - no thread provided, will be created automatically
+        first_query = "What's the weather like in Seattle?"
+        print(f"User: {first_query}")
+        first_result = await agent.run(first_query)
+        print(f"Agent: {first_result.text}")
+
+        # Second conversation - still no thread provided, will create another new thread
+        second_query = "What was the last city I asked about?"
+        print(f"\nUser: {second_query}")
+        second_result = await agent.run(second_query)
+        print(f"Agent: {second_result.text}")
+        print("Note: Each call creates a separate thread, so the agent doesn't remember previous context.\n")
+
+
+async def example_with_thread_persistence() -> None:
+    """Example showing thread persistence across multiple conversations."""
+    print("=== Thread Persistence Example ===")
+    print("Using the same thread across multiple conversations to maintain context.\n")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentsProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="WeatherAgent",
+            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
+        first_query = "What's the weather like in Tokyo?"
+        print(f"User: {first_query}")
+        first_result = await agent.run(first_query, thread=thread)
+        print(f"Agent: {first_result.text}")
+
+        # Second conversation using the same thread - maintains context
+        second_query = "How about London?"
+        print(f"\nUser: {second_query}")
+        second_result = await agent.run(second_query, thread=thread)
+        print(f"Agent: {second_result.text}")
+
+        # Third conversation - agent should remember both previous cities
+        third_query = "Which of the cities I asked about has better weather?"
+        print(f"\nUser: {third_query}")
+        third_result = await agent.run(third_query, thread=thread)
+        print(f"Agent: {third_result.text}")
+        print("Note: The agent remembers context from previous messages in the same thread.\n")
+
+
+async def example_with_existing_thread_id() -> None:
+    """Example showing how to work with an existing thread ID from the service."""
+    print("=== Existing Thread ID Example ===")
+    print("Using a specific thread ID to continue an existing conversation.\n")
+
+    # First, create a conversation and capture the thread ID
+    existing_thread_id = None
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentsProvider(credential=credential) as provider,
+    ):
+        agent = await provider.create_agent(
+            name="WeatherAgent",
+            instructions="You are a helpful weather agent.",
+            tools=get_weather,
+        )
+
+        # Start a conversation and get the thread ID
+        thread = agent.get_new_thread()
+        first_query = "What's the weather in Paris?"
+        print(f"User: {first_query}")
+        first_result = await agent.run(first_query, thread=thread)
+        print(f"Agent: {first_result.text}")
+
+        # The thread ID is set after the first response
+        existing_thread_id = thread.service_thread_id
+        print(f"Thread ID: {existing_thread_id}")
+
+    if existing_thread_id:
+        print("\n--- Continuing with the same thread ID in a new agent instance ---")
+
+        # Create a new provider and agent but use the existing thread ID
+        async with (
+            AzureCliCredential() as credential,
+            AzureAIAgentsProvider(credential=credential) as provider,
+        ):
+            agent = await provider.create_agent(
+                name="WeatherAgent",
+                instructions="You are a helpful weather agent.",
+                tools=get_weather,
+            )
+
+            # Create a thread with the existing ID
+            thread = AgentThread(service_thread_id=existing_thread_id)
+
+            second_query = "What was the last city I asked about?"
+            print(f"User: {second_query}")
+            second_result = await agent.run(second_query, thread=thread)
+            print(f"Agent: {second_result.text}")
+            print("Note: The agent continues the conversation from the previous thread.\n")
+
+
+async def main() -> None:
+    print("=== Azure AI Chat Client Agent Thread Management Examples ===\n")
+
+    await example_with_automatic_thread_creation()
+    await example_with_thread_persistence()
+    await example_with_existing_thread_id()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())