fix: improve autonomous mode comments per code review

refactor: remove redundant autonomous turn counter reset from ContinueTurnAsync
fix: reset autonomous turn counter at start of each new HandoffState turn
2026-06-16 21:04:09 +08:00 · 2026-05-12 00:38:26 +00:00 · 2026-05-12 00:35:10 +00:00 · 2026-05-12 00:32:36 +00:00 · 2026-05-12 00:29:25 +00:00 · 2026-05-12 00:17:07 +00:00
416 changed files with 33954 additions and 6275 deletions
@@ -37,6 +37,7 @@ jobs:
    outputs:
      dotnetChanges: ${{ steps.filter.outputs.dotnet }}
      cosmosDbChanges: ${{ steps.filter.outputs.cosmosdb }}
+      foundryHostingChanges: ${{ steps.filter.outputs.foundryHosting }}
    steps:
      - uses: actions/checkout@v6
      - uses: dorny/paths-filter@v3
@@ -47,6 +48,22 @@ jobs:
              - 'dotnet/**'
            cosmosdb:
              - 'dotnet/src/Microsoft.Agents.AI.CosmosNoSql/**'
+            # The Foundry hosted-agent IT is costly (builds a container, pushes to ACR,
+            # provisions live agents). Only run it when the project under test, its
+            # dependency chain, the test container, the test fixture, or their tooling
+            # changed. Keep this list in sync with $hashedDirs in scripts/it-build-image.ps1.
+            foundryHosting:
+              - 'dotnet/src/Microsoft.Agents.AI.Foundry.Hosting/**'
+              - 'dotnet/src/Microsoft.Agents.AI.Foundry/**'
+              - 'dotnet/src/Microsoft.Agents.AI/**'
+              - 'dotnet/src/Microsoft.Agents.AI.Abstractions/**'
+              - 'dotnet/src/Microsoft.Agents.AI.Workflows/**'
+              - 'dotnet/tests/Foundry.Hosting.IntegrationTests/**'
+              - 'dotnet/tests/Foundry.Hosting.IntegrationTests.TestContainer/**'
+              - 'dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/**'
+              - 'dotnet/Directory.Packages.props'
+              - 'dotnet/tests/Foundry.Hosting.IntegrationTests/scripts/it-build-image.ps1'
+              - '.github/workflows/dotnet-build-and-test.yml'
      # run only if 'dotnet' files were changed
      - name: dotnet tests
        if: steps.filter.outputs.dotnet == 'true'
@@ -257,8 +274,11 @@ jobs:
            -c ${{ matrix.configuration }} `
            --no-build -v Normal `
            --report-xunit-trx `
+            --report-junit `
+            --results-directory ../IntegrationTestResults/ `
            --ignore-exit-code 8 `
            --filter-not-trait "Category=IntegrationDisabled" `
+            --filter-not-trait "Category=FoundryHostedAgents" `
            --parallel-algorithm aggressive `
            --max-threads 2.0x
        env:
@@ -277,6 +297,10 @@ jobs:
          AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
          AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZURE_AI_MODEL_DEPLOYMENT_NAME }}
          AZURE_AI_BING_CONNECTION_ID: ${{ vars.AZURE_AI_BING_CONNECTION_ID }}
+          # Anthropic Models
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          ANTHROPIC_CHAT_MODEL_NAME: ${{ vars.ANTHROPIC_CHAT_MODEL_NAME }}
+          ANTHROPIC_REASONING_MODEL_NAME: ${{ vars.ANTHROPIC_REASONING_MODEL_NAME }}

      # Generate test reports and check coverage
      - name: Generate test reports
@@ -299,11 +323,104 @@ jobs:
        shell: pwsh
        run: ./dotnet/eng/scripts/dotnet-check-coverage.ps1 -JsonReportPath "TestResults/Reports/Summary.json" -CoverageThreshold $env:COVERAGE_THRESHOLD

+      - name: Upload integration test results
+        if: always() && github.event_name != 'pull_request' && matrix.integration-tests
+        uses: actions/upload-artifact@v7
+        with:
+          name: dotnet-test-results-${{ matrix.targetFramework }}-${{ matrix.os }}
+          path: IntegrationTestResults/**/*.junit
+          if-no-files-found: ignore
+
+  # The Foundry hosted-agent IT is costly (it builds a container, pushes to ACR, and provisions
+  # live agents on a separate Foundry project). Running it in its own job keeps the overall
+  # workflow time roughly flat: it executes in parallel to dotnet-build and dotnet-test and is
+  # gated on paths-filter.outputs.foundryHostingChanges so unrelated edits skip the work.
+  dotnet-foundry-hosted-it:
+    needs: paths-filter
+    if: github.event_name != 'pull_request' && needs.paths-filter.outputs.foundryHostingChanges == 'true'
+    runs-on: ubuntu-latest
+    environment: integration
+    env:
+      configuration: Release
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+          sparse-checkout: |
+            .
+            .github
+            dotnet
+            python
+
+      - name: Setup dotnet
+        uses: actions/setup-dotnet@v5.2.0
+        with:
+          global-json-file: ${{ github.workspace }}/dotnet/global.json
+
+      # Build the test csproj directly instead of a filtered slnx + -f override.
+      # The test project pins TargetFrameworks=net10.0 and its ProjectReference closure
+      # gives MSBuild a single-rooted graph, so each multi-targeted dependency is invoked
+      # exactly once for net10.0. This avoids the MSB3026/MSB3491/MSB4018/MSB3883 file-lock
+      # collisions caused by parallel inner-builds racing on shared bin/obj output paths
+      # under the previous slnx + global TFM override approach.
+      - name: Build Foundry hosted IT (and its deps)
+        shell: bash
+        run: dotnet build dotnet/tests/Foundry.Hosting.IntegrationTests/Foundry.Hosting.IntegrationTests.csproj -c "$configuration" --warnaserror
+
+      - name: Azure CLI Login
+        uses: azure/login@v2
+        with:
+          client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+
+      # We rebuild and push the test container image on every IT run so framework code changes
+      # are picked up; the image tag is content-hashed across the test container source AND its
+      # framework project references, so identical content is a no-op push.
+      #
+      # The script always passes --no-dependencies to dotnet publish so publish never re-touches
+      # the framework lib DLLs the prior "Build Foundry hosted IT (and its deps)" step produced.
+      # This structurally eliminates the MSB3026 collision that VBCSCompiler from the prebuild
+      # would otherwise cause by holding file handles to those DLLs. Do not remove the prebuild
+      # step: the subsequent `dotnet test --no-build` step and the publish's ProjectReference
+      # resolution both depend on the prebuilt outputs being present.
+      - name: Build and push Foundry Hosted Agents test container
+        id: build-foundry-hosted-image
+        shell: pwsh
+        working-directory: ${{ github.workspace }}
+        run: |
+          $registry = "${{ vars.IT_HOSTED_AGENT_REGISTRY }}"
+          if ([string]::IsNullOrWhiteSpace($registry)) {
+            throw "IT_HOSTED_AGENT_REGISTRY not set in the integration environment."
+          }
+          & "${{ github.workspace }}/dotnet/tests/Foundry.Hosting.IntegrationTests/scripts/it-build-image.ps1" -Registry $registry | Tee-Object -FilePath $env:GITHUB_ENV -Append
+
+      - name: Run Foundry Hosted Agents Integration Tests
+        shell: pwsh
+        working-directory: dotnet
+        run: |
+          dotnet test --project tests/Foundry.Hosting.IntegrationTests/Foundry.Hosting.IntegrationTests.csproj `
+            -c $env:configuration `
+            --no-build -v Normal `
+            --report-xunit-trx `
+            --ignore-exit-code 8 `
+            --filter-trait "Category=FoundryHostedAgents"
+        env:
+          AZURE_AI_PROJECT_ENDPOINT: ${{ vars.IT_HOSTED_AGENT_PROJECT_ENDPOINT }}
+          AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.IT_HOSTED_AGENT_MODEL_DEPLOYMENT_NAME }}
+          # Azure AI Search (for the azure-search-rag scenario). Reuses the integration
+          # environment secrets shared with python-sample-validation.yml. The index is
+          # provisioned out of band; see dotnet/tests/Foundry.Hosting.IntegrationTests/README.md
+          # for the required schema and seed content.
+          AZURE_SEARCH_ENDPOINT: ${{ secrets.AZURE_SEARCH_ENDPOINT }}
+          AZURE_SEARCH_INDEX_NAME: ${{ secrets.AZURE_SEARCH_INDEX_NAME }}
+          # IT_HOSTED_AGENT_IMAGE was exported into $GITHUB_ENV by the previous step.
+
  # This final job is required to satisfy the merge queue. It must only run (or succeed) if no tests failed
  dotnet-build-and-test-check:
    if: always()
    runs-on: ubuntu-latest
-    needs: [dotnet-build, dotnet-test]
+    needs: [dotnet-build, dotnet-test, dotnet-foundry-hosted-it]
    steps:
      - name: Get Date
        shell: bash
@@ -341,3 +458,64 @@ jobs:
        uses: actions/github-script@v8
        with:
          script: core.setFailed('Integration Tests Cancelled!')
+
+  # Integration test trend report (aggregates JUnit XML results from dotnet test jobs)
+  dotnet-integration-test-report:
+    name: Integration Test Report
+    if: >
+      always() &&
+      github.event_name != 'pull_request' &&
+      (contains(join(needs.*.result, ','), 'success') ||
+       contains(join(needs.*.result, ','), 'failure'))
+    needs: [dotnet-test]
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+          sparse-checkout: |
+            .github/actions/python-setup
+            python
+      - name: Set up python and install the project
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: "3.13"
+          os: ${{ runner.os }}
+      - name: Download all test results from current run
+        uses: actions/download-artifact@v4
+        with:
+          pattern: dotnet-test-results-*
+          path: dotnet-test-results/
+      - name: Restore report history cache
+        uses: actions/cache/restore@v4
+        with:
+          path: python/dotnet-integration-report-history.json
+          key: dotnet-integration-report-history-${{ github.run_id }}
+          restore-keys: |
+            dotnet-integration-report-history-
+      - name: Generate trend report
+        run: >
+          uv run python scripts/integration_test_report/aggregate.py
+          ../dotnet-test-results/
+          dotnet-integration-report-history.json
+          dotnet-integration-test-report.md
+      - name: Post to Job Summary
+        if: always()
+        run: cat dotnet-integration-test-report.md >> $GITHUB_STEP_SUMMARY
+      - name: Save report history cache
+        if: always()
+        uses: actions/cache/save@v4
+        with:
+          path: python/dotnet-integration-report-history.json
+          key: dotnet-integration-report-history-${{ github.run_id }}
+      - name: Upload trend report
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: dotnet-integration-test-report
+          path: |
+            python/dotnet-integration-test-report.md
+            python/dotnet-integration-report-history.json
@@ -6,8 +6,12 @@
 [![MS Learn Documentation](https://img.shields.io/badge/MS%20Learn-Documentation-blue)](https://learn.microsoft.com/en-us/agent-framework/)
 [![PyPI](https://img.shields.io/pypi/v/agent-framework)](https://pypi.org/project/agent-framework/)
 [![NuGet](https://img.shields.io/nuget/v/Microsoft.Agents.AI)](https://www.nuget.org/profiles/MicrosoftAgentFramework/)
+[![GitHub stars](https://img.shields.io/github/stars/microsoft/agent-framework?style=social)](https://github.com/microsoft/agent-framework/stargazers)

-Welcome to Microsoft's comprehensive multi-language framework for building, orchestrating, and deploying AI agents with support for both .NET and Python implementations. This framework provides everything from simple chat agents to complex multi-agent workflows with graph-based orchestration.
+
+Microsoft Agent Framework (MAF) is an open, multi-language framework for building **production-grade AI agents and multi-agent workflows** in **.NET and Python**.
+
+Microsoft Agent Framework is built for teams taking agents from prototype to production. It provides a consistent foundation for building, orchestrating, and operating agent systems across Python and .NET, while keeping architecture choices open as requirements evolve, and supports a broad ecosystem including Microsoft Foundry, Azure OpenAI, OpenAI, and the GitHub Copilot SDK, with samples and hosting patterns for both local development and cloud deployment.

 <p align="center">
  <a href="https://www.youtube.com/watch?v=AAgdMhftj8w" title="Watch the full Agent Framework introduction (30 min)">
@@ -21,10 +25,54 @@ Welcome to Microsoft's comprehensive multi-language framework for building, orch
  </a>
 </p>

-## 📋 Getting Started
+## Is this the right framework for you?

-### 📦 Installation
+MAF is a strong fit if you:
+- are building agents and workflows you expect to run in production,
+- need orchestration beyond a single prompt or stateless chat loop,
+- want graph-based patterns such as sequential, concurrent, handoff, and group collaboration,
+- care about durability, restartability, observability, governance, or human-in-the-loop control,
+- need provider flexibility so your architecture can evolve without major rewrites.

+## Key Features
+Explore new MAF capabilities and real implementation patterns on the [official blog](https://devblogs.microsoft.com/agent-framework/).
+
+- **Python and C#/.NET Support**: Full framework support for both Python and C#/.NET implementations with consistent APIs
+  - [Python packages](./python/packages/) | [.NET source](./dotnet/src/)
+- **Multiple Agent Provider Support**: Support for various LLM providers with more being added continuously
+  - [Python examples](./python/samples/02-agents/providers/) | [.NET examples](./dotnet/samples/02-agents/AgentProviders/)
+- **Middleware**: Flexible middleware system for request/response processing, exception handling, and custom pipelines
+  - [Python middleware](./python/samples/02-agents/middleware/) | [.NET middleware](./dotnet/samples/02-agents/Agents/Agent_Step11_Middleware/)
+- **Orchestration Patterns & Workflows**: Build multi-agent systems with graph-based workflows supporting sequential, concurrent, handoff, and group collaboration patterns; includes checkpointing, streaming, human-in-the-loop, and time-travel
+  - [Python workflows](./python/samples/03-workflows/) | [.NET workflows](./dotnet/samples/03-workflows/)
+- **Foundry Hosted Agents (new)**: Deploy and host your agents to Foundry-hosted infrastructure with just 2 additional lines of code
+  - [Python samples](./python/samples/04-hosting/foundry-hosted-agents/) | [.NET samples](./dotnet/samples/04-hosting/FoundryHostedAgents/)
+- **Observability**: Built-in OpenTelemetry integration for distributed tracing, monitoring, and debugging
+  - [Python observability](./python/samples/02-agents/observability/) | [.NET telemetry](./dotnet/samples/02-agents/AgentOpenTelemetry/)
+- **Declarative Agents**: Define agents using YAML for faster setup and versioning
+  - [Declarative agent samples](./declarative-agents/)
+- **Agent Skills**: Build domain-specific knowledge bases from multiple sources—files, inline code, class libraries—for agents to discover and use
+  - [Skills design](./docs/decisions/0021-agent-skills-design.md)
+- **AF Labs**: Experimental packages for cutting-edge features including benchmarking, reinforcement learning, and research initiatives
+  - [Labs directory](./python/packages/lab/)
+- **DevUI**: Interactive developer UI for agent development, testing, and debugging workflows
+  - [See the DevUI in action](https://www.youtube.com/watch?v=mOAaGY4WPvc)
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+  - [Installation](#installation)
+  - [Learning Resources](#learning-resources)
+  - [Quickstart](#quickstart)
+    - [Basic Agent - Python](#basic-agent---python)
+    - [Basic Agent - .NET](#basic-agent---net)
+- [More Examples & Samples](#more-examples--samples)
+- [Community & Feedback](#community--feedback)
+- [Troubleshooting](#troubleshooting)
+- [Contributor Resources](#contributor-resources)
+
+## Getting Started
+### Installation
 Python

 ```bash
@@ -37,9 +85,13 @@ pip install agent-framework

 ```bash
 dotnet add package Microsoft.Agents.AI
+# For Foundry integration (used in the .NET quickstart below):
+dotnet add package Microsoft.Agents.AI.Foundry
+dotnet add package Azure.AI.Projects
+dotnet add package Azure.Identity
 ```

-### 📚 Documentation
+### Learning Resources

 - **[Overview](https://learn.microsoft.com/agent-framework/overview/agent-framework-overview)** - High level overview of the framework
 - **[Quick Start](https://learn.microsoft.com/agent-framework/tutorials/quick-start)** - Get started with a simple agent
@@ -48,44 +100,9 @@ dotnet add package Microsoft.Agents.AI
 - **[Migration from Semantic Kernel](https://learn.microsoft.com/en-us/agent-framework/migration-guide/from-semantic-kernel)** - Guide to migrate from Semantic Kernel
 - **[Migration from AutoGen](https://learn.microsoft.com/en-us/agent-framework/migration-guide/from-autogen)** - Guide to migrate from AutoGen

-Still have questions? Join our [weekly office hours](./COMMUNITY.md#public-community-office-hours) or ask questions in our [Discord channel](https://discord.gg/b5zjErwbQM) to get help from the team and other users.
+### Quickstart

-### ✨ **Highlights**
-
- **Graph-based Workflows**: Connect agents and deterministic functions using data flows with streaming, checkpointing, human-in-the-loop, and time-travel capabilities
-  - [Python workflows](./python/samples/03-workflows/) | [.NET workflows](./dotnet/samples/03-workflows/)
- **AF Labs**: Experimental packages for cutting-edge features including benchmarking, reinforcement learning, and research initiatives
-  - [Labs directory](./python/packages/lab/)
- **DevUI**: Interactive developer UI for agent development, testing, and debugging workflows
-  - [DevUI package](./python/packages/devui/)
-
-<p align="center">
-  <a href="https://www.youtube.com/watch?v=mOAaGY4WPvc">
-    <img src="https://img.youtube.com/vi/mOAaGY4WPvc/hqdefault.jpg" alt="See the DevUI in action" width="480">
-  </a>
-</p>
-<p align="center">
-  <a href="https://www.youtube.com/watch?v=mOAaGY4WPvc">
-    See the DevUI in action (1 min)
-  </a>
-</p>
-
- **Python and C#/.NET Support**: Full framework support for both Python and C#/.NET implementations with consistent APIs
-  - [Python packages](./python/packages/) | [.NET source](./dotnet/src/)
- **Observability**: Built-in OpenTelemetry integration for distributed tracing, monitoring, and debugging
-  - [Python observability](./python/samples/02-agents/observability/) | [.NET telemetry](./dotnet/samples/02-agents/AgentOpenTelemetry/)
- **Multiple Agent Provider Support**: Support for various LLM providers with more being added continuously
-  - [Python examples](./python/samples/02-agents/providers/) | [.NET examples](./dotnet/samples/02-agents/AgentProviders/)
- **Middleware**: Flexible middleware system for request/response processing, exception handling, and custom pipelines
-  - [Python middleware](./python/samples/02-agents/middleware/) | [.NET middleware](./dotnet/samples/02-agents/Agents/Agent_Step11_Middleware/)
-
-### 💬 **We want your feedback!**
-
- For bugs, please file a [GitHub issue](https://github.com/microsoft/agent-framework/issues).
-
-## Quickstart
-
-### Basic Agent - Python
+#### Basic Agent - Python

 Create a simple Azure Responses Agent that writes a haiku about the Microsoft Agent Framework

@@ -109,7 +126,7 @@ async def main():
          # project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
          # model=os.environ["FOUNDRY_MODEL_DEPLOYMENT_NAME"],
      ),
-      name="HaikuBot",
+      name="HaikuAgent",
      instructions="You are an upbeat assistant that writes beautifully.",
    )

@@ -119,40 +136,24 @@ if __name__ == "__main__":
    asyncio.run(main())
 ```

-### Basic Agent - .NET
-Create a simple Agent, using Microsoft Foundry with token-based auth, that writes a haiku about the Microsoft Agent Framework
+#### Basic Agent - .NET
+Create a simple Agent, using Microsoft Foundry that writes a haiku about the Microsoft Agent Framework

 ```c#
-// dotnet add package Microsoft.Agents.AI.Foundry
-// Use `az login` to authenticate with Azure CLI
-using Azure.AI.Projects;
-using Azure.Identity;
-using System;
+// This sample shows how to create and run a basic agent with AIProjectClient.AsAIAgent(...).
+
 using Azure.AI.Projects;
 using Azure.Identity;
+using Microsoft.Agents.AI;

-var endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+string endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";

-var agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
-    .AsAIAgent(model: deploymentName, name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
-
-Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
-```
-
-Create a simple Agent, using OpenAI Responses, that writes a haiku about the Microsoft Agent Framework
-
-```c#
-// dotnet add package Microsoft.Agents.AI.OpenAI
-using System;
-using OpenAI;
-using OpenAI.Responses;
-
-// Replace the <apikey> with your OpenAI API key.
-var agent = new OpenAIClient("<apikey>")
-    .GetResponsesClient()
-    .AsAIAgent(model: "gpt-5.4-mini", name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
+AIAgent agent =
+    new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
+    .AsAIAgent(model: deploymentName, instructions: "You are an upbeat assistant that writes beautifully.", name: "HaikuAgent");

+// Once you have the agent, you can invoke it like any other AIAgent.
 Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
 ```

@@ -175,6 +176,12 @@ Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Fram
 - [Hosting](./dotnet/samples/04-hosting): A2A, Durable Agents, Durable Workflows
 - [End-to-End](./dotnet/samples/05-end-to-end): full applications and demos

+## Community & Feedback
+
+- **Found a bug?** File a [GitHub issue](https://github.com/microsoft/agent-framework/issues) to help us improve.
+- **Enjoying MAF?** [![GitHub stars](https://img.shields.io/badge/Star-us%20on%20GitHub-yellow)](https://github.com/microsoft/agent-framework) to show your support and help others discover the project.
+- **Have questions?** Join our [Discord](https://discord.gg/b5zjErwbQM) or visit [weekly office hours](./COMMUNITY.md#public-community-office-hours).
+
 ## Troubleshooting

 ### Authentication
@@ -187,16 +194,7 @@ Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Fram
 > **Tip:** `DefaultAzureCredential` is convenient for development but in production, consider using a specific credential (e.g., `ManagedIdentityCredential`) to avoid latency issues, unintended credential probing, and potential security risks from fallback mechanisms.

 ### Environment Variables
-
-The samples typically read configuration from environment variables. Common required variables:
-
-| Variable | Used by | Purpose |
-|----------|---------|---------|
-| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI samples | Your Azure OpenAI resource URL |
-| `AZURE_OPENAI_DEPLOYMENT_NAME` | Azure OpenAI samples | Model deployment name (e.g. `gpt-4o-mini`) |
-| `AZURE_AI_PROJECT_ENDPOINT` | Microsoft Foundry samples | Your Microsoft Foundry project endpoint |
-| `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Microsoft Foundry samples | Model deployment name |
-| `OPENAI_API_KEY` | OpenAI (non-Azure) samples | Your OpenAI platform API key |
+For environment variable configuration specific to each sample, refer to the README in the sample directory ([Python samples](./python/samples/) | [.NET samples](./dotnet/samples/)).

 ## Contributor Resources

@@ -25,7 +25,8 @@
    <PackageVersion Include="Azure.AI.AgentServer.Core" Version="1.0.0-beta.23" />
    <PackageVersion Include="Azure.AI.AgentServer.Invocations" Version="1.0.0-beta.3" />
    <PackageVersion Include="Azure.AI.AgentServer.Responses" Version="1.0.0-beta.4" />
-    <PackageVersion Include="Azure.AI.Projects" Version="2.0.0" />
+    <PackageVersion Include="Azure.Search.Documents" Version="12.0.0" />
+    <PackageVersion Include="Azure.AI.Projects" Version="2.1.0-beta.1" />
    <PackageVersion Include="Azure.AI.Agents.Persistent" Version="1.2.0-beta.10" />
    <PackageVersion Include="Azure.AI.OpenAI" Version="2.9.0-beta.1" />
    <PackageVersion Include="Azure.Core" Version="1.53.0" />
@@ -71,12 +72,12 @@
    <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
    <PackageVersion Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.0.0" />
    <!-- Microsoft.Extensions.* -->
-    <PackageVersion Include="Microsoft.Extensions.AI" Version="10.5.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="10.5.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI" Version="10.5.1" />
+    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="10.5.1" />
    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation" Version="10.4.0" />
    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation.Quality" Version="10.4.0" />
    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation.Safety" Version="10.3.0-preview.1.26109.11" />
-    <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.5.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.5.1" />
    <PackageVersion Include="Microsoft.Extensions.Caching.Memory" Version="10.0.0" />
    <PackageVersion Include="Microsoft.Extensions.Compliance.Abstractions" Version="10.5.0" />
    <PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.1" />
@@ -98,7 +99,7 @@
    <PackageVersion Include="Microsoft.SemanticKernel.Connectors.InMemory" Version="1.67.0-preview" />
    <PackageVersion Include="Microsoft.SemanticKernel.Connectors.Qdrant" Version="1.67.0-preview" />
    <!-- Agent SDKs -->
-    <PackageVersion Include="GitHub.Copilot.SDK" Version="0.1.29" />
+    <PackageVersion Include="GitHub.Copilot.SDK" Version="1.0.0-beta.2" />
    <PackageVersion Include="Microsoft.Agents.CopilotStudio.Client" Version="1.3.171-beta" />
    <!-- M365 Agents SDK -->
    <PackageVersion Include="AdaptiveCards" Version="3.1.0" />
@@ -109,6 +110,8 @@
    <PackageVersion Include="A2A.AspNetCore" Version="1.0.0-preview2" />
    <!-- MCP -->
    <PackageVersion Include="ModelContextProtocol" Version="1.1.0" />
+    <!-- Hyperlight -->
+    <PackageVersion Include="Hyperlight.HyperlightSandbox.Api" Version="0.4.0" />
    <!-- Inference SDKs -->
    <PackageVersion Include="Microsoft.ML.OnnxRuntimeGenAI" Version="0.10.0" />
    <PackageVersion Include="Microsoft.ML.Tokenizers" Version="2.0.0" />
@@ -33,3 +33,4 @@ Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Fram
 - [Design Documents](../docs/design)
 - [Architectural Decision Records](../docs/decisions)
 - [MSFT Learn Docs](https://learn.microsoft.com/agent-framework/overview/agent-framework-overview)
+
@@ -1,4 +1,4 @@
-<Solution>
+<Solution>
  <Configurations>
    <BuildType Name="Debug" />
    <BuildType Name="Publish" />
@@ -167,7 +167,7 @@
    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step22_MemorySearch/Agent_Step22_MemorySearch.csproj" />
    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step23_LocalMCP/Agent_Step23_LocalMCP.csproj" />
    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step24_CodeInterpreterFileDownload/Agent_Step24_CodeInterpreterFileDownload.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step25_ToolboxServerSideTools/Agent_Step25_ToolboxServerSideTools.csproj" />
+    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step25_FoundryToolboxMcp/Agent_Step25_FoundryToolboxMcp.csproj" />
  </Folder>
  <Folder Name="/Samples/02-agents/Evaluation/">
    <Project Path="samples/02-agents/Evaluation/Evaluation_CustomEvals/Evaluation_CustomEvals.csproj" />
@@ -175,6 +175,12 @@
    <Project Path="samples/02-agents/Evaluation/Evaluation_Multimodal/Evaluation_Multimodal.csproj" />
    <Project Path="samples/02-agents/Evaluation/Evaluation_SimpleEval/Evaluation_SimpleEval.csproj" />
  </Folder>
+  <Folder Name="/Samples/02-agents/AgentWithCodeAct/">
+    <File Path="samples/02-agents/AgentWithCodeAct/README.md" />
+    <Project Path="samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step01_Interpreter/AgentWithCodeAct_Step01_Interpreter.csproj" />
+    <Project Path="samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step02_ToolEnabled/AgentWithCodeAct_Step02_ToolEnabled.csproj" />
+    <Project Path="samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step03_ManualWiring/AgentWithCodeAct_Step03_ManualWiring.csproj" />
+  </Folder>
  <Folder Name="/Samples/02-agents/AgentWithMemory/">
    <File Path="samples/02-agents/AgentWithMemory/README.md" />
    <Project Path="samples/02-agents/AgentWithMemory/AgentWithMemory_Step01_ChatHistoryMemory/AgentWithMemory_Step01_ChatHistoryMemory.csproj" />
@@ -307,15 +313,24 @@
  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-FoundryAgent/">
    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-FoundryAgent/HostedFoundryAgent.csproj" />
  </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files/HostedFiles.csproj" />
+  </Folder>
  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalTools/">
    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalTools/HostedLocalTools.csproj" />
  </Folder>
  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-McpTools/">
    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-McpTools/HostedMcpTools.csproj" />
  </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-Observability/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-Observability/HostedObservability.csproj" />
+  </Folder>
  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox/">
    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox/HostedToolbox.csproj" />
  </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/HostedAzureSearchRag.csproj" />
+  </Folder>
  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-TextRag/">
    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-TextRag/HostedTextRag.csproj" />
  </Folder>
@@ -323,6 +338,7 @@
    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Simple/HostedWorkflowSimple.csproj" />
  </Folder>
  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SessionFilesClient/SessionFilesClient.csproj" />
    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent/SimpleAgent.csproj" />
  </Folder>
  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Handoff/">
@@ -357,7 +373,7 @@
    <Project Path="samples/02-agents/A2A/A2AAgent_PollingForTaskCompletion/A2AAgent_PollingForTaskCompletion.csproj" />
    <Project Path="samples/02-agents/A2A/A2AAgent_ProtocolSelection/A2AAgent_ProtocolSelection.csproj" />
    <Project Path="samples/02-agents/A2A/A2AAgent_StreamReconnection/A2AAgent_StreamReconnection.csproj" />
-  </Folder>  
+  </Folder>
  <Folder Name="/Samples/05-end-to-end/">
    <Project Path="samples/05-end-to-end/AgentWithPurview/AgentWithPurview.csproj" />
    <Project Path="samples/05-end-to-end/M365Agent/M365Agent.csproj" />
@@ -535,6 +551,16 @@
  <Folder Name="/Solution Items/src/Shared/StructuredOutput/">
    <File Path="src/Shared/StructuredOutput/StructuredOutputSchemaUtilities.cs" />
  </Folder>
+  <Folder Name="/Solution Items/src/Shared/Workflows/" />
+  <Folder Name="/Solution Items/src/Shared/Workflows/Execution/">
+    <File Path="src/Shared/Workflows/Execution/README.md" />
+    <File Path="src/Shared/Workflows/Execution/WorkflowFactory.cs" />
+    <File Path="src/Shared/Workflows/Execution/WorkflowRunner.cs" />
+  </Folder>
+  <Folder Name="/Solution Items/src/Shared/Workflows/Settings/">
+    <File Path="src/Shared/Workflows/Settings/Application.cs" />
+    <File Path="src/Shared/Workflows/Settings/README.md" />
+  </Folder>
  <Folder Name="/Solution Items/tests/">
    <File Path="tests/.editorconfig" />
    <File Path="tests/Directory.Build.props" />
@@ -560,6 +586,7 @@
    <Project Path="src/Microsoft.Agents.AI.Hosting.AzureFunctions/Microsoft.Agents.AI.Hosting.AzureFunctions.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Hosting.OpenAI/Microsoft.Agents.AI.Hosting.OpenAI.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Hosting/Microsoft.Agents.AI.Hosting.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Hyperlight/Microsoft.Agents.AI.Hyperlight.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Mem0/Microsoft.Agents.AI.Mem0.csproj" />
    <Project Path="src/Microsoft.Agents.AI.OpenAI/Microsoft.Agents.AI.OpenAI.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Purview/Microsoft.Agents.AI.Purview.csproj" />
@@ -576,11 +603,14 @@
    <Project Path="tests/AnthropicChatCompletion.IntegrationTests/AnthropicChatCompletion.IntegrationTests.csproj" />
    <Project Path="tests/AzureAIAgentsPersistent.IntegrationTests/AzureAIAgentsPersistent.IntegrationTests.csproj" />
    <Project Path="tests/CopilotStudio.IntegrationTests/CopilotStudio.IntegrationTests.csproj" />
+    <Project Path="tests/Foundry.Hosting.IntegrationTests/Foundry.Hosting.IntegrationTests.csproj" />
+    <Project Path="tests/Foundry.Hosting.IntegrationTests.TestContainer/Foundry.Hosting.IntegrationTests.TestContainer.csproj" />
    <Project Path="tests/Foundry.IntegrationTests/Foundry.IntegrationTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.DurableTask.IntegrationTests/Microsoft.Agents.AI.DurableTask.IntegrationTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.IntegrationTests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.IntegrationTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Hyperlight.IntegrationTests/Microsoft.Agents.AI.Hyperlight.IntegrationTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Mem0.IntegrationTests/Microsoft.Agents.AI.Mem0.IntegrationTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Workflows.Declarative.IntegrationTests/Microsoft.Agents.AI.Workflows.Declarative.IntegrationTests.csproj" />
    <Project Path="tests/OpenAIAssistant.IntegrationTests/OpenAIAssistant.IntegrationTests.csproj" />
@@ -606,6 +636,7 @@
    <Project Path="tests/Microsoft.Agents.AI.Hosting.AzureFunctions.UnitTests/Microsoft.Agents.AI.Hosting.AzureFunctions.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Hosting.UnitTests/Microsoft.Agents.AI.Hosting.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Hyperlight.UnitTests/Microsoft.Agents.AI.Hyperlight.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Mem0.UnitTests/Microsoft.Agents.AI.Mem0.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.OpenAI.UnitTests/Microsoft.Agents.AI.OpenAI.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Purview.UnitTests/Microsoft.Agents.AI.Purview.UnitTests.csproj" />
@@ -30,7 +30,8 @@
      "src\\Microsoft.Agents.AI.Workflows.Generators\\Microsoft.Agents.AI.Workflows.Generators.csproj",
      "src\\Microsoft.Agents.AI.Workflows\\Microsoft.Agents.AI.Workflows.csproj",
      "src\\Microsoft.Agents.AI\\Microsoft.Agents.AI.csproj",
-      "src\\Aspire.Hosting.AgentFramework.DevUI\\Aspire.Hosting.AgentFramework.DevUI.csproj"
+      "src\\Aspire.Hosting.AgentFramework.DevUI\\Aspire.Hosting.AgentFramework.DevUI.csproj",
+      "src\\Microsoft.Agents.AI.Hyperlight\\Microsoft.Agents.AI.Hyperlight.csproj"
    ]
  }
 }
@@ -1,14 +1,14 @@
 <Project>
  <PropertyGroup>
    <!-- Central version prefix - applies to all nuget packages. -->
-    <VersionPrefix>1.3.0</VersionPrefix>
+    <VersionPrefix>1.5.0</VersionPrefix>
    <RCNumber>1</RCNumber>
-    <DateSuffix>260423</DateSuffix>
+    <DateSuffix>260507</DateSuffix>
    <PackageVersion Condition="'$(IsReleaseCandidate)' == 'true'">$(VersionPrefix)-rc$(RCNumber)</PackageVersion>
    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).$(DateSuffix).1</PackageVersion>
    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' == ''">$(VersionPrefix)-preview.$(DateSuffix).1</PackageVersion>
    <PackageVersion Condition="'$(IsReleased)' == 'true'">$(VersionPrefix)</PackageVersion>
-    <GitTag>1.3.0</GitTag>
+    <GitTag>1.5.0</GitTag>

    <Configurations>Debug;Release;Publish</Configurations>
    <IsPackable>true</IsPackable>
@@ -50,12 +50,12 @@ Console.WriteLine(await agent.RunAsync("My name is Ruaidhrí", session));
 Console.WriteLine(await agent.RunAsync("I am 20 years old", session));

 // We can serialize the session. The serialized state will include the state of the memory component.
-JsonElement sesionElement = await agent.SerializeSessionAsync(session);
+JsonElement sessionElement = await agent.SerializeSessionAsync(session);

 Console.WriteLine("\n>> Use deserialized session with previously created memories\n");

 // Later we can deserialize the session and continue the conversation with the previous memory component state.
-var deserializedSession = await agent.DeserializeSessionAsync(sesionElement);
+var deserializedSession = await agent.DeserializeSessionAsync(sessionElement);
 Console.WriteLine(await agent.RunAsync("What is my name and age?", deserializedSession));

 Console.WriteLine("\n>> Read memories using memory component\n");
@@ -12,7 +12,9 @@ static Task<PermissionRequestResult> PromptPermission(PermissionRequest request,
    Console.Write("Approve? (y/n): ");

    string? input = Console.ReadLine()?.Trim().ToUpperInvariant();
-    string kind = input is "Y" or "YES" ? "approved" : "denied-interactively-by-user";
+    PermissionRequestResultKind kind = input is "Y" or "YES"
+                                     ? PermissionRequestResultKind.Approved
+                                     : PermissionRequestResultKind.Rejected;

    return Task.FromResult(new PermissionRequestResult { Kind = kind });
 }
@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Hyperlight\Microsoft.Agents.AI.Hyperlight.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,30 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to use HyperlightCodeActProvider as a sandboxed Python
+// code interpreter: the model can write and execute arbitrary Python code to
+// answer quantitative questions without calling any additional tools.
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Hyperlight;
+using OpenAI.Chat;
+
+var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+var guestPath = Environment.GetEnvironmentVariable("HYPERLIGHT_PYTHON_GUEST_PATH") ?? throw new InvalidOperationException("HYPERLIGHT_PYTHON_GUEST_PATH is not set.");
+
+using var codeAct = new HyperlightCodeActProvider(HyperlightCodeActProviderOptions.CreateForWasm(guestPath));
+
+AIAgent agent = new AzureOpenAIClient(
+    new Uri(endpoint),
+    new DefaultAzureCredential())
+    .GetChatClient(deploymentName)
+    .AsAIAgent(new ChatClientAgentOptions()
+    {
+        ChatOptions = new() { Instructions = "You are a helpful assistant. When the user asks something quantitative, write Python and call `execute_code` instead of guessing." },
+        AIContextProviders = [codeAct],
+    });
+
+Console.WriteLine(await agent.RunAsync("What is the 20th Fibonacci number?"));
+Console.WriteLine(await agent.RunAsync("Compute the mean and standard deviation of [1, 4, 9, 16, 25, 36]."));
@@ -0,0 +1,35 @@
+# AgentWithCodeAct_Step01_Interpreter
+
+A minimal CodeAct sample. The agent uses `HyperlightCodeActProvider` as a
+sandboxed Python interpreter: when the user asks something quantitative, the
+model writes Python and invokes the `execute_code` tool rather than answering
+from memory.
+
+## Configuration
+
+| Variable                       | Description                                                                               |
+|--------------------------------|-------------------------------------------------------------------------------------------|
+| `AZURE_OPENAI_ENDPOINT`        | Azure OpenAI endpoint. Required.                                                          |
+| `AZURE_OPENAI_DEPLOYMENT_NAME` | Azure OpenAI deployment. Defaults to `gpt-5.4-mini`.                                      |
+| `HYPERLIGHT_PYTHON_GUEST_PATH` | Absolute path to the Hyperlight Python guest module (`.wasm` or `.aot` file). Required.   |
+
+Authentication uses `DefaultAzureCredential`.
+
+## Getting the guest module
+
+The Python guest module is built from the
+[hyperlight-dev/hyperlight-sandbox](https://github.com/hyperlight-dev/hyperlight-sandbox)
+repository — see its README for the exact `cargo`/`just` invocations and
+the location of the resulting `.wasm` / `.aot` file. Set
+`HYPERLIGHT_PYTHON_GUEST_PATH` to the absolute path of that artifact
+before running the sample.
+
+Hyperlight requires a hardware virtualization back end on the host:
+KVM on Linux or WHP (Windows Hypervisor Platform) on Windows.
+
+## Run
+
+```shell
+cd AgentWithCodeAct_Step01_Interpreter
+dotnet run
+```
@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Hyperlight\Microsoft.Agents.AI.Hyperlight.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,52 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to use HyperlightCodeActProvider with provider-owned
+// tools (exposed inside the sandbox via `call_tool(...)`). The model can
+// orchestrate those tools in a single Python block, reducing round-trips. A
+// sensitive tool (`send_email`) is additionally wrapped in
+// ApprovalRequiredAIFunction so any code that reaches it requires user approval
+// for the entire execute_code invocation.
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Hyperlight;
+using Microsoft.Extensions.AI;
+using OpenAI.Chat;
+
+var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+var guestPath = Environment.GetEnvironmentVariable("HYPERLIGHT_PYTHON_GUEST_PATH") ?? throw new InvalidOperationException("HYPERLIGHT_PYTHON_GUEST_PATH is not set.");
+
+AIFunction fetchDocs = AIFunctionFactory.Create(
+    (string topic) => $"Docs for {topic}: (...)",
+    name: "fetch_docs",
+    description: "Fetch documentation for a given topic.");
+
+AIFunction queryData = AIFunctionFactory.Create(
+    (string query) => $"Rows for `{query}`: []",
+    name: "query_data",
+    description: "Run a read-only SQL-like query against the sample store.");
+
+AIFunction sendEmail = new ApprovalRequiredAIFunction(
+    AIFunctionFactory.Create(
+        (string to, string subject) => $"Sent '{subject}' to {to}.",
+        name: "send_email",
+        description: "Send an email on behalf of the user."));
+
+var options = HyperlightCodeActProviderOptions.CreateForWasm(guestPath);
+options.Tools = [fetchDocs, queryData, sendEmail];
+
+using var codeAct = new HyperlightCodeActProvider(options);
+
+AIAgent agent = new AzureOpenAIClient(
+    new Uri(endpoint),
+    new DefaultAzureCredential())
+    .GetChatClient(deploymentName)
+    .AsAIAgent(new ChatClientAgentOptions()
+    {
+        ChatOptions = new() { Instructions = "You are a helpful assistant. Prefer orchestrating your work in a single `execute_code` block using `call_tool(...)` over issuing many direct tool calls." },
+        AIContextProviders = [codeAct],
+    });
+
+Console.WriteLine(await agent.RunAsync("Look up docs on 'retries' and query the 'orders' table, then summarize."));
@@ -0,0 +1,34 @@
+# AgentWithCodeAct_Step02_ToolEnabled
+
+Demonstrates adding provider-owned tools to `HyperlightCodeActProvider`. Those
+tools are **only** available to code running inside the sandbox via
+`call_tool("<name>", ...)` — they are never exposed to the model as direct
+tools. This lets the model orchestrate multiple tool calls in a single Python
+block.
+
+One tool (`send_email`) is wrapped in `ApprovalRequiredAIFunction`, which causes
+the entire `execute_code` invocation to require user approval when that tool
+is configured.
+
+## Configuration
+
+| Variable                       | Description                                                                               |
+|--------------------------------|-------------------------------------------------------------------------------------------|
+| `AZURE_OPENAI_ENDPOINT`        | Azure OpenAI endpoint. Required.                                                          |
+| `AZURE_OPENAI_DEPLOYMENT_NAME` | Azure OpenAI deployment. Defaults to `gpt-5.4-mini`.                                      |
+| `HYPERLIGHT_PYTHON_GUEST_PATH` | Absolute path to the Hyperlight Python guest module (`.wasm` or `.aot` file). Required.   |
+
+## Run
+
+```shell
+cd AgentWithCodeAct_Step02_ToolEnabled
+dotnet run
+```
+
+## Planned follow-up
+
+A more realistic "upload a file (e.g. an Excel workbook), have the agent
+analyze it with code" sample is planned as a separate step that will use
+`HostInputDirectory` together with a guest tool capable of reading the
+uploaded file. It will be added in a follow-up PR once the corresponding
+guest module support is in place.
@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Hyperlight\Microsoft.Agents.AI.Hyperlight.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,40 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to wire up CodeAct manually using
+// HyperlightExecuteCodeFunction rather than the AIContextProvider. Use this
+// when you want a fixed tool surface for the agent's lifetime and don't need
+// the per-run snapshot/registry semantics of HyperlightCodeActProvider.
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Hyperlight;
+using Microsoft.Extensions.AI;
+using OpenAI.Chat;
+
+var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+var guestPath = Environment.GetEnvironmentVariable("HYPERLIGHT_PYTHON_GUEST_PATH") ?? throw new InvalidOperationException("HYPERLIGHT_PYTHON_GUEST_PATH is not set.");
+
+AIFunction calculate = AIFunctionFactory.Create(
+    (double a, double b) => a * b,
+    name: "multiply",
+    description: "Multiply two numbers.");
+
+var options = HyperlightCodeActProviderOptions.CreateForWasm(guestPath);
+options.Tools = [calculate];
+
+using var executeCode = new HyperlightExecuteCodeFunction(options);
+
+var instructions =
+    "You are a helpful assistant. When math is involved, solve it by writing Python "
+    + "and calling `execute_code` instead of computing values yourself.\n\n"
+    + executeCode.BuildInstructions(toolsVisibleToModel: false);
+
+AIAgent agent = new AzureOpenAIClient(
+    new Uri(endpoint),
+    new DefaultAzureCredential())
+    .GetChatClient(deploymentName)
+    .AsAIAgent(instructions: instructions, tools: [executeCode]);
+
+Console.WriteLine(await agent.RunAsync("What is 12.3 * 4.5? Use the multiply tool from within `execute_code`."));
@@ -0,0 +1,21 @@
+# AgentWithCodeAct_Step03_ManualWiring
+
+Shows how to wire CodeAct manually using `HyperlightExecuteCodeFunction` as a
+direct agent tool instead of via an `AIContextProvider`. This is useful when
+the sandbox's tool surface and capabilities are fixed for the agent's
+lifetime, avoiding per-run snapshot/restore of the provider registry.
+
+## Configuration
+
+| Variable                       | Description                                                                               |
+|--------------------------------|-------------------------------------------------------------------------------------------|
+| `AZURE_OPENAI_ENDPOINT`        | Azure OpenAI endpoint. Required.                                                          |
+| `AZURE_OPENAI_DEPLOYMENT_NAME` | Azure OpenAI deployment. Defaults to `gpt-5.4-mini`.                                      |
+| `HYPERLIGHT_PYTHON_GUEST_PATH` | Absolute path to the Hyperlight Python guest module (`.wasm` or `.aot` file). Required.   |
+
+## Run
+
+```shell
+cd AgentWithCodeAct_Step03_ManualWiring
+dotnet run
+```
@@ -0,0 +1,16 @@
+# Agent Framework CodeAct (Hyperlight) Samples
+
+These samples show how to enable an agent to write and execute code in a
+Hyperlight-backed sandbox via the CodeAct pattern. Guest code can be pure
+Python (interpreter mode) or orchestrate host-provided tools through
+`call_tool(...)` — all inside a secure sandbox with opt-in filesystem and
+network access.
+
+|Sample|Description|
+|---|---|
+|[Code interpreter](./AgentWithCodeAct_Step01_Interpreter/)|Uses `HyperlightCodeActProvider` as a sandboxed Python interpreter with no host tools.|
+|[Tool-enabled CodeAct](./AgentWithCodeAct_Step02_ToolEnabled/)|Registers provider-owned tools that guest code can orchestrate via `call_tool(...)`, with an approval-required tool for sensitive actions.|
+|[Manual wiring](./AgentWithCodeAct_Step03_ManualWiring/)|Uses `HyperlightExecuteCodeFunction` directly as an agent tool when the sandbox configuration is fixed.|
+
+All samples require a Hyperlight Python guest module. Set
+`HYPERLIGHT_PYTHON_GUEST_PATH` to its absolute path before running.
@@ -8,6 +8,11 @@
 // even if the process is interrupted mid-loop, but may also result in chat history that is not
 // yet finalized (e.g., tool calls without results) being persisted, which may be undesirable in some cases.
 //
+// Additionally, this sample demonstrates the MessageInjectingChatClient feature, which allows tool
+// code to inject new user messages during the function execution loop. When a tool or anything else enqueues
+// a message via MessageInjectingChatClient.EnqueueMessages during the tool execution loop, the PerServiceCallChatHistoryPersistingChatClient
+// detects the pending message before the next service call and includes the injected message in the request.
+//
 // To use end-of-run persistence instead (atomic run semantics), remove the
 // RequirePerServiceCallChatHistoryPersistence = true setting (or set it to false). End-of-run
 // persistence is the default behavior.
@@ -54,6 +59,37 @@ static string GetTime([Description("The city name.")] string city) =>
        _ => $"{city}: time data not available."
    };

+// This tool demonstrates message injection during the function execution loop.
+// When called, it checks travel advisories for a city. If an advisory is active, it uses
+// the ambient run context to resolve MessageInjectingChatClient and injects a follow-up user message
+// asking for alternative destinations. The model will process this injected message on the next
+// service call — even though the parent FunctionInvokingChatClient loop would otherwise stop.
+[Description("Check current travel advisories for a city.")]
+static string CheckTravelAdvisory([Description("The city name.")] string city)
+{
+    // Simulated travel advisory data.
+    var advisory = city.ToUpperInvariant() switch
+    {
+        "LONDON" => "Travel advisory: Severe fog warnings in London. Flights may be delayed or cancelled.",
+        "SEATTLE" => "Travel advisory: Heavy rainfall expected. Flooding possible in low-lying areas.",
+        _ => null
+    };
+
+    if (advisory is null)
+    {
+        return $"{city}: No active travel advisories.";
+    }
+
+    // When an advisory is found, inject a follow-up question so the model automatically
+    // suggests alternatives without the user needing to ask.
+    var runContext = AIAgent.CurrentRunContext!;
+    runContext.Agent.GetService<MessageInjectingChatClient>()?.EnqueueMessages(
+        runContext.Session!,
+        [new ChatMessage(ChatRole.User, $"Given the travel advisory for {city}, what alternative cities would you recommend instead?")]);
+
+    return advisory;
+}
+
 // Create the agent — per-service-call persistence is enabled via RequirePerServiceCallChatHistoryPersistence.
 // The in-memory ChatHistoryProvider is used by default when the service does not require service stored chat
 // history, so for those cases, we can inspect the chat history via session.TryGetInMemoryChatHistory().
@@ -65,10 +101,11 @@ AIAgent agent = chatClient.AsAIAgent(
    {
        Name = "WeatherAssistant",
        RequirePerServiceCallChatHistoryPersistence = true,
+        EnableMessageInjection = true,
        ChatOptions = new()
        {
-            Instructions = "You are a helpful assistant. When asked about multiple cities, call the appropriate tool for each city.",
-            Tools = [AIFunctionFactory.Create(GetWeather), AIFunctionFactory.Create(GetTime)]
+            Instructions = "You are a helpful travel assistant. When asked about cities, call the appropriate tools for each city.",
+            Tools = [AIFunctionFactory.Create(GetWeather), AIFunctionFactory.Create(GetTime), AIFunctionFactory.Create(CheckTravelAdvisory)]
        },
    });

@@ -109,6 +146,18 @@ async Task RunNonStreamingAsync()
    response = await agent.RunAsync(FollowUp2, session);
    PrintAgentResponse(response.Text);
    PrintChatHistory(session, "After third run", ref lastChatHistorySize, ref lastConversationId);
+
+    // Fourth turn — demonstrates message injection during the function loop.
+    // The CheckTravelAdvisory tool detects an advisory for London and injects a follow-up
+    // user message asking for alternative cities. After the tool completes, the internal loop
+    // in PerServiceCallChatHistoryPersistingChatClient detects the pending injected message
+    // and calls the service again, so the model answers the follow-up automatically.
+    const string TravelPrompt = "I'm planning to travel to London next week. Check if there are any travel advisories.";
+    PrintUserMessage(TravelPrompt);
+
+    response = await agent.RunAsync(TravelPrompt, session);
+    PrintAgentResponse(response.Text);
+    PrintChatHistory(session, "After travel advisory run", ref lastChatHistorySize, ref lastConversationId);
 }

 async Task RunStreamingAsync()
@@ -181,6 +230,30 @@ async Task RunStreamingAsync()

    Console.WriteLine();
    PrintChatHistory(session, "After third run", ref lastChatHistorySize, ref lastConversationId);
+
+    // Fourth turn — demonstrates message injection during the function loop (streaming).
+    // The CheckTravelAdvisory tool detects an advisory for London and injects a follow-up
+    // user message asking for alternative cities. After the tool completes, the internal loop
+    // in PerServiceCallChatHistoryPersistingChatClient detects the pending injected message
+    // and calls the service again, so the model answers the follow-up automatically.
+    const string TravelPrompt = "I'm planning to travel to London next week. Check if there are any travel advisories.";
+    PrintUserMessage(TravelPrompt);
+
+    Console.ForegroundColor = ConsoleColor.Cyan;
+    Console.Write("\n[Agent] ");
+    Console.ResetColor();
+
+    await foreach (var update in agent.RunStreamingAsync(TravelPrompt, session))
+    {
+        Console.Write(update);
+
+        // During streaming we should be able to see updates to the chat history
+        // before the full run completes, as each service call is made and persisted.
+        PrintChatHistory(session, "During travel advisory run", ref lastChatHistorySize, ref lastConversationId);
+    }
+
+    Console.WriteLine();
+    PrintChatHistory(session, "After travel advisory run", ref lastChatHistorySize, ref lastConversationId);
 }

 void PrintUserMessage(string message)
@@ -6,12 +6,16 @@

    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
-    
  </PropertyGroup>

  <ItemGroup>
-    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry.Hosting\Microsoft.Agents.AI.Foundry.Hosting.csproj" />
-    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.AI.Projects" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="ModelContextProtocol" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
  </ItemGroup>

 </Project>
@@ -1,93 +1,80 @@
 // Copyright (c) Microsoft. All rights reserved.

-// This sample shows how to load a Foundry toolbox and pass its tools as server-side
-// tools when creating an agent. The Foundry platform handles tool execution — the agent
-// process does not invoke tools locally.
+// Foundry Toolbox via MCP (Streamable HTTP).
+//
+// Point an `McpClient` at a Foundry Toolbox's MCP endpoint. The agent
+// discovers the toolbox's tools at runtime and invokes them locally.

 using System.ClientModel;
 using System.ClientModel.Primitives;
+using System.Net.Http.Headers;
 using Azure.AI.Projects;
 using Azure.AI.Projects.Agents;
+using Azure.Core;
 using Azure.Identity;
 using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using ModelContextProtocol.Client;
 using OpenAI.Responses;

 #pragma warning disable OPENAI001 // Experimental API
 #pragma warning disable AAIP001  // AgentToolboxes is experimental
-#pragma warning disable CS8321   // Local functions may be commented-out alternatives

-// Replace with your own Foundry toolbox name.
+// Must match the `<name>` segment of FOUNDRY_TOOLBOX_ENDPOINT.
 const string ToolboxName = "research_toolbox";
-// Used only by CombineToolboxes — swap in a second toolbox you own.
-const string SecondToolboxName = "analysis_toolbox";
-// Replace with any question that exercises the tools configured in your toolbox.
-const string Query = "Introduce yourself and briefly describe the tools you can use to help me.";
+const string Query = "What tools do you have access to?";

-string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
-    ?? throw new InvalidOperationException("Set FOUNDRY_PROJECT_ENDPOINT to your Foundry project endpoint.");
-string model = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
+string endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+string toolboxEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_TOOLBOX_ENDPOINT")
+    ?? throw new InvalidOperationException(
+        "FOUNDRY_TOOLBOX_ENDPOINT is not set. Example: " +
+        "https://<account>.services.ai.azure.com/api/projects/<project>/toolsets/<name>/mcp?api-version=2025-05-01-preview");
+
+TokenCredential credential = new DefaultAzureCredential();
+
+// Comment out if the toolbox already exists in your Foundry project.
+await CreateSampleToolboxAsync(ToolboxName, endpoint, credential);
+
+// Inject a fresh Azure AI bearer token on every MCP request.
+using var httpClient = new HttpClient(new BearerTokenHandler(credential, "https://ai.azure.com/.default")
+{
+    InnerHandler = new HttpClientHandler(),
+});
+
+Console.WriteLine($"Connecting to toolbox MCP endpoint: {toolboxEndpoint}");
+
+await using McpClient mcpClient = await McpClient.CreateAsync(
+    new HttpClientTransport(
+        new HttpClientTransportOptions
+        {
+            Endpoint = new Uri(toolboxEndpoint),
+            Name = "foundry_toolbox",
+        },
+        httpClient));
+
+IList<McpClientTool> mcpTools = await mcpClient.ListToolsAsync();
+Console.WriteLine($"Toolbox MCP tools available: {string.Join(", ", mcpTools.Select(t => t.Name))}");

 // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
 // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
 // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-var projectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential());
+AIProjectClient aiProjectClient = new(new Uri(endpoint), credential);

-await Main(projectClient, model, endpoint);
-// await CombineToolboxes(projectClient, model, endpoint);
+AIAgent agent = aiProjectClient.AsAIAgent(
+    model: deploymentName,
+    instructions: "You are a helpful assistant. Use the available toolbox tools to answer the user.",
+    name: "ToolboxMcpAgent",
+    tools: [.. mcpTools.Cast<AITool>()]);
+
+Console.WriteLine($"\nUser: {Query}\n");
+Console.WriteLine($"Assistant: {await agent.RunAsync(Query)}");

 // ---------------------------------------------------------------------------
-// Main: single toolbox
+// Helper: create (or replace) a sample toolbox so the sample runs end-to-end
 // ---------------------------------------------------------------------------
-static async Task Main(AIProjectClient projectClient, string model, string endpoint)
-{
-    Console.WriteLine("=== Foundry Toolbox Server-Side Tools Example ===");
-
-    // Comment out if the toolbox already exists in your Foundry project.
-    await CreateSampleToolboxAsync(ToolboxName, endpoint);
-
-    // Omit the version to resolve the toolbox's current default version at runtime.
-    var tools = await projectClient.GetToolboxToolsAsync(ToolboxName);
-
-    AIAgent agent = projectClient
-        .AsAIAgent(
-            model: model,
-            instructions: "You are a research assistant. Use the available tools to answer questions.",
-            tools: tools.ToList());
-
-    Console.WriteLine($"User: {Query}");
-    Console.WriteLine($"Result: {await agent.RunAsync(Query)}\n");
-}
-
-// ---------------------------------------------------------------------------
-// Alternative: combine tools from multiple toolboxes
-// ---------------------------------------------------------------------------
-static async Task CombineToolboxes(AIProjectClient projectClient, string model, string endpoint)
-{
-    Console.WriteLine("=== Combine Toolboxes Example ===");
-
-    // Comment out if the toolboxes already exist in your Foundry project.
-    await CreateSampleToolboxAsync(ToolboxName, endpoint);
-    await CreateSampleToolboxAsync(SecondToolboxName, endpoint);
-
-    var toolboxA = await projectClient.GetToolboxToolsAsync(ToolboxName);
-    var toolboxB = await projectClient.GetToolboxToolsAsync(SecondToolboxName);
-
-    var allTools = toolboxA.Concat(toolboxB).ToList();
-
-    AIAgent agent = projectClient
-        .AsAIAgent(
-            model: model,
-            instructions: "You are a research assistant. Use all available tools to answer questions.",
-            tools: allTools);
-
-    Console.WriteLine($"User: {Query}");
-    Console.WriteLine($"Combined-toolbox result: {await agent.RunAsync(Query)}\n");
-}
-
-// ---------------------------------------------------------------------------
-// Helper: create (or replace) a sample toolbox so the sample works out-of-the-box
-// ---------------------------------------------------------------------------
-static async Task CreateSampleToolboxAsync(string name, string endpoint)
+static async Task CreateSampleToolboxAsync(string name, string endpoint, TokenCredential credential)
 {
    // Toolboxes are normally configured in the Foundry portal or a deployment
    // script, not the application itself. This helper exists so the sample can
@@ -96,10 +83,7 @@ static async Task CreateSampleToolboxAsync(string name, string endpoint)
    // The Foundry-Features header is currently required for toolbox CRUD operations.
    var options = new AgentAdministrationClientOptions();
    options.AddPolicy(new FoundryFeaturesPolicy("Toolboxes=V1Preview"), PipelinePosition.PerCall);
-    var adminClient = new AgentAdministrationClient(
-        new Uri(endpoint),
-        new DefaultAzureCredential(),
-        options);
+    var adminClient = new AgentAdministrationClient(new Uri(endpoint), credential, options);
    var toolboxClient = adminClient.GetAgentToolboxes();

    // Delete existing toolbox if present (ignore 404).
@@ -128,7 +112,7 @@ static async Task CreateSampleToolboxAsync(string name, string endpoint)
 }

 // ---------------------------------------------------------------------------
-// Pipeline policy that adds the Foundry-Features header for toolbox CRUD
+// Pipeline policy: adds the Foundry-Features header for toolbox CRUD calls
 // ---------------------------------------------------------------------------
 internal sealed class FoundryFeaturesPolicy(string feature) : PipelinePolicy
 {
@@ -146,3 +130,18 @@ internal sealed class FoundryFeaturesPolicy(string feature) : PipelinePolicy
        return ProcessNextAsync(message, pipeline, currentIndex);
    }
 }
+
+// ---------------------------------------------------------------------------
+// DelegatingHandler: attaches a fresh Azure AI bearer token to every request
+// ---------------------------------------------------------------------------
+internal sealed class BearerTokenHandler(TokenCredential credential, string scope) : DelegatingHandler
+{
+    private readonly TokenRequestContext _tokenContext = new([scope]);
+
+    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
+    {
+        AccessToken token = await credential.GetTokenAsync(this._tokenContext, cancellationToken).ConfigureAwait(false);
+        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token.Token);
+        return await base.SendAsync(request, cancellationToken).ConfigureAwait(false);
+    }
+}
@@ -0,0 +1,31 @@
+# Foundry Toolbox via MCP
+
+This sample shows how to use a Foundry Toolbox by pointing an `McpClient` at the toolbox's MCP endpoint. The agent discovers the toolbox's tools at runtime and invokes them locally over MCP.
+
+## What this sample demonstrates
+
+- Connecting to a Foundry toolbox's MCP endpoint via Streamable HTTP transport
+- Injecting a fresh Azure AI bearer token (`https://ai.azure.com/.default`) on every MCP request
+- Passing the discovered MCP tools to `AIProjectClient.AsAIAgent(...)`
+- Optional helper to create (or replace) a sample toolbox in the project so the sample is runnable end-to-end
+
+## Prerequisites
+
+- A Microsoft Foundry project with a toolbox configured (or let the sample create one for you)
+- Azure CLI installed and authenticated (`az login`)
+
+Set the following environment variables:
+
+```powershell
+$env:AZURE_AI_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project"
+$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-5.4-mini"
+$env:FOUNDRY_TOOLBOX_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project/toolsets/research_toolbox/mcp?api-version=2025-05-01-preview"
+```
+
+The `<name>` segment of `FOUNDRY_TOOLBOX_ENDPOINT` must match the `ToolboxName` constant in `Program.cs`.
+
+## Run the sample
+
+```powershell
+dotnet run
+```
@@ -1,46 +0,0 @@
-# Agent_Step25_ToolboxServerSideTools
-
-This sample demonstrates loading a named Foundry toolbox and passing its tools as
-**server-side tools** when creating an agent via `AsAIAgent()`.
-
-When tools from a toolbox are passed this way, they are sent as tool definitions in
-the Responses API request. The Foundry platform handles tool execution — the agent
-process does not invoke tools locally.
-
-This is the dotnet equivalent of the Python sample:
-`python/samples/02-agents/providers/foundry/foundry_chat_client_with_toolbox.py`
-
-## Prerequisites
-
- A Microsoft Foundry project
- `AZURE_AI_PROJECT_ENDPOINT` environment variable set to your Foundry project endpoint
- `AZURE_AI_MODEL_DEPLOYMENT_NAME` environment variable set (defaults to `gpt-5.4-mini`)
-
-The sample recreates the toolbox on each run, replacing any existing toolbox with
-the same name. Comment out the `CreateSampleToolboxAsync` call if you want to keep
-an existing toolbox unchanged.
-
-## How it works
-
-1. `projectClient.GetToolboxVersionAsync(name)` fetches the toolbox definition from the
-   Foundry project API (resolving the default version if none is specified)
-2. `ToolboxVersion.ToAITools()` converts each tool definition to an `AITool` instance
-3. The tools are passed to `AsAIAgent(tools: ...)` which includes them in the Responses
-   API request as server-side tool definitions
-
-For a one-liner, use `projectClient.GetToolboxToolsAsync(name)` to fetch and convert in one call.
-
-## Sample flows
-
-| Flow | Description |
-|------|-------------|
-| `Main` (default) | Loads a single toolbox and runs an agent with its tools |
-| `CombineToolboxes` | Loads two toolboxes and merges their tools into one agent |
-
-Uncomment the desired flow in the top-level statements to try each one.
-
-## Running the sample
-
-```bash
-dotnet run
-```
@@ -73,6 +73,7 @@ Some samples require extra tool-specific environment variables. See each sample
 | [Memory search](./Agent_Step22_MemorySearch/) | Memory search tool |
 | [Local MCP](./Agent_Step23_LocalMCP/) | Local MCP client with HTTP transport |
 | [Code interpreter file download](./Agent_Step24_CodeInterpreterFileDownload/) | Download container files generated by code interpreter |
+| [Foundry toolbox via MCP](./Agent_Step25_FoundryToolboxMcp/) | Use a Foundry Toolbox from a non-hosted agent via its MCP endpoint |

 ## Running the samples

@@ -24,5 +24,5 @@ public interface ICommandHandler
    /// <param name="input">The raw user input string.</param>
    /// <param name="session">The current agent session.</param>
    /// <returns><see langword="true"/> if this handler handled the input; <see langword="false"/> otherwise.</returns>
-    bool TryHandle(string input, AgentSession session);
+    ValueTask<bool> TryHandleAsync(string input, AgentSession session);
 }
@@ -27,17 +27,17 @@ internal sealed class ModeCommandHandler : ICommandHandler
    public string? GetHelpText() => this._modeProvider is not null ? "/mode [plan|execute] (show or switch mode)" : null;

    /// <inheritdoc/>
-    public bool TryHandle(string input, AgentSession session)
+    public ValueTask<bool> TryHandleAsync(string input, AgentSession session)
    {
        if (!input.StartsWith("/mode ", StringComparison.OrdinalIgnoreCase) && !input.Equals("/mode", StringComparison.OrdinalIgnoreCase))
        {
-            return false;
+            return ValueTask.FromResult(false);
        }

        if (this._modeProvider is null)
        {
            System.Console.WriteLine("AgentModeProvider is not available.");
-            return true;
+            return ValueTask.FromResult(true);
        }

        string[] parts = input.Split(' ', 2, StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
@@ -45,7 +45,7 @@ internal sealed class ModeCommandHandler : ICommandHandler
        {
            string current = this._modeProvider.GetMode(session);
            System.Console.WriteLine($"\n  Current mode: {current}\n");
-            return true;
+            return ValueTask.FromResult(true);
        }

        string newMode = parts[1];
@@ -64,6 +64,6 @@ internal sealed class ModeCommandHandler : ICommandHandler
            System.Console.ResetColor();
        }

-        return true;
+        return ValueTask.FromResult(true);
    }
 }
@@ -24,7 +24,7 @@ internal sealed class TodoCommandHandler : ICommandHandler
    public string? GetHelpText() => this._todoProvider is not null ? "/todos (show todo list)" : null;

    /// <inheritdoc/>
-    public bool TryHandle(string input, AgentSession session)
+    public async ValueTask<bool> TryHandleAsync(string input, AgentSession session)
    {
        if (!input.Equals("/todos", StringComparison.OrdinalIgnoreCase))
        {
@@ -37,7 +37,7 @@ internal sealed class TodoCommandHandler : ICommandHandler
            return true;
        }

-        var todos = this._todoProvider.GetAllTodos(session);
+        var todos = await this._todoProvider.GetAllTodosAsync(session).ConfigureAwait(false);
        if (todos.Count == 0)
        {
            System.Console.WriteLine("\n  No todos yet.\n");
@@ -69,7 +69,7 @@ public static class HarnessConsole
            bool handled = false;
            foreach (var handler in commandHandlers)
            {
-                if (handler.TryHandle(userInput, session))
+                if (await handler.TryHandleAsync(userInput, session).ConfigureAwait(false))
                {
                    handled = true;
                    break;
@@ -165,7 +165,8 @@ AIAgent agent =
                Tools =
                [
                    ResponseTool.CreateWebSearchTool().AsAITool(),          // Add the foundry hosted web search tool that runs in the service.
-                    new WebBrowsingTool(),                                  // Add a local web browsing tool that converts html to markdown.
+                    new WebBrowsingTool(                                    // Add a local web browsing tool that converts html to markdown.
+                        new WebBrowsingToolOptions { AllowPublicNetworks = true }),
                ],
                MaxOutputTokens = MaxOutputTokens,                          // Set a high token limit for long research tasks with many tool calls and long outputs.
                Reasoning = new() { Effort = ReasoningEffort.Medium },
@@ -2,6 +2,7 @@

 using System.ComponentModel;
 using System.Net;
+using System.Net.Sockets;
 using System.Text.Json;
 using System.Text.RegularExpressions;
 using Microsoft.Extensions.AI;
@@ -10,11 +11,23 @@ namespace SampleApp;

 /// <summary>
 /// An AI function that downloads HTML pages and converts them to markdown.
+/// Access is controlled by <see cref="WebBrowsingToolOptions"/> — by default, no hosts are accessible.
 /// </summary>
 internal sealed partial class WebBrowsingTool : AIFunction
 {
    private static readonly HttpClient s_httpClient = new();
-    private readonly AIFunction _inner = AIFunctionFactory.Create(DownloadUriAsync);
+    private readonly AIFunction _inner;
+    private readonly WebBrowsingToolOptions _options;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="WebBrowsingTool"/> class.
+    /// </summary>
+    /// <param name="options">Options controlling which URLs are permitted. By default, no hosts are accessible.</param>
+    public WebBrowsingTool(WebBrowsingToolOptions options)
+    {
+        this._options = options ?? throw new ArgumentNullException(nameof(options));
+        this._inner = AIFunctionFactory.Create(this.DownloadUriAsync);
+    }

    /// <inheritdoc/>
    public override string Name => this._inner.Name;
@@ -32,7 +45,7 @@ internal sealed partial class WebBrowsingTool : AIFunction
        this._inner.InvokeAsync(arguments, cancellationToken);

    [Description("Fetch the html from the given url as markdown")]
-    private static async Task<string> DownloadUriAsync(
+    private async Task<string> DownloadUriAsync(
        [Description("The URL to download")] string uri,
        CancellationToken cancellationToken = default)
    {
@@ -46,9 +59,12 @@ internal sealed partial class WebBrowsingTool : AIFunction
            return $"Error: Only HTTP and HTTPS URLs are supported. Got: '{parsedUri.Scheme}'.";
        }

-        // NOTE: In production scenarios, consider also blocking requests to private/internal IP
-        // ranges (e.g., 10.x.x.x, 172.16-31.x.x, 192.168.x.x, 127.0.0.1, 169.254.169.254)
-        // to prevent SSRF attacks via prompt injection in web content.
+        // Check access policy.
+        string? accessError = await this.CheckAccessAsync(parsedUri, cancellationToken);
+        if (accessError is not null)
+        {
+            return accessError;
+        }

        try
        {
@@ -61,6 +77,142 @@ internal sealed partial class WebBrowsingTool : AIFunction
        }
    }

+    /// <summary>
+    /// Checks whether the given URI is permitted by the configured access policy.
+    /// Returns null if allowed, or an error message string if blocked.
+    /// </summary>
+    private async Task<string?> CheckAccessAsync(Uri uri, CancellationToken cancellationToken)
+    {
+        string host = uri.Host;
+
+        // 1. Check AllowedHosts.
+        if (this._options.AllowedHosts is { Count: > 0 } allowedHosts)
+        {
+            foreach (string pattern in allowedHosts)
+            {
+                if (HostMatchesPattern(host, pattern))
+                {
+                    return null; // Allowed by explicit host list.
+                }
+            }
+        }
+
+        // 2. Short-circuit when the policy is guaranteed to block.
+        if (!this._options.AllowPublicNetworks &&
+            !this._options.AllowPrivateNetworks &&
+            !this._options.AllowAllHosts)
+        {
+            return $"Error: Access to '{host}' is blocked by the current access policy. Configure WebBrowsingToolOptions to allow access.";
+        }
+
+        // 3. Resolve DNS to determine if the host is public or private.
+        IPAddress[] addresses;
+        try
+        {
+            addresses = await Dns.GetHostAddressesAsync(host, cancellationToken);
+        }
+        catch (SocketException)
+        {
+            return $"Error: Could not resolve host '{host}'.";
+        }
+
+        if (addresses.Length == 0)
+        {
+            return $"Error: Could not resolve host '{host}'.";
+        }
+
+        bool isPrivate = Array.Exists(addresses, IsPrivateAddress);
+
+        // 4. If public and AllowPublicNetworks is true → allow.
+        if (!isPrivate && this._options.AllowPublicNetworks)
+        {
+            return null;
+        }
+
+        // 5. If private and AllowPrivateNetworks is true → allow.
+        if (isPrivate && this._options.AllowPrivateNetworks)
+        {
+            return null;
+        }
+
+        // 6. If AllowAllHosts is true → allow.
+        if (this._options.AllowAllHosts)
+        {
+            return null;
+        }
+
+        // 7. Block.
+        string networkType = isPrivate ? "private/internal network" : "public network";
+        return $"Error: Access to '{host}' is blocked. The host resolves to a {networkType} address and the current access policy does not permit this. " +
+               "Configure WebBrowsingToolOptions to allow access.";
+    }
+
+    /// <summary>
+    /// Checks whether a host matches a pattern. Supports exact match and wildcard prefix (e.g., "*.example.com").
+    /// </summary>
+    private static bool HostMatchesPattern(string host, string pattern)
+    {
+        if (string.Equals(host, pattern, StringComparison.OrdinalIgnoreCase))
+        {
+            return true;
+        }
+
+        // Wildcard prefix: "*.example.com" matches "sub.example.com" and "a.b.example.com".
+        if (pattern.StartsWith("*.", StringComparison.Ordinal))
+        {
+            string suffix = pattern[1..]; // ".example.com"
+            return host.EndsWith(suffix, StringComparison.OrdinalIgnoreCase);
+        }
+
+        return false;
+    }
+
+    /// <summary>
+    /// Determines whether an IP address is private, loopback, or link-local.
+    /// </summary>
+    private static bool IsPrivateAddress(IPAddress address)
+    {
+        if (address.IsIPv4MappedToIPv6)
+        {
+            address = address.MapToIPv4();
+        }
+
+        if (IPAddress.IsLoopback(address))
+        {
+            return true;
+        }
+
+        if (address.AddressFamily == AddressFamily.InterNetwork)
+        {
+            byte[] bytes = address.GetAddressBytes();
+            return bytes[0] switch
+            {
+                10 => true,                                          // 10.0.0.0/8
+                172 => bytes[1] >= 16 && bytes[1] <= 31,             // 172.16.0.0/12
+                192 => bytes[1] == 168,                              // 192.168.0.0/16
+                169 => bytes[1] == 254,                              // 169.254.0.0/16 (link-local + metadata)
+                _ => false
+            };
+        }
+
+        if (address.AddressFamily == AddressFamily.InterNetworkV6)
+        {
+            // fe80::/10 (link-local) or fc00::/7 (unique local).
+            byte[] bytes = address.GetAddressBytes();
+            if (bytes[0] == 0xfe && (bytes[1] & 0xc0) == 0x80)
+            {
+                return true; // Link-local
+            }
+
+            if ((bytes[0] & 0xfe) == 0xfc)
+            {
+                return true; // Unique local
+            }
+        }
+
+        return false;
+    }
+
    /// <summary>
    /// A simple HTML to Markdown converter using regex-based transformations.
    /// Handles the most common HTML elements without requiring external dependencies.
@@ -0,0 +1,60 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace SampleApp;
+
+/// <summary>
+/// Options that control which URLs the <see cref="WebBrowsingTool"/> is permitted to access.
+/// </summary>
+/// <remarks>
+/// <para>
+/// By default, <b>no hosts are accessible</b>. You must explicitly opt in to one or more
+/// of the access modes below. The validation order is:
+/// </para>
+/// <list type="number">
+/// <item><description>If the host matches an entry in <see cref="AllowedHosts"/>, the request is allowed.</description></item>
+/// <item><description>If the resolved IP is a public address and <see cref="AllowPublicNetworks"/> is <see langword="true"/>, the request is allowed.</description></item>
+/// <item><description>If the resolved IP is a private/loopback/link-local address and <see cref="AllowPrivateNetworks"/> is <see langword="true"/>, the request is allowed.</description></item>
+/// <item><description>If <see cref="AllowAllHosts"/> is <see langword="true"/>, the request is allowed.</description></item>
+/// <item><description>Otherwise, the request is blocked.</description></item>
+/// </list>
+/// </remarks>
+internal sealed class WebBrowsingToolOptions
+{
+    /// <summary>
+    /// Gets or sets a list of host patterns that are always permitted, regardless of other settings.
+    /// Patterns support wildcard prefix matching (e.g., <c>"*.example.com"</c> matches <c>"docs.example.com"</c>).
+    /// Exact host names (e.g., <c>"docs.microsoft.com"</c>) are also supported.
+    /// </summary>
+    /// <remarks>This has the highest priority — if a host matches, it is allowed immediately.</remarks>
+    public IReadOnlyList<string>? AllowedHosts { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether public internet hosts (non-private, non-loopback, non-link-local IPs) are permitted.
+    /// Default is <see langword="false"/>.
+    /// </summary>
+    public bool AllowPublicNetworks { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether private network hosts are permitted.
+    /// This includes RFC 1918 addresses (10.x.x.x, 172.16-31.x.x, 192.168.x.x),
+    /// loopback (127.x.x.x, ::1), link-local (169.254.x.x, fe80::),
+    /// and cloud metadata endpoints (169.254.169.254).
+    /// Default is <see langword="false"/>.
+    /// </summary>
+    /// <remarks>
+    /// <b>Warning:</b> Enabling this allows the agent to make requests to internal services,
+    /// localhost, and cloud metadata endpoints. Only enable this if you understand the SSRF risks.
+    /// </remarks>
+    public bool AllowPrivateNetworks { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether all hosts are permitted without any restriction.
+    /// Default is <see langword="false"/>.
+    /// </summary>
+    /// <remarks>
+    /// <b>⚠️ UNSAFE:</b> Enabling this disables all network boundary checks and allows the agent
+    /// to access any URL, including internal services, cloud metadata endpoints, and localhost.
+    /// Only use this for trusted, isolated environments where SSRF is not a concern.
+    /// </remarks>
+    public bool AllowAllHosts { get; set; }
+}
@@ -11,6 +11,7 @@ The getting started samples demonstrate the fundamental concepts and functionali
 | [Agent Providers](./AgentProviders/README.md) | Getting started with creating agents using various providers |
 | [Agents With Retrieval Augmented Generation (RAG)](./AgentWithRAG/README.md) | Adding Retrieval Augmented Generation (RAG) capabilities to your agents |
 | [Agents With Memory](./AgentWithMemory/README.md) | Adding memory capabilities to your agents |
+| [Agents With CodeAct (Hyperlight)](./AgentWithCodeAct/README.md) | Enabling sandboxed code execution (CodeAct) for your agents via Hyperlight |
 | [Agent Open Telemetry](./AgentOpenTelemetry/README.md) | Getting started with OpenTelemetry for agents |
 | [Agent With OpenAI exchange types](./AgentWithOpenAI/README.md) | Using OpenAI exchange types with agents |
 | [Agent With Anthropic](./AgentWithAnthropic/README.md) | Getting started with agents using Anthropic Claude |
@@ -0,0 +1,8 @@
+AZURE_AI_PROJECT_ENDPOINT=<your-azure-ai-project-endpoint>
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+AZURE_SEARCH_ENDPOINT=<your-azure-search-endpoint>
+AZURE_SEARCH_INDEX_NAME=contoso-outdoors
+AZURE_BEARER_TOKEN_FOUNDRY=DefaultAzureCredential
+AZURE_BEARER_TOKEN_SEARCH=DefaultAzureCredential
+ASPNETCORE_URLS=http://+:8088
+ASPNETCORE_ENVIRONMENT=Development
@@ -0,0 +1,17 @@
+# Use the official .NET 10.0 ASP.NET runtime as a parent image
+FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
+WORKDIR /app
+
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /src
+COPY . .
+RUN dotnet restore
+RUN dotnet publish -c Release -o /app/publish
+
+# Final stage
+FROM base AS final
+WORKDIR /app
+COPY --from=build /app/publish .
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+ENTRYPOINT ["dotnet", "HostedAzureSearchRag.dll"]
@@ -0,0 +1,23 @@
+# Dockerfile for contributors building from the agent-framework repository source.
+#
+# This project uses ProjectReference to the local Microsoft.Agents.AI.Foundry source,
+# which means a standard multi-stage Docker build cannot resolve dependencies outside
+# this folder. Instead, pre-publish the app targeting the container runtime and copy
+# the output into the container:
+#
+#   dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+#   docker build -f Dockerfile.contributor -t hosted-azure-search-rag .
+#   docker run --rm -p 8088:8088 \
+#     -e AGENT_NAME=hosted-azure-search-rag \
+#     -e AZURE_BEARER_TOKEN_FOUNDRY=$AZURE_BEARER_TOKEN_FOUNDRY \
+#     -e AZURE_BEARER_TOKEN_SEARCH=$AZURE_BEARER_TOKEN_SEARCH \
+#     --env-file .env hosted-azure-search-rag
+#
+# For end-users consuming the NuGet package (not ProjectReference), use the standard
+# Dockerfile which performs a full dotnet restore + publish inside the container.
+FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final
+WORKDIR /app
+COPY out/ .
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+ENTRYPOINT ["dotnet", "HostedAzureSearchRag.dll"]
@@ -0,0 +1,35 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <CentralPackageTransitivePinningEnabled>false</CentralPackageTransitivePinningEnabled>
+    <RootNamespace>HostedAzureSearchRag</RootNamespace>
+    <AssemblyName>HostedAzureSearchRag</AssemblyName>
+    <NoWarn>$(NoWarn);</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Azure.Search.Documents" />
+    <PackageReference Include="DotNetEnv" />
+  </ItemGroup>
+
+  <!-- For contributors: uses ProjectReference to build against local source -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry.Hosting\Microsoft.Agents.AI.Foundry.Hosting.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+  <!-- For end-users: uncomment the PackageReference below and remove the ProjectReferences above
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.Foundry" Version="1.0.0" />
+    <PackageReference Include="Microsoft.Agents.AI.Foundry.Hosting" Version="1.0.0" />
+    <PackageReference Include="Microsoft.Agents.AI.OpenAI" Version="1.0.0" />
+  </ItemGroup>
+  -->
+
+</Project>
@@ -0,0 +1,171 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to add Retrieval Augmented Generation (RAG) capabilities to a hosted
+// agent using Azure AI Search. The sample assumes the search index has already been provisioned
+// and populated out of band (see README.md for the required schema and example seed content).
+// A SearchClient-backed adapter is plugged into TextSearchProvider, which runs a keyword search
+// against the index before each model invocation and injects the matching documents into the
+// model context.
+
+using Azure;
+using Azure.AI.Projects;
+using Azure.Core;
+using Azure.Identity;
+using Azure.Search.Documents;
+using Azure.Search.Documents.Models;
+using DotNetEnv;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry.Hosting;
+using Microsoft.Extensions.AI;
+using OpenAI.Chat;
+
+// Load .env file if present (for local development)
+Env.TraversePath().Load();
+
+string projectEndpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";
+
+string searchEndpoint = Environment.GetEnvironmentVariable("AZURE_SEARCH_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_SEARCH_ENDPOINT is not set.");
+string searchIndexName = Environment.GetEnvironmentVariable("AZURE_SEARCH_INDEX_NAME")
+    ?? throw new InvalidOperationException("AZURE_SEARCH_INDEX_NAME is not set.");
+
+// Use a chained credential. Try a temporary dev token first (for local Docker debugging),
+// then fall back to DefaultAzureCredential (for local dev via dotnet run / managed identity in
+// production). The dev credential is scope aware so a single instance serves both Foundry and
+// Azure AI Search clients (each Azure SDK client requests a token for its own audience).
+TokenCredential credential = new ChainedTokenCredential(
+    new DevTemporaryTokenCredential(),
+    new DefaultAzureCredential());
+
+// Connect to the pre-provisioned search index. The caller is expected to have created the
+// index and populated it with documents matching the schema (id / content / sourceName /
+// sourceLink) before running this sample. See README.md for an example provisioning script.
+var searchClient = new SearchClient(new Uri(searchEndpoint), searchIndexName, credential);
+
+TextSearchProviderOptions textSearchOptions = new()
+{
+    SearchTime = TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke,
+    RecentMessageMemoryLimit = 6,
+};
+
+AIAgent agent = new AIProjectClient(new Uri(projectEndpoint), credential)
+    .AsAIAgent(new ChatClientAgentOptions
+    {
+        Name = Environment.GetEnvironmentVariable("AGENT_NAME") ?? "hosted-azure-search-rag",
+        ChatOptions = new ChatOptions
+        {
+            ModelId = deploymentName,
+            Instructions = "You are a helpful support specialist for Contoso Outdoors. " +
+                           "Answer questions using the provided context and cite the source document when available.",
+        },
+        AIContextProviders = [new TextSearchProvider(CreateSearchAdapter(searchClient), textSearchOptions)]
+    });
+
+// Host the agent as a Foundry Hosted Agent using the Responses API.
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddFoundryResponses(agent);
+
+var app = builder.Build();
+app.MapFoundryResponses();
+
+if (app.Environment.IsDevelopment())
+{
+    app.MapFoundryResponses("openai/v1");
+}
+
+app.Run();
+
+// ── Search adapter ───────────────────────────────────────────────────────────
+// Wraps a SearchClient as the delegate TextSearchProvider expects. Keyword/full-text only;
+// no embeddings. Returns the top results and projects them into TextSearchResult entries
+// the provider will inject into the model context.
+
+static Func<string, CancellationToken, Task<IEnumerable<TextSearchProvider.TextSearchResult>>>
+    CreateSearchAdapter(SearchClient client, int top = 3) =>
+    async (query, cancellationToken) =>
+    {
+        var options = new SearchOptions { Size = top };
+        Response<SearchResults<SearchDocument>> response =
+            await client.SearchAsync<SearchDocument>(query, options, cancellationToken).ConfigureAwait(false);
+
+        var results = new List<TextSearchProvider.TextSearchResult>();
+        await foreach (SearchResult<SearchDocument> hit in response.Value.GetResultsAsync().WithCancellation(cancellationToken).ConfigureAwait(false))
+        {
+            results.Add(new TextSearchProvider.TextSearchResult
+            {
+                SourceName = hit.Document.TryGetValue("sourceName", out var name) ? name?.ToString() ?? string.Empty : string.Empty,
+                SourceLink = hit.Document.TryGetValue("sourceLink", out var link) ? link?.ToString() ?? string.Empty : string.Empty,
+                Text = hit.Document.TryGetValue("content", out var content) ? content?.ToString() ?? string.Empty : string.Empty,
+                RawRepresentation = hit
+            });
+        }
+
+        return results;
+    };
+
+/// <summary>
+/// A scope aware <see cref="TokenCredential"/> for local Docker debugging only.
+/// Reads pre-fetched bearer tokens from environment variables, dispensing the right token
+/// based on the requested scope:
+/// <list type="bullet">
+///   <item><description><c>ai.azure.com</c> scopes -> <c>AZURE_BEARER_TOKEN_FOUNDRY</c></description></item>
+///   <item><description><c>search.azure.com</c> scopes -> <c>AZURE_BEARER_TOKEN_SEARCH</c></description></item>
+/// </list>
+/// For any other scope, throws <see cref="CredentialUnavailableException"/> so a chained
+/// credential will fall through. This should NOT be used in production: tokens expire (~1 hour)
+/// and cannot be refreshed.
+///
+/// Generate the tokens on your host and pass them to the container:
+/// <code>
+///   export AZURE_BEARER_TOKEN_FOUNDRY=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
+///   export AZURE_BEARER_TOKEN_SEARCH=$(az account get-access-token --resource https://search.azure.com --query accessToken -o tsv)
+///   docker run -e AZURE_BEARER_TOKEN_FOUNDRY -e AZURE_BEARER_TOKEN_SEARCH ...
+/// </code>
+/// </summary>
+internal sealed class DevTemporaryTokenCredential : TokenCredential
+{
+    private const string FoundryEnvironmentVariable = "AZURE_BEARER_TOKEN_FOUNDRY";
+    private const string SearchEnvironmentVariable = "AZURE_BEARER_TOKEN_SEARCH";
+
+    public override AccessToken GetToken(TokenRequestContext requestContext, CancellationToken cancellationToken)
+        => Resolve(requestContext.Scopes);
+
+    public override ValueTask<AccessToken> GetTokenAsync(TokenRequestContext requestContext, CancellationToken cancellationToken)
+        => new(Resolve(requestContext.Scopes));
+
+    private static AccessToken Resolve(IReadOnlyList<string> scopes)
+    {
+        string? envVar = null;
+        foreach (var scope in scopes)
+        {
+            if (scope.Contains("search.azure.com", StringComparison.OrdinalIgnoreCase))
+            {
+                envVar = SearchEnvironmentVariable;
+                break;
+            }
+
+            if (scope.Contains("ai.azure.com", StringComparison.OrdinalIgnoreCase))
+            {
+                envVar = FoundryEnvironmentVariable;
+                break;
+            }
+        }
+
+        if (envVar is null)
+        {
+            throw new CredentialUnavailableException(
+                $"DevTemporaryTokenCredential cannot serve scopes [{string.Join(", ", scopes)}]; falling through.");
+        }
+
+        var token = Environment.GetEnvironmentVariable(envVar);
+        if (string.IsNullOrEmpty(token) || string.Equals(token, "DefaultAzureCredential", StringComparison.Ordinal))
+        {
+            throw new CredentialUnavailableException(
+                $"{envVar} environment variable is not set; falling through to next credential.");
+        }
+
+        return new AccessToken(token, DateTimeOffset.UtcNow.AddHours(1));
+    }
+}
@@ -0,0 +1,179 @@
+# Hosted-AzureSearchRag
+
+A hosted agent with **Retrieval Augmented Generation (RAG)** capabilities backed by **Azure AI Search**. The agent grounds its answers in product documentation by running a keyword search against an Azure AI Search index before each model invocation, then citing the source in its response.
+
+This sample is the Azure AI Search counterpart to `Hosted-TextRag`. Where `Hosted-TextRag` uses a mock in-process search function, this sample talks to a real Azure AI Search index that is provisioned out of band (see "Provisioning the search index" below).
+
+## Prerequisites
+
+- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
+- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- An Azure AI Search service ([create one](https://learn.microsoft.com/azure/search/search-create-service-portal))
+- **A pre-provisioned search index** with the schema and content described in the next section
+- Azure CLI logged in (`az login`)
+
+### Required RBAC
+
+Your identity (or the Managed Identity running the container in production) needs:
+
+- **Azure AI User** on the Foundry project scope
+- **Search Index Data Reader** on the Azure AI Search service (the sample only reads from the index)
+
+## Provisioning the search index (one time)
+
+The sample assumes the search index already exists and contains documents the agent can retrieve from. Provision it once via the Azure Portal, the [REST API](https://learn.microsoft.com/azure/search/search-how-to-create-search-index), or the snippet below.
+
+### Index schema
+
+| Field | Type | Attributes |
+|---|---|---|
+| `id` | `Edm.String` | key, filterable |
+| `content` | `Edm.String` | searchable (full-text) |
+| `sourceName` | `Edm.String` | retrievable, filterable |
+| `sourceLink` | `Edm.String` | retrievable |
+
+### Example: provision and seed via Azure CLI + REST
+
+```bash
+SEARCH_ENDPOINT="https://<your-search>.search.windows.net"
+INDEX_NAME="contoso-outdoors"
+TOKEN=$(az account get-access-token --resource https://search.azure.com --query accessToken -o tsv)
+
+# 1. Create the index.
+curl -X PUT "$SEARCH_ENDPOINT/indexes/$INDEX_NAME?api-version=2024-07-01" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{
+    "name": "contoso-outdoors",
+    "fields": [
+      { "name": "id",         "type": "Edm.String", "key": true,  "filterable": true,  "searchable": false, "retrievable": true },
+      { "name": "content",    "type": "Edm.String", "key": false, "filterable": false, "searchable": true,  "retrievable": true, "analyzer": "standard.lucene" },
+      { "name": "sourceName", "type": "Edm.String", "key": false, "filterable": true,  "searchable": false, "retrievable": true },
+      { "name": "sourceLink", "type": "Edm.String", "key": false, "filterable": false, "searchable": false, "retrievable": true }
+    ]
+  }'
+
+# 2. Upload three Contoso Outdoors documents matching the queries below.
+curl -X POST "$SEARCH_ENDPOINT/indexes/$INDEX_NAME/docs/index?api-version=2024-07-01" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{
+    "value": [
+      { "@search.action": "mergeOrUpload", "id": "return-policy",  "sourceName": "Contoso Outdoors Return Policy",     "sourceLink": "https://contoso.com/policies/returns",       "content": "Customers may return any item within 30 days of delivery. Items should be unused and include original packaging. Refunds are issued to the original payment method within 5 business days of inspection. As a thank you, every accepted return ships back with a complimentary Contoso TrailRunner sticker pack, item code TR-CANARY-7821." },
+      { "@search.action": "mergeOrUpload", "id": "shipping-guide", "sourceName": "Contoso Outdoors Shipping Guide",    "sourceLink": "https://contoso.com/help/shipping",          "content": "Standard shipping is free on orders over $50 and typically arrives in 3-5 business days within the continental United States. Expedited options are available at checkout. Use promo code SHIP-CANARY-4493 at checkout for a one-time free overnight upgrade on your first order." },
+      { "@search.action": "mergeOrUpload", "id": "tent-care",      "sourceName": "TrailRunner Tent Care Instructions", "sourceLink": "https://contoso.com/manuals/trailrunner-tent", "content": "Clean the tent fabric with lukewarm water and a non-detergent soap. Allow it to air dry completely before storage and avoid prolonged UV exposure to extend the lifespan of the waterproof coating. Replacement waterproofing kits are stocked under SKU TENT-CANARY-9067." }
+    ]
+  }'
+```
+
+You can also point the sample at any existing index that exposes the four fields above; the sample reads `content`, `sourceName`, and `sourceLink` as projected by the search results.
+
+## Configuration
+
+Copy the template and fill in your endpoints:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env`:
+
+```env
+AZURE_AI_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+AZURE_SEARCH_ENDPOINT=https://<your-search>.search.windows.net
+AZURE_SEARCH_INDEX_NAME=contoso-outdoors
+AZURE_BEARER_TOKEN_FOUNDRY=DefaultAzureCredential
+AZURE_BEARER_TOKEN_SEARCH=DefaultAzureCredential
+ASPNETCORE_URLS=http://+:8088
+ASPNETCORE_ENVIRONMENT=Development
+```
+
+> **Note:** `.env` is gitignored. The `.env.example` template is checked in as a reference.
+
+## Running directly (contributors)
+
+This project uses `ProjectReference` to build against the local Agent Framework source.
+
+```bash
+cd dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag
+AGENT_NAME=hosted-azure-search-rag dotnet run
+```
+
+The agent will start on `http://localhost:8088`. The sample assumes the search index has already been provisioned and seeded (see "Provisioning the search index" above).
+
+### Test it
+
+Using the Azure Developer CLI:
+
+```bash
+azd ai agent invoke --local "What is your return policy?"
+azd ai agent invoke --local "How long does shipping take?"
+azd ai agent invoke --local "How do I clean my tent?"
+```
+
+Or with curl:
+
+```bash
+curl -X POST http://localhost:8088/responses \
+  -H "Content-Type: application/json" \
+  -d '{"input": "What is your return policy?", "model": "hosted-azure-search-rag"}'
+```
+
+## Running with Docker
+
+Since this project uses `ProjectReference`, use `Dockerfile.contributor` which takes a pre-published output.
+
+### 1. Publish for the container runtime (Linux Alpine)
+
+```bash
+dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+```
+
+### 2. Build the Docker image
+
+```bash
+docker build -f Dockerfile.contributor -t hosted-azure-search-rag .
+```
+
+### 3. Run the container
+
+Generate two bearer tokens on your host (one per audience) and pass them to the container. A single Azure AD token has only one `aud` claim, so Foundry and Azure AI Search require separate tokens.
+
+```bash
+# Generate tokens (each expires in ~1 hour)
+export AZURE_BEARER_TOKEN_FOUNDRY=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
+export AZURE_BEARER_TOKEN_SEARCH=$(az account get-access-token --resource https://search.azure.com --query accessToken -o tsv)
+
+# Run with both tokens
+docker run --rm -p 8088:8088 \
+  -e AGENT_NAME=hosted-azure-search-rag \
+  -e AZURE_BEARER_TOKEN_FOUNDRY=$AZURE_BEARER_TOKEN_FOUNDRY \
+  -e AZURE_BEARER_TOKEN_SEARCH=$AZURE_BEARER_TOKEN_SEARCH \
+  --env-file .env \
+  hosted-azure-search-rag
+```
+
+### 4. Test it
+
+Using the Azure Developer CLI:
+
+```bash
+azd ai agent invoke --local "What is your return policy?"
+```
+
+## How RAG works in this sample
+
+The `TextSearchProvider` runs a keyword search against the configured Azure AI Search index **before each model invocation**. When the index is seeded with the three Contoso Outdoors documents from the provisioning section above:
+
+| User query mentions | Search result injected |
+|---|---|
+| "return", "refund" | Contoso Outdoors Return Policy (canary token: `TR-CANARY-7821`) |
+| "shipping", "promo" | Contoso Outdoors Shipping Guide (canary token: `SHIP-CANARY-4493`) |
+| "tent", "fabric" | TrailRunner Tent Care Instructions (canary token: `TENT-CANARY-9067`) |
+
+The model receives the top three search results as additional context and cites the source in its response. Each seeded document includes a unique `*-CANARY-*` token that does not exist in any model training data, so the integration tests can prove an answer was grounded in retrieved content (not fabricated from training) by asking for the canary and asserting it appears in the response.
+
+Replace the seed documents (or point the sample at an existing index with your own content) to ground the agent in your own knowledge base.
+
+## NuGet package users
+
+If you are consuming the Agent Framework as a NuGet package (not building from source), use the standard `Dockerfile` instead of `Dockerfile.contributor`. See the commented section in `HostedAzureSearchRag.csproj` for the `PackageReference` alternative.
@@ -0,0 +1,31 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/AgentManifest.yaml
+name: hosted-azure-search-rag
+displayName: "Hosted Azure AI Search RAG Agent"
+
+description: >
+  A support specialist agent for Contoso Outdoors with RAG capabilities backed by
+  Azure AI Search. Uses TextSearchProvider with a SearchClient adapter to ground
+  answers in product documentation indexed in Azure AI Search before each model
+  invocation.
+
+metadata:
+  tags:
+    - AI Agent Hosting
+    - Azure AI AgentServer
+    - Responses Protocol
+    - RAG
+    - Azure AI Search
+    - Agent Framework
+
+template:
+  name: hosted-azure-search-rag
+  kind: hosted
+  protocols:
+    - protocol: responses
+      version: 1.0.0
+  resources:
+    cpu: "0.25"
+    memory: 0.5Gi
+parameters:
+  properties: []
+resources: []
@@ -0,0 +1,9 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml
+kind: hosted
+name: hosted-azure-search-rag
+protocols:
+  - protocol: responses
+    version: 1.0.0
+resources:
+  cpu: "0.25"
+  memory: 0.5Gi
@@ -0,0 +1,6 @@
+**/bin
+**/obj
+**/.vs
+**/.vscode
+.env
+*.user
@@ -0,0 +1,5 @@
+AZURE_AI_PROJECT_ENDPOINT=<your-azure-ai-project-endpoint>
+ASPNETCORE_URLS=http://+:8088
+ASPNETCORE_ENVIRONMENT=Development
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+AZURE_BEARER_TOKEN=DefaultAzureCredential
@@ -0,0 +1,17 @@
+# Use the official .NET 10.0 ASP.NET runtime as a parent image
+FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
+WORKDIR /app
+
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /src
+COPY . .
+RUN dotnet restore
+RUN dotnet publish -c Release -o /app/publish
+
+# Final stage
+FROM base AS final
+WORKDIR /app
+COPY --from=build /app/publish .
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+ENTRYPOINT ["dotnet", "HostedFiles.dll"]
@@ -0,0 +1,19 @@
+# Dockerfile for contributors building from the agent-framework repository source.
+#
+# This project uses ProjectReference to the local Microsoft.Agents.AI.Foundry source,
+# which means a standard multi-stage Docker build cannot resolve dependencies outside
+# this folder. Instead, pre-publish the app targeting the container runtime and copy
+# the output into the container:
+#
+#   dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+#   docker build -f Dockerfile.contributor -t hosted-files .
+#   docker run --rm -p 8088:8088 -e AGENT_NAME=hosted-files -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN --env-file .env hosted-files
+#
+# For end-users consuming the NuGet package (not ProjectReference), use the standard
+# Dockerfile which performs a full dotnet restore + publish inside the container.
+FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final
+WORKDIR /app
+COPY out/ .
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+ENTRYPOINT ["dotnet", "HostedFiles.dll"]
@@ -0,0 +1,40 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <CentralPackageTransitivePinningEnabled>false</CentralPackageTransitivePinningEnabled>
+    <RootNamespace>HostedFiles</RootNamespace>
+    <AssemblyName>HostedFiles</AssemblyName>
+    <NoWarn>$(NoWarn);</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="DotNetEnv" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <!-- Bake demo resources into the published output so the deployed agent's
+         tools can read them from /app/resources/ inside the container. -->
+    <Content Include="resources\**\*">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </Content>
+  </ItemGroup>
+
+  <!-- For contributors: uses ProjectReference to build against local source -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry.Hosting\Microsoft.Agents.AI.Foundry.Hosting.csproj" />
+  </ItemGroup>
+
+  <!-- For end-users: uncomment the PackageReference below and remove the ProjectReference above
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.Foundry" Version="1.0.0" />
+    <PackageReference Include="Microsoft.Agents.AI.Foundry.Hosting" Version="1.0.0" />
+  </ItemGroup>
+  -->
+
+</Project>
@@ -0,0 +1,223 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// Hosted Files Agent - A hosted agent that exposes two distinct file knowledge sources
+// through scoped, security-hardened tools:
+//
+//   * Bundled files (image-baked) — files copied into the published output via the csproj
+//     <Content Include="resources\**"> rule. Live at /app/resources/ inside the container.
+//     Author-shipped knowledge that ships with every session.
+//
+//   * Session files (per-session $HOME volume) — files uploaded at runtime via the alpha
+//     Azure.AI.Projects.AgentSessionFiles SDK. Live at $HOME inside the per-session
+//     container, which the platform sets to /home/session by default
+//     (container-image-spec.md line 127, "If you use the session files API, $HOME is
+//     also the base path for those operations").
+//
+// Each source is exposed via a separate tool pair, each rooted at its own directory.
+// Tools take a fileName, not a path: Path.GetFileName strips any directory components,
+// then a canonicalize + StartsWith(root) check enforces the boundary. The model cannot
+// be tricked into reading /etc/passwd or any path outside its tool's root, even via
+// indirect prompt injection in an uploaded file.
+//
+// Required environment variables:
+//   AZURE_AI_PROJECT_ENDPOINT         - Azure AI Foundry project endpoint
+//   AZURE_AI_MODEL_DEPLOYMENT_NAME    - Model deployment name (default: gpt-4o)
+//
+// Optional:
+//   AGENT_NAME                        - Agent name (default: hosted-files)
+//   BUNDLED_FILES_DIR                 - Override the bundled-files root
+//                                       (default: <baseDir>/resources, i.e. /app/resources/)
+//   HOME                              - Standard env var; the per-session sandbox volume
+//                                       (default: /home/session in the platform-managed container)
+
+using System.ComponentModel;
+using Azure.AI.Projects;
+using Azure.Core;
+using Azure.Identity;
+using DotNetEnv;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry.Hosting;
+using Microsoft.Extensions.AI;
+
+// Load .env file if present (for local development)
+Env.TraversePath().Load();
+
+// Bypass SampleEnvironment alias (which prompts on missing env vars) for optional values.
+string? GetOptionalEnv(string key) => System.Environment.GetEnvironmentVariable(key);
+
+string endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
+string deploymentName = GetOptionalEnv("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";
+
+// Use a chained credential: try a temporary dev token first (for local Docker debugging),
+// then fall back to DefaultAzureCredential (for local dev via dotnet run / managed identity in production).
+TokenCredential credential = new ChainedTokenCredential(
+    new DevTemporaryTokenCredential(),
+    new DefaultAzureCredential());
+
+// ── File roots (canonicalized once) ──────────────────────────────────────────
+
+// Bundled root: where csproj <Content Include="resources\**"> lands at runtime.
+// In the container that resolves to /app/resources/.
+string bundledRoot = Path.GetFullPath(
+    GetOptionalEnv("BUNDLED_FILES_DIR")
+    ?? Path.Combine(AppContext.BaseDirectory, "resources"));
+
+// Session root: the per-session $HOME volume mounted by the Foundry platform.
+// Files uploaded via AgentSessionFiles.UploadSessionFileAsync(sessionStoragePath: "foo")
+// land at $HOME/foo per container-image-spec.md line 172.
+string sessionRoot = Path.GetFullPath(
+    GetOptionalEnv("HOME")
+    ?? "/home/session");
+
+// ── Tools: bundled files (image-baked, /app/resources/) ──────────────────────
+
+[Description("List the names of files bundled with the agent (built-in knowledge that ships with the image).")]
+string ListBundledFiles() => SafeListNames(bundledRoot);
+
+[Description("Read the full text contents of a bundled file by name. Bundled files are built-in knowledge shipped with the agent image.")]
+string ReadBundledFile(
+    [Description("Name of the bundled file (no directory components). Must be one of the names returned by ListBundledFiles.")] string fileName)
+    => SafeRead(bundledRoot, fileName, scope: "bundled files");
+
+// ── Tools: session files (per-session $HOME) ─────────────────────────────────
+
+[Description("List the names of files uploaded into the current session sandbox by the user (e.g., via AgentSessionFiles.UploadSessionFileAsync).")]
+string ListSessionFiles() => SafeListNames(sessionRoot);
+
+[Description("Read the full text contents of a file uploaded into the current session by name. Session files are user-supplied data that lives only for the lifetime of this session.")]
+string ReadSessionFile(
+    [Description("Name of the session file (no directory components). Must be one of the names returned by ListSessionFiles.")] string fileName)
+    => SafeRead(sessionRoot, fileName, scope: "session files");
+
+// ── Path-safe helpers (defense-in-depth: GetFileName + canonicalize + StartsWith(root)) ──
+
+string SafeListNames(string root)
+{
+    try
+    {
+        if (!Directory.Exists(root))
+        {
+            return string.Empty;
+        }
+
+        return string.Join(
+            Environment.NewLine,
+            Directory.EnumerateFiles(root).Select(Path.GetFileName));
+    }
+    catch (Exception ex)
+    {
+        return $"Error listing files: {ex.Message}";
+    }
+}
+
+string SafeRead(string root, string fileName, string scope)
+{
+    try
+    {
+        // Step 1: strip any directory components the model might have included.
+        string safeName = Path.GetFileName(fileName);
+        if (string.IsNullOrEmpty(safeName))
+        {
+            return $"File '{fileName}' not found in {scope}.";
+        }
+
+        // Step 2: combine with the root and canonicalize.
+        string fullPath = Path.GetFullPath(Path.Combine(root, safeName));
+
+        // Step 3: enforce the prefix boundary so a crafted name still cannot escape.
+        string rootPrefix = root.EndsWith(Path.DirectorySeparatorChar)
+            ? root
+            : root + Path.DirectorySeparatorChar;
+        if (!fullPath.StartsWith(rootPrefix, StringComparison.Ordinal))
+        {
+            return $"File '{fileName}' not found in {scope}.";
+        }
+
+        return File.Exists(fullPath)
+            ? File.ReadAllText(fullPath)
+            : $"File '{fileName}' not found in {scope}.";
+    }
+    catch (Exception ex)
+    {
+        return $"Error reading '{fileName}': {ex.Message}";
+    }
+}
+
+// ── Create and host the agent ────────────────────────────────────────────────
+
+AIAgent agent = new AIProjectClient(new Uri(endpoint), credential)
+    .AsAIAgent(
+        model: deploymentName,
+        instructions: """
+            You are a friendly assistant that answers questions over two file sources:
+
+              - Bundled files: built-in knowledge that ships with the agent image
+                (e.g., reference reports the author packaged with you). Tools:
+                ListBundledFiles, ReadBundledFile.
+
+              - Session files: user-uploaded data for this session only (e.g., a CSV
+                the user wants you to analyse). Tools: ListSessionFiles, ReadSessionFile.
+
+            Pick the tool pair by intent. If a name could match either source, list
+            both first. Always read the file before answering; do not guess. Quote
+            numbers and figures verbatim from the file.
+            """,
+        name: GetOptionalEnv("AGENT_NAME") ?? "hosted-files",
+        description: "Hosted agent that answers questions over bundled (image-baked) and session-uploaded files via two scoped tool pairs.",
+        tools:
+        [
+            AIFunctionFactory.Create(ListBundledFiles),
+            AIFunctionFactory.Create(ReadBundledFile),
+            AIFunctionFactory.Create(ListSessionFiles),
+            AIFunctionFactory.Create(ReadSessionFile),
+        ]);
+
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddFoundryResponses(agent);
+
+var app = builder.Build();
+app.MapFoundryResponses();
+
+if (app.Environment.IsDevelopment())
+{
+    app.MapFoundryResponses("openai/v1");
+}
+
+app.Run();
+
+/// <summary>
+/// A <see cref="TokenCredential"/> for local Docker debugging only.
+/// Reads a pre-fetched bearer token from the <c>AZURE_BEARER_TOKEN</c> environment variable
+/// once at startup. This should NOT be used in production.
+///
+/// Generate a token on your host and pass it to the container:
+///   export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
+///   docker run -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN ...
+/// </summary>
+internal sealed class DevTemporaryTokenCredential : TokenCredential
+{
+    private const string EnvironmentVariable = "AZURE_BEARER_TOKEN";
+    private readonly string? _token;
+
+    public DevTemporaryTokenCredential()
+    {
+        this._token = System.Environment.GetEnvironmentVariable(EnvironmentVariable);
+    }
+
+    public override AccessToken GetToken(TokenRequestContext requestContext, CancellationToken cancellationToken)
+        => this.GetAccessToken();
+
+    public override ValueTask<AccessToken> GetTokenAsync(TokenRequestContext requestContext, CancellationToken cancellationToken)
+        => new(this.GetAccessToken());
+
+    private AccessToken GetAccessToken()
+    {
+        if (string.IsNullOrEmpty(this._token) || this._token == "DefaultAzureCredential")
+        {
+            throw new CredentialUnavailableException($"{EnvironmentVariable} environment variable is not set.");
+        }
+
+        return new AccessToken(this._token, DateTimeOffset.UtcNow.AddHours(1));
+    }
+}
@@ -0,0 +1,128 @@
+# Hosted-Files
+
+A hosted agent that demonstrates **two distinct file knowledge sources** through scoped, security-hardened tools:
+
+- **Bundled files** (image-baked) — files the author packages with the agent at build time. Live at `/app/resources/` inside the container, copied from this project's [`resources/`](./resources/) folder via the csproj `<Content Include="resources\**\*" CopyToOutputDirectory="PreserveNewest" />` rule.
+- **Session files** (per-session `$HOME` volume) — files the user uploads at runtime via the alpha `Azure.AI.Projects.AgentSessionFiles` SDK. Live at `$HOME` inside the per-session container. The Foundry platform sets `HOME=/home/session` by default and roots the session-files API there per [`container-image-spec.md` line 172](https://github.com/microsoft/foundrysdk-specs/blob/main/specs/agents/hosted_agents/container-spec/docs/container-image-spec.md): *"If you use the session files API, `$HOME` is also the base path for those operations; any paths given in those API endpoints will be relative to `$HOME`."*
+
+## Tool surface
+
+Each source is exposed via its own tool pair, rooted at its own directory. The model picks by intent.
+
+| Tool | Source | Root |
+|------|--------|------|
+| `ListBundledFiles` | Bundled (image-baked) | `/app/resources/` |
+| `ReadBundledFile` | Bundled (image-baked) | `/app/resources/` |
+| `ListSessionFiles` | Session-uploaded | `$HOME` (`/home/session`) |
+| `ReadSessionFile` | Session-uploaded | `$HOME` (`/home/session`) |
+
+## Security model — distinct tools, distinct sandboxes
+
+Each tool takes a `fileName` (no directory components allowed) and enforces three layers of defence inside the implementation:
+
+1. **`Path.GetFileName(input)`** strips any directory parts from the model-supplied name. `"../../etc/passwd"` becomes `"passwd"`.
+2. **`Path.GetFullPath(Combine(root, name))`** canonicalises the path.
+3. **`fullPath.StartsWith(root + DirectorySeparatorChar)`** rejects anything that resolves outside the tool's root.
+
+Failures return a controlled `"File '<input>' not found in <scope>."` rather than throwing or exposing the canonical path.
+
+This is why the agent has four narrowly-scoped tools instead of a single `ReadFile(path)`:
+
+- **Smaller per-tool attack surface.** Each tool has one purpose, one root, and no path-typed parameter. Even a buggy implementation can only leak its own directory.
+- **Cross-boundary access is impossible by schema.** A prompt-injection attempt to make the bundled tool read a session path (or vice versa) does not even compile in the tool schema the model sees.
+- **Read-only, non-recursive listing.** No write tools, no glob, no `..`.
+
+## Companion
+
+[`Using-Samples/SessionFilesClient`](../Using-Samples/SessionFilesClient/) — a thin chat REPL (same shape as [`SimpleAgent`](../Using-Samples/SimpleAgent/)) that points at the deployed Hosted-Files endpoint via `FoundryAgent` and lets you ask questions whose answers come from either file source.
+
+## Live proof of the session-files contract
+
+The end-to-end alpha-SDK round trip (client uploads via `AgentSessionFiles.UploadSessionFileAsync` → file arrives at `$HOME/<name>` inside the per-session container → agent's `ReadSessionFile` tool reads it → response quotes the verbatim contents) is exercised live by [`SessionFilesHostedAgentTests.UploadedFile_IsReadByHostedAgentAsync`](../../../../../tests/Foundry.Hosting.IntegrationTests/SessionFilesHostedAgentTests.cs) against the matching `session-files` scenario in the integration test container.
+
+## Prerequisites
+
+- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
+- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- Azure CLI logged in (`az login`)
+
+## Configuration
+
+Copy the template and fill in your project endpoint:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env`:
+
+```env
+AZURE_AI_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>
+ASPNETCORE_URLS=http://+:8088
+ASPNETCORE_ENVIRONMENT=Development
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+```
+
+> `.env` is gitignored. The `.env.example` template is checked in as a reference.
+
+## Running directly (contributors)
+
+```bash
+cd dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files
+AGENT_NAME=hosted-files dotnet run
+```
+
+The agent starts on `http://localhost:8088`.
+
+## Try it from the SessionFilesClient REPL
+
+### Bundled files (works against any deployment, including local)
+
+```bash
+cd ../Using-Samples/SessionFilesClient
+$env:AGENT_ENDPOINT = "http://localhost:8088"
+$env:AGENT_NAME = "hosted-files"
+dotnet run
+
+You> What is the total revenue in the contoso file?
+Agent> The contoso file reports total revenue of "$1,482.6M".
+```
+
+The agent calls `ListBundledFiles`, sees `contoso_q1_2026_report.txt`, calls `ReadBundledFile("contoso_q1_2026_report.txt")` (which resolves under `/app/resources/`), and quotes the figure verbatim.
+
+### Session files (against a deployed agent)
+
+Upload a file to a specific session via `azd ai agent files upload` or via the alpha `AgentSessionFiles` SDK (see the integration test for the SDK call), then ask the agent about it. The agent's `ReadSessionFile` tool reads from `$HOME` and surfaces the content the same way.
+
+## Running with Docker
+
+This project uses `ProjectReference`, so use `Dockerfile.contributor` which takes a pre-published output:
+
+```bash
+dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+docker build -f Dockerfile.contributor -t hosted-files .
+
+export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
+docker run --rm -p 8088:8088 \
+  -e AGENT_NAME=hosted-files \
+  -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN \
+  --env-file .env \
+  hosted-files
+```
+
+The bundled `resources/` folder is part of the published output and ships inside the image.
+
+## NuGet package users
+
+If consuming the Agent Framework as a NuGet package, use the standard `Dockerfile` instead of `Dockerfile.contributor` and switch the `ProjectReference` entries in `HostedFiles.csproj` to `PackageReference` (commented section in the csproj).
+
+## Adding more bundled files
+
+Drop additional text files into [`resources/`](./resources/). The csproj `<Content Include="resources\**\*" CopyToOutputDirectory="PreserveNewest" />` rule picks them up on the next `dotnet build` / `docker build`.
+
+## Overrides
+
+| Env var | Purpose | Default |
+|---------|---------|---------|
+| `BUNDLED_FILES_DIR` | Override the bundled-files root the tools read from. | `<process base dir>/resources` (`/app/resources/` in container) |
+| `HOME` | The per-session sandbox volume root the session-files tools read from. Set by the Foundry platform; can be overridden for local testing. | `/home/session` |
@@ -0,0 +1,30 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/AgentManifest.yaml
+name: hosted-files
+displayName: "Hosted Files Agent"
+
+description: >
+  A hosted agent that answers questions over a small set of files bundled
+  with its container image (under /app/resources/). Two local C# function
+  tools (ListFiles, ReadFile) surface the bundled file contents to the model.
+
+metadata:
+  tags:
+    - AI Agent Hosting
+    - Azure AI AgentServer
+    - Responses Protocol
+    - Bundled Files
+    - Local Tools
+    - Agent Framework
+
+template:
+  name: hosted-files
+  kind: hosted
+  protocols:
+    - protocol: responses
+      version: 1.0.0
+  resources:
+    cpu: "0.25"
+    memory: 0.5Gi
+parameters:
+  properties: []
+resources: []
@@ -0,0 +1,9 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml
+kind: hosted
+name: hosted-files
+protocols:
+  - protocol: responses
+    version: 1.0.0
+resources:
+  cpu: "0.25"
+  memory: 0.5Gi
@@ -0,0 +1,121 @@
+Contoso Corporation
+Quarterly Report — Q1 2026 (Three months ended March 31, 2026)
+
+DISCLAIMER
+This document contains fictional data for sample/demo purposes only.
+Contoso is a fictional company; all figures below are fabricated.
+
+------------------------------------------------------------
+1. EXECUTIVE SUMMARY
+------------------------------------------------------------
+Contoso delivered a solid first quarter, with total revenue of
+$1,482.6M, up 11.4% year-over-year. Growth was led by the Cloud
+Services segment (+22.7% YoY) and continued double-digit expansion
+in International markets. Operating margin expanded 140 basis points
+to 23.8% on disciplined cost management and improved gross margin.
+
+Key highlights:
+  - Revenue: $1,482.6M (YoY +11.4%)
+  - Gross profit: $912.0M (gross margin 61.5%)
+  - Operating income: $352.9M (operating margin 23.8%)
+  - Net income: $268.4M (net margin 18.1%)
+  - Diluted EPS: $1.27 (vs. $1.04 prior year)
+  - Free cash flow: $311.5M
+  - Cash & equivalents: $2,140.8M
+
+------------------------------------------------------------
+2. INCOME STATEMENT (USD millions, unaudited)
+------------------------------------------------------------
+                                     Q1 2026     Q1 2025     YoY %
+Revenue                              1,482.6     1,330.7     +11.4%
+Cost of revenue                        570.6       538.9      +5.9%
+Gross profit                           912.0       791.8     +15.2%
+  Gross margin                          61.5%       59.5%    +200 bps
+Operating expenses
+  Research & development               241.4       220.5      +9.5%
+  Sales & marketing                    218.7       205.1      +6.6%
+  General & administrative              99.0        88.6     +11.7%
+Total operating expenses               559.1       514.2      +8.7%
+Operating income                       352.9       277.6     +27.1%
+  Operating margin                      23.8%       20.9%    +290 bps
+Other income / (expense), net            8.4         5.1
+Income before taxes                    361.3       282.7
+Provision for income taxes              92.9        72.6
+Net income                             268.4       210.1     +27.7%
+Diluted EPS (USD)                       1.27        1.04     +22.1%
+
+------------------------------------------------------------
+3. REVENUE BY SEGMENT (USD millions)
+------------------------------------------------------------
+Segment                              Q1 2026     Q1 2025     YoY %
+Cloud Services                         612.4       499.1     +22.7%
+Productivity Software                  448.9       422.6      +6.2%
+Devices & Hardware                     267.0       260.4      +2.5%
+Professional Services                  154.3       148.6      +3.8%
+Total revenue                        1,482.6     1,330.7     +11.4%
+
+------------------------------------------------------------
+4. REVENUE BY GEOGRAPHY (USD millions)
+------------------------------------------------------------
+Region                               Q1 2026     Q1 2025     YoY %
+North America                          812.1       756.0      +7.4%
+EMEA                                   388.5       340.2     +14.2%
+Asia-Pacific                           221.7       183.4     +20.9%
+Latin America                           60.3        51.1     +18.0%
+Total revenue                        1,482.6     1,330.7     +11.4%
+
+------------------------------------------------------------
+5. SELECTED BALANCE SHEET ITEMS (USD millions)
+------------------------------------------------------------
+                                     Mar 31,     Dec 31,
+                                       2026        2025
+Cash & equivalents                   2,140.8     1,902.3
+Short-term investments                 845.6       820.4
+Accounts receivable, net             1,012.7       988.5
+Total current assets                 4,510.2     4,190.6
+Goodwill & intangibles               2,330.1     2,338.9
+Total assets                         9,884.5     9,512.0
+Total current liabilities            2,118.4     2,054.7
+Long-term debt                       1,750.0     1,750.0
+Total liabilities                    4,402.6     4,310.5
+Total stockholders' equity           5,481.9     5,201.5
+
+------------------------------------------------------------
+6. CASH FLOW HIGHLIGHTS (USD millions)
+------------------------------------------------------------
+                                     Q1 2026     Q1 2025
+Net cash from operating activities     382.0       298.7
+Capital expenditures                   (70.5)      (62.1)
+Free cash flow                         311.5       236.6
+Share repurchases                     (120.0)      (90.0)
+Dividends paid                         (54.2)      (48.6)
+
+------------------------------------------------------------
+7. KEY OPERATING METRICS
+------------------------------------------------------------
+Cloud paid seats (millions)             48.6        39.7     +22.4%
+Cloud net revenue retention            118%        114%
+Active enterprise customers          18,420      16,905      +9.0%
+Headcount (end of period)            22,140      20,610      +7.4%
+
+------------------------------------------------------------
+8. OUTLOOK — Q2 2026 GUIDANCE
+------------------------------------------------------------
+Revenue:           $1,520M – $1,560M (YoY +10% to +13%)
+Operating margin:  23.5% – 24.5%
+Diluted EPS:       $1.30 – $1.36
+Capital expenditures: ~$80M
+
+Management remains confident in the full-year plan and reiterates
+fiscal-year 2026 revenue growth of 10–12% and operating-margin
+expansion of 100–150 basis points versus FY 2025.
+
+------------------------------------------------------------
+9. NOTES
+------------------------------------------------------------
+- All figures are unaudited and rounded to one decimal place.
+- Year-over-year comparisons are versus the same period in 2025.
+- "Free cash flow" is defined as net cash from operating activities
+  less capital expenditures, and is a non-GAAP measure.
+- This sample report is intended solely for demonstration of an
+  agent-driven document analysis pipeline.
@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk.Web">
+<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFrameworks>net10.0</TargetFrameworks>
@@ -11,7 +11,7 @@
  </PropertyGroup>

  <ItemGroup>
-    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.AI.Projects" />
    <PackageReference Include="Azure.Identity" />
    <PackageReference Include="DotNetEnv" />
  </ItemGroup>
@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk.Web">
+<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFrameworks>net10.0</TargetFrameworks>
@@ -11,7 +11,7 @@
  </PropertyGroup>

  <ItemGroup>
-    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.AI.Projects" />
    <PackageReference Include="Azure.Identity" />
    <PackageReference Include="ModelContextProtocol" VersionOverride="1.2.0" />
    <PackageReference Include="DotNetEnv" />
@@ -0,0 +1,7 @@
+.env
+bin/
+obj/
+out/
+.vs/
+.vscode/
+*.user
@@ -0,0 +1,12 @@
+AZURE_AI_PROJECT_ENDPOINT=<your-azure-ai-project-endpoint>
+ASPNETCORE_URLS=http://+:8088
+ASPNETCORE_ENVIRONMENT=Development
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+AZURE_BEARER_TOKEN=DefaultAzureCredential
+
+# Capture prompt / completion / tool argument content on GenAI spans.
+OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
+
+# Uncomment and set to send local-run telemetry to Application Insights.
+# When the agent runs inside Foundry this value is injected automatically.
+#APPLICATIONINSIGHTS_CONNECTION_STRING=<your-app-insights-connection-string>
@@ -0,0 +1,17 @@
+# Use the official .NET 10.0 ASP.NET runtime as a parent image
+FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
+WORKDIR /app
+
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /src
+COPY . .
+RUN dotnet restore
+RUN dotnet publish -c Release -o /app/publish
+
+# Final stage
+FROM base AS final
+WORKDIR /app
+COPY --from=build /app/publish .
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+ENTRYPOINT ["dotnet", "HostedObservability.dll"]
@@ -0,0 +1,19 @@
+# Dockerfile for contributors building from the agent-framework repository source.
+#
+# This project uses ProjectReference to the local Microsoft.Agents.AI.Foundry source,
+# which means a standard multi-stage Docker build cannot resolve dependencies outside
+# this folder. Instead, pre-publish the app targeting the container runtime and copy
+# the output into the container:
+#
+#   dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+#   docker build -f Dockerfile.contributor -t hosted-observability .
+#   docker run --rm -p 8088:8088 -e AGENT_NAME=hosted-observability -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN --env-file .env hosted-observability
+#
+# For end-users consuming the NuGet package (not ProjectReference), use the standard
+# Dockerfile which performs a full dotnet restore + publish inside the container.
+FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final
+WORKDIR /app
+COPY out/ .
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+ENTRYPOINT ["dotnet", "HostedObservability.dll"]
@@ -0,0 +1,32 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <CentralPackageTransitivePinningEnabled>false</CentralPackageTransitivePinningEnabled>
+    <RootNamespace>HostedObservability</RootNamespace>
+    <AssemblyName>HostedObservability</AssemblyName>
+    <NoWarn>$(NoWarn);</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Projects" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="DotNetEnv" />
+  </ItemGroup>
+
+  <!-- For contributors: uses ProjectReference to build against local source -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry.Hosting\Microsoft.Agents.AI.Foundry.Hosting.csproj" />
+  </ItemGroup>
+
+  <!-- For end-users: uncomment the PackageReference below and remove the ProjectReference above
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.Foundry" Version="1.0.0" />
+    <PackageReference Include="Microsoft.Agents.AI.Foundry.Hosting" Version="1.0.0" />
+  </ItemGroup>
+  -->
+
+</Project>
@@ -0,0 +1,108 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// Hosted Observability Agent - demonstrates that the Foundry hosting pipeline
+// emits OpenTelemetry traces, metrics and logs with no extra wiring required.
+// Two small tools are included so a request produces a span tree covering
+// agent invocation, the chat call, and tool execution.
+
+using System.ComponentModel;
+using Azure.AI.Projects;
+using Azure.Core;
+using Azure.Identity;
+using DotNetEnv;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry.Hosting;
+using Microsoft.Extensions.AI;
+
+// Load .env file if present (for local development)
+Env.TraversePath().Load();
+
+string endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";
+
+// Use a chained credential: try a temporary dev token first (for local Docker debugging),
+// then fall back to DefaultAzureCredential (for local dev via dotnet run / managed identity in production).
+TokenCredential credential = new ChainedTokenCredential(
+    new DevTemporaryTokenCredential(),
+    new DefaultAzureCredential());
+
+// ── Tools ────────────────────────────────────────────────────────────────────
+
+string[] locations = ["New York", "London", "Paris", "Tokyo"];
+string[] conditions = ["sunny", "cloudy", "rainy", "stormy"];
+
+[Description("Get the current location of the user.")]
+string GetCurrentLocation() => locations[Random.Shared.Next(locations.Length)];
+
+[Description("Get the weather for a given location.")]
+string GetWeather(
+    [Description("The location to get the weather for.")] string location)
+    => $"The weather in {location} is {conditions[Random.Shared.Next(conditions.Length)]} with a high of {Random.Shared.Next(10, 31)}°C.";
+
+// ── Create and host the agent ────────────────────────────────────────────────
+//
+// AddFoundryResponses automatically wraps `agent` with OpenTelemetryAgent
+// (see Microsoft.Agents.AI.Foundry.Hosting.ServiceCollectionExtensions.ApplyOpenTelemetry)
+// and the OTLP exporter is registered by Azure.AI.AgentServer.Core's
+// AddAgentHostTelemetry(). No additional observability wiring is required.
+
+AIAgent agent = new AIProjectClient(new Uri(endpoint), credential)
+    .AsAIAgent(
+        model: deploymentName,
+        instructions: "You are a friendly assistant. Keep your answers brief.",
+        name: Environment.GetEnvironmentVariable("AGENT_NAME") ?? "hosted-observability",
+        description: "A hosted agent that demonstrates Foundry observability.",
+        tools: [
+            AIFunctionFactory.Create(GetCurrentLocation),
+            AIFunctionFactory.Create(GetWeather),
+        ]);
+
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddFoundryResponses(agent);
+
+var app = builder.Build();
+app.MapFoundryResponses();
+
+if (app.Environment.IsDevelopment())
+{
+    app.MapFoundryResponses("openai/v1");
+}
+
+app.Run();
+
+/// <summary>
+/// A <see cref="TokenCredential"/> for local Docker debugging only.
+/// Reads a pre-fetched bearer token from the <c>AZURE_BEARER_TOKEN</c> environment variable
+/// once at startup. This should NOT be used in production.
+///
+/// Generate a token on your host and pass it to the container:
+///   export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
+///   docker run -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN ...
+/// </summary>
+internal sealed class DevTemporaryTokenCredential : TokenCredential
+{
+    private const string EnvironmentVariable = "AZURE_BEARER_TOKEN";
+    private readonly string? _token;
+
+    public DevTemporaryTokenCredential()
+    {
+        this._token = Environment.GetEnvironmentVariable(EnvironmentVariable);
+    }
+
+    public override AccessToken GetToken(TokenRequestContext requestContext, CancellationToken cancellationToken)
+        => this.GetAccessToken();
+
+    public override ValueTask<AccessToken> GetTokenAsync(TokenRequestContext requestContext, CancellationToken cancellationToken)
+        => new(this.GetAccessToken());
+
+    private AccessToken GetAccessToken()
+    {
+        if (string.IsNullOrEmpty(this._token) || this._token == "DefaultAzureCredential")
+        {
+            throw new CredentialUnavailableException($"{EnvironmentVariable} environment variable is not set.");
+        }
+
+        return new AccessToken(this._token, DateTimeOffset.UtcNow.AddHours(1));
+    }
+}
@@ -0,0 +1,109 @@
+# Hosted-Observability
+
+A hosted [Agent Framework](https://github.com/microsoft/agent-framework) agent that demonstrates how the Foundry hosting pipeline emits OpenTelemetry traces, metrics and logs with no extra wiring.
+
+The agent has two small tools, `GetCurrentLocation` and `GetWeather`, so an end-to-end run produces a span tree covering agent invocation, the underlying chat call, and tool execution.
+
+## How it works
+
+### Instrumentation is on by default
+
+Unlike the Python SDK, the .NET hosting library is instrumented by default. `AddFoundryResponses(agent)` automatically wraps the agent with `OpenTelemetryAgent` (see `Microsoft.Agents.AI.Foundry.Hosting.ServiceCollectionExtensions.ApplyOpenTelemetry`) and the OTLP exporter pipeline is registered by `Azure.AI.AgentServer.Core`'s `AddAgentHostTelemetry()`. There is no `ENABLE_INSTRUMENTATION` flag to set.
+
+### Sensitive content
+
+Prompt, completion and tool argument content are omitted from spans by default. Set the OpenTelemetry standard environment variable to capture them:
+
+```env
+OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
+```
+
+This is the .NET equivalent of the Python sample's `ENABLE_SENSITIVE_DATA`. It is read by `OpenTelemetryAgent.EnableSensitiveData`.
+
+### Where the telemetry goes
+
+Foundry injects `APPLICATIONINSIGHTS_CONNECTION_STRING` when the agent runs in the hosted environment, so traces, metrics and logs flow to Application Insights with no code change. To send telemetry from a local run, set the connection string yourself in `.env`.
+
+## Prerequisites
+
+- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
+- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- Azure CLI logged in (`az login`)
+
+## Configuration
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` and set your Azure AI Foundry project endpoint:
+
+```env
+AZURE_AI_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>
+ASPNETCORE_URLS=http://+:8088
+ASPNETCORE_ENVIRONMENT=Development
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
+```
+
+> **Note:** `.env` is gitignored. The `.env.example` template is checked in as a reference.
+
+## Running directly (contributors)
+
+```bash
+cd dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Observability
+AGENT_NAME=hosted-observability dotnet run
+```
+
+The agent starts on `http://localhost:8088`.
+
+### Test it
+
+```bash
+azd ai agent invoke --local "What is the current weather where I am?"
+```
+
+Or with curl:
+
+```bash
+curl -X POST http://localhost:8088/responses \
+  -H "Content-Type: application/json" \
+  -d '{"input": "What is the current weather where I am?", "model": "hosted-observability"}'
+```
+
+## Expected span tree
+
+A single request produces approximately the following spans:
+
+| Span | Source |
+|------|--------|
+| `invoke_agent` | Outer span emitted by the Azure AI AgentServer hosting SDK |
+| `agent_invoke <name>` | Emitted by `OpenTelemetryAgent` for each agent invocation |
+| `chat <model>` | Emitted by the underlying `IChatClient` for each model call |
+| `execute_tool <tool>` | Emitted for each invocation of `GetCurrentLocation` / `GetWeather` |
+
+See the [OpenTelemetry GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) for the attributes captured on each span.
+
+## Running with Docker
+
+This project uses `ProjectReference` to the local Agent Framework source, so use `Dockerfile.contributor` with a pre-published output:
+
+```bash
+dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+docker build -f Dockerfile.contributor -t hosted-observability .
+
+export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
+docker run --rm -p 8088:8088 \
+  -e AGENT_NAME=hosted-observability \
+  -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN \
+  --env-file .env \
+  hosted-observability
+```
+
+## Deploying to Foundry and viewing traces
+
+Once deployed, telemetry flows to the Application Insights instance attached to your Foundry project. In the Foundry UI, the **Traces** tab next to **Playground** lists conversations and lets you drill into the span tree for any request.
+
+## NuGet package users
+
+If consuming the Agent Framework as a NuGet package, use the standard `Dockerfile` instead of `Dockerfile.contributor`. See the commented section in `HostedObservability.csproj` for the `PackageReference` alternative.
@@ -0,0 +1,34 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/AgentManifest.yaml
+name: hosted-observability
+displayName: "Hosted Observability Agent"
+
+description: >
+  A hosted Agent Framework agent that demonstrates how the Foundry hosting
+  pipeline emits OpenTelemetry traces, metrics and logs to Application Insights
+  with no extra wiring required.
+
+metadata:
+  tags:
+    - AI Agent Hosting
+    - Azure AI AgentServer
+    - Responses Protocol
+    - Observability
+    - OpenTelemetry
+    - Agent Framework
+
+template:
+  name: hosted-observability
+  kind: hosted
+  protocols:
+    - protocol: responses
+      version: 1.0.0
+  resources:
+    cpu: "0.25"
+    memory: 0.5Gi
+  environment_variables:
+    # Capture prompt / completion / tool argument content on GenAI spans.
+    - name: OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT
+      value: "true"
+parameters:
+  properties: []
+resources: []
@@ -0,0 +1,14 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml
+kind: hosted
+name: hosted-observability
+protocols:
+  - protocol: responses
+    version: 1.0.0
+resources:
+  cpu: "0.25"
+  memory: 0.5Gi
+environment_variables:
+  # Capture prompt / completion / tool argument content on GenAI spans.
+  # See https://opentelemetry.io/docs/specs/semconv/gen-ai/ for the standard env var.
+  - name: OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT
+    value: "true"
@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk.Web">
+<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFrameworks>net10.0</TargetFrameworks>
@@ -11,7 +11,7 @@
  </PropertyGroup>

  <ItemGroup>
-    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.AI.Projects" />
    <PackageReference Include="Azure.Identity" />
    <PackageReference Include="DotNetEnv" />
  </ItemGroup>
@@ -11,7 +11,7 @@
  </PropertyGroup>

  <ItemGroup>
-    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.AI.Projects" />
    <PackageReference Include="Azure.Identity" />
    <PackageReference Include="DotNetEnv" />
  </ItemGroup>
@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk.Web">
+<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFrameworks>net10.0</TargetFrameworks>
@@ -11,7 +11,7 @@
  </PropertyGroup>

  <ItemGroup>
-    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.AI.Projects" />
    <PackageReference Include="Azure.Identity" />
    <PackageReference Include="DotNetEnv" />
  </ItemGroup>
@@ -0,0 +1,116 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ClientModel.Primitives;
+using Azure.AI.Extensions.OpenAI;
+using Azure.AI.Projects;
+using Azure.Identity;
+using DotNetEnv;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry;
+
+// Load .env file if present (for local development)
+Env.TraversePath().Load();
+
+Uri agentEndpoint = new(Environment.GetEnvironmentVariable("AGENT_ENDPOINT")
+    ?? "http://localhost:8088");
+
+var agentName = Environment.GetEnvironmentVariable("AGENT_NAME")
+    ?? throw new InvalidOperationException("AGENT_NAME is not set.");
+
+// ── Create an agent-framework agent backed by the remote Hosted-Files agent ──
+
+var options = new AIProjectClientOptions();
+
+if (agentEndpoint.Scheme == "http")
+{
+    // For local HTTP dev: tell AIProjectClient the endpoint is HTTPS (to satisfy
+    // BearerTokenPolicy's TLS check), then swap the scheme back to HTTP right
+    // before the request hits the wire.
+
+    agentEndpoint = new UriBuilder(agentEndpoint) { Scheme = "https" }.Uri;
+    options.AddPolicy(new HttpSchemeRewritePolicy(), PipelinePosition.BeforeTransport);
+}
+
+var aiProjectClient = new AIProjectClient(agentEndpoint, new AzureCliCredential(), options);
+FoundryAgent agent = aiProjectClient.AsAIAgent(new AgentReference(agentName));
+
+AgentSession session = await agent.CreateSessionAsync();
+
+// ── REPL ──────────────────────────────────────────────────────────────────────
+
+Console.ForegroundColor = ConsoleColor.Cyan;
+Console.WriteLine($"""
+    ══════════════════════════════════════════════════════════
+    Session Files Client                                    
+    Connected to: {agentEndpoint}
+    Try: "Give me the total revenue in the contoso file."
+    Type a message or 'quit' to exit                        
+    ══════════════════════════════════════════════════════════
+    """);
+Console.ResetColor();
+Console.WriteLine();
+
+while (true)
+{
+    Console.ForegroundColor = ConsoleColor.Green;
+    Console.Write("You> ");
+    Console.ResetColor();
+
+    string? input = Console.ReadLine();
+
+    if (string.IsNullOrWhiteSpace(input)) { continue; }
+    if (input.Equals("quit", StringComparison.OrdinalIgnoreCase)) { break; }
+
+    try
+    {
+        Console.ForegroundColor = ConsoleColor.Yellow;
+        Console.Write("Agent> ");
+        Console.ResetColor();
+
+        await foreach (var update in agent.RunStreamingAsync(input, session))
+        {
+            Console.Write(update);
+        }
+
+        Console.WriteLine();
+    }
+    catch (Exception ex)
+    {
+        Console.ForegroundColor = ConsoleColor.Red;
+        Console.WriteLine($"Error: {ex.Message}");
+        Console.ResetColor();
+    }
+
+    Console.WriteLine();
+}
+
+Console.WriteLine("Goodbye!");
+
+/// <summary>
+/// For Local Development Only
+/// Rewrites HTTPS URIs to HTTP right before transport, allowing AIProjectClient
+/// to target a local HTTP dev server while satisfying BearerTokenPolicy's TLS check.
+/// </summary>
+internal sealed class HttpSchemeRewritePolicy : PipelinePolicy
+{
+    public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+    {
+        RewriteScheme(message);
+        ProcessNext(message, pipeline, currentIndex);
+    }
+
+    public override async ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+    {
+        RewriteScheme(message);
+        await ProcessNextAsync(message, pipeline, currentIndex).ConfigureAwait(false);
+    }
+
+    private static void RewriteScheme(PipelineMessage message)
+    {
+        var uri = message.Request.Uri!;
+        if (uri.Scheme == Uri.UriSchemeHttps)
+        {
+            message.Request.Uri = new UriBuilder(uri) { Scheme = "http" }.Uri;
+        }
+    }
+}
@@ -0,0 +1,50 @@
+# SessionFilesClient
+
+A thin chat REPL that connects to a deployed [`Hosted-Files`](../../Hosted-Files/) agent via `FoundryAgent` and lets you ask questions whose answers come from the files bundled with that agent. Same shape as [`SimpleAgent`](../SimpleAgent/) — point it at an `AGENT_ENDPOINT`, build a `FoundryAgent`, run.
+
+The agent's container-side `ListFiles` and `ReadFile` tools surface the bundled file contents to the model. The client knows nothing about files; that is entirely the agent's concern.
+
+## Prerequisites
+
+- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
+- A running [`Hosted-Files`](../../Hosted-Files/) agent (locally via `dotnet run` or deployed to Foundry)
+- Azure CLI logged in (`az login`)
+
+## Configuration
+
+```env
+AGENT_ENDPOINT=http://localhost:8088
+AGENT_NAME=hosted-files
+```
+
+`AGENT_ENDPOINT` defaults to `http://localhost:8088`. Override with the deployed agent endpoint when chatting against Foundry.
+
+## Run
+
+```bash
+cd dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SessionFilesClient
+$env:AGENT_ENDPOINT = "http://localhost:8088"
+$env:AGENT_NAME = "hosted-files"
+dotnet run
+```
+
+## End-to-end demo
+
+With the [`Hosted-Files`](../../Hosted-Files/) agent running:
+
+```text
+══════════════════════════════════════════════════════════
+Session Files Client
+Connected to: http://localhost:8088/
+Try: "Give me the total revenue in the contoso file."
+Type a message or 'quit' to exit
+══════════════════════════════════════════════════════════
+
+You> Give me the total revenue in the contoso file.
+Agent> The contoso file reports total revenue of "$1,482.6M".
+
+You> quit
+Goodbye!
+```
+
+The agent looked at its bundled files via `ListFiles`, picked `contoso_q1_2026_report.txt`, called `ReadFile`, and quoted the figure verbatim. The client only sent a chat prompt.
@@ -0,0 +1,24 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <CentralPackageTransitivePinningEnabled>false</CentralPackageTransitivePinningEnabled>
+    <RootNamespace>SessionFilesClient</RootNamespace>
+    <AssemblyName>session-files-client</AssemblyName>
+    <NoWarn>$(NoWarn);NU1605;OPENAI001</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Projects" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="DotNetEnv" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -2,6 +2,7 @@

 using System;
 using System.Collections.Generic;
+using System.Linq;
 using System.Text.Json;
 using Microsoft.Extensions.AI;

@@ -55,6 +56,32 @@ internal static class AGUIChatMessageExtensions
                    break;
                }

+                case AGUIReasoningMessage reasoningMessage:
+                {
+                    var contents = new List<AIContent>();
+
+                    if (!string.IsNullOrEmpty(reasoningMessage.Content))
+                    {
+                        contents.Add(new TextReasoningContent(reasoningMessage.Content)
+                        {
+                            ProtectedData = reasoningMessage.EncryptedValue
+                        });
+                    }
+                    else if (!string.IsNullOrEmpty(reasoningMessage.EncryptedValue))
+                    {
+                        contents.Add(new TextReasoningContent("")
+                        {
+                            ProtectedData = reasoningMessage.EncryptedValue
+                        });
+                    }
+
+                    yield return new ChatMessage(role, contents)
+                    {
+                        MessageId = message.Id
+                    };
+                    break;
+                }
+
                case AGUIAssistantMessage assistantMessage when assistantMessage.ToolCalls is { Length: > 0 }:
                {
                    var contents = new List<AIContent>();
@@ -125,6 +152,12 @@ internal static class AGUIChatMessageExtensions
            }
            else if (message.Role == ChatRole.Assistant)
            {
+                var reasoningMessage = MapReasoningMessage(message);
+                if (reasoningMessage != null)
+                {
+                    yield return reasoningMessage;
+                }
+
                var assistantMessage = MapAssistantMessage(jsonSerializerOptions, message);
                if (assistantMessage != null)
                {
@@ -144,6 +177,32 @@ internal static class AGUIChatMessageExtensions
        }
    }

+    private static AGUIReasoningMessage? MapReasoningMessage(ChatMessage message)
+    {
+        var reasoning = message.Contents.OfType<TextReasoningContent>().FirstOrDefault();
+        if (reasoning is null)
+        {
+            return null;
+        }
+
+        var text = string.Join(
+            string.Empty,
+            message.Contents.OfType<TextReasoningContent>()
+                .Where(r => !string.IsNullOrEmpty(r.Text))
+                .Select(r => r.Text));
+
+        var protectedData = message.Contents.OfType<TextReasoningContent>()
+            .Select(r => r.ProtectedData)
+            .LastOrDefault(p => !string.IsNullOrEmpty(p));
+
+        return new AGUIReasoningMessage
+        {
+            Id = message.MessageId,
+            Content = text,
+            EncryptedValue = protectedData,
+        };
+    }
+
    private static AGUIAssistantMessage? MapAssistantMessage(JsonSerializerOptions jsonSerializerOptions, ChatMessage message)
    {
        List<AGUIToolCall>? toolCalls = null;
@@ -212,5 +271,6 @@ internal static class AGUIChatMessageExtensions
        string.Equals(role, AGUIRoles.Assistant, StringComparison.OrdinalIgnoreCase) ? ChatRole.Assistant :
        string.Equals(role, AGUIRoles.Developer, StringComparison.OrdinalIgnoreCase) ? s_developerChatRole :
        string.Equals(role, AGUIRoles.Tool, StringComparison.OrdinalIgnoreCase) ? ChatRole.Tool :
+        string.Equals(role, AGUIRoles.Reasoning, StringComparison.OrdinalIgnoreCase) ? ChatRole.Assistant :
        throw new InvalidOperationException($"Unknown chat role: {role}");
 }
@@ -31,4 +31,18 @@ internal static class AGUIEventTypes
    public const string StateSnapshot = "STATE_SNAPSHOT";

    public const string StateDelta = "STATE_DELTA";
+
+    public const string ReasoningStart = "REASONING_START";
+
+    public const string ReasoningMessageStart = "REASONING_MESSAGE_START";
+
+    public const string ReasoningMessageContent = "REASONING_MESSAGE_CONTENT";
+
+    public const string ReasoningMessageEnd = "REASONING_MESSAGE_END";
+
+    public const string ReasoningEnd = "REASONING_END";
+
+    public const string ReasoningMessageChunk = "REASONING_MESSAGE_CHUNK";
+
+    public const string ReasoningEncryptedValue = "REASONING_ENCRYPTED_VALUE";
 }
@@ -28,6 +28,7 @@ namespace Microsoft.Agents.AI.AGUI;
 [JsonSerializable(typeof(AGUIUserMessage))]
 [JsonSerializable(typeof(AGUIAssistantMessage))]
 [JsonSerializable(typeof(AGUIToolMessage))]
+[JsonSerializable(typeof(AGUIReasoningMessage))]
 [JsonSerializable(typeof(AGUITool))]
 [JsonSerializable(typeof(AGUIToolCall))]
 [JsonSerializable(typeof(AGUIToolCall[]))]
@@ -46,6 +47,13 @@ namespace Microsoft.Agents.AI.AGUI;
 [JsonSerializable(typeof(ToolCallResultEvent))]
 [JsonSerializable(typeof(StateSnapshotEvent))]
 [JsonSerializable(typeof(StateDeltaEvent))]
+[JsonSerializable(typeof(ReasoningStartEvent))]
+[JsonSerializable(typeof(ReasoningMessageStartEvent))]
+[JsonSerializable(typeof(ReasoningMessageContentEvent))]
+[JsonSerializable(typeof(ReasoningMessageEndEvent))]
+[JsonSerializable(typeof(ReasoningEndEvent))]
+[JsonSerializable(typeof(ReasoningMessageChunkEvent))]
+[JsonSerializable(typeof(ReasoningEncryptedValueEvent))]
 [JsonSerializable(typeof(IDictionary<string, object?>))]
 [JsonSerializable(typeof(Dictionary<string, object?>))]
 [JsonSerializable(typeof(IDictionary<string, System.Text.Json.JsonElement?>))]
@@ -41,6 +41,7 @@ internal sealed class AGUIMessageJsonConverter : JsonConverter<AGUIMessage>
            AGUIRoles.User => jsonElement.Deserialize(options.GetTypeInfo(typeof(AGUIUserMessage))) as AGUIUserMessage,
            AGUIRoles.Assistant => jsonElement.Deserialize(options.GetTypeInfo(typeof(AGUIAssistantMessage))) as AGUIAssistantMessage,
            AGUIRoles.Tool => jsonElement.Deserialize(options.GetTypeInfo(typeof(AGUIToolMessage))) as AGUIToolMessage,
+            AGUIRoles.Reasoning => jsonElement.Deserialize(options.GetTypeInfo(typeof(AGUIReasoningMessage))) as AGUIReasoningMessage,
            _ => throw new JsonException($"Unknown AGUIMessage role discriminator: '{discriminator}'")
        };

@@ -75,6 +76,9 @@ internal sealed class AGUIMessageJsonConverter : JsonConverter<AGUIMessage>
            case AGUIToolMessage tool:
                JsonSerializer.Serialize(writer, tool, options.GetTypeInfo(typeof(AGUIToolMessage)));
                break;
+            case AGUIReasoningMessage reasoning:
+                JsonSerializer.Serialize(writer, reasoning, options.GetTypeInfo(typeof(AGUIReasoningMessage)));
+                break;
            default:
                throw new JsonException($"Unknown AGUIMessage type: {value.GetType().Name}");
        }
@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+#if ASPNETCORE
+namespace Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.Shared;
+#else
+namespace Microsoft.Agents.AI.AGUI.Shared;
+#endif
+
+internal sealed class AGUIReasoningMessage : AGUIMessage
+{
+    public AGUIReasoningMessage()
+    {
+        this.Role = AGUIRoles.Reasoning;
+    }
+
+    [JsonPropertyName("encryptedValue")]
+    public string? EncryptedValue { get; set; }
+}
@@ -17,4 +17,6 @@ internal static class AGUIRoles
    public const string Developer = "developer";

    public const string Tool = "tool";
+
+    public const string Reasoning = "reasoning";
 }
@@ -47,6 +47,13 @@ internal sealed class BaseEventJsonConverter : JsonConverter<BaseEvent>
            AGUIEventTypes.ToolCallEnd => jsonElement.Deserialize(options.GetTypeInfo(typeof(ToolCallEndEvent))) as ToolCallEndEvent,
            AGUIEventTypes.ToolCallResult => jsonElement.Deserialize(options.GetTypeInfo(typeof(ToolCallResultEvent))) as ToolCallResultEvent,
            AGUIEventTypes.StateSnapshot => jsonElement.Deserialize(options.GetTypeInfo(typeof(StateSnapshotEvent))) as StateSnapshotEvent,
+            AGUIEventTypes.ReasoningStart => jsonElement.Deserialize(options.GetTypeInfo(typeof(ReasoningStartEvent))) as ReasoningStartEvent,
+            AGUIEventTypes.ReasoningMessageStart => jsonElement.Deserialize(options.GetTypeInfo(typeof(ReasoningMessageStartEvent))) as ReasoningMessageStartEvent,
+            AGUIEventTypes.ReasoningMessageContent => jsonElement.Deserialize(options.GetTypeInfo(typeof(ReasoningMessageContentEvent))) as ReasoningMessageContentEvent,
+            AGUIEventTypes.ReasoningMessageEnd => jsonElement.Deserialize(options.GetTypeInfo(typeof(ReasoningMessageEndEvent))) as ReasoningMessageEndEvent,
+            AGUIEventTypes.ReasoningEnd => jsonElement.Deserialize(options.GetTypeInfo(typeof(ReasoningEndEvent))) as ReasoningEndEvent,
+            AGUIEventTypes.ReasoningMessageChunk => jsonElement.Deserialize(options.GetTypeInfo(typeof(ReasoningMessageChunkEvent))) as ReasoningMessageChunkEvent,
+            AGUIEventTypes.ReasoningEncryptedValue => jsonElement.Deserialize(options.GetTypeInfo(typeof(ReasoningEncryptedValueEvent))) as ReasoningEncryptedValueEvent,
            _ => throw new JsonException($"Unknown BaseEvent type discriminator: '{discriminator}'")
        };

@@ -102,6 +109,27 @@ internal sealed class BaseEventJsonConverter : JsonConverter<BaseEvent>
            case StateDeltaEvent stateDelta:
                JsonSerializer.Serialize(writer, stateDelta, options.GetTypeInfo(typeof(StateDeltaEvent)));
                break;
+            case ReasoningStartEvent reasoningStart:
+                JsonSerializer.Serialize(writer, reasoningStart, options.GetTypeInfo(typeof(ReasoningStartEvent)));
+                break;
+            case ReasoningMessageStartEvent reasoningMessageStart:
+                JsonSerializer.Serialize(writer, reasoningMessageStart, options.GetTypeInfo(typeof(ReasoningMessageStartEvent)));
+                break;
+            case ReasoningMessageContentEvent reasoningMessageContent:
+                JsonSerializer.Serialize(writer, reasoningMessageContent, options.GetTypeInfo(typeof(ReasoningMessageContentEvent)));
+                break;
+            case ReasoningMessageEndEvent reasoningMessageEnd:
+                JsonSerializer.Serialize(writer, reasoningMessageEnd, options.GetTypeInfo(typeof(ReasoningMessageEndEvent)));
+                break;
+            case ReasoningEndEvent reasoningEnd:
+                JsonSerializer.Serialize(writer, reasoningEnd, options.GetTypeInfo(typeof(ReasoningEndEvent)));
+                break;
+            case ReasoningMessageChunkEvent reasoningMessageChunk:
+                JsonSerializer.Serialize(writer, reasoningMessageChunk, options.GetTypeInfo(typeof(ReasoningMessageChunkEvent)));
+                break;
+            case ReasoningEncryptedValueEvent reasoningEncryptedValue:
+                JsonSerializer.Serialize(writer, reasoningEncryptedValue, options.GetTypeInfo(typeof(ReasoningEncryptedValueEvent)));
+                break;
            default:
                throw new InvalidOperationException($"Unknown event type: {value.GetType().Name}");
        }
@@ -31,6 +31,7 @@ internal static class ChatResponseUpdateAGUIExtensions
        string? responseId = null;
        var textMessageBuilder = new TextMessageBuilder();
        var toolCallAccumulator = new ToolCallBuilder();
+        var reasoningBuilder = new ReasoningMessageBuilder();
        await foreach (var evt in events.WithCancellation(cancellationToken).ConfigureAwait(false))
        {
            switch (evt)
@@ -41,6 +42,7 @@ internal static class ChatResponseUpdateAGUIExtensions
                    responseId = runStarted.RunId;
                    toolCallAccumulator.SetConversationAndResponseIds(conversationId, responseId);
                    textMessageBuilder.SetConversationAndResponseIds(conversationId, responseId);
+                    reasoningBuilder.SetConversationAndResponseIds(conversationId, responseId);
                    yield return ValidateAndEmitRunStart(runStarted);
                    break;
                case RunFinishedEvent runFinished:
@@ -88,6 +90,36 @@ internal static class ChatResponseUpdateAGUIExtensions
                        yield return CreateStateDeltaUpdate(stateDelta, conversationId, responseId, jsonSerializerOptions);
                    }
                    break;
+
+                // Reasoning events (explicit lifecycle form)
+                case ReasoningMessageStartEvent reasoningStart:
+                    reasoningBuilder.AddReasoningStart(reasoningStart);
+                    break;
+                case ReasoningMessageContentEvent reasoningContent:
+                    yield return reasoningBuilder.EmitReasoningContent(reasoningContent);
+                    break;
+                case ReasoningMessageEndEvent reasoningEnd:
+                    reasoningBuilder.EndCurrentMessage(reasoningEnd);
+                    break;
+
+                // Reasoning events (chunk shorthand form)
+                case ReasoningMessageChunkEvent reasoningChunk:
+                    var chunkUpdate = reasoningBuilder.EmitReasoningChunk(reasoningChunk);
+                    if (chunkUpdate is not null)
+                    {
+                        yield return chunkUpdate;
+                    }
+                    break;
+
+                // Encrypted reasoning value (emitted by either form)
+                case ReasoningEncryptedValueEvent encryptedValue:
+                    yield return reasoningBuilder.EmitEncryptedValue(encryptedValue);
+                    break;
+
+                // ReasoningStartEvent and ReasoningEndEvent are bracket markers only — no content to emit
+                case ReasoningStartEvent:
+                case ReasoningEndEvent:
+                    break;
            }
        }
    }
@@ -305,6 +337,81 @@ internal static class ChatResponseUpdateAGUIExtensions
        }
    }

+    private sealed class ReasoningMessageBuilder()
+    {
+        private string? _currentMessageId;
+        private string? _conversationId;
+        private string? _responseId;
+
+        public void SetConversationAndResponseIds(string? conversationId, string? responseId)
+        {
+            this._conversationId = conversationId;
+            this._responseId = responseId;
+        }
+
+        public void AddReasoningStart(ReasoningMessageStartEvent reasoningStart)
+        {
+            if (this._currentMessageId != null)
+            {
+                throw new InvalidOperationException(
+                    "Received ReasoningMessageStartEvent while another message is being processed.");
+            }
+
+            this._currentMessageId = reasoningStart.MessageId;
+        }
+
+        public ChatResponseUpdate EmitReasoningContent(ReasoningMessageContentEvent contentEvent)
+        {
+            return new ChatResponseUpdate(ChatRole.Assistant, [new TextReasoningContent(contentEvent.Delta)])
+            {
+                ConversationId = this._conversationId,
+                ResponseId = this._responseId,
+                MessageId = contentEvent.MessageId,
+                CreatedAt = DateTimeOffset.UtcNow
+            };
+        }
+
+        public ChatResponseUpdate? EmitReasoningChunk(ReasoningMessageChunkEvent chunkEvent)
+        {
+            if (string.IsNullOrEmpty(chunkEvent.Delta))
+            {
+                // Empty delta is the implicit close signal for chunk-based streaming
+                this._currentMessageId = null;
+                return null;
+            }
+
+            this._currentMessageId ??= chunkEvent.MessageId;
+            return new ChatResponseUpdate(ChatRole.Assistant, [new TextReasoningContent(chunkEvent.Delta)])
+            {
+                ConversationId = this._conversationId,
+                ResponseId = this._responseId,
+                MessageId = chunkEvent.MessageId,
+                CreatedAt = DateTimeOffset.UtcNow
+            };
+        }
+
+        public ChatResponseUpdate EmitEncryptedValue(ReasoningEncryptedValueEvent encryptedEvent)
+        {
+            return new ChatResponseUpdate(ChatRole.Assistant, [new TextReasoningContent("") { ProtectedData = encryptedEvent.EncryptedValue }])
+            {
+                ConversationId = this._conversationId,
+                ResponseId = this._responseId,
+                MessageId = encryptedEvent.EntityId,
+                CreatedAt = DateTimeOffset.UtcNow
+            };
+        }
+
+        public void EndCurrentMessage(ReasoningMessageEndEvent reasoningEnd)
+        {
+            if (!string.Equals(this._currentMessageId, reasoningEnd.MessageId, StringComparison.Ordinal))
+            {
+                throw new InvalidOperationException(
+                    "Received ReasoningMessageEndEvent for a different message than the current one.");
+            }
+            this._currentMessageId = null;
+        }
+    }
+
    private static IDictionary<string, object?>? DeserializeArgumentsIfAvailable(string argsJson, JsonSerializerOptions options)
    {
        if (!string.IsNullOrEmpty(argsJson))
@@ -342,6 +449,9 @@ internal static class ChatResponseUpdateAGUIExtensions

        string? currentMessageId = null;
        string? streamingMessageId = null;
+        string? currentReasoningBaseId = null;
+        string? currentReasoningId = null;
+        string? currentReasoningMessageId = null;
        await foreach (var chatResponse in updates.WithCancellation(cancellationToken).ConfigureAwait(false))
        {
            // Generate a fallback MessageId when the provider doesn't supply one.
@@ -356,6 +466,25 @@ internal static class ChatResponseUpdateAGUIExtensions
                chatResponse.Contents[0] is TextContent &&
                !string.Equals(currentMessageId, chatResponse.MessageId, StringComparison.Ordinal))
            {
+                // Close any open reasoning block before opening a text message, so AG-UI
+                // events are properly bracketed. MEAI providers share one MessageId across
+                // reasoning and text content, so the reasoning-block state alone wouldn't
+                // detect the transition.
+                if (currentReasoningMessageId is not null)
+                {
+                    yield return new ReasoningMessageEndEvent
+                    {
+                        MessageId = currentReasoningMessageId
+                    };
+                    yield return new ReasoningEndEvent
+                    {
+                        MessageId = currentReasoningId!
+                    };
+                    currentReasoningBaseId = null;
+                    currentReasoningId = null;
+                    currentReasoningMessageId = null;
+                }
+
                // End the previous message if there was one
                if (currentMessageId is not null)
                {
@@ -381,7 +510,7 @@ internal static class ChatResponseUpdateAGUIExtensions
            {
                yield return new TextMessageContentEvent
                {
-                    MessageId = chatResponse.MessageId!,
+                    MessageId = currentMessageId!,
                    Delta = textContent.Text
                };
            }
@@ -393,6 +522,22 @@ internal static class ChatResponseUpdateAGUIExtensions
                {
                    if (content is FunctionCallContent functionCallContent)
                    {
+                        // Close any open reasoning block before emitting tool events.
+                        if (currentReasoningMessageId is not null)
+                        {
+                            yield return new ReasoningMessageEndEvent
+                            {
+                                MessageId = currentReasoningMessageId
+                            };
+                            yield return new ReasoningEndEvent
+                            {
+                                MessageId = currentReasoningId!
+                            };
+                            currentReasoningBaseId = null;
+                            currentReasoningId = null;
+                            currentReasoningMessageId = null;
+                        }
+
                        yield return new ToolCallStartEvent
                        {
                            ToolCallId = functionCallContent.CallId,
@@ -415,6 +560,22 @@ internal static class ChatResponseUpdateAGUIExtensions
                    }
                    else if (content is FunctionResultContent functionResultContent)
                    {
+                        // Close any open reasoning block before emitting tool result events.
+                        if (currentReasoningMessageId is not null)
+                        {
+                            yield return new ReasoningMessageEndEvent
+                            {
+                                MessageId = currentReasoningMessageId
+                            };
+                            yield return new ReasoningEndEvent
+                            {
+                                MessageId = currentReasoningId!
+                            };
+                            currentReasoningBaseId = null;
+                            currentReasoningId = null;
+                            currentReasoningMessageId = null;
+                        }
+
                        yield return new ToolCallResultEvent
                        {
                            MessageId = chatResponse.MessageId,
@@ -423,6 +584,55 @@ internal static class ChatResponseUpdateAGUIExtensions
                            Role = AGUIRoles.Tool
                        };
                    }
+                    else if (content is TextReasoningContent reasoningContent
+                        && (!string.IsNullOrEmpty(reasoningContent.Text) || !string.IsNullOrEmpty(reasoningContent.ProtectedData)))
+                    {
+                        if (!string.Equals(currentReasoningBaseId, chatResponse.MessageId, StringComparison.Ordinal))
+                        {
+                            if (currentReasoningMessageId is not null)
+                            {
+                                yield return new ReasoningMessageEndEvent
+                                {
+                                    MessageId = currentReasoningMessageId
+                                };
+                                yield return new ReasoningEndEvent
+                                {
+                                    MessageId = currentReasoningId!
+                                };
+                            }
+
+                            currentReasoningBaseId = chatResponse.MessageId;
+                            currentReasoningId = Guid.NewGuid().ToString("N");
+                            currentReasoningMessageId = Guid.NewGuid().ToString("N");
+
+                            yield return new ReasoningStartEvent
+                            {
+                                MessageId = currentReasoningId
+                            };
+                            yield return new ReasoningMessageStartEvent
+                            {
+                                MessageId = currentReasoningMessageId
+                            };
+                        }
+
+                        if (!string.IsNullOrEmpty(reasoningContent.Text))
+                        {
+                            yield return new ReasoningMessageContentEvent
+                            {
+                                MessageId = currentReasoningMessageId!,
+                                Delta = reasoningContent.Text
+                            };
+                        }
+
+                        if (!string.IsNullOrEmpty(reasoningContent.ProtectedData))
+                        {
+                            yield return new ReasoningEncryptedValueEvent
+                            {
+                                EntityId = currentReasoningMessageId!,
+                                EncryptedValue = reasoningContent.ProtectedData
+                            };
+                        }
+                    }
                    else if (content is DataContent dataContent)
                    {
                        if (MediaTypeHeaderValue.TryParse(dataContent.MediaType, out var mediaType) && mediaType.Equals(s_json))
@@ -476,6 +686,19 @@ internal static class ChatResponseUpdateAGUIExtensions
            }
        }

+        // End the last reasoning block if there was one
+        if (currentReasoningMessageId is not null)
+        {
+            yield return new ReasoningMessageEndEvent
+            {
+                MessageId = currentReasoningMessageId
+            };
+            yield return new ReasoningEndEvent
+            {
+                MessageId = currentReasoningId!
+            };
+        }
+
        // End the last message if there was one
        if (currentMessageId is not null)
        {
@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+#if ASPNETCORE
+namespace Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.Shared;
+#else
+namespace Microsoft.Agents.AI.AGUI.Shared;
+#endif
+
+internal sealed class ReasoningEncryptedValueEvent : BaseEvent
+{
+    public ReasoningEncryptedValueEvent()
+    {
+        this.Type = AGUIEventTypes.ReasoningEncryptedValue;
+    }
+
+    [JsonPropertyName("subtype")]
+    public string Subtype { get; set; } = "message";
+
+    [JsonPropertyName("entityId")]
+    public string EntityId { get; set; } = string.Empty;
+
+    [JsonPropertyName("encryptedValue")]
+    public string EncryptedValue { get; set; } = string.Empty;
+}
@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+#if ASPNETCORE
+namespace Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.Shared;
+#else
+namespace Microsoft.Agents.AI.AGUI.Shared;
+#endif
+
+internal sealed class ReasoningEndEvent : BaseEvent
+{
+    public ReasoningEndEvent()
+    {
+        this.Type = AGUIEventTypes.ReasoningEnd;
+    }
+
+    [JsonPropertyName("messageId")]
+    public string MessageId { get; set; } = string.Empty;
+}
@@ -0,0 +1,25 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+#if ASPNETCORE
+namespace Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.Shared;
+#else
+namespace Microsoft.Agents.AI.AGUI.Shared;
+#endif
+
+internal sealed class ReasoningMessageChunkEvent : BaseEvent
+{
+    public ReasoningMessageChunkEvent()
+    {
+        this.Type = AGUIEventTypes.ReasoningMessageChunk;
+    }
+
+    [JsonPropertyName("messageId")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? MessageId { get; set; }
+
+    [JsonPropertyName("delta")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? Delta { get; set; }
+}
@@ -0,0 +1,23 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+#if ASPNETCORE
+namespace Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.Shared;
+#else
+namespace Microsoft.Agents.AI.AGUI.Shared;
+#endif
+
+internal sealed class ReasoningMessageContentEvent : BaseEvent
+{
+    public ReasoningMessageContentEvent()
+    {
+        this.Type = AGUIEventTypes.ReasoningMessageContent;
+    }
+
+    [JsonPropertyName("messageId")]
+    public string MessageId { get; set; } = string.Empty;
+
+    [JsonPropertyName("delta")]
+    public string Delta { get; set; } = string.Empty;
+}
@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+#if ASPNETCORE
+namespace Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.Shared;
+#else
+namespace Microsoft.Agents.AI.AGUI.Shared;
+#endif
+
+internal sealed class ReasoningMessageEndEvent : BaseEvent
+{
+    public ReasoningMessageEndEvent()
+    {
+        this.Type = AGUIEventTypes.ReasoningMessageEnd;
+    }
+
+    [JsonPropertyName("messageId")]
+    public string MessageId { get; set; } = string.Empty;
+}
@@ -0,0 +1,23 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+#if ASPNETCORE
+namespace Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.Shared;
+#else
+namespace Microsoft.Agents.AI.AGUI.Shared;
+#endif
+
+internal sealed class ReasoningMessageStartEvent : BaseEvent
+{
+    public ReasoningMessageStartEvent()
+    {
+        this.Type = AGUIEventTypes.ReasoningMessageStart;
+    }
+
+    [JsonPropertyName("messageId")]
+    public string MessageId { get; set; } = string.Empty;
+
+    [JsonPropertyName("role")]
+    public string Role { get; set; } = AGUIRoles.Reasoning;
+}
@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+#if ASPNETCORE
+namespace Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.Shared;
+#else
+namespace Microsoft.Agents.AI.AGUI.Shared;
+#endif
+
+internal sealed class ReasoningStartEvent : BaseEvent
+{
+    public ReasoningStartEvent()
+    {
+        this.Type = AGUIEventTypes.ReasoningStart;
+    }
+
+    [JsonPropertyName("messageId")]
+    public string MessageId { get; set; } = string.Empty;
+}
@@ -105,7 +105,7 @@ public sealed class InMemoryChatHistoryProvider : ChatHistoryProvider
        State state = this._sessionState.GetOrInitializeState(context.Session);

        // Add request and response messages to the provider
-        var allNewMessages = context.RequestMessages.Concat(context.ResponseMessages ?? []);
+        var allNewMessages = (context.RequestMessages ?? []).Concat(context.ResponseMessages ?? []);
        state.Messages.AddRange(allNewMessages);

        if (this.ReducerTriggerEvent is InMemoryChatHistoryProviderOptions.ChatReducerTriggerEvent.AfterMessageAdded && this.ChatReducer is not null)
@@ -0,0 +1,106 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Net;
+using System.Security.Cryptography;
+using System.Text;
+using Microsoft.Extensions.Options;
+using Microsoft.Net.Http.Headers;
+
+namespace Microsoft.Agents.AI.DevUI;
+
+/// <summary>
+/// Endpoint filter that enforces the DevUI security posture: loopback-only
+/// access by default, plus optional bearer-token authentication.
+/// </summary>
+internal sealed class DevUIAuthFilter : IEndpointFilter
+{
+    private const string BearerScheme = "Bearer";
+
+    private readonly DevUIOptions _options;
+    private readonly byte[]? _expectedTokenBytes;
+    private readonly ILogger<DevUIAuthFilter> _logger;
+
+    /// <summary>
+    /// Gets a value indicating whether a bearer token is required by this filter
+    /// (either via <see cref="DevUIOptions.AuthToken"/> or the
+    /// <c>DEVUI_AUTH_TOKEN</c> environment variable).
+    /// </summary>
+    public bool TokenRequired => this._expectedTokenBytes is { Length: > 0 };
+
+    public DevUIAuthFilter(IOptions<DevUIOptions> options, ILogger<DevUIAuthFilter> logger)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+        ArgumentNullException.ThrowIfNull(logger);
+        this._options = options.Value;
+        this._logger = logger;
+
+        var configuredToken = !string.IsNullOrEmpty(this._options.AuthToken)
+            ? this._options.AuthToken
+            : Environment.GetEnvironmentVariable(DevUIOptions.AuthTokenEnvironmentVariable);
+
+        this._expectedTokenBytes = !string.IsNullOrEmpty(configuredToken)
+            ? Encoding.UTF8.GetBytes(configuredToken)
+            : null;
+    }
+
+    public async ValueTask<object?> InvokeAsync(EndpointFilterInvocationContext context, EndpointFilterDelegate next)
+    {
+        var httpContext = context.HttpContext;
+        var remoteIp = httpContext.Connection.RemoteIpAddress;
+        var isLoopback = remoteIp is not null && IPAddress.IsLoopback(remoteIp);
+
+        if (!isLoopback && !this._options.AllowRemoteAccess)
+        {
+            this._logger.LogWarning(
+                "Rejected non-loopback DevUI request from {RemoteIp}. Set DevUIOptions.AllowRemoteAccess to permit remote callers.",
+                remoteIp);
+            return Results.Problem(
+                statusCode: StatusCodes.Status403Forbidden,
+                title: "DevUI access denied",
+                detail: "DevUI is restricted to loopback callers by default. Enable AllowRemoteAccess to permit remote access.");
+        }
+
+        if (this._expectedTokenBytes is { Length: > 0 } expected && !TokenIsValid(httpContext.Request, expected))
+        {
+            httpContext.Response.Headers[HeaderNames.WWWAuthenticate] = BearerScheme;
+            return Results.Problem(
+                statusCode: StatusCodes.Status401Unauthorized,
+                title: "DevUI authentication required",
+                detail: "Provide a valid bearer token via the Authorization header.");
+        }
+
+        return await next(context).ConfigureAwait(false);
+    }
+
+    private static bool TokenIsValid(HttpRequest request, byte[] expected)
+    {
+        if (!request.Headers.TryGetValue(HeaderNames.Authorization, out var headerValues))
+        {
+            return false;
+        }
+
+        foreach (var header in headerValues)
+        {
+            if (string.IsNullOrEmpty(header))
+            {
+                continue;
+            }
+
+            const int PrefixLength = 7; // "Bearer "
+            if (header.Length <= PrefixLength ||
+                !header.StartsWith(BearerScheme, StringComparison.OrdinalIgnoreCase) ||
+                header[BearerScheme.Length] != ' ')
+            {
+                continue;
+            }
+
+            var presented = Encoding.UTF8.GetBytes(header.AsSpan(PrefixLength).Trim().ToString());
+            if (CryptographicOperations.FixedTimeEquals(presented, expected))
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
+}
@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.

 using System.Diagnostics.CodeAnalysis;
+using Microsoft.Extensions.Options;

 namespace Microsoft.Agents.AI.DevUI;

@@ -13,12 +14,19 @@ public static class DevUIExtensions
    /// Maps an endpoint that serves the DevUI from the '/devui' path.
    /// </summary>
    /// <remarks>
+    /// <para>
    /// DevUI requires the OpenAI Responses and Conversations services to be registered with
    /// <see cref="MicrosoftAgentAIHostingOpenAIServiceCollectionExtensions.AddOpenAIResponses(IServiceCollection)"/> and
    /// <see cref="MicrosoftAgentAIHostingOpenAIServiceCollectionExtensions.AddOpenAIConversations(IServiceCollection)"/>,
    /// and the corresponding endpoints to be mapped using
    /// <see cref="MicrosoftAgentAIHostingOpenAIEndpointRouteBuilderExtensions.MapOpenAIResponses(IEndpointRouteBuilder)"/> and
    /// <see cref="MicrosoftAgentAIHostingOpenAIEndpointRouteBuilderExtensions.MapOpenAIConversations(IEndpointRouteBuilder)"/>.
+    /// </para>
+    /// <para>
+    /// DevUI is restricted to loopback callers unless
+    /// <see cref="DevUIOptions.AllowRemoteAccess"/> is set. See <see cref="DevUIOptions"/>
+    /// for the available authentication and authorization hooks.
+    /// </para>
    /// </remarks>
    /// <param name="endpoints">The <see cref="IEndpointRouteBuilder"/> to add the endpoint to.</param>
    /// <returns>A <see cref="IEndpointConventionBuilder"/> that can be used to add authorization or other endpoint configuration.</returns>
@@ -30,11 +38,29 @@ public static class DevUIExtensions
    public static IEndpointConventionBuilder MapDevUI(
        this IEndpointRouteBuilder endpoints)
    {
-        var group = endpoints.MapGroup("");
-        group.MapDevUI(pattern: "/devui");
-        group.MapMeta();
-        group.MapEntities();
-        return group;
+        ArgumentNullException.ThrowIfNull(endpoints);
+
+        var authFilter = endpoints.ServiceProvider.GetRequiredService<DevUIAuthFilter>();
+        var options = endpoints.ServiceProvider.GetRequiredService<IOptions<DevUIOptions>>().Value;
+        var startupLogger = endpoints.ServiceProvider.GetRequiredService<ILogger<DevUIAuthFilter>>();
+
+        WarnIfInsecurelyExposed(startupLogger, options);
+
+        // /meta must remain reachable without authentication so the frontend can
+        // discover whether a bearer token is required before prompting for one.
+        endpoints.MapMeta(authRequired: authFilter.TokenRequired);
+
+        var protectedGroup = endpoints.MapGroup("");
+
+        // Conventions must be applied before endpoints are added to the group so
+        // they reliably attach to every protected DevUI endpoint.
+        options.ConfigureEndpoints?.Invoke(protectedGroup);
+        protectedGroup.AddEndpointFilter(authFilter);
+
+        protectedGroup.MapDevUI(pattern: "/devui");
+        protectedGroup.MapEntities();
+
+        return protectedGroup;
    }

    /// <summary>
@@ -66,4 +92,18 @@ public static class DevUIExtensions
            .WithName($"DevUI at {cleanPattern}")
            .WithDescription("Interactive developer interface for Microsoft Agent Framework");
    }
+
+    private static void WarnIfInsecurelyExposed(ILogger logger, DevUIOptions options)
+    {
+        var tokenConfigured = !string.IsNullOrEmpty(options.AuthToken)
+            || !string.IsNullOrEmpty(Environment.GetEnvironmentVariable(DevUIOptions.AuthTokenEnvironmentVariable));
+
+        if (options.AllowRemoteAccess && !tokenConfigured && options.ConfigureEndpoints is null)
+        {
+            logger.LogWarning(
+                "DevUI is configured with AllowRemoteAccess=true and no authentication. " +
+                "Set DevUIOptions.AuthToken, the {EnvVar} environment variable, or attach an authorization policy via ConfigureEndpoints.",
+                DevUIOptions.AuthTokenEnvironmentVariable);
+        }
+    }
 }
@@ -0,0 +1,59 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI.DevUI;
+
+/// <summary>
+/// Options that control the security posture of the DevUI HTTP surface.
+/// </summary>
+/// <remarks>
+/// DevUI exposes agent metadata that is sensitive in production contexts:
+/// system instructions, tool definitions, model identifiers, and workflow
+/// structure. By default, DevUI rejects any request whose remote endpoint
+/// is not a loopback address. Hosts that intentionally expose DevUI on a
+/// non-loopback interface must opt in via <see cref="AllowRemoteAccess"/>
+/// and should also configure <see cref="AuthToken"/> or
+/// <see cref="ConfigureEndpoints"/> to attach an authorization policy.
+/// </remarks>
+public sealed class DevUIOptions
+{
+    /// <summary>
+    /// Environment variable inspected for a default bearer token when
+    /// <see cref="AuthToken"/> is not explicitly set.
+    /// </summary>
+    public const string AuthTokenEnvironmentVariable = "DEVUI_AUTH_TOKEN";
+
+    /// <summary>
+    /// Gets or sets a value indicating whether DevUI may be served to
+    /// non-loopback callers. Defaults to <see langword="false"/>.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="false"/>, any request whose
+    /// <see cref="ConnectionInfo.RemoteIpAddress"/> is
+    /// not a loopback address (or is missing) is rejected with HTTP 403 before
+    /// reaching the DevUI handlers. Enable only when the host is responsible
+    /// for fronting DevUI with its own authentication, network policy, or both.
+    /// </remarks>
+    public bool AllowRemoteAccess { get; set; }
+
+    /// <summary>
+    /// Gets or sets a shared bearer token required on every DevUI request.
+    /// When <see langword="null"/> or empty, the value of the
+    /// <c>DEVUI_AUTH_TOKEN</c> environment variable is used instead.
+    /// </summary>
+    /// <remarks>
+    /// When a token is configured, requests must include the header
+    /// <c>Authorization: Bearer &lt;token&gt;</c>. Comparison is performed
+    /// in constant time. This is a convenience for development scenarios.
+    /// Production hosts should prefer a real ASP.NET Core authentication
+    /// scheme attached via <see cref="ConfigureEndpoints"/>.
+    /// </remarks>
+    public string? AuthToken { get; set; }
+
+    /// <summary>
+    /// Gets or sets a callback invoked with the DevUI endpoint group so the
+    /// host can attach authorization, rate limiting, or other endpoint
+    /// conventions (for example
+    /// <c>group.RequireAuthorization("DevUIPolicy")</c>).
+    /// </summary>
+    public Action<IEndpointConventionBuilder>? ConfigureEndpoints { get; set; }
+}
@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.

+using Microsoft.Agents.AI.DevUI;
+
 namespace Microsoft.Extensions.Hosting;

 /// <summary>
@@ -13,10 +15,19 @@ public static class MicrosoftAgentAIDevUIHostApplicationBuilderExtensions
    /// <param name="builder">The <see cref="IHostApplicationBuilder"/> to configure.</param>
    /// <returns>The <see cref="IHostApplicationBuilder"/> for method chaining.</returns>
    public static IHostApplicationBuilder AddDevUI(this IHostApplicationBuilder builder)
+        => AddDevUI(builder, configure: null);
+
+    /// <summary>
+    /// Adds DevUI services to the host application builder.
+    /// </summary>
+    /// <param name="builder">The <see cref="IHostApplicationBuilder"/> to configure.</param>
+    /// <param name="configure">Optional callback used to configure <see cref="DevUIOptions"/>.</param>
+    /// <returns>The <see cref="IHostApplicationBuilder"/> for method chaining.</returns>
+    public static IHostApplicationBuilder AddDevUI(this IHostApplicationBuilder builder, Action<DevUIOptions>? configure)
    {
        ArgumentNullException.ThrowIfNull(builder);

-        builder.Services.AddDevUI();
+        builder.Services.AddDevUI(configure);

        return builder;
    }
@@ -13,6 +13,7 @@ internal static class MetaApiExtensions
    /// Maps the HTTP API endpoint for retrieving server metadata.
    /// </summary>
    /// <param name="endpoints">The <see cref="IEndpointRouteBuilder"/> to add the route to.</param>
+    /// <param name="authRequired">Value reported via <c>auth_required</c> in the meta response so the frontend can decide whether to prompt for a bearer token.</param>
    /// <returns>The <see cref="IEndpointConventionBuilder"/> for method chaining.</returns>
    /// <remarks>
    /// This extension method registers the following endpoint:
@@ -22,16 +23,16 @@ internal static class MetaApiExtensions
    /// The endpoint is compatible with the Python DevUI frontend and provides essential
    /// configuration information needed for proper frontend initialization.
    /// </remarks>
-    public static IEndpointConventionBuilder MapMeta(this IEndpointRouteBuilder endpoints)
+    public static IEndpointConventionBuilder MapMeta(this IEndpointRouteBuilder endpoints, bool authRequired = false)
    {
-        return endpoints.MapGet("/meta", GetMeta)
+        return endpoints.MapGet("/meta", () => GetMeta(authRequired))
            .WithName("GetMeta")
            .WithSummary("Get server metadata and configuration")
            .WithDescription("Returns server metadata including UI mode, version, framework identifier, capabilities, and authentication requirements. Used by the frontend for initialization and feature detection.")
            .Produces<MetaResponse>(StatusCodes.Status200OK, contentType: "application/json");
    }

-    private static IResult GetMeta()
+    private static IResult GetMeta(bool authRequired)
    {
        // TODO: Consider making these configurable via IOptions<DevUIOptions>
        // For now, using sensible defaults that match Python DevUI behavior
@@ -53,7 +54,7 @@ internal static class MetaApiExtensions
                // Deployment capability - not currently supported in .NET DevUI
                ["deployment"] = false
            },
-            AuthRequired = false // Could be made configurable based on authentication middleware
+            AuthRequired = authRequired
        };

        return Results.Json(meta, EntitiesJsonContext.Default.MetaResponse);
@@ -2,6 +2,9 @@

 This package provides a web interface for testing and debugging AI agents during development.

+> [!WARNING]
+> DevUI is intended for development only. Its endpoints surface agent system instructions, tool definitions, model identifiers, and workflow structure. Do not expose DevUI to untrusted callers. By default, DevUI rejects any request whose remote endpoint is not a loopback address; see [Security](#security) below for the available options.
+
 ## Installation

 ```bash
@@ -48,3 +51,30 @@ if (builder.Environment.IsDevelopment())

 app.Run();
 ```
+
+## Security
+
+DevUI exposes `/v1/entities` and `/v1/entities/{id}/info`, which return agent metadata including the system prompt (`ChatClientAgent.Instructions`). To prevent accidental disclosure, the DevUI route group is wrapped in a small endpoint filter that:
+
+- Rejects requests from any non-loopback `RemoteIpAddress` with HTTP 403 by default.
+- Optionally requires a shared bearer token on every request.
+
+Configure via `DevUIOptions`:
+
+```csharp
+builder.AddDevUI(options =>
+{
+    // Allow non-loopback callers. Set this only when the host fronts DevUI with
+    // its own authentication or network policy.
+    options.AllowRemoteAccess = true;
+
+    // Optional: require Authorization: Bearer <token> on every request.
+    // Falls back to the DEVUI_AUTH_TOKEN environment variable when null.
+    options.AuthToken = builder.Configuration["DevUI:AuthToken"];
+
+    // Optional: attach a real authorization policy or rate limiting.
+    options.ConfigureEndpoints = group => group.RequireAuthorization("DevUIPolicy");
+});
+```
+
+The bundled bearer-token check uses constant-time comparison and is intended as a convenience for development scenarios. Production hosts should prefer a real ASP.NET Core authentication scheme via `ConfigureEndpoints`.
@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.

 using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.DevUI;
 using Microsoft.Agents.AI.Workflows;
 using Microsoft.Shared.Diagnostics;

@@ -17,9 +18,26 @@ public static class MicrosoftAgentAIDevUIServiceCollectionsExtensions
    /// <param name="services">The <see cref="IServiceCollection"/> to configure.</param>
    /// <returns>The <see cref="IServiceCollection"/> for method chaining.</returns>
    public static IServiceCollection AddDevUI(this IServiceCollection services)
+        => AddDevUI(services, configure: null);
+
+    /// <summary>
+    /// Adds services required for DevUI integration.
+    /// </summary>
+    /// <param name="services">The <see cref="IServiceCollection"/> to configure.</param>
+    /// <param name="configure">Optional callback used to configure <see cref="DevUIOptions"/>.</param>
+    /// <returns>The <see cref="IServiceCollection"/> for method chaining.</returns>
+    public static IServiceCollection AddDevUI(this IServiceCollection services, Action<DevUIOptions>? configure)
    {
        ArgumentNullException.ThrowIfNull(services);

+        var optionsBuilder = services.AddOptions<DevUIOptions>();
+        if (configure is not null)
+        {
+            optionsBuilder.Configure(configure);
+        }
+
+        services.AddSingleton<DevUIAuthFilter>();
+
        // a factory that tries to construct an AIAgent from Workflow,
        // even if workflow was not explicitly registered as an AIAgent.

@@ -1,57 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using System.Collections.Generic;
-using System.Diagnostics.CodeAnalysis;
-using System.Threading;
-using System.Threading.Tasks;
-using Microsoft.Agents.AI.Foundry.Hosting;
-using Microsoft.Extensions.AI;
-using Microsoft.Shared.DiagnosticIds;
-using Microsoft.Shared.Diagnostics;
-
-#pragma warning disable OPENAI001
-#pragma warning disable AAIP001 // AgentToolboxes is experimental in Azure.AI.Projects.Agents
-
-namespace Azure.AI.Projects;
-
-/// <summary>
-/// Provides extension methods on <see cref="AIProjectClient"/> for fetching
-/// Foundry toolbox definitions as server-side tools.
-/// </summary>
-/// <remarks>
-/// These extensions mirror Python's <c>FoundryChatClient.get_toolbox()</c> pattern,
-/// allowing a single call on the project client to retrieve tools ready for use
-/// with <c>AsAIAgent(model, instructions, tools: ...)</c>.
-/// </remarks>
-[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
-public static class AIProjectClientToolboxExtensions
-{
-    /// <summary>
-    /// Fetches a toolbox from the Foundry project and returns its tools as <see cref="AITool"/> instances
-    /// ready for use as server-side tools in the Responses API.
-    /// </summary>
-    /// <param name="projectClient">The <see cref="AIProjectClient"/> to use. Cannot be <see langword="null"/>.</param>
-    /// <param name="name">The name of the toolbox to fetch.</param>
-    /// <param name="version">
-    /// The specific toolbox version to fetch. When <see langword="null"/>, the toolbox's
-    /// default version is resolved automatically.
-    /// </param>
-    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
-    /// <returns>A read-only list of <see cref="AITool"/> instances from the toolbox.</returns>
-    /// <exception cref="System.ArgumentNullException">
-    /// Thrown when <paramref name="projectClient"/> or <paramref name="name"/> is <see langword="null"/>.
-    /// </exception>
-    public static async Task<IReadOnlyList<AITool>> GetToolboxToolsAsync(
-        this AIProjectClient projectClient,
-        string name,
-        string? version = null,
-        CancellationToken cancellationToken = default)
-    {
-        Throw.IfNull(projectClient);
-        Throw.IfNullOrWhitespace(name);
-
-        var toolboxClient = projectClient.AgentAdministrationClient.GetAgentToolboxes();
-        var toolboxVersion = await FoundryToolbox.GetToolboxVersionCoreAsync(toolboxClient, name, version, cancellationToken).ConfigureAwait(false);
-        return toolboxVersion.ToAITools();
-    }
-}
@@ -77,23 +77,31 @@ public class AgentFrameworkResponseHandler : ResponseHandler
        // 4. Convert input: history + current input → ChatMessage[]
        var messages = new List<ChatMessage>();

-        // Load conversation history if available
-        var history = await context.GetHistoryAsync(cancellationToken).ConfigureAwait(false);
-        if (history.Count > 0)
+        // Load conversation history only for fresh sessions. When a session already exists
+        // (e.g. resuming a workflow paused at an external-input port), the workflow's
+        // checkpointed state already contains the prior turns' messages — replaying history
+        // would re-drive completed actions and break HITL resume semantics.
+        var isResume = !string.IsNullOrWhiteSpace(sessionConversationId)
+            && session?.StateBag?.Count > 0;
+        if (!isResume)
        {
-            messages.AddRange(InputConverter.ConvertOutputItemsToMessages(history));
+            var history = await context.GetHistoryAsync(cancellationToken).ConfigureAwait(false);
+            if (history.Count > 0)
+            {
+                messages.AddRange(InputConverter.ConvertOutputItemsToMessages(history, session?.StateBag));
+            }
        }

        // Load and convert current input items
        var inputItems = await context.GetInputItemsAsync(cancellationToken: cancellationToken).ConfigureAwait(false);
        if (inputItems.Count > 0)
        {
-            messages.AddRange(InputConverter.ConvertItemsToMessages(inputItems));
+            messages.AddRange(InputConverter.ConvertItemsToMessages(inputItems, session?.StateBag));
        }
        else
        {
            // Fall back to raw request input
-            messages.AddRange(InputConverter.ConvertInputToMessages(request));
+            messages.AddRange(InputConverter.ConvertInputToMessages(request, session?.StateBag));
        }

        // 5. Build chat options
@@ -191,6 +199,7 @@ public class AgentFrameworkResponseHandler : ResponseHandler
        var enumerator = OutputConverter.ConvertUpdatesToEventsAsync(
            agent.RunStreamingAsync(messages, session, options: options, cancellationToken: consentCts.Token),
            stream,
+            session?.StateBag,
            cancellationToken).GetAsyncEnumerator(cancellationToken);
        try
        {
@@ -0,0 +1,261 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Buffers;
+using System.Diagnostics.CodeAnalysis;
+using System.IO;
+using System.Linq;
+using System.Text.Json;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI.Foundry.Hosting;
+
+/// <summary>
+/// Provides a file-system backed implementation of <see cref="AgentSessionStore"/> that persists
+/// the agent-framework's serialized <see cref="AgentSession"/> state for each (agent, conversation)
+/// pair to disk. This complements Foundry storage (which owns conversation messages, agent
+/// definitions, and threads) — it is not a replacement for it.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The session JSON stored here is the AF runtime's own state (workflow checkpoint manager,
+/// pending external requests, internal port state) that is required to resume an
+/// <see cref="AgentSession"/> across HTTP requests or process restarts but is not part of
+/// Foundry's data model.
+/// </para>
+/// <para>
+/// When running in a Foundry hosted environment, sessions are stored under the well-known
+/// <c>/.checkpoints</c> path; locally, they fall under <c>{cwd}/.checkpoints</c>. The session
+/// JSON produced when the agent serializes the session already contains the workflow's
+/// in-memory checkpoint manager state, so a single file per (agent, conversation) pair is
+/// sufficient to resume long-running workflows across process restarts.
+/// </para>
+/// <para>
+/// Files are written atomically via a temp-file + <see cref="File.Move(string, string, bool)"/>
+/// rename so a partially-written file cannot be observed by a concurrent reader.
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
+public sealed class FileSystemAgentSessionStore : AgentSessionStore
+{
+    /// <summary>
+    /// The well-known absolute path used when running inside a Foundry hosted environment.
+    /// </summary>
+    public const string HostedCheckpointDirectory = "/.checkpoints";
+
+    /// <summary>
+    /// The directory name used under the current working directory when running locally.
+    /// </summary>
+    public const string LocalCheckpointDirectoryName = ".checkpoints";
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FileSystemAgentSessionStore"/> class
+    /// that stores serialized sessions under <paramref name="rootDirectory"/>.
+    /// </summary>
+    /// <param name="rootDirectory">
+    /// The absolute or relative directory where session files will be written.
+    /// The directory is created on first write if it does not already exist.
+    /// </param>
+    public FileSystemAgentSessionStore(string rootDirectory)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(rootDirectory);
+        this.RootDirectory = Path.GetFullPath(rootDirectory);
+    }
+
+    /// <summary>
+    /// Gets the root directory under which session files are written.
+    /// </summary>
+    public string RootDirectory { get; }
+
+    /// <summary>
+    /// Creates a <see cref="FileSystemAgentSessionStore"/> rooted at the default location:
+    /// <see cref="HostedCheckpointDirectory"/> when running in a Foundry hosted environment,
+    /// otherwise <see cref="LocalCheckpointDirectoryName"/> under the current working directory.
+    /// </summary>
+    /// <returns>A new <see cref="FileSystemAgentSessionStore"/> instance.</returns>
+    public static FileSystemAgentSessionStore CreateDefault()
+    {
+        string root = FoundryEnvironment.IsHosted
+            ? HostedCheckpointDirectory
+            : Path.Combine(Environment.CurrentDirectory, LocalCheckpointDirectoryName);
+        return new FileSystemAgentSessionStore(root);
+    }
+
+    /// <inheritdoc/>
+    public override async ValueTask SaveSessionAsync(AIAgent agent, string conversationId, AgentSession session, CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(agent);
+        ArgumentException.ThrowIfNullOrWhiteSpace(conversationId);
+        ArgumentNullException.ThrowIfNull(session);
+
+        JsonElement serialized = await agent.SerializeSessionAsync(session, cancellationToken: cancellationToken).ConfigureAwait(false);
+
+        Directory.CreateDirectory(this.RootDirectory);
+
+        string path = this.GetSessionPath(agent, conversationId);
+        string? parentDir = Path.GetDirectoryName(path);
+        if (!string.IsNullOrEmpty(parentDir))
+        {
+            Directory.CreateDirectory(parentDir);
+        }
+
+        // Each save writes to its own temp file before atomically renaming over the
+        // destination. Last writer wins for the final file, but no reader can observe
+        // a torn or partially-written JSON document.
+        string tempPath = $"{path}.{Guid.NewGuid():N}.tmp";
+
+        try
+        {
+            using (FileStream stream = new(tempPath, FileMode.Create, FileAccess.Write, FileShare.None))
+            using (Utf8JsonWriter writer = new(stream))
+            {
+                serialized.WriteTo(writer);
+            }
+
+            File.Move(tempPath, path, overwrite: true);
+        }
+        catch
+        {
+            try { File.Delete(tempPath); } catch { /* best-effort cleanup */ }
+            throw;
+        }
+    }
+
+    /// <inheritdoc/>
+    public override async ValueTask<AgentSession> GetSessionAsync(AIAgent agent, string conversationId, CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(agent);
+        ArgumentException.ThrowIfNullOrWhiteSpace(conversationId);
+
+        string path = this.GetSessionPath(agent, conversationId);
+        if (!File.Exists(path))
+        {
+            return await agent.CreateSessionAsync(cancellationToken).ConfigureAwait(false);
+        }
+
+        byte[] bytes = await File.ReadAllBytesAsync(path, cancellationToken).ConfigureAwait(false);
+        if (bytes.Length == 0)
+        {
+            return await agent.CreateSessionAsync(cancellationToken).ConfigureAwait(false);
+        }
+
+        // Parse and clone so the document buffer can be released.
+        using JsonDocument document = JsonDocument.Parse(bytes);
+        JsonElement element = document.RootElement.Clone();
+        return await agent.DeserializeSessionAsync(element, cancellationToken: cancellationToken).ConfigureAwait(false);
+    }
+
+    private string GetSessionPath(AIAgent agent, string conversationId)
+    {
+        // When agent.Name is set we bucket sessions into a per-agent subdirectory so
+        // multiple keyed agents sharing a single in-process default store cannot
+        // collide on the same conversationId. agent.Id is intentionally NOT used
+        // because it is regenerated on every startup for in-memory-defined agents.
+        string fileName = $"{Sanitize(conversationId)}.json";
+        if (string.IsNullOrEmpty(agent.Name))
+        {
+            return Path.Combine(this.RootDirectory, fileName);
+        }
+
+        string agentDir = Path.Combine(this.RootDirectory, Sanitize(agent.Name!));
+        return Path.Combine(agentDir, fileName);
+    }
+
+    private static string Sanitize(string value)
+    {
+        // Percent-encode every character that is invalid in a filename, plus '%' itself
+        // so the encoding is unambiguous. This is reversible and avoids the collision
+        // hazard of a lossy character substitution (e.g. "foo/bar" and "foo_bar" sharing
+        // a sanitized name).
+        char[] invalid = Path.GetInvalidFileNameChars();
+
+        int encodedLength = ComputeEncodedLength(value, invalid);
+
+        // stackalloc is bounded so an externally-controlled length cannot crash the
+        // hosting process with StackOverflowException.
+        const int StackLimit = 512;
+        string sanitized;
+        if (encodedLength <= StackLimit)
+        {
+            Span<char> buffer = stackalloc char[encodedLength];
+            SanitizeCore(value, invalid, buffer);
+            sanitized = new string(buffer);
+        }
+        else
+        {
+            char[] rented = ArrayPool<char>.Shared.Rent(encodedLength);
+            try
+            {
+                Span<char> buffer = rented.AsSpan(0, encodedLength);
+                SanitizeCore(value, invalid, buffer);
+                sanitized = new string(buffer);
+            }
+            finally
+            {
+                ArrayPool<char>.Shared.Return(rented);
+            }
+        }
+
+        // '.' and '..' are valid filename characters but resolve to current/parent
+        // directory when used as a bare path component. Windows additionally strips
+        // trailing dots from filenames, so a segment like "..." would survive on disk
+        // as "" and a partial-encode like "%2E.." would survive as "%2E". Encode every
+        // dot in any all-dot segment so the result has no special meaning to the OS.
+        if (sanitized.Length > 0 && IsAllDots(sanitized))
+        {
+            return string.Concat(Enumerable.Repeat("%2E", sanitized.Length));
+        }
+
+        return sanitized;
+    }
+
+    private static int ComputeEncodedLength(string value, char[] invalid)
+    {
+        int extra = 0;
+        for (int i = 0; i < value.Length; i++)
+        {
+            char c = value[i];
+            if (c == '%' || Array.IndexOf(invalid, c) >= 0)
+            {
+                extra += 2; // 1 char ('%' or invalid) becomes 3 chars ("%XX")
+            }
+        }
+        return value.Length + extra;
+    }
+
+    private static bool IsAllDots(string value)
+    {
+        for (int i = 0; i < value.Length; i++)
+        {
+            if (value[i] != '.')
+            {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    private static void SanitizeCore(string value, char[] invalid, Span<char> buffer)
+    {
+        int j = 0;
+        for (int i = 0; i < value.Length; i++)
+        {
+            char c = value[i];
+            if (c == '%' || Array.IndexOf(invalid, c) >= 0)
+            {
+                buffer[j++] = '%';
+                buffer[j++] = HexChar((c >> 4) & 0xF);
+                buffer[j++] = HexChar(c & 0xF);
+            }
+            else
+            {
+                buffer[j++] = c;
+            }
+        }
+    }
+
+    private static char HexChar(int n) => (char)(n < 10 ? '0' + n : 'A' + n - 10);
+}
@@ -1,223 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using System;
-using System.ClientModel;
-using System.ClientModel.Primitives;
-using System.Collections.Generic;
-using System.Diagnostics.CodeAnalysis;
-using System.Linq;
-using System.Text.Json.Nodes;
-using System.Threading;
-using System.Threading.Tasks;
-using Azure.AI.Projects.Agents;
-using Microsoft.Extensions.AI;
-using Microsoft.Shared.DiagnosticIds;
-using Microsoft.Shared.Diagnostics;
-using OpenAI.Responses;
-
-#pragma warning disable OPENAI001
-#pragma warning disable AAIP001 // AgentToolboxes is experimental in Azure.AI.Projects.Agents
-#pragma warning disable IL2026 // ModelReaderWriter.Read<ResponseTool> uses reflection; suppressed for Azure SDK model types.
-#pragma warning disable IL3050 // ModelReaderWriter.Read<ResponseTool> requires dynamic code; suppressed for Azure SDK model types.
-
-namespace Microsoft.Agents.AI.Foundry.Hosting;
-
-/// <summary>
-/// Provides methods for fetching Foundry toolbox definitions and converting their tools
-/// to <see cref="AITool"/> instances for use as server-side tools in the Responses API.
-/// </summary>
-/// <remarks>
-/// <para>
-/// When tools from a toolbox are passed to a Foundry agent (e.g. via <c>AsAIAgent(model, instructions, tools: ...)</c>),
-/// they are sent as server-side tool definitions in the Responses API request. The Foundry platform
-/// handles tool execution — the agent process does not invoke tools locally.
-/// </para>
-/// <para>
-/// This is the dotnet equivalent of Python's <c>FoundryChatClient.get_toolbox()</c> pattern.
-/// </para>
-/// </remarks>
-[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
-public static class FoundryToolbox
-{
-    /// <summary>
-    /// Fetches a toolbox version from the Foundry project and returns the raw SDK <see cref="ToolboxVersion"/>.
-    /// </summary>
-    /// <param name="projectEndpoint">The Foundry project endpoint URI.</param>
-    /// <param name="credential">The authentication credential used to access the Foundry project.</param>
-    /// <param name="name">The name of the toolbox to fetch.</param>
-    /// <param name="version">
-    /// The specific toolbox version to fetch. When <see langword="null"/>, the toolbox's
-    /// default version is resolved automatically (requires an additional API call).
-    /// </param>
-    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
-    /// <returns>The <see cref="ToolboxVersion"/> containing tool definitions.</returns>
-    /// <exception cref="ArgumentNullException">
-    /// Thrown when <paramref name="projectEndpoint"/>, <paramref name="credential"/>, or <paramref name="name"/> is <see langword="null"/>.
-    /// </exception>
-    /// <exception cref="ClientResultException">Thrown when the Foundry project API returns an error.</exception>
-    public static async Task<ToolboxVersion> GetToolboxVersionAsync(
-        Uri projectEndpoint,
-        AuthenticationTokenProvider credential,
-        string name,
-        string? version = null,
-        CancellationToken cancellationToken = default)
-    {
-        Throw.IfNull(projectEndpoint);
-        Throw.IfNull(credential);
-        Throw.IfNullOrWhitespace(name);
-
-        var toolboxClient = CreateToolboxClient(projectEndpoint, credential);
-        return await GetToolboxVersionCoreAsync(toolboxClient, name, version, cancellationToken).ConfigureAwait(false);
-    }
-
-    /// <summary>
-    /// Fetches a toolbox from the Foundry project and returns its tools as <see cref="AITool"/> instances
-    /// ready for use as server-side tools in the Responses API.
-    /// </summary>
-    /// <param name="projectEndpoint">The Foundry project endpoint URI.</param>
-    /// <param name="credential">The authentication credential used to access the Foundry project.</param>
-    /// <param name="name">The name of the toolbox to fetch.</param>
-    /// <param name="version">
-    /// The specific toolbox version to fetch. When <see langword="null"/>, the toolbox's
-    /// default version is resolved automatically.
-    /// </param>
-    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
-    /// <returns>A read-only list of <see cref="AITool"/> instances from the toolbox.</returns>
-    /// <exception cref="ArgumentNullException">
-    /// Thrown when <paramref name="projectEndpoint"/>, <paramref name="credential"/>, or <paramref name="name"/> is <see langword="null"/>.
-    /// </exception>
-    /// <exception cref="ClientResultException">Thrown when the Foundry project API returns an error.</exception>
-    public static async Task<IReadOnlyList<AITool>> GetToolsAsync(
-        Uri projectEndpoint,
-        AuthenticationTokenProvider credential,
-        string name,
-        string? version = null,
-        CancellationToken cancellationToken = default)
-    {
-        var toolboxVersion = await GetToolboxVersionAsync(projectEndpoint, credential, name, version, cancellationToken).ConfigureAwait(false);
-        return toolboxVersion.ToAITools();
-    }
-
-    /// <summary>
-    /// Converts the tools in a <see cref="ToolboxVersion"/> to <see cref="AITool"/> instances
-    /// suitable for use as server-side tools in the Responses API.
-    /// </summary>
-    /// <param name="toolboxVersion">The toolbox version whose tools to convert.</param>
-    /// <returns>A read-only list of <see cref="AITool"/> instances.</returns>
-    /// <exception cref="ArgumentNullException">Thrown when <paramref name="toolboxVersion"/> is <see langword="null"/>.</exception>
-    /// <remarks>
-    /// <para>
-    /// Each <see cref="ProjectsAgentTool"/> in the toolbox is cast to <see cref="ResponseTool"/>
-    /// and converted via <c>AsAITool()</c>. Non-function hosted tools (MCP, web_search,
-    /// code_interpreter, etc.) are included as server-side tool definitions — the Foundry
-    /// platform handles their execution.
-    /// </para>
-    /// <para>
-    /// Non-function tools are sanitized to remove decoration fields (<c>name</c>, <c>description</c>)
-    /// that the toolbox API returns but the Responses API rejects.
-    /// </para>
-    /// </remarks>
-    public static IReadOnlyList<AITool> ToAITools(this ToolboxVersion toolboxVersion)
-    {
-        Throw.IfNull(toolboxVersion);
-
-        if (toolboxVersion.Tools?.Any() != true)
-        {
-            return [];
-        }
-
-        return toolboxVersion.Tools
-            .Select(SanitizeAndConvert)
-            .ToList();
-    }
-
-    #region Internal helpers (visible to unit tests via InternalsVisibleTo)
-
-    /// <summary>
-    /// Sanitizes a <see cref="ProjectsAgentTool"/> by removing decoration fields that the
-    /// toolbox API returns but the Responses API rejects, then converts to <see cref="AITool"/>.
-    /// </summary>
-    /// <remarks>
-    /// The Azure AI Projects toolbox API may return <c>name</c> and <c>description</c> on
-    /// hosted tool objects (MCP, code_interpreter, file_search, etc.). The Responses API
-    /// rejects at least <c>name</c> with "Unknown parameter: 'tools[0].name'". We strip
-    /// these decoration fields for non-function tools. Function tools keep them since
-    /// <c>name</c> and <c>description</c> are expected parts of the function schema.
-    /// </remarks>
-    internal static AITool SanitizeAndConvert(ProjectsAgentTool tool)
-    {
-        var toolJson = ModelReaderWriter.Write(tool, new ModelReaderWriterOptions("J"));
-        var node = JsonNode.Parse(toolJson.ToString());
-        if (node is not JsonObject obj)
-        {
-            return ((ResponseTool)tool).AsAITool();
-        }
-
-        var toolType = obj["type"]?.GetValue<string>();
-
-        // Function tools need name/description — don't strip
-        if (toolType is "function" or "custom")
-        {
-            return ((ResponseTool)tool).AsAITool();
-        }
-
-        // Strip decoration fields that the Responses API rejects
-        bool modified = false;
-        modified |= obj.Remove("name");
-        modified |= obj.Remove("description");
-
-        if (!modified)
-        {
-            return ((ResponseTool)tool).AsAITool();
-        }
-
-        var sanitizedJson = obj.ToJsonString();
-        var sanitizedTool = ModelReaderWriter.Read<ResponseTool>(BinaryData.FromString(sanitizedJson))!;
-        return sanitizedTool.AsAITool();
-    }
-
-    internal static async Task<ToolboxVersion> GetToolboxVersionAsync(
-        Uri projectEndpoint,
-        AuthenticationTokenProvider credential,
-        string name,
-        string? version,
-        AgentAdministrationClientOptions? clientOptions,
-        CancellationToken cancellationToken)
-    {
-        Throw.IfNull(projectEndpoint);
-        Throw.IfNull(credential);
-        Throw.IfNullOrWhitespace(name);
-
-        var toolboxClient = CreateToolboxClient(projectEndpoint, credential, clientOptions);
-        return await GetToolboxVersionCoreAsync(toolboxClient, name, version, cancellationToken).ConfigureAwait(false);
-    }
-
-    internal static AgentToolboxes CreateToolboxClient(
-        Uri projectEndpoint,
-        AuthenticationTokenProvider credential,
-        AgentAdministrationClientOptions? clientOptions = null)
-    {
-        clientOptions ??= new AgentAdministrationClientOptions();
-        var adminClient = new AgentAdministrationClient(projectEndpoint, credential, clientOptions);
-        return adminClient.GetAgentToolboxes();
-    }
-
-    internal static async Task<ToolboxVersion> GetToolboxVersionCoreAsync(
-        AgentToolboxes toolboxClient,
-        string name,
-        string? version,
-        CancellationToken cancellationToken)
-    {
-        if (version is null)
-        {
-            var record = await toolboxClient.GetToolboxAsync(name, cancellationToken).ConfigureAwait(false);
-            version = record.Value.DefaultVersion
-                ?? throw new InvalidOperationException($"Toolbox '{name}' does not have a default version. Specify an explicit version.");
-        }
-
-        var result = await toolboxClient.GetToolboxVersionAsync(name, version, cancellationToken).ConfigureAwait(false);
-        return result.Value;
-    }
-
-    #endregion
-}
@@ -4,6 +4,7 @@ using System.ClientModel.Primitives;
 using System.Collections.Generic;
 using System.Reflection;
 using System.Threading.Tasks;
+using Microsoft.Extensions.AI;

 namespace Microsoft.Agents.AI.Foundry.Hosting;

@@ -18,10 +19,9 @@ namespace Microsoft.Agents.AI.Foundry.Hosting;
 /// is already present in the <c>User-Agent</c> header, the policy does not append it again.
 /// </para>
 /// <para>
-/// This policy is added at request time (per-call <see cref="PipelinePosition"/>)
-/// by <see cref="UserAgentResponsesClient"/> when invoking the wrapped
-/// <see cref="OpenAI.Responses.ResponsesClient"/>. It is only registered when an agent is
-/// resolved by the Foundry hosting layer.
+/// This policy is added at hosted-agent resolution time via the MEAI 10.5.1
+/// <see cref="OpenAIRequestPolicies"/> hook on the agent's underlying chat client. It is only
+/// registered when an agent is resolved by the Foundry hosting layer.
 /// </para>
 /// </remarks>
 internal sealed class HostedAgentUserAgentPolicy : PipelinePolicy
@@ -3,10 +3,12 @@
 using System;
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
+using System.Text;
 using System.Text.Json;
 using Azure.AI.AgentServer.Responses.Models;
 using Microsoft.Extensions.AI;
 using MeaiTextContent = Microsoft.Extensions.AI.TextContent;
+using SdkTextContent = Azure.AI.AgentServer.Responses.Models.TextContent;

 namespace Microsoft.Agents.AI.Foundry.Hosting;

@@ -19,14 +21,15 @@ internal static class InputConverter
    /// Converts the SDK <see cref="CreateResponse"/> request input items into a list of <see cref="ChatMessage"/>.
    /// </summary>
    /// <param name="request">The create response request from the SDK.</param>
+    /// <param name="stateBag">Optional session state bag carrying the tool-approval id mapping.</param>
    /// <returns>A list of chat messages representing the request input.</returns>
-    public static List<ChatMessage> ConvertInputToMessages(CreateResponse request)
+    public static List<ChatMessage> ConvertInputToMessages(CreateResponse request, AgentSessionStateBag? stateBag = null)
    {
        var messages = new List<ChatMessage>();

        foreach (var item in request.GetInputExpanded())
        {
-            var message = ConvertInputItemToMessage(item);
+            var message = ConvertInputItemToMessage(item, stateBag);
            if (message is not null)
            {
                messages.Add(message);
@@ -40,14 +43,15 @@ internal static class InputConverter
    /// Converts resolved SDK <see cref="Item"/> input items into <see cref="ChatMessage"/> instances.
    /// </summary>
    /// <param name="items">The resolved input items from the SDK context.</param>
+    /// <param name="stateBag">Optional session state bag carrying the tool-approval id mapping.</param>
    /// <returns>A list of chat messages.</returns>
-    public static List<ChatMessage> ConvertItemsToMessages(IReadOnlyList<Item> items)
+    public static List<ChatMessage> ConvertItemsToMessages(IReadOnlyList<Item> items, AgentSessionStateBag? stateBag = null)
    {
        var messages = new List<ChatMessage>();

        foreach (var item in items)
        {
-            var message = ConvertInputItemToMessage(item);
+            var message = ConvertInputItemToMessage(item, stateBag);
            if (message is not null)
            {
                messages.Add(message);
@@ -61,14 +65,15 @@ internal static class InputConverter
    /// Converts resolved SDK <see cref="OutputItem"/> history/input items into <see cref="ChatMessage"/> instances.
    /// </summary>
    /// <param name="items">The resolved output items from the SDK context.</param>
+    /// <param name="stateBag">Optional session state bag carrying the tool-approval id mapping.</param>
    /// <returns>A list of chat messages.</returns>
-    public static List<ChatMessage> ConvertOutputItemsToMessages(IReadOnlyList<OutputItem> items)
+    public static List<ChatMessage> ConvertOutputItemsToMessages(IReadOnlyList<OutputItem> items, AgentSessionStateBag? stateBag = null)
    {
        var messages = new List<ChatMessage>();

        foreach (var item in items)
        {
-            var message = ConvertOutputItemToMessage(item);
+            var message = ConvertOutputItemToMessage(item, stateBag);
            if (message is not null)
            {
                messages.Add(message);
@@ -128,13 +133,15 @@ internal static class InputConverter
        return markers;
    }

-    private static ChatMessage? ConvertInputItemToMessage(Item item)
+    private static ChatMessage? ConvertInputItemToMessage(Item item, AgentSessionStateBag? stateBag)
    {
        return item switch
        {
            ItemMessage msg => ConvertItemMessage(msg),
            FunctionCallOutputItemParam funcOutput => ConvertFunctionCallOutput(funcOutput),
            ItemFunctionToolCall funcCall => ConvertItemFunctionToolCall(funcCall),
+            ItemMcpApprovalRequest approvalRequest => ConvertMcpApprovalRequest(approvalRequest.Id, approvalRequest.Name, approvalRequest.Arguments),
+            MCPApprovalResponse approvalResponse => ConvertMcpApprovalResponse(approvalResponse.ApprovalRequestId, approvalResponse.Approve, stateBag),
            ItemReferenceParam => null,
            _ => null
        };
@@ -152,43 +159,23 @@ internal static class InputConverter
                case MessageContentInputTextContent textContent:
                    contents.Add(new MeaiTextContent(textContent.Text));
                    break;
+                case SdkTextContent textContent:
+                    contents.Add(new MeaiTextContent(textContent.Text));
+                    break;
+                case SummaryTextContent summary:
+                    contents.Add(new MeaiTextContent(summary.Text));
+                    break;
+                case MessageContentReasoningTextContent reasoning:
+                    contents.Add(new TextReasoningContent(reasoning.Text));
+                    break;
                case MessageContentInputImageContent imageContent:
-                    if (imageContent.ImageUrl is not null)
-                    {
-                        var url = imageContent.ImageUrl.ToString();
-                        if (url.StartsWith("data:", StringComparison.OrdinalIgnoreCase))
-                        {
-                            contents.Add(new DataContent(url, "image/*"));
-                        }
-                        else
-                        {
-                            contents.Add(new UriContent(imageContent.ImageUrl, "image/*"));
-                        }
-                    }
-                    else if (!string.IsNullOrEmpty(imageContent.FileId))
-                    {
-                        contents.Add(new HostedFileContent(imageContent.FileId));
-                    }
-
+                    AppendImageContent(contents, imageContent.ImageUrl, imageContent.FileId);
                    break;
                case MessageContentInputFileContent fileContent:
-                    if (fileContent.FileUrl is not null)
-                    {
-                        contents.Add(new UriContent(fileContent.FileUrl, "application/octet-stream"));
-                    }
-                    else if (!string.IsNullOrEmpty(fileContent.FileData))
-                    {
-                        contents.Add(new DataContent(fileContent.FileData, "application/octet-stream"));
-                    }
-                    else if (!string.IsNullOrEmpty(fileContent.FileId))
-                    {
-                        contents.Add(new HostedFileContent(fileContent.FileId));
-                    }
-                    else if (!string.IsNullOrEmpty(fileContent.Filename))
-                    {
-                        contents.Add(new MeaiTextContent($"[File: {fileContent.Filename}]"));
-                    }
-
+                    AppendFileContent(contents, fileContent.FileUrl, fileContent.FileData, fileContent.FileId, fileContent.Filename);
+                    break;
+                case ComputerScreenshotContent screenshot:
+                    AppendImageContent(contents, screenshot.ImageUrl, screenshot.FileId);
                    break;
            }
        }
@@ -203,7 +190,7 @@ internal static class InputConverter

    private static ChatMessage ConvertFunctionCallOutput(FunctionCallOutputItemParam funcOutput)
    {
-        var output = funcOutput.Output?.ToString() ?? string.Empty;
+        var output = DecodeFunctionResultPayload(funcOutput.Output);
        return new ChatMessage(
            ChatRole.Tool,
            [new FunctionResultContent(funcOutput.CallId, output)]);
@@ -231,13 +218,73 @@ internal static class InputConverter
            [new FunctionCallContent(funcCall.CallId, funcCall.Name, arguments)]);
    }

-    private static ChatMessage? ConvertOutputItemToMessage(OutputItem item)
+    /// <summary>
+    /// Converts an inbound <c>mcp_approval_request</c> wire item (from history replay
+    /// or fresh-input) to a <see cref="ToolApprovalRequestContent"/> wrapping a
+    /// <see cref="FunctionCallContent"/>.
+    /// </summary>
+    private static ChatMessage ConvertMcpApprovalRequest(string id, string name, string? arguments)
+    {
+        var functionCall = new FunctionCallContent(id, name, ParseFunctionArgumentsObject(arguments));
+        return new ChatMessage(
+            ChatRole.Assistant,
+            [new ToolApprovalRequestContent(id, functionCall)]);
+    }
+
+    /// <summary>
+    /// Converts an inbound <c>mcp_approval_response</c> wire item to a
+    /// <see cref="ToolApprovalResponseContent"/>. Looks up the original
+    /// <see cref="FunctionCallContent"/> via <see cref="ToolApprovalIdMap"/> so the
+    /// reconstructed response carries the original tool name, call id, and arguments.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown when no mapping is recorded for <paramref name="approvalRequestId"/>.
+    /// Without the mapping the original call cannot be reconstructed, so we fail the request.
+    /// </exception>
+    private static ChatMessage ConvertMcpApprovalResponse(string approvalRequestId, bool approve, AgentSessionStateBag? stateBag)
+    {
+        var entry = ToolApprovalIdMap.ResolveEntry(stateBag, approvalRequestId)
+            ?? throw new InvalidOperationException(
+                $"No approval mapping recorded for wire id '{approvalRequestId}'.");
+
+        var functionCall = new FunctionCallContent(
+            entry.CallId,
+            entry.Name,
+            ParseFunctionArgumentsObject(entry.Arguments));
+
+        return new ChatMessage(
+            ChatRole.User,
+            [new ToolApprovalResponseContent(entry.AfRequestId, approve, functionCall)]);
+    }
+
+    [UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Deserializing tool-call arguments from SDK input.")]
+    [UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Deserializing tool-call arguments from SDK input.")]
+    private static Dictionary<string, object?>? ParseFunctionArgumentsObject(string? arguments)
+    {
+        if (string.IsNullOrWhiteSpace(arguments))
+        {
+            return null;
+        }
+
+        try
+        {
+            return JsonSerializer.Deserialize<Dictionary<string, object?>>(arguments);
+        }
+        catch (JsonException)
+        {
+            return new Dictionary<string, object?> { ["_raw"] = arguments };
+        }
+    }
+
+    private static ChatMessage? ConvertOutputItemToMessage(OutputItem item, AgentSessionStateBag? stateBag)
    {
        return item switch
        {
            OutputItemMessage msg => ConvertOutputItemMessageToChat(msg),
            OutputItemFunctionToolCall funcCall => ConvertOutputItemFunctionCall(funcCall),
            OutputItemFunctionToolCallOutput funcOutput => ConvertFunctionToolCallOutput(funcOutput),
+            OutputItemMcpApprovalRequest approvalRequest => ConvertMcpApprovalRequest(approvalRequest.Id, approvalRequest.Name, approvalRequest.Arguments),
+            OutputItemMcpApprovalResponseResource approvalResponse => ConvertMcpApprovalResponse(approvalResponse.ApprovalRequestId, approvalResponse.Approve, stateBag),
            OutputItemReasoningItem => null,
            _ => null
        };
@@ -258,46 +305,26 @@ internal static class InputConverter
                case MessageContentOutputTextContent textContent:
                    contents.Add(new MeaiTextContent(textContent.Text));
                    break;
+                case SdkTextContent textContent:
+                    contents.Add(new MeaiTextContent(textContent.Text));
+                    break;
+                case SummaryTextContent summary:
+                    contents.Add(new MeaiTextContent(summary.Text));
+                    break;
+                case MessageContentReasoningTextContent reasoning:
+                    contents.Add(new TextReasoningContent(reasoning.Text));
+                    break;
                case MessageContentRefusalContent refusal:
                    contents.Add(new MeaiTextContent($"[Refusal: {refusal.Refusal}]"));
                    break;
                case MessageContentInputImageContent imageContent:
-                    if (imageContent.ImageUrl is not null)
-                    {
-                        var url = imageContent.ImageUrl.ToString();
-                        if (url.StartsWith("data:", StringComparison.OrdinalIgnoreCase))
-                        {
-                            contents.Add(new DataContent(url, "image/*"));
-                        }
-                        else
-                        {
-                            contents.Add(new UriContent(imageContent.ImageUrl, "image/*"));
-                        }
-                    }
-                    else if (!string.IsNullOrEmpty(imageContent.FileId))
-                    {
-                        contents.Add(new HostedFileContent(imageContent.FileId));
-                    }
-
+                    AppendImageContent(contents, imageContent.ImageUrl, imageContent.FileId);
                    break;
                case MessageContentInputFileContent fileContent:
-                    if (fileContent.FileUrl is not null)
-                    {
-                        contents.Add(new UriContent(fileContent.FileUrl, "application/octet-stream"));
-                    }
-                    else if (!string.IsNullOrEmpty(fileContent.FileData))
-                    {
-                        contents.Add(new DataContent(fileContent.FileData, "application/octet-stream"));
-                    }
-                    else if (!string.IsNullOrEmpty(fileContent.FileId))
-                    {
-                        contents.Add(new HostedFileContent(fileContent.FileId));
-                    }
-                    else if (!string.IsNullOrEmpty(fileContent.Filename))
-                    {
-                        contents.Add(new MeaiTextContent($"[File: {fileContent.Filename}]"));
-                    }
-
+                    AppendFileContent(contents, fileContent.FileUrl, fileContent.FileData, fileContent.FileId, fileContent.Filename);
+                    break;
+                case ComputerScreenshotContent screenshot:
+                    AppendImageContent(contents, screenshot.ImageUrl, screenshot.FileId);
                    break;
            }
        }
@@ -310,6 +337,127 @@ internal static class InputConverter
        return new ChatMessage(role, contents);
    }

+    private static void AppendImageContent(List<AIContent> contents, Uri? imageUrl, string? fileId)
+    {
+        if (imageUrl is not null)
+        {
+            var url = imageUrl.ToString();
+            if (url.StartsWith("data:", StringComparison.OrdinalIgnoreCase))
+            {
+                contents.Add(new DataContent(url, "image/*"));
+            }
+            else
+            {
+                contents.Add(new UriContent(imageUrl, "image/*"));
+            }
+        }
+        else if (!string.IsNullOrEmpty(fileId))
+        {
+            contents.Add(new HostedFileContent(fileId));
+        }
+    }
+
+    private static void AppendFileContent(List<AIContent> contents, Uri? fileUrl, string? fileData, string? fileId, string? filename)
+    {
+        if (fileUrl is not null)
+        {
+            var content = new UriContent(fileUrl, "application/octet-stream");
+            if (!string.IsNullOrEmpty(filename))
+            {
+                content.AdditionalProperties = new AdditionalPropertiesDictionary { ["filename"] = filename };
+            }
+            contents.Add(content);
+            return;
+        }
+
+        if (!string.IsNullOrEmpty(fileData))
+        {
+            // If the data URI carries text/* content, decode it inline as TextContent so
+            // {System.LastMessageText} (and other text-only consumers) sees the file's
+            // body rather than an opaque blob.
+            if (TryDecodeTextDataUri(fileData, filename, out var decodedText))
+            {
+                contents.Add(new MeaiTextContent(decodedText));
+            }
+            else
+            {
+                var dataContent = new DataContent(fileData, "application/octet-stream");
+                if (!string.IsNullOrEmpty(filename))
+                {
+                    dataContent.AdditionalProperties = new AdditionalPropertiesDictionary { ["filename"] = filename };
+                }
+                contents.Add(dataContent);
+            }
+            return;
+        }
+
+        if (!string.IsNullOrEmpty(fileId))
+        {
+            var hosted = new HostedFileContent(fileId);
+            if (!string.IsNullOrEmpty(filename))
+            {
+                hosted.AdditionalProperties = new AdditionalPropertiesDictionary { ["filename"] = filename };
+            }
+            contents.Add(hosted);
+            return;
+        }
+
+        if (!string.IsNullOrEmpty(filename))
+        {
+            contents.Add(new MeaiTextContent($"[File: {filename}]"));
+        }
+    }
+
+    private static bool TryDecodeTextDataUri(string dataUri, string? filename, out string text)
+    {
+        // Cap the encoded payload so an oversized client-supplied data URI cannot
+        // trigger an unbounded allocation in Convert.FromBase64String. 16 MiB
+        // encoded → ~12 MiB decoded, well above any realistic text/* file we'd
+        // want to inline as content while still bounding the worst case.
+        const int MaxEncodedLength = 16 * 1024 * 1024;
+
+        text = string.Empty;
+        if (!dataUri.StartsWith("data:", StringComparison.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        const string Marker = ";base64,";
+        int markerIndex = dataUri.IndexOf(Marker, StringComparison.OrdinalIgnoreCase);
+        if (markerIndex < 0)
+        {
+            return false;
+        }
+
+        string mediaType = dataUri.Substring("data:".Length, markerIndex - "data:".Length);
+        if (!mediaType.StartsWith("text/", StringComparison.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        string encoded = dataUri.Substring(markerIndex + Marker.Length);
+        if (encoded.Length > MaxEncodedLength)
+        {
+            return false;
+        }
+
+        try
+        {
+            byte[] bytes = Convert.FromBase64String(encoded);
+            string decoded = Encoding.UTF8.GetString(bytes);
+            text = string.IsNullOrEmpty(filename) ? decoded : $"[File: {filename}]\n{decoded}";
+            return true;
+        }
+        catch (FormatException)
+        {
+            return false;
+        }
+        catch (DecoderFallbackException)
+        {
+            return false;
+        }
+    }
+
    [UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Deserializing function call arguments from SDK output history.")]
    [UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Deserializing function call arguments from SDK output history.")]
    private static ChatMessage ConvertOutputItemFunctionCall(OutputItemFunctionToolCall funcCall)
@@ -334,9 +482,54 @@ internal static class InputConverter

    private static ChatMessage ConvertFunctionToolCallOutput(OutputItemFunctionToolCallOutput funcOutput)
    {
+        var output = DecodeFunctionResultPayload(funcOutput.Output);
        return new ChatMessage(
            ChatRole.Tool,
-            [new FunctionResultContent(funcOutput.CallId, funcOutput.Output)]);
+            [new FunctionResultContent(funcOutput.CallId, output)]);
+    }
+
+    /// <summary>
+    /// Decodes the wire payload of a <c>function_call_output.output</c> field back into the
+    /// underlying tool-result text suitable for replay as <see cref="FunctionResultContent.Result"/>.
+    /// </summary>
+    /// <remarks>
+    /// Mirrors <c>OutputConverter.EncodeFunctionResultAsJsonStringPayload</c>. Per the OpenAI
+    /// Responses spec, <c>output</c> is a JSON string; we extract its underlying value. Legacy
+    /// producers that emitted raw JSON values (arrays/objects) are tolerated by passing the raw
+    /// bytes through unchanged.
+    /// </remarks>
+    private static string DecodeFunctionResultPayload(BinaryData? rawOutput)
+    {
+        if (rawOutput is null)
+        {
+            return string.Empty;
+        }
+
+        var raw = rawOutput.ToString();
+        if (string.IsNullOrEmpty(raw))
+        {
+            return string.Empty;
+        }
+
+        try
+        {
+            using var doc = JsonDocument.Parse(raw);
+            if (doc.RootElement.ValueKind == JsonValueKind.String)
+            {
+                return doc.RootElement.GetString() ?? string.Empty;
+            }
+
+            // Legacy/non-conforming producers may have emitted a raw JSON value
+            // (array/object/number/bool/null). Pass the raw text through as the
+            // payload so the replayed FunctionResultContent.Result preserves the
+            // original tool output shape.
+            return raw;
+        }
+        catch (JsonException)
+        {
+            // Not valid JSON — treat the bytes as a literal string payload.
+            return raw;
+        }
    }

    private static ChatRole ConvertMessageRole(MessageRole role)
@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFrameworks>$(TargetFrameworksCore)</TargetFrameworks>
@@ -31,7 +31,7 @@

  <ItemGroup>
    <PackageReference Include="Azure.AI.AgentServer.Responses" />
-    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.AI.Projects" />
    <PackageReference Include="Azure.Identity" />
    <PackageReference Include="ModelContextProtocol" />
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" />
@@ -30,6 +30,7 @@ internal static class OutputConverter
    /// </summary>
    /// <param name="updates">The agent response updates to convert.</param>
    /// <param name="stream">The SDK event stream builder.</param>
+    /// <param name="stateBag">Optional session state bag used to persist tool-approval id mappings across turns.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>An async enumerable of SDK response stream events (excluding lifecycle events).</returns>
    [UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Serializing function call arguments dictionary.")]
@@ -37,6 +38,7 @@ internal static class OutputConverter
    public static async IAsyncEnumerable<ResponseStreamEvent> ConvertUpdatesToEventsAsync(
        IAsyncEnumerable<AgentResponseUpdate> updates,
        ResponseEventStream stream,
+        AgentSessionStateBag? stateBag = null,
        [EnumeratorCancellation] CancellationToken cancellationToken = default)
    {
        ResponseUsage? accumulatedUsage = null;
@@ -51,8 +53,11 @@ internal static class OutputConverter
        {
            cancellationToken.ThrowIfCancellationRequested();

-            // Handle workflow events from RawRepresentation
-            if (update.RawRepresentation is WorkflowEvent workflowEvent)
+            // Handle workflow events from RawRepresentation.
+            // If the update also carries Contents (e.g. WorkflowSession unwrapped a
+            // WorkflowErrorEvent or ExecutorFailedEvent into an ErrorContent payload),
+            // fall through to the content-processing path below so those are emitted.
+            if (update.RawRepresentation is WorkflowEvent workflowEvent && update.Contents.Count == 0)
            {
                // Close any open message builder before emitting workflow items
                foreach (var evt in CloseCurrentMessage(currentMessageBuilder, currentTextBuilder, accumulatedText))
@@ -113,8 +118,13 @@ internal static class OutputConverter
                        break;
                    }

-                    case FunctionCallContent funcCall:
+                    case FunctionCallContent functionCall:
                    {
+                        if (functionCall.CallId is not { Length: > 0 })
+                        {
+                            break;
+                        }
+
                        foreach (var evt in CloseCurrentMessage(currentMessageBuilder, currentTextBuilder, accumulatedText))
                        {
                            yield return evt;
@@ -125,17 +135,15 @@ internal static class OutputConverter
                        accumulatedText = null;
                        previousMessageId = null;

-                        var callId = funcCall.CallId ?? Guid.NewGuid().ToString("N");
-                        var funcBuilder = stream.AddOutputItemFunctionCall(funcCall.Name, callId);
-                        yield return funcBuilder.EmitAdded();
-
-                        var arguments = funcCall.Arguments is not null
-                            ? JsonSerializer.Serialize(funcCall.Arguments)
+                        var arguments = functionCall.Arguments is not null
+                            ? JsonSerializer.Serialize(functionCall.Arguments)
                            : "{}";

-                        yield return funcBuilder.EmitArgumentsDelta(arguments);
-                        yield return funcBuilder.EmitArgumentsDone(arguments);
-                        yield return funcBuilder.EmitDone();
+                        var fcBuilder = stream.AddOutputItemFunctionCall(functionCall.Name, functionCall.CallId);
+                        yield return fcBuilder.EmitAdded();
+                        yield return fcBuilder.EmitArgumentsDelta(arguments);
+                        yield return fcBuilder.EmitArgumentsDone(arguments);
+                        yield return fcBuilder.EmitDone();
                        break;
                    }

@@ -166,6 +174,61 @@ internal static class OutputConverter
                        break;
                    }

+                    case ToolApprovalRequestContent approvalRequest when approvalRequest.ToolCall is FunctionCallContent approvalFunctionCall:
+                    {
+                        foreach (var evt in CloseCurrentMessage(currentMessageBuilder, currentTextBuilder, accumulatedText))
+                        {
+                            yield return evt;
+                        }
+
+                        currentTextBuilder = null;
+                        currentMessageBuilder = null;
+                        accumulatedText = null;
+                        previousMessageId = null;
+
+                        // The Responses API only standardizes the MCP-flavored approval primitive.
+                        // We emit the AF tool-approval request as `mcp_approval_request` with
+                        // server_label="agent_framework" — declaring the AF runtime as the virtual
+                        // server holding this call. The SDK requires a strict {prefix}_{50hex}
+                        // wire-id format, so we hash the AF RequestId and persist the
+                        // wireId↔afRequestId mapping in the session state bag for later lookup
+                        // when the matching `mcp_approval_response` arrives on a subsequent turn.
+                        var wireId = ToolApprovalIdMap.ComputeWireId(approvalRequest.RequestId);
+
+                        var approvalArguments = approvalFunctionCall.Arguments is not null
+                            ? JsonSerializer.Serialize(approvalFunctionCall.Arguments)
+                            : "{}";
+
+                        ToolApprovalIdMap.Record(
+                            stateBag,
+                            wireId,
+                            approvalRequest.RequestId,
+                            approvalFunctionCall.CallId,
+                            approvalFunctionCall.Name,
+                            approvalArguments);
+
+                        var approvalItem = new OutputItemMcpApprovalRequest(
+                            wireId,
+                            "agent_framework",
+                            approvalFunctionCall.Name,
+                            approvalArguments);
+
+                        var approvalBuilder = stream.AddOutputItem<OutputItemMcpApprovalRequest>(wireId);
+                        yield return approvalBuilder.EmitAdded(approvalItem);
+                        yield return approvalBuilder.EmitDone(approvalItem);
+                        break;
+                    }
+
+                    case ToolApprovalRequestContent:
+                        // Approval requests must wrap a FunctionCallContent (handled above).
+                        // Any other shape has no representation in the Responses wire format.
+                        break;
+
+                    case ToolApprovalResponseContent:
+                        // Approval responses originate from the client and travel inbound; the
+                        // workflow does not re-emit them. Skip silently if encountered.
+                        break;
+
                    case UsageContent usageContent when usageContent.Details is not null:
                    {
                        accumulatedUsage = ConvertUsage(usageContent.Details, accumulatedUsage);
@@ -199,10 +262,35 @@ internal static class OutputConverter
                        // These would need to be serialized as base64 or URL references.
                        break;

-                    case FunctionResultContent:
-                        // Function results are internal to the agent's tool-calling loop
-                        // and are not emitted as output items in the response stream.
+                    case FunctionResultContent functionResult:
+                    {
+                        if (functionResult.CallId is not { Length: > 0 })
+                        {
+                            break;
+                        }
+
+                        foreach (var evt in CloseCurrentMessage(currentMessageBuilder, currentTextBuilder, accumulatedText))
+                        {
+                            yield return evt;
+                        }
+
+                        currentTextBuilder = null;
+                        currentMessageBuilder = null;
+                        accumulatedText = null;
+                        previousMessageId = null;
+
+                        var outputText = EncodeFunctionResultAsJsonStringPayload(functionResult.Result);
+
+                        var itemId = GenerateItemId("fc");
+                        var outputItem = new OutputItemFunctionToolCallOutput(
+                            functionResult.CallId,
+                            BinaryData.FromString(outputText));
+
+                        var outputBuilder = stream.AddOutputItem<OutputItemFunctionToolCallOutput>(itemId);
+                        yield return outputBuilder.EmitAdded(outputItem);
+                        yield return outputBuilder.EmitDone(outputItem);
                        break;
+                    }

                    default:
                        break;
@@ -355,4 +443,44 @@ internal static class OutputConverter
        var body = Convert.ToHexString(bytes); // 50 hex chars, uppercase
        return $"{prefix}_{body}";
    }
+
+    /// <summary>
+    /// Encodes a <see cref="FunctionResultContent.Result"/> value into the wire payload for
+    /// the OpenAI Responses <c>function_call_output.output</c> field.
+    /// </summary>
+    /// <remarks>
+    /// The OpenAI Responses spec requires <c>output</c> to be a JSON string. The Responses
+    /// SDK's <see cref="OutputItemFunctionToolCallOutput"/> accepts a <see cref="BinaryData"/>
+    /// containing the *raw JSON value* for the field, so the returned text is always a JSON
+    /// string literal (quoted, with escapes). This avoids two bugs:
+    /// <list type="bullet">
+    ///   <item>Complex results (e.g. <c>List&lt;TodoItem&gt;</c>) landing on the wire as an
+    ///   unquoted JSON array, which the strict-parsing OpenAI .NET client
+    ///   (<c>FunctionCallOutputResponseItem</c>) rejects with
+    ///   "requires an element of type 'String', but the target element has type 'Array'".</item>
+    ///   <item>Numeric- or JSON-shaped string results (e.g. <c>"42"</c> or <c>"{\"k\":1}"</c>)
+    ///   silently changing type on the wire because <c>BinaryData</c> auto-detects JSON.</item>
+    /// </list>
+    /// <see cref="JsonElement"/> / <see cref="JsonDocument"/> values are unwrapped first so
+    /// a string-kind element does not get double-encoded into <c>"\"value\""</c>.
+    /// </remarks>
+    [UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Serializing function call result payload.")]
+    [UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Serializing function call result payload.")]
+    private static string EncodeFunctionResultAsJsonStringPayload(object? result)
+    {
+        string innerText = result switch
+        {
+            null => string.Empty,
+            string s => s,
+            JsonElement je => je.ValueKind == JsonValueKind.String
+                ? (je.GetString() ?? string.Empty)
+                : je.GetRawText(),
+            JsonDocument jd => jd.RootElement.ValueKind == JsonValueKind.String
+                ? (jd.RootElement.GetString() ?? string.Empty)
+                : jd.RootElement.GetRawText(),
+            _ => JsonSerializer.Serialize(result),
+        };
+
+        return JsonSerializer.Serialize(innerText);
+    }
 }
@@ -1,8 +1,9 @@
 // Copyright (c) Microsoft. All rights reserved.

 using System;
+using System.ClientModel.Primitives;
 using System.Diagnostics.CodeAnalysis;
-using System.Reflection;
+using System.Runtime.CompilerServices;
 using Azure.AI.AgentServer.Responses;
 using Azure.Core;
 using Azure.Identity;
@@ -11,7 +12,6 @@ using Microsoft.Extensions.AI;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.DependencyInjection.Extensions;
 using Microsoft.Shared.DiagnosticIds;
-using OpenAI.Responses;

 namespace Microsoft.Agents.AI.Foundry.Hosting;

@@ -49,7 +49,7 @@ public static class FoundryHostingExtensions
    {
        ArgumentNullException.ThrowIfNull(services);
        services.AddResponsesServer();
-        services.TryAddSingleton<AgentSessionStore, InMemoryAgentSessionStore>();
+        services.TryAddSingleton<AgentSessionStore>(_ => FileSystemAgentSessionStore.CreateDefault());
        services.TryAddSingleton<ResponseHandler, AgentFrameworkResponseHandler>();
        return services;
    }
@@ -76,7 +76,7 @@ public static class FoundryHostingExtensions
    /// </remarks>
    /// <param name="services">The service collection.</param>
    /// <param name="agent">The agent instance to register.</param>
-    /// <param name="agentSessionStore">The agent session store to use for managing agent sessions server-side. If null, an in-memory session store will be used.</param>
+    /// <param name="agentSessionStore">The agent session store to use for managing agent sessions server-side. If null, a file-system session store is used, rooted at <c>/.checkpoints</c> when running in a Foundry hosted environment and <c>{cwd}/.checkpoints</c> locally.</param>
    /// <returns>The service collection for chaining.</returns>
    public static IServiceCollection AddFoundryResponses(this IServiceCollection services, AIAgent agent, AgentSessionStore? agentSessionStore = null)
    {
@@ -84,7 +84,7 @@ public static class FoundryHostingExtensions
        ArgumentNullException.ThrowIfNull(agent);

        services.AddResponsesServer();
-        agentSessionStore ??= new InMemoryAgentSessionStore();
+        agentSessionStore ??= FileSystemAgentSessionStore.CreateDefault();

        if (!string.IsNullOrWhiteSpace(agent.Name))
        {
@@ -185,8 +185,6 @@ public static class FoundryHostingExtensions

    /// <summary>
    /// The ActivitySource name for the Responses hosting pipeline.
-    /// Matches the value previously exposed by <c>AgentHostTelemetry.ResponsesSourceName</c>
-    /// in <c>Azure.AI.AgentServer.Core</c>.
    /// </summary>
    private const string ResponsesSourceName = "Azure.AI.AgentServer.Responses";

@@ -209,84 +207,45 @@ public static class FoundryHostingExtensions
    }

    /// <summary>
-    /// Attempts to wrap the agent's underlying <see cref="ResponsesClient"/>
-    /// with a <see cref="UserAgentResponsesClient"/> so every outgoing Responses-API request
-    /// carries the hosted-agent <c>User-Agent</c> segment.
+    /// Registers the hosted-agent <c>User-Agent</c> supplement policy
+    /// (<see cref="HostedAgentUserAgentPolicy"/>) on the agent's underlying chat client via the
+    /// MEAI 10.5.1 <see cref="OpenAIRequestPolicies"/> hook so every outgoing OpenAI Responses
+    /// request carries the segment <c>foundry-hosting/agent-framework-dotnet/{version}</c>.
    /// </summary>
    /// <remarks>
    /// <para>
    /// Best-effort and idempotent. The method is a no-op when:
    /// <list type="bullet">
    /// <item><description><paramref name="agent"/> exposes no <see cref="IChatClient"/>;</description></item>
-    /// <item><description>the chat client is not backed by MEAI's internal <c>OpenAIResponsesChatClient</c> (e.g., a non-OpenAI provider or a custom impl);</description></item>
-    /// <item><description>the inner <see cref="ResponsesClient"/> is already a <see cref="UserAgentResponsesClient"/>.</description></item>
+    /// <item><description>the chat client is not OpenAI-backed (the <see cref="OpenAIRequestPolicies"/> service lookup returns <see langword="null"/>);</description></item>
+    /// <item><description>the policy was already registered on this client by a prior invocation (deduped via reflection on <c>OpenAIRequestPolicies._entries</c>).</description></item>
    /// </list>
    /// </para>
    /// <para>
-    /// Works for any <see cref="ResponsesClient"/>-derived inner client — both the Foundry-specific
-    /// <see cref="Azure.AI.Extensions.OpenAI.ProjectResponsesClient"/> and the native OpenAI
-    /// <see cref="ResponsesClient"/> obtained from <see cref="OpenAI.OpenAIClient"/>. The wrapper preserves
-    /// the inner client's pipeline (Transport, RetryPolicy, NetworkTimeout, OrganizationId / ProjectId /
-    /// UserAgentApplicationId, custom policies) because every override delegates to the inner instance.
-    /// </para>
-    /// <para>
-    /// Returns the same <paramref name="agent"/> instance unchanged. Mutation happens via
-    /// reflection on MEAI's private <c>_responseClient</c> field; the agent itself is not wrapped.
+    /// Returns the same <paramref name="agent"/> instance unchanged. The policy is installed
+    /// on the chat client; the agent itself is not wrapped.
    /// </para>
    /// </remarks>
    internal static AIAgent TryApplyUserAgent(AIAgent agent)
    {
        var chatClient = agent.GetService<IChatClient>();
-        if (chatClient is null)
+        if (chatClient?.GetService<OpenAIRequestPolicies>() is { } policies)
        {
-            return agent;
+            // Hosted agents are typically singletons resolved per request, so AddPolicy must be
+            // called at most once per OpenAIRequestPolicies instance to avoid unbounded growth of
+            // the policy list (each entry adds per-request CPU work even though the User-Agent
+            // value stays stable). Track which instances we have already wired with a
+            // ConditionalWeakTable keyed on the OpenAIRequestPolicies reference; the table holds
+            // weak references so it does not extend the lifetime of the chat client.
+            if (s_userAgentRegistrations.TryAdd(policies, s_boxedTrue))
+            {
+                policies.AddPolicy(HostedAgentUserAgentPolicy.Instance, PipelinePosition.PerCall);
+            }
        }

-        var meaiType = s_meaiResponsesChatClientType;
-        if (meaiType is null)
-        {
-            return agent;
-        }
-
-        var meaiInstance = chatClient.GetService(meaiType);
-        if (meaiInstance is null)
-        {
-            return agent;
-        }
-
-        var field = s_meaiResponseClientField;
-        if (field is null)
-        {
-            return agent;
-        }
-
-        var current = field.GetValue(meaiInstance) as ResponsesClient;
-        if (current is null or UserAgentResponsesClient)
-        {
-            return agent;
-        }
-
-        field.SetValue(meaiInstance, new UserAgentResponsesClient(current));
        return agent;
    }

-    /// <summary>
-    /// MEAI's internal <c>OpenAIResponsesChatClient</c> type, resolved once via reflection.
-    /// <see langword="null"/> if the type cannot be found (e.g., MEAI version drift).
-    /// </summary>
-    [UnconditionalSuppressMessage("Trimming", "IL2026:RequiresUnreferencedCode",
-        Justification = "MEAI's OpenAIResponsesChatClient is referenced through MicrosoftExtensionsAIResponsesExtensions and survives trimming.")]
-    [UnconditionalSuppressMessage("Trimming", "IL2073:RequiresUnreferencedCode",
-        Justification = "MEAI's OpenAIResponsesChatClient is referenced through MicrosoftExtensionsAIResponsesExtensions and survives trimming.")]
-    private static readonly Type? s_meaiResponsesChatClientType =
-        typeof(MicrosoftExtensionsAIResponsesExtensions).Assembly.GetType("Microsoft.Extensions.AI.OpenAIResponsesChatClient");
-
-    /// <summary>
-    /// MEAI's internal <c>_responseClient</c> field on <c>OpenAIResponsesChatClient</c>,
-    /// resolved once via reflection. <see langword="null"/> if the field cannot be found.
-    /// </summary>
-    [UnconditionalSuppressMessage("Trimming", "IL2080:RequiresDynamicallyAccessedMembers",
-        Justification = "OpenAIResponsesChatClient and its private fields are preserved by the polyfill design; MEAI does the same reflection internally.")]
-    private static readonly FieldInfo? s_meaiResponseClientField =
-        s_meaiResponsesChatClientType?.GetField("_responseClient", BindingFlags.NonPublic | BindingFlags.Instance);
+    private static readonly object s_boxedTrue = new();
+    private static readonly ConditionalWeakTable<OpenAIRequestPolicies, object> s_userAgentRegistrations = new();
 }
--- a/Show More
+++ b/Show More