Python: [BREAKING] Python: Provider-leading client design & OpenAI package extraction (#4818)

* Python: Provider-leading client design & OpenAI package extraction Major refactoring of the Python Agent Framework client architecture: - Extract OpenAI clients into new `agent-framework-openai` package - Core package no longer depends on openai, azure-identity, azure-ai-projects - Rename clients for discoverability: OpenAIResponsesClient → OpenAIChatClient, OpenAIChatClient → OpenAIChatCompletionClient - Unify `model_id`/`deployment_name`/`model_deployment_name` → `model` param - New FoundryChatClient for Azure AI Foundry Responses API - New FoundryAgent/FoundryAgentClient for connecting to pre-configured Foundry agents - Remove OpenAIBase/OpenAIConfigMixin from non-deprecated client MRO - Deprecate AzureOpenAI* clients, AzureAIClient, OpenAIAssistantsClient - Reorganize samples: azure_openai+azure_ai+azure_ai_agent → azure/ - ADR-0020: Provider-Leading Client Design Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: missing Agent imports in samples, .model_id → .model in foundry_local sample Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: CI failures — mypy errors, coverage targets, sample imports - azure-ai mypy: add type ignores for TypedDict total=, model arg, forward ref - Coverage: replace core.azure/openai targets with openai package target - project_provider: add type annotation for opts dict Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: populate openai .pyi stub, fix broken README links, coverage targets Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fixes * updated observabilitty * reset azure init.pyi * fix errors * updated adr number * fix foundry local * fixed not renamed docstrings and comments, and added deprecated markers to old classes * fix tests and pyprojects * fix test vars * updated function tests * update durable * updated test setup for functions * Fix Foundry auth in workflow samples Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Stabilize Python integration workflows Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Update hosting samples for Foundry Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Trigger full CI rerun Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Trigger CI rerun again Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * trigger rerun * trigger rerun * fix for litellm * undo durabletask changes * Move Foundry APIs into foundry namespace Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix Foundry pyproject formatting Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Split provider samples by Foundry surface Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Restore hosting sample requirements Also fix the Foundry Local sample link after the provider sample move. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * updated tests * udpated foundry integration tests * removed dist from azurefunctions tests * Use separate Foundry clients for concurrent agents Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix client setup in azfunc and durable * disabled two tests * updated setup for some function and durable tests * improved azure openai setup with new clients * ignore deprecated * fixes * skip 11 * remove openai assistants int tests --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-06-16 21:04:09 +08:00 · 2026-03-25 10:56:29 +01:00
parent 4b533608b6
commit 5e056b672e
485 changed files with 9784 additions and 12084 deletions
@@ -0,0 +1,48 @@
+# Foundry Provider Samples
+
+This folder contains Azure AI Foundry and Foundry Local samples for Agent Framework.
+
+## FoundryAgent Samples
+
+| File | Description |
+|------|-------------|
+| [`foundry_agent_basic.py`](foundry_agent_basic.py) | Foundry Agent basic example |
+| [`foundry_agent_custom_client.py`](foundry_agent_custom_client.py) | Foundry Agent custom client configuration |
+| [`foundry_agent_hosted.py`](foundry_agent_hosted.py) | Foundry Agent for hosted agents |
+| [`foundry_agent_with_env_vars.py`](foundry_agent_with_env_vars.py) | Foundry Agent using environment variables |
+| [`foundry_agent_with_function_tools.py`](foundry_agent_with_function_tools.py) | Foundry Agent with local function tools |
+
+## FoundryChatClient Samples
+
+| File | Description |
+|------|-------------|
+| [`foundry_chat_client.py`](foundry_chat_client.py) | Foundry Chat Client with project endpoint example |
+| [`foundry_chat_client_basic.py`](foundry_chat_client_basic.py) | Foundry Chat Client basic example |
+| [`foundry_chat_client_code_interpreter_files.py`](foundry_chat_client_code_interpreter_files.py) | Foundry Chat Client with code interpreter and files |
+| [`foundry_chat_client_image_analysis.py`](foundry_chat_client_image_analysis.py) | Foundry Chat Client with image analysis |
+| [`foundry_chat_client_with_code_interpreter.py`](foundry_chat_client_with_code_interpreter.py) | Foundry Chat Client with code interpreter |
+| [`foundry_chat_client_with_explicit_settings.py`](foundry_chat_client_with_explicit_settings.py) | Foundry Chat Client with explicit settings |
+| [`foundry_chat_client_with_file_search.py`](foundry_chat_client_with_file_search.py) | Foundry Chat Client with file search |
+| [`foundry_chat_client_with_function_tools.py`](foundry_chat_client_with_function_tools.py) | Foundry Chat Client with function tools |
+| [`foundry_chat_client_with_hosted_mcp.py`](foundry_chat_client_with_hosted_mcp.py) | Foundry Chat Client with hosted MCP |
+| [`foundry_chat_client_with_local_mcp.py`](foundry_chat_client_with_local_mcp.py) | Foundry Chat Client with local MCP |
+| [`foundry_chat_client_with_session.py`](foundry_chat_client_with_session.py) | Foundry Chat Client with session management |
+
+## FoundryLocalClient Samples
+
+### Prerequisites
+
+1. Install Foundry Local and required local runtime components.
+2. Install the connector package:
+
+   ```bash
+   pip install agent-framework-foundry-local --pre
+   ```
+
+| File | Description |
+|------|-------------|
+| [`foundry_local_agent.py`](foundry_local_agent.py) | Basic Foundry Local agent usage with streaming and non-streaming responses, plus function tool calling. |
+
+### Environment Variables
+
+- `FOUNDRY_LOCAL_MODEL_ID`: Optional model alias/ID to use by default when `model_id` is not passed to `FoundryLocalClient`.
@@ -0,0 +1,42 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework.foundry import FoundryAgent
+from azure.identity import AzureCliCredential
+
+"""
+Foundry Agent — Connect to a pre-configured agent in Microsoft Foundry
+
+This sample shows the simplest way to connect to an existing PromptAgent
+in Azure AI Foundry and run it. The agent's instructions, model, and hosted
+tools are all configured on the service — you just connect and run.
+
+Environment variables:
+    FOUNDRY_PROJECT_ENDPOINT — Azure AI Foundry project endpoint
+    FOUNDRY_AGENT_NAME       — Name of the agent in Foundry
+    FOUNDRY_AGENT_VERSION    — Version of the agent (for PromptAgents)
+"""
+
+
+async def main() -> None:
+    agent = FoundryAgent(
+        project_endpoint="https://your-project.services.ai.azure.com",
+        agent_name="my-prompt-agent",
+        agent_version="1.0",
+        credential=AzureCliCredential(),
+    )
+
+    result = await agent.run("What is the capital of France?")
+    print(f"Agent: {result}")
+
+    # Streaming
+    print("Agent (streaming): ", end="", flush=True)
+    async for chunk in agent.run("Tell me a fun fact.", stream=True):
+        if chunk.text:
+            print(chunk.text, end="", flush=True)
+    print()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,61 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import Agent
+from agent_framework.foundry import FoundryAgent, RawFoundryAgentChatClient
+from azure.identity import AzureCliCredential
+
+"""
+Foundry Agent — Custom client configuration
+
+This sample demonstrates three ways to customize the FoundryAgent client layer:
+
+1. Default: FoundryAgent creates a RawFoundryAgentChatClient (full middleware) internally
+2. client_type: Pass RawFoundryAgentChatClient for no client middleware
+3. Composition: Use Agent(client=RawFoundryAgentChatClient(...)) directly
+
+Environment variables:
+    FOUNDRY_PROJECT_ENDPOINT — Azure AI Foundry project endpoint
+    FOUNDRY_AGENT_NAME       — Name of the agent in Foundry
+    FOUNDRY_AGENT_VERSION    — Version of the agent
+"""
+
+
+async def main() -> None:
+    # Option 1: Default — full middleware on both agent and client
+    agent = FoundryAgent(
+        project_endpoint="https://your-project.services.ai.azure.com",
+        agent_name="my-agent",
+        agent_version="1.0",
+        credential=AzureCliCredential(),
+    )
+    result = await agent.run("Hello from the default setup!")
+    print(f"Default: {result}\n")
+
+    # Option 2: Raw client — no client-level middleware (agent middleware still active)
+    agent_raw_client = FoundryAgent(
+        project_endpoint="https://your-project.services.ai.azure.com",
+        agent_name="my-agent",
+        agent_version="1.0",
+        credential=AzureCliCredential(),
+        client_type=RawFoundryAgentChatClient,
+    )
+    result = await agent_raw_client.run("Hello from raw client!")
+    print(f"Raw client: {result}\n")
+
+    # Option 3: Composition — use Agent(client=...) directly
+    # this will not run the checks that the `FoundryAgent` does on things like tools.
+    client = RawFoundryAgentChatClient(
+        project_endpoint="https://your-project.services.ai.azure.com",
+        agent_name="my-agent",
+        agent_version="1.0",
+        credential=AzureCliCredential(),
+    )
+    agent_composed = Agent(client=client)
+    result = await agent_composed.run("Hello from composed setup!")
+    print(f"Composed: {result}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,33 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework.foundry import FoundryAgent
+from azure.identity import AzureCliCredential
+
+"""
+Foundry Agent — Connect to a HostedAgent (no version needed)
+
+HostedAgents in Azure AI Foundry are pre-deployed agents that don't require
+a version number. You only need the agent name to connect.
+
+Environment variables:
+    FOUNDRY_PROJECT_ENDPOINT — Azure AI Foundry project endpoint
+    FOUNDRY_AGENT_NAME       — Name of the hosted agent
+"""
+
+
+async def main() -> None:
+    # HostedAgents don't need agent_version
+    agent = FoundryAgent(
+        project_endpoint="https://your-project.services.ai.azure.com",
+        agent_name="my-hosted-agent",
+        credential=AzureCliCredential(),
+    )
+
+    result = await agent.run("Summarize the latest news about AI.")
+    print(f"Agent: {result}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,40 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+
+from agent_framework.foundry import FoundryAgent
+from azure.identity import AzureCliCredential
+
+"""
+Foundry Agent with Environment Variables
+
+This sample shows the recommended pattern for advanced samples that use
+environment variables for configuration.
+
+Environment variables:
+    FOUNDRY_PROJECT_ENDPOINT — Azure AI Foundry project endpoint
+    FOUNDRY_AGENT_NAME       — Name of the agent in Foundry
+    FOUNDRY_AGENT_VERSION    — Version of the agent (optional, for PromptAgents)
+"""
+
+
+async def main() -> None:
+    agent = FoundryAgent(
+        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+        agent_name=os.environ["FOUNDRY_AGENT_NAME"],
+        agent_version=os.environ.get("FOUNDRY_AGENT_VERSION"),
+        credential=AzureCliCredential(),
+    )
+
+    session = agent.create_session()
+
+    result = await agent.run("Hello! My name is Alice.", session=session)
+    print(f"Agent: {result}\n")
+
+    result = await agent.run("What's my name?", session=session)
+    print(f"Agent: {result}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,50 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Annotated
+
+from agent_framework import tool
+from agent_framework.foundry import FoundryAgent
+from azure.identity import AzureCliCredential
+from pydantic import Field
+
+"""
+Foundry Agent with Local Function Tools
+
+This sample shows how to connect to a Foundry agent and provide local function
+tools. The Foundry agent must already have these tools defined in its configuration
+(as declaration-only tools). The local implementations are matched by name.
+
+Only FunctionTool objects are accepted — hosted tools (code interpreter, file search,
+web search, etc.) must be configured on the agent definition in the service.
+
+Environment variables:
+    FOUNDRY_PROJECT_ENDPOINT — Azure AI Foundry project endpoint
+    FOUNDRY_AGENT_NAME       — Name of the agent in Foundry
+    FOUNDRY_AGENT_VERSION    — Version of the agent
+"""
+
+
+@tool(approval_mode="never_require")
+def get_weather(
+    location: Annotated[str, Field(description="The city to get weather for.")],
+) -> str:
+    """Get the current weather for a location."""
+    return f"The weather in {location} is sunny, 22°C."
+
+
+async def main() -> None:
+    agent = FoundryAgent(
+        project_endpoint="https://your-project.services.ai.azure.com",
+        agent_name="my-weather-agent",
+        agent_version="1.0",
+        credential=AzureCliCredential(),
+        tools=[get_weather],
+    )
+
+    result = await agent.run("What's the weather in Paris?")
+    print(f"Agent: {result}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,115 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from random import randint
+from typing import Annotated
+
+from agent_framework import Agent, tool
+from agent_framework.foundry import FoundryChatClient
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+"""
+Foundry Chat Client with Project Endpoint Example
+
+This sample demonstrates how to create a FoundryChatClient using a
+Foundry project endpoint. Instead of providing a service endpoint
+directly, you provide a Foundry project endpoint and the client is created via
+the Azure AI Foundry project SDK.
+
+This requires:
+- The `FOUNDRY_PROJECT_ENDPOINT` environment variable set to your Foundry project endpoint.
+- The `FOUNDRY_MODEL` environment variable set to the model deployment name.
+"""
+
+
+@tool(approval_mode="never_require")
+def get_weather(
+    location: Annotated[str, "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 ===")
+
+    # 1. Create the FoundryChatClient using a Foundry project endpoint.
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    credential = AzureCliCredential()
+    _client = FoundryChatClient(
+        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+        model=os.environ["FOUNDRY_MODEL"],
+        credential=credential,
+    )
+    agent = Agent(
+        client=_client,
+        instructions="You are a helpful weather agent.",
+        tools=get_weather,
+    )
+
+    # 2. Run a query and print the result.
+    query = "What's the weather like in Seattle?"
+    print(f"User: {query}")
+    result = await agent.run(query)
+    print(f"Result: {result}\n")
+
+
+async def streaming_example() -> None:
+    """Example of streaming response (get results as they are generated)."""
+    print("=== Streaming Response Example ===")
+
+    # 1. Create the FoundryChatClient using a Foundry project endpoint.
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    credential = AzureCliCredential()
+    _client = FoundryChatClient(
+        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+        model=os.environ["FOUNDRY_MODEL"],
+        credential=credential,
+    )
+    agent = Agent(
+        client=_client,
+        instructions="You are a helpful weather agent.",
+        tools=get_weather,
+    )
+
+    # 2. Stream the response and print each chunk as it arrives.
+    query = "What's the weather like in Portland?"
+    print(f"User: {query}")
+    print("Agent: ", end="", flush=True)
+    async for chunk in agent.run(query, stream=True):
+        if chunk.text:
+            print(chunk.text, end="", flush=True)
+    print("\n")
+
+
+async def main() -> None:
+    print("=== Foundry Chat Client with Project Endpoint Example ===")
+
+    await non_streaming_example()
+    await streaming_example()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+
+"""
+Sample output:
+=== Foundry Chat Client with Project Endpoint Example ===
+=== Non-streaming Response Example ===
+User: What's the weather like in Seattle?
+Result: The weather in Seattle is cloudy with a high of 18°C.
+
+=== Streaming Response Example ===
+User: What's the weather like in Portland?
+Agent: The weather in Portland is sunny with a high of 25°C.
+"""
@@ -0,0 +1,86 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from random import randint
+from typing import Annotated
+
+from agent_framework import Agent, tool
+from agent_framework.foundry import FoundryChatClient
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+from pydantic import Field
+
+# Load environment variables from .env file
+load_dotenv()
+
+"""
+Foundry Chat Client Basic Example
+
+This sample demonstrates basic usage of FoundryChatClient for structured
+response generation, showing both streaming and non-streaming responses.
+
+This uses a deployed model in Foundry, with the Responses API endpoint of Foundry.
+The client has full support for tools, response formats, etc.
+"""
+
+
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
+# see samples/02-agents/tools/function_tool_with_approval.py
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
+@tool(approval_mode="never_require")
+def get_weather(
+    location: Annotated[str, Field(description="The location to get the weather for.")],
+) -> str:
+    """Get the weather for a given location."""
+    conditions = ["sunny", "cloudy", "rainy", "stormy"]
+    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
+
+
+async def non_streaming_example() -> None:
+    """Example of non-streaming response (get the complete result at once)."""
+    print("=== Non-streaming Response Example ===")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = Agent(
+        client=FoundryChatClient(credential=AzureCliCredential()),
+        instructions="You are a helpful weather agent.",
+        tools=get_weather,
+    )
+
+    query = "What's the weather like in Seattle?"
+    print(f"User: {query}")
+    result = await agent.run(query)
+    print(f"Result: {result}\n")
+
+
+async def streaming_example() -> None:
+    """Example of streaming response (get results as they are generated)."""
+    print("=== Streaming Response Example ===")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = Agent(
+        client=FoundryChatClient(credential=AzureCliCredential()),
+        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(query, stream=True):
+        if chunk.text:
+            print(chunk.text, end="", flush=True)
+    print("\n")
+
+
+async def main() -> None:
+    print("=== Foundry Chat Client Basic Example ===")
+
+    await non_streaming_example()
+    await streaming_example()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,104 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+import tempfile
+
+from agent_framework import Agent
+from agent_framework.foundry import FoundryChatClient
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+from openai import AsyncAzureOpenAI
+
+# Load environment variables from .env file
+load_dotenv()
+
+"""
+Foundry Chat Client with Code Interpreter and Files Example
+
+This sample demonstrates using get_code_interpreter_tool() with Responses on Foundry
+for Python code execution and data analysis with uploaded files.
+"""
+
+# Helper functions
+
+
+async def create_sample_file_and_upload(openai_client: AsyncAzureOpenAI) -> tuple[str, str]:
+    """Create a sample CSV file and upload it for Foundry code interpreter use."""
+    csv_data = """name,department,salary,years_experience
+Alice Johnson,Engineering,95000,5
+Bob Smith,Sales,75000,3
+Carol Williams,Engineering,105000,8
+David Brown,Marketing,68000,2
+Emma Davis,Sales,82000,4
+Frank Wilson,Engineering,88000,6
+"""
+
+    # Create temporary CSV file
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".csv", delete=False) as temp_file:
+        temp_file.write(csv_data)
+        temp_file_path = temp_file.name
+
+    # Upload file for the code interpreter tool
+    print("Uploading file for code interpreter...")
+    with open(temp_file_path, "rb") as file:
+        uploaded_file = await openai_client.files.create(
+            file=file,
+            purpose="assistants",  # Required for code interpreter
+        )
+
+    print(f"File uploaded with ID: {uploaded_file.id}")
+    return temp_file_path, uploaded_file.id
+
+
+async def cleanup_files(openai_client: AsyncAzureOpenAI, temp_file_path: str, file_id: str) -> None:
+    """Clean up both local temporary file and uploaded file."""
+    # Clean up: delete the uploaded file
+    await openai_client.files.delete(file_id)
+    print(f"Cleaned up uploaded file: {file_id}")
+
+    # Clean up temporary local file
+    os.unlink(temp_file_path)
+    print(f"Cleaned up temporary file: {temp_file_path}")
+
+
+async def main() -> None:
+    print("=== Foundry Chat Client with Code Interpreter and File Upload ===")
+
+    # Initialize the underlying OpenAI client for file operations
+    credential = AzureCliCredential()
+
+    async def get_token():
+        token = credential.get_token("https://cognitiveservices.azure.com/.default")
+        return token.token
+
+    openai_client = AsyncAzureOpenAI(
+        azure_ad_token_provider=get_token,
+        api_version="2024-05-01-preview",
+    )
+
+    temp_file_path, file_id = await create_sample_file_and_upload(openai_client)
+
+    # Create agent using FoundryChatClient
+    client = FoundryChatClient(credential=credential)
+
+    # Create code interpreter tool with file access
+    code_interpreter_tool = client.get_code_interpreter_tool(file_ids=[file_id])
+
+    agent = Agent(
+        client=client,
+        instructions="You are a helpful assistant that can analyze data files using Python code.",
+        tools=[code_interpreter_tool],
+    )
+
+    # Test the code interpreter with the uploaded file
+    query = "Analyze the employee data in the uploaded CSV file. Calculate average salary by department."
+    print(f"User: {query}")
+    result = await agent.run(query)
+    print(f"Agent: {result.text}")
+
+    await cleanup_files(openai_client, temp_file_path, file_id)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,44 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import Agent, Content
+from agent_framework.foundry import FoundryChatClient
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+"""
+Foundry Chat Client with Image Analysis Example
+
+This sample demonstrates using FoundryChatClient for image analysis and vision tasks,
+showing multi-modal messages combining text and image content.
+"""
+
+
+async def main():
+    print("=== Foundry Chat Client with Image Analysis ===")
+
+    # 1. Create a Foundry-backed agent with vision capabilities
+    agent = Agent(
+        client=FoundryChatClient(credential=AzureCliCredential()),
+        name="VisionAgent",
+        instructions="You are a image analysist, you get a image and need to respond with what you see in the picture.",
+    )
+
+    # 2. Get the agent's response
+    print("User: What do you see in this image? [Image provided]")
+    result = await agent.run(
+        Content.from_uri(
+            uri="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800",
+            media_type="image/jpeg",
+        )
+    )
+    print(f"Agent: {result.text}")
+    print()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,57 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import Agent, ChatResponse
+from agent_framework.foundry import FoundryChatClient
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+from openai.types.responses.response import Response as OpenAIResponse
+from openai.types.responses.response_code_interpreter_tool_call import ResponseCodeInterpreterToolCall
+
+# Load environment variables from .env file
+load_dotenv()
+
+"""
+Foundry Chat Client with Code Interpreter Example
+
+This sample demonstrates using get_code_interpreter_tool() with FoundryChatClient
+for Python code execution and mathematical problem solving.
+"""
+
+
+async def main() -> None:
+    """Example showing how to use the code interpreter tool with FoundryChatClient."""
+    print("=== Foundry Chat Client with Code Interpreter Example ===")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    client = FoundryChatClient(credential=AzureCliCredential())
+
+    # Create code interpreter tool using instance method
+    code_interpreter_tool = client.get_code_interpreter_tool()
+
+    agent = Agent(
+        client=client,
+        instructions="You are a helpful assistant that can write and execute Python code to solve problems.",
+        tools=[code_interpreter_tool],
+    )
+
+    query = "Use code to calculate the factorial of 100?"
+    print(f"User: {query}")
+    result = await agent.run(query)
+    print(f"Result: {result}\n")
+
+    if (
+        isinstance(result.raw_representation, ChatResponse)
+        and isinstance(result.raw_representation.raw_representation, OpenAIResponse)
+        and len(result.raw_representation.raw_representation.output) > 0
+        and isinstance(result.raw_representation.raw_representation.output[0], ResponseCodeInterpreterToolCall)
+    ):
+        generated_code = result.raw_representation.raw_representation.output[0].code
+
+        print(f"Generated code:\n{generated_code}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,58 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from random import randint
+from typing import Annotated
+
+from agent_framework import Agent, tool
+from agent_framework.foundry import FoundryChatClient
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+from pydantic import Field
+
+# Load environment variables from .env file
+load_dotenv()
+
+"""
+Foundry Chat Client with Explicit Settings Example
+
+This sample demonstrates creating FoundryChatClient with explicit project endpoint and
+model settings rather than relying on environment variable defaults.
+"""
+
+
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
+# see samples/02-agents/tools/function_tool_with_approval.py
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
+@tool(approval_mode="never_require")
+def get_weather(
+    location: Annotated[str, Field(description="The location to get the weather for.")],
+) -> str:
+    """Get the weather for a given location."""
+    conditions = ["sunny", "cloudy", "rainy", "stormy"]
+    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
+
+
+async def main() -> None:
+    print("=== Foundry Chat Client with Explicit Settings ===")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    _client = FoundryChatClient(
+        model=os.environ["FOUNDRY_MODEL"],
+        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+        credential=AzureCliCredential(),
+    )
+    agent = Agent(
+        client=_client,
+        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())
@@ -0,0 +1,81 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import contextlib
+
+from agent_framework import Agent
+from agent_framework.foundry import FoundryChatClient
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+"""
+Foundry Chat Client with File Search Example
+
+This sample demonstrates using get_file_search_tool() with FoundryChatClient
+for direct document-based question answering and information retrieval.
+
+Prerequisites:
+- Set environment variables:
+  - FOUNDRY_PROJECT_ENDPOINT: Your Foundry project endpoint URL
+  - FOUNDRY_MODEL: Your Responses API deployment name
+- Authenticate via 'az login' for AzureCliCredential
+"""
+
+# Helper functions
+
+
+async def create_vector_store(client: FoundryChatClient) -> tuple[str, str]:
+    """Create a vector store with sample documents."""
+    file = await client.client.files.create(
+        file=("todays_weather.txt", b"The weather today is sunny with a high of 75F."), purpose="assistants"
+    )
+    vector_store = await client.client.vector_stores.create(
+        name="knowledge_base",
+        expires_after={"anchor": "last_active_at", "days": 1},
+    )
+    result = await client.client.vector_stores.files.create_and_poll(vector_store_id=vector_store.id, file_id=file.id)
+    if result.last_error is not None:
+        raise Exception(f"Vector store file processing failed with status: {result.last_error.message}")
+
+    return file.id, vector_store.id
+
+
+async def delete_vector_store(client: FoundryChatClient, file_id: str, vector_store_id: str) -> None:
+    """Delete the vector store after using it."""
+    with contextlib.suppress(Exception):
+        await client.client.vector_stores.delete(vector_store_id=vector_store_id)
+    with contextlib.suppress(Exception):
+        await client.client.files.delete(file_id=file_id)
+
+
+async def main() -> None:
+    print("=== Foundry Chat Client with File Search Example ===\n")
+
+    # Initialize the Foundry chat client
+    # Make sure you're logged in via 'az login' before running this sample
+    client = FoundryChatClient(credential=AzureCliCredential())
+
+    file_id, vector_store_id = await create_vector_store(client)
+
+    # Create file search tool using instance method
+    file_search_tool = client.get_file_search_tool(vector_store_ids=[vector_store_id])
+
+    agent = Agent(
+        client=client,
+        instructions="You are a helpful assistant that can search through files to find information.",
+        tools=[file_search_tool],
+    )
+
+    query = "What is the weather today? Do a file search to find the answer."
+    print(f"User: {query}")
+    result = await agent.run(query)
+    print(f"Agent: {result}\n")
+
+    await delete_vector_store(client, file_id, vector_store_id)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,143 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from datetime import datetime, timezone
+from random import randint
+from typing import Annotated
+
+from agent_framework import Agent, tool
+from agent_framework.foundry import FoundryChatClient
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+from pydantic import Field
+
+# Load environment variables from .env file
+load_dotenv()
+
+"""
+Foundry Chat Client with Function Tools Example
+
+This sample demonstrates function tool integration with FoundryChatClient,
+showing both agent-level and query-level tool configuration patterns.
+"""
+
+
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
+# see samples/02-agents/tools/function_tool_with_approval.py
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
+@tool(approval_mode="never_require")
+def get_weather(
+    location: Annotated[str, Field(description="The location to get the weather for.")],
+) -> str:
+    """Get the weather for a given location."""
+    conditions = ["sunny", "cloudy", "rainy", "stormy"]
+    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
+
+
+@tool(approval_mode="never_require")
+def get_time() -> str:
+    """Get the current UTC time."""
+    current_time = datetime.now(timezone.utc)
+    return f"The current UTC time is {current_time.strftime('%Y-%m-%d %H:%M:%S')}."
+
+
+async def tools_on_agent_level() -> None:
+    """Example showing tools defined when creating the agent."""
+    print("=== Tools Defined on Agent Level ===")
+
+    # Tools are provided when creating the agent
+    # The agent can use these tools for any query during its lifetime
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = Agent(
+        client=FoundryChatClient(credential=AzureCliCredential()),
+        instructions="You are a helpful assistant that can provide weather and time information.",
+        tools=[get_weather, get_time],  # Tools defined at agent creation
+    )
+
+    # First query - agent can use weather tool
+    query1 = "What's the weather like in New York?"
+    print(f"User: {query1}")
+    result1 = await agent.run(query1)
+    print(f"Agent: {result1}\n")
+
+    # Second query - agent can use time tool
+    query2 = "What's the current UTC time?"
+    print(f"User: {query2}")
+    result2 = await agent.run(query2)
+    print(f"Agent: {result2}\n")
+
+    # Third query - agent can use both tools if needed
+    query3 = "What's the weather in London and what's the current UTC time?"
+    print(f"User: {query3}")
+    result3 = await agent.run(query3)
+    print(f"Agent: {result3}\n")
+
+
+async def tools_on_run_level() -> None:
+    """Example showing tools passed to the run method."""
+    print("=== Tools Passed to Run Method ===")
+
+    # Agent created without tools
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = Agent(
+        client=FoundryChatClient(credential=AzureCliCredential()),
+        instructions="You are a helpful assistant.",
+        # No tools defined here
+    )
+
+    # First query with weather tool
+    query1 = "What's the weather like in Seattle?"
+    print(f"User: {query1}")
+    result1 = await agent.run(query1, tools=[get_weather])  # Tool passed to run method
+    print(f"Agent: {result1}\n")
+
+    # Second query with time tool
+    query2 = "What's the current UTC time?"
+    print(f"User: {query2}")
+    result2 = await agent.run(query2, tools=[get_time])  # Different tool for this query
+    print(f"Agent: {result2}\n")
+
+    # Third query with multiple tools
+    query3 = "What's the weather in Chicago and what's the current UTC time?"
+    print(f"User: {query3}")
+    result3 = await agent.run(query3, tools=[get_weather, get_time])  # Multiple tools
+    print(f"Agent: {result3}\n")
+
+
+async def mixed_tools_example() -> None:
+    """Example showing both agent-level tools and run-method tools."""
+    print("=== Mixed Tools Example (Agent + Run Method) ===")
+
+    # Agent created with some base tools
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = Agent(
+        client=FoundryChatClient(credential=AzureCliCredential()),
+        instructions="You are a comprehensive assistant that can help with various information requests.",
+        tools=[get_weather],  # Base tool available for all queries
+    )
+
+    # Query using both agent tool and additional run-method tools
+    query = "What's the weather in Denver and what's the current UTC time?"
+    print(f"User: {query}")
+
+    # Agent has access to get_weather (from creation) + additional tools from run method
+    result = await agent.run(
+        query,
+        tools=[get_time],  # Additional tools for this specific query
+    )
+    print(f"Agent: {result}\n")
+
+
+async def main() -> None:
+    print("=== Foundry Chat Client 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())
@@ -0,0 +1,265 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+from agent_framework import Agent
+from agent_framework.foundry import FoundryChatClient
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+"""
+Foundry Chat Client with Hosted MCP Example
+
+This sample demonstrates integrating hosted Model Context Protocol (MCP) tools with
+FoundryChatClient, including user approval workflows for function call security.
+"""
+
+if TYPE_CHECKING:
+    from agent_framework import AgentSession, SupportsAgentRun
+
+
+async def handle_approvals_without_session(query: str, agent: "SupportsAgentRun"):
+    """When we don't have a session, we need to ensure we return with the input, approval request and approval."""
+    from agent_framework import Message
+
+    result = await agent.run(query)
+    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(Message(role="assistant", contents=[user_input_needed]))
+            user_approval = input("Approve function call? (y/n): ")
+            new_inputs.append(
+                Message(
+                    role="user",
+                    contents=[user_input_needed.to_function_approval_response(user_approval.lower() == "y")],
+                )
+            )
+
+        result = await agent.run(new_inputs)
+    return result
+
+
+async def handle_approvals_with_session(query: str, agent: "SupportsAgentRun", session: "AgentSession"):
+    """Here we let the session deal with the previous responses, and we just rerun with the approval."""
+    from agent_framework import Message
+
+    result = await agent.run(query, session=session, 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(
+                Message(
+                    role="user",
+                    contents=[user_input_needed.to_function_approval_response(user_approval.lower() == "y")],
+                )
+            )
+        result = await agent.run(new_input, session=session, store=True)
+    return result
+
+
+async def handle_approvals_with_session_streaming(query: str, agent: "SupportsAgentRun", session: "AgentSession"):
+    """Here we let the session deal with the previous responses, and we just rerun with the approval."""
+    from agent_framework import Message
+
+    new_input: list[Message | str] = [query]
+    new_input_added = True
+    while new_input_added:
+        new_input_added = False
+        async for update in agent.run(new_input, session=session, options={"store": True}, stream=True):
+            if update.user_input_requests:
+                # Reset input to only contain new approval responses for the next iteration
+                new_input = []
+                for user_input_needed in update.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(
+                        Message(
+                            role="user",
+                            contents=[user_input_needed.to_function_approval_response(user_approval.lower() == "y")],
+                        )
+                    )
+                    new_input_added = True
+            else:
+                yield update
+
+
+async def run_hosted_mcp_without_session_and_specific_approval() -> None:
+    """Example showing Mcp Tools with approvals without using a session."""
+    print("=== Mcp with approvals and without session ===")
+    credential = AzureCliCredential()
+    client = FoundryChatClient(credential=credential)
+
+    # Create MCP tool with specific approval settings
+    mcp_tool = client.get_mcp_tool(
+        name="Microsoft Learn MCP",
+        url="https://learn.microsoft.com/api/mcp",
+        # we don't require approval for microsoft_docs_search tool calls
+        # but we do for any other tool
+        approval_mode={"never_require_approval": ["microsoft_docs_search"]},
+    )
+
+    # Tools are provided when creating the agent
+    # The agent can use these tools for any query during its lifetime
+    async with Agent(
+        client=client,
+        name="DocsAgent",
+        instructions="You are a helpful assistant that uses your MCP tool "
+        "to help with microsoft documentation questions.",
+        tools=[mcp_tool],
+    ) as agent:
+        # First query
+        query1 = "How to create an Azure storage account using az cli?"
+        print(f"User: {query1}")
+        result1 = await handle_approvals_without_session(query1, agent)
+        print(f"{agent.name}: {result1}\n")
+        print("\n=======================================\n")
+        # Second query
+        query2 = "What is Microsoft Agent Framework?"
+        print(f"User: {query2}")
+        result2 = await handle_approvals_without_session(query2, agent)
+        print(f"{agent.name}: {result2}\n")
+
+
+async def run_hosted_mcp_without_approval() -> None:
+    """Example showing Mcp Tools without approvals."""
+    print("=== Mcp without approvals ===")
+    credential = AzureCliCredential()
+    client = FoundryChatClient(credential=credential)
+
+    # Create MCP tool without approval requirements
+    mcp_tool = client.get_mcp_tool(
+        name="Microsoft Learn MCP",
+        url="https://learn.microsoft.com/api/mcp",
+        # we don't require approval for any function calls
+        # this means we will not see the approval messages,
+        # it is fully handled by the service and a final response is returned.
+        approval_mode="never_require",
+    )
+
+    # Tools are provided when creating the agent
+    # The agent can use these tools for any query during its lifetime
+    async with Agent(
+        client=client,
+        name="DocsAgent",
+        instructions="You are a helpful assistant that uses your MCP tool "
+        "to help with Microsoft documentation questions.",
+        tools=[mcp_tool],
+    ) as agent:
+        # First query
+        query1 = "How to create an Azure storage account using az cli?"
+        print(f"User: {query1}")
+        result1 = await handle_approvals_without_session(query1, agent)
+        print(f"{agent.name}: {result1}\n")
+        print("\n=======================================\n")
+        # Second query
+        query2 = "What is Microsoft Agent Framework?"
+        print(f"User: {query2}")
+        result2 = await handle_approvals_without_session(query2, agent)
+        print(f"{agent.name}: {result2}\n")
+
+
+async def run_hosted_mcp_with_session() -> None:
+    """Example showing Mcp Tools with approvals using a session."""
+    print("=== Mcp with approvals and with session ===")
+    credential = AzureCliCredential()
+    client = FoundryChatClient(credential=credential)
+
+    # Create MCP tool with always require approval
+    mcp_tool = client.get_mcp_tool(
+        name="Microsoft Learn MCP",
+        url="https://learn.microsoft.com/api/mcp",
+        # we require approval for all function calls
+        approval_mode="always_require",
+    )
+
+    # Tools are provided when creating the agent
+    # The agent can use these tools for any query during its lifetime
+    async with Agent(
+        client=client,
+        name="DocsAgent",
+        instructions="You are a helpful assistant that uses your MCP tool "
+        "to help with microsoft documentation questions.",
+        tools=[mcp_tool],
+    ) as agent:
+        # First query
+        session = agent.create_session()
+        query1 = "How to create an Azure storage account using az cli?"
+        print(f"User: {query1}")
+        result1 = await handle_approvals_with_session(query1, agent, session)
+        print(f"{agent.name}: {result1}\n")
+        print("\n=======================================\n")
+        # Second query
+        query2 = "What is Microsoft Agent Framework?"
+        print(f"User: {query2}")
+        result2 = await handle_approvals_with_session(query2, agent, session)
+        print(f"{agent.name}: {result2}\n")
+
+
+async def run_hosted_mcp_with_session_streaming() -> None:
+    """Example showing Mcp Tools with approvals using a session."""
+    print("=== Mcp with approvals and with session ===")
+    credential = AzureCliCredential()
+    client = FoundryChatClient(credential=credential)
+
+    # Create MCP tool with always require approval
+    mcp_tool = client.get_mcp_tool(
+        name="Microsoft Learn MCP",
+        url="https://learn.microsoft.com/api/mcp",
+        # we require approval for all function calls
+        approval_mode="always_require",
+    )
+
+    # Tools are provided when creating the agent
+    # The agent can use these tools for any query during its lifetime
+    async with Agent(
+        client=client,
+        name="DocsAgent",
+        instructions="You are a helpful assistant that uses your MCP tool "
+        "to help with microsoft documentation questions.",
+        tools=[mcp_tool],
+    ) as agent:
+        # First query
+        session = agent.create_session()
+        query1 = "How to create an Azure storage account using az cli?"
+        print(f"User: {query1}")
+        print(f"{agent.name}: ", end="")
+        async for update in handle_approvals_with_session_streaming(query1, agent, session):
+            print(update, end="")
+        print("\n")
+        print("\n=======================================\n")
+        # Second query
+        query2 = "What is Microsoft Agent Framework?"
+        print(f"User: {query2}")
+        print(f"{agent.name}: ", end="")
+        async for update in handle_approvals_with_session_streaming(query2, agent, session):
+            print(update, end="")
+        print("\n")
+
+
+async def main() -> None:
+    print("=== Foundry Chat Client with Hosted MCP Examples ===\n")
+
+    await run_hosted_mcp_without_approval()
+    await run_hosted_mcp_without_session_and_specific_approval()
+    await run_hosted_mcp_with_session()
+    await run_hosted_mcp_with_session_streaming()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,66 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+
+from agent_framework import Agent, MCPStreamableHTTPTool
+from agent_framework.foundry import FoundryChatClient
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+"""
+Foundry Chat Client with Local Model Context Protocol (MCP) Example
+
+This sample demonstrates integration of FoundryChatClient with local Model Context Protocol (MCP)
+servers.
+"""
+
+
+# --- Below code uses Microsoft Learn MCP server over Streamable HTTP ---
+# --- Users can set these environment variables, or just edit the values below to their desired local MCP server
+MCP_NAME = os.environ.get("MCP_NAME", "Microsoft Learn MCP")  # example name
+MCP_URL = os.environ.get("MCP_URL", "https://learn.microsoft.com/api/mcp")  # example endpoint
+
+# Environment variables for FoundryChatClient authentication
+# FOUNDRY_PROJECT_ENDPOINT="<your-foundry-project-endpoint>"
+# FOUNDRY_MODEL="<your-deployment-name>"
+
+
+async def main():
+    """Example showing local MCP tools for a Foundry Chat Client agent."""
+    # AuthN: use Azure CLI
+    credential = AzureCliCredential()
+
+    # Build an agent backed by FoundryChatClient
+    # (project endpoint and model can also come from env vars above)
+    responses_client = FoundryChatClient(
+        credential=credential,
+    )
+
+    agent: Agent = Agent(
+        client=responses_client,
+        name="DocsAgent",
+        instructions=("You are a helpful assistant that can help with Microsoft documentation questions."),
+    )
+
+    # Connect to the MCP server (Streamable HTTP)
+    async with MCPStreamableHTTPTool(
+        name=MCP_NAME,
+        url=MCP_URL,
+    ) as mcp_tool:
+        # First query — expect the agent to use the MCP tool if it helps
+        first_query = "How to create an Azure storage account using az cli?"
+        first_response = await agent.run(first_query, tools=mcp_tool)
+        print("\n=== Answer 1 ===\n", first_response.text)
+
+        # Follow-up query (connection is reused)
+        second_query = "What is Microsoft Agent Framework?"
+        second_response = await agent.run(second_query, tools=mcp_tool)
+        print("\n=== Answer 2 ===\n", second_response.text)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,161 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from random import randint
+from typing import Annotated
+
+from agent_framework import Agent, AgentSession, InMemoryHistoryProvider, tool
+from agent_framework.foundry import FoundryChatClient
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+from pydantic import Field
+
+# Load environment variables from .env file
+load_dotenv()
+
+"""
+Foundry Chat Client with Session Management Example
+
+This sample demonstrates session management with FoundryChatClient, comparing
+automatic session creation with explicit session management for persistent context.
+"""
+
+
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
+# see samples/02-agents/tools/function_tool_with_approval.py
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
+@tool(approval_mode="never_require")
+def get_weather(
+    location: Annotated[str, Field(description="The location to get the weather for.")],
+) -> str:
+    """Get the weather for a given location."""
+    conditions = ["sunny", "cloudy", "rainy", "stormy"]
+    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
+
+
+async def example_with_automatic_session_creation() -> None:
+    """Example showing automatic session creation (service-managed session)."""
+    print("=== Automatic Session Creation Example ===")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = Agent(
+        client=FoundryChatClient(credential=AzureCliCredential()),
+        instructions="You are a helpful weather agent.",
+        tools=get_weather,
+    )
+
+    # First conversation - no session provided, will be created automatically
+    query1 = "What's the weather like in Seattle?"
+    print(f"User: {query1}")
+    result1 = await agent.run(query1)
+    print(f"Agent: {result1.text}")
+
+    # Second conversation - still no session provided, will create another new session
+    query2 = "What was the last city I asked about?"
+    print(f"\nUser: {query2}")
+    result2 = await agent.run(query2)
+    print(f"Agent: {result2.text}")
+    print("Note: Each call creates a separate session, so the agent doesn't remember previous context.\n")
+
+
+async def example_with_session_persistence() -> None:
+    """Example showing session persistence across multiple conversations."""
+    print("=== Session Persistence Example ===")
+    print("Using the same session across multiple conversations to maintain context.\n")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = Agent(
+        client=FoundryChatClient(credential=AzureCliCredential()),
+        instructions="You are a helpful weather agent.",
+        tools=get_weather,
+    )
+
+    # Create a new session that will be reused
+    session = agent.create_session()
+
+    # First conversation
+    query1 = "What's the weather like in Tokyo?"
+    print(f"User: {query1}")
+    result1 = await agent.run(query1, session=session)
+    print(f"Agent: {result1.text}")
+
+    # Second conversation using the same session - maintains context
+    query2 = "How about London?"
+    print(f"\nUser: {query2}")
+    result2 = await agent.run(query2, session=session)
+    print(f"Agent: {result2.text}")
+
+    # Third conversation - agent should remember both previous cities
+    query3 = "Which of the cities I asked about has better weather?"
+    print(f"\nUser: {query3}")
+    result3 = await agent.run(query3, session=session)
+    print(f"Agent: {result3.text}")
+    print("Note: The agent remembers context from previous messages in the same session.\n")
+
+
+async def example_with_existing_session_messages() -> None:
+    """Example showing how to work with existing session messages for Foundry-backed agents."""
+    print("=== Existing Session Messages Example ===")
+
+    # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    agent = Agent(
+        client=FoundryChatClient(credential=AzureCliCredential()),
+        instructions="You are a helpful weather agent.",
+        tools=get_weather,
+    )
+
+    # Start a conversation and build up message history
+    session = agent.create_session()
+
+    query1 = "What's the weather in Paris?"
+    print(f"User: {query1}")
+    result1 = await agent.run(query1, session=session)
+    print(f"Agent: {result1.text}")
+
+    # The session now contains the conversation history in state
+    memory_state = session.state.get(InMemoryHistoryProvider.DEFAULT_SOURCE_ID, {})
+    messages = memory_state.get("messages", [])
+    if messages:
+        print(f"Session contains {len(messages)} messages")
+
+    print("\n--- Continuing with the same session in a new agent instance ---")
+
+    # Create a new agent instance but use the existing session with its message history
+    new_agent = Agent(
+        client=FoundryChatClient(credential=AzureCliCredential()),
+        instructions="You are a helpful weather agent.",
+        tools=get_weather,
+    )
+
+    # Use the same session object which contains the conversation history
+    query2 = "What was the last city I asked about?"
+    print(f"User: {query2}")
+    result2 = await new_agent.run(query2, session=session)
+    print(f"Agent: {result2.text}")
+    print("Note: The agent continues the conversation using the local message history.\n")
+
+    print("\n--- Alternative: Creating a new session from existing messages ---")
+
+    # You can also create a new session from existing messages
+    new_session = AgentSession()
+
+    query3 = "How does the Paris weather compare to London?"
+    print(f"User: {query3}")
+    result3 = await new_agent.run(query3, session=new_session)
+    print(f"Agent: {result3.text}")
+    print("Note: This creates a new session with the same conversation history.\n")
+
+
+async def main() -> None:
+    print("=== Foundry Chat Client Session Management Examples ===\n")
+
+    await example_with_automatic_session_creation()
+    await example_with_session_persistence()
+    await example_with_existing_session_messages()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,79 @@
+# Copyright (c) Microsoft. All rights reserved.
+# ruff: noqa
+
+from __future__ import annotations
+
+import asyncio
+from random import randint
+from typing import Annotated
+
+from agent_framework import Agent
+from agent_framework.foundry import FoundryLocalClient
+
+"""
+This sample demonstrates basic usage of the FoundryLocalClient.
+Shows both streaming and non-streaming responses with function tools.
+
+Running this sample the first time will be slow, as the model needs to be
+downloaded and initialized.
+
+Also, not every model supports function calling, so be sure to check the
+model capabilities in the Foundry catalog, or pick one from the list printed
+when running this sample.
+"""
+
+
+def get_weather(
+    location: Annotated[str, "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(agent: Agent) -> None:
+    """Example of non-streaming response (get the complete result at once)."""
+    print("=== Non-streaming Response Example ===")
+
+    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(agent: Agent) -> None:
+    """Example of streaming response (get results as they are generated)."""
+    print("=== Streaming Response Example ===")
+
+    query = "What's the weather like in Amsterdam?"
+    print(f"User: {query}")
+    print("Agent: ", end="", flush=True)
+    async for chunk in agent.run(query, stream=True):
+        if chunk.text:
+            print(chunk.text, end="", flush=True)
+    print("\n")
+
+
+async def main() -> None:
+    print("=== Basic Foundry Local Client Agent Example ===")
+
+    client = FoundryLocalClient(model="phi-4-mini")
+    print(f"Client Model ID: {client.model}\n")
+    print("Other available models (tool calling supported only):")
+    for model in client.manager.list_catalog_models():
+        if model.supports_tool_calling:
+            print(
+                f"- {model.alias} for {model.task} - id={model.id} - {(model.file_size_mb / 1000):.2f} GB - {model.license}"
+            )
+    agent = Agent(
+        client=client,
+        name="LocalAgent",
+        instructions="You are a helpful agent.",
+        tools=get_weather,
+    )
+    await non_streaming_example(agent)
+    await streaming_example(agent)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())