Update python/samples/03-workflows/declarative/invoke_mcp_tool/main.py

Co-authored-by: Eduard van Valkenburg <eavanvalkenburg@users.noreply.github.com>
Fix cache and PR comments
2026-06-16 21:04:09 +08:00 · 2026-05-05 08:09:12 -07:00 · 2026-05-04 15:08:04 -07:00 · 2026-05-04 13:47:24 -07:00 · 2026-05-04 13:08:21 -07:00 · 2026-05-04 11:57:45 -07:00
478 changed files with 48497 additions and 4019 deletions
@@ -157,6 +157,8 @@ jobs:
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
      ANTHROPIC_CHAT_MODEL: ${{ vars.ANTHROPIC_CHAT_MODEL_ID }}
      LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
+      OLLAMA_MODEL: qwen2.5:1.5b
+      OLLAMA_EMBEDDING_MODEL: nomic-embed-text
    defaults:
      run:
        working-directory: python
@@ -171,6 +173,43 @@ jobs:
        with:
          python-version: ${{ env.UV_PYTHON }}
          os: ${{ runner.os }}
+      - name: Install Ollama
+        run: curl -fsSL https://ollama.com/install.sh | sh
+        working-directory: .
+      - name: Cache Ollama models
+        uses: actions/cache@v4
+        with:
+          path: ~/.ollama/models
+          key: ollama-models-qwen2.5-1.5b-nomic-embed-text-v1
+      - name: Start Ollama and pull models
+        run: |
+          # Stop any Ollama instance auto-started by the install script
+          pkill ollama || true
+          sleep 2
+          ollama serve &
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:11434/api/tags > /dev/null 2>&1; then
+              break
+            fi
+            sleep 1
+          done
+          # Pull models with retry for transient 429 rate limits
+          for model in qwen2.5:1.5b nomic-embed-text; do
+            pulled=false
+            for attempt in 1 2 3; do
+              if ollama pull "$model"; then
+                pulled=true
+                break
+              fi
+              echo "Retry $attempt for $model (waiting 15s)..."
+              sleep 15
+            done
+            if [ "$pulled" != "true" ]; then
+              echo "ERROR: Failed to pull $model after 3 attempts"
+              exit 1
+            fi
+          done
+        working-directory: .
      - name: Start local MCP server
        id: local-mcp
        uses: ./.github/actions/setup-local-mcp-server
@@ -271,7 +310,7 @@ jobs:
          -m integration
          -n logical --dist worksteal
          -x
-          --timeout=360 --session-timeout=900 --timeout_method thread
+          --timeout=480 --session-timeout=900 --timeout_method thread
          --retries 2 --retry-delay 5
          --junitxml=pytest.xml
      - name: Upload test results
@@ -336,6 +375,53 @@ jobs:
          path: ./python/pytest.xml
          if-no-files-found: ignore

+  # Foundry Hosting integration tests
+  python-tests-foundry-hosting:
+    name: Python Integration Tests - Foundry Hosting
+    runs-on: ubuntu-latest
+    environment: integration
+    timeout-minutes: 60
+    env:
+      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
+      FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL }}
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
+          persist-credentials: false
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - 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 }}
+      - name: Test with pytest (Foundry Hosting integration)
+        timeout-minutes: 15
+        run: >
+          uv run pytest --import-mode=importlib
+          packages/foundry_hosting/tests
+          -m integration
+          -n logical --dist worksteal
+          --timeout=120 --session-timeout=900 --timeout_method thread
+          --retries 2 --retry-delay 5
+          --junitxml=pytest.xml
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: test-results-foundry-hosting
+          path: ./python/pytest.xml
+          if-no-files-found: ignore
+
  # Azure Cosmos integration tests
  python-tests-cosmos:
    name: Python Integration Tests - Cosmos
@@ -388,9 +474,9 @@ jobs:
          path: ./python/pytest.xml
          if-no-files-found: ignore

-  # Flaky test trend report (aggregates per-job JUnit XML results)
-  python-flaky-test-report:
-    name: Flaky Test Report
+  # Integration test trend report (aggregates per-job JUnit XML results)
+  python-integration-test-report:
+    name: Integration Test Report
    if: >
      always() &&
      (contains(join(needs.*.result, ','), 'success') ||
@@ -402,6 +488,7 @@ jobs:
        python-tests-misc-integration,
        python-tests-functions,
        python-tests-foundry,
+        python-tests-foundry-hosting,
        python-tests-cosmos,
      ]
    runs-on: ubuntu-latest
@@ -423,36 +510,36 @@ jobs:
        with:
          pattern: test-results-*
          path: test-results/
-      - name: Restore flaky report history cache
+      - name: Restore report history cache
        uses: actions/cache/restore@v4
        with:
-          path: python/flaky-report-history.json
-          key: flaky-report-history-integration-${{ github.run_id }}
+          path: python/integration-report-history.json
+          key: integration-report-history-integration-${{ github.run_id }}
          restore-keys: |
-            flaky-report-history-integration-
+            integration-report-history-integration-
      - name: Generate trend report
        run: >
-          uv run python scripts/flaky_report/aggregate.py
+          uv run python scripts/integration_test_report/aggregate.py
          ../test-results/
-          flaky-report-history.json
-          flaky-test-report.md
+          integration-report-history.json
+          integration-test-report.md
      - name: Post to Job Summary
        if: always()
-        run: cat flaky-test-report.md >> $GITHUB_STEP_SUMMARY
-      - name: Save flaky report history cache
+        run: cat integration-test-report.md >> $GITHUB_STEP_SUMMARY
+      - name: Save report history cache
        if: always()
        uses: actions/cache/save@v4
        with:
-          path: python/flaky-report-history.json
-          key: flaky-report-history-integration-${{ github.run_id }}
+          path: python/integration-report-history.json
+          key: integration-report-history-integration-${{ github.run_id }}
      - name: Upload unified trend report
        if: always()
        uses: actions/upload-artifact@v7
        with:
-          name: flaky-test-report
+          name: integration-test-report
          path: |
-            python/flaky-test-report.md
-            python/flaky-report-history.json
+            python/integration-test-report.md
+            python/integration-report-history.json

  python-integration-tests-check:
    if: always()
@@ -465,6 +552,7 @@ jobs:
        python-tests-misc-integration,
        python-tests-functions,
        python-tests-foundry,
+        python-tests-foundry-hosting,
        python-tests-cosmos
      ]
    steps:
@@ -38,6 +38,7 @@ jobs:
      miscChanged: ${{ steps.filter.outputs.misc }}
      functionsChanged: ${{ steps.filter.outputs.functions }}
      foundryChanged: ${{ steps.filter.outputs.foundry }}
+      foundryHostingChanged: ${{ steps.filter.outputs.foundry_hosting }}
      cosmosChanged: ${{ steps.filter.outputs.cosmos }}
    steps:
      - uses: actions/checkout@v6
@@ -80,6 +81,8 @@ jobs:
              - 'python/packages/foundry/**'
              - 'python/samples/**/providers/foundry/**'
              - 'python/samples/02-agents/embeddings/foundry_embeddings.py'
+            foundry_hosting:
+              - 'python/packages/foundry_hosting/**'
            cosmos:
              - 'python/packages/azure-cosmos/**'
      # run only if 'python' files were changed
@@ -275,6 +278,8 @@ jobs:
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
      ANTHROPIC_CHAT_MODEL: ${{ vars.ANTHROPIC_CHAT_MODEL_ID }}
      LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
+      OLLAMA_MODEL: qwen2.5:1.5b
+      OLLAMA_EMBEDDING_MODEL: nomic-embed-text
    defaults:
      run:
        working-directory: python
@@ -286,6 +291,43 @@ jobs:
        with:
          python-version: ${{ env.UV_PYTHON }}
          os: ${{ runner.os }}
+      - name: Install Ollama
+        run: curl -fsSL https://ollama.com/install.sh | sh
+        working-directory: .
+      - name: Cache Ollama models
+        uses: actions/cache@v4
+        with:
+          path: ~/.ollama/models
+          key: ollama-models-qwen2.5-1.5b-nomic-embed-text-v1
+      - name: Start Ollama and pull models
+        run: |
+          # Stop any Ollama instance auto-started by the install script
+          pkill ollama || true
+          sleep 2
+          ollama serve &
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:11434/api/tags > /dev/null 2>&1; then
+              break
+            fi
+            sleep 1
+          done
+          # Pull models with retry for transient 429 rate limits
+          for model in qwen2.5:1.5b nomic-embed-text; do
+            pulled=false
+            for attempt in 1 2 3; do
+              if ollama pull "$model"; then
+                pulled=true
+                break
+              fi
+              echo "Retry $attempt for $model (waiting 15s)..."
+              sleep 15
+            done
+            if [ "$pulled" != "true" ]; then
+              echo "ERROR: Failed to pull $model after 3 attempts"
+              exit 1
+            fi
+          done
+        working-directory: .
      - name: Start local MCP server
        id: local-mcp
        uses: ./.github/actions/setup-local-mcp-server
@@ -400,7 +442,7 @@ jobs:
          -m integration
          -n logical --dist worksteal
          -x
-          --timeout=360 --session-timeout=900 --timeout_method thread
+          --timeout=480 --session-timeout=900 --timeout_method thread
          --retries 2 --retry-delay 5
          --junitxml=pytest.xml
        working-directory: ./python
@@ -488,6 +530,67 @@ jobs:
          path: ./python/pytest.xml
          if-no-files-found: ignore

+  # Foundry Hosting integration tests
+  python-tests-foundry-hosting:
+    name: Python Tests - Foundry Hosting Integration
+    needs: paths-filter
+    if: >
+      github.event_name != 'pull_request' &&
+      needs.paths-filter.outputs.pythonChanges == 'true' &&
+      (github.event_name != 'merge_group' ||
+       needs.paths-filter.outputs.foundryHostingChanged == 'true' ||
+       needs.paths-filter.outputs.coreChanged == 'true')
+    runs-on: ubuntu-latest
+    environment: integration
+    env:
+      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
+      FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL }}
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Azure CLI Login
+        if: github.event_name != 'pull_request'
+        uses: azure/login@v2
+        with:
+          client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+      - name: Test with pytest (Foundry Hosting integration)
+        timeout-minutes: 15
+        run: >
+          uv run pytest --import-mode=importlib
+          packages/foundry_hosting/tests
+          -m integration
+          -n logical --dist worksteal
+          --timeout=120 --session-timeout=900 --timeout_method thread
+          --retries 2 --retry-delay 5
+          --junitxml=pytest.xml
+        working-directory: ./python
+      - name: Surface failing tests
+        if: always()
+        uses: pmeier/pytest-results-action@v0.7.2
+        with:
+          path: ./python/pytest.xml
+          summary: true
+          display-options: fEX
+          fail-on-empty: false
+          title: Foundry Hosting integration test results
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: test-results-foundry-hosting
+          path: ./python/pytest.xml
+          if-no-files-found: ignore
+
  # TODO: Add python-tests-lab

  # Azure Cosmos integration tests
@@ -555,9 +658,9 @@ jobs:
          path: ./python/pytest.xml
          if-no-files-found: ignore

-  # Flaky test trend report (aggregates per-job JUnit XML results)
-  python-flaky-test-report:
-    name: Flaky Test Report
+  # Integration test trend report (aggregates per-job JUnit XML results)
+  python-integration-test-report:
+    name: Integration Test Report
    if: >
      always() &&
      (contains(join(needs.*.result, ','), 'success') ||
@@ -569,6 +672,7 @@ jobs:
        python-tests-misc-integration,
        python-tests-functions,
        python-tests-foundry,
+        python-tests-foundry-hosting,
        python-tests-cosmos,
      ]
    runs-on: ubuntu-latest
@@ -587,36 +691,36 @@ jobs:
        with:
          pattern: test-results-*
          path: test-results/
-      - name: Restore flaky report history cache
+      - name: Restore report history cache
        uses: actions/cache/restore@v4
        with:
-          path: python/flaky-report-history.json
-          key: flaky-report-history-merge-${{ github.run_id }}
+          path: python/integration-report-history.json
+          key: integration-report-history-merge-${{ github.run_id }}
          restore-keys: |
-            flaky-report-history-merge-
+            integration-report-history-merge-
      - name: Generate trend report
        run: >
-          uv run python scripts/flaky_report/aggregate.py
+          uv run python scripts/integration_test_report/aggregate.py
          ../test-results/
-          flaky-report-history.json
-          flaky-test-report.md
+          integration-report-history.json
+          integration-test-report.md
      - name: Post to Job Summary
        if: always()
-        run: cat flaky-test-report.md >> $GITHUB_STEP_SUMMARY
-      - name: Save flaky report history cache
+        run: cat integration-test-report.md >> $GITHUB_STEP_SUMMARY
+      - name: Save report history cache
        if: always()
        uses: actions/cache/save@v4
        with:
-          path: python/flaky-report-history.json
-          key: flaky-report-history-merge-${{ github.run_id }}
+          path: python/integration-report-history.json
+          key: integration-report-history-merge-${{ github.run_id }}
      - name: Upload unified trend report
        if: always()
        uses: actions/upload-artifact@v7
        with:
-          name: flaky-test-report
+          name: integration-test-report
          path: |
-            python/flaky-test-report.md
-            python/flaky-report-history.json
+            python/integration-test-report.md
+            python/integration-report-history.json

  python-integration-tests-check:
    if: always()
@@ -629,6 +733,7 @@ jobs:
        python-tests-misc-integration,
        python-tests-functions,
        python-tests-foundry,
+        python-tests-foundry-hosting,
        python-tests-cosmos,
      ]
    steps:
@@ -242,3 +242,7 @@ python/dotnet-ref
 # Generated filtered solution files (created by eng/scripts/New-FilteredSolution.ps1)
 dotnet/filtered-*.slnx
 **/*.lscache
+
+# Local tool state
+.omc/
+.omx/
@@ -22,9 +22,9 @@
    <PackageVersion Include="Aspire.Microsoft.Azure.Cosmos" Version="$(AspireAppHostSdkVersion)" />
    <PackageVersion Include="CommunityToolkit.Aspire.OllamaSharp" Version="13.0.0" />
    <!-- Azure.* -->
-    <PackageVersion Include="Azure.AI.AgentServer.Core" Version="1.0.0-beta.22" />
-    <PackageVersion Include="Azure.AI.AgentServer.Invocations" Version="1.0.0-beta.1" />
-    <PackageVersion Include="Azure.AI.AgentServer.Responses" Version="1.0.0-beta.3" />
+    <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.AI.Agents.Persistent" Version="1.2.0-beta.10" />
    <PackageVersion Include="Azure.AI.OpenAI" Version="2.9.0-beta.1" />
@@ -56,15 +56,15 @@
    <PackageVersion Include="System.Threading.Tasks.Extensions" Version="4.6.3" />
    <PackageVersion Include="System.Net.Security" Version="4.3.2" />
    <!-- OpenTelemetry -->
-    <PackageVersion Include="OpenTelemetry" Version="1.15.0" />
-    <PackageVersion Include="OpenTelemetry.Api" Version="1.15.0" />
-    <PackageVersion Include="OpenTelemetry.Exporter.Console" Version="1.15.0" />
-    <PackageVersion Include="OpenTelemetry.Exporter.InMemory" Version="1.15.0" />
-    <PackageVersion Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.15.0" />
-    <PackageVersion Include="OpenTelemetry.Extensions.Hosting" Version="1.14.0" />
-    <PackageVersion Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.14.0" />
-    <PackageVersion Include="OpenTelemetry.Instrumentation.Http" Version="1.14.0" />
-    <PackageVersion Include="OpenTelemetry.Instrumentation.Runtime" Version="1.14.0" />
+    <PackageVersion Include="OpenTelemetry" Version="1.15.3" />
+    <PackageVersion Include="OpenTelemetry.Api" Version="1.15.3" />
+    <PackageVersion Include="OpenTelemetry.Exporter.Console" Version="1.15.3" />
+    <PackageVersion Include="OpenTelemetry.Exporter.InMemory" Version="1.15.3" />
+    <PackageVersion Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.15.3" />
+    <PackageVersion Include="OpenTelemetry.Extensions.Hosting" Version="1.15.3" />
+    <PackageVersion Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.15.2" />
+    <PackageVersion Include="OpenTelemetry.Instrumentation.Http" Version="1.15.1" />
+    <PackageVersion Include="OpenTelemetry.Instrumentation.Runtime" Version="1.15.1" />
    <!-- Microsoft.AspNetCore.* -->
    <PackageVersion Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.0" />
    <PackageVersion Include="Microsoft.AspNetCore.Authentication.OpenIdConnect" Version="10.0.0" />
@@ -86,6 +86,7 @@
    <PackageVersion Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.1" />
    <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.1" />
    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.6" />
+    <PackageVersion Include="Microsoft.Extensions.FileSystemGlobbing" Version="10.0.6" />
    <PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.1" />
    <PackageVersion Include="Microsoft.Extensions.Http.Resilience" Version="10.0.0" />
    <PackageVersion Include="Microsoft.Extensions.Logging" Version="10.0.1" />
@@ -135,6 +136,8 @@
    <PackageVersion Include="Microsoft.Azure.Functions.Worker.Sdk" Version="2.0.7" />
    <!-- Redis -->
    <PackageVersion Include="StackExchange.Redis" Version="2.10.1" />
+    <!-- Console UX -->
+    <PackageVersion Include="Spectre.Console" Version="0.49.1" />
    <!-- Test -->
    <PackageVersion Include="FluentAssertions" Version="8.8.0" />
    <PackageVersion Include="Microsoft.AspNetCore.TestHost" Condition="'$(TargetFramework)' == 'net8.0'" Version="8.0.22" />
@@ -188,4 +191,4 @@
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
  </ItemGroup>
-</Project>
+</Project>
@@ -117,6 +117,13 @@
    <Project Path="samples/02-agents/AgentSkills/Agent_Step04_MixedSkills/Agent_Step04_MixedSkills.csproj" />
    <Project Path="samples/02-agents/AgentSkills/Agent_Step05_SkillsWithDI/Agent_Step05_SkillsWithDI.csproj" />
  </Folder>
+  <Folder Name="/Samples/02-agents/Harness/">
+    <File Path="samples/02-agents/Harness/README.md" />
+    <Project Path="samples/02-agents/Harness/Harness_Shared_Console/Harness_Shared_Console.csproj" />
+    <Project Path="samples/02-agents/Harness/Harness_Step01_Research/Harness_Step01_Research.csproj" />
+    <Project Path="samples/02-agents/Harness/Harness_Step02_Research_WithSubAgents/Harness_Step02_Research_WithSubAgents.csproj" />
+    <Project Path="samples/02-agents/Harness/Harness_Step03_DataProcessing/Harness_Step03_DataProcessing.csproj" />
+  </Folder>
  <Folder Name="/Samples/02-agents/AGUI/Step05_StateManagement/">
    <Project Path="samples/02-agents/AGUI/Step05_StateManagement/Client/Client.csproj" />
    <Project Path="samples/02-agents/AGUI/Step05_StateManagement/Server/Server.csproj" />
@@ -160,12 +167,13 @@
    <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" />
  </Folder>
  <Folder Name="/Samples/02-agents/Evaluation/">
-    <Project Path="samples/02-agents/Evaluation/Evaluation_SimpleEval/Evaluation_SimpleEval.csproj" />
    <Project Path="samples/02-agents/Evaluation/Evaluation_CustomEvals/Evaluation_CustomEvals.csproj" />
    <Project Path="samples/02-agents/Evaluation/Evaluation_ExpectedOutputs/Evaluation_ExpectedOutputs.csproj" />
    <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/AgentWithMemory/">
    <File Path="samples/02-agents/AgentWithMemory/README.md" />
@@ -225,6 +233,7 @@
    <Project Path="samples/03-workflows/Declarative/HostedWorkflow/HostedWorkflow.csproj" />
    <Project Path="samples/03-workflows/Declarative/InputArguments/InputArguments.csproj" />
    <Project Path="samples/03-workflows/Declarative/InvokeFunctionTool/InvokeFunctionTool.csproj" />
+    <Project Path="samples/03-workflows/Declarative/InvokeHttpRequest/InvokeHttpRequest.csproj" />
    <Project Path="samples/03-workflows/Declarative/InvokeMcpTool/InvokeMcpTool.csproj" />
    <Project Path="samples/03-workflows/Declarative/Marketing/Marketing.csproj" />
    <Project Path="samples/03-workflows/Declarative/StudentTeacher/StudentTeacher.csproj" />
@@ -346,17 +355,17 @@
    <File Path="samples/02-agents/A2A/README.md" />
    <Project Path="samples/02-agents/A2A/A2AAgent_AsFunctionTools/A2AAgent_AsFunctionTools.csproj" />
    <Project Path="samples/02-agents/A2A/A2AAgent_PollingForTaskCompletion/A2AAgent_PollingForTaskCompletion.csproj" />
-    <Project Path="samples/02-agents/A2A/A2AAgent_StreamReconnection/A2AAgent_StreamReconnection.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 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" />
  </Folder>
  <Folder Name="/Samples/05-end-to-end/Evaluation/">
+    <Project Path="samples/05-end-to-end/Evaluation/Evaluation_ConversationSplits/Evaluation_ConversationSplits.csproj" />
    <Project Path="samples/05-end-to-end/Evaluation/Evaluation_FoundryQuality/Evaluation_FoundryQuality.csproj" />
    <Project Path="samples/05-end-to-end/Evaluation/Evaluation_MixedProviders/Evaluation_MixedProviders.csproj" />
-    <Project Path="samples/05-end-to-end/Evaluation/Evaluation_ConversationSplits/Evaluation_ConversationSplits.csproj" />
  </Folder>
  <Folder Name="/Samples/05-end-to-end/A2AClientServer/">
    <File Path="samples/05-end-to-end/A2AClientServer/README.md" />
@@ -542,8 +551,8 @@
    <Project Path="src/Microsoft.Agents.AI.Declarative/Microsoft.Agents.AI.Declarative.csproj" />
    <Project Path="src/Microsoft.Agents.AI.DevUI/Microsoft.Agents.AI.DevUI.csproj" />
    <Project Path="src/Microsoft.Agents.AI.DurableTask/Microsoft.Agents.AI.DurableTask.csproj" />
-    <Project Path="src/Microsoft.Agents.AI.Foundry/Microsoft.Agents.AI.Foundry.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Foundry.Hosting/Microsoft.Agents.AI.Foundry.Hosting.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Foundry/Microsoft.Agents.AI.Foundry.csproj" />
    <Project Path="src/Microsoft.Agents.AI.GitHub.Copilot/Microsoft.Agents.AI.GitHub.Copilot.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Hosting.A2A.AspNetCore/Microsoft.Agents.AI.Hosting.A2A.AspNetCore.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Hosting.A2A/Microsoft.Agents.AI.Hosting.A2A.csproj" />
@@ -590,6 +599,7 @@
    <Project Path="tests/Microsoft.Agents.AI.DevUI.UnitTests/Microsoft.Agents.AI.DevUI.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.DurableTask.UnitTests/Microsoft.Agents.AI.DurableTask.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Foundry.UnitTests/Microsoft.Agents.AI.Foundry.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Foundry.Hosting.UnitTests/Microsoft.Agents.AI.Foundry.Hosting.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Hosting.A2A.UnitTests/Microsoft.Agents.AI.Hosting.A2A.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests.csproj" />
@@ -1,14 +1,14 @@
 <Project>
  <PropertyGroup>
    <!-- Central version prefix - applies to all nuget packages. -->
-    <VersionPrefix>1.2.0</VersionPrefix>
+    <VersionPrefix>1.3.0</VersionPrefix>
    <RCNumber>1</RCNumber>
-    <DateSuffix>260421</DateSuffix>
+    <DateSuffix>260423</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.2.0</GitTag>
+    <GitTag>1.3.0</GitTag>

    <Configurations>Debug;Release;Publish</Configurations>
    <IsPackable>true</IsPackable>
@@ -5,16 +5,16 @@
 // This is provided for demonstration purposes only.

 using System.Diagnostics;
+using System.Text.Json;
 using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;

 /// <summary>
 /// Executes file-based skill scripts as local subprocesses.
 /// </summary>
 /// <remarks>
-/// This runner uses the script's absolute path, converts the arguments
-/// to CLI flags, and returns captured output. It is intended for
-/// demonstration purposes only.
+/// This runner uses the script's absolute path and converts the arguments
+/// to CLI arguments. When the LLM sends a JSON array, each element is used
+/// as a positional argument. It is intended for demonstration purposes only.
 /// </remarks>
 internal static class SubprocessScriptRunner
 {
@@ -24,7 +24,8 @@ internal static class SubprocessScriptRunner
    public static async Task<object?> RunAsync(
        AgentFileSkill skill,
        AgentFileSkillScript script,
-        AIFunctionArguments arguments,
+        JsonElement? arguments,
+        IServiceProvider? serviceProvider,
        CancellationToken cancellationToken)
    {
        if (!File.Exists(script.FullPath))
@@ -61,24 +62,27 @@ internal static class SubprocessScriptRunner
            startInfo.FileName = script.FullPath;
        }

-        if (arguments is not null)
+        if (arguments is { ValueKind: JsonValueKind.Array } json)
        {
-            foreach (var (key, value) in arguments)
+            // Positional CLI arguments
+            foreach (var element in json.EnumerateArray())
            {
-                if (value is bool boolValue)
+                if (element.ValueKind != JsonValueKind.String)
                {
-                    if (boolValue)
-                    {
-                        startInfo.ArgumentList.Add(NormalizeKey(key));
-                    }
-                }
-                else if (value is not null)
-                {
-                    startInfo.ArgumentList.Add(NormalizeKey(key));
-                    startInfo.ArgumentList.Add(value.ToString()!);
+                    throw new InvalidOperationException(
+                        $"File-based skill scripts only accept string CLI arguments but received a JSON element of kind '{element.ValueKind}'. " +
+                        "All array elements must be JSON strings.");
                }
+
+                startInfo.ArgumentList.Add(element.GetString()!);
            }
        }
+        else if (arguments is not null && arguments.Value.ValueKind != JsonValueKind.Null && arguments.Value.ValueKind != JsonValueKind.Undefined)
+        {
+            throw new InvalidOperationException(
+                $"Expected a JSON array of CLI arguments but received {arguments.Value.ValueKind}. " +
+                "File-based skill scripts expect positional arguments as a JSON array of strings.");
+        }

        Process? process = null;
        try
@@ -128,10 +132,4 @@ internal static class SubprocessScriptRunner
            process?.Dispose();
        }
    }
-
-    /// <summary>
-    /// Normalizes a parameter key to a consistent --flag format.
-    /// Models may return keys with or without leading dashes (e.g., "value" vs "--value").
-    /// </summary>
-    private static string NormalizeKey(string key) => "--" + key.TrimStart('-');
 }
@@ -0,0 +1,17 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <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" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,148 @@
+// 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.
+
+using System.ClientModel;
+using System.ClientModel.Primitives;
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+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.
+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.";
+
+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";
+
+// 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());
+
+await Main(projectClient, model, endpoint);
+// await CombineToolboxes(projectClient, model, endpoint);
+
+// ---------------------------------------------------------------------------
+// Main: single toolbox
+// ---------------------------------------------------------------------------
+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)
+{
+    // Toolboxes are normally configured in the Foundry portal or a deployment
+    // script, not the application itself. This helper exists so the sample can
+    // be run end-to-end without first setting a toolbox up by hand.
+
+    // 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 toolboxClient = adminClient.GetAgentToolboxes();
+
+    // Delete existing toolbox if present (ignore 404).
+    try
+    {
+        await toolboxClient.DeleteToolboxAsync(name);
+        Console.WriteLine($"Deleted existing toolbox '{name}'");
+    }
+    catch (ClientResultException ex) when (ex.Status == 404)
+    {
+        // Toolbox does not exist — nothing to delete.
+    }
+
+    // Create a fresh version with a single MCP tool.
+    ProjectsAgentTool mcpTool = ProjectsAgentTool.AsProjectTool(ResponseTool.CreateMcpTool(
+        serverLabel: "api-specs",
+        serverUri: new Uri("https://gitmcp.io/Azure/azure-rest-api-specs"),
+        toolCallApprovalPolicy: new McpToolCallApprovalPolicy(GlobalMcpToolCallApprovalPolicy.NeverRequireApproval)));
+
+    var created = (await toolboxClient.CreateToolboxVersionAsync(
+        name: name,
+        tools: [mcpTool],
+        description: "Sample toolbox with an MCP tool — created by Agent_Step25 sample.")).Value;
+
+    Console.WriteLine($"Created toolbox '{created.Name}' v{created.Version} ({created.Tools.Count} tool(s))");
+}
+
+// ---------------------------------------------------------------------------
+// Pipeline policy that adds the Foundry-Features header for toolbox CRUD
+// ---------------------------------------------------------------------------
+internal sealed class FoundryFeaturesPolicy(string feature) : PipelinePolicy
+{
+    private const string FeatureHeader = "Foundry-Features";
+
+    public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+    {
+        message.Request.Headers.Add(FeatureHeader, feature);
+        ProcessNext(message, pipeline, currentIndex);
+    }
+
+    public override ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+    {
+        message.Request.Headers.Add(FeatureHeader, feature);
+        return ProcessNextAsync(message, pipeline, currentIndex);
+    }
+}
@@ -0,0 +1,46 @@
+# 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
+```
@@ -0,0 +1,28 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+
+namespace Harness.Shared.Console.Commands;
+
+/// <summary>
+/// Handles a console command (e.g., /todos, /mode). Command handlers are checked
+/// in order before user input is sent to the agent. The first handler that
+/// accepts the input prevents further handlers from being checked.
+/// </summary>
+public interface ICommandHandler
+{
+    /// <summary>
+    /// Gets the help text for this command, displayed in the console header.
+    /// Returns <see langword="null"/> if the command is not currently available.
+    /// </summary>
+    /// <returns>Help text like <c>"/todos (show todo list)"</c>, or <see langword="null"/>.</returns>
+    string? GetHelpText();
+
+    /// <summary>
+    /// Attempts to handle the given user input.
+    /// </summary>
+    /// <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);
+}
@@ -0,0 +1,69 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+
+namespace Harness.Shared.Console.Commands;
+
+/// <summary>
+/// Handles the <c>/mode</c> command to display or switch the current agent mode.
+/// </summary>
+internal sealed class ModeCommandHandler : ICommandHandler
+{
+    private readonly AgentModeProvider? _modeProvider;
+    private readonly IReadOnlyDictionary<string, ConsoleColor>? _modeColors;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ModeCommandHandler"/> class.
+    /// </summary>
+    /// <param name="modeProvider">The mode provider, or <see langword="null"/> if not available.</param>
+    /// <param name="modeColors">Optional mapping of mode names to console colors.</param>
+    public ModeCommandHandler(AgentModeProvider? modeProvider, IReadOnlyDictionary<string, ConsoleColor>? modeColors = null)
+    {
+        this._modeProvider = modeProvider;
+        this._modeColors = modeColors;
+    }
+
+    /// <inheritdoc/>
+    public string? GetHelpText() => this._modeProvider is not null ? "/mode [plan|execute] (show or switch mode)" : null;
+
+    /// <inheritdoc/>
+    public bool TryHandle(string input, AgentSession session)
+    {
+        if (!input.StartsWith("/mode ", StringComparison.OrdinalIgnoreCase) && !input.Equals("/mode", StringComparison.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        if (this._modeProvider is null)
+        {
+            System.Console.WriteLine("AgentModeProvider is not available.");
+            return true;
+        }
+
+        string[] parts = input.Split(' ', 2, StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+        if (parts.Length < 2)
+        {
+            string current = this._modeProvider.GetMode(session);
+            System.Console.WriteLine($"\n  Current mode: {current}\n");
+            return true;
+        }
+
+        string newMode = parts[1];
+
+        try
+        {
+            this._modeProvider.SetMode(session, newMode);
+            System.Console.ForegroundColor = ConsoleWriter.GetModeColor(newMode, this._modeColors);
+            System.Console.WriteLine($"\n  Switched to {newMode} mode.\n");
+            System.Console.ResetColor();
+        }
+        catch (ArgumentException ex)
+        {
+            System.Console.ForegroundColor = ConsoleColor.Red;
+            System.Console.WriteLine($"\n  {ex}\n");
+            System.Console.ResetColor();
+        }
+
+        return true;
+    }
+}
@@ -0,0 +1,66 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+
+namespace Harness.Shared.Console.Commands;
+
+/// <summary>
+/// Handles the <c>/todos</c> command to display the current todo list.
+/// </summary>
+internal sealed class TodoCommandHandler : ICommandHandler
+{
+    private readonly TodoProvider? _todoProvider;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="TodoCommandHandler"/> class.
+    /// </summary>
+    /// <param name="todoProvider">The todo provider, or <see langword="null"/> if not available.</param>
+    public TodoCommandHandler(TodoProvider? todoProvider)
+    {
+        this._todoProvider = todoProvider;
+    }
+
+    /// <inheritdoc/>
+    public string? GetHelpText() => this._todoProvider is not null ? "/todos (show todo list)" : null;
+
+    /// <inheritdoc/>
+    public bool TryHandle(string input, AgentSession session)
+    {
+        if (!input.Equals("/todos", StringComparison.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        if (this._todoProvider is null)
+        {
+            System.Console.WriteLine("TodoProvider is not available.");
+            return true;
+        }
+
+        var todos = this._todoProvider.GetAllTodos(session);
+        if (todos.Count == 0)
+        {
+            System.Console.WriteLine("\n  No todos yet.\n");
+            return true;
+        }
+
+        System.Console.WriteLine();
+        System.Console.WriteLine("  ── Todo List ──");
+        foreach (var item in todos)
+        {
+            string status = item.IsComplete ? "✓" : "○";
+            System.Console.ForegroundColor = item.IsComplete ? ConsoleColor.DarkGray : ConsoleColor.White;
+            System.Console.Write($"  [{status}] #{item.Id} {item.Title}");
+            if (!string.IsNullOrWhiteSpace(item.Description))
+            {
+                System.Console.Write($" — {item.Description}");
+            }
+
+            System.Console.WriteLine();
+        }
+
+        System.Console.ResetColor();
+        System.Console.WriteLine();
+        return true;
+    }
+}
@@ -0,0 +1,278 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Spectre.Console;
+
+namespace Harness.Shared.Console;
+
+/// <summary>
+/// Centralizes all console output and spinner management for the harness console.
+/// Observers write through this class so the spinner is automatically paused before output.
+/// </summary>
+public sealed class ConsoleWriter : IDisposable
+{
+    private readonly Spinner _spinner = new();
+    private readonly IReadOnlyDictionary<string, ConsoleColor>? _modeColors;
+
+    private bool _lastWasText;
+    private bool _hasReceivedAnyText;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ConsoleWriter"/> class.
+    /// </summary>
+    /// <param name="modeColors">Optional mapping of mode names to console colors.</param>
+    public ConsoleWriter(IReadOnlyDictionary<string, ConsoleColor>? modeColors = null)
+    {
+        this._modeColors = modeColors;
+    }
+
+    /// <summary>
+    /// Gets or sets the current agent mode (e.g., "plan", "execute").
+    /// Used to determine the console color for mode-prefixed output.
+    /// </summary>
+    public string? CurrentMode { get; set; }
+
+    /// <summary>
+    /// Writes the agent response header (e.g., "[plan] Agent: ") and starts the spinner.
+    /// </summary>
+    public void WriteResponseHeader()
+    {
+        if (this.CurrentMode is not null)
+        {
+            System.Console.ForegroundColor = GetModeColor(this.CurrentMode, this._modeColors);
+            System.Console.Write($"\n[{this.CurrentMode}] Agent: ");
+        }
+        else
+        {
+            System.Console.Write("\nAgent: ");
+        }
+
+        this._lastWasText = true;
+        this._hasReceivedAnyText = false;
+        this._spinner.Start();
+    }
+
+    /// <summary>
+    /// Writes informational output with automatic prefix spacing, without a trailing newline.
+    /// Use when continuation content will be appended on the same line.
+    /// </summary>
+    /// <param name="text">The informational text to write (without leading newline/indent — added automatically).</param>
+    /// <param name="color">Optional console color for the text.</param>
+    public async Task WriteInfoAsync(string text, ConsoleColor? color = null)
+    {
+        await this.WriteInfoCoreAsync(text, color, newLine: false);
+    }
+
+    /// <summary>
+    /// Writes informational output with automatic prefix spacing, followed by a newline.
+    /// </summary>
+    /// <param name="text">The informational text to write (without leading newline/indent — added automatically).</param>
+    /// <param name="color">Optional console color for the text.</param>
+    public async Task WriteInfoLineAsync(string text, ConsoleColor? color = null)
+    {
+        await this.WriteInfoCoreAsync(text, color, newLine: true);
+    }
+
+    private async Task WriteInfoCoreAsync(string text, ConsoleColor? color, bool newLine)
+    {
+        await this._spinner.StopAsync();
+
+        string prefix = this._lastWasText ? "\n\n  " : "  ";
+        this._lastWasText = false;
+
+        System.Console.ForegroundColor = color ?? GetModeColor(this.CurrentMode, this._modeColors);
+
+        if (newLine)
+        {
+            System.Console.WriteLine(prefix + text);
+        }
+        else
+        {
+            System.Console.Write(prefix + text);
+        }
+
+        System.Console.ForegroundColor = GetModeColor(this.CurrentMode, this._modeColors);
+
+        this._spinner.Start();
+    }
+
+    /// <summary>
+    /// Writes text output from the agent, managing line break state.
+    /// Ensures a newline is written before the first text output.
+    /// </summary>
+    /// <param name="text">The text to write.</param>
+    /// <param name="color">Optional console color override for this text.</param>
+    public async Task WriteTextAsync(string text, ConsoleColor? color = null)
+    {
+        await this._spinner.StopAsync();
+
+        if (!this._lastWasText)
+        {
+            System.Console.Write("\n");
+            this._lastWasText = true;
+        }
+
+        this._hasReceivedAnyText = true;
+
+        if (color.HasValue)
+        {
+            System.Console.ForegroundColor = color.Value;
+        }
+
+        System.Console.Write(text);
+
+        if (color.HasValue)
+        {
+            System.Console.ForegroundColor = GetModeColor(this.CurrentMode, this._modeColors);
+        }
+
+        this._spinner.Start();
+    }
+
+    /// <summary>
+    /// Reads a line of input from the console, pausing the spinner while waiting for input.
+    /// Optionally displays a prompt before reading. The prompt is rendered between
+    /// two horizontal rules for visual clarity.
+    /// </summary>
+    /// <param name="prompt">Optional prompt text to display before reading input.</param>
+    /// <param name="promptColor">Optional console color for the prompt text.</param>
+    /// <returns>The line read from the console, or <c>null</c> if no input is available.</returns>
+    public async Task<string?> ReadLineAsync(string? prompt = null, ConsoleColor? promptColor = null)
+    {
+        await this._spinner.StopAsync();
+
+        if (prompt is not null)
+        {
+            System.Console.WriteLine();
+            AnsiConsole.Write(this.CreateModeRule());
+
+            if (promptColor.HasValue)
+            {
+                System.Console.ForegroundColor = promptColor.Value;
+            }
+
+            System.Console.Write($"  {prompt}");
+
+            if (promptColor.HasValue)
+            {
+                System.Console.ForegroundColor = GetModeColor(this.CurrentMode, this._modeColors);
+            }
+        }
+
+        string? input = System.Console.ReadLine();
+
+        if (prompt is not null)
+        {
+            AnsiConsole.Write(this.CreateModeRule());
+        }
+
+        this._lastWasText = false;
+        return input;
+    }
+
+    /// <summary>
+    /// Presents a selection prompt with the given choices, plus an option to type a custom response.
+    /// Uses Spectre.Console <see cref="SelectionPrompt{T}"/> for interactive arrow-key selection.
+    /// </summary>
+    /// <param name="title">The title/question displayed above the selection list.</param>
+    /// <param name="choices">The list of choices to present.</param>
+    /// <returns>The selected choice text, or the custom-typed response.</returns>
+    public async Task<string> ReadSelectionAsync(string title, IList<string> choices)
+    {
+        await this._spinner.StopAsync();
+
+        AnsiConsole.Write(this.CreateModeRule());
+
+        const string FreeformOption = "✏️  Type a custom response...";
+        var allChoices = choices.Concat([FreeformOption]).ToList();
+
+        var prompt = new SelectionPrompt<string>()
+            .Title($"  [bold]{Markup.Escape(title)}[/]")
+            .PageSize(10)
+            .AddChoices(allChoices);
+
+        string selection = AnsiConsole.Prompt(prompt);
+
+        if (selection == FreeformOption)
+        {
+            var textPrompt = new TextPrompt<string>("  [grey]Response:[/]");
+            selection = AnsiConsole.Prompt(textPrompt);
+        }
+
+        AnsiConsole.MarkupLine($"  [dim]→ {Markup.Escape(selection)}[/]");
+        AnsiConsole.Write(this.CreateModeRule());
+
+        this._lastWasText = false;
+        return selection;
+    }
+
+    /// <summary>
+    /// Writes the stream-complete footer (handles "no text response" fallback, resets color).
+    /// </summary>
+    public async Task WriteStreamFooterAsync(bool hasFollowUpMessages)
+    {
+        await this._spinner.StopAsync();
+
+        if (!this._hasReceivedAnyText && !hasFollowUpMessages)
+        {
+            System.Console.ForegroundColor = ConsoleColor.DarkYellow;
+            System.Console.Write("\n  (no text response from agent)");
+        }
+
+        System.Console.ResetColor();
+        System.Console.WriteLine();
+    }
+
+    /// <inheritdoc/>
+    public void Dispose()
+    {
+        this._spinner.Dispose();
+    }
+
+    /// <summary>
+    /// Gets the console color associated with a mode name, using the provided color map.
+    /// </summary>
+    internal static ConsoleColor GetModeColor(string? mode, IReadOnlyDictionary<string, ConsoleColor>? modeColors = null)
+    {
+        if (mode is null)
+        {
+            return ConsoleColor.Gray;
+        }
+
+        if (modeColors is not null && modeColors.TryGetValue(mode, out var color))
+        {
+            return color;
+        }
+
+        return ConsoleColor.Gray;
+    }
+
+    /// <summary>
+    /// Creates a <see cref="Rule"/> styled with the current mode color.
+    /// </summary>
+    internal Rule CreateModeRule()
+    {
+        var spectreColor = ToSpectreColor(GetModeColor(this.CurrentMode, this._modeColors));
+        return new Rule().RuleStyle(new Style(spectreColor));
+    }
+
+    internal static Color ToSpectreColor(ConsoleColor consoleColor) => consoleColor switch
+    {
+        ConsoleColor.Black => Color.Black,
+        ConsoleColor.DarkBlue => Color.Blue,
+        ConsoleColor.DarkGreen => Color.Green,
+        ConsoleColor.DarkCyan => Color.Teal,
+        ConsoleColor.DarkRed => Color.Red,
+        ConsoleColor.DarkMagenta => Color.Purple,
+        ConsoleColor.DarkYellow => Color.Olive,
+        ConsoleColor.Gray => Color.Silver,
+        ConsoleColor.DarkGray => Color.Grey,
+        ConsoleColor.Blue => Color.Blue1,
+        ConsoleColor.Green => Color.Green1,
+        ConsoleColor.Cyan => Color.Aqua,
+        ConsoleColor.Red => Color.Red1,
+        ConsoleColor.Magenta => Color.Fuchsia,
+        ConsoleColor.Yellow => Color.Yellow,
+        ConsoleColor.White => Color.White,
+        _ => Color.Silver,
+    };
+}
@@ -0,0 +1,214 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Harness.Shared.Console.Commands;
+using Harness.Shared.Console.Observers;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console;
+
+/// <summary>
+/// Provides a reusable interactive console loop for running an <see cref="AIAgent"/>
+/// with streaming output, extensible observers, and mode-aware interaction strategies.
+/// </summary>
+public static class HarnessConsole
+{
+    /// <summary>
+    /// Runs an interactive console session with the specified agent.
+    /// Supports streaming output, tool call display, spinner animation,
+    /// optional planning UX with structured output, and the <c>/todos</c> command.
+    /// </summary>
+    /// <param name="agent">The agent to interact with.</param>
+    /// <param name="title">The title displayed in the console header.</param>
+    /// <param name="userPrompt">A short prompt to the user, displayed below the title.</param>
+    /// <param name="options">Optional configuration options for the console session.</param>
+    public static async Task RunAgentAsync(AIAgent agent, string title, string userPrompt, HarnessConsoleOptions? options = null)
+    {
+        options ??= new();
+
+        if (options.EnablePlanningUx
+            && (string.IsNullOrWhiteSpace(options.PlanningModeName) || string.IsNullOrWhiteSpace(options.ExecutionModeName)))
+        {
+            throw new ArgumentException(
+                "When EnablePlanningUx is true, both PlanningModeName and ExecutionModeName must be configured.",
+                nameof(options));
+        }
+
+        System.Console.WriteLine($"=== {title} ===");
+        System.Console.WriteLine(userPrompt);
+
+        var todoProvider = agent.GetService<TodoProvider>();
+        var modeProvider = agent.GetService<AgentModeProvider>();
+
+        // Build command handlers.
+        var commandHandlers = new List<ICommandHandler>
+        {
+            new TodoCommandHandler(todoProvider),
+            new ModeCommandHandler(modeProvider, options.ModeColors),
+        };
+
+        var commands = commandHandlers
+            .Select(h => h.GetHelpText())
+            .Where(t => t is not null)
+            .Append("exit (quit)");
+
+        System.Console.WriteLine($"Commands: {string.Join(", ", commands)}");
+        System.Console.WriteLine();
+
+        AgentSession session = await agent.CreateSessionAsync();
+        using var writer = new ConsoleWriter(options.ModeColors);
+        writer.CurrentMode = modeProvider?.GetMode(session);
+
+        string prompt = BuildUserPrompt(modeProvider, session);
+        string? userInput = await writer.ReadLineAsync(prompt);
+
+        // Main loop to run a command or agent and get the next user command/input.
+        while (!string.IsNullOrWhiteSpace(userInput) && !userInput.Equals("exit", StringComparison.OrdinalIgnoreCase))
+        {
+            // Check command handlers first — first one to handle wins.
+            bool handled = false;
+            foreach (var handler in commandHandlers)
+            {
+                if (handler.TryHandle(userInput, session))
+                {
+                    handled = true;
+                    break;
+                }
+            }
+
+            if (!handled)
+            {
+                await RunAgentTurnAsync(agent, session, modeProvider, options, writer, userInput);
+            }
+
+            writer.CurrentMode = modeProvider?.GetMode(session);
+            prompt = BuildUserPrompt(modeProvider, session);
+            userInput = await writer.ReadLineAsync(prompt);
+        }
+
+        System.Console.ResetColor();
+        System.Console.WriteLine("Goodbye!");
+    }
+
+    /// <summary>
+    /// Runs one or more agent invocations for a single user turn, using the current
+    /// observers. Re-invokes automatically for tool approvals and mode-driven follow-ups
+    /// (e.g., planning clarification loops).
+    /// </summary>
+    private static async Task RunAgentTurnAsync(
+        AIAgent agent,
+        AgentSession session,
+        AgentModeProvider? modeProvider,
+        HarnessConsoleOptions options,
+        ConsoleWriter writer,
+        string userInput)
+    {
+        IList<ChatMessage>? nextMessages = [new ChatMessage(ChatRole.User, userInput)];
+
+        while (nextMessages is not null)
+        {
+            // Build observers for this invocation (may change between iterations due to mode changes).
+            var observers = CreateObservers(options, modeProvider, session);
+
+            // Build run options — observers may inject ResponseFormat, etc.
+            var runOptions = new AgentRunOptions();
+            foreach (var observer in observers)
+            {
+                observer.ConfigureRunOptions(runOptions);
+            }
+
+            // Stream the response, fanning out to all observers.
+            writer.CurrentMode = modeProvider?.GetMode(session);
+            writer.WriteResponseHeader();
+
+            try
+            {
+                await foreach (var update in agent.RunStreamingAsync(nextMessages, session, runOptions))
+                {
+                    // Update mode color if the mode changed during streaming.
+                    if (modeProvider is not null)
+                    {
+                        string currentMode = modeProvider.GetMode(session);
+                        if (currentMode != writer.CurrentMode)
+                        {
+                            writer.CurrentMode = currentMode;
+                        }
+                    }
+
+                    foreach (var content in update.Contents)
+                    {
+                        foreach (var observer in observers)
+                        {
+                            await observer.OnContentAsync(writer, content);
+                        }
+                    }
+
+                    if (!string.IsNullOrEmpty(update.Text))
+                    {
+                        foreach (var observer in observers)
+                        {
+                            await observer.OnTextAsync(writer, update.Text);
+                        }
+                    }
+                }
+            }
+            catch (Exception ex)
+            {
+                await writer.WriteInfoLineAsync($"❌ Stream error: {ex.GetType().Name}:\n{ex}", ConsoleColor.Red);
+            }
+
+            // Collect messages from all observers.
+            var combinedMessages = new List<ChatMessage>();
+            bool hasObserverMessages = false;
+            foreach (var observer in observers)
+            {
+                var messages = await observer.OnStreamCompleteAsync(writer, agent, session, options);
+                if (messages is { Count: > 0 })
+                {
+                    combinedMessages.AddRange(messages);
+                    hasObserverMessages = true;
+                }
+            }
+
+            await writer.WriteStreamFooterAsync(hasFollowUpMessages: hasObserverMessages);
+            nextMessages = combinedMessages.Count > 0 ? combinedMessages : null;
+        }
+    }
+
+    private static List<ConsoleObserver> CreateObservers(HarnessConsoleOptions options, AgentModeProvider? modeProvider, AgentSession session)
+    {
+        var observers = new List<ConsoleObserver>
+        {
+            new ToolCallDisplayObserver(),
+            new ToolApprovalObserver(),
+            new ErrorDisplayObserver(),
+            new ReasoningDisplayObserver(),
+            new UsageDisplayObserver(options.MaxContextWindowTokens, options.MaxOutputTokens),
+        };
+
+        // Add the appropriate output observer based on the current mode.
+        if (options.EnablePlanningUx
+            && modeProvider is not null
+            && string.Equals(modeProvider.GetMode(session), options.PlanningModeName, StringComparison.OrdinalIgnoreCase))
+        {
+            observers.Add(new PlanningOutputObserver(modeProvider));
+        }
+        else
+        {
+            observers.Add(new TextOutputObserver());
+        }
+
+        return observers;
+    }
+
+    private static string BuildUserPrompt(AgentModeProvider? modeProvider, AgentSession session)
+    {
+        if (modeProvider is not null)
+        {
+            string mode = modeProvider.GetMode(session);
+            return $"[{mode}] You: ";
+        }
+
+        return "You: ";
+    }
+}
@@ -0,0 +1,52 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Harness.Shared.Console;
+
+/// <summary>
+/// Configuration options for <see cref="HarnessConsole"/>.
+/// </summary>
+public class HarnessConsoleOptions
+{
+    /// <summary>
+    /// Gets or sets the optional maximum context window size in tokens.
+    /// When set, token usage is displayed as a percentage of the budget.
+    /// </summary>
+    public int? MaxContextWindowTokens { get; set; }
+
+    /// <summary>
+    /// Gets or sets the optional maximum output tokens.
+    /// Used with <see cref="MaxContextWindowTokens"/> to show input/output budget breakdown.
+    /// </summary>
+    public int? MaxOutputTokens { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the planning UX is enabled.
+    /// When <see langword="true"/> and the agent is in the mode specified by <see cref="PlanningModeName"/>,
+    /// the console uses structured output to present clarification questions and approval requests
+    /// instead of streaming free-form text.
+    /// </summary>
+    /// <value>Defaults to <see langword="false"/>.</value>
+    public bool EnablePlanningUx { get; set; }
+
+    /// <summary>
+    /// Gets or sets the name of the agent mode that activates the planning UX.
+    /// Must be set when <see cref="EnablePlanningUx"/> is <see langword="true"/>.
+    /// </summary>
+    public string? PlanningModeName { get; set; }
+
+    /// <summary>
+    /// Gets or sets the name of the agent mode to switch to when the user approves a plan.
+    /// Must be set when <see cref="EnablePlanningUx"/> is <see langword="true"/>.
+    /// </summary>
+    public string? ExecutionModeName { get; set; }
+
+    /// <summary>
+    /// Gets or sets a mapping of agent mode names to console colors.
+    /// When a mode is not found in this dictionary, the default color (<see cref="ConsoleColor.Gray"/>) is used.
+    /// </summary>
+    public Dictionary<string, ConsoleColor> ModeColors { get; set; } = new(StringComparer.OrdinalIgnoreCase)
+    {
+        ["plan"] = ConsoleColor.Cyan,
+        ["execute"] = ConsoleColor.Green,
+    };
+}
@@ -0,0 +1,18 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Spectre.Console" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,53 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console.Observers;
+
+/// <summary>
+/// Abstract base class for console observers that participate in the agent response
+/// streaming lifecycle. Observers can configure run options, observe streamed content,
+/// and return messages to re-invoke the agent after the stream completes.
+/// All methods have default no-op implementations so subclasses only override what they need.
+/// </summary>
+public abstract class ConsoleObserver
+{
+    /// <summary>
+    /// Configures <see cref="AgentRunOptions"/> before the agent is invoked.
+    /// Override to set options such as <see cref="AgentRunOptions.ResponseFormat"/>.
+    /// </summary>
+    /// <param name="options">The run options to configure.</param>
+    public virtual void ConfigureRunOptions(AgentRunOptions options)
+    {
+    }
+
+    /// <summary>
+    /// Called for each <see cref="AIContent"/> item in the response stream.
+    /// </summary>
+    /// <param name="writer">The console writer for rendering output.</param>
+    /// <param name="content">The content item from the stream.</param>
+    public virtual Task OnContentAsync(ConsoleWriter writer, AIContent content) => Task.CompletedTask;
+
+    /// <summary>
+    /// Called for each text update in the response stream.
+    /// </summary>
+    /// <param name="writer">The console writer for rendering output.</param>
+    /// <param name="text">The text from the update.</param>
+    public virtual Task OnTextAsync(ConsoleWriter writer, string text) => Task.CompletedTask;
+
+    /// <summary>
+    /// Called after the response stream completes. Returns messages to include in the
+    /// next agent invocation, or <see langword="null"/> if no re-invocation is needed.
+    /// </summary>
+    /// <param name="writer">The console writer for rendering output.</param>
+    /// <param name="agent">The agent being interacted with.</param>
+    /// <param name="session">The current agent session.</param>
+    /// <param name="options">The console options.</param>
+    /// <returns>Messages to send to the agent, or <see langword="null"/> if no action is needed.</returns>
+    public virtual Task<IList<ChatMessage>?> OnStreamCompleteAsync(
+        ConsoleWriter writer,
+        AIAgent agent,
+        AgentSession session,
+        HarnessConsoleOptions options) => Task.FromResult<IList<ChatMessage>?>(null);
+}
@@ -0,0 +1,31 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console.Observers;
+
+/// <summary>
+/// Displays error content (❌) from the response stream.
+/// </summary>
+internal sealed class ErrorDisplayObserver : ConsoleObserver
+{
+    /// <inheritdoc/>
+    public override async Task OnContentAsync(ConsoleWriter writer, AIContent content)
+    {
+        if (content is ErrorContent errorContent)
+        {
+            string errorText = $"❌ Error: {errorContent.Message}";
+            if (!string.IsNullOrWhiteSpace(errorContent.ErrorCode))
+            {
+                errorText += $" (code: {errorContent.ErrorCode})";
+            }
+
+            if (!string.IsNullOrWhiteSpace(errorContent.Details))
+            {
+                errorText += $" details: {errorContent.Details}";
+            }
+
+            await writer.WriteInfoLineAsync(errorText, ConsoleColor.Red);
+        }
+    }
+}
@@ -0,0 +1,177 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text;
+using System.Text.Json;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console.Observers;
+
+/// <summary>
+/// Planning observer that configures structured output, collects streamed text,
+/// and deserializes it as a <see cref="PlanningResponse"/>. Renders clarification
+/// questions and approval prompts, and manages mode switching when the user approves a plan.
+/// </summary>
+internal sealed class PlanningOutputObserver : ConsoleObserver
+{
+    private readonly StringBuilder _textCollector = new();
+    private readonly AgentModeProvider _modeProvider;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="PlanningOutputObserver"/> class.
+    /// </summary>
+    /// <param name="modeProvider">The mode provider for switching modes on approval.</param>
+    public PlanningOutputObserver(AgentModeProvider modeProvider)
+    {
+        this._modeProvider = modeProvider;
+    }
+
+    /// <inheritdoc/>
+    public override void ConfigureRunOptions(AgentRunOptions options)
+    {
+        options.ResponseFormat = ChatResponseFormat.ForJsonSchema<PlanningResponse>();
+    }
+
+    /// <inheritdoc/>
+    public override Task OnTextAsync(ConsoleWriter writer, string text)
+    {
+        // Collect text silently instead of displaying it.
+        this._textCollector.Append(text);
+        return Task.CompletedTask;
+    }
+
+    /// <inheritdoc/>
+    public override async Task<IList<ChatMessage>?> OnStreamCompleteAsync(
+        ConsoleWriter writer,
+        AIAgent agent,
+        AgentSession session,
+        HarnessConsoleOptions options)
+    {
+        // Read collected text from our stream observation.
+        string collectedText = this._textCollector.ToString();
+        this._textCollector.Clear();
+
+        if (string.IsNullOrWhiteSpace(collectedText))
+        {
+            return null;
+        }
+
+        // Deserialize the structured response.
+        PlanningResponse? planningResponse;
+        try
+        {
+            planningResponse = JsonSerializer.Deserialize<PlanningResponse>(collectedText);
+        }
+        catch (JsonException ex)
+        {
+            await writer.WriteInfoLineAsync($"❌ Failed to parse planning response: {ex.Message}", ConsoleColor.Red);
+            await writer.WriteInfoLineAsync($"(raw response) {collectedText}", ConsoleColor.DarkYellow);
+            return null;
+        }
+
+        if (planningResponse is null)
+        {
+            await writer.WriteInfoLineAsync("(no structured response from agent)", ConsoleColor.DarkYellow);
+            return null;
+        }
+
+        // Render based on response type.
+        if (planningResponse.Type == PlanningResponseType.Clarification)
+        {
+            return AsUserMessages(await this.RenderClarificationsAndCollectResponsesAsync(writer, planningResponse));
+        }
+
+        if (planningResponse.Type == PlanningResponseType.Approval)
+        {
+            var question = planningResponse.Questions.FirstOrDefault();
+            if (question is null)
+            {
+                await writer.WriteInfoLineAsync("(approval response had no content)", ConsoleColor.DarkYellow);
+                return null;
+            }
+
+            string response = await this.RenderApprovalAndCollectResponseAsync(writer, question, options);
+            if (response == "Approved")
+            {
+                this._modeProvider.SetMode(session, options.ExecutionModeName!);
+
+                await writer.WriteInfoLineAsync($"✅ Switched to {options.ExecutionModeName} mode.",
+                    ConsoleWriter.GetModeColor(options.ExecutionModeName, options.ModeColors));
+            }
+
+            return AsUserMessages(response);
+        }
+
+        await writer.WriteInfoLineAsync($"(unexpected response type: {planningResponse.Type})", ConsoleColor.DarkYellow);
+        return null;
+    }
+
+    private static IList<ChatMessage>? AsUserMessages(string? text) =>
+        text is not null ? [new ChatMessage(ChatRole.User, text)] : null;
+
+    private async Task<string?> RenderClarificationsAndCollectResponsesAsync(ConsoleWriter writer, PlanningResponse response)
+    {
+        var answers = new List<string>();
+
+        foreach (var question in response.Questions)
+        {
+            await writer.WriteInfoLineAsync(string.Empty);
+            await writer.WriteInfoLineAsync(question.Message);
+
+            string? answer;
+            if (question.Choices is { Count: > 0 })
+            {
+                answer = await writer.ReadSelectionAsync(
+                    "Choose an option:",
+                    question.Choices);
+            }
+            else
+            {
+                answer = (await writer.ReadLineAsync("Response: "))?.Trim();
+            }
+
+            if (!string.IsNullOrWhiteSpace(answer))
+            {
+                answers.Add($"Q: {question.Message}\nA: {answer}");
+            }
+        }
+
+        return answers.Count > 0 ? string.Join("\n\n", answers) : null;
+    }
+
+    private async Task<string> RenderApprovalAndCollectResponseAsync(ConsoleWriter writer, PlanningQuestion question, HarnessConsoleOptions options)
+    {
+        await writer.WriteInfoLineAsync(question.Message);
+
+        var choices = new List<string>
+        {
+            "Approve and switch to execute mode",
+            "Suggest changes",
+        };
+
+        string selection = await writer.ReadSelectionAsync("What would you like to do?", choices);
+
+        if (selection == choices[0])
+        {
+            return "Approved";
+        }
+
+        if (selection == choices[1])
+        {
+            string? feedback = await writer.ReadLineAsync(
+                "Your feedback: ",
+                ConsoleWriter.GetModeColor(options.PlanningModeName, options.ModeColors));
+
+            if (string.IsNullOrWhiteSpace(feedback))
+            {
+                // Treat empty feedback as no changes — re-prompt the agent with the plan.
+                return "No changes suggested. Please re-present the plan for approval.";
+            }
+
+            return feedback;
+        }
+
+        // Custom freeform input — treat as suggested changes.
+        return selection;
+    }
+}
@@ -0,0 +1,51 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+using System.Text.Json.Serialization;
+
+namespace Harness.Shared.Console.Observers;
+
+/// <summary>
+/// Represents a structured response from the agent while in planning mode.
+/// Used with structured output to enable consistent rendering of clarification
+/// questions and approval requests in the console.
+/// </summary>
+public class PlanningResponse
+{
+    /// <summary>
+    /// Gets or sets the type of planning response.
+    /// </summary>
+    [JsonPropertyName("type")]
+    public required PlanningResponseType Type { get; set; }
+
+    /// <summary>
+    /// Gets or sets the list of questions or items to present to the user.
+    /// For clarification, this contains one or more questions (each with choices).
+    /// For approval, this contains exactly one item with the plan summary.
+    /// </summary>
+    [JsonPropertyName("questions")]
+    [Description("For clarifications, this has one or more questions to ask the user (each with choices). For approvals, this has exactly one item containing the plan summary for the user to approve.")]
+    public required List<PlanningQuestion> Questions { get; set; }
+}
+
+/// <summary>
+/// Represents a single question or item within a <see cref="PlanningResponse"/>.
+/// </summary>
+public class PlanningQuestion
+{
+    /// <summary>
+    /// Gets or sets the message to display to the user.
+    /// For clarification, this is the question. For approval, this is the plan summary.
+    /// </summary>
+    [JsonPropertyName("message")]
+    [Description("For clarifications, this has the question that needs to be clarified with the user. For approvals, this would contain a summary of the execution plan that the user needs to approve.")]
+    public required string Message { get; set; }
+
+    /// <summary>
+    /// Gets or sets the list of choices for the user to pick from.
+    /// Only used for clarification questions. Null when no predefined choices are offered.
+    /// </summary>
+    [JsonPropertyName("choices")]
+    [Description("For clarifications, this has a list of options that the user can choose from. null for approvals.")]
+    public List<string>? Choices { get; set; }
+}
@@ -0,0 +1,25 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+using System.Text.Json.Serialization;
+
+namespace Harness.Shared.Console.Observers;
+
+/// <summary>
+/// Specifies the type of planning response from the agent.
+/// </summary>
+[JsonConverter(typeof(JsonStringEnumConverter<PlanningResponseType>))]
+public enum PlanningResponseType
+{
+    /// <summary>
+    /// The agent needs clarification and presents options for the user to choose from.
+    /// </summary>
+    [Description("Use this type when you need clarification around the user request and you want to present the user with options to choose from.")]
+    Clarification,
+
+    /// <summary>
+    /// The agent is seeking approval to proceed with execution.
+    /// </summary>
+    [Description("Use this type when you are ready to start execution, but need approval to start executing.")]
+    Approval,
+}
@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console.Observers;
+
+/// <summary>
+/// Displays reasoning content in dark magenta from the response stream.
+/// </summary>
+internal sealed class ReasoningDisplayObserver : ConsoleObserver
+{
+    /// <inheritdoc/>
+    public override async Task OnContentAsync(ConsoleWriter writer, AIContent content)
+    {
+        if (content is TextReasoningContent reasoning && !string.IsNullOrEmpty(reasoning.Text))
+        {
+            await writer.WriteTextAsync(reasoning.Text, ConsoleColor.DarkMagenta);
+        }
+    }
+}
@@ -0,0 +1,16 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Harness.Shared.Console.Observers;
+
+/// <summary>
+/// Streams agent text output directly to the console.
+/// Used in normal (non-planning) mode.
+/// </summary>
+internal sealed class TextOutputObserver : ConsoleObserver
+{
+    /// <inheritdoc/>
+    public override async Task OnTextAsync(ConsoleWriter writer, string text)
+    {
+        await writer.WriteTextAsync(text);
+    }
+}
@@ -0,0 +1,92 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console.Observers;
+
+/// <summary>
+/// Collects <see cref="ToolApprovalRequestContent"/> items during the response stream,
+/// displays approval-needed notifications inline, and prompts the user for approval
+/// decisions after the stream completes.
+/// </summary>
+internal sealed class ToolApprovalObserver : ConsoleObserver
+{
+    private readonly List<ToolApprovalRequestContent> _approvalRequests = [];
+
+    /// <inheritdoc/>
+    public override async Task OnContentAsync(ConsoleWriter writer, AIContent content)
+    {
+        if (content is ToolApprovalRequestContent approvalRequest)
+        {
+            this._approvalRequests.Add(approvalRequest);
+            string toolName = approvalRequest.ToolCall is FunctionCallContent fc
+                ? ToolCallFormatter.Format(fc)
+                : approvalRequest.ToolCall?.ToString() ?? "unknown";
+            await writer.WriteInfoLineAsync($"⚠️ Approval needed: {toolName}", ConsoleColor.Yellow);
+        }
+    }
+
+    /// <inheritdoc/>
+    public override async Task<IList<ChatMessage>?> OnStreamCompleteAsync(
+        ConsoleWriter writer,
+        AIAgent agent,
+        AgentSession session,
+        HarnessConsoleOptions options)
+    {
+        if (this._approvalRequests.Count == 0)
+        {
+            return null;
+        }
+
+        var messages = await PromptForApprovalsAsync(writer, this._approvalRequests);
+        this._approvalRequests.Clear();
+        return messages;
+    }
+
+    private static async Task<List<ChatMessage>?> PromptForApprovalsAsync(ConsoleWriter writer, List<ToolApprovalRequestContent> approvalRequests)
+    {
+        if (approvalRequests.Count == 0)
+        {
+            return null;
+        }
+
+        var responses = new List<AIContent>();
+        foreach (var request in approvalRequests)
+        {
+            string toolName = request.ToolCall is FunctionCallContent fc
+                ? ToolCallFormatter.Format(fc)
+                : request.ToolCall?.ToString() ?? "unknown";
+
+            var choices = new List<string>
+            {
+                "Approve this call",
+                "Always approve this tool (any arguments)",
+                "Always approve this tool with these arguments",
+                "Deny",
+            };
+
+            string selection = await writer.ReadSelectionAsync($"🔐 Tool approval: {toolName}", choices);
+            AIContent response = selection switch
+            {
+                "Always approve this tool (any arguments)" => request.CreateAlwaysApproveToolResponse("User chose to always approve this tool"),
+                "Always approve this tool with these arguments" => request.CreateAlwaysApproveToolWithArgumentsResponse("User chose to always approve this tool with these arguments"),
+                "Deny" => request.CreateResponse(approved: false, reason: "User denied"),
+                _ => request.CreateResponse(approved: true, reason: "User approved"),
+            };
+
+            string action = selection switch
+            {
+                "Always approve this tool (any arguments)" => "✅ Always approved (any args)",
+                "Always approve this tool with these arguments" => "✅ Always approved (these args)",
+                "Deny" => "❌ Denied",
+                _ => "✅ Approved",
+            };
+            await writer.WriteInfoLineAsync($"   {action}", ConsoleColor.DarkGray);
+
+            responses.Add(response);
+        }
+
+        return [new ChatMessage(ChatRole.User, responses)];
+    }
+}
@@ -0,0 +1,25 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console.Observers;
+
+/// <summary>
+/// Displays tool call notifications (🔧) for <see cref="FunctionCallContent"/>
+/// and <see cref="ToolCallContent"/> items in the response stream.
+/// </summary>
+internal sealed class ToolCallDisplayObserver : ConsoleObserver
+{
+    /// <inheritdoc/>
+    public override async Task OnContentAsync(ConsoleWriter writer, AIContent content)
+    {
+        if (content is FunctionCallContent functionCall)
+        {
+            await writer.WriteInfoLineAsync($"🔧 Calling tool: {ToolCallFormatter.Format(functionCall)}...", ConsoleColor.DarkYellow);
+        }
+        else if (content is ToolCallContent toolCall)
+        {
+            await writer.WriteInfoLineAsync($"🔧 Calling tool: {toolCall}...", ConsoleColor.DarkYellow);
+        }
+    }
+}
@@ -0,0 +1,288 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text;
+using System.Text.Json;
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console.Observers;
+
+/// <summary>
+/// Formats <see cref="FunctionCallContent"/> instances into human-readable strings
+/// for console display.
+/// </summary>
+public static class ToolCallFormatter
+{
+    /// <summary>
+    /// Returns a formatted string for the given tool call, with human-readable
+    /// details for known tools (todos, mode, sub-agents, web tools).
+    /// </summary>
+    /// <param name="call">The function call content to format.</param>
+    /// <returns>A formatted string describing the tool call.</returns>
+    public static string Format(FunctionCallContent call)
+    {
+        string? detail = call.Name switch
+        {
+            // Todo tools
+            "TodoList_Add" => FormatAddTodos(call),
+            "TodoList_Complete" => FormatIdList(call, "ids", "Complete"),
+            "TodoList_Remove" => FormatIdList(call, "ids", "Remove"),
+            "TodoList_GetRemaining" => null,
+            "TodoList_GetAll" => null,
+
+            // Mode tools
+            "AgentMode_Set" => FormatStringArg(call, "mode"),
+            "AgentMode_Get" => null,
+
+            // Sub-agent tools
+            "SubAgents_StartTask" => FormatStartSubTask(call),
+            "SubAgents_WaitForFirstCompletion" => FormatIdList(call, "taskIds", "Wait for"),
+            "SubAgents_GetTaskResults" => FormatSingleId(call, "taskId"),
+            "SubAgents_GetAllTasks" => null,
+            "SubAgents_ContinueTask" => FormatContinueTask(call),
+            "SubAgents_ClearCompletedTask" => FormatSingleId(call, "taskId"),
+
+            // File memory tools
+            "FileMemory_SaveFile" => FormatSaveFile(call),
+            "FileMemory_ReadFile" => FormatStringArg(call, "fileName"),
+            "FileMemory_DeleteFile" => FormatStringArg(call, "fileName"),
+            "FileMemory_ListFiles" => null,
+            "FileMemory_SearchFiles" => FormatSearchFiles(call),
+
+            // External tools
+            "web_search" => FormatStringArg(call, "query"),
+            "DownloadUri" => FormatStringArg(call, "uri"),
+
+            _ => FormatFallback(call),
+        };
+
+        return detail is not null ? $"{call.Name} {detail}" : call.Name;
+    }
+
+    private static string? FormatAddTodos(FunctionCallContent call)
+    {
+        if (call.Arguments?.TryGetValue("todos", out object? todosObj) != true || todosObj is null)
+        {
+            return null;
+        }
+
+        var titles = new List<string>();
+
+        if (todosObj is JsonElement jsonArray && jsonArray.ValueKind == JsonValueKind.Array)
+        {
+            foreach (JsonElement item in jsonArray.EnumerateArray())
+            {
+                string? title = item.TryGetProperty("title", out JsonElement titleElement)
+                    ? titleElement.GetString()
+                    : null;
+
+                if (!string.IsNullOrEmpty(title))
+                {
+                    titles.Add(title);
+                }
+            }
+        }
+
+        if (titles.Count == 0)
+        {
+            return null;
+        }
+
+        var sb = new StringBuilder();
+        sb.Append($"({titles.Count} item{(titles.Count == 1 ? "" : "s")})");
+        foreach (string title in titles)
+        {
+            sb.Append($"\n    • {title}");
+        }
+
+        return sb.ToString();
+    }
+
+    private static string? FormatIdList(FunctionCallContent call, string paramName, string verb)
+    {
+        List<int>? ids = GetIntList(call, paramName);
+        if (ids is null || ids.Count == 0)
+        {
+            return null;
+        }
+
+        return $"({verb} #{string.Join(", #", ids)})";
+    }
+
+    private static string? FormatSingleId(FunctionCallContent call, string paramName)
+    {
+        int? id = GetInt(call, paramName);
+        return id.HasValue ? $"(task #{id.Value})" : null;
+    }
+
+    private static string? FormatStartSubTask(FunctionCallContent call)
+    {
+        string? agentName = GetString(call, "agentName");
+        string? description = GetString(call, "description");
+
+        if (agentName is null && description is null)
+        {
+            return null;
+        }
+
+        var sb = new StringBuilder("(");
+        if (agentName is not null)
+        {
+            sb.Append($"agent: {agentName}");
+        }
+
+        if (description is not null)
+        {
+            if (agentName is not null)
+            {
+                sb.Append(", ");
+            }
+
+            sb.Append($"\"{Truncate(description, 60)}\"");
+        }
+
+        sb.Append(')');
+        return sb.ToString();
+    }
+
+    private static string? FormatContinueTask(FunctionCallContent call)
+    {
+        int? taskId = GetInt(call, "taskId");
+        string? text = GetString(call, "text");
+
+        if (!taskId.HasValue)
+        {
+            return null;
+        }
+
+        return text is not null
+            ? $"(task #{taskId.Value}, \"{Truncate(text, 50)}\")"
+            : $"(task #{taskId.Value})";
+    }
+
+    private static string? FormatSaveFile(FunctionCallContent call)
+    {
+        string? fileName = GetString(call, "fileName");
+        string? description = GetString(call, "description");
+
+        if (fileName is null)
+        {
+            return null;
+        }
+
+        return string.IsNullOrEmpty(description)
+            ? $"({fileName})"
+            : $"({fileName}, with description)";
+    }
+
+    private static string? FormatSearchFiles(FunctionCallContent call)
+    {
+        string? pattern = GetString(call, "regexPattern");
+        string? filePattern = GetString(call, "filePattern");
+
+        if (pattern is null)
+        {
+            return null;
+        }
+
+        return string.IsNullOrEmpty(filePattern)
+            ? $"(/{pattern}/)"
+            : $"(/{pattern}/ in {filePattern})";
+    }
+
+    private static string? FormatStringArg(FunctionCallContent call, string paramName)
+    {
+        string? value = GetString(call, paramName);
+        return value is not null ? $"({value})" : null;
+    }
+
+    private static string? FormatFallback(FunctionCallContent call)
+    {
+        if (call.Arguments is null || call.Arguments.Count == 0)
+        {
+            return null;
+        }
+
+        var parts = new List<string>();
+        foreach (var kvp in call.Arguments)
+        {
+            string? stringValue = kvp.Value switch
+            {
+                JsonElement je => je.ValueKind switch
+                {
+                    JsonValueKind.String => je.GetString(),
+                    JsonValueKind.Number => je.GetRawText(),
+                    JsonValueKind.True => "true",
+                    JsonValueKind.False => "false",
+                    _ => null,
+                },
+                not null => kvp.Value.ToString(),
+                _ => null,
+            };
+
+            if (stringValue is not null)
+            {
+                parts.Add($"{kvp.Key}: {Truncate(stringValue, 40)}");
+            }
+        }
+
+        return parts.Count > 0 ? $"({string.Join(", ", parts)})" : null;
+    }
+
+    private static string? GetString(FunctionCallContent call, string paramName)
+    {
+        if (call.Arguments?.TryGetValue(paramName, out object? value) != true || value is null)
+        {
+            return null;
+        }
+
+        return value switch
+        {
+            JsonElement je when je.ValueKind == JsonValueKind.String => je.GetString(),
+            string s => s,
+            _ => value.ToString(),
+        };
+    }
+
+    private static int? GetInt(FunctionCallContent call, string paramName)
+    {
+        if (call.Arguments?.TryGetValue(paramName, out object? value) != true || value is null)
+        {
+            return null;
+        }
+
+        return value switch
+        {
+            JsonElement je when je.ValueKind == JsonValueKind.Number => je.GetInt32(),
+            int i => i,
+            _ => int.TryParse(value.ToString(), out int parsed) ? parsed : null,
+        };
+    }
+
+    private static List<int>? GetIntList(FunctionCallContent call, string paramName)
+    {
+        if (call.Arguments?.TryGetValue(paramName, out object? value) != true || value is null)
+        {
+            return null;
+        }
+
+        var result = new List<int>();
+
+        if (value is JsonElement je && je.ValueKind == JsonValueKind.Array)
+        {
+            foreach (JsonElement item in je.EnumerateArray())
+            {
+                if (item.ValueKind == JsonValueKind.Number)
+                {
+                    result.Add(item.GetInt32());
+                }
+            }
+        }
+
+        return result.Count > 0 ? result : null;
+    }
+
+    private static string Truncate(string text, int maxLength)
+    {
+        return text.Length <= maxLength ? text : string.Concat(text.AsSpan(0, maxLength), "…");
+    }
+}
@@ -0,0 +1,68 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console.Observers;
+
+/// <summary>
+/// Displays token usage statistics (📊) from the response stream.
+/// </summary>
+internal sealed class UsageDisplayObserver : ConsoleObserver
+{
+    private readonly int? _maxContextWindowTokens;
+    private readonly int? _maxOutputTokens;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="UsageDisplayObserver"/> class.
+    /// </summary>
+    /// <param name="maxContextWindowTokens">Optional max context window size in tokens.</param>
+    /// <param name="maxOutputTokens">Optional max output tokens.</param>
+    public UsageDisplayObserver(int? maxContextWindowTokens, int? maxOutputTokens)
+    {
+        this._maxContextWindowTokens = maxContextWindowTokens;
+        this._maxOutputTokens = maxOutputTokens;
+    }
+
+    /// <inheritdoc/>
+    public override async Task OnContentAsync(ConsoleWriter writer, AIContent content)
+    {
+        if (content is UsageContent usage)
+        {
+            if (usage.Details is not null)
+            {
+                await writer.WriteInfoLineAsync(this.FormatUsageBreakdown(usage.Details), ConsoleColor.DarkGray);
+            }
+            else
+            {
+                await writer.WriteInfoLineAsync("📊 Tokens —", ConsoleColor.DarkGray);
+            }
+        }
+    }
+
+    private string FormatUsageBreakdown(UsageDetails details)
+    {
+        int? inputBudget = (this._maxContextWindowTokens is not null && this._maxOutputTokens is not null)
+            ? this._maxContextWindowTokens.Value - this._maxOutputTokens.Value
+            : null;
+
+        return $"📊 Tokens — input: {FormatTokenCount(details.InputTokenCount, inputBudget)}"
+            + $" | output: {FormatTokenCount(details.OutputTokenCount, this._maxOutputTokens)}"
+            + $" | total: {FormatTokenCount(details.TotalTokenCount, this._maxContextWindowTokens)}";
+    }
+
+    private static string FormatTokenCount(long? count, int? budget)
+    {
+        if (count is null)
+        {
+            return "—";
+        }
+
+        if (budget is not null && budget.Value > 0)
+        {
+            double pct = (double)count.Value / budget.Value * 100;
+            return $"{count.Value:N0}/{budget.Value:N0} ({pct:F1}%)";
+        }
+
+        return $"{count.Value:N0}";
+    }
+}
@@ -0,0 +1,77 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Harness.Shared.Console;
+
+/// <summary>
+/// A restartable spinner that can be started and stopped multiple times.
+/// </summary>
+internal sealed class Spinner : IDisposable
+{
+    private static readonly string[] s_frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+    private CancellationTokenSource? _cts;
+    private Task? _task;
+
+    public void Start()
+    {
+        if (this._task is not null)
+        {
+            return;
+        }
+
+        this._cts = new CancellationTokenSource();
+        this._task = RunAsync(this._cts.Token);
+    }
+
+    public async Task StopAsync()
+    {
+        if (this._cts is null || this._task is null)
+        {
+            return;
+        }
+
+        this._cts.Cancel();
+        await this._task;
+        this._cts.Dispose();
+        this._cts = null;
+        this._task = null;
+    }
+
+    public void Dispose()
+    {
+        if (this._cts is not null && this._task is not null)
+        {
+            this._cts.Cancel();
+
+            // Block briefly to let the spinner task clean up.
+            // This prevents the background task from writing to the console after disposal.
+#pragma warning disable VSTHRD002 // Synchronous wait in Dispose is acceptable here — the spinner task completes quickly on cancellation.
+            this._task.Wait();
+#pragma warning restore VSTHRD002
+        }
+
+        this._cts?.Dispose();
+        this._cts = null;
+        this._task = null;
+    }
+
+    private static async Task RunAsync(CancellationToken cancellationToken)
+    {
+        int i = 0;
+        try
+        {
+            while (!cancellationToken.IsCancellationRequested)
+            {
+                System.Console.Write(s_frames[i % s_frames.Length]);
+                await Task.Delay(80, cancellationToken);
+                System.Console.Write("\b \b");
+                i++;
+            }
+        }
+        catch (OperationCanceledException)
+        {
+            // Clear the last spinner frame left on screen.
+            System.Console.Write("\b \b");
+        }
+    }
+}
@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\Harness_Shared_Console\Harness_Shared_Console.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,190 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to use a ChatClientAgent with the Harness AIContextProviders
+// (TodoProvider and AgentModeProvider) for interactive research tasks with web search
+// capabilities powered by Azure AI Foundry.
+// The agent plans research tasks, creates a todo list, gets user approval,
+// and then executes each step — all within an interactive conversation loop.
+//
+// Special commands:
+//   /todos  — Display the current todo list without invoking the agent.
+//   exit    — End the session.
+
+#pragma warning disable OPENAI001 // Suppress experimental API warnings for Responses API usage.
+#pragma warning disable MAAI001  // Suppress experimental API warnings for Agents AI experiments.
+
+using System.ClientModel.Primitives;
+using Azure.Identity;
+using Harness.Shared.Console;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Compaction;
+using Microsoft.Extensions.AI;
+using OpenAI;
+using OpenAI.Responses;
+using SampleApp;
+
+var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_OPENAI_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5.4";
+
+const int MaxContextWindowTokens = 1_050_000;
+const int MaxOutputTokens = 128_000;
+
+// Create a ChatClientAgent with the Harness providers (TodoProvider and AgentModeProvider)
+// and research-focused instructions including the mandatory planning workflow.
+var instructions =
+    """
+    You are a research assistant. When given a research topic, research it thoroughly using web search and web browsing.
+    Use your knowledge to form good search queries and hypotheses, but always verify claims with the tools available to you rather than relying on memory alone.
+
+    ## Mandatory planning workflow
+
+    For every new substantive user request, including short factual questions, your behavior is determined by the mode you are in.
+    If you are in plan mode, start with the *Plan Mode* steps, and if you are in execute mode, skip directly to the *Execute Mode* steps below.
+
+    *Plan Mode*
+
+    1. Analyze the request with the purpose of building a research plan.
+    2. Create a list of todo items.
+    3. If needed, use the provided tools to do some exploratory checks to help build a plan and determine what clarifying questions you may need from the user.
+    4. Ask for clarifications from the user where needed.
+      1. Ask each clarification one by one.
+      2. When asking for clarification and you have specific options in mind, present them to the user, so they can choose the option instead of having to retype the entire response.
+      3. Do not proceed until you have received all the needed clarifications.
+      4. Do short exploratory research if it helps with being able to ask sensible clarifications from the user.
+    5. Write the plan to a memory file, so that it is retained even if compaction happens. Make sure to update the plan file if the user requests changes.
+    6. Present the plan to the user and ask for approval to switch to execute mode and process the plan.
+    7. When approval is granted, always switch to execute mode (using the `AgentMode_Set` tool), and follow the steps for *Execute mode*.
+
+    *Execute Mode*
+
+    1. If you don't have a plan or tasks yet, analyse the user request and create tasks and a plan. (**Skip this step if you came from plan mode**)
+    2. Work autonomously — use your best judgement to make decisions and keep progressing without asking the user questions. The goal is to have a complete, useful result ready when the user returns.
+    3. If you encounter ambiguity or an unexpected situation during execution, choose the most reasonable option, note your choice, and keep going.
+    4. Mark tasks as completed as you finish them.
+    5. Continue working, thinking and calling tools until you have the research result for the user.
+
+    ## General Instructions
+
+    - You must check the current mode after any user input, since the user may have changed the mode themselves,
+      e.g. the user may have switched to 'plan' mode after a previous research task finished in 'execute' mode, meaning they want to review a plan first before execution.
+    - Explain your reasoning and thought process as you work through tasks.
+    - Explain what you learned and what you are going to do next between tool calls, so the user can follow along with your thought process.
+    - Avoid making more than 4 tool calls in a row without explaining what you are doing.
+    - Do not answer the underlying question before the plan has been presented and approved.
+    - This rule applies even when the answer seems obvious or the task seems small.
+    - For short requests, use a brief micro-plan rather than skipping planning. The only exceptions are:
+      - greetings,
+      - pure acknowledgments,
+      - clarification questions needed to form the plan,
+      - follow-up questions about results you have already presented,
+      - meta-discussion about the workflow itself.
+
+    **Todo management**
+
+    Mark each todo complete as you finish it so the list stays current.
+    If a todo turns out to be unnecessary or is blocked, remove it and briefly explain why.
+    Once the user finishes with a topic and moves onto a new one, clean up old completed todos by deleting them.
+
+    **Research quality**
+
+    Consult multiple sources when possible and cross-reference key claims.
+    When sources disagree, note the discrepancy and explain which source you consider more reliable and why.
+    If a web page fails to load or a search returns irrelevant results, try alternative search queries or sources before moving on.
+    Track your sources — you will need them when presenting results.
+
+    **Presenting results**
+
+    When presenting your final findings:
+    - Use clear sections with headings for each major topic or sub-question.
+    - Cite your sources inline (e.g., "According to [source name](URL), ...").
+    - End with a brief summary of key takeaways.
+    - Save the final research report to file memory so it survives compaction and can be referenced later.
+
+    **File memory**
+
+    Use the FileMemory_* tools to:
+    - Store downloaded search results or web pages.
+    - Store plans.
+    - Read the current plan to make sure tasks were done according to plan.
+    - Store findings.
+    - Check for relevant previously downloaded data / findings before starting new research.
+    """;
+
+// Create a compaction strategy based on the model's context window.
+// gpt-5.4: 1,050,000 token context window, 128,000 max output tokens.
+// Defaults: tool result eviction at 50% of input budget, truncation at 80%.
+var compactionStrategy = new ContextWindowCompactionStrategy(
+    maxContextWindowTokens: MaxContextWindowTokens,
+    maxOutputTokens: MaxOutputTokens);
+
+AIAgent agent =
+    // Create an OpenAIClient that communicates with the Foundry responses service.
+    new OpenAIClient(
+        // 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.
+        new BearerTokenPolicy(new DefaultAzureCredential(), "https://ai.azure.com/.default"),
+        new OpenAIClientOptions()
+        {
+            Endpoint = new Uri(endpoint),
+            RetryPolicy = new ClientRetryPolicy(3)          // Enable retries to improve resiliency.
+        })
+    .GetResponsesClient()
+    .AsIChatClientWithStoredOutputDisabled(deploymentName)  // We want to manage chat history locally (not stored in the responses service), so that we can manage compaction ourselves.
+
+    // Build a ChatClient Pipeline
+    .AsBuilder()
+    .UseFunctionInvocation()                                // We are building our own stack from scratch so we need to include Function Invocation ourselves.
+    .UsePerServiceCallChatHistoryPersistence()              // Save chat history updates to the session after each service call, rather than only at the end of the run.
+    .UseAIContextProviders(new CompactionProvider(compactionStrategy))  // Add Compaction before each service call to responses so that long function invocation loops don't overflow the context.
+
+    // Build our agent on top of the ChatClient Pipeline
+    .BuildAIAgent(
+        new ChatClientAgentOptions
+        {
+            Name = "ResearchAgent",
+            Description = "A research assistant that plans and executes research tasks.",
+            UseProvidedChatClientAsIs = true,                           // Since we built our own stack from scratch we need to tell the agent not to also add defaults like Function Invocation.
+            RequirePerServiceCallChatHistoryPersistence = true,         // Since we are added the per service call persistence ChatClient, we need to tell the agent to not also store chat history at the end of the run.
+            ChatHistoryProvider = new InMemoryChatHistoryProvider(      // Store chat history in memory in the session object. Will persist if the session is persisted.
+                new InMemoryChatHistoryProviderOptions
+                {
+                    ChatReducer = compactionStrategy.AsChatReducer(),   // Run compaction on the InMemory chat history when it gets too large.
+                }),
+            AIContextProviders =
+            [
+                new TodoProvider(),         // Add an AIContextProvider to allow the agent to create a TODO list, which is stored in the session.
+                new AgentModeProvider(),    // Add an AIContextProvider that tracks the agent mode and allows switching mode. Current mode is stored in the session.
+                new FileMemoryProvider(     // Add an AIContextProvider that can store memories in files under a session specific working folder.
+                    new FileSystemAgentFileStore(Path.Combine(AppContext.BaseDirectory, "agent-files")),
+                    (_) => new FileMemoryState() { WorkingFolder = DateTime.UtcNow.ToString("yyyyMMdd_HHmmss") + "_" + Guid.NewGuid().ToString() })
+            ],
+            ChatOptions = new ChatOptions
+            {
+                Instructions = instructions,
+                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.
+                ],
+                MaxOutputTokens = MaxOutputTokens,                          // Set a high token limit for long research tasks with many tool calls and long outputs.
+                Reasoning = new() { Effort = ReasoningEffort.Medium },
+            },
+        })
+    .AsBuilder()
+    .UseToolApproval()                                                      // Add the ability to auto approve tools once a user has said they don't want to be asked again. Approval rules are tied to the session.
+    .Build();
+
+// Run the interactive console session using the shared HarnessConsole helper.
+await HarnessConsole.RunAgentAsync(
+    agent,
+    title: "Research Assistant",
+    userPrompt: "Enter a research topic to get started.",
+    new HarnessConsoleOptions
+    {
+        MaxContextWindowTokens = MaxContextWindowTokens,
+        MaxOutputTokens = MaxOutputTokens,
+        EnablePlanningUx = true,
+        PlanningModeName = "plan",
+        ExecutionModeName = "execute"
+    });
@@ -0,0 +1,52 @@
+# What this sample demonstrates
+
+This sample demonstrates how to use a `ChatClientAgent` with the Harness `AIContextProviders` (`TodoProvider` and `AgentModeProvider`) for interactive research tasks with web search capabilities powered by Azure AI Foundry.
+
+Key features showcased:
+
+- **ChatClientAgent** — configured directly with Harness providers for planning and task management
+- **Web Search** — the agent can search the web for current information via `ResponseTool.CreateWebSearchTool()`
+- **TodoProvider** — the agent creates and manages a todo list to track research questions
+- **AgentModeProvider** — the agent switches between "plan" mode (breaking down the topic) and "execute" mode (answering each research question)
+- **Interactive conversation** — you can review the agent's plan, provide feedback, and approve before execution begins
+- **Streaming output** — responses are streamed token-by-token for a natural experience
+- **`/todos` command** — view the current todo list at any time without invoking the agent
+- **Mode-based coloring** — console output is colored based on the agent's current mode (cyan for plan, green for execute)
+
+## Prerequisites
+
+Before running this sample, ensure you have:
+
+1. An Azure AI Foundry project with a deployed model (e.g., `gpt-5.4`)
+2. Azure CLI installed and authenticated (`az login`)
+
+## Environment Variables
+
+Set the following environment variables:
+
+```bash
+# Required: Your Azure AI Foundry OpenAI endpoint
+export AZURE_FOUNDRY_OPENAI_ENDPOINT="https://your-project.services.ai.azure.com/openai/v1/"
+
+# Optional: Model deployment name (defaults to gpt-5.4)
+export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-5.4"
+```
+
+## Running the Sample
+
+```bash
+cd dotnet
+dotnet run --project samples/02-agents/Harness/Harness_Step01_Research
+```
+
+## What to Expect
+
+The sample starts an interactive conversation loop. You can:
+
+1. **Enter a research topic** — the agent will analyze it and create a plan with todos
+2. **Review and adjust** — provide feedback on the plan, ask for changes, or approve it
+3. **Type `/todos`** — to see the current todo list at any time
+4. **Watch execution** — once approved, tell the agent to proceed and it will work through each todo
+5. **Type `exit`** — to end the session
+
+The prompt and agent output are colored by the current mode: **cyan** during planning, **green** during execution.
@@ -0,0 +1,287 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+using System.Net;
+using System.Text.Json;
+using System.Text.RegularExpressions;
+using Microsoft.Extensions.AI;
+
+namespace SampleApp;
+
+/// <summary>
+/// An AI function that downloads HTML pages and converts them to markdown.
+/// </summary>
+internal sealed partial class WebBrowsingTool : AIFunction
+{
+    private static readonly HttpClient s_httpClient = new();
+    private readonly AIFunction _inner = AIFunctionFactory.Create(DownloadUriAsync);
+
+    /// <inheritdoc/>
+    public override string Name => this._inner.Name;
+
+    /// <inheritdoc/>
+    public override string Description => this._inner.Description;
+
+    /// <inheritdoc/>
+    public override JsonElement JsonSchema => this._inner.JsonSchema;
+
+    /// <inheritdoc/>
+    protected override ValueTask<object?> InvokeCoreAsync(
+        AIFunctionArguments arguments,
+        CancellationToken cancellationToken) =>
+        this._inner.InvokeAsync(arguments, cancellationToken);
+
+    [Description("Fetch the html from the given url as markdown")]
+    private static async Task<string> DownloadUriAsync(
+        [Description("The URL to download")] string uri,
+        CancellationToken cancellationToken = default)
+    {
+        if (!Uri.TryCreate(uri, UriKind.Absolute, out Uri? parsedUri))
+        {
+            return $"Error: '{uri}' is not a valid URL.";
+        }
+
+        if (parsedUri.Scheme is not "http" and not "https")
+        {
+            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.
+
+        try
+        {
+            string html = await s_httpClient.GetStringAsync(parsedUri, cancellationToken);
+            return HtmlToMarkdownConverter.Convert(html);
+        }
+        catch (HttpRequestException ex)
+        {
+            return $"Error downloading {uri}: {ex.Message}";
+        }
+    }
+
+    /// <summary>
+    /// A simple HTML to Markdown converter using regex-based transformations.
+    /// Handles the most common HTML elements without requiring external dependencies.
+    /// </summary>
+    private static partial class HtmlToMarkdownConverter
+    {
+        public static string Convert(string html)
+        {
+            // Extract body content if present, otherwise use the full HTML.
+            var bodyMatch = BodyRegex().Match(html);
+            string content = bodyMatch.Success ? bodyMatch.Groups[1].Value : html;
+
+            // Remove script, style, and head blocks.
+            content = ScriptRegex().Replace(content, string.Empty);
+            content = StyleRegex().Replace(content, string.Empty);
+            content = HeadRegex().Replace(content, string.Empty);
+            content = CommentRegex().Replace(content, string.Empty);
+
+            // Convert block elements before inline elements.
+            content = ConvertHeadings(content);
+            content = ConvertCodeBlocks(content);
+            content = ConvertBlockquotes(content);
+            content = ConvertLists(content);
+            content = ConvertHorizontalRules(content);
+
+            // Convert inline elements.
+            content = ConvertLinks(content);
+            content = ConvertImages(content);
+            content = ConvertBold(content);
+            content = ConvertItalic(content);
+            content = ConvertInlineCode(content);
+
+            // Convert structural elements.
+            content = ConvertParagraphs(content);
+            content = ConvertLineBreaks(content);
+
+            // Strip remaining HTML tags.
+            content = StripTagsRegex().Replace(content, string.Empty);
+
+            // Decode HTML entities.
+            content = WebUtility.HtmlDecode(content);
+
+            // Clean up excessive whitespace.
+            content = ExcessiveNewlinesRegex().Replace(content, "\n\n");
+
+            return content.Trim();
+        }
+
+        private static string ConvertHeadings(string html)
+        {
+            html = H1Regex().Replace(html, m => $"\n# {StripInnerTags(m.Groups[1].Value).Trim()}\n");
+            html = H2Regex().Replace(html, m => $"\n## {StripInnerTags(m.Groups[1].Value).Trim()}\n");
+            html = H3Regex().Replace(html, m => $"\n### {StripInnerTags(m.Groups[1].Value).Trim()}\n");
+            html = H4Regex().Replace(html, m => $"\n#### {StripInnerTags(m.Groups[1].Value).Trim()}\n");
+            html = H5Regex().Replace(html, m => $"\n##### {StripInnerTags(m.Groups[1].Value).Trim()}\n");
+            html = H6Regex().Replace(html, m => $"\n###### {StripInnerTags(m.Groups[1].Value).Trim()}\n");
+            return html;
+        }
+
+        private static string ConvertLinks(string html) =>
+            LinkRegex().Replace(html, m =>
+            {
+                string href = m.Groups[1].Value;
+                string text = StripInnerTags(m.Groups[2].Value).Trim();
+
+                // Skip javascript and data links.
+                if (href.StartsWith("javascript:", StringComparison.OrdinalIgnoreCase) ||
+                    href.StartsWith("data:", StringComparison.OrdinalIgnoreCase))
+                {
+                    return text;
+                }
+
+                return string.IsNullOrWhiteSpace(text) ? string.Empty : $"[{text}]({href})";
+            });
+
+        private static string ConvertImages(string html) =>
+            ImageRegex().Replace(html, m =>
+            {
+                string src = m.Groups[1].Value;
+                string alt = m.Groups[2].Value;
+
+                // Truncate data URIs.
+                if (src.StartsWith("data:", StringComparison.OrdinalIgnoreCase))
+                {
+                    src = src.Split(',')[0] + "...";
+                }
+
+                return $"![{alt}]({src})";
+            });
+
+        private static string ConvertBold(string html) =>
+            BoldRegex().Replace(html, m => $"**{m.Groups[2].Value}**");
+
+        private static string ConvertItalic(string html) =>
+            ItalicRegex().Replace(html, m => $"*{m.Groups[2].Value}*");
+
+        private static string ConvertInlineCode(string html) =>
+            InlineCodeRegex().Replace(html, m => $"`{m.Groups[1].Value}`");
+
+        private static string ConvertCodeBlocks(string html) =>
+            CodeBlockRegex().Replace(html, m => $"\n```\n{StripInnerTags(m.Groups[1].Value).Trim()}\n```\n");
+
+        private static string ConvertBlockquotes(string html) =>
+            BlockquoteRegex().Replace(html, m =>
+            {
+                string inner = StripInnerTags(m.Groups[1].Value).Trim();
+                // Prefix each line with "> ".
+                string quoted = string.Join("\n", inner.Split('\n').Select(line => $"> {line.Trim()}"));
+                return $"\n{quoted}\n";
+            });
+
+        private static string ConvertLists(string html)
+        {
+            // Unordered lists.
+            html = UlRegex().Replace(html, m =>
+            {
+                string items = LiRegex().Replace(m.Groups[1].Value, li => $"- {StripInnerTags(li.Groups[1].Value).Trim()}\n");
+                return $"\n{items}";
+            });
+
+            // Ordered lists.
+            html = OlRegex().Replace(html, m =>
+            {
+                int index = 1;
+                string items = LiRegex().Replace(m.Groups[1].Value, li => $"{index++}. {StripInnerTags(li.Groups[1].Value).Trim()}\n");
+                return $"\n{items}";
+            });
+
+            return html;
+        }
+
+        private static string ConvertHorizontalRules(string html) =>
+            HrRegex().Replace(html, "\n---\n");
+
+        private static string ConvertParagraphs(string html) =>
+            ParagraphRegex().Replace(html, m => $"\n\n{m.Groups[1].Value}\n\n");
+
+        private static string ConvertLineBreaks(string html) =>
+            BrRegex().Replace(html, "\n");
+
+        private static string StripInnerTags(string html) =>
+            StripTagsRegex().Replace(html, string.Empty);
+
+        // Source-generated regex patterns for performance and AOT compatibility.
+
+        [GeneratedRegex(@"<body[^>]*>(.*?)</body>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex BodyRegex();
+
+        [GeneratedRegex(@"<script[^>]*>.*?</script>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex ScriptRegex();
+
+        [GeneratedRegex(@"<style[^>]*>.*?</style>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex StyleRegex();
+
+        [GeneratedRegex(@"<head[^>]*>.*?</head>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex HeadRegex();
+
+        [GeneratedRegex(@"<!--.*?-->", RegexOptions.Singleline)]
+        private static partial Regex CommentRegex();
+
+        [GeneratedRegex(@"<h1[^>]*>(.*?)</h1>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex H1Regex();
+
+        [GeneratedRegex(@"<h2[^>]*>(.*?)</h2>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex H2Regex();
+
+        [GeneratedRegex(@"<h3[^>]*>(.*?)</h3>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex H3Regex();
+
+        [GeneratedRegex(@"<h4[^>]*>(.*?)</h4>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex H4Regex();
+
+        [GeneratedRegex(@"<h5[^>]*>(.*?)</h5>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex H5Regex();
+
+        [GeneratedRegex(@"<h6[^>]*>(.*?)</h6>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex H6Regex();
+
+        [GeneratedRegex(@"<a\s[^>]*href=[""']([^""']*)[""'][^>]*>(.*?)</a>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex LinkRegex();
+
+        [GeneratedRegex(@"<img\s[^>]*src=[""']([^""']*)[""'][^>]*?(?:alt=[""']([^""']*)[""'])?[^>]*/?>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex ImageRegex();
+
+        [GeneratedRegex(@"<(strong|b)\b[^>]*>(.*?)</\1>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex BoldRegex();
+
+        [GeneratedRegex(@"<(em|i)\b[^>]*>(.*?)</\1>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex ItalicRegex();
+
+        [GeneratedRegex(@"<code[^>]*>(.*?)</code>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex InlineCodeRegex();
+
+        [GeneratedRegex(@"<pre[^>]*>(.*?)</pre>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex CodeBlockRegex();
+
+        [GeneratedRegex(@"<blockquote[^>]*>(.*?)</blockquote>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex BlockquoteRegex();
+
+        [GeneratedRegex(@"<ul[^>]*>(.*?)</ul>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex UlRegex();
+
+        [GeneratedRegex(@"<ol[^>]*>(.*?)</ol>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex OlRegex();
+
+        [GeneratedRegex(@"<li[^>]*>(.*?)</li>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex LiRegex();
+
+        [GeneratedRegex(@"<hr\s*/?>", RegexOptions.IgnoreCase)]
+        private static partial Regex HrRegex();
+
+        [GeneratedRegex(@"<p[^>]*>(.*?)</p>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex ParagraphRegex();
+
+        [GeneratedRegex(@"<br\s*/?>", RegexOptions.IgnoreCase)]
+        private static partial Regex BrRegex();
+
+        [GeneratedRegex(@"<[^>]+>")]
+        private static partial Regex StripTagsRegex();
+
+        [GeneratedRegex(@"\n{3,}")]
+        private static partial Regex ExcessiveNewlinesRegex();
+    }
+}
@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\Harness_Shared_Console\Harness_Shared_Console.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,106 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to use the SubAgentsProvider to delegate work to sub-agents.
+// A parent agent is given a list of stock tickers and instructed to find the closing price
+// for each ticker on December 31, 2025. It delegates the web searches to a sub-agent
+// equipped with Foundry's hosted web search tool.
+//
+// Special commands:
+//   exit    — End the session.
+
+#pragma warning disable OPENAI001 // Suppress experimental API warnings for Responses API usage.
+#pragma warning disable MAAI001  // Suppress experimental API warnings for Agents AI experiments.
+
+using System.ClientModel.Primitives;
+using Azure.Identity;
+using Harness.Shared.Console;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using OpenAI;
+using OpenAI.Responses;
+
+var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_OPENAI_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5.4";
+
+// --- Sub-agent: Web Search Agent ---
+// This agent can search the web and is used by the parent agent to look up stock prices.
+AIAgent webSearchAgent =
+    new OpenAIClient(
+        new BearerTokenPolicy(new DefaultAzureCredential(), "https://ai.azure.com/.default"),
+        new OpenAIClientOptions()
+        {
+            Endpoint = new Uri(endpoint),
+            RetryPolicy = new ClientRetryPolicy(3)
+        })
+    .GetResponsesClient()
+    .AsIChatClientWithStoredOutputDisabled(deploymentName)
+    .AsAIAgent(
+        new ChatClientAgentOptions
+        {
+            Name = "WebSearchAgent",
+            Description = "An agent that can search the web to find information.",
+            ChatOptions = new ChatOptions
+            {
+                Instructions = "You are a web search assistant. When asked to find information, use the web search tool to look it up and return a concise, factual answer.",
+                Tools =
+                [
+                    ResponseTool.CreateWebSearchTool().AsAITool(),
+                ],
+            },
+        });
+
+// --- Parent agent: Stock Price Researcher ---
+// This agent orchestrates the sub-agent to look up stock prices in parallel.
+var parentInstructions =
+    """
+    You are a stock price research assistant. You have access to a web search sub-agent that can look up information on the web.
+
+    When given a list of stock tickers, your job is to find the closing price for each ticker on December 31, 2025.
+
+    ## Workflow
+
+    1. For each ticker, start a sub-task on the WebSearchAgent asking it to find the closing price on December 31, 2025.
+       - Start all sub-tasks before waiting for any of them to complete, so they run concurrently.
+    2. Wait for all sub-tasks to complete.
+    3. Retrieve the results from each sub-task.
+    4. Present a summary table with the ticker symbol and closing price for each stock.
+    5. Clear all completed tasks to free memory.
+
+    ## Important
+
+    - Always delegate web searches to the WebSearchAgent sub-agent. Do not try to answer from memory.
+    - If a sub-task fails or returns unclear results, continue the task with a more specific query.
+    - Present results in a clean markdown table format.
+    """;
+
+AIAgent parentAgent =
+    new OpenAIClient(
+        new BearerTokenPolicy(new DefaultAzureCredential(), "https://ai.azure.com/.default"),
+        new OpenAIClientOptions()
+        {
+            Endpoint = new Uri(endpoint),
+            RetryPolicy = new ClientRetryPolicy(3)
+        })
+    .GetResponsesClient()
+    .AsIChatClientWithStoredOutputDisabled(deploymentName)
+    .AsAIAgent(
+        new ChatClientAgentOptions
+        {
+            Name = "StockPriceResearcher",
+            Description = "An agent that researches stock prices using sub-agents.",
+            AIContextProviders =
+            [
+                new SubAgentsProvider([webSearchAgent]),
+            ],
+            ChatOptions = new ChatOptions
+            {
+                Instructions = parentInstructions,
+                MaxOutputTokens = 16_000,
+            },
+        });
+
+// Run the interactive console session.
+await HarnessConsole.RunAgentAsync(
+    parentAgent,
+    title: "Stock Price Researcher (SubAgents Demo)",
+    userPrompt: "Enter a list of stock tickers (e.g., BAC, MSFT, BA):");
@@ -0,0 +1,53 @@
+# Harness Step 02 — SubAgents (Stock Price Research)
+
+This sample demonstrates how to use the **SubAgentsProvider** to delegate work from a parent agent to sub-agents.
+
+## What It Does
+
+A parent agent receives a list of stock tickers and uses a web-search sub-agent to find the closing price for each ticker on December 31, 2025. The sub-tasks run concurrently, and results are presented in a summary table.
+
+### Architecture
+
+```
+┌─────────────────────────────────┐
+│     StockPriceResearcher        │
+│         (Parent Agent)          │
+│                                 │
+│  SubAgentsProvider              │
+│    ├─ SubAgents_StartTask       │
+│    ├─ SubAgents_WaitFor...      │
+│    ├─ SubAgents_GetTaskResults  │
+│    └─ ...                       │
+└────────────┬────────────────────┘
+             │  delegates to
+             ▼
+┌─────────────────────────────────┐
+│       WebSearchAgent            │
+│        (Sub-Agent)              │
+│                                 │
+│  Tools:                         │
+│    └─ web_search (Foundry)      │
+└─────────────────────────────────┘
+```
+
+## Prerequisites
+
+- An Azure AI Foundry endpoint with an OpenAI model deployment
+- Set the following environment variables:
+  - `AZURE_FOUNDRY_OPENAI_ENDPOINT` — Your Foundry OpenAI endpoint URL
+  - `AZURE_AI_MODEL_DEPLOYMENT_NAME` — Model deployment name (defaults to `gpt-5.4`)
+
+## Running the Sample
+
+```bash
+cd dotnet/samples/02-agents/Harness/Harness_Step02_Research_WithSubAgents
+dotnet run
+```
+
+When prompted, enter a list of stock tickers such as:
+
+```
+BAC, MSFT, BA
+```
+
+The parent agent will delegate each ticker lookup to the web search sub-agent concurrently and present the results in a table.
@@ -0,0 +1,24 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\Harness_Shared_Console\Harness_Shared_Console.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Content Include="data\**\*" CopyToOutputDirectory="PreserveNewest" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,110 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to use a ChatClientAgent with the FileAccessProvider
+// to give an agent access to a folder of CSV data files. The agent can read, analyze,
+// and extract information from the data, then write results back as new files.
+//
+// The sample includes a pre-populated `data/` folder with sales transaction data.
+// Ask the agent to analyze the data, produce summaries, or create new output files.
+//
+// Special commands:
+//   exit — End the session.
+
+#pragma warning disable OPENAI001 // Suppress experimental API warnings for Responses API usage.
+#pragma warning disable MAAI001  // Suppress experimental API warnings for Agents AI experiments.
+
+using System.ClientModel.Primitives;
+using Azure.Identity;
+using Harness.Shared.Console;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Compaction;
+using Microsoft.Extensions.AI;
+using OpenAI;
+using OpenAI.Responses;
+
+var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_OPENAI_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5.4";
+
+const int MaxContextWindowTokens = 1_050_000;
+const int MaxOutputTokens = 128_000;
+
+// Point the file store at the data/ folder that ships with the sample.
+var dataFolder = Path.Combine(AppContext.BaseDirectory, "data");
+var fileStore = new FileSystemAgentFileStore(dataFolder);
+
+var instructions =
+    """
+    You are a data analyst assistant. You have access to a folder of data files via the FileAccess_* tools.
+
+    ## Getting started
+    - Start by listing available files with FileAccess_ListFiles to see what data is available.
+    - Read the files to understand their structure and contents.
+
+    ## Working with data
+    - When asked to analyze data, read the relevant files first, then perform the analysis.
+    - Show your analysis clearly with tables, summaries, and key insights.
+    - When calculations are needed, work through them step by step and show your reasoning.
+
+    ## Writing output
+    - When asked to produce output files (e.g., reports, summaries, filtered data), use FileAccess_SaveFile to write them.
+    - Use appropriate file formats: CSV for tabular data, Markdown for reports.
+    - Confirm what you wrote and where.
+
+    ## Important
+    - Never modify or delete the original input data files unless explicitly asked to do so.
+    - If asked about data you haven't read yet, read it first before answering.
+    - Always explain your reasoning and thought process as you work through tasks.
+    - Always explain what you learned and what you are going to do next between tool calls, so the user can follow along with your thought process.
+    """;
+
+// Create a compaction strategy based on the model's context window.
+var compactionStrategy = new ContextWindowCompactionStrategy(
+    maxContextWindowTokens: MaxContextWindowTokens,
+    maxOutputTokens: MaxOutputTokens);
+
+AIAgent agent =
+    new OpenAIClient(
+        new BearerTokenPolicy(new DefaultAzureCredential(), "https://ai.azure.com/.default"),
+        new OpenAIClientOptions()
+        {
+            Endpoint = new Uri(endpoint),
+            RetryPolicy = new ClientRetryPolicy(3)
+        })
+    .GetResponsesClient()
+    .AsIChatClientWithStoredOutputDisabled(deploymentName)
+
+    .AsBuilder()
+    .UseFunctionInvocation()
+    .UsePerServiceCallChatHistoryPersistence()
+    .UseAIContextProviders(new CompactionProvider(compactionStrategy))
+
+    .BuildAIAgent(
+        new ChatClientAgentOptions
+        {
+            Name = "DataAnalyst",
+            Description = "A data analyst assistant that reads, analyzes, and processes data files.",
+            UseProvidedChatClientAsIs = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
+            ChatHistoryProvider = new InMemoryChatHistoryProvider(
+                new InMemoryChatHistoryProviderOptions
+                {
+                    ChatReducer = compactionStrategy.AsChatReducer(),
+                }),
+            AIContextProviders =
+            [
+                new FileAccessProvider(fileStore),
+            ],
+            ChatOptions = new ChatOptions
+            {
+                Instructions = instructions,
+                MaxOutputTokens = MaxOutputTokens,
+            },
+        })
+    .AsBuilder()
+    .Build();
+
+// Run the interactive console session.
+await HarnessConsole.RunAgentAsync(
+    agent,
+    title: "Data Processing Assistant",
+    userPrompt: "Ask me to analyze the data files, produce summaries, or create output files.");
@@ -0,0 +1,65 @@
+# What this sample demonstrates
+
+This sample demonstrates how to use a `ChatClientAgent` with the `FileAccessProvider` to give an agent access to a folder of data files for reading, analyzing, and writing results.
+
+Key features showcased:
+
+- **FileAccessProvider** — gives the agent tools to read, write, list, search, and delete files in a shared data folder
+- **CSV data processing** — the agent reads sales transaction data and performs analysis on demand
+- **Output file creation** — the agent can write summaries, filtered data, or reports back to the data folder
+- **Streaming output** — responses are streamed token-by-token for a natural experience
+- **No planning mode** — this is a simple conversational sample focused on data interaction
+
+## Prerequisites
+
+Before running this sample, ensure you have:
+
+1. An Azure AI Foundry project with a deployed model (e.g., `gpt-5.4`)
+2. Azure CLI installed and authenticated (`az login`)
+
+## Environment Variables
+
+Set the following environment variables:
+
+```bash
+# Required: Your Azure AI Foundry OpenAI endpoint
+export AZURE_FOUNDRY_OPENAI_ENDPOINT="https://your-project.services.ai.azure.com/openai/v1/"
+
+# Optional: Model deployment name (defaults to gpt-5.4)
+export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-5.4"
+```
+
+## Running the Sample
+
+```bash
+cd dotnet
+dotnet run --project samples/02-agents/Harness/Harness_Step03_DataProcessing
+```
+
+## What to Expect
+
+The sample starts an interactive conversation with a data analyst agent. The `data/` folder contains a `sales.csv` file with ~50 rows of sales transaction data (date, product, category, quantity, unit price, region, salesperson).
+
+You can ask the agent to:
+
+1. **List available files** — "What files do you have?"
+2. **Analyze the data** — "What are the total sales by region?" or "Which salesperson has the highest revenue?"
+3. **Create output files** — "Create a summary report as a markdown file" or "Write a CSV with monthly totals"
+4. **Search for patterns** — "Find all transactions over $1000"
+5. **Type `exit`** — to end the session
+
+E.g. try the following prompt `Please process the sales.csv file by first filtering it to only North region sales, and then calculating the sum of sales by person. I'd like to write the results of the processing to north_region_totals.csv`.
+
+## Sample Data
+
+The included `data/sales.csv` contains sales transactions from January to March 2025 with the following columns:
+
+| Column | Description |
+| --- | --- |
+| `date` | Transaction date (YYYY-MM-DD) |
+| `product` | Product name |
+| `category` | Product category (Electronics, Furniture, Stationery) |
+| `quantity` | Units sold |
+| `unit_price` | Price per unit |
+| `region` | Sales region (North, South, West) |
+| `salesperson` | Name of the salesperson |
@@ -0,0 +1,50 @@
+date,product,category,quantity,unit_price,region,salesperson
+2025-01-03,Laptop Pro 15,Electronics,2,1299.99,North,Alice
+2025-01-05,Ergonomic Chair,Furniture,5,349.50,South,Bob
+2025-01-07,Wireless Mouse,Electronics,12,24.99,North,Alice
+2025-01-08,Standing Desk,Furniture,1,599.00,West,Carol
+2025-01-10,USB-C Hub,Electronics,8,45.99,North,David
+2025-01-12,Monitor 27in,Electronics,3,429.00,South,Bob
+2025-01-14,Desk Lamp,Furniture,6,79.95,West,Carol
+2025-01-15,Keyboard Mech,Electronics,4,149.99,North,Alice
+2025-01-17,Filing Cabinet,Furniture,2,189.00,South,David
+2025-01-20,Webcam HD,Electronics,10,89.99,West,Bob
+2025-01-22,Laptop Pro 15,Electronics,1,1299.99,South,Carol
+2025-01-24,Ergonomic Chair,Furniture,3,349.50,North,Alice
+2025-01-25,Notebook Pack,Stationery,20,12.99,South,David
+2025-01-27,Wireless Mouse,Electronics,15,24.99,West,Carol
+2025-01-28,Whiteboard,Stationery,4,129.00,North,Bob
+2025-01-30,Standing Desk,Furniture,2,599.00,South,Alice
+2025-02-02,USB-C Hub,Electronics,6,45.99,West,David
+2025-02-04,Monitor 27in,Electronics,2,429.00,North,Carol
+2025-02-05,Desk Lamp,Furniture,8,79.95,South,Bob
+2025-02-07,Keyboard Mech,Electronics,5,149.99,West,Alice
+2025-02-09,Filing Cabinet,Furniture,1,189.00,North,David
+2025-02-11,Webcam HD,Electronics,7,89.99,South,Carol
+2025-02-13,Laptop Pro 15,Electronics,3,1299.99,West,Bob
+2025-02-15,Notebook Pack,Stationery,30,12.99,North,Alice
+2025-02-17,Ergonomic Chair,Furniture,4,349.50,South,David
+2025-02-19,Wireless Mouse,Electronics,20,24.99,North,Carol
+2025-02-20,Whiteboard,Stationery,2,129.00,West,Bob
+2025-02-22,Standing Desk,Furniture,1,599.00,North,Alice
+2025-02-24,USB-C Hub,Electronics,10,45.99,South,David
+2025-02-26,Monitor 27in,Electronics,4,429.00,West,Carol
+2025-02-28,Desk Lamp,Furniture,3,79.95,North,Bob
+2025-03-02,Keyboard Mech,Electronics,6,149.99,South,Alice
+2025-03-04,Filing Cabinet,Furniture,3,189.00,West,David
+2025-03-06,Webcam HD,Electronics,9,89.99,North,Carol
+2025-03-08,Laptop Pro 15,Electronics,2,1299.99,South,Bob
+2025-03-10,Notebook Pack,Stationery,25,12.99,West,Alice
+2025-03-12,Ergonomic Chair,Furniture,6,349.50,North,David
+2025-03-14,Wireless Mouse,Electronics,18,24.99,South,Carol
+2025-03-15,Whiteboard,Stationery,5,129.00,North,Bob
+2025-03-17,Standing Desk,Furniture,3,599.00,West,Alice
+2025-03-19,USB-C Hub,Electronics,7,45.99,North,David
+2025-03-21,Monitor 27in,Electronics,5,429.00,South,Carol
+2025-03-23,Desk Lamp,Furniture,4,79.95,West,Bob
+2025-03-25,Keyboard Mech,Electronics,3,149.99,North,Alice
+2025-03-27,Filing Cabinet,Furniture,2,189.00,South,David
+2025-03-28,Webcam HD,Electronics,11,89.99,West,Carol
+2025-03-29,Laptop Pro 15,Electronics,1,1299.99,North,Bob
+2025-03-30,Notebook Pack,Stationery,15,12.99,South,Alice
+2025-03-31,Ergonomic Chair,Furniture,2,349.50,West,David
@@ -0,0 +1,11 @@
+# Harness Agent Samples
+
+Samples demonstrating the [Harness AIContextProviders](../../../src/Microsoft.Agents.AI/Harness/) — reusable providers that add planning, task management, and mode tracking to any `ChatClientAgent`.
+
+## Samples
+
+| Sample | Description |
+| --- | --- |
+| [Harness_Step01_Research](./Harness_Step01_Research/README.md) | Using a ChatClientAgent with TodoProvider and AgentModeProvider for research, showcasing planning mode and todo management |
+| [Harness_Step02_Research_WithSubAgents](./Harness_Step02_Research_WithSubAgents/README.md) | Using SubAgentsProvider to delegate stock price lookups to a web-search sub-agent concurrently |
+| [Harness_Step03_DataProcessing](./Harness_Step03_DataProcessing/README.md) | Using FileAccessProvider to give an agent access to CSV data files for reading, analysis, and output generation |
@@ -16,6 +16,7 @@ The getting started samples demonstrate the fundamental concepts and functionali
 | [Agent With Anthropic](./AgentWithAnthropic/README.md) | Getting started with agents using Anthropic Claude |
 | [Model Context Protocol](./ModelContextProtocol/README.md) | Getting started with Model Context Protocol |
 | [Agent Skills](./AgentSkills/README.md) | Getting started with Agent Skills |
+| [Agent Harness with built-in tools](./Harness/README.md) | Demonstrating how to build an Agent Harness with built-in planning, todo, and mode management tooling |
 | [Declarative Agents](./DeclarativeAgents) | Loading and executing AI agents from YAML configuration files |
 | [AG-UI](./AGUI/README.md) | Getting started with AG-UI (Agent UI Protocol) servers and clients |
 | [Dev UI](./DevUI/README.md) | Interactive web interface for testing and debugging AI agents during development |
@@ -0,0 +1,38 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <InjectIsExternalInitOnLegacy>true</InjectIsExternalInitOnLegacy>
+    <InjectSharedFoundryAgents>true</InjectSharedFoundryAgents>
+    <InjectSharedWorkflowsExecution>true</InjectSharedWorkflowsExecution>
+    <InjectSharedWorkflowsSettings>true</InjectSharedWorkflowsSettings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Configuration" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
+    <PackageReference Include="Microsoft.Extensions.Logging" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative\Microsoft.Agents.AI.Workflows.Declarative.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative.Foundry\Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="InvokeHttpRequest.yaml">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,76 @@
+#
+# This workflow demonstrates using HttpRequestAction to call a REST API directly
+# from the workflow without going through an AI agent first.
+#
+# HttpRequestAction allows workflows to:
+# - Fetch data from external HTTP endpoints
+# - Store the parsed response in workflow variables for later use
+# - Add the response body to the conversation so a downstream agent can
+#   answer questions based on it
+#
+# This sample fetches public metadata for the dotnet/runtime repository from
+# the GitHub REST API (no authentication required) and uses an agent to
+# answer follow-up questions about it.
+#
+# Example input:
+# How many subscribers does the repository have?
+#
+kind: Workflow
+trigger:
+
+  kind: OnConversationStart
+  id: workflow_invoke_http_request_demo
+  actions:
+
+    # Capture the original user message for input to the follow-up agent.
+    - kind: SetVariable
+      id: set_user_message
+      variable: Local.InputMessage
+      value: =System.LastMessage
+
+    # Set the repository org/name used to form the request URL.
+    - kind: SetVariable
+      id: set_repo_name
+      variable: Local.RepoName
+      value: microsoft/agent-framework
+
+    # Invoke the GitHub repo API. The response body is parsed into Local.RepoInfo
+    # and also added to the conversation (via conversationId) so the agent below
+    # can answer questions based on it.
+    - kind: HttpRequestAction
+      id: fetch_repo_info
+      conversationId: =System.ConversationId
+      method: GET
+      url: =Concatenate("https://api.github.com/repos/", Local.RepoName)
+      headers:
+        Accept: application/vnd.github+json
+        User-Agent: agent-framework-sample
+      response: Local.RepoInfo
+
+    # Display a confirmation message showing key fields from the parsed response.
+    - kind: SendMessage
+      id: show_repo_summary
+      message: "Fetched repo: visibility={Local.RepoInfo.visibility}, description={Local.RepoInfo.description}"
+
+    # Use the agent to summarize the repo using the conversation context.
+    - kind: InvokeAzureAgent
+      id: summarize_repo
+      conversationId: =System.ConversationId
+      agent:
+        name: GitHubRepoInfoAgent
+      input:
+        messages: =UserMessage("Please provide a brief summary of this GitHub repository based on the data already in the conversation.")
+      output:
+        autoSend: true
+        messages: Local.AgentResponse
+
+    # Allow the user to ask follow-up questions about the repo in a loop.
+    - kind: InvokeAzureAgent
+      id: invoke_followup
+      conversationId: =System.ConversationId
+      agent:
+        name: GitHubRepoInfoAgent
+      input:
+        messages: =Local.InputMessage
+        externalLoop:
+          when: =Upper(System.LastMessage.Text) <> "EXIT"
@@ -0,0 +1,95 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Azure.Identity;
+using Microsoft.Agents.AI.Workflows.Declarative;
+using Microsoft.Extensions.Configuration;
+using Shared.Foundry;
+using Shared.Workflows;
+
+namespace Demo.Workflows.Declarative.InvokeHttpRequest;
+
+/// <summary>
+/// Demonstrates a workflow that uses HttpRequestAction to call a REST API
+/// directly from the workflow.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The HttpRequestAction allows workflows to issue HTTP requests and:
+/// </para>
+/// <list type="bullet">
+/// <item>Fetch data from external REST endpoints</item>
+/// <item>Store the parsed response in workflow variables</item>
+/// <item>Add the response body to the conversation so an agent can answer
+///       questions based on it</item>
+/// </list>
+/// <para>
+/// This sample fetches public metadata for the dotnet/runtime repository from
+/// the GitHub REST API (no authentication required) and uses a Foundry agent
+/// to answer follow-up questions about it. Type "EXIT" to end the conversation.
+/// </para>
+/// <para>
+/// See the README.md file in the parent folder (../README.md) for detailed
+/// information about the configuration required to run this sample.
+/// </para>
+/// </remarks>
+internal sealed class Program
+{
+    public static async Task Main(string[] args)
+    {
+        // Initialize configuration
+        IConfiguration configuration = Application.InitializeConfig();
+        Uri foundryEndpoint = new(configuration.GetValue(Application.Settings.FoundryEndpoint));
+
+        // Ensure sample agent exists in Foundry. The agent has no tools - it answers
+        // questions about the GitHub repository using only the JSON data that the
+        // HttpRequestAction adds to the conversation.
+        await CreateAgentAsync(foundryEndpoint, configuration);
+
+        // Get input from command line or console
+        string workflowInput = Application.GetInput(args);
+
+        // The default HttpRequestHandler is sufficient for this sample because the
+        // GitHub REST endpoint used here does not require authentication. For
+        // authenticated endpoints, supply a custom Func<HttpRequestInfo, ..., HttpClient?>
+        // to DefaultHttpRequestHandler so each request can be routed through a
+        // pre-configured (cached) HttpClient with the appropriate credentials.
+        await using DefaultHttpRequestHandler httpRequestHandler = new();
+
+        // Create the workflow factory with the HTTP request handler
+        WorkflowFactory workflowFactory = new("InvokeHttpRequest.yaml", foundryEndpoint)
+        {
+            HttpRequestHandler = httpRequestHandler
+        };
+
+        // Execute the workflow
+        WorkflowRunner runner = new() { UseJsonCheckpoints = true };
+        await runner.ExecuteAsync(workflowFactory.CreateWorkflow, workflowInput);
+    }
+
+    private static async Task CreateAgentAsync(Uri foundryEndpoint, IConfiguration configuration)
+    {
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        AIProjectClient aiProjectClient = new(foundryEndpoint, new DefaultAzureCredential());
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "GitHubRepoInfoAgent",
+            agentDefinition: DefineAgent(configuration),
+            agentDescription: "Answers questions about a GitHub repository using HTTP response data in the conversation");
+    }
+
+    private static DeclarativeAgentDefinition DefineAgent(IConfiguration configuration)
+    {
+        return new DeclarativeAgentDefinition(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                Answer the user's questions about the GitHub repository using only the
+                JSON data already present in the conversation history.
+                If the answer is not contained in the conversation, say so plainly
+                rather than guessing. Be concise and helpful.
+                """
+        };
+    }
+}
@@ -65,6 +65,53 @@ Workflow orchestration started for CancelOrder. Orchestration runId: abc123def45
 >
 > If not provided, a unique run ID is auto-generated.

+### Wait for the Workflow Result
+
+By default, the HTTP endpoint returns `202 Accepted` immediately with the run ID. If you want to wait for the workflow to complete and get the result in the response, add the `x-ms-wait-for-response: true` header:
+
+Bash (Linux/macOS/WSL):
+
+```bash
+curl -X POST http://localhost:7071/api/workflows/CancelOrder/run \
+    -H "Content-Type: text/plain" \
+    -H "x-ms-wait-for-response: true" \
+    -d "12345"
+```
+
+PowerShell:
+
+```powershell
+Invoke-RestMethod -Method Post `
+    -Uri http://localhost:7071/api/workflows/CancelOrder/run `
+    -ContentType text/plain `
+    -Headers @{ "x-ms-wait-for-response" = "true" } `
+    -Body "12345"
+```
+
+The response will contain the workflow result as plain text (200 OK):
+
+```text
+Cancellation email sent for order 12345 to jerry@example.com.
+```
+
+To get the result as JSON, also include the `Accept: application/json` header:
+
+```bash
+curl -X POST http://localhost:7071/api/workflows/CancelOrder/run \
+    -H "Content-Type: text/plain" \
+    -H "x-ms-wait-for-response: true" \
+    -H "Accept: application/json" \
+    -d "12345"
+```
+
+```json
+{
+    "runId": "abc123def456",
+    "workflowStatus": "Completed",
+    "result": "Cancellation email sent for order 12345 to jerry@example.com."
+}
+```
+
 In the function app logs, you will see the sequential execution of each executor:

 ```text
@@ -7,6 +7,21 @@ Content-Type: text/plain

 12345

+### Cancel an order and wait for the result
+POST {{authority}}/api/workflows/CancelOrder/run
+Content-Type: text/plain
+x-ms-wait-for-response: true
+
+12345
+
+### Cancel an order and wait for the result (JSON response)
+POST {{authority}}/api/workflows/CancelOrder/run
+Content-Type: text/plain
+Accept: application/json
+x-ms-wait-for-response: true
+
+12345
+
 ### Cancel an order with a custom run ID
 POST {{authority}}/api/workflows/CancelOrder/run?runId=my-custom-id-123
 Content-Type: text/plain
@@ -19,6 +34,13 @@ Content-Type: text/plain

 12345

+### Get order status and wait for the result
+POST {{authority}}/api/workflows/OrderStatus/run
+Content-Type: text/plain
+x-ms-wait-for-response: true
+
+12345
+
 ### Batch cancel orders with a complex JSON input
 POST {{authority}}/api/workflows/BatchCancelOrders/run
 Content-Type: application/json
@@ -13,6 +13,8 @@
  <ItemGroup>
    <PackageReference Include="Azure.AI.AgentServer.Invocations" />
    <PackageReference Include="DotNetEnv" />
+    <PackageReference Include="OpenTelemetry.Api" />
+    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" />
  </ItemGroup>

  <!-- For contributors: uses ProjectReference to build against local source -->
@@ -0,0 +1,57 @@
+// 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();
+    }
+}
@@ -297,6 +297,7 @@ public class AgentFrameworkResponseHandler : ResponseHandler
            var agent = this._serviceProvider.GetKeyedService<AIAgent>(agentName);
            if (agent is not null)
            {
+                FoundryHostingExtensions.TryApplyUserAgent(agent);
                return FoundryHostingExtensions.ApplyOpenTelemetry(agent);
            }

@@ -310,12 +311,13 @@ public class AgentFrameworkResponseHandler : ResponseHandler
        var defaultAgent = this._serviceProvider.GetService<AIAgent>();
        if (defaultAgent is not null)
        {
+            FoundryHostingExtensions.TryApplyUserAgent(defaultAgent);
            return FoundryHostingExtensions.ApplyOpenTelemetry(defaultAgent);
        }

        var errorMessage = string.IsNullOrEmpty(agentName)
            ? "No agent name specified in the request (via agent.name or metadata[\"entity_id\"]) and no default AIAgent is registered."
-            : $"Agent '{agentName}' not found. Ensure it is registered via AddAIAgent(\"{agentName}\", ...) or as a default AIAgent.";
+            : $"Agent '{agentName}' not found. Ensure it is registered via AddFoundryResponses(services, agent) or services.AddKeyedSingleton<AIAgent>(\"{agentName}\", ...).";

        throw new InvalidOperationException(errorMessage);
    }
@@ -352,7 +354,7 @@ public class AgentFrameworkResponseHandler : ResponseHandler

        var errorMessage = string.IsNullOrEmpty(agentName)
            ? "No agent name specified in the request (via agent.name or metadata[\"entity_id\"]) and no default AgentSessionStore is registered."
-            : $"Agent '{agentName}' not found. Ensure it is registered via AddAIAgent(\"{agentName}\", ...) or as a default AgentSessionStore.";
+            : $"AgentSessionStore for agent '{agentName}' not found. Ensure it is registered via AddFoundryResponses(services, agent, agentSessionStore) or services.AddKeyedSingleton<AgentSessionStore>(\"{agentName}\", ...).";

        throw new InvalidOperationException(errorMessage);
    }
@@ -0,0 +1,223 @@
+// 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
+}
@@ -0,0 +1,84 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ClientModel.Primitives;
+using System.Collections.Generic;
+using System.Reflection;
+using System.Threading.Tasks;
+
+namespace Microsoft.Agents.AI.Foundry.Hosting;
+
+/// <summary>
+/// Pipeline policy that appends the hosted-agent <c>User-Agent</c> segment
+/// (e.g. <c>"foundry-hosting/agent-framework-dotnet/{version}"</c>) to outgoing requests.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The supplement value is computed once from the Microsoft.Agents.AI.Foundry.Hosting
+/// assembly's informational version. The policy is idempotent on retries: if the segment
+/// 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.
+/// </para>
+/// </remarks>
+internal sealed class HostedAgentUserAgentPolicy : PipelinePolicy
+{
+    public static HostedAgentUserAgentPolicy Instance { get; } = new HostedAgentUserAgentPolicy();
+
+    private static readonly string s_supplementValue = CreateSupplementValue();
+
+    public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+    {
+        AppendHeader(message);
+        ProcessNext(message, pipeline, currentIndex);
+    }
+
+    public override async ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+    {
+        AppendHeader(message);
+        await ProcessNextAsync(message, pipeline, currentIndex).ConfigureAwait(false);
+    }
+
+    private static void AppendHeader(PipelineMessage message)
+    {
+        if (message.Request.Headers.TryGetValue("User-Agent", out var existing) && !string.IsNullOrEmpty(existing))
+        {
+            // Guard against double-append on retries or when the policy
+            // is registered on multiple pipeline positions.
+            if (existing.Contains(s_supplementValue))
+            {
+                return;
+            }
+
+            message.Request.Headers.Set("User-Agent", $"{existing} {s_supplementValue}");
+        }
+        else
+        {
+            message.Request.Headers.Set("User-Agent", s_supplementValue);
+        }
+    }
+
+    private static string CreateSupplementValue()
+    {
+        const string Name = "foundry-hosting/agent-framework-dotnet";
+
+        if (typeof(HostedAgentUserAgentPolicy).Assembly.GetCustomAttribute<AssemblyInformationalVersionAttribute>()?.InformationalVersion is string version)
+        {
+            int pos = version.IndexOf('+');
+            if (pos >= 0)
+            {
+                version = version.Substring(0, pos);
+            }
+
+            if (version.Length > 0)
+            {
+                return $"{Name}/{version}";
+            }
+        }
+
+        return Name;
+    }
+}
@@ -237,7 +237,7 @@ internal static class InputConverter
        {
            OutputItemMessage msg => ConvertOutputItemMessageToChat(msg),
            OutputItemFunctionToolCall funcCall => ConvertOutputItemFunctionCall(funcCall),
-            FunctionToolCallOutputResource funcOutput => ConvertFunctionToolCallOutputResource(funcOutput),
+            OutputItemFunctionToolCallOutput funcOutput => ConvertFunctionToolCallOutput(funcOutput),
            OutputItemReasoningItem => null,
            _ => null
        };
@@ -332,7 +332,7 @@ internal static class InputConverter
            [new FunctionCallContent(funcCall.CallId, funcCall.Name, arguments)]);
    }

-    private static ChatMessage ConvertFunctionToolCallOutputResource(FunctionToolCallOutputResource funcOutput)
+    private static ChatMessage ConvertFunctionToolCallOutput(OutputItemFunctionToolCallOutput funcOutput)
    {
        return new ChatMessage(
            ChatRole.Tool,
@@ -34,6 +34,7 @@
    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
    <PackageReference Include="Azure.Identity" />
    <PackageReference Include="ModelContextProtocol" />
+    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" />
  </ItemGroup>

  <ItemGroup>
@@ -43,7 +44,7 @@
  </ItemGroup>

  <ItemGroup>
-    <InternalsVisibleTo Include="Microsoft.Agents.AI.Foundry.UnitTests" />
+    <InternalsVisibleTo Include="Microsoft.Agents.AI.Foundry.Hosting.UnitTests" />
    <InternalsVisibleTo Include="DynamicProxyGenAssembly2" />
  </ItemGroup>

@@ -251,16 +251,25 @@ internal static class OutputConverter
        var outputTokens = details.OutputTokenCount ?? 0;
        var totalTokens = details.TotalTokenCount ?? 0;

+        var cachedTokens = details.AdditionalCounts?.TryGetValue("InputTokenDetails.CachedTokenCount", out var cached) ?? false
+            ? cached : 0;
+        var reasoningTokens = details.AdditionalCounts?.TryGetValue("OutputTokenDetails.ReasoningTokenCount", out var reasoning) ?? false
+            ? reasoning : 0;
+
        if (existing is not null)
        {
            inputTokens += existing.InputTokens;
            outputTokens += existing.OutputTokens;
            totalTokens += existing.TotalTokens;
+            cachedTokens += existing.InputTokensDetails?.CachedTokens ?? 0;
+            reasoningTokens += existing.OutputTokensDetails?.ReasoningTokens ?? 0;
        }

-        return AzureAIAgentServerResponsesModelFactory.ResponseUsage(
+        return new ResponseUsage(
            inputTokens: inputTokens,
+            inputTokensDetails: new ResponseUsageInputTokensDetails(cachedTokens),
            outputTokens: outputTokens,
+            outputTokensDetails: new ResponseUsageOutputTokensDetails(reasoningTokens),
            totalTokens: totalTokens);
    }

@@ -3,16 +3,15 @@
 using System;
 using System.Diagnostics.CodeAnalysis;
 using System.Reflection;
-using System.Threading.Tasks;
 using Azure.AI.AgentServer.Responses;
 using Azure.Core;
 using Azure.Identity;
-using Microsoft.AspNetCore.Builder;
-using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Routing;
+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;

@@ -36,7 +35,7 @@ public static class FoundryHostingExtensions
    /// <para>
    /// Example:
    /// <code>
-    /// builder.AddAIAgent("my-agent", ...);
+    /// builder.Services.AddKeyedSingleton&lt;AIAgent&gt;("my-agent", myAgent);
    /// builder.Services.AddFoundryResponses();
    ///
    /// var app = builder.Build();
@@ -181,13 +180,6 @@ public static class FoundryHostingExtensions
    {
        ArgumentNullException.ThrowIfNull(endpoints);
        endpoints.MapResponsesServer(prefix);
-
-        if (endpoints is IApplicationBuilder app)
-        {
-            // Ensure the middleware is added to the pipeline
-            app.UseMiddleware<AgentFrameworkUserAgentMiddleware>();
-        }
-
        return endpoints;
    }

@@ -216,46 +208,85 @@ public static class FoundryHostingExtensions
                    .Build();
    }

-    private sealed class AgentFrameworkUserAgentMiddleware(RequestDelegate next)
+    /// <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.
+    /// </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>
+    /// </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.
+    /// </para>
+    /// </remarks>
+    internal static AIAgent TryApplyUserAgent(AIAgent agent)
    {
-        private static readonly string s_userAgentValue = CreateUserAgentValue();
-
-        public async Task InvokeAsync(HttpContext context)
+        var chatClient = agent.GetService<IChatClient>();
+        if (chatClient is null)
        {
-            var headers = context.Request.Headers;
-            var userAgent = headers.UserAgent.ToString();
-
-            if (string.IsNullOrEmpty(userAgent))
-            {
-                headers.UserAgent = s_userAgentValue;
-            }
-            else if (!userAgent.Contains(s_userAgentValue, StringComparison.OrdinalIgnoreCase))
-            {
-                headers.UserAgent = $"{userAgent} {s_userAgentValue}";
-            }
-
-            await next(context).ConfigureAwait(false);
+            return agent;
        }

-        private static string CreateUserAgentValue()
+        var meaiType = s_meaiResponsesChatClientType;
+        if (meaiType is null)
        {
-            const string Name = "agent-framework-dotnet";
-
-            if (typeof(AgentFrameworkUserAgentMiddleware).Assembly.GetCustomAttribute<AssemblyInformationalVersionAttribute>()?.InformationalVersion is string version)
-            {
-                int pos = version.IndexOf('+');
-                if (pos >= 0)
-                {
-                    version = version.Substring(0, pos);
-                }
-
-                if (version.Length > 0)
-                {
-                    return $"{Name}/{version}";
-                }
-            }
-
-            return Name;
+            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);
 }
@@ -0,0 +1,113 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.ClientModel;
+using System.ClientModel.Primitives;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+using OpenAI;
+using OpenAI.Responses;
+
+#pragma warning disable OPENAI001, SCME0001
+
+namespace Microsoft.Agents.AI.Foundry.Hosting;
+
+/// <summary>
+/// A <see cref="ResponsesClient"/> subclass that delegates every protocol-level request to a
+/// wrapped <see cref="ResponsesClient"/>. Before each call, a
+/// <see cref="HostedAgentUserAgentPolicy"/> is added to the per-call
+/// <see cref="RequestOptions"/> so the wrapped client's pipeline appends the hosted-agent
+/// <c>User-Agent</c> segment on the wire.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The streaming overloads MEAI binds via reflection (<c>internal CreateResponseStreamingAsync(CreateResponseOptions, RequestOptions)</c>
+/// and <c>internal GetResponseStreamingAsync(GetResponseOptions, RequestOptions)</c>) bottom out
+/// in calls to the public-virtual non-streaming protocol overloads on <see langword="this"/>. Overriding those
+/// non-streaming overloads is therefore sufficient to intercept both streaming and non-streaming traffic.
+/// </para>
+/// <para>
+/// The base pipeline supplied to <see cref="ResponsesClient(ClientPipeline, OpenAIClientOptions)"/>
+/// is a dummy pipeline whose terminal transport throws if invoked. Every override on this class
+/// delegates to the inner client BEFORE any code path reaches <see cref="ResponsesClient.Pipeline"/>, so the dummy is
+/// never expected to run; the throwing transport surfaces any unexpected escape route loudly.
+/// </para>
+/// </remarks>
+internal sealed class UserAgentResponsesClient : ResponsesClient
+{
+    private readonly ResponsesClient _inner;
+
+    public UserAgentResponsesClient(ResponsesClient inner)
+        : base(BuildDummyPipeline(), new OpenAIClientOptions { Endpoint = inner?.Endpoint })
+    {
+        this._inner = inner ?? throw new ArgumentNullException(nameof(inner));
+    }
+
+    public override async Task<ClientResult> CreateResponseAsync(BinaryContent content, RequestOptions? options = null)
+        => await this._inner.CreateResponseAsync(content, AddUserAgentPolicy(options)).ConfigureAwait(false);
+
+    public override ClientResult CreateResponse(BinaryContent content, RequestOptions? options = null)
+        => this._inner.CreateResponse(content, AddUserAgentPolicy(options));
+
+    public override async Task<ClientResult> GetResponseAsync(string responseId, IEnumerable<IncludedResponseProperty>? include, bool? stream, int? startingAfter, bool? includeObfuscation, RequestOptions options)
+        => await this._inner.GetResponseAsync(responseId, include, stream, startingAfter, includeObfuscation, AddUserAgentPolicy(options)).ConfigureAwait(false);
+
+    public override ClientResult GetResponse(string responseId, IEnumerable<IncludedResponseProperty>? include, bool? stream, int? startingAfter, bool? includeObfuscation, RequestOptions options)
+        => this._inner.GetResponse(responseId, include, stream, startingAfter, includeObfuscation, AddUserAgentPolicy(options));
+
+    public override async Task<ClientResult> DeleteResponseAsync(string responseId, RequestOptions options)
+        => await this._inner.DeleteResponseAsync(responseId, AddUserAgentPolicy(options)).ConfigureAwait(false);
+
+    public override ClientResult DeleteResponse(string responseId, RequestOptions options)
+        => this._inner.DeleteResponse(responseId, AddUserAgentPolicy(options));
+
+    public override async Task<ClientResult> CancelResponseAsync(string responseId, RequestOptions options)
+        => await this._inner.CancelResponseAsync(responseId, AddUserAgentPolicy(options)).ConfigureAwait(false);
+
+    public override ClientResult CancelResponse(string responseId, RequestOptions options)
+        => this._inner.CancelResponse(responseId, AddUserAgentPolicy(options));
+
+    public override async Task<ClientResult> GetInputTokenCountAsync(string contentType, BinaryContent content, RequestOptions? options = null)
+        => await this._inner.GetInputTokenCountAsync(contentType, content, AddUserAgentPolicy(options)).ConfigureAwait(false);
+
+    public override ClientResult GetInputTokenCount(string contentType, BinaryContent content, RequestOptions? options = null)
+        => this._inner.GetInputTokenCount(contentType, content, AddUserAgentPolicy(options));
+
+    public override async Task<ClientResult> CompactResponseAsync(string contentType, BinaryContent content, RequestOptions? options = null)
+        => await this._inner.CompactResponseAsync(contentType, content, AddUserAgentPolicy(options)).ConfigureAwait(false);
+
+    public override ClientResult CompactResponse(string contentType, BinaryContent content, RequestOptions? options = null)
+        => this._inner.CompactResponse(contentType, content, AddUserAgentPolicy(options));
+
+    public override async Task<ClientResult> GetResponseInputItemCollectionPageAsync(string responseId, int? limit, string order, string after, string before, RequestOptions options)
+        => await this._inner.GetResponseInputItemCollectionPageAsync(responseId, limit, order, after, before, AddUserAgentPolicy(options)).ConfigureAwait(false);
+
+    public override ClientResult GetResponseInputItemCollectionPage(string responseId, int? limit, string order, string after, string before, RequestOptions options)
+        => this._inner.GetResponseInputItemCollectionPage(responseId, limit, order, after, before, AddUserAgentPolicy(options));
+
+    private static RequestOptions AddUserAgentPolicy(RequestOptions? options)
+    {
+        options ??= new RequestOptions();
+        options.AddPolicy(HostedAgentUserAgentPolicy.Instance, PipelinePosition.PerCall);
+        return options;
+    }
+
+    private static ClientPipeline BuildDummyPipeline()
+    {
+        var options = new ClientPipelineOptions
+        {
+            Transport = new ThrowingTransport(),
+        };
+        return ClientPipeline.Create(options, default, default, default);
+    }
+
+    private sealed class ThrowingTransport : PipelineTransport
+    {
+        private const string Message =
+            "UserAgentResponsesClient transport invoked bypassed the override-and-delegate design. This exception should be unreachable and should never be thrown following the correct usage of UserAgentResponsesClient.";
+
+        protected override PipelineMessage CreateMessageCore() => throw new InvalidOperationException(Message);
+        protected override void ProcessCore(PipelineMessage message) => throw new InvalidOperationException(Message);
+        protected override ValueTask ProcessCoreAsync(PipelineMessage message) => throw new InvalidOperationException(Message);
+    }
+}
@@ -53,6 +53,7 @@

  <ItemGroup>
    <InternalsVisibleTo Include="Microsoft.Agents.AI.Foundry.UnitTests" />
+    <InternalsVisibleTo Include="Microsoft.Agents.AI.Foundry.Hosting.UnitTests" />
    <InternalsVisibleTo Include="DynamicProxyGenAssembly2" />
  </ItemGroup>

@@ -3,7 +3,6 @@
 using System.ClientModel.Primitives;
 using System.Collections.Generic;
 using System.Reflection;
-using System.Threading;
 using System.Threading.Tasks;

 namespace Microsoft.Agents.AI;
@@ -13,20 +12,6 @@ internal static class RequestOptionsExtensions
    /// <summary>Gets the singleton <see cref="PipelinePolicy"/> that adds a MEAI user-agent header.</summary>
    internal static PipelinePolicy UserAgentPolicy => MeaiUserAgentPolicy.Instance;

-    /// <summary>Creates a <see cref="RequestOptions"/> configured for use with Foundry Agents.</summary>
-    public static RequestOptions ToRequestOptions(this CancellationToken cancellationToken, bool streaming)
-    {
-        RequestOptions requestOptions = new()
-        {
-            CancellationToken = cancellationToken,
-            BufferResponse = !streaming
-        };
-
-        requestOptions.AddPolicy(MeaiUserAgentPolicy.Instance, PipelinePosition.PerCall);
-
-        return requestOptions;
-    }
-
    /// <summary>Provides a pipeline policy that adds a "MEAI/x.y.z" user-agent header.</summary>
    private sealed class MeaiUserAgentPolicy : PipelinePolicy
    {
@@ -42,11 +42,19 @@ internal sealed class A2AAgentHandler : IAgentHandler
    /// <inheritdoc/>
    public Task ExecuteAsync(RequestContext context, AgentEventQueue eventQueue, CancellationToken cancellationToken)
    {
+        // Handle task updates
        if (context.IsContinuation)
        {
            return this.HandleTaskUpdateAsync(context, eventQueue, cancellationToken);
        }

+        // Handle messages received via streaming endpoint
+        if (context.StreamingResponse)
+        {
+            return this.HandleNewMessageStreamingAsync(context, eventQueue, cancellationToken);
+        }
+
+        // Handle new messages received via non-streaming endpoint
        return this.HandleNewMessageAsync(context, eventQueue, cancellationToken);
    }

@@ -80,13 +88,19 @@ internal sealed class A2AAgentHandler : IAgentHandler
            ? new AgentRunOptions { AllowBackgroundResponses = allowBackgroundResponses }
            : new AgentRunOptions { AllowBackgroundResponses = allowBackgroundResponses, AdditionalProperties = context.Metadata.ToAdditionalProperties() };

-        var response = await this._hostAgent.RunAsync(
-            chatMessages,
-            session: session,
-            options: options,
-            cancellationToken: cancellationToken).ConfigureAwait(false);
-
-        await this._hostAgent.SaveSessionAsync(contextId, session, cancellationToken).ConfigureAwait(false);
+        AgentResponse response;
+        try
+        {
+            response = await this._hostAgent.RunAsync(
+                chatMessages,
+                session: session,
+                options: options,
+                cancellationToken: cancellationToken).ConfigureAwait(false);
+        }
+        finally
+        {
+            await this._hostAgent.SaveSessionAsync(contextId, session, CancellationToken.None).ConfigureAwait(false);
+        }

        if (response.ContinuationToken is null)
        {
@@ -108,6 +122,39 @@ internal sealed class A2AAgentHandler : IAgentHandler
        }
    }

+    private async Task HandleNewMessageStreamingAsync(RequestContext context, AgentEventQueue eventQueue, CancellationToken cancellationToken)
+    {
+        var contextId = context.ContextId ?? Guid.NewGuid().ToString("N");
+        var session = await this._hostAgent.GetOrCreateSessionAsync(contextId, cancellationToken).ConfigureAwait(false);
+
+        // AIAgent does not support resuming from arbitrary prior tasks.
+        // Throw explicitly so the client gets a clear error rather than a response
+        // that silently ignores the referenced task context.
+        if (context.Message?.ReferenceTaskIds is { Count: > 0 })
+        {
+            throw new NotSupportedException("ReferenceTaskIds is not supported. AIAgent cannot resume from arbitrary prior task context.");
+        }
+
+        List<ChatMessage> chatMessages = context.Message is not null ? [context.Message.ToChatMessage()] : [];
+
+        var options = context.Metadata is { Count: > 0 }
+            ? new AgentRunOptions { AdditionalProperties = context.Metadata.ToAdditionalProperties() }
+            : null;
+
+        try
+        {
+            await foreach (var update in this._hostAgent.RunStreamingAsync(chatMessages, session, options, cancellationToken).ConfigureAwait(false))
+            {
+                var message = CreateMessageFromUpdate(contextId, update);
+                await eventQueue.EnqueueMessageAsync(message, cancellationToken).ConfigureAwait(false);
+            }
+        }
+        finally
+        {
+            await this._hostAgent.SaveSessionAsync(contextId, session, CancellationToken.None).ConfigureAwait(false);
+        }
+    }
+
    private async Task HandleTaskUpdateAsync(RequestContext context, AgentEventQueue eventQueue, CancellationToken cancellationToken)
    {
        var contextId = context.ContextId ?? Guid.NewGuid().ToString("N");
@@ -141,8 +188,10 @@ internal sealed class A2AAgentHandler : IAgentHandler
            await failUpdater.FailAsync(message: null, CancellationToken.None).ConfigureAwait(false);
            throw;
        }
-
-        await this._hostAgent.SaveSessionAsync(contextId, session, cancellationToken).ConfigureAwait(false);
+        finally
+        {
+            await this._hostAgent.SaveSessionAsync(contextId, session, CancellationToken.None).ConfigureAwait(false);
+        }

        if (response.ContinuationToken is null)
        {
@@ -174,6 +223,16 @@ internal sealed class A2AAgentHandler : IAgentHandler
            Metadata = response.AdditionalProperties?.ToA2AMetadata()
        };

+    private static Message CreateMessageFromUpdate(string contextId, AgentResponseUpdate update) =>
+        new()
+        {
+            MessageId = update.ResponseId ?? Guid.NewGuid().ToString("N"),
+            ContextId = contextId,
+            Role = Role.Agent,
+            Parts = update.ToParts(),
+            Metadata = update.AdditionalProperties?.ToA2AMetadata()
+        };
+
    private static List<ChatMessage> ExtractChatMessagesFromTaskHistory(AgentTask? agentTask)
    {
        if (agentTask?.History is not { Count: > 0 })
@@ -8,6 +8,26 @@ namespace Microsoft.Agents.AI.Hosting.A2A.Converters;

 internal static class MessageConverter
 {
+    public static List<Part> ToParts(this AgentResponseUpdate update)
+    {
+        if (update is null || update.Contents is not { Count: > 0 })
+        {
+            return [];
+        }
+
+        var parts = new List<Part>();
+        foreach (var content in update.Contents)
+        {
+            var part = content.ToPart();
+            if (part is not null)
+            {
+                parts.Add(part);
+            }
+        }
+
+        return parts;
+    }
+
    public static List<Part> ToParts(this IList<ChatMessage> chatMessages)
    {
        if (chatMessages is null || chatMessages.Count == 0)
@@ -21,6 +21,8 @@ internal static class BuiltInFunctions
    internal const string HttpPrefix = "http-";
    internal const string McpToolPrefix = "mcptool-";

+    private const string WaitForResponseHeaderName = "x-ms-wait-for-response";
+
    internal static readonly string RunAgentHttpFunctionEntryPoint = $"{typeof(BuiltInFunctions).FullName!}.{nameof(RunAgentHttpAsync)}";
    internal static readonly string RunAgentEntityFunctionEntryPoint = $"{typeof(BuiltInFunctions).FullName!}.{nameof(InvokeAgentAsync)}";
    internal static readonly string RunAgentMcpToolFunctionEntryPoint = $"{typeof(BuiltInFunctions).FullName!}.{nameof(RunMcpToolAsync)}";
@@ -62,6 +64,11 @@ internal static class BuiltInFunctions
        StartOrchestrationOptions? options = instanceId is not null ? new StartOrchestrationOptions(instanceId) : null;
        string resolvedInstanceId = await client.ScheduleNewOrchestrationInstanceAsync(orchestrationFunctionName, orchestrationInput, options);

+        if (ShouldWaitForResponse(req, defaultValue: false))
+        {
+            return await WaitForWorkflowCompletionAsync(req, client, context, resolvedInstanceId);
+        }
+
        HttpResponseData response = req.CreateResponse(HttpStatusCode.Accepted);
        await response.WriteStringAsync($"Workflow orchestration started for {workflowName}. Orchestration runId: {resolvedInstanceId}");
        return response;
@@ -304,15 +311,7 @@ internal static class BuiltInFunctions
        }

        // Check if we should wait for response (default is true)
-        bool waitForResponse = true;
-        if (req.Headers.TryGetValues("x-ms-wait-for-response", out IEnumerable<string>? waitForResponseValues))
-        {
-            string? waitForResponseValue = waitForResponseValues.FirstOrDefault();
-            if (!string.IsNullOrEmpty(waitForResponseValue) && bool.TryParse(waitForResponseValue, out bool parsedValue))
-            {
-                waitForResponse = parsedValue;
-            }
-        }
+        bool waitForResponse = ShouldWaitForResponse(req, defaultValue: true);

        AIAgent agentProxy = client.AsDurableAgentProxy(context, agentName);

@@ -428,6 +427,95 @@ internal static class BuiltInFunctions
        return metadata.ReadOutputAs<DurableWorkflowResult>()?.Result;
    }

+    /// <summary>
+    /// Waits for a workflow orchestration to complete and returns an appropriate HTTP response.
+    /// </summary>
+    private static async Task<HttpResponseData> WaitForWorkflowCompletionAsync(
+        HttpRequestData req,
+        DurableTaskClient client,
+        FunctionContext context,
+        string instanceId)
+    {
+        bool acceptsJson = AcceptsJson(req);
+
+        OrchestrationMetadata? metadata = await client.WaitForInstanceCompletionAsync(
+            instanceId,
+            getInputsAndOutputs: true,
+            cancellation: context.CancellationToken);
+
+        if (metadata is null)
+        {
+            return await CreateErrorResponseAsync(req, context, HttpStatusCode.NotFound,
+                $"No workflow orchestration with ID '{instanceId}' was found.", acceptsJson);
+        }
+
+        if (metadata.RuntimeStatus is OrchestrationRuntimeStatus.Failed)
+        {
+            string errorMessage = metadata.FailureDetails?.ErrorMessage ?? "Unknown error";
+            HttpResponseData failedResponse = req.CreateResponse(HttpStatusCode.OK);
+
+            if (acceptsJson)
+            {
+                await failedResponse.WriteAsJsonAsync(
+                    new WorkflowRunResponse(instanceId, metadata.RuntimeStatus.ToString(), Result: null, Error: errorMessage),
+                    context.CancellationToken);
+            }
+            else
+            {
+                failedResponse.Headers.Add("Content-Type", "text/plain");
+                await failedResponse.WriteStringAsync(errorMessage, context.CancellationToken);
+            }
+
+            return failedResponse;
+        }
+
+        if (metadata.RuntimeStatus is not OrchestrationRuntimeStatus.Completed)
+        {
+            return await CreateErrorResponseAsync(req, context, HttpStatusCode.InternalServerError,
+                $"Workflow orchestration '{instanceId}' ended with unexpected status '{metadata.RuntimeStatus}'.", acceptsJson);
+        }
+
+        string? result = metadata.ReadOutputAs<DurableWorkflowResult>()?.Result;
+
+        HttpResponseData response = req.CreateResponse(HttpStatusCode.OK);
+
+        if (acceptsJson)
+        {
+            JsonElement? resultElement = null;
+            if (!string.IsNullOrEmpty(result))
+            {
+                try
+                {
+                    using JsonDocument doc = JsonDocument.Parse(result);
+                    resultElement = doc.RootElement.Clone();
+                }
+                catch (JsonException)
+                {
+                    // Result is a plain string (not valid JSON) — serialize it as a JSON string element.
+                    var buffer = new System.Buffers.ArrayBufferWriter<byte>();
+                    using (var writer = new Utf8JsonWriter(buffer))
+                    {
+                        writer.WriteStringValue(result);
+                    }
+
+                    using JsonDocument fallbackDoc = JsonDocument.Parse(buffer.WrittenMemory);
+                    resultElement = fallbackDoc.RootElement.Clone();
+                }
+            }
+
+            await response.WriteAsJsonAsync(
+                new WorkflowRunResponse(instanceId, metadata.RuntimeStatus.ToString(), resultElement),
+                context.CancellationToken);
+        }
+        else
+        {
+            response.Headers.Add("Content-Type", "text/plain");
+            await response.WriteStringAsync(result ?? string.Empty, context.CancellationToken);
+        }
+
+        return response;
+    }
+
    /// <summary>
    /// Creates an error response with the specified status code and error message.
    /// </summary>
@@ -435,18 +523,18 @@ internal static class BuiltInFunctions
    /// <param name="context">The function context.</param>
    /// <param name="statusCode">The HTTP status code.</param>
    /// <param name="errorMessage">The error message.</param>
+    /// <param name="acceptsJson">Optional pre-computed value indicating whether the client accepts JSON. When <see langword="null"/>, the value is determined from the request's <c>Accept</c> header.</param>
    /// <returns>The HTTP response data containing the error.</returns>
    private static async Task<HttpResponseData> CreateErrorResponseAsync(
        HttpRequestData req,
        FunctionContext context,
        HttpStatusCode statusCode,
-        string errorMessage)
+        string errorMessage,
+        bool? acceptsJson = null)
    {
        HttpResponseData response = req.CreateResponse(statusCode);
-        bool acceptsJson = req.Headers.TryGetValues("Accept", out IEnumerable<string>? acceptValues) &&
-            acceptValues.Contains("application/json", StringComparer.OrdinalIgnoreCase);

-        if (acceptsJson)
+        if (acceptsJson ?? AcceptsJson(req))
        {
            ErrorResponse errorResponse = new((int)statusCode, errorMessage);
            await response.WriteAsJsonAsync(errorResponse, context.CancellationToken);
@@ -479,10 +567,7 @@ internal static class BuiltInFunctions
        HttpResponseData response = req.CreateResponse(statusCode);
        response.Headers.Add("x-ms-thread-id", sessionId);

-        bool acceptsJson = req.Headers.TryGetValues("Accept", out IEnumerable<string>? acceptValues) &&
-            acceptValues.Contains("application/json", StringComparer.OrdinalIgnoreCase);
-
-        if (acceptsJson)
+        if (AcceptsJson(req))
        {
            AgentRunSuccessResponse successResponse = new((int)statusCode, sessionId, agentResponse);
            await response.WriteAsJsonAsync(successResponse, context.CancellationToken);
@@ -511,10 +596,7 @@ internal static class BuiltInFunctions
        HttpResponseData response = req.CreateResponse(HttpStatusCode.Accepted);
        response.Headers.Add("x-ms-thread-id", sessionId);

-        bool acceptsJson = req.Headers.TryGetValues("Accept", out IEnumerable<string>? acceptValues) &&
-            acceptValues.Contains("application/json", StringComparer.OrdinalIgnoreCase);
-
-        if (acceptsJson)
+        if (AcceptsJson(req))
        {
            AgentRunAcceptedResponse acceptedResponse = new((int)HttpStatusCode.Accepted, sessionId);
            await response.WriteAsJsonAsync(acceptedResponse, context.CancellationToken);
@@ -528,6 +610,34 @@ internal static class BuiltInFunctions
        return response;
    }

+    /// <summary>
+    /// Returns <see langword="true"/> when the caller has requested waiting for the workflow/agent to complete,
+    /// as indicated by the <c>x-ms-wait-for-response</c> header. Falls back to <paramref name="defaultValue"/>
+    /// when the header is absent or not a valid boolean.
+    /// </summary>
+    private static bool ShouldWaitForResponse(HttpRequestData req, bool defaultValue)
+    {
+        if (req.Headers.TryGetValues(WaitForResponseHeaderName, out IEnumerable<string>? values) &&
+            bool.TryParse(values.FirstOrDefault(), out bool parsed))
+        {
+            return parsed;
+        }
+
+        return defaultValue;
+    }
+
+    /// <summary>
+    /// Returns <see langword="true"/> when the request accepts the <c>application/json</c> media type.
+    /// </summary>
+    private static bool AcceptsJson(HttpRequestData req)
+    {
+        return req.Headers.TryGetValues("Accept", out IEnumerable<string>? acceptValues) &&
+            acceptValues
+                .SelectMany(v => v.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries))
+                .Select(v => v.Split(';', 2)[0].Trim())
+                .Contains("application/json", StringComparer.OrdinalIgnoreCase);
+    }
+
    private static string GetAgentName(FunctionContext context)
    {
        // Check if the function name starts with the HttpPrefix
@@ -591,6 +701,19 @@ internal static class BuiltInFunctions
        [property: JsonPropertyName("eventName")] string? EventName,
        [property: JsonPropertyName("response")] JsonElement Response);

+    /// <summary>
+    /// Represents a workflow run response when waiting for completion.
+    /// </summary>
+    /// <param name="RunId">The orchestration run ID.</param>
+    /// <param name="WorkflowStatus">The orchestration runtime status (e.g., "Completed", "Failed").</param>
+    /// <param name="Result">The workflow result as a JSON element so POCOs serialize as nested objects rather than escaped strings.</param>
+    /// <param name="Error">An optional error message when the workflow has failed.</param>
+    private sealed record WorkflowRunResponse(
+        [property: JsonPropertyName("runId")] string RunId,
+        [property: JsonPropertyName("workflowStatus")] string WorkflowStatus,
+        [property: JsonPropertyName("result")] JsonElement? Result,
+        [property: JsonPropertyName("error"), JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] string? Error = null);
+
    /// <summary>
    /// A service provider that combines the original service provider with an additional DurableTaskClient instance.
    /// </summary>
@@ -2,6 +2,7 @@

 ## [Unreleased]

+- Support returning workflow results from HTTP trigger endpoint ([#5321](https://github.com/microsoft/agent-framework/pull/5321))
 - Added MCP tool trigger support for durable workflows ([#4768](https://github.com/microsoft/agent-framework/pull/4768))
 - Added Azure Functions hosting support for durable workflows ([#4436](https://github.com/microsoft/agent-framework/pull/4436))

@@ -26,6 +26,12 @@ public sealed class DeclarativeWorkflowOptions(ResponseAgentProvider agentProvid
    /// </summary>
    public IMcpToolHandler? McpToolHandler { get; init; }

+    /// <summary>
+    /// Gets or sets the HTTP request handler for executing <c>HttpRequestAction</c> actions within workflows.
+    /// If not set, HTTP request actions will fail with an appropriate error message.
+    /// </summary>
+    public IHttpRequestHandler? HttpRequestHandler { get; init; }
+
    /// <summary>
    /// Defines the configuration settings for the workflow.
    /// </summary>
@@ -0,0 +1,289 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Net.Http;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Microsoft.Agents.AI.Workflows.Declarative;
+
+/// <summary>
+/// Default implementation of <see cref="IHttpRequestHandler"/> built on <see cref="HttpClient"/>.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This handler supports per-request authentication via an optional <c>httpClientProvider</c> callback that
+/// returns a pre-configured <see cref="HttpClient"/> for a given request (e.g. authenticated, custom handler).
+/// When the provider returns <see langword="null"/>, or no provider is supplied, a shared internal <see cref="HttpClient"/>
+/// is used.
+/// </para>
+/// <para>
+/// The handler applies the per-request <see cref="HttpRequestInfo.Timeout"/> using a linked <see cref="CancellationTokenSource"/>
+/// so it does not mutate <see cref="HttpClient.Timeout"/> on shared instances.
+/// </para>
+/// </remarks>
+public sealed class DefaultHttpRequestHandler : IHttpRequestHandler, IAsyncDisposable
+{
+    private readonly Func<HttpRequestInfo, CancellationToken, Task<HttpClient?>>? _httpClientProvider;
+    private readonly Lazy<HttpClient> _ownedHttpClient;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DefaultHttpRequestHandler"/> class that uses an
+    /// internally owned <see cref="HttpClient"/> for all requests. The internal client is disposed
+    /// when <see cref="DisposeAsync"/> is called.
+    /// </summary>
+    public DefaultHttpRequestHandler()
+        : this(httpClientProvider: null)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DefaultHttpRequestHandler"/> class that uses the
+    /// supplied <see cref="HttpClient"/> for all requests.
+    /// </summary>
+    /// <param name="httpClient">
+    /// The <see cref="HttpClient"/> to use for all requests. The caller retains ownership of this
+    /// instance; it is not disposed by <see cref="DisposeAsync"/>.
+    /// </param>
+    /// <exception cref="ArgumentNullException"><paramref name="httpClient"/> is <see langword="null"/>.</exception>
+    public DefaultHttpRequestHandler(HttpClient httpClient)
+        : this(CreateSingleClientProvider(httpClient))
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DefaultHttpRequestHandler"/> class that selects
+    /// an <see cref="HttpClient"/> per request via a caller-supplied callback — for example, to route
+    /// different URLs through differently authenticated clients.
+    /// </summary>
+    /// <param name="httpClientProvider">
+    /// An optional callback invoked for each request. The callback receives the <see cref="HttpRequestInfo"/>
+    /// and should return a pre-configured <see cref="HttpClient"/> (e.g. with authentication or a custom
+    /// transport). Return <see langword="null"/> to fall back to the handler's shared internal
+    /// <see cref="HttpClient"/>.
+    /// </param>
+    /// <remarks>
+    /// <para>
+    /// <b>Ownership</b>: the caller is solely responsible for the lifetime of clients returned by this
+    /// callback. <see cref="DefaultHttpRequestHandler"/> will <b>not</b> dispose provider-returned
+    /// clients; only the handler's internally owned fallback client is disposed by <see cref="DisposeAsync"/>.
+    /// </para>
+    /// <para>
+    /// <b>Reuse</b>: callers are expected to cache and reuse clients (for example, keyed by base URL or
+    /// auth scope) across requests. Returning a newly allocated <see cref="HttpClient"/> on every
+    /// invocation will leak sockets and handler resources.
+    /// </para>
+    /// </remarks>
+    public DefaultHttpRequestHandler(Func<HttpRequestInfo, CancellationToken, Task<HttpClient?>>? httpClientProvider)
+    {
+        this._httpClientProvider = httpClientProvider;
+        this._ownedHttpClient = new Lazy<HttpClient>(() => new HttpClient(), LazyThreadSafetyMode.ExecutionAndPublication);
+    }
+
+    private static Func<HttpRequestInfo, CancellationToken, Task<HttpClient?>> CreateSingleClientProvider(HttpClient httpClient)
+    {
+        if (httpClient is null)
+        {
+            throw new ArgumentNullException(nameof(httpClient));
+        }
+
+        return (_, _) => Task.FromResult<HttpClient?>(httpClient);
+    }
+
+    /// <inheritdoc/>
+    public async Task<HttpRequestResult> SendAsync(HttpRequestInfo request, CancellationToken cancellationToken = default)
+    {
+        if (request is null)
+        {
+            throw new ArgumentNullException(nameof(request));
+        }
+
+        if (string.IsNullOrWhiteSpace(request.Url))
+        {
+            throw new ArgumentException("Request URL must be provided.", nameof(request));
+        }
+
+        if (string.IsNullOrWhiteSpace(request.Method))
+        {
+            throw new ArgumentException("Request method must be provided.", nameof(request));
+        }
+
+        HttpClient? providedClient = null;
+        if (this._httpClientProvider is not null)
+        {
+            providedClient = await this._httpClientProvider(request, cancellationToken).ConfigureAwait(false);
+        }
+
+        HttpClient client = providedClient ?? this._ownedHttpClient.Value;
+
+        using HttpRequestMessage httpRequest = BuildHttpRequestMessage(request);
+
+        using CancellationTokenSource? timeoutCts = request.Timeout is { } timeout && timeout > TimeSpan.Zero
+            ? CancellationTokenSource.CreateLinkedTokenSource(cancellationToken)
+            : null;
+
+        timeoutCts?.CancelAfter(request.Timeout!.Value);
+
+        CancellationToken effectiveToken = timeoutCts?.Token ?? cancellationToken;
+
+        using HttpResponseMessage httpResponse = await client
+            .SendAsync(httpRequest, HttpCompletionOption.ResponseContentRead, effectiveToken)
+            .ConfigureAwait(false);
+
+        string? body = httpResponse.Content is null
+            ? null
+#if NET
+            : await httpResponse.Content.ReadAsStringAsync(effectiveToken).ConfigureAwait(false);
+#else
+            : await httpResponse.Content.ReadAsStringAsync().ConfigureAwait(false);
+#endif
+
+        Dictionary<string, IReadOnlyList<string>> headers = new(StringComparer.OrdinalIgnoreCase);
+        AppendHeaders(headers, httpResponse.Headers);
+        if (httpResponse.Content is not null)
+        {
+            AppendHeaders(headers, httpResponse.Content.Headers);
+        }
+
+        return new HttpRequestResult
+        {
+            StatusCode = (int)httpResponse.StatusCode,
+            IsSuccessStatusCode = httpResponse.IsSuccessStatusCode,
+            Body = body,
+            Headers = headers,
+        };
+    }
+
+    /// <inheritdoc/>
+    public ValueTask DisposeAsync()
+    {
+        if (this._ownedHttpClient.IsValueCreated)
+        {
+            this._ownedHttpClient.Value.Dispose();
+        }
+
+        return default;
+    }
+
+    private static HttpRequestMessage BuildHttpRequestMessage(HttpRequestInfo request)
+    {
+        HttpMethod method = ResolveMethod(request.Method);
+        string requestUri = ResolveRequestUri(request);
+        HttpRequestMessage httpRequest = new(method, requestUri);
+
+        if (request.Body is not null)
+        {
+            string contentType = string.IsNullOrWhiteSpace(request.BodyContentType)
+                ? "text/plain"
+                : request.BodyContentType!;
+
+            httpRequest.Content = new StringContent(request.Body, Encoding.UTF8);
+            // Replace the default content-type header (including charset) with the declared type.
+            httpRequest.Content.Headers.Remove("Content-Type");
+            httpRequest.Content.Headers.TryAddWithoutValidation("Content-Type", contentType);
+        }
+
+        if (request.Headers is not null)
+        {
+            foreach (KeyValuePair<string, string> header in request.Headers)
+            {
+                if (string.IsNullOrEmpty(header.Key))
+                {
+                    continue;
+                }
+
+                // Content-* headers belong on HttpContent; all others belong on the request.
+                if (header.Key.StartsWith("Content-", StringComparison.OrdinalIgnoreCase) && httpRequest.Content is not null)
+                {
+                    httpRequest.Content.Headers.Remove(header.Key);
+                    httpRequest.Content.Headers.TryAddWithoutValidation(header.Key, header.Value);
+                    continue;
+                }
+
+                if (!httpRequest.Headers.TryAddWithoutValidation(header.Key, header.Value))
+                {
+                    httpRequest.Content?.Headers.TryAddWithoutValidation(header.Key, header.Value);
+                }
+            }
+        }
+
+        return httpRequest;
+    }
+
+    private static HttpMethod ResolveMethod(string method)
+    {
+        string normalized = method.Trim().ToUpperInvariant();
+        return normalized switch
+        {
+            "GET" => HttpMethod.Get,
+            "POST" => HttpMethod.Post,
+            "PUT" => HttpMethod.Put,
+            "DELETE" => HttpMethod.Delete,
+#if NET
+            "PATCH" => HttpMethod.Patch,
+#else
+            "PATCH" => new HttpMethod("PATCH"),
+#endif
+            _ => new HttpMethod(normalized),
+        };
+    }
+
+    private static string ResolveRequestUri(HttpRequestInfo request)
+    {
+        string baseUrl = request.Url;
+        if (request.QueryParameters is null || request.QueryParameters.Count == 0)
+        {
+            return baseUrl;
+        }
+
+        StringBuilder queryBuilder = new();
+        foreach (KeyValuePair<string, string> parameter in request.QueryParameters)
+        {
+            if (string.IsNullOrEmpty(parameter.Key))
+            {
+                continue;
+            }
+
+            if (queryBuilder.Length > 0)
+            {
+                queryBuilder.Append('&');
+            }
+
+            queryBuilder.Append(Uri.EscapeDataString(parameter.Key))
+                .Append('=')
+                .Append(Uri.EscapeDataString(parameter.Value ?? string.Empty));
+        }
+
+        if (queryBuilder.Length == 0)
+        {
+            return baseUrl;
+        }
+
+        char separator = baseUrl.Contains('?') ? '&' : '?';
+        return string.Concat(baseUrl, separator.ToString(), queryBuilder.ToString());
+    }
+
+    private static void AppendHeaders(
+        Dictionary<string, IReadOnlyList<string>> target,
+        System.Net.Http.Headers.HttpHeaders source)
+    {
+        foreach (KeyValuePair<string, IEnumerable<string>> header in source)
+        {
+            string[] values = header.Value.ToArray();
+
+            if (target.TryGetValue(header.Key, out IReadOnlyList<string>? existing))
+            {
+                List<string> combined = new(existing);
+                combined.AddRange(values);
+                target[header.Key] = combined;
+            }
+            else
+            {
+                target[header.Key] = values;
+            }
+        }
+    }
+}
@@ -16,6 +16,60 @@ internal static class ChatMessageExtensions
    public static RecordValue ToRecord(this ChatMessage message) =>
        FormulaValue.NewRecordFromFields(message.GetMessageFields());

+    /// <summary>
+    /// Merges the user-authored <paramref name="input"/> with the round-tripped
+    /// <paramref name="inputMessage"/> returned by <c>AgentProvider.CreateMessageAsync</c>
+    /// to produce the value stored in <c>System.LastMessage</c>.
+    /// </summary>
+    /// <remarks>
+    /// The agent service often strips or alters <see cref="TextContent"/> on round-trip,
+    /// while replacing inline media (<see cref="DataContent"/>, <see cref="UriContent"/>)
+    /// with server-side references (typically <see cref="HostedFileContent"/>).
+    /// We want both: the original text (so <c>=System.LastMessage.Text</c> works) and
+    /// the server's media references (so subsequent actions don't re-upload large blobs).
+    /// <para>
+    /// Strategy: keep <paramref name="inputMessage"/> as the base — it has the server-generated
+    /// <see cref="ChatMessage.MessageId"/> and any provider-augmented metadata, and is forward-
+    /// compatible with new properties added on <see cref="ChatMessage"/> in the abstractions
+    /// layer. Only the <see cref="ChatMessage.Contents"/> list is mutated to substitute
+    /// original <see cref="TextContent"/> items in place (and append any extras the round-trip
+    /// dropped). Non-text content items returned by the service are left untouched so
+    /// server-side references survive.
+    /// </para>
+    /// </remarks>
+    public static ChatMessage MergeForLastMessage(this ChatMessage input, ChatMessage? inputMessage)
+    {
+        if (inputMessage is null)
+        {
+            return input;
+        }
+
+        // Build a queue of the original text items, in order. Fall back to ChatMessage.Text
+        // if the input has no explicit TextContent entries.
+        Queue<TextContent> originalTexts = new(input.Contents.OfType<TextContent>());
+        if (originalTexts.Count == 0 && !string.IsNullOrEmpty(input.Text))
+        {
+            originalTexts.Enqueue(new TextContent(input.Text));
+        }
+
+        // Replace TextContent items in inputMessage.Contents with the originals, in order.
+        for (int i = 0; i < inputMessage.Contents.Count && originalTexts.Count > 0; i++)
+        {
+            if (inputMessage.Contents[i] is TextContent)
+            {
+                inputMessage.Contents[i] = originalTexts.Dequeue();
+            }
+        }
+
+        // Append any remaining original text items that the round-trip dropped entirely.
+        while (originalTexts.Count > 0)
+        {
+            inputMessage.Contents.Add(originalTexts.Dequeue());
+        }
+
+        return inputMessage;
+    }
+
    public static TableValue ToTable(this IEnumerable<ChatMessage> messages) =>
        FormulaValue.NewTable(TypeSchema.Message.RecordType, messages.Select(message => message.ToRecord()));

@@ -0,0 +1,103 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Microsoft.Agents.AI.Workflows.Declarative;
+
+/// <summary>
+/// Defines the contract for executing HTTP requests emitted by <c>HttpRequestAction</c> within declarative workflows.
+/// </summary>
+/// <remarks>
+/// This interface allows the HTTP request dispatch to be abstracted, enabling different implementations
+/// for local development, hosted workflows, authenticated scenarios, and testing.
+/// </remarks>
+public interface IHttpRequestHandler
+{
+    /// <summary>
+    /// Sends an HTTP request and returns the response.
+    /// </summary>
+    /// <param name="request">The HTTP request to send.</param>
+    /// <param name="cancellationToken">A token to observe cancellation.</param>
+    /// <returns>The <see cref="HttpRequestResult"/> describing the HTTP response.</returns>
+    Task<HttpRequestResult> SendAsync(
+        HttpRequestInfo request,
+        CancellationToken cancellationToken = default);
+}
+
+/// <summary>
+/// Describes an HTTP request to be sent by an <see cref="IHttpRequestHandler"/>.
+/// </summary>
+[SuppressMessage("Design", "CA1056:URI-like properties should not be strings", Justification = "URL is carried as a string to preserve the declarative expression result and to avoid forcing handler implementations to construct a Uri eagerly.")]
+public sealed class HttpRequestInfo
+{
+    /// <summary>
+    /// Gets the HTTP method to use (GET, POST, PUT, PATCH, DELETE).
+    /// </summary>
+    public string Method { get; init; } = "GET";
+
+    /// <summary>
+    /// Gets the absolute URL to send the request to.
+    /// </summary>
+    public string Url { get; init; } = string.Empty;
+
+    /// <summary>
+    /// Gets the headers to include on the request, excluding the <c>Content-Type</c> header (which is supplied via <see cref="BodyContentType"/>).
+    /// </summary>
+    public IReadOnlyDictionary<string, string>? Headers { get; init; }
+
+    /// <summary>
+    /// Gets the <c>Content-Type</c> of the request body, or <see langword="null"/> if no body is sent.
+    /// </summary>
+    public string? BodyContentType { get; init; }
+
+    /// <summary>
+    /// Gets the serialized request body, or <see langword="null"/> if no body is sent.
+    /// </summary>
+    public string? Body { get; init; }
+
+    /// <summary>
+    /// Gets the maximum amount of time to wait for the request to complete, or <see langword="null"/> to use the handler default.
+    /// </summary>
+    public TimeSpan? Timeout { get; init; }
+
+    /// <summary>
+    /// Gets the query parameters to append to the request URL, with values already formatted as strings.
+    /// </summary>
+    public IReadOnlyDictionary<string, string>? QueryParameters { get; init; }
+
+    /// <summary>
+    /// Gets the name of the declared remote connection, or <see langword="null"/> if no connection is declared.
+    /// This maps to the Foundry project connection Id and is only used when running in foundry service.
+    /// </summary>
+    public string? ConnectionName { get; init; }
+}
+
+/// <summary>
+/// Represents the result of an HTTP request executed by an <see cref="IHttpRequestHandler"/>.
+/// </summary>
+public sealed class HttpRequestResult
+{
+    /// <summary>
+    /// Gets the HTTP status code returned by the server.
+    /// </summary>
+    public int StatusCode { get; init; }
+
+    /// <summary>
+    /// Gets a value indicating whether the status code is in the range 200-299.
+    /// </summary>
+    public bool IsSuccessStatusCode { get; init; }
+
+    /// <summary>
+    /// Gets the response body, or <see langword="null"/> if no body was returned.
+    /// </summary>
+    public string? Body { get; init; }
+
+    /// <summary>
+    /// Gets the response headers keyed by header name. Each header may have multiple values.
+    /// </summary>
+    public IReadOnlyDictionary<string, IReadOnlyList<string>>? Headers { get; init; }
+}
@@ -43,7 +43,11 @@ internal sealed class DeclarativeWorkflowExecutor<TInput>(
        await declarativeContext.QueueConversationUpdateAsync(conversationId, isExternal: true, cancellationToken).ConfigureAwait(false);

        ChatMessage inputMessage = await options.AgentProvider.CreateMessageAsync(conversationId, input, cancellationToken).ConfigureAwait(false);
-        await declarativeContext.SetLastMessageAsync(inputMessage).ConfigureAwait(false);
+
+        // Use the original input for System.LastMessage to ensure Text is preserved (the
+        // service may strip text on round-trip), but substitute server-side media references
+        // (e.g., HostedFileContent) so subsequent actions don't re-upload large blobs.
+        await declarativeContext.SetLastMessageAsync(input.MergeForLastMessage(inputMessage)).ConfigureAwait(false);

        await context.SendResultMessageAsync(this.Id, cancellationToken).ConfigureAwait(false);
    }
@@ -529,6 +529,18 @@ internal sealed class WorkflowActionVisitor : DialogActionVisitor
        this._workflowModel.AddNode(new DelegateActionExecutor(postId, this._workflowState, action.CompleteAsync), action.ParentId);
    }

+    protected override void Visit(HttpRequestAction item)
+    {
+        this.Trace(item);
+
+        if (this._workflowOptions.HttpRequestHandler is null)
+        {
+            throw new DeclarativeModelException("HTTP request handler not configured. Set HttpRequestHandler in DeclarativeWorkflowOptions to use HttpRequestAction actions.");
+        }
+
+        this.ContinueWith(new HttpRequestExecutor(item, this._workflowOptions.HttpRequestHandler, this._workflowOptions.AgentProvider, this._workflowState));
+    }
+
    #region Not supported

    protected override void Visit(AnswerQuestionWithAI item) => this.NotSupported(item);
@@ -573,8 +585,6 @@ internal sealed class WorkflowActionVisitor : DialogActionVisitor

    protected override void Visit(GetConversationMembers item) => this.NotSupported(item);

-    protected override void Visit(HttpRequestAction item) => this.NotSupported(item);
-
    protected override void Visit(RecognizeIntent item) => this.NotSupported(item);

    protected override void Visit(TransferConversation item) => this.NotSupported(item);
@@ -58,7 +58,6 @@ public abstract class RootExecutor<TInput> : Executor<TInput>, IResettableExecut
    public override async ValueTask HandleAsync(TInput message, IWorkflowContext context, CancellationToken cancellationToken)
    {
        DeclarativeWorkflowContext declarativeContext = new(context, this._state);
-        await this.ExecuteAsync(message, declarativeContext, cancellationToken).ConfigureAwait(false);

        ChatMessage input = (this._inputTransform ?? DefaultInputTransform).Invoke(message);

@@ -69,7 +68,13 @@ public abstract class RootExecutor<TInput> : Executor<TInput>, IResettableExecut
        await declarativeContext.QueueConversationUpdateAsync(this._conversationId, isExternal: true, cancellationToken).ConfigureAwait(false);

        ChatMessage inputMessage = await this._agentProvider.CreateMessageAsync(this._conversationId, input, cancellationToken).ConfigureAwait(false);
-        await declarativeContext.SetLastMessageAsync(inputMessage).ConfigureAwait(false);
+
+        // Use the original input for System.LastMessage to ensure Text is preserved (the
+        // service may strip text on round-trip), but substitute server-side media references
+        // (e.g., HostedFileContent) so subsequent actions don't re-upload large blobs.
+        await declarativeContext.SetLastMessageAsync(input.MergeForLastMessage(inputMessage)).ConfigureAwait(false);
+
+        await this.ExecuteAsync(message, declarativeContext, cancellationToken).ConfigureAwait(false);

        await declarativeContext.SendResultMessageAsync(this.Id, cancellationToken).ConfigureAwait(false);
    }
@@ -0,0 +1,346 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Text.Json;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Agents.AI.Workflows.Declarative.Extensions;
+using Microsoft.Agents.AI.Workflows.Declarative.Interpreter;
+using Microsoft.Agents.AI.Workflows.Declarative.Kit;
+using Microsoft.Agents.AI.Workflows.Declarative.PowerFx;
+using Microsoft.Agents.ObjectModel;
+using Microsoft.Extensions.AI;
+using Microsoft.PowerFx.Types;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI.Workflows.Declarative.ObjectModel;
+
+/// <summary>
+/// Executor for the <see cref="HttpRequestAction"/> action.
+/// Dispatches the request through the configured <see cref="IHttpRequestHandler"/> and assigns
+/// the response body and headers to the declared property paths.
+/// </summary>
+internal sealed class HttpRequestExecutor(
+    HttpRequestAction model,
+    IHttpRequestHandler httpRequestHandler,
+    ResponseAgentProvider agentProvider,
+    WorkflowFormulaState state) :
+    DeclarativeActionExecutor<HttpRequestAction>(model, state)
+{
+    /// <inheritdoc/>
+    protected override async ValueTask<object?> ExecuteAsync(IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        string method = this.GetMethod();
+        string url = this.GetUrl();
+        Dictionary<string, string>? headers = this.GetHeaders();
+        Dictionary<string, string>? queryParameters = this.GetQueryParameters();
+        (string? body, string? contentType) = this.GetBody();
+        TimeSpan? timeout = this.GetTimeout();
+        string? conversationId = this.GetConversationId();
+        string? connectionName = this.GetConnectionName();
+
+        HttpRequestInfo requestInfo = new()
+        {
+            Method = method,
+            Url = url,
+            Headers = headers,
+            QueryParameters = queryParameters,
+            Body = body,
+            BodyContentType = contentType,
+            Timeout = timeout,
+            ConnectionName = connectionName,
+        };
+
+        HttpRequestResult result;
+        try
+        {
+            result = await httpRequestHandler.SendAsync(requestInfo, cancellationToken).ConfigureAwait(false);
+        }
+        catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested)
+        {
+            throw this.Exception($"HTTP request to '{url}' timed out.");
+        }
+        catch (Exception exception) when (exception is not DeclarativeActionException)
+        {
+            throw this.Exception($"HTTP request to '{url}' failed: {exception.Message}", exception);
+        }
+
+        if (result.IsSuccessStatusCode)
+        {
+            await this.AssignResponseAsync(context, result.Body).ConfigureAwait(false);
+            await this.AssignResponseHeadersAsync(context, result.Headers).ConfigureAwait(false);
+            await this.AddResponseToConversationAsync(conversationId, result.Body, cancellationToken).ConfigureAwait(false);
+            return default;
+        }
+
+        // Non-success status code - throw.
+        // Also publish response headers for diagnostic purposes.
+        await this.AssignResponseHeadersAsync(context, result.Headers).ConfigureAwait(false);
+
+        string bodyPreview = FormatBodyForDiagnostics(result.Body);
+        string message = bodyPreview.Length == 0
+            ? $"HTTP request to '{url}' failed with status code {result.StatusCode}."
+            : $"HTTP request to '{url}' failed with status code {result.StatusCode}. Body: '{bodyPreview}'";
+
+        throw this.Exception(message);
+    }
+
+    // Response bodies can echo secrets (tokens, PII) and may be very large (multi-MB HTML error pages).
+    // Exception messages are often logged and persisted, so we clip the body to bound both exposure
+    // and message size. Full bodies are still available via the success path (assigned to Response).
+    private const int MaxBodyDiagnosticLength = 256;
+    private const string BodyTruncationSuffix = " \u2026 [truncated]";
+
+    private static string FormatBodyForDiagnostics(string? body)
+    {
+        if (string.IsNullOrEmpty(body))
+        {
+            return string.Empty;
+        }
+
+        int sourceLen = body!.Length;
+        bool truncated = sourceLen > MaxBodyDiagnosticLength;
+        int copyLen = truncated ? MaxBodyDiagnosticLength : sourceLen;
+        int finalLen = copyLen + (truncated ? BodyTruncationSuffix.Length : 0);
+
+        // Size the buffer for the final string so we only allocate once for the chars
+        // and once for the string itself. For a 10 KB error body we touch 256 chars instead of 10,000.
+        char[] buffer = new char[finalLen];
+        for (int i = 0; i < copyLen; i++)
+        {
+            char c = body[i];
+            buffer[i] = c is '\r' or '\n' or '\t' ? ' ' : c;
+        }
+
+        if (truncated)
+        {
+            BodyTruncationSuffix.CopyTo(0, buffer, copyLen, BodyTruncationSuffix.Length);
+        }
+
+        return new string(buffer);
+    }
+
+    private async ValueTask AddResponseToConversationAsync(string? conversationId, string? responseBody, CancellationToken cancellationToken)
+    {
+        if (conversationId is null || string.IsNullOrEmpty(responseBody))
+        {
+            return;
+        }
+
+        ChatMessage message = new(ChatRole.Assistant, responseBody);
+        await agentProvider.CreateMessageAsync(conversationId, message, cancellationToken).ConfigureAwait(false);
+    }
+
+    private async ValueTask AssignResponseAsync(IWorkflowContext context, string? responseBody)
+    {
+        if (this.Model.Response is not { Path: { } responsePath })
+        {
+            return;
+        }
+
+        await this.AssignAsync(responsePath, ParseResponseBody(responseBody), context).ConfigureAwait(false);
+    }
+
+    private async ValueTask AssignResponseHeadersAsync(IWorkflowContext context, IReadOnlyDictionary<string, IReadOnlyList<string>>? responseHeaders)
+    {
+        if (this.Model.ResponseHeaders is not { Path: { } headersPath })
+        {
+            return;
+        }
+
+        if (responseHeaders is null || responseHeaders.Count == 0)
+        {
+            await this.AssignAsync(headersPath, FormulaValue.NewBlank(), context).ConfigureAwait(false);
+            return;
+        }
+
+        // Flatten multi-value headers by joining with commas (standard HTTP header folding).
+        Dictionary<string, object?> flattened = new(StringComparer.OrdinalIgnoreCase);
+        foreach (KeyValuePair<string, IReadOnlyList<string>> header in responseHeaders)
+        {
+            flattened[header.Key] = string.Join(",", header.Value);
+        }
+
+        await this.AssignAsync(headersPath, flattened.ToFormula(), context).ConfigureAwait(false);
+    }
+
+    private static FormulaValue ParseResponseBody(string? responseBody)
+    {
+        if (string.IsNullOrEmpty(responseBody))
+        {
+            return FormulaValue.NewBlank();
+        }
+
+        // Attempt to parse as JSON so records/tables are exposed naturally to the workflow.
+        try
+        {
+            using JsonDocument jsonDocument = JsonDocument.Parse(responseBody);
+
+            object? parsedValue = jsonDocument.RootElement.ValueKind switch
+            {
+                JsonValueKind.Object => jsonDocument.ParseRecord(VariableType.RecordType),
+                JsonValueKind.Array => jsonDocument.ParseList(jsonDocument.RootElement.GetListTypeFromJson()),
+                JsonValueKind.String => jsonDocument.RootElement.GetString(),
+                JsonValueKind.Number => jsonDocument.RootElement.TryGetInt64(out long l)
+                    ? l
+                    : jsonDocument.RootElement.GetDouble(),
+                JsonValueKind.True => true,
+                JsonValueKind.False => false,
+                JsonValueKind.Null => null,
+                _ => responseBody,
+            };
+
+            return parsedValue.ToFormula();
+        }
+        catch (JsonException)
+        {
+            // Not valid JSON — return the raw string.
+            return FormulaValue.New(responseBody);
+        }
+    }
+
+    private string GetMethod()
+    {
+        EnumExpression<HttpMethodTypeWrapper>? methodExpression = this.Model.Method;
+        if (methodExpression is null)
+        {
+            return "GET";
+        }
+
+        HttpMethodTypeWrapper wrapper = this.Evaluator.GetValue(methodExpression).Value;
+        return !string.IsNullOrEmpty(wrapper.UnknownValue) ? wrapper.UnknownValue! : wrapper.Value.ToString().ToUpperInvariant();
+    }
+
+    private string GetUrl() =>
+        this.Evaluator.GetValue(
+            Throw.IfNull(
+                this.Model.Url,
+                $"{nameof(this.Model)}.{nameof(this.Model.Url)}")).Value;
+
+    private Dictionary<string, string>? GetHeaders()
+    {
+        if (this.Model.Headers is null || this.Model.Headers.Count == 0)
+        {
+            return null;
+        }
+
+        Dictionary<string, string> result = new(StringComparer.OrdinalIgnoreCase);
+        foreach (KeyValuePair<string, StringExpression> header in this.Model.Headers)
+        {
+            string value = this.Evaluator.GetValue(header.Value).Value;
+            if (!string.IsNullOrEmpty(value))
+            {
+                result[header.Key] = value;
+            }
+        }
+
+        return result.Count == 0 ? null : result;
+    }
+
+    private (string? Body, string? ContentType) GetBody()
+    {
+        switch (this.Model.Body)
+        {
+            case null:
+            case NoRequestContent:
+                return (null, null);
+
+            case JsonRequestContent jsonContent when jsonContent.Content is not null:
+            {
+                FormulaValue formula = this.Evaluator.GetValue(jsonContent.Content).Value.ToFormula();
+                string json = formula.ToJson().ToJsonString();
+                return (json, "application/json");
+            }
+
+            case RawRequestContent rawContent:
+            {
+                string? content = rawContent.Content is null
+                        ? null
+                        : this.Evaluator.GetValue(rawContent.Content).Value;
+
+                string? contentType = rawContent.ContentType is null
+                        ? null
+                        : this.Evaluator.GetValue(rawContent.ContentType).Value;
+
+                return (content, string.IsNullOrEmpty(contentType) ? null : contentType);
+            }
+
+            default:
+                return (null, null);
+        }
+    }
+
+    private TimeSpan? GetTimeout()
+    {
+        if (this.Model.RequestTimeoutInMilliseconds is null || this.Model.RequestTimeoutInMillisecondsIsDefaultValue)
+        {
+            return null;
+        }
+
+        long value = this.Evaluator.GetValue(this.Model.RequestTimeoutInMilliseconds).Value;
+        return value > 0 ? TimeSpan.FromMilliseconds(value) : null;
+    }
+
+    private Dictionary<string, string>? GetQueryParameters()
+    {
+        if (this.Model.QueryParameters is null || this.Model.QueryParameters.Count == 0)
+        {
+            return null;
+        }
+
+        Dictionary<string, string> result = new(StringComparer.Ordinal);
+        foreach (KeyValuePair<string, ValueExpression> parameter in this.Model.QueryParameters)
+        {
+            if (string.IsNullOrEmpty(parameter.Key) || parameter.Value is null)
+            {
+                continue;
+            }
+
+            object? rawValue = this.Evaluator.GetValue(parameter.Value).Value.ToObject();
+            string? formatted = FormatQueryValue(rawValue);
+            if (formatted is not null)
+            {
+                result[parameter.Key] = formatted;
+            }
+        }
+
+        return result.Count == 0 ? null : result;
+    }
+
+    private static string? FormatQueryValue(object? value) =>
+        value switch
+        {
+            null => null,
+            string s => s,
+            bool b => b ? "true" : "false",
+            IFormattable formattable => formattable.ToString(null, System.Globalization.CultureInfo.InvariantCulture),
+            _ => value.ToString(),
+        };
+
+    private string? GetConversationId()
+    {
+        if (this.Model.ConversationId is null)
+        {
+            return null;
+        }
+
+        string value = this.Evaluator.GetValue(this.Model.ConversationId).Value;
+        return value.Length == 0 ? null : value;
+    }
+
+    private string? GetConnectionName()
+    {
+        RemoteConnection? connection = this.Model.Connection;
+        if (connection is null)
+        {
+            return null;
+        }
+
+        string? name = connection.Name is null
+            ? null
+            : this.Evaluator.GetValue(connection.Name).Value;
+
+        return string.IsNullOrEmpty(name) ? null : name;
+    }
+}
@@ -1,5 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.

+using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
 using System.Text.Encodings.Web;
 using System.Text.Json;
@@ -69,6 +70,38 @@ internal static partial class AgentJsonUtilities
    [JsonSerializable(typeof(TextSearchProvider.TextSearchProviderState))]
    [JsonSerializable(typeof(ChatHistoryMemoryProvider.State))]

+    // TodoProvider types
+    [JsonSerializable(typeof(TodoState))]
+    [JsonSerializable(typeof(TodoItem))]
+    [JsonSerializable(typeof(TodoItemInput))]
+    [JsonSerializable(typeof(List<int>), TypeInfoPropertyName = "IntList")]
+    [JsonSerializable(typeof(List<TodoItem>), TypeInfoPropertyName = "TodoItemList")]
+    [JsonSerializable(typeof(List<TodoItemInput>), TypeInfoPropertyName = "TodoItemInputList")]
+
+    // AgentModeProvider types
+    [JsonSerializable(typeof(AgentModeState))]
+
+    // ToolApprovalAgent types
+    [JsonSerializable(typeof(ToolApprovalState))]
+    [JsonSerializable(typeof(ToolApprovalRule))]
+    [JsonSerializable(typeof(List<ToolApprovalRule>), TypeInfoPropertyName = "ToolApprovalRuleList")]
+
+    // FileMemoryProvider types
+    [JsonSerializable(typeof(FileMemoryState))]
+    [JsonSerializable(typeof(FileSearchResult))]
+    [JsonSerializable(typeof(List<FileSearchResult>), TypeInfoPropertyName = "FileSearchResultList")]
+    [JsonSerializable(typeof(FileSearchMatch))]
+    [JsonSerializable(typeof(List<FileSearchMatch>), TypeInfoPropertyName = "FileSearchMatchList")]
+    [JsonSerializable(typeof(FileListEntry))]
+    [JsonSerializable(typeof(List<FileListEntry>), TypeInfoPropertyName = "FileListEntryList")]
+
+    // SubAgentsProvider types
+    [JsonSerializable(typeof(SubAgentState))]
+    [JsonSerializable(typeof(SubAgentRuntimeState))]
+    [JsonSerializable(typeof(SubTaskInfo))]
+    [JsonSerializable(typeof(SubTaskStatus))]
+    [JsonSerializable(typeof(List<SubTaskInfo>), TypeInfoPropertyName = "SubTaskInfoList")]
+
    [ExcludeFromCodeCoverage]
    internal sealed partial class JsonContext : JsonSerializerContext;
 }
@@ -188,7 +188,7 @@ internal sealed class PerServiceCallChatHistoryPersistingChatClient : Delegating
        while (hasUpdates)
        {
            var update = enumerator.Current;
-            responseUpdates.Add(update);
+            responseUpdates.Add(update.Clone());

            // If the service returned a real ConversationId on any update, remember that.
            // Otherwise stamp our sentinel so FICC treats this as service-managed —
@@ -0,0 +1,148 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.Logging;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI.Compaction;
+
+/// <summary>
+/// A compaction strategy that derives token thresholds from a model's context window size
+/// and maximum output tokens, applying a two-phase compaction pipeline:
+/// <list type="number">
+/// <item><description><b>Tool result eviction</b> (<see cref="ToolResultCompactionStrategy"/>) — collapses old tool call groups
+/// into concise summaries when the token count exceeds the <see cref="ToolEvictionThreshold"/>.</description></item>
+/// <item><description><b>Truncation</b> (<see cref="TruncationCompactionStrategy"/>) — removes the oldest non-system message groups
+/// when the token count exceeds the <see cref="TruncationThreshold"/>.</description></item>
+/// </list>
+/// </summary>
+/// <remarks>
+/// <para>
+/// The <b>input budget</b> is defined as <c>maxContextWindowTokens - maxOutputTokens</c>, representing
+/// the maximum number of tokens available for the conversation input (including system messages, tools, and history).
+/// </para>
+/// <para>
+/// This strategy is a convenience wrapper around <see cref="PipelineCompactionStrategy"/> that automates
+/// threshold calculation from model specifications.
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class ContextWindowCompactionStrategy : CompactionStrategy
+{
+    /// <summary>
+    /// The default fraction of the input budget at which tool result eviction triggers.
+    /// </summary>
+    public const double DefaultToolEvictionThreshold = 0.5;
+
+    /// <summary>
+    /// The default fraction of the input budget at which truncation triggers.
+    /// </summary>
+    public const double DefaultTruncationThreshold = 0.8;
+
+    private readonly PipelineCompactionStrategy _pipeline;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ContextWindowCompactionStrategy"/> class.
+    /// </summary>
+    /// <param name="maxContextWindowTokens">
+    /// The maximum number of tokens the model's context window supports (e.g., 1,050,000 for gpt-5.4).
+    /// </param>
+    /// <param name="maxOutputTokens">
+    /// The maximum number of output tokens the model can generate per response (e.g., 128,000 for gpt-5.4).
+    /// </param>
+    /// <param name="toolEvictionThreshold">
+    /// The fraction of the input budget (0.0, 1.0] at which tool result eviction triggers.
+    /// Defaults to <see cref="DefaultToolEvictionThreshold"/> (0.5).
+    /// </param>
+    /// <param name="truncationThreshold">
+    /// The fraction of the input budget (0.0, 1.0] at which truncation triggers.
+    /// Defaults to <see cref="DefaultTruncationThreshold"/> (0.8).
+    /// Must be greater than or equal to <paramref name="toolEvictionThreshold"/>.
+    /// </param>
+    /// <exception cref="ArgumentOutOfRangeException">
+    /// <paramref name="maxContextWindowTokens"/> is not positive, or
+    /// <paramref name="maxOutputTokens"/> is negative or greater than or equal to <paramref name="maxContextWindowTokens"/>, or
+    /// <paramref name="toolEvictionThreshold"/> or <paramref name="truncationThreshold"/> is not in (0.0, 1.0], or
+    /// <paramref name="truncationThreshold"/> is less than <paramref name="toolEvictionThreshold"/>.
+    /// </exception>
+    public ContextWindowCompactionStrategy(
+        int maxContextWindowTokens,
+        int maxOutputTokens,
+        double toolEvictionThreshold = DefaultToolEvictionThreshold,
+        double truncationThreshold = DefaultTruncationThreshold)
+        : base(CompactionTriggers.Always)
+    {
+        Throw.IfLessThanOrEqual(maxContextWindowTokens, 0);
+        Throw.IfLessThan(maxOutputTokens, 0);
+        Throw.IfGreaterThanOrEqual(maxOutputTokens, maxContextWindowTokens);
+
+        ValidateThreshold(toolEvictionThreshold, nameof(toolEvictionThreshold));
+        ValidateThreshold(truncationThreshold, nameof(truncationThreshold));
+
+        if (truncationThreshold < toolEvictionThreshold)
+        {
+            throw new ArgumentOutOfRangeException(nameof(truncationThreshold), truncationThreshold,
+                $"Truncation threshold ({truncationThreshold}) must be greater than or equal to tool eviction threshold ({toolEvictionThreshold}).");
+        }
+
+        this.MaxContextWindowTokens = maxContextWindowTokens;
+        this.MaxOutputTokens = maxOutputTokens;
+        this.InputBudgetTokens = maxContextWindowTokens - maxOutputTokens;
+        this.ToolEvictionThreshold = toolEvictionThreshold;
+        this.TruncationThreshold = truncationThreshold;
+
+        int toolEvictionTokens = (int)(this.InputBudgetTokens * toolEvictionThreshold);
+        int truncationTokens = (int)(this.InputBudgetTokens * truncationThreshold);
+
+        this._pipeline = new PipelineCompactionStrategy(
+            new ToolResultCompactionStrategy(
+                trigger: CompactionTriggers.TokensExceed(toolEvictionTokens),
+                minimumPreservedGroups: 2),
+            new TruncationCompactionStrategy(
+                trigger: CompactionTriggers.TokensExceed(truncationTokens),
+                minimumPreservedGroups: 2));
+    }
+
+    /// <summary>
+    /// Gets the maximum context window size in tokens.
+    /// </summary>
+    public int MaxContextWindowTokens { get; }
+
+    /// <summary>
+    /// Gets the maximum output tokens per response.
+    /// </summary>
+    public int MaxOutputTokens { get; }
+
+    /// <summary>
+    /// Gets the computed input budget in tokens (<see cref="MaxContextWindowTokens"/> minus <see cref="MaxOutputTokens"/>).
+    /// </summary>
+    public int InputBudgetTokens { get; }
+
+    /// <summary>
+    /// Gets the fraction of the input budget at which tool result eviction triggers.
+    /// </summary>
+    public double ToolEvictionThreshold { get; }
+
+    /// <summary>
+    /// Gets the fraction of the input budget at which truncation triggers.
+    /// </summary>
+    public double TruncationThreshold { get; }
+
+    /// <inheritdoc/>
+    protected override async ValueTask<bool> CompactCoreAsync(CompactionMessageIndex index, ILogger logger, CancellationToken cancellationToken)
+    {
+        return await this._pipeline.CompactAsync(index, logger, cancellationToken).ConfigureAwait(false);
+    }
+
+    private static void ValidateThreshold(double value, string paramName)
+    {
+        if (value is <= 0.0 or > 1.0)
+        {
+            throw new ArgumentOutOfRangeException(paramName, value, "Threshold must be in the range (0.0, 1.0].");
+        }
+    }
+}
@@ -1,6 +1,20 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- https://learn.microsoft.com/dotnet/fundamentals/package-validation/diagnostic-ids -->
 <Suppressions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentFileSkillScriptRunner.BeginInvoke(Microsoft.Agents.AI.AgentFileSkill,Microsoft.Agents.AI.AgentFileSkillScript,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken,System.AsyncCallback,System.Object)</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentFileSkillScriptRunner.Invoke(Microsoft.Agents.AI.AgentFileSkill,Microsoft.Agents.AI.AgentFileSkillScript,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken)</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
  <Suppression>
    <DiagnosticId>CP0002</DiagnosticId>
    <Target>M:Microsoft.Agents.AI.AgentInlineSkill.#ctor(Microsoft.Agents.AI.AgentSkillFrontmatter,System.String)</Target>
@@ -29,6 +43,13 @@
    <Right>lib/net10.0/Microsoft.Agents.AI.dll</Right>
    <IsBaselineSuppression>true</IsBaselineSuppression>
  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentSkillScript.RunAsync(Microsoft.Agents.AI.AgentSkill,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken)</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
  <Suppression>
    <DiagnosticId>CP0002</DiagnosticId>
    <Target>M:Microsoft.Agents.AI.AgentSkillsProvider.#ctor(Microsoft.Agents.AI.AgentInlineSkill[])</Target>
@@ -43,6 +64,20 @@
    <Right>lib/net10.0/Microsoft.Agents.AI.dll</Right>
    <IsBaselineSuppression>true</IsBaselineSuppression>
  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentFileSkillScriptRunner.BeginInvoke(Microsoft.Agents.AI.AgentFileSkill,Microsoft.Agents.AI.AgentFileSkillScript,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken,System.AsyncCallback,System.Object)</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentFileSkillScriptRunner.Invoke(Microsoft.Agents.AI.AgentFileSkill,Microsoft.Agents.AI.AgentFileSkillScript,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken)</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
  <Suppression>
    <DiagnosticId>CP0002</DiagnosticId>
    <Target>M:Microsoft.Agents.AI.AgentInlineSkill.#ctor(Microsoft.Agents.AI.AgentSkillFrontmatter,System.String)</Target>
@@ -71,6 +106,13 @@
    <Right>lib/net472/Microsoft.Agents.AI.dll</Right>
    <IsBaselineSuppression>true</IsBaselineSuppression>
  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentSkillScript.RunAsync(Microsoft.Agents.AI.AgentSkill,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken)</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
  <Suppression>
    <DiagnosticId>CP0002</DiagnosticId>
    <Target>M:Microsoft.Agents.AI.AgentSkillsProvider.#ctor(Microsoft.Agents.AI.AgentInlineSkill[])</Target>
@@ -85,6 +127,20 @@
    <Right>lib/net472/Microsoft.Agents.AI.dll</Right>
    <IsBaselineSuppression>true</IsBaselineSuppression>
  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentFileSkillScriptRunner.BeginInvoke(Microsoft.Agents.AI.AgentFileSkill,Microsoft.Agents.AI.AgentFileSkillScript,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken,System.AsyncCallback,System.Object)</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentFileSkillScriptRunner.Invoke(Microsoft.Agents.AI.AgentFileSkill,Microsoft.Agents.AI.AgentFileSkillScript,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken)</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
  <Suppression>
    <DiagnosticId>CP0002</DiagnosticId>
    <Target>M:Microsoft.Agents.AI.AgentInlineSkill.#ctor(Microsoft.Agents.AI.AgentSkillFrontmatter,System.String)</Target>
@@ -113,6 +169,13 @@
    <Right>lib/net8.0/Microsoft.Agents.AI.dll</Right>
    <IsBaselineSuppression>true</IsBaselineSuppression>
  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentSkillScript.RunAsync(Microsoft.Agents.AI.AgentSkill,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken)</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
  <Suppression>
    <DiagnosticId>CP0002</DiagnosticId>
    <Target>M:Microsoft.Agents.AI.AgentSkillsProvider.#ctor(Microsoft.Agents.AI.AgentInlineSkill[])</Target>
@@ -127,6 +190,20 @@
    <Right>lib/net8.0/Microsoft.Agents.AI.dll</Right>
    <IsBaselineSuppression>true</IsBaselineSuppression>
  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentFileSkillScriptRunner.BeginInvoke(Microsoft.Agents.AI.AgentFileSkill,Microsoft.Agents.AI.AgentFileSkillScript,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken,System.AsyncCallback,System.Object)</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentFileSkillScriptRunner.Invoke(Microsoft.Agents.AI.AgentFileSkill,Microsoft.Agents.AI.AgentFileSkillScript,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken)</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
  <Suppression>
    <DiagnosticId>CP0002</DiagnosticId>
    <Target>M:Microsoft.Agents.AI.AgentInlineSkill.#ctor(Microsoft.Agents.AI.AgentSkillFrontmatter,System.String)</Target>
@@ -155,6 +232,13 @@
    <Right>lib/net9.0/Microsoft.Agents.AI.dll</Right>
    <IsBaselineSuppression>true</IsBaselineSuppression>
  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentSkillScript.RunAsync(Microsoft.Agents.AI.AgentSkill,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken)</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
  <Suppression>
    <DiagnosticId>CP0002</DiagnosticId>
    <Target>M:Microsoft.Agents.AI.AgentSkillsProvider.#ctor(Microsoft.Agents.AI.AgentInlineSkill[])</Target>
@@ -169,6 +253,20 @@
    <Right>lib/net9.0/Microsoft.Agents.AI.dll</Right>
    <IsBaselineSuppression>true</IsBaselineSuppression>
  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentFileSkillScriptRunner.BeginInvoke(Microsoft.Agents.AI.AgentFileSkill,Microsoft.Agents.AI.AgentFileSkillScript,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken,System.AsyncCallback,System.Object)</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentFileSkillScriptRunner.Invoke(Microsoft.Agents.AI.AgentFileSkill,Microsoft.Agents.AI.AgentFileSkillScript,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken)</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
  <Suppression>
    <DiagnosticId>CP0002</DiagnosticId>
    <Target>M:Microsoft.Agents.AI.AgentInlineSkill.#ctor(Microsoft.Agents.AI.AgentSkillFrontmatter,System.String)</Target>
@@ -197,6 +295,13 @@
    <Right>lib/netstandard2.0/Microsoft.Agents.AI.dll</Right>
    <IsBaselineSuppression>true</IsBaselineSuppression>
  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentSkillScript.RunAsync(Microsoft.Agents.AI.AgentSkill,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken)</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
  <Suppression>
    <DiagnosticId>CP0002</DiagnosticId>
    <Target>M:Microsoft.Agents.AI.AgentSkillsProvider.#ctor(Microsoft.Agents.AI.AgentInlineSkill[])</Target>
@@ -211,4 +316,39 @@
    <Right>lib/netstandard2.0/Microsoft.Agents.AI.dll</Right>
    <IsBaselineSuppression>true</IsBaselineSuppression>
  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0005</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentSkillScript.RunAsync(Microsoft.Agents.AI.AgentSkill,System.Nullable{System.Text.Json.JsonElement},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0005</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentSkillScript.RunAsync(Microsoft.Agents.AI.AgentSkill,System.Nullable{System.Text.Json.JsonElement},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0005</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentSkillScript.RunAsync(Microsoft.Agents.AI.AgentSkill,System.Nullable{System.Text.Json.JsonElement},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0005</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentSkillScript.RunAsync(Microsoft.Agents.AI.AgentSkill,System.Nullable{System.Text.Json.JsonElement},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0005</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentSkillScript.RunAsync(Microsoft.Agents.AI.AgentSkill,System.Nullable{System.Text.Json.JsonElement},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
 </Suppressions>
@@ -0,0 +1,244 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// An <see cref="AIContextProvider"/> that tracks the agent's operating mode (e.g., "plan" or "execute")
+/// in the session state and provides tools for querying and switching modes.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The <see cref="AgentModeProvider"/> enables agents to operate in distinct modes during long-running
+/// complex tasks. The current mode is persisted in the session's <see cref="AgentSessionStateBag"/>
+/// and is included in the instructions provided to the agent on each invocation.
+/// </para>
+/// <para>
+/// The set of available modes is configurable via <see cref="AgentModeProviderOptions.Modes"/>.
+/// By default, two modes are provided: <c>"plan"</c> (interactive planning) and <c>"execute"</c>
+/// (autonomous execution).
+/// </para>
+/// <para>
+/// This provider exposes the following tools to the agent:
+/// <list type="bullet">
+/// <item><description><c>AgentMode_Set</c> — Switch the agent's operating mode.</description></item>
+/// <item><description><c>AgentMode_Get</c> — Retrieve the agent's current operating mode.</description></item>
+/// </list>
+/// </para>
+/// <para>
+/// Public helper methods <see cref="GetMode"/> and <see cref="SetMode"/> allow external code
+/// to programmatically read and change the mode.
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class AgentModeProvider : AIContextProvider
+{
+    private const string DefaultInstructions =
+        """
+        ## Agent Mode
+
+        You can operate in different modes. Depending on the mode you are in, you will be required to follow different processes.
+
+        Use the AgentMode_Get tool to check your current operating mode.
+        Use the AgentMode_Set tool to switch between modes as your work progresses. Only use AgentMode_Set if the user explicitly instructs/allows you to change modes.
+
+        {available_modes}
+
+        You are currently operating in the {current_mode} mode.
+        """;
+
+    private static readonly IReadOnlyList<AgentModeProviderOptions.AgentMode> s_defaultModes =
+    [
+        new("plan", "Use this mode when analyzing requirements, breaking down tasks, and creating plans. This is the interactive mode — ask clarifying questions, discuss options, and get user approval before proceeding."),
+        new("execute", "Use this mode when carrying out approved plans. Work autonomously using your best judgement — do not ask the user questions or wait for feedback. Make reasonable decisions on your own so that there is a complete, useful result when the user returns. If you encounter ambiguity, choose the most reasonable option and note your choice."),
+    ];
+
+    private readonly ProviderSessionState<AgentModeState> _sessionState;
+    private readonly IReadOnlyList<AgentModeProviderOptions.AgentMode> _modes;
+    private readonly string _defaultMode;
+    private readonly string? _instructions;
+    private readonly HashSet<string> _validModeNames;
+    private readonly string _modeNamesDisplay;
+    private IReadOnlyList<string>? _stateKeys;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AgentModeProvider"/> class.
+    /// </summary>
+    /// <param name="options">Optional settings that control provider behavior. When <see langword="null"/>, defaults are used.</param>
+    public AgentModeProvider(AgentModeProviderOptions? options = null)
+    {
+        this._modes = options?.Modes ?? s_defaultModes;
+
+        if (this._modes.Count == 0)
+        {
+            throw new ArgumentException("At least one mode must be configured.", nameof(options));
+        }
+
+        this._instructions = options?.Instructions ?? DefaultInstructions;
+
+        this._validModeNames = new HashSet<string>(StringComparer.Ordinal);
+        var modeNamesList = new List<string>(this._modes.Count);
+        for (int i = 0; i < this._modes.Count; i++)
+        {
+            var mode = this._modes[i];
+            if (mode is null)
+            {
+                throw new ArgumentException($"Configured mode at index {i} must not be null.", nameof(options));
+            }
+
+            if (string.IsNullOrEmpty(mode.Name))
+            {
+                throw new ArgumentException($"Configured mode at index {i} must have a non-empty name.", nameof(options));
+            }
+
+            if (!this._validModeNames.Add(mode.Name))
+            {
+                throw new ArgumentException($"Configured modes contain a duplicate mode name \"{mode.Name}\".", nameof(options));
+            }
+
+            modeNamesList.Add(mode.Name);
+        }
+
+        this._modeNamesDisplay = string.Join("\", \"", modeNamesList);
+        this._defaultMode = options?.DefaultMode ?? modeNamesList[0];
+
+        if (!this._validModeNames.Contains(this._defaultMode))
+        {
+            throw new ArgumentException($"Default mode \"{this._defaultMode}\" is not in the configured modes list.", nameof(options));
+        }
+
+        this._sessionState = new ProviderSessionState<AgentModeState>(
+            _ => new AgentModeState { CurrentMode = this._defaultMode },
+            this.GetType().Name,
+            AgentJsonUtilities.DefaultOptions);
+    }
+
+    /// <inheritdoc />
+    public override IReadOnlyList<string> StateKeys => this._stateKeys ??= [this._sessionState.StateKey];
+
+    /// <summary>
+    /// Gets the current operating mode from the session state.
+    /// </summary>
+    /// <param name="session">The agent session to read the mode from.</param>
+    /// <returns>The current mode string.</returns>
+    public string GetMode(AgentSession? session)
+    {
+        return this._sessionState.GetOrInitializeState(session).CurrentMode;
+    }
+
+    /// <summary>
+    /// Sets the operating mode in the session state.
+    /// </summary>
+    /// <param name="session">The agent session to update the mode in.</param>
+    /// <param name="mode">The new mode to set.</param>
+    /// <exception cref="ArgumentException"><paramref name="mode"/> is not a configured mode.</exception>
+    public void SetMode(AgentSession? session, string mode)
+    {
+        this.ValidateMode(mode);
+
+        AgentModeState state = this._sessionState.GetOrInitializeState(session);
+        string previousMode = state.CurrentMode;
+        state.CurrentMode = mode;
+
+        if (!string.Equals(previousMode, mode, StringComparison.Ordinal))
+        {
+            state.PreviousModeForNotification = previousMode;
+        }
+
+        this._sessionState.SaveState(session, state);
+    }
+
+    /// <inheritdoc />
+    protected override ValueTask<AIContext> ProvideAIContextAsync(InvokingContext context, CancellationToken cancellationToken = default)
+    {
+        AgentModeState state = this._sessionState.GetOrInitializeState(context.Session);
+
+        string instructions = this.BuildInstructions(state.CurrentMode);
+
+        var aiContext = new AIContext
+        {
+            Instructions = instructions,
+            Tools = this.CreateTools(state, context.Session),
+        };
+
+        // If the mode was changed externally (e.g., via /mode command), inject a notification message
+        // so the agent clearly sees the change rather than relying solely on the system instructions.
+        if (state.PreviousModeForNotification != null)
+        {
+            string previousMode = state.PreviousModeForNotification;
+            state.PreviousModeForNotification = null;
+
+            aiContext.Messages =
+            [
+                new ChatMessage(ChatRole.User, $"[Mode changed: The operating mode has been switched from \"{previousMode}\" to \"{state.CurrentMode}\". You must now adjust your behavior to match the \"{state.CurrentMode}\" mode.]"),
+            ];
+        }
+
+        return new ValueTask<AIContext>(aiContext);
+    }
+
+    private string BuildInstructions(string currentMode)
+    {
+        // Build list of modes text:
+        var modesListBuilder = new StringBuilder();
+        foreach (var mode in this._modes)
+        {
+            modesListBuilder.AppendLine($"- \"{mode.Name}\": {mode.Description}");
+        }
+        var modesListText = modesListBuilder.ToString();
+
+        return new StringBuilder(this._instructions)
+            .Replace("{available_modes}", modesListText)
+            .Replace("{current_mode}", currentMode)
+            .ToString();
+    }
+
+    private void ValidateMode(string mode)
+    {
+        if (!this._validModeNames.Contains(mode))
+        {
+            throw new ArgumentException($"Invalid mode: \"{mode}\". Supported modes are: \"{this._modeNamesDisplay}\".", nameof(mode));
+        }
+    }
+
+    private AITool[] CreateTools(AgentModeState state, AgentSession? session)
+    {
+        var serializerOptions = AgentJsonUtilities.DefaultOptions;
+
+        return
+        [
+            AIFunctionFactory.Create(
+                (string mode) =>
+                {
+                    this.ValidateMode(mode);
+
+                    state.CurrentMode = mode;
+                    this._sessionState.SaveState(session, state);
+                    return $"Mode changed to \"{mode}\".";
+                },
+                new AIFunctionFactoryOptions
+                {
+                    Name = "AgentMode_Set",
+                    Description = $"Switch the agent's operating mode. Supported modes: \"{this._modeNamesDisplay}\".",
+                    SerializerOptions = serializerOptions,
+                }),
+
+            AIFunctionFactory.Create(
+                () => state.CurrentMode,
+                new AIFunctionFactoryOptions
+                {
+                    Name = "AgentMode_Get",
+                    Description = "Get the agent's current operating mode.",
+                    SerializerOptions = serializerOptions,
+                }),
+        ];
+    }
+}
@@ -0,0 +1,77 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Options controlling the behavior of <see cref="AgentModeProvider"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class AgentModeProviderOptions
+{
+    /// <summary>
+    /// Gets or sets custom instructions provided to the agent for using the mode tools.
+    /// </summary>
+    /// <remarks>
+    /// The instructions must contain a <c>{available_modes}</c> placeholder for the provider to inject the
+    /// currently available list of modes, and a <c>{current_mode}</c> placeholder to inject the currently
+    /// active mode.
+    /// </remarks>
+    /// <value>
+    /// When <see langword="null"/> (the default), the provider uses a default set of instructions.
+    /// </value>
+    public string? Instructions { get; set; }
+
+    /// <summary>
+    /// Gets or sets the list of available modes the agent can operate in.
+    /// </summary>
+    /// <value>
+    /// When <see langword="null"/> (the default), the provider uses two built-in modes:
+    /// <c>"plan"</c> (interactive planning) and <c>"execute"</c> (autonomous execution).
+    /// </value>
+    public IReadOnlyList<AgentMode>? Modes { get; set; }
+
+    /// <summary>
+    /// Gets or sets the initial mode for new sessions.
+    /// </summary>
+    /// <value>
+    /// When <see langword="null"/> (the default), the first mode in the <see cref="Modes"/> list is used.
+    /// Must match the <see cref="AgentMode.Name"/> of one of the configured modes.
+    /// </value>
+    public string? DefaultMode { get; set; }
+
+    /// <summary>
+    /// Represents an agent operating mode with a name and description.
+    /// </summary>
+    [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+    public sealed class AgentMode
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AgentMode"/> class.
+        /// </summary>
+        /// <param name="name">The name of the mode.</param>
+        /// <param name="description">A description of when and how to use this mode.</param>
+        /// <exception cref="ArgumentNullException"><paramref name="name"/> or <paramref name="description"/> is <see langword="null"/>.</exception>
+        /// <exception cref="ArgumentException"><paramref name="name"/> or <paramref name="description"/> is empty or whitespace.</exception>
+        public AgentMode(string name, string description)
+        {
+            this.Name = Throw.IfNullOrWhitespace(name);
+            this.Description = Throw.IfNullOrWhitespace(description);
+        }
+
+        /// <summary>
+        /// Gets the name of the mode.
+        /// </summary>
+        public string Name { get; }
+
+        /// <summary>
+        /// Gets a description of when and how to use this mode.
+        /// </summary>
+        public string Description { get; }
+    }
+}
@@ -0,0 +1,27 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents the state of the agent's operating mode, stored in the session's <see cref="AgentSessionStateBag"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+internal sealed class AgentModeState
+{
+    /// <summary>
+    /// Gets or sets the current operating mode of the agent.
+    /// </summary>
+    [JsonPropertyName("currentMode")]
+    public string CurrentMode { get; set; } = "plan";
+
+    /// <summary>
+    /// Gets or sets the previous mode before the last external change, if a mode change notification is pending.
+    /// When non-null, indicates that the mode was changed externally and a notification should be injected.
+    /// </summary>
+    [JsonPropertyName("previousModeForNotification")]
+    public string? PreviousModeForNotification { get; set; }
+}
@@ -0,0 +1,180 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.ComponentModel;
+using System.Diagnostics.CodeAnalysis;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// An <see cref="AIContextProvider"/> that provides file access tools to an agent
+/// for saving, reading, deleting, listing, and searching files.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The <see cref="FileAccessProvider"/> gives agents the ability to work with files
+/// in a folder that the user has granted access to. Unlike <see cref="FileMemoryProvider"/>,
+/// which provides session-scoped memory that may be isolated per session, <see cref="FileAccessProvider"/>
+/// operates on a shared, persistent folder whose contents are visible across sessions and agents.
+/// This makes it suitable for reading input data, writing output artifacts, and working with
+/// files that have a lifetime beyond any single agent session.
+/// </para>
+/// <para>
+/// File access is mediated through a <see cref="AgentFileStore"/> abstraction, allowing pluggable
+/// backends (in-memory, local file system, remote blob storage, etc.).
+/// </para>
+/// <para>
+/// This provider exposes the following tools to the agent:
+/// <list type="bullet">
+/// <item><description><c>SaveFile</c> — Save a file with the given name and content.</description></item>
+/// <item><description><c>ReadFile</c> — Read the content of a file by name.</description></item>
+/// <item><description><c>DeleteFile</c> — Delete a file by name.</description></item>
+/// <item><description><c>ListFiles</c> — List all file names.</description></item>
+/// <item><description><c>SearchFiles</c> — Search file contents using a regular expression pattern.</description></item>
+/// </list>
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class FileAccessProvider : AIContextProvider
+{
+    private const string DefaultInstructions =
+        """
+        ## File Access
+        You have access to a shared file storage area via the `FileAccess_*` tools for reading, writing, and managing files.
+        These files persist beyond the current session and may be shared across sessions or agents.
+        Use these tools to read input data provided by the user, write output artifacts, and manage any files the user has asked you to work with.
+
+        - Never delete or overwrite existing files unless the user has explicitly asked you to do so.
+        """;
+
+    private readonly AgentFileStore _fileStore;
+    private readonly string _instructions;
+    private AITool[]? _tools;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FileAccessProvider"/> class.
+    /// </summary>
+    /// <param name="fileStore">
+    /// The file store implementation used for storage operations.
+    /// The store should already be scoped to the desired folder or storage location.
+    /// </param>
+    /// <param name="options">Optional settings that control provider behavior. When <see langword="null"/>, defaults are used.</param>
+    /// <exception cref="System.ArgumentNullException">Thrown when <paramref name="fileStore"/> is <see langword="null"/>.</exception>
+    public FileAccessProvider(AgentFileStore fileStore, FileAccessProviderOptions? options = null)
+    {
+        Throw.IfNull(fileStore);
+
+        this._fileStore = fileStore;
+        this._instructions = options?.Instructions ?? DefaultInstructions;
+    }
+
+    /// <inheritdoc />
+    public override IReadOnlyList<string> StateKeys => [];
+
+    /// <inheritdoc />
+    protected override ValueTask<AIContext> ProvideAIContextAsync(InvokingContext context, CancellationToken cancellationToken = default)
+    {
+        return new ValueTask<AIContext>(new AIContext
+        {
+            Instructions = this._instructions,
+            Tools = this._tools ??= this.CreateTools(),
+        });
+    }
+
+    /// <summary>
+    /// Save a file with the given name and content. By default, does not overwrite an existing file unless overwrite is set to true.
+    /// </summary>
+    /// <param name="fileName">The name of the file to save.</param>
+    /// <param name="content">The content to write to the file.</param>
+    /// <param name="overwrite">Whether to overwrite the file if it already exists.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A confirmation message.</returns>
+    [Description("Save a file with the given name and content. By default, does not overwrite an existing file unless overwrite is set to true.")]
+    private async Task<string> SaveFileAsync(string fileName, string content, bool overwrite = false, CancellationToken cancellationToken = default)
+    {
+        string path = StorePaths.NormalizeRelativePath(fileName);
+
+        if (!overwrite && await this._fileStore.FileExistsAsync(path, cancellationToken).ConfigureAwait(false))
+        {
+            return $"File '{fileName}' already exists. To replace it, save again with overwrite set to true.";
+        }
+
+        await this._fileStore.WriteFileAsync(path, content, cancellationToken).ConfigureAwait(false);
+        return $"File '{fileName}' saved.";
+    }
+
+    /// <summary>
+    /// Read the content of a file by name. Returns the file content or a message indicating the file was not found.
+    /// </summary>
+    /// <param name="fileName">The name of the file to read.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>The file content or a not-found message.</returns>
+    [Description("Read the content of a file by name. Returns the file content or a message indicating the file was not found.")]
+    private async Task<string> ReadFileAsync(string fileName, CancellationToken cancellationToken = default)
+    {
+        string path = StorePaths.NormalizeRelativePath(fileName);
+        string? content = await this._fileStore.ReadFileAsync(path, cancellationToken).ConfigureAwait(false);
+        return content ?? $"File '{fileName}' not found.";
+    }
+
+    /// <summary>
+    /// Delete a file by name.
+    /// </summary>
+    /// <param name="fileName">The name of the file to delete.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A confirmation or not-found message.</returns>
+    [Description("Delete a file by name.")]
+    private async Task<string> DeleteFileAsync(string fileName, CancellationToken cancellationToken = default)
+    {
+        string path = StorePaths.NormalizeRelativePath(fileName);
+        bool deleted = await this._fileStore.DeleteFileAsync(path, cancellationToken).ConfigureAwait(false);
+        return deleted ? $"File '{fileName}' deleted." : $"File '{fileName}' not found.";
+    }
+
+    /// <summary>
+    /// List all file names.
+    /// </summary>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A list of file names.</returns>
+    [Description("List all file names.")]
+    private async Task<List<string>> ListFilesAsync(CancellationToken cancellationToken = default)
+    {
+        IReadOnlyList<string> fileNames = await this._fileStore.ListFilesAsync(string.Empty, cancellationToken).ConfigureAwait(false);
+        return new List<string>(fileNames);
+    }
+
+    /// <summary>
+    /// Search file contents using a regular expression pattern (case-insensitive).
+    /// Optionally filter which files to search using a glob pattern.
+    /// </summary>
+    /// <param name="regexPattern">A regular expression pattern to match against file contents (case-insensitive).</param>
+    /// <param name="filePattern">An optional glob pattern to filter which files to search (e.g., "*.md", "research*"). Leave empty or omit to search all files.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A list of search results with matching file names, snippets, and matching lines.</returns>
+    [Description("Search file contents using a regular expression pattern (case-insensitive). Optionally filter which files to search using a glob pattern (e.g., \"*.md\", \"research*\"). Returns matching file names, snippets, and matching lines with line numbers.")]
+    private async Task<List<FileSearchResult>> SearchFilesAsync(string regexPattern, string? filePattern = null, CancellationToken cancellationToken = default)
+    {
+        string? pattern = string.IsNullOrWhiteSpace(filePattern) ? null : filePattern;
+        IReadOnlyList<FileSearchResult> results = await this._fileStore.SearchFilesAsync(string.Empty, regexPattern, pattern, cancellationToken).ConfigureAwait(false);
+        return new List<FileSearchResult>(results);
+    }
+
+    private AITool[] CreateTools()
+    {
+        var serializerOptions = AgentJsonUtilities.DefaultOptions;
+
+        return
+        [
+            AIFunctionFactory.Create(this.SaveFileAsync, new AIFunctionFactoryOptions { Name = "FileAccess_SaveFile", SerializerOptions = serializerOptions }),
+            AIFunctionFactory.Create(this.ReadFileAsync, new AIFunctionFactoryOptions { Name = "FileAccess_ReadFile", SerializerOptions = serializerOptions }),
+            AIFunctionFactory.Create(this.DeleteFileAsync, new AIFunctionFactoryOptions { Name = "FileAccess_DeleteFile", SerializerOptions = serializerOptions }),
+            AIFunctionFactory.Create(this.ListFilesAsync, new AIFunctionFactoryOptions { Name = "FileAccess_ListFiles", SerializerOptions = serializerOptions }),
+            AIFunctionFactory.Create(this.SearchFilesAsync, new AIFunctionFactoryOptions { Name = "FileAccess_SearchFiles", SerializerOptions = serializerOptions }),
+        ];
+    }
+}
@@ -0,0 +1,22 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Options controlling the behavior of <see cref="FileAccessProvider"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class FileAccessProviderOptions
+{
+    /// <summary>
+    /// Gets or sets custom instructions provided to the agent for using the file access tools.
+    /// </summary>
+    /// <value>
+    /// When <see langword="null"/> (the default), the provider uses built-in instructions
+    /// that guide the agent on how to use file storage effectively.
+    /// </value>
+    public string? Instructions { get; set; }
+}
@@ -0,0 +1,27 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents a file entry returned by the <see cref="FileMemoryProvider"/> list files tool,
+/// containing the file name and an optional description.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class FileListEntry
+{
+    /// <summary>
+    /// Gets or sets the name of the file.
+    /// </summary>
+    [JsonPropertyName("fileName")]
+    public string FileName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the description of the file, or <see langword="null"/> if no description is available.
+    /// </summary>
+    [JsonPropertyName("description")]
+    public string? Description { get; set; }
+}
@@ -0,0 +1,425 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.ComponentModel;
+using System.Diagnostics.CodeAnalysis;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// An <see cref="AIContextProvider"/> that provides file-based memory tools to an agent
+/// for storing, retrieving, modifying, listing, deleting, and searching files.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The <see cref="FileMemoryProvider"/> enables agents to persist information across interactions
+/// using a file-based storage model. Each memory is stored as an individual file with a meaningful name.
+/// For large files, a companion description file (suffixed with <c>_description.md</c>) can be stored
+/// alongside the main file to provide a summary.
+/// </para>
+/// <para>
+/// File access is mediated through a <see cref="AgentFileStore"/> abstraction, allowing pluggable
+/// backends (in-memory, local file system, remote blob storage, etc.).
+/// </para>
+/// <para>
+/// This provider exposes the following tools to the agent:
+/// <list type="bullet">
+/// <item><description><c>SaveFile</c> — Save a memory file with the given name, content, and an optional description.</description></item>
+/// <item><description><c>ReadFile</c> — Read the content of a file by name.</description></item>
+/// <item><description><c>DeleteFile</c> — Delete a file by name.</description></item>
+/// <item><description><c>ListFiles</c> — List all files with their descriptions (if available).</description></item>
+/// <item><description><c>SearchFiles</c> — Search file contents using a regular expression pattern.</description></item>
+/// </list>
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class FileMemoryProvider : AIContextProvider, IDisposable
+{
+    private const string DescriptionSuffix = "_description.md";
+    private const string MemoryIndexFileName = "memories.md";
+    private const int MaxIndexEntries = 50;
+
+    private const string DefaultInstructions =
+        """
+        ## File Based Memory
+        You have access to a session-scoped, file-based memory system via the `FileMemory_*` tools for storing and retrieving information across interactions.
+        These files act as your working memory for the current session and are isolated from other sessions.
+        Use these tools to store plans, memories, processing results, or downloaded data.
+
+        - Use descriptive file names (e.g., "projectarchitecture.md", "userpreferences.md").
+        - Include a description when saving a file to help with future discovery.
+        - Before starting new tasks, use FileMemory_ListFiles and FileMemory_SearchFiles to check for relevant existing memories.
+        - Keep memories up-to-date by overwriting files when information changes.
+        - When you receive large amounts of data (e.g., downloaded web pages, API responses, research results),
+          save them to files if they will be required later, so that they are not lost when older context is compacted or truncated.
+          This ensures important data remains accessible across long-running sessions.
+        """;
+
+    private readonly AgentFileStore _fileStore;
+    private readonly ProviderSessionState<FileMemoryState> _sessionState;
+    private readonly SemaphoreSlim _writeLock = new(1, 1);
+    private readonly string _instructions;
+    private IReadOnlyList<string>? _stateKeys;
+    private AITool[]? _tools;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FileMemoryProvider"/> class.
+    /// </summary>
+    /// <param name="fileStore">The file store implementation used for storage operations.</param>
+    /// <param name="stateInitializer">
+    /// An optional function that initializes the <see cref="FileMemoryState"/> for a new session.
+    /// Use this to customize the working folder (e.g., per-user or per-session subfolders).
+    /// When <see langword="null"/>, the default initializer creates state with an empty working folder.
+    /// </param>
+    /// <param name="options">Optional settings that control provider behavior. When <see langword="null"/>, defaults are used.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="fileStore"/> is <see langword="null"/>.</exception>
+    public FileMemoryProvider(AgentFileStore fileStore, Func<AgentSession?, FileMemoryState>? stateInitializer = null, FileMemoryProviderOptions? options = null)
+    {
+        Throw.IfNull(fileStore);
+
+        this._fileStore = fileStore;
+        this._instructions = options?.Instructions ?? DefaultInstructions;
+        this._sessionState = new ProviderSessionState<FileMemoryState>(
+            stateInitializer ?? (_ => new FileMemoryState()),
+            this.GetType().Name,
+            AgentJsonUtilities.DefaultOptions);
+    }
+
+    /// <inheritdoc />
+    public override IReadOnlyList<string> StateKeys => this._stateKeys ??= [this._sessionState.StateKey];
+
+    /// <summary>
+    /// Releases the resources used by the <see cref="FileMemoryProvider"/>.
+    /// </summary>
+    public void Dispose()
+    {
+        this._writeLock.Dispose();
+    }
+
+    /// <inheritdoc />
+    protected override async ValueTask<AIContext> ProvideAIContextAsync(InvokingContext context, CancellationToken cancellationToken = default)
+    {
+        FileMemoryState state = this._sessionState.GetOrInitializeState(context.Session);
+
+        // Ensure the working folder exists in the store.
+        if (!string.IsNullOrEmpty(state.WorkingFolder))
+        {
+            await this._fileStore.CreateDirectoryAsync(state.WorkingFolder, cancellationToken).ConfigureAwait(false);
+        }
+
+        var aiContext = new AIContext
+        {
+            Instructions = this._instructions,
+            Tools = this._tools ??= this.CreateTools(),
+        };
+
+        // Inject the memory index as a user message so the agent knows what memories are available.
+        string indexPath = CombinePaths(state.WorkingFolder, MemoryIndexFileName);
+        string? indexContent = await this._fileStore.ReadFileAsync(indexPath, cancellationToken).ConfigureAwait(false);
+        if (!string.IsNullOrWhiteSpace(indexContent))
+        {
+            aiContext.Messages =
+            [
+                new ChatMessage(ChatRole.User,
+                    "The following is your memory index — a list of files you have previously saved. " +
+                    "You can read any of these files using the FileMemory_ReadFile tool.\n\n" +
+                    indexContent),
+            ];
+        }
+
+        return aiContext;
+    }
+
+    /// <summary>
+    /// Save a memory file with the given name and content.
+    /// Overwrites the file if it already exists.
+    /// Include a description for large files to provide a summary that helps with discovery.
+    /// </summary>
+    /// <param name="fileName">The name of the file to save.</param>
+    /// <param name="content">The content to write to the file.</param>
+    /// <param name="description">An optional description of the file contents for discovery. Leave empty or omit to skip.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A confirmation message.</returns>
+    [Description("Save a memory file with the given name and content. Overwrites the file if it already exists. Include a description for large files to provide a summary that helps with discovery.")]
+    private async Task<string> SaveFileAsync(string fileName, string content, string? description = null, CancellationToken cancellationToken = default)
+    {
+        if (IsInternalFile(fileName))
+        {
+            throw new ArgumentException("The provided file name is reserved by the system for internal use. Please choose a different file name.", nameof(fileName));
+        }
+
+        FileMemoryState state = this._sessionState.GetOrInitializeState(AIAgent.CurrentRunContext?.Session);
+        string path = ResolvePath(state.WorkingFolder, fileName);
+
+        await this._writeLock.WaitAsync(cancellationToken).ConfigureAwait(false);
+        try
+        {
+            await this._fileStore.WriteFileAsync(path, content, cancellationToken).ConfigureAwait(false);
+
+            string descPath = ResolvePath(state.WorkingFolder, GetDescriptionFileName(fileName));
+
+            if (!string.IsNullOrWhiteSpace(description))
+            {
+                await this._fileStore.WriteFileAsync(descPath, description, cancellationToken).ConfigureAwait(false);
+            }
+            else
+            {
+                // Remove any stale description file when no description is provided.
+                await this._fileStore.DeleteFileAsync(descPath, cancellationToken).ConfigureAwait(false);
+            }
+
+            string result = string.IsNullOrWhiteSpace(description)
+                ? $"File '{fileName}' saved."
+                : $"File '{fileName}' saved with description.";
+
+            await this.RebuildMemoryIndexAsync(state, cancellationToken).ConfigureAwait(false);
+            return result;
+        }
+        finally
+        {
+            this._writeLock.Release();
+        }
+    }
+
+    /// <summary>
+    /// Read the content of a memory file by name.
+    /// Returns the file content or a message indicating the file was not found.
+    /// </summary>
+    /// <param name="fileName">The name of the file to read.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>The file content or a not-found message.</returns>
+    [Description("Read the content of a memory file by name. Returns the file content or a message indicating the file was not found.")]
+    private async Task<string> ReadFileAsync(string fileName, CancellationToken cancellationToken = default)
+    {
+        FileMemoryState state = this._sessionState.GetOrInitializeState(AIAgent.CurrentRunContext?.Session);
+        string path = ResolvePath(state.WorkingFolder, fileName);
+        string? content = await this._fileStore.ReadFileAsync(path, cancellationToken).ConfigureAwait(false);
+        return content ?? $"File '{fileName}' not found.";
+    }
+
+    /// <summary>
+    /// Delete a memory file by name. Also removes its companion description file if one exists.
+    /// </summary>
+    /// <param name="fileName">The name of the file to delete.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A confirmation or not-found message.</returns>
+    [Description("Delete a memory file by name. Also removes its companion description file if one exists.")]
+    private async Task<string> DeleteFileAsync(string fileName, CancellationToken cancellationToken = default)
+    {
+        FileMemoryState state = this._sessionState.GetOrInitializeState(AIAgent.CurrentRunContext?.Session);
+        string path = ResolvePath(state.WorkingFolder, fileName);
+
+        await this._writeLock.WaitAsync(cancellationToken).ConfigureAwait(false);
+        try
+        {
+            bool deleted = await this._fileStore.DeleteFileAsync(path, cancellationToken).ConfigureAwait(false);
+
+            // Also delete companion description file if it exists.
+            string descPath = ResolvePath(state.WorkingFolder, GetDescriptionFileName(fileName));
+            await this._fileStore.DeleteFileAsync(descPath, cancellationToken).ConfigureAwait(false);
+
+            await this.RebuildMemoryIndexAsync(state, cancellationToken).ConfigureAwait(false);
+            return deleted ? $"File '{fileName}' deleted." : $"File '{fileName}' not found.";
+        }
+        finally
+        {
+            this._writeLock.Release();
+        }
+    }
+
+    /// <summary>
+    /// List all memory files with their descriptions (if available). Description files are not shown separately.
+    /// </summary>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A list of file entries with names and optional descriptions.</returns>
+    [Description("List all memory files with their descriptions (if available). Description files are not shown separately.")]
+    private async Task<List<FileListEntry>> ListFilesAsync(CancellationToken cancellationToken = default)
+    {
+        FileMemoryState state = this._sessionState.GetOrInitializeState(AIAgent.CurrentRunContext?.Session);
+        IReadOnlyList<string> fileNames = await this._fileStore.ListFilesAsync(state.WorkingFolder, cancellationToken).ConfigureAwait(false);
+
+        var descriptionFileSet = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        foreach (string file in fileNames)
+        {
+            if (file.EndsWith(DescriptionSuffix, StringComparison.OrdinalIgnoreCase))
+            {
+                descriptionFileSet.Add(file);
+            }
+        }
+
+        var entries = new List<FileListEntry>();
+        foreach (string file in fileNames)
+        {
+            if (descriptionFileSet.Contains(file))
+            {
+                continue;
+            }
+
+            if (IsInternalFile(file))
+            {
+                continue;
+            }
+
+            string? fileDescription = null;
+            string descFileName = GetDescriptionFileName(file);
+
+            if (descriptionFileSet.Contains(descFileName))
+            {
+                string descPath = CombinePaths(state.WorkingFolder, descFileName);
+                fileDescription = await this._fileStore.ReadFileAsync(descPath, cancellationToken).ConfigureAwait(false);
+            }
+
+            entries.Add(new FileListEntry { FileName = file, Description = fileDescription });
+        }
+
+        return entries;
+    }
+
+    /// <summary>
+    /// Search memory file contents using a regular expression pattern (case-insensitive).
+    /// Optionally filter which files to search using a glob pattern.
+    /// Returns matching file names, content snippets, and matching lines with line numbers.
+    /// </summary>
+    /// <param name="regexPattern">A regular expression pattern to match against file contents (case-insensitive).</param>
+    /// <param name="filePattern">An optional glob pattern to filter which files to search (e.g., "*.md", "research*"). Leave empty or omit to search all files.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A list of search results with matching file names, snippets, and matching lines.</returns>
+    [Description("Search memory file contents using a regular expression pattern (case-insensitive). Optionally filter which files to search using a glob pattern (e.g., \"*.md\", \"research*\"). Returns matching file names, content snippets, and matching lines with line numbers.")]
+    private async Task<List<FileSearchResult>> SearchFilesAsync(string regexPattern, string? filePattern = null, CancellationToken cancellationToken = default)
+    {
+        FileMemoryState state = this._sessionState.GetOrInitializeState(AIAgent.CurrentRunContext?.Session);
+        string? pattern = string.IsNullOrWhiteSpace(filePattern) ? null : filePattern;
+        IReadOnlyList<FileSearchResult> results = await this._fileStore.SearchFilesAsync(state.WorkingFolder, regexPattern, pattern, cancellationToken).ConfigureAwait(false);
+
+        // Filter out internal files (description sidecars and memory index) so they stay hidden.
+        var filtered = new List<FileSearchResult>(results.Count);
+        foreach (var result in results)
+        {
+            if (IsInternalFile(result.FileName))
+            {
+                continue;
+            }
+
+            filtered.Add(result);
+        }
+
+        return filtered;
+    }
+
+    private AITool[] CreateTools()
+    {
+        var serializerOptions = AgentJsonUtilities.DefaultOptions;
+
+        return
+        [
+            AIFunctionFactory.Create(this.SaveFileAsync, new AIFunctionFactoryOptions { Name = "FileMemory_SaveFile", SerializerOptions = serializerOptions }),
+            AIFunctionFactory.Create(this.ReadFileAsync, new AIFunctionFactoryOptions { Name = "FileMemory_ReadFile", SerializerOptions = serializerOptions }),
+            AIFunctionFactory.Create(this.DeleteFileAsync, new AIFunctionFactoryOptions { Name = "FileMemory_DeleteFile", SerializerOptions = serializerOptions }),
+            AIFunctionFactory.Create(this.ListFilesAsync, new AIFunctionFactoryOptions { Name = "FileMemory_ListFiles", SerializerOptions = serializerOptions }),
+            AIFunctionFactory.Create(this.SearchFilesAsync, new AIFunctionFactoryOptions { Name = "FileMemory_SearchFiles", SerializerOptions = serializerOptions }),
+        ];
+    }
+
+    /// <summary>
+    /// Rebuilds the <c>memories.md</c> index file by listing all user files in the working folder,
+    /// reading their companion description files, and writing a markdown summary capped at <see cref="MaxIndexEntries"/> entries.
+    /// </summary>
+    private async Task RebuildMemoryIndexAsync(FileMemoryState state, CancellationToken cancellationToken)
+    {
+        IReadOnlyList<string> fileNames = await this._fileStore.ListFilesAsync(state.WorkingFolder, cancellationToken).ConfigureAwait(false);
+
+        // Sort deterministically so the index is stable across runs and platforms.
+        var sortedFiles = fileNames.OrderBy(f => f, StringComparer.OrdinalIgnoreCase).ToList();
+
+        var sb = new System.Text.StringBuilder();
+        sb.AppendLine("# Memory Index");
+        sb.AppendLine();
+
+        int count = 0;
+        foreach (string file in sortedFiles)
+        {
+            // Skip internal system files.
+            if (IsInternalFile(file))
+            {
+                continue;
+            }
+
+            if (count >= MaxIndexEntries)
+            {
+                break;
+            }
+
+            string? description = null;
+            string descFileName = GetDescriptionFileName(file);
+            string descPath = CombinePaths(state.WorkingFolder, descFileName);
+            description = await this._fileStore.ReadFileAsync(descPath, cancellationToken).ConfigureAwait(false);
+
+            if (!string.IsNullOrWhiteSpace(description))
+            {
+                sb.AppendLine($"- **{file}**: {description}");
+            }
+            else
+            {
+                sb.AppendLine($"- **{file}**");
+            }
+
+            count++;
+        }
+
+        string indexPath = CombinePaths(state.WorkingFolder, MemoryIndexFileName);
+        await this._fileStore.WriteFileAsync(indexPath, sb.ToString(), cancellationToken).ConfigureAwait(false);
+    }
+
+    private static string GetDescriptionFileName(string fileName)
+    {
+        int extIndex = fileName.LastIndexOf('.');
+        if (extIndex > 0)
+        {
+#pragma warning disable CA1845 // Use span-based 'string.Concat' — not available on all target frameworks
+            return fileName.Substring(0, extIndex) + DescriptionSuffix;
+#pragma warning restore CA1845
+        }
+
+        return fileName + DescriptionSuffix;
+    }
+
+    /// <summary>
+    /// Returns <see langword="true"/> if the file is an internal system file that should be hidden
+    /// from user-facing operations (description sidecars and the memory index).
+    /// </summary>
+    private static bool IsInternalFile(string fileName) =>
+        fileName.EndsWith(DescriptionSuffix, StringComparison.OrdinalIgnoreCase) ||
+        fileName.Equals(MemoryIndexFileName, StringComparison.OrdinalIgnoreCase);
+
+    private static string ResolvePath(string workingFolder, string fileName)
+    {
+        // Validate and normalize the file name (rejects rooted, traversal, empty, etc.).
+        // Only fileName needs validation — workingFolder is developer-provided and trusted.
+        string normalizedFileName = StorePaths.NormalizeRelativePath(fileName);
+
+        string normalizedWorkingFolder = workingFolder.Replace('\\', '/');
+        return CombinePaths(normalizedWorkingFolder, normalizedFileName);
+    }
+
+    private static string CombinePaths(string basePath, string relativePath)
+    {
+        if (string.IsNullOrEmpty(basePath))
+        {
+            return relativePath;
+        }
+
+        if (string.IsNullOrEmpty(relativePath))
+        {
+            return basePath;
+        }
+
+        return basePath.TrimEnd('/') + "/" + relativePath.TrimStart('/');
+    }
+}
@@ -0,0 +1,22 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Options controlling the behavior of <see cref="FileMemoryProvider"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class FileMemoryProviderOptions
+{
+    /// <summary>
+    /// Gets or sets custom instructions provided to the agent for using the file memory tools.
+    /// </summary>
+    /// <value>
+    /// When <see langword="null"/> (the default), the provider uses built-in instructions
+    /// that guide the agent on how to use file-based memory effectively.
+    /// </value>
+    public string? Instructions { get; set; }
+}
@@ -0,0 +1,21 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents the state of the <see cref="FileMemoryProvider"/>,
+/// stored in the session's <see cref="AgentSessionStateBag"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class FileMemoryState
+{
+    /// <summary>
+    /// Gets or sets the working folder path for this session, relative to the store root.
+    /// </summary>
+    [JsonPropertyName("workingFolder")]
+    public string WorkingFolder { get; set; } = string.Empty;
+}
@@ -0,0 +1,93 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.FileSystemGlobbing;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Provides an abstract base class for file storage operations.
+/// </summary>
+/// <remarks>
+/// <para>
+/// All paths are relative to an implementation-defined root. Implementations may map these
+/// paths to a local file system, in-memory store, remote blob storage, or other mechanisms.
+/// </para>
+/// <para>
+/// Paths use forward slashes as separators and must not escape the root (e.g., via <c>..</c> segments).
+/// It is up to each implementation to ensure that this is enforced.
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public abstract class AgentFileStore
+{
+    /// <summary>
+    /// Writes content to a file, creating or overwriting it.
+    /// </summary>
+    /// <param name="path">The relative path of the file to write.</param>
+    /// <param name="content">The content to write to the file.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A task representing the asynchronous operation.</returns>
+    public abstract Task WriteFileAsync(string path, string content, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Reads the content of a file.
+    /// </summary>
+    /// <param name="path">The relative path of the file to read.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>The file content, or <see langword="null"/> if the file does not exist.</returns>
+    public abstract Task<string?> ReadFileAsync(string path, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Deletes a file.
+    /// </summary>
+    /// <param name="path">The relative path of the file to delete.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns><see langword="true"/> if the file was deleted; <see langword="false"/> if it did not exist.</returns>
+    public abstract Task<bool> DeleteFileAsync(string path, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Lists files in a directory.
+    /// </summary>
+    /// <param name="directory">The relative path of the directory to list. Use an empty string for the root.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A list of file names in the specified directory (direct children only).</returns>
+    public abstract Task<IReadOnlyList<string>> ListFilesAsync(string directory, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Checks whether a file exists.
+    /// </summary>
+    /// <param name="path">The relative path of the file to check.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns><see langword="true"/> if the file exists; otherwise, <see langword="false"/>.</returns>
+    public abstract Task<bool> FileExistsAsync(string path, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Searches for files whose content matches a regular expression pattern.
+    /// </summary>
+    /// <param name="directory">The relative path of the directory to search. Use an empty string for the root.</param>
+    /// <param name="regexPattern">
+    /// A regular expression pattern to match against file contents. The pattern is matched case-insensitively.
+    /// For example, <c>"error|warning"</c> matches lines containing "error" or "warning".
+    /// </param>
+    /// <param name="filePattern">
+    /// An optional glob pattern to filter which files are searched (e.g., <c>"*.md"</c>, <c>"research*"</c>).
+    /// When <see langword="null"/>, all files in the directory are searched.
+    /// Uses standard glob syntax from <see cref="Matcher"/>.
+    /// </param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A list of search results with matching file names, snippets, and matching lines.</returns>
+    public abstract Task<IReadOnlyList<FileSearchResult>> SearchFilesAsync(string directory, string regexPattern, string? filePattern = null, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Ensures a directory exists, creating it if necessary.
+    /// </summary>
+    /// <param name="path">The relative path of the directory to create.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A task representing the asynchronous operation.</returns>
+    public abstract Task CreateDirectoryAsync(string path, CancellationToken cancellationToken = default);
+}
@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents a match found within a file during a search operation.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class FileSearchMatch
+{
+    /// <summary>
+    /// Gets or sets the 1-based line number where the match was found.
+    /// </summary>
+    [JsonPropertyName("lineNumber")]
+    public int LineNumber { get; set; }
+
+    /// <summary>
+    /// Gets or sets the content of the matching line.
+    /// </summary>
+    [JsonPropertyName("line")]
+    public string Line { get; set; } = string.Empty;
+}
@@ -0,0 +1,33 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents a result from searching files, containing the file name, a content snippet, and matching lines.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class FileSearchResult
+{
+    /// <summary>
+    /// Gets or sets the name of the file that matched the search.
+    /// </summary>
+    [JsonPropertyName("fileName")]
+    public string FileName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets a snippet of content from the file around the first match.
+    /// </summary>
+    [JsonPropertyName("snippet")]
+    public string Snippet { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the lines where matches were found.
+    /// </summary>
+    [JsonPropertyName("matchingLines")]
+    public List<FileSearchMatch> MatchingLines { get; set; } = [];
+}
@@ -0,0 +1,269 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.IO;
+using System.Linq;
+using System.Text;
+using System.Text.RegularExpressions;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.FileSystemGlobbing;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// A file-system-backed implementation of <see cref="AgentFileStore"/> that stores files on disk
+/// under a configurable root directory.
+/// </summary>
+/// <remarks>
+/// <para>
+/// All paths passed to this store are resolved relative to the root directory provided
+/// at construction time. Lexical path traversal attempts (for example, via <c>..</c> segments
+/// or absolute paths) are rejected with an <see cref="ArgumentException"/>.
+/// </para>
+/// <para>
+/// The root directory is created automatically if it does not already exist.
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class FileSystemAgentFileStore : AgentFileStore
+{
+    /// <summary>
+    /// The canonical full path of the root directory, always ending with a directory separator.
+    /// </summary>
+    private readonly string _rootPath;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FileSystemAgentFileStore"/> class.
+    /// </summary>
+    /// <param name="rootDirectory">
+    /// The root directory under which all files are stored. Created if it does not exist.
+    /// </param>
+    public FileSystemAgentFileStore(string rootDirectory)
+    {
+        _ = Throw.IfNullOrWhitespace(rootDirectory);
+
+        // Canonicalize the root and ensure it ends with a separator for prefix comparison.
+        string fullRoot = Path.GetFullPath(rootDirectory);
+        if (!fullRoot.EndsWith(Path.DirectorySeparatorChar.ToString(), StringComparison.Ordinal) &&
+            !fullRoot.EndsWith(Path.AltDirectorySeparatorChar.ToString(), StringComparison.Ordinal))
+        {
+            fullRoot += Path.DirectorySeparatorChar;
+        }
+
+        this._rootPath = fullRoot;
+        Directory.CreateDirectory(fullRoot);
+    }
+
+    /// <inheritdoc />
+    public override async Task WriteFileAsync(string path, string content, CancellationToken cancellationToken = default)
+    {
+        string fullPath = this.ResolveSafePath(path);
+
+        // Ensure the parent directory exists.
+        string? parentDir = Path.GetDirectoryName(fullPath);
+        if (parentDir is not null)
+        {
+            Directory.CreateDirectory(parentDir);
+        }
+
+#if NET8_0_OR_GREATER
+        await File.WriteAllTextAsync(fullPath, content, Encoding.UTF8, cancellationToken).ConfigureAwait(false);
+#else
+        using var writer = new StreamWriter(fullPath, false, Encoding.UTF8);
+        await writer.WriteAsync(content).ConfigureAwait(false);
+#endif
+    }
+
+    /// <inheritdoc />
+    public override async Task<string?> ReadFileAsync(string path, CancellationToken cancellationToken = default)
+    {
+        string fullPath = this.ResolveSafePath(path);
+
+        if (!File.Exists(fullPath))
+        {
+            return null;
+        }
+
+#if NET8_0_OR_GREATER
+        return await File.ReadAllTextAsync(fullPath, Encoding.UTF8, cancellationToken).ConfigureAwait(false);
+#else
+        using var reader = new StreamReader(fullPath, Encoding.UTF8);
+        return await reader.ReadToEndAsync().ConfigureAwait(false);
+#endif
+    }
+
+    /// <inheritdoc />
+    public override Task<bool> DeleteFileAsync(string path, CancellationToken cancellationToken = default)
+    {
+        string fullPath = this.ResolveSafePath(path);
+
+        if (!File.Exists(fullPath))
+        {
+            return Task.FromResult(false);
+        }
+
+        File.Delete(fullPath);
+        return Task.FromResult(true);
+    }
+
+    /// <inheritdoc />
+    public override Task<IReadOnlyList<string>> ListFilesAsync(string directory, CancellationToken cancellationToken = default)
+    {
+        string fullDir = this.ResolveSafeDirectoryPath(directory);
+
+        if (!Directory.Exists(fullDir))
+        {
+            return Task.FromResult<IReadOnlyList<string>>([]);
+        }
+
+        var files = Directory.GetFiles(fullDir)
+            .Select(Path.GetFileName)
+            .Where(name => name is not null)
+            .ToList();
+
+        return Task.FromResult<IReadOnlyList<string>>(files!);
+    }
+
+    /// <inheritdoc />
+    public override Task<bool> FileExistsAsync(string path, CancellationToken cancellationToken = default)
+    {
+        string fullPath = this.ResolveSafePath(path);
+        return Task.FromResult(File.Exists(fullPath));
+    }
+
+    /// <inheritdoc />
+    public override async Task<IReadOnlyList<FileSearchResult>> SearchFilesAsync(
+        string directory,
+        string regexPattern,
+        string? filePattern = null,
+        CancellationToken cancellationToken = default)
+    {
+        string fullDir = this.ResolveSafeDirectoryPath(directory);
+
+        if (!Directory.Exists(fullDir))
+        {
+            return [];
+        }
+
+        // Compile the regex with a timeout to guard against catastrophic backtracking (ReDoS).
+        var regex = new Regex(regexPattern, RegexOptions.IgnoreCase, TimeSpan.FromSeconds(5));
+        Matcher? matcher = filePattern is not null ? StorePaths.CreateGlobMatcher(filePattern) : null;
+        var results = new List<FileSearchResult>();
+
+        foreach (string filePath in Directory.GetFiles(fullDir))
+        {
+            string? fileName = Path.GetFileName(filePath);
+            if (fileName is null)
+            {
+                continue;
+            }
+
+            // Apply the optional glob filter on the file name.
+            if (!StorePaths.MatchesGlob(fileName, matcher))
+            {
+                continue;
+            }
+
+            // Read file content.
+#if NET8_0_OR_GREATER
+            string fileContent = await File.ReadAllTextAsync(filePath, Encoding.UTF8, cancellationToken).ConfigureAwait(false);
+#else
+            string fileContent;
+            using (var reader = new StreamReader(filePath, Encoding.UTF8))
+            {
+                fileContent = await reader.ReadToEndAsync().ConfigureAwait(false);
+            }
+#endif
+
+            // Search each line for regex matches, tracking line numbers and building a snippet.
+            string[] lines = fileContent.Split('\n');
+            var matchingLines = new List<FileSearchMatch>();
+            string? firstSnippet = null;
+            int lineStartOffset = 0;
+
+            for (int i = 0; i < lines.Length; i++)
+            {
+                Match match = regex.Match(lines[i]);
+                if (match.Success)
+                {
+                    matchingLines.Add(new FileSearchMatch { LineNumber = i + 1, Line = lines[i].TrimEnd('\r') });
+
+                    // Build a context snippet around the first match (±50 chars).
+                    if (firstSnippet is null)
+                    {
+                        int charIndex = lineStartOffset + match.Index;
+                        int snippetStart = Math.Max(0, charIndex - 50);
+                        int snippetEnd = Math.Min(fileContent.Length, charIndex + match.Value.Length + 50);
+                        firstSnippet = fileContent.Substring(snippetStart, snippetEnd - snippetStart);
+                    }
+                }
+
+                // Advance the offset past this line (including the '\n' separator).
+                lineStartOffset += lines[i].Length + 1;
+            }
+
+            if (matchingLines.Count > 0)
+            {
+                results.Add(new FileSearchResult
+                {
+                    FileName = fileName,
+                    Snippet = firstSnippet!,
+                    MatchingLines = matchingLines,
+                });
+            }
+        }
+
+        return results;
+    }
+
+    /// <inheritdoc />
+    public override Task CreateDirectoryAsync(string path, CancellationToken cancellationToken = default)
+    {
+        string fullPath = this.ResolveSafeDirectoryPath(path);
+        Directory.CreateDirectory(fullPath);
+        return Task.CompletedTask;
+    }
+
+    /// <summary>
+    /// Resolves a relative file path to a safe absolute path under the root directory.
+    /// Rejects paths that would escape the root via traversal or rooted paths.
+    /// </summary>
+    private string ResolveSafePath(string relativePath)
+    {
+        // Normalize and validate the relative path (rejects rooted, traversal, etc.).
+        string normalized = StorePaths.NormalizeRelativePath(relativePath);
+
+        // Convert to OS-native separators before combining.
+        string nativePath = normalized.Replace('/', Path.DirectorySeparatorChar);
+        string combined = Path.Combine(this._rootPath, nativePath);
+        string fullPath = Path.GetFullPath(combined);
+
+        if (!fullPath.StartsWith(this._rootPath, StringComparison.Ordinal))
+        {
+            throw new ArgumentException(
+                $"Invalid path: '{relativePath}'. The resolved path escapes the root directory.",
+                nameof(relativePath));
+        }
+
+        return fullPath;
+    }
+
+    /// <summary>
+    /// Resolves a relative directory path to a safe absolute path under the root directory.
+    /// An empty string resolves to the root directory itself.
+    /// </summary>
+    private string ResolveSafeDirectoryPath(string relativeDirectory)
+    {
+        if (string.IsNullOrEmpty(relativeDirectory))
+        {
+            return this._rootPath.TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);
+        }
+
+        return this.ResolveSafePath(relativeDirectory);
+    }
+}
@@ -0,0 +1,160 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Concurrent;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Linq;
+using System.Text.RegularExpressions;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.FileSystemGlobbing;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// An in-memory implementation of <see cref="AgentFileStore"/> that stores files in a dictionary.
+/// </summary>
+/// <remarks>
+/// This implementation is suitable for testing and lightweight scenarios where persistence is not required.
+/// Directory concepts are simulated using path prefixes — no explicit directory structure is maintained.
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class InMemoryAgentFileStore : AgentFileStore
+{
+    private readonly ConcurrentDictionary<string, string> _files = new(StringComparer.OrdinalIgnoreCase);
+
+    /// <inheritdoc />
+    public override Task WriteFileAsync(string path, string content, CancellationToken cancellationToken = default)
+    {
+        path = StorePaths.NormalizeRelativePath(path);
+        this._files[path] = content;
+        return Task.CompletedTask;
+    }
+
+    /// <inheritdoc />
+    public override Task<string?> ReadFileAsync(string path, CancellationToken cancellationToken = default)
+    {
+        path = StorePaths.NormalizeRelativePath(path);
+        this._files.TryGetValue(path, out string? content);
+        return Task.FromResult(content);
+    }
+
+    /// <inheritdoc />
+    public override Task<bool> DeleteFileAsync(string path, CancellationToken cancellationToken = default)
+    {
+        path = StorePaths.NormalizeRelativePath(path);
+        return Task.FromResult(this._files.TryRemove(path, out _));
+    }
+
+    /// <inheritdoc />
+    public override Task<IReadOnlyList<string>> ListFilesAsync(string directory, CancellationToken cancellationToken = default)
+    {
+        string prefix = StorePaths.NormalizeRelativePath(directory, isDirectory: true);
+        if (prefix.Length > 0 && !prefix.EndsWith("/", StringComparison.Ordinal))
+        {
+            prefix += "/";
+        }
+
+        var files = this._files.Keys
+            .Where(k => k.StartsWith(prefix, StringComparison.OrdinalIgnoreCase))
+            .Select(k => k.Substring(prefix.Length))
+            .Where(k => k.IndexOf("/", StringComparison.Ordinal) < 0)
+            .ToList();
+
+        return Task.FromResult<IReadOnlyList<string>>(files);
+    }
+
+    /// <inheritdoc />
+    public override Task<bool> FileExistsAsync(string path, CancellationToken cancellationToken = default)
+    {
+        path = StorePaths.NormalizeRelativePath(path);
+        return Task.FromResult(this._files.ContainsKey(path));
+    }
+
+    /// <inheritdoc />
+    public override Task<IReadOnlyList<FileSearchResult>> SearchFilesAsync(string directory, string regexPattern, string? filePattern = null, CancellationToken cancellationToken = default)
+    {
+        // Normalize the directory prefix for path matching.
+        string prefix = StorePaths.NormalizeRelativePath(directory, isDirectory: true);
+        if (prefix.Length > 0 && !prefix.EndsWith("/", StringComparison.Ordinal))
+        {
+            prefix += "/";
+        }
+
+        // Compile the regex with a timeout to guard against catastrophic backtracking (ReDoS).
+        var regex = new Regex(regexPattern, RegexOptions.IgnoreCase, TimeSpan.FromSeconds(5));
+        Matcher? matcher = filePattern is not null ? StorePaths.CreateGlobMatcher(filePattern) : null;
+        var results = new List<FileSearchResult>();
+
+        foreach (var kvp in this._files)
+        {
+            // Only consider files within the target directory (by path prefix).
+            if (!kvp.Key.StartsWith(prefix, StringComparison.OrdinalIgnoreCase))
+            {
+                continue;
+            }
+
+            // Exclude files in subdirectories (direct children only).
+            string relativeName = kvp.Key.Substring(prefix.Length);
+            if (relativeName.IndexOf("/", StringComparison.Ordinal) >= 0)
+            {
+                continue;
+            }
+
+            // Apply the optional glob filter on the file name.
+            if (!StorePaths.MatchesGlob(relativeName, matcher))
+            {
+                continue;
+            }
+
+            // Search each line for regex matches, tracking line numbers and building a snippet.
+            string fileContent = kvp.Value;
+            string[] lines = fileContent.Split('\n');
+            var matchingLines = new List<FileSearchMatch>();
+            string? firstSnippet = null;
+            int lineStartOffset = 0;
+
+            for (int i = 0; i < lines.Length; i++)
+            {
+                Match match = regex.Match(lines[i]);
+                if (match.Success)
+                {
+                    matchingLines.Add(new FileSearchMatch { LineNumber = i + 1, Line = lines[i].TrimEnd('\r') });
+
+                    // Build a context snippet around the first match (±50 chars).
+                    if (firstSnippet is null)
+                    {
+                        int charIndex = lineStartOffset + match.Index;
+                        int snippetStart = Math.Max(0, charIndex - 50);
+                        int snippetEnd = Math.Min(fileContent.Length, charIndex + match.Value.Length + 50);
+                        firstSnippet = fileContent.Substring(snippetStart, snippetEnd - snippetStart);
+                    }
+                }
+
+                // Advance the offset past this line (including the '\n' separator).
+                lineStartOffset += lines[i].Length + 1;
+            }
+
+            if (matchingLines.Count > 0)
+            {
+                results.Add(new FileSearchResult
+                {
+                    FileName = relativeName,
+                    Snippet = firstSnippet!,
+                    MatchingLines = matchingLines,
+                });
+            }
+        }
+
+        return Task.FromResult<IReadOnlyList<FileSearchResult>>(results);
+    }
+
+    /// <inheritdoc />
+    public override Task CreateDirectoryAsync(string path, CancellationToken cancellationToken = default)
+    {
+        // No-op: directories are implicit from file paths in the in-memory store.
+        return Task.CompletedTask;
+    }
+}
@@ -0,0 +1,119 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.IO;
+using Microsoft.Extensions.FileSystemGlobbing;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Internal helper for normalizing and validating relative store paths and matching glob patterns.
+/// Shared across <see cref="AgentFileStore"/> implementations and <see cref="FileMemoryProvider"/>.
+/// </summary>
+internal static class StorePaths
+{
+    /// <summary>
+    /// Normalizes a relative path by replacing backslashes with forward slashes, trimming leading
+    /// and trailing separators, and collapsing consecutive separators. Also validates that the path
+    /// does not contain rooted paths, drive roots, or <c>.</c>/<c>..</c> traversal segments.
+    /// </summary>
+    /// <param name="path">The relative path to normalize.</param>
+    /// <param name="isDirectory">
+    /// When <see langword="true"/>, the path represents a directory and an empty result (meaning root) is allowed.
+    /// When <see langword="false"/> (default), the path represents a file and an empty result is rejected.
+    /// </param>
+    /// <returns>The normalized forward-slash path.</returns>
+    /// <exception cref="ArgumentException">
+    /// Thrown when <paramref name="path"/> is rooted, starts with a drive letter, contains
+    /// <c>.</c> or <c>..</c> segments, or is empty when <paramref name="isDirectory"/> is <see langword="false"/>.
+    /// </exception>
+    internal static string NormalizeRelativePath(string path, bool isDirectory = false)
+    {
+        if (string.IsNullOrWhiteSpace(path))
+        {
+            if (!isDirectory)
+            {
+                throw new ArgumentException("A file path must not be empty or whitespace-only.", nameof(path));
+            }
+
+            return string.Empty;
+        }
+
+        string normalized = path.Replace('\\', '/').Trim('/');
+
+        if (Path.IsPathRooted(path) ||
+            path.StartsWith("/", StringComparison.Ordinal) ||
+            path.StartsWith("\\", StringComparison.Ordinal) ||
+            (normalized.Length >= 2 && char.IsLetter(normalized[0]) && normalized[1] == ':'))
+        {
+            throw new ArgumentException(
+                $"Invalid path: '{path}'. Paths must be relative and must not start with '/', '\\', or a drive root.",
+                nameof(path));
+        }
+
+        // Split, validate segments, and filter out empty segments to collapse consecutive separators.
+        string[] segments = normalized.Split('/');
+        var cleanSegments = new List<string>(segments.Length);
+        foreach (string segment in segments)
+        {
+            if (segment.Length == 0)
+            {
+                continue;
+            }
+
+            if (segment.Equals(".", StringComparison.Ordinal) || segment.Equals("..", StringComparison.Ordinal))
+            {
+                throw new ArgumentException(
+                    $"Invalid path: '{path}'. Paths must not contain '.' or '..' segments.",
+                    nameof(path));
+            }
+
+            cleanSegments.Add(segment);
+        }
+
+        string result = string.Join("/", cleanSegments);
+
+        if (!isDirectory && result.Length == 0)
+        {
+            throw new ArgumentException("A file path must not be empty.", nameof(path));
+        }
+
+        return result;
+    }
+
+    /// <summary>
+    /// Creates a <see cref="Matcher"/> for the specified glob pattern. Use the returned instance
+    /// to test multiple file names without allocating a new matcher for each one.
+    /// </summary>
+    /// <param name="filePattern">
+    /// The glob pattern to match against (e.g., <c>"*.md"</c>, <c>"research*"</c>).
+    /// </param>
+    /// <returns>A <see cref="Matcher"/> configured with the specified pattern.</returns>
+    internal static Matcher CreateGlobMatcher(string filePattern)
+    {
+        var matcher = new Matcher(StringComparison.OrdinalIgnoreCase);
+        matcher.AddInclude(filePattern);
+        return matcher;
+    }
+
+    /// <summary>
+    /// Determines whether a file name matches a pre-built glob <see cref="Matcher"/>.
+    /// </summary>
+    /// <param name="fileName">The file name to test (not a full path — just the name).</param>
+    /// <param name="matcher">
+    /// A pre-built <see cref="Matcher"/> to test against.
+    /// When <see langword="null"/>, this method returns <see langword="true"/> for any file name.
+    /// </param>
+    /// <returns><see langword="true"/> if the file name matches the pattern or if the matcher is <see langword="null"/>; otherwise, <see langword="false"/>.</returns>
+    internal static bool MatchesGlob(string fileName, Matcher? matcher)
+    {
+        if (matcher is null)
+        {
+            return true;
+        }
+
+        PatternMatchingResult result = matcher.Match(fileName);
+        return result.HasMatches;
+    }
+}
@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Text.Json.Serialization;
+using System.Threading.Tasks;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Holds non-serializable runtime references for in-flight sub-tasks within a single parent session.
+/// </summary>
+/// <remarks>
+/// Properties are marked with <see cref="JsonIgnoreAttribute"/> because <see cref="Task{TResult}"/>
+/// and <see cref="AgentSession"/> are not JSON-serializable. After deserialization (e.g., after a restart),
+/// a fresh empty instance is created and any previously-running tasks are marked as
+/// <see cref="SubTaskStatus.Lost"/> by <see cref="SubAgentsProvider"/>.
+/// </remarks>
+internal sealed class SubAgentRuntimeState
+{
+    /// <summary>
+    /// Gets the mapping of task IDs to their in-flight <see cref="Task{AgentResponse}"/> instances.
+    /// </summary>
+    [JsonIgnore]
+    public Dictionary<int, Task<AgentResponse>> InFlightTasks { get; } = [];
+
+    /// <summary>
+    /// Gets the mapping of task IDs to their sub-agent <see cref="AgentSession"/> instances,
+    /// needed for <c>ContinueTask</c>.
+    /// </summary>
+    [JsonIgnore]
+    public Dictionary<int, AgentSession> SubTaskSessions { get; } = [];
+}
@@ -0,0 +1,28 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents the serializable state of sub-tasks managed by the <see cref="SubAgentsProvider"/>,
+/// stored in the session's <see cref="AgentSessionStateBag"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+internal sealed class SubAgentState
+{
+    /// <summary>
+    /// Gets or sets the next ID to assign to a new sub-task.
+    /// </summary>
+    [JsonPropertyName("nextTaskId")]
+    public int NextTaskId { get; set; } = 1;
+
+    /// <summary>
+    /// Gets the list of sub-task metadata entries.
+    /// </summary>
+    [JsonPropertyName("tasks")]
+    public List<SubTaskInfo> Tasks { get; set; } = [];
+}
@@ -0,0 +1,458 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.ComponentModel;
+using System.Diagnostics.CodeAnalysis;
+using System.Linq;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// An <see cref="AIContextProvider"/> that enables an agent to delegate work to sub-agents asynchronously.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The <see cref="SubAgentsProvider"/> allows a parent agent to start sub-tasks on child agents,
+/// wait for their completion, and retrieve results. Each sub-task runs in its own session and
+/// executes concurrently.
+/// </para>
+/// <para>
+/// This provider exposes the following tools to the agent:
+/// <list type="bullet">
+/// <item><description><c>SubAgents_StartTask</c> — Start a sub-task on a named agent with text input. Returns the task ID.</description></item>
+/// <item><description><c>SubAgents_WaitForFirstCompletion</c> — Block until the first of the specified tasks completes. Returns the completed task's ID.</description></item>
+/// <item><description><c>SubAgents_GetTaskResults</c> — Retrieve the text output of a completed sub-task.</description></item>
+/// <item><description><c>SubAgents_GetAllTasks</c> — List all sub-tasks with their IDs, statuses, descriptions, and agent names.</description></item>
+/// <item><description><c>SubAgents_ContinueTask</c> — Send follow-up input to a completed sub-task's session to resume work.</description></item>
+/// <item><description><c>SubAgents_ClearCompletedTask</c> — Remove a completed sub-task and release its session to free memory.</description></item>
+/// </list>
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class SubAgentsProvider : AIContextProvider
+{
+    private const string DefaultInstructions =
+        """
+        ## SubAgents
+        You have access to sub-agents that can perform work on your behalf.
+
+        - Use the `SubAgents_*` list of tools to start tasks on sub agents and check their results.
+        - Creating a sub task does not block, and sub-tasks run concurrently.
+        - Important: Always wait for outstanding tasks to finish before you finish processing.
+        - Important: After retrieving results from a completed task, clear it with SubAgents_ClearCompletedTask to free memory, unless you plan to continue it with SubAgents_ContinueTask.
+
+        {sub_agents}
+        """;
+
+    private readonly Dictionary<string, AIAgent> _agents;
+    private readonly ProviderSessionState<SubAgentState> _sessionState;
+    private readonly ProviderSessionState<SubAgentRuntimeState> _runtimeSessionState;
+    private readonly string _instructions;
+    private IReadOnlyList<string>? _stateKeys;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="SubAgentsProvider"/> class.
+    /// </summary>
+    /// <param name="agents">The collection of sub-agents available for delegation.</param>
+    /// <param name="options">Optional settings controlling the provider behavior.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="agents"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentException">An agent has a null or empty name, or agent names are not unique.</exception>
+    public SubAgentsProvider(IEnumerable<AIAgent> agents, SubAgentsProviderOptions? options = null)
+    {
+        _ = Throw.IfNull(agents);
+
+        this._agents = ValidateAndBuildAgentDictionary(agents);
+
+        string baseInstructions = options?.Instructions ?? DefaultInstructions;
+        string agentListText = options?.AgentListBuilder is not null
+            ? options.AgentListBuilder(this._agents)
+            : BuildDefaultAgentListText(this._agents);
+        this._instructions = baseInstructions.Replace("{sub_agents}", agentListText);
+
+        this._sessionState = new ProviderSessionState<SubAgentState>(
+            _ => new SubAgentState(),
+            this.GetType().Name,
+            AgentJsonUtilities.DefaultOptions);
+
+        this._runtimeSessionState = new ProviderSessionState<SubAgentRuntimeState>(
+            _ => new SubAgentRuntimeState(),
+            this.GetType().Name + "_Runtime",
+            AgentJsonUtilities.DefaultOptions);
+    }
+
+    /// <inheritdoc />
+    public override IReadOnlyList<string> StateKeys => this._stateKeys ??= [this._sessionState.StateKey, this._runtimeSessionState.StateKey];
+
+    /// <inheritdoc />
+    protected override ValueTask<AIContext> ProvideAIContextAsync(InvokingContext context, CancellationToken cancellationToken = default)
+    {
+        SubAgentState state = this._sessionState.GetOrInitializeState(context.Session);
+        SubAgentRuntimeState runtimeState = this._runtimeSessionState.GetOrInitializeState(context.Session);
+
+        return new ValueTask<AIContext>(new AIContext
+        {
+            Instructions = this._instructions,
+            Tools = this.CreateTools(state, runtimeState, context.Session),
+        });
+    }
+
+    /// <summary>
+    /// Validates the agent collection and builds a case-insensitive name dictionary.
+    /// </summary>
+    private static Dictionary<string, AIAgent> ValidateAndBuildAgentDictionary(IEnumerable<AIAgent> agents)
+    {
+        var dict = new Dictionary<string, AIAgent>(StringComparer.OrdinalIgnoreCase);
+        foreach (AIAgent agent in agents)
+        {
+            if (string.IsNullOrWhiteSpace(agent.Name))
+            {
+                throw new ArgumentException("All sub-agents must have a non-empty Name.", nameof(agents));
+            }
+
+            if (dict.ContainsKey(agent.Name))
+            {
+                throw new ArgumentException($"Duplicate sub-agent name: '{agent.Name}'. Agent names must be unique (case-insensitive).", nameof(agents));
+            }
+
+            dict[agent.Name] = agent;
+        }
+
+        if (dict.Count == 0)
+        {
+            throw new ArgumentException("At least one sub-agent must be provided.", nameof(agents));
+        }
+
+        return dict;
+    }
+
+    /// <summary>
+    /// Builds the default text listing available sub-agents and their descriptions.
+    /// </summary>
+    private static string BuildDefaultAgentListText(IReadOnlyDictionary<string, AIAgent> agents)
+    {
+        var sb = new StringBuilder();
+        sb.AppendLine("Available sub-agents:");
+        foreach (var kvp in agents)
+        {
+            sb.Append("- ").Append(kvp.Key);
+            if (!string.IsNullOrWhiteSpace(kvp.Value.Description))
+            {
+                sb.Append(": ").Append(kvp.Value.Description);
+            }
+
+            sb.AppendLine();
+        }
+
+        return sb.ToString();
+    }
+
+    /// <summary>
+    /// Refreshes the status of in-flight tasks in the given state for the specified session.
+    /// </summary>
+    private void TryRefreshTaskState(SubAgentState state, SubAgentRuntimeState runtimeState, AgentSession? session)
+    {
+        bool changed = false;
+        foreach (SubTaskInfo task in state.Tasks)
+        {
+            if (task.Status != SubTaskStatus.Running)
+            {
+                continue;
+            }
+
+            if (!runtimeState.InFlightTasks.TryGetValue(task.Id, out Task<AgentResponse>? inFlight))
+            {
+                // In-flight reference lost (e.g., after restart/deserialization).
+                task.Status = SubTaskStatus.Lost;
+                changed = true;
+                continue;
+            }
+
+            if (inFlight.IsCompleted)
+            {
+                FinalizeTask(task, inFlight, runtimeState);
+                changed = true;
+            }
+        }
+
+        if (changed)
+        {
+            this._sessionState.SaveState(session, state);
+        }
+    }
+
+    /// <summary>
+    /// Finalizes a task by extracting results from the completed Task and updating the SubTaskInfo.
+    /// </summary>
+    private static void FinalizeTask(SubTaskInfo taskInfo, Task<AgentResponse> completedTask, SubAgentRuntimeState runtimeState)
+    {
+        if (completedTask.Status == TaskStatus.RanToCompletion)
+        {
+            taskInfo.Status = SubTaskStatus.Completed;
+#pragma warning disable VSTHRD002 // Avoid problematic synchronous waits — task is already completed
+            taskInfo.ResultText = completedTask.Result.Text;
+#pragma warning restore VSTHRD002
+        }
+        else if (completedTask.IsFaulted)
+        {
+            taskInfo.Status = SubTaskStatus.Failed;
+            taskInfo.ErrorText = completedTask.Exception?.InnerException?.Message ?? completedTask.Exception?.Message ?? "Unknown error";
+        }
+        else if (completedTask.IsCanceled)
+        {
+            taskInfo.Status = SubTaskStatus.Failed;
+            taskInfo.ErrorText = "Task was canceled.";
+        }
+
+        runtimeState.InFlightTasks.Remove(taskInfo.Id);
+    }
+
+    private AITool[] CreateTools(SubAgentState state, SubAgentRuntimeState runtimeState, AgentSession? session)
+    {
+        var serializerOptions = AgentJsonUtilities.DefaultOptions;
+
+        return
+        [
+            AIFunctionFactory.Create(
+                async (
+                    [Description("The name of the sub agent to delegate the task to.")] string agentName,
+                    [Description("The request to pass to the sub agent.")] string input,
+                    [Description("A description of the task used to identify the task later.")] string description) =>
+                {
+                    if (!this._agents.TryGetValue(agentName, out AIAgent? agent))
+                    {
+                        return $"Error: No sub-agent found with name '{agentName}'. Available agents: {string.Join(", ", this._agents.Keys)}";
+                    }
+
+                    int taskId = state.NextTaskId++;
+                    var taskInfo = new SubTaskInfo
+                    {
+                        Id = taskId,
+                        AgentName = agentName,
+                        Description = description,
+                        Status = SubTaskStatus.Running,
+                    };
+                    state.Tasks.Add(taskInfo);
+
+                    // Create a dedicated session for this sub-task so it can be continued later.
+                    AgentSession subSession = await agent.CreateSessionAsync().ConfigureAwait(false);
+
+                    // Wrap in Task.Run to fork the ExecutionContext. AIAgent.RunAsync is a non-async
+                    // method that synchronously sets the static AsyncLocal CurrentRunContext. Without
+                    // this isolation, the sub-agent's RunAsync would overwrite the outer (calling)
+                    // agent's CurrentRunContext, corrupting all subsequent tool invocations in the
+                    // same FICC batch.
+                    runtimeState.InFlightTasks[taskId] = Task.Run(() => agent.RunAsync(input, subSession));
+                    runtimeState.SubTaskSessions[taskId] = subSession;
+
+                    this._sessionState.SaveState(session, state);
+                    return $"Sub-task {taskId} started on agent '{agentName}'.";
+                },
+                new AIFunctionFactoryOptions
+                {
+                    Name = "SubAgents_StartTask",
+                    Description = "Start a sub-task on a named sub-agent. Returns a confirmation message containing the task ID.",
+                    SerializerOptions = serializerOptions,
+                }),
+
+            AIFunctionFactory.Create(
+                async (List<int> taskIds) =>
+                {
+                    if (taskIds.Count == 0)
+                    {
+                        return "Error: No task IDs provided.";
+                    }
+
+                    // Collect in-flight tasks matching the requested IDs (including already-completed ones,
+                    // since Task.WhenAny returns immediately for completed tasks).
+                    var waitableTasks = new List<(int Id, Task<AgentResponse> Task)>();
+                    foreach (int id in taskIds)
+                    {
+                        if (runtimeState.InFlightTasks.TryGetValue(id, out Task<AgentResponse>? inFlight))
+                        {
+                            waitableTasks.Add((id, inFlight));
+                        }
+                    }
+
+                    if (waitableTasks.Count == 0)
+                    {
+                        // Refresh state to catch any that completed.
+                        this.TryRefreshTaskState(state, runtimeState, session);
+                        this._sessionState.SaveState(session, state);
+
+                        // Check if any of the requested IDs are already complete.
+                        SubTaskInfo? alreadyComplete = state.Tasks.FirstOrDefault(t => taskIds.Contains(t.Id) && t.Status != SubTaskStatus.Running);
+                        if (alreadyComplete is not null)
+                        {
+                            return $"Task {alreadyComplete.Id} is not running; current status: {alreadyComplete.Status}.";
+                        }
+
+                        return "Error: None of the specified task IDs correspond to running tasks.";
+                    }
+
+                    // Wait for the first one to complete.
+                    Task completedTask = await Task.WhenAny(waitableTasks.Select(t => t.Task)).ConfigureAwait(false);
+
+                    // Find which ID completed.
+                    var completedEntry = waitableTasks.First(t => t.Task == completedTask);
+
+                    // Finalize the completed task.
+                    SubTaskInfo? taskInfo = state.Tasks.FirstOrDefault(t => t.Id == completedEntry.Id);
+                    if (taskInfo is not null)
+                    {
+                        FinalizeTask(taskInfo, completedEntry.Task, runtimeState);
+                        this._sessionState.SaveState(session, state);
+                    }
+
+                    return $"Task {completedEntry.Id} finished with status: {taskInfo?.Status.ToString() ?? "Unknown"}.";
+                },
+                new AIFunctionFactoryOptions
+                {
+                    Name = "SubAgents_WaitForFirstCompletion",
+                    Description = "Block until the first of the specified sub-tasks completes. Provide one or more task IDs. Returns a status message containing the ID of the task that completed first.",
+                    SerializerOptions = serializerOptions,
+                }),
+
+            AIFunctionFactory.Create(
+                (int taskId) =>
+                {
+                    this.TryRefreshTaskState(state, runtimeState, session);
+
+                    SubTaskInfo? taskInfo = state.Tasks.FirstOrDefault(t => t.Id == taskId);
+                    if (taskInfo is null)
+                    {
+                        return $"Error: No task found with ID {taskId}.";
+                    }
+
+                    return taskInfo.Status switch
+                    {
+                        SubTaskStatus.Completed => taskInfo.ResultText ?? "(no output)",
+                        SubTaskStatus.Failed => $"Task failed: {taskInfo.ErrorText ?? "Unknown error"}",
+                        SubTaskStatus.Lost => "Task state was lost (reference unavailable).",
+                        SubTaskStatus.Running => $"Task {taskId} is still running.",
+                        _ => $"Task {taskId} has status: {taskInfo.Status}.",
+                    };
+                },
+                new AIFunctionFactoryOptions
+                {
+                    Name = "SubAgents_GetTaskResults",
+                    Description = "Get the text output of a sub-task by its ID. Returns the result text if complete, or status information if still running or failed.",
+                    SerializerOptions = serializerOptions,
+                }),
+
+            AIFunctionFactory.Create(
+                () =>
+                {
+                    this.TryRefreshTaskState(state, runtimeState, session);
+
+                    if (state.Tasks.Count == 0)
+                    {
+                        return "No tasks.";
+                    }
+
+                    var sb = new StringBuilder();
+                    sb.AppendLine("Tasks:");
+                    foreach (SubTaskInfo task in state.Tasks)
+                    {
+                        sb.Append("- Task ").Append(task.Id).Append(" [").Append(task.Status).Append("] (").Append(task.AgentName).Append("): ").AppendLine(task.Description);
+                    }
+
+                    return sb.ToString();
+                },
+                new AIFunctionFactoryOptions
+                {
+                    Name = "SubAgents_GetAllTasks",
+                    Description = "List all sub-tasks with their IDs, statuses, agent names, and descriptions.",
+                    SerializerOptions = serializerOptions,
+                }),
+
+            AIFunctionFactory.Create(
+                (int taskId, string text) =>
+                {
+                    this.TryRefreshTaskState(state, runtimeState, session);
+
+                    SubTaskInfo? taskInfo = state.Tasks.FirstOrDefault(t => t.Id == taskId);
+                    if (taskInfo is null)
+                    {
+                        return $"Error: No task found with ID {taskId}.";
+                    }
+
+                    if (taskInfo.Status == SubTaskStatus.Lost)
+                    {
+                        return $"Error: Task {taskId} cannot be continued because its session was lost (e.g., after a session restore). Start a new task instead.";
+                    }
+
+                    if (taskInfo.Status == SubTaskStatus.Running)
+                    {
+                        return $"Error: Task {taskId} is still running. Wait for it to complete before continuing.";
+                    }
+
+                    if (!this._agents.TryGetValue(taskInfo.AgentName, out AIAgent? agent))
+                    {
+                        return $"Error: Agent '{taskInfo.AgentName}' is no longer available.";
+                    }
+
+                    if (!runtimeState.SubTaskSessions.TryGetValue(taskId, out AgentSession? subSession))
+                    {
+                        return $"Error: Session for task {taskId} is no longer available.";
+                    }
+
+                    // Reset task state and start a new run on the existing session.
+                    taskInfo.Status = SubTaskStatus.Running;
+                    taskInfo.ResultText = null;
+                    taskInfo.ErrorText = null;
+
+                    // Wrap in Task.Run to isolate the ExecutionContext (see StartSubTask comment).
+                    runtimeState.InFlightTasks[taskId] = Task.Run(() => agent.RunAsync(text, subSession));
+
+                    this._sessionState.SaveState(session, state);
+                    return $"Task {taskId} continued with new input.";
+                },
+                new AIFunctionFactoryOptions
+                {
+                    Name = "SubAgents_ContinueTask",
+                    Description = "Send follow-up input to a completed or failed sub-task to resume its work. The sub-task's session is preserved, so the agent retains conversational context.",
+                    SerializerOptions = serializerOptions,
+                }),
+
+            AIFunctionFactory.Create(
+                (int taskId) =>
+                {
+                    this.TryRefreshTaskState(state, runtimeState, session);
+
+                    SubTaskInfo? taskInfo = state.Tasks.FirstOrDefault(t => t.Id == taskId);
+                    if (taskInfo is null)
+                    {
+                        return $"Error: No task found with ID {taskId}.";
+                    }
+
+                    if (taskInfo.Status == SubTaskStatus.Running)
+                    {
+                        return $"Error: Task {taskId} is still running. Wait for it to complete before clearing.";
+                    }
+
+                    // Remove the task from state.
+                    state.Tasks.Remove(taskInfo);
+
+                    // Clean up runtime references.
+                    runtimeState.InFlightTasks.Remove(taskId);
+                    runtimeState.SubTaskSessions.Remove(taskId);
+
+                    this._sessionState.SaveState(session, state);
+                    return $"Task {taskId} cleared.";
+                },
+                new AIFunctionFactoryOptions
+                {
+                    Name = "SubAgents_ClearCompletedTask",
+                    Description = "Remove a completed or failed sub-task and release its session to free memory. Use this after retrieving results when you no longer need to continue the task.",
+                    SerializerOptions = serializerOptions,
+                }),
+        ];
+    }
+}
@@ -0,0 +1,39 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Options controlling the behavior of <see cref="SubAgentsProvider"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class SubAgentsProviderOptions
+{
+    /// <summary>
+    /// Gets or sets custom instructions provided to the agent for using the sub-agent tools.
+    /// </summary>
+    /// <remarks>
+    /// Use the <c>{sub_agents}</c> placeholder to allow the provider to inject
+    /// the formatted list of available sub agents.
+    /// </remarks>
+    /// <value>
+    /// When <see langword="null"/> (the default), the provider uses built-in instructions
+    /// that guide the agent on how to use the sub-agent tools.
+    /// The agent list is always appended after the instructions regardless of this setting.
+    /// </value>
+    public string? Instructions { get; set; }
+
+    /// <summary>
+    /// Gets or sets a custom function that builds the agent list text to append to instructions.
+    /// </summary>
+    /// <value>
+    /// When <see langword="null"/> (the default), the provider generates a standard list of agent names and descriptions.
+    /// When set, this function receives the dictionary of available agents (keyed by name) and should return
+    /// a formatted string describing the available sub-agents.
+    /// </value>
+    public Func<IReadOnlyDictionary<string, AIAgent>, string>? AgentListBuilder { get; set; }
+}
@@ -0,0 +1,50 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents the metadata and result of a sub-task managed by the <see cref="SubAgentsProvider"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class SubTaskInfo
+{
+    /// <summary>
+    /// Gets or sets the unique identifier for this sub-task.
+    /// </summary>
+    [JsonPropertyName("id")]
+    public int Id { get; set; }
+
+    /// <summary>
+    /// Gets or sets the name of the agent that is executing this sub-task.
+    /// </summary>
+    [JsonPropertyName("agentName")]
+    public string AgentName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets a description of what this sub-task is doing.
+    /// </summary>
+    [JsonPropertyName("description")]
+    public string Description { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the current status of this sub-task.
+    /// </summary>
+    [JsonPropertyName("status")]
+    public SubTaskStatus Status { get; set; }
+
+    /// <summary>
+    /// Gets or sets the text result of the sub-task, populated when the task completes successfully.
+    /// </summary>
+    [JsonPropertyName("resultText")]
+    public string? ResultText { get; set; }
+
+    /// <summary>
+    /// Gets or sets the error message if the sub-task failed.
+    /// </summary>
+    [JsonPropertyName("errorText")]
+    public string? ErrorText { get; set; }
+}
@@ -0,0 +1,34 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents the status of a sub-task managed by the <see cref="SubAgentsProvider"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public enum SubTaskStatus
+{
+    /// <summary>
+    /// The sub-task is currently running.
+    /// </summary>
+    Running,
+
+    /// <summary>
+    /// The sub-task completed successfully.
+    /// </summary>
+    Completed,
+
+    /// <summary>
+    /// The sub-task failed with an error.
+    /// </summary>
+    Failed,
+
+    /// <summary>
+    /// The sub-task's in-flight reference was lost (e.g., after a restart),
+    /// and its final state cannot be determined.
+    /// </summary>
+    Lost,
+}
@@ -0,0 +1,38 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents a single todo item managed by the <see cref="TodoProvider"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class TodoItem
+{
+    /// <summary>
+    /// Gets or sets the unique identifier for this todo item.
+    /// </summary>
+    [JsonPropertyName("id")]
+    public int Id { get; set; }
+
+    /// <summary>
+    /// Gets or sets the title of this todo item.
+    /// </summary>
+    [JsonPropertyName("title")]
+    public string Title { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets an optional description providing additional details about this todo item.
+    /// </summary>
+    [JsonPropertyName("description")]
+    public string? Description { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether this todo item has been completed.
+    /// </summary>
+    [JsonPropertyName("isComplete")]
+    public bool IsComplete { get; set; }
+}
@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents the input for creating a new todo item via the <see cref="TodoProvider"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+internal sealed class TodoItemInput
+{
+    /// <summary>
+    /// Gets or sets the title of the todo item to create.
+    /// </summary>
+    [JsonPropertyName("title")]
+    public string Title { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets an optional description providing additional details about the todo item.
+    /// </summary>
+    [JsonPropertyName("description")]
+    public string? Description { get; set; }
+}
@@ -0,0 +1,209 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// An <see cref="AIContextProvider"/> that provides todo management tools and instructions
+/// to an agent for tracking work items during long-running complex tasks.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The <see cref="TodoProvider"/> enables agents to create, complete, remove, and query todo items
+/// as part of their planning and execution workflow. Todo state is stored in the session's
+/// <see cref="AgentSessionStateBag"/> and persists across agent invocations within the same session.
+/// </para>
+/// <para>
+/// This provider exposes the following tools to the agent:
+/// <list type="bullet">
+/// <item><description><c>TodoList_Add</c> — Add one or more todo items, each with a title and optional description.</description></item>
+/// <item><description><c>TodoList_Complete</c> — Mark one or more todo items as complete by their IDs.</description></item>
+/// <item><description><c>TodoList_Remove</c> — Remove one or more todo items by their IDs.</description></item>
+/// <item><description><c>TodoList_GetRemaining</c> — Retrieve only incomplete todo items.</description></item>
+/// <item><description><c>TodoList_GetAll</c> — Retrieve all todo items (complete and incomplete).</description></item>
+/// </list>
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class TodoProvider : AIContextProvider
+{
+    private const string DefaultInstructions =
+        """
+        ## Todo Items
+
+        You have access to a todo list for tracking work items.
+        While planning, make sure that you break down complex tasks into manageable todo items and add them to the list.
+        Ask questions from the user where clarification is needed to create effective todos.
+        If the user provides feedback on your plan, adjust your todos accordingly by adding new items or removing irrelevant ones.
+        During execution, use the todo list to keep track of what needs to be done, mark items as complete when finished, and remove any items that are no longer needed.
+        When a user changes the topic or changes their mind, ensure that you update the todo list accordingly by removing irrelevant items or adding new ones as needed.
+        
+        Use these tools to manage your tasks:
+        - Use TodoList_Add to break down complex work into trackable items (supports adding one or many at once).
+        - Use TodoList_Complete to mark items as done when finished (supports one or many at once).
+        - Use TodoList_GetRemaining to check what work is still pending.
+        - Use TodoList_GetAll to review the full list including completed items.
+        - Use TodoList_Remove to remove items that are no longer needed (supports one or many at once).
+        """;
+
+    private readonly ProviderSessionState<TodoState> _sessionState;
+    private readonly string _instructions;
+    private IReadOnlyList<string>? _stateKeys;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="TodoProvider"/> class.
+    /// </summary>
+    /// <param name="options">Optional settings that control provider behavior. When <see langword="null"/>, defaults are used.</param>
+    public TodoProvider(TodoProviderOptions? options = null)
+    {
+        this._instructions = options?.Instructions ?? DefaultInstructions;
+        this._sessionState = new ProviderSessionState<TodoState>(
+            _ => new TodoState(),
+            this.GetType().Name,
+            AgentJsonUtilities.DefaultOptions);
+    }
+
+    /// <inheritdoc />
+    public override IReadOnlyList<string> StateKeys => this._stateKeys ??= [this._sessionState.StateKey];
+
+    /// <summary>
+    /// Gets all todo items from the session state.
+    /// </summary>
+    /// <param name="session">The agent session to read todos from.</param>
+    /// <returns>A read-only list of all todo items.</returns>
+    public IReadOnlyList<TodoItem> GetAllTodos(AgentSession? session)
+    {
+        return this._sessionState.GetOrInitializeState(session).Items;
+    }
+
+    /// <summary>
+    /// Gets the remaining (incomplete) todo items from the session state.
+    /// </summary>
+    /// <param name="session">The agent session to read todos from.</param>
+    /// <returns>A list of incomplete todo items.</returns>
+    public List<TodoItem> GetRemainingTodos(AgentSession? session)
+    {
+        return this._sessionState.GetOrInitializeState(session).Items.Where(t => !t.IsComplete).ToList();
+    }
+
+    /// <inheritdoc />
+    protected override ValueTask<AIContext> ProvideAIContextAsync(InvokingContext context, CancellationToken cancellationToken = default)
+    {
+        TodoState state = this._sessionState.GetOrInitializeState(context.Session);
+
+        return new ValueTask<AIContext>(new AIContext
+        {
+            Instructions = this._instructions,
+            Tools = this.CreateTools(state, context.Session),
+        });
+    }
+
+    // Note: These tool delegates mutate shared session state without synchronization.
+    // This is safe because FunctionInvokingChatClient serializes tool calls within a single run.
+    private AITool[] CreateTools(TodoState state, AgentSession? session)
+    {
+        var serializerOptions = AgentJsonUtilities.DefaultOptions;
+
+        return
+        [
+            AIFunctionFactory.Create(
+                (List<TodoItemInput> todos) =>
+                {
+                    var created = new List<TodoItem>();
+                    foreach (var input in todos)
+                    {
+                        var item = new TodoItem
+                        {
+                            Id = state.NextId++,
+                            Title = input.Title,
+                            Description = input.Description,
+                        };
+                        state.Items.Add(item);
+                        created.Add(item);
+                    }
+
+                    this._sessionState.SaveState(session, state);
+                    return created;
+                },
+                new AIFunctionFactoryOptions
+                {
+                    Name = "TodoList_Add",
+                    Description = "Add one or more todo items. Each item has a title and an optional description. Returns the list of created todo items.",
+                    SerializerOptions = serializerOptions,
+                }),
+
+            AIFunctionFactory.Create(
+                (List<int> ids) =>
+                {
+                    var idSet = new HashSet<int>(ids);
+                    int completed = 0;
+                    foreach (TodoItem item in state.Items)
+                    {
+                        if (!item.IsComplete && idSet.Contains(item.Id))
+                        {
+                            item.IsComplete = true;
+                            completed++;
+                        }
+                    }
+
+                    if (completed > 0)
+                    {
+                        this._sessionState.SaveState(session, state);
+                    }
+
+                    return completed;
+                },
+                new AIFunctionFactoryOptions
+                {
+                    Name = "TodoList_Complete",
+                    Description = "Mark one or more todo items as complete by their IDs. Returns the number of items that were found and marked complete.",
+                    SerializerOptions = serializerOptions,
+                }),
+
+            AIFunctionFactory.Create(
+                (List<int> ids) =>
+                {
+                    var idSet = new HashSet<int>(ids);
+                    int removed = state.Items.RemoveAll(t => idSet.Contains(t.Id));
+
+                    if (removed > 0)
+                    {
+                        this._sessionState.SaveState(session, state);
+                    }
+
+                    return removed;
+                },
+                new AIFunctionFactoryOptions
+                {
+                    Name = "TodoList_Remove",
+                    Description = "Remove one or more todo items by their IDs. Returns the number of items that were found and removed.",
+                    SerializerOptions = serializerOptions,
+                }),
+
+            AIFunctionFactory.Create(
+                () => state.Items.Where(t => !t.IsComplete).ToList(),
+                new AIFunctionFactoryOptions
+                {
+                    Name = "TodoList_GetRemaining",
+                    Description = "Retrieve the list of incomplete todo items.",
+                    SerializerOptions = serializerOptions,
+                }),
+
+            AIFunctionFactory.Create(
+                () => state.Items,
+                new AIFunctionFactoryOptions
+                {
+                    Name = "TodoList_GetAll",
+                    Description = "Retrieve the full list of todo items, both complete and incomplete.",
+                    SerializerOptions = serializerOptions,
+                }),
+        ];
+    }
+}
@@ -0,0 +1,22 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Options controlling the behavior of <see cref="TodoProvider"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class TodoProviderOptions
+{
+    /// <summary>
+    /// Gets or sets custom instructions provided to the agent for using the todo tools.
+    /// </summary>
+    /// <value>
+    /// When <see langword="null"/> (the default), the provider uses built-in instructions
+    /// that guide the agent on how to manage todos effectively.
+    /// </value>
+    public string? Instructions { get; set; }
+}
--- a/Show More
+++ b/Show More