fix for model_client

* Fix OpenAIResponsesAgentClient endpoint to include agentName in path (#5324)

The sample OpenAIResponsesAgentClient used '/v1/' as the endpoint, which
routes to the multi-agent endpoint requiring agent.name in the request body.
However, AsIChatClient(agentName) maps agentName to the model field, not
agent.name, causing HTTP 400 errors on OpenAI-compatible endpoints.

Changed the endpoint to '/{agentName}/v1/' to match the pattern used by
OpenAIChatCompletionsAgentClient, routing to the single-agent endpoint
where no agent.name body field is needed.

Added regression test verifying that the model field alone is insufficient
for agent resolution on the multi-agent endpoint.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Address review feedback for #5324

- URL-escape agentName in OpenAIResponsesAgentClient endpoint path to
  handle reserved characters safely
- Add per-agent MapOpenAIResponses() calls in AgentHost so the sample
  host serves the /{agentName}/v1/responses routes the client now targets
- Replace brittle Assert.Contains("agent.name") assertions with stable
  machine-readable error code assertion ("missing_required_parameter")

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Address additional review feedback for #5324

- Apply Uri.EscapeDataString to OpenAIChatCompletionsAgentClient endpoint
  for consistency with OpenAIResponsesAgentClient
- Map OpenAI Responses and ChatCompletions endpoints for all builder-based
  agents (chemist, mathematician, literator, science workflows) so every
  discoverable agent is reachable via the single-agent endpoint path

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <copilot@github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

.github/workflows/dotnet-build-and-test.yml

@@ -37,6 +37,7 @@ jobs:
     outputs:
       dotnetChanges: ${{ steps.filter.outputs.dotnet }}
       cosmosDbChanges: ${{ steps.filter.outputs.cosmosdb }}
+      foundryHostingChanges: ${{ steps.filter.outputs.foundryHosting }}
     steps:
       - uses: actions/checkout@v6
       - uses: dorny/paths-filter@v3
@@ -47,6 +48,22 @@ jobs:
               - 'dotnet/**'
             cosmosdb:
               - 'dotnet/src/Microsoft.Agents.AI.CosmosNoSql/**'
+            # The Foundry hosted-agent IT is costly (builds a container, pushes to ACR,
+            # provisions live agents). Only run it when the project under test, its
+            # dependency chain, the test container, the test fixture, or their tooling
+            # changed. Keep this list in sync with $hashedDirs in scripts/it-build-image.ps1.
+            foundryHosting:
+              - 'dotnet/src/Microsoft.Agents.AI.Foundry.Hosting/**'
+              - 'dotnet/src/Microsoft.Agents.AI.Foundry/**'
+              - 'dotnet/src/Microsoft.Agents.AI/**'
+              - 'dotnet/src/Microsoft.Agents.AI.Abstractions/**'
+              - 'dotnet/src/Microsoft.Agents.AI.Workflows/**'
+              - 'dotnet/tests/Foundry.Hosting.IntegrationTests/**'
+              - 'dotnet/tests/Foundry.Hosting.IntegrationTests.TestContainer/**'
+              - 'dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/**'
+              - 'dotnet/Directory.Packages.props'
+              - 'dotnet/tests/Foundry.Hosting.IntegrationTests/scripts/it-build-image.ps1'
+              - '.github/workflows/dotnet-build-and-test.yml'
       # run only if 'dotnet' files were changed
       - name: dotnet tests
         if: steps.filter.outputs.dotnet == 'true'
@@ -257,8 +274,11 @@ jobs:
             -c ${{ matrix.configuration }} `
             --no-build -v Normal `
             --report-xunit-trx `
+            --report-junit `
+            --results-directory ../IntegrationTestResults/ `
             --ignore-exit-code 8 `
             --filter-not-trait "Category=IntegrationDisabled" `
+            --filter-not-trait "Category=FoundryHostedAgents" `
             --parallel-algorithm aggressive `
             --max-threads 2.0x
         env:
@@ -277,6 +297,10 @@ jobs:
           AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
           AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZURE_AI_MODEL_DEPLOYMENT_NAME }}
           AZURE_AI_BING_CONNECTION_ID: ${{ vars.AZURE_AI_BING_CONNECTION_ID }}
+          # Anthropic Models
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          ANTHROPIC_CHAT_MODEL_NAME: ${{ vars.ANTHROPIC_CHAT_MODEL_NAME }}
+          ANTHROPIC_REASONING_MODEL_NAME: ${{ vars.ANTHROPIC_REASONING_MODEL_NAME }}
 
       # Generate test reports and check coverage
       - name: Generate test reports
@@ -299,11 +323,104 @@ jobs:
         shell: pwsh
         run: ./dotnet/eng/scripts/dotnet-check-coverage.ps1 -JsonReportPath "TestResults/Reports/Summary.json" -CoverageThreshold $env:COVERAGE_THRESHOLD
 
+      - name: Upload integration test results
+        if: always() && github.event_name != 'pull_request' && matrix.integration-tests
+        uses: actions/upload-artifact@v7
+        with:
+          name: dotnet-test-results-${{ matrix.targetFramework }}-${{ matrix.os }}
+          path: IntegrationTestResults/**/*.junit
+          if-no-files-found: ignore
+
+  # The Foundry hosted-agent IT is costly (it builds a container, pushes to ACR, and provisions
+  # live agents on a separate Foundry project). Running it in its own job keeps the overall
+  # workflow time roughly flat: it executes in parallel to dotnet-build and dotnet-test and is
+  # gated on paths-filter.outputs.foundryHostingChanges so unrelated edits skip the work.
+  dotnet-foundry-hosted-it:
+    needs: paths-filter
+    if: github.event_name != 'pull_request' && needs.paths-filter.outputs.foundryHostingChanges == 'true'
+    runs-on: ubuntu-latest
+    environment: integration
+    env:
+      configuration: Release
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+          sparse-checkout: |
+            .
+            .github
+            dotnet
+            python
+
+      - name: Setup dotnet
+        uses: actions/setup-dotnet@v5.2.0
+        with:
+          global-json-file: ${{ github.workspace }}/dotnet/global.json
+
+      # Build the test csproj directly instead of a filtered slnx + -f override.
+      # The test project pins TargetFrameworks=net10.0 and its ProjectReference closure
+      # gives MSBuild a single-rooted graph, so each multi-targeted dependency is invoked
+      # exactly once for net10.0. This avoids the MSB3026/MSB3491/MSB4018/MSB3883 file-lock
+      # collisions caused by parallel inner-builds racing on shared bin/obj output paths
+      # under the previous slnx + global TFM override approach.
+      - name: Build Foundry hosted IT (and its deps)
+        shell: bash
+        run: dotnet build dotnet/tests/Foundry.Hosting.IntegrationTests/Foundry.Hosting.IntegrationTests.csproj -c "$configuration" --warnaserror
+
+      - name: Azure CLI Login
+        uses: azure/login@v2
+        with:
+          client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+
+      # We rebuild and push the test container image on every IT run so framework code changes
+      # are picked up; the image tag is content-hashed across the test container source AND its
+      # framework project references, so identical content is a no-op push.
+      #
+      # The script always passes --no-dependencies to dotnet publish so publish never re-touches
+      # the framework lib DLLs the prior "Build Foundry hosted IT (and its deps)" step produced.
+      # This structurally eliminates the MSB3026 collision that VBCSCompiler from the prebuild
+      # would otherwise cause by holding file handles to those DLLs. Do not remove the prebuild
+      # step: the subsequent `dotnet test --no-build` step and the publish's ProjectReference
+      # resolution both depend on the prebuilt outputs being present.
+      - name: Build and push Foundry Hosted Agents test container
+        id: build-foundry-hosted-image
+        shell: pwsh
+        working-directory: ${{ github.workspace }}
+        run: |
+          $registry = "${{ vars.IT_HOSTED_AGENT_REGISTRY }}"
+          if ([string]::IsNullOrWhiteSpace($registry)) {
+            throw "IT_HOSTED_AGENT_REGISTRY not set in the integration environment."
+          }
+          & "${{ github.workspace }}/dotnet/tests/Foundry.Hosting.IntegrationTests/scripts/it-build-image.ps1" -Registry $registry | Tee-Object -FilePath $env:GITHUB_ENV -Append
+
+      - name: Run Foundry Hosted Agents Integration Tests
+        shell: pwsh
+        working-directory: dotnet
+        run: |
+          dotnet test --project tests/Foundry.Hosting.IntegrationTests/Foundry.Hosting.IntegrationTests.csproj `
+            -c $env:configuration `
+            --no-build -v Normal `
+            --report-xunit-trx `
+            --ignore-exit-code 8 `
+            --filter-trait "Category=FoundryHostedAgents"
+        env:
+          AZURE_AI_PROJECT_ENDPOINT: ${{ vars.IT_HOSTED_AGENT_PROJECT_ENDPOINT }}
+          AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.IT_HOSTED_AGENT_MODEL_DEPLOYMENT_NAME }}
+          # Azure AI Search (for the azure-search-rag scenario). Reuses the integration
+          # environment secrets shared with python-sample-validation.yml. The index is
+          # provisioned out of band; see dotnet/tests/Foundry.Hosting.IntegrationTests/README.md
+          # for the required schema and seed content.
+          AZURE_SEARCH_ENDPOINT: ${{ secrets.AZURE_SEARCH_ENDPOINT }}
+          AZURE_SEARCH_INDEX_NAME: ${{ secrets.AZURE_SEARCH_INDEX_NAME }}
+          # IT_HOSTED_AGENT_IMAGE was exported into $GITHUB_ENV by the previous step.
+
   # This final job is required to satisfy the merge queue. It must only run (or succeed) if no tests failed
   dotnet-build-and-test-check:
     if: always()
     runs-on: ubuntu-latest
-    needs: [dotnet-build, dotnet-test]
+    needs: [dotnet-build, dotnet-test, dotnet-foundry-hosted-it]
     steps:
       - name: Get Date
         shell: bash
@@ -341,3 +458,64 @@ jobs:
         uses: actions/github-script@v8
         with:
           script: core.setFailed('Integration Tests Cancelled!')
+
+  # Integration test trend report (aggregates JUnit XML results from dotnet test jobs)
+  dotnet-integration-test-report:
+    name: Integration Test Report
+    if: >
+      always() &&
+      github.event_name != 'pull_request' &&
+      (contains(join(needs.*.result, ','), 'success') ||
+       contains(join(needs.*.result, ','), 'failure'))
+    needs: [dotnet-test]
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+          sparse-checkout: |
+            .github/actions/python-setup
+            python
+      - name: Set up python and install the project
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: "3.13"
+          os: ${{ runner.os }}
+      - name: Download all test results from current run
+        uses: actions/download-artifact@v4
+        with:
+          pattern: dotnet-test-results-*
+          path: dotnet-test-results/
+      - name: Restore report history cache
+        uses: actions/cache/restore@v4
+        with:
+          path: python/dotnet-integration-report-history.json
+          key: dotnet-integration-report-history-${{ github.run_id }}
+          restore-keys: |
+            dotnet-integration-report-history-
+      - name: Generate trend report
+        run: >
+          uv run python scripts/integration_test_report/aggregate.py
+          ../dotnet-test-results/
+          dotnet-integration-report-history.json
+          dotnet-integration-test-report.md
+      - name: Post to Job Summary
+        if: always()
+        run: cat dotnet-integration-test-report.md >> $GITHUB_STEP_SUMMARY
+      - name: Save report history cache
+        if: always()
+        uses: actions/cache/save@v4
+        with:
+          path: python/dotnet-integration-report-history.json
+          key: dotnet-integration-report-history-${{ github.run_id }}
+      - name: Upload trend report
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: dotnet-integration-test-report
+          path: |
+            python/dotnet-integration-test-report.md
+            python/dotnet-integration-report-history.json

.github/workflows/issue-triage.yml

@@ -1,12 +1,8 @@
 name: Issue Triage
 
 on:
-  workflow_dispatch:
-    inputs:
-      issue_number:
-        description: Issue number to triage
-        required: true
-        type: string
+  issues:
+    types: [opened, labeled]
 
 permissions:
   contents: read
@@ -14,7 +10,13 @@ permissions:
   id-token: write
 
 concurrency:
-  group: issue-triage-${{ github.repository }}-${{ github.event.issue.number || inputs.issue_number || github.run_id }}
+  group: >-
+    issue-triage-${{ github.repository }}-${{
+      ((github.event.action == 'opened' && contains(github.event.issue.labels.*.name, 'bug'))
+       || (github.event.action == 'labeled' && github.event.label.name == 'bug'))
+      && github.event.issue.number
+      || github.run_id
+    }}
   cancel-in-progress: true
 
 env:
@@ -26,6 +28,7 @@ env:
 jobs:
   team_check:
     runs-on: ubuntu-latest
+    if: ${{ (github.event.action == 'opened' && contains(github.event.issue.labels.*.name, 'bug')) || (github.event.action == 'labeled' && github.event.label.name == 'bug') }}
     outputs:
       is_team_member: ${{ steps.check.outputs.is_team_member }}
       issue_number: ${{ steps.issue.outputs.issue_number }}
@@ -36,18 +39,13 @@ jobs:
         shell: bash
         env:
           ISSUE_NUMBER_EVENT: ${{ github.event.issue.number }}
-          ISSUE_NUMBER_INPUT: ${{ inputs.issue_number }}
         run: |
           set -euo pipefail
 
-          if [[ "${GITHUB_EVENT_NAME}" == "issues" ]]; then
-            issue_number="${ISSUE_NUMBER_EVENT}"
-          else
-            issue_number="${ISSUE_NUMBER_INPUT}"
-          fi
+          issue_number="${ISSUE_NUMBER_EVENT}"
 
           if [[ ! "$issue_number" =~ ^[1-9][0-9]*$ ]]; then
-            echo "Could not determine issue number; for workflow_dispatch runs, the 'issue_number' input is required." >&2
+            echo "Could not determine issue number from event payload." >&2
             exit 1
           fi
 
@@ -166,6 +164,9 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           GH_COPILOT_TOKEN: ${{ secrets.GH_COPILOT_TOKEN }}
+          # Not seen by the agent prompt; used only to push a paper-trail
+          # branch back to maf-dashboard at run end.
+          DEVFLOW_TOKEN: ${{ secrets.DEVFLOW_TOKEN }}
           SK_REPO_PATH: ${{ env.TARGET_REPO_PATH }}
           AGENT_REPO_PATH: ${{ env.TARGET_REPO_PATH }}
           ISSUE_REPO: ${{ needs.team_check.outputs.repo }}

.github/workflows/python-integration-tests.yml

@@ -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
@@ -435,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') ||
@@ -471,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()

.github/workflows/python-merge-tests.yml

@@ -278,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
@@ -289,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
@@ -403,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
@@ -619,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') ||
@@ -652,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()

README.md

@@ -6,8 +6,12 @@
 [![MS Learn Documentation](https://img.shields.io/badge/MS%20Learn-Documentation-blue)](https://learn.microsoft.com/en-us/agent-framework/)
 [![PyPI](https://img.shields.io/pypi/v/agent-framework)](https://pypi.org/project/agent-framework/)
 [![NuGet](https://img.shields.io/nuget/v/Microsoft.Agents.AI)](https://www.nuget.org/profiles/MicrosoftAgentFramework/)
+[![GitHub stars](https://img.shields.io/github/stars/microsoft/agent-framework?style=social)](https://github.com/microsoft/agent-framework/stargazers)
 
-Welcome to Microsoft's comprehensive multi-language framework for building, orchestrating, and deploying AI agents with support for both .NET and Python implementations. This framework provides everything from simple chat agents to complex multi-agent workflows with graph-based orchestration.
+
+Microsoft Agent Framework (MAF) is an open, multi-language framework for building **production-grade AI agents and multi-agent workflows** in **.NET and Python**.
+
+Microsoft Agent Framework is built for teams taking agents from prototype to production. It provides a consistent foundation for building, orchestrating, and operating agent systems across Python and .NET, while keeping architecture choices open as requirements evolve, and supports a broad ecosystem including Microsoft Foundry, Azure OpenAI, OpenAI, and the GitHub Copilot SDK, with samples and hosting patterns for both local development and cloud deployment.
 
 <p align="center">
   <a href="https://www.youtube.com/watch?v=AAgdMhftj8w" title="Watch the full Agent Framework introduction (30 min)">
@@ -21,10 +25,54 @@ Welcome to Microsoft's comprehensive multi-language framework for building, orch
   </a>
 </p>
 
-## 📋 Getting Started
+## Is this the right framework for you?
 
-### 📦 Installation
+MAF is a strong fit if you:
+- are building agents and workflows you expect to run in production,
+- need orchestration beyond a single prompt or stateless chat loop,
+- want graph-based patterns such as sequential, concurrent, handoff, and group collaboration,
+- care about durability, restartability, observability, governance, or human-in-the-loop control,
+- need provider flexibility so your architecture can evolve without major rewrites.
 
+## Key Features
+Explore new MAF capabilities and real implementation patterns on the [official blog](https://devblogs.microsoft.com/agent-framework/).
+
+- **Python and C#/.NET Support**: Full framework support for both Python and C#/.NET implementations with consistent APIs
+  - [Python packages](./python/packages/) | [.NET source](./dotnet/src/)
+- **Multiple Agent Provider Support**: Support for various LLM providers with more being added continuously
+  - [Python examples](./python/samples/02-agents/providers/) | [.NET examples](./dotnet/samples/02-agents/AgentProviders/)
+- **Middleware**: Flexible middleware system for request/response processing, exception handling, and custom pipelines
+  - [Python middleware](./python/samples/02-agents/middleware/) | [.NET middleware](./dotnet/samples/02-agents/Agents/Agent_Step11_Middleware/)
+- **Orchestration Patterns & Workflows**: Build multi-agent systems with graph-based workflows supporting sequential, concurrent, handoff, and group collaboration patterns; includes checkpointing, streaming, human-in-the-loop, and time-travel
+  - [Python workflows](./python/samples/03-workflows/) | [.NET workflows](./dotnet/samples/03-workflows/)
+- **Foundry Hosted Agents (new)**: Deploy and host your agents to Foundry-hosted infrastructure with just 2 additional lines of code
+  - [Python samples](./python/samples/04-hosting/foundry-hosted-agents/) | [.NET samples](./dotnet/samples/04-hosting/FoundryHostedAgents/)
+- **Observability**: Built-in OpenTelemetry integration for distributed tracing, monitoring, and debugging
+  - [Python observability](./python/samples/02-agents/observability/) | [.NET telemetry](./dotnet/samples/02-agents/AgentOpenTelemetry/)
+- **Declarative Agents**: Define agents using YAML for faster setup and versioning
+  - [Declarative agent samples](./declarative-agents/)
+- **Agent Skills**: Build domain-specific knowledge bases from multiple sources—files, inline code, class libraries—for agents to discover and use
+  - [Skills design](./docs/decisions/0021-agent-skills-design.md)
+- **AF Labs**: Experimental packages for cutting-edge features including benchmarking, reinforcement learning, and research initiatives
+  - [Labs directory](./python/packages/lab/)
+- **DevUI**: Interactive developer UI for agent development, testing, and debugging workflows
+  - [See the DevUI in action](https://www.youtube.com/watch?v=mOAaGY4WPvc)
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+  - [Installation](#installation)
+  - [Learning Resources](#learning-resources)
+  - [Quickstart](#quickstart)
+    - [Basic Agent - Python](#basic-agent---python)
+    - [Basic Agent - .NET](#basic-agent---net)
+- [More Examples & Samples](#more-examples--samples)
+- [Community & Feedback](#community--feedback)
+- [Troubleshooting](#troubleshooting)
+- [Contributor Resources](#contributor-resources)
+
+## Getting Started
+### Installation
 Python
 
 ```bash
@@ -37,9 +85,13 @@ pip install agent-framework
 
 ```bash
 dotnet add package Microsoft.Agents.AI
+# For Foundry integration (used in the .NET quickstart below):
+dotnet add package Microsoft.Agents.AI.Foundry
+dotnet add package Azure.AI.Projects
+dotnet add package Azure.Identity
 ```
 
-### 📚 Documentation
+### Learning Resources
 
 - **[Overview](https://learn.microsoft.com/agent-framework/overview/agent-framework-overview)** - High level overview of the framework
 - **[Quick Start](https://learn.microsoft.com/agent-framework/tutorials/quick-start)** - Get started with a simple agent
@@ -48,44 +100,9 @@ dotnet add package Microsoft.Agents.AI
 - **[Migration from Semantic Kernel](https://learn.microsoft.com/en-us/agent-framework/migration-guide/from-semantic-kernel)** - Guide to migrate from Semantic Kernel
 - **[Migration from AutoGen](https://learn.microsoft.com/en-us/agent-framework/migration-guide/from-autogen)** - Guide to migrate from AutoGen
 
-Still have questions? Join our [weekly office hours](./COMMUNITY.md#public-community-office-hours) or ask questions in our [Discord channel](https://discord.gg/b5zjErwbQM) to get help from the team and other users.
+### Quickstart
 
-### ✨ **Highlights**
-
-- **Graph-based Workflows**: Connect agents and deterministic functions using data flows with streaming, checkpointing, human-in-the-loop, and time-travel capabilities
-  - [Python workflows](./python/samples/03-workflows/) | [.NET workflows](./dotnet/samples/03-workflows/)
-- **AF Labs**: Experimental packages for cutting-edge features including benchmarking, reinforcement learning, and research initiatives
-  - [Labs directory](./python/packages/lab/)
-- **DevUI**: Interactive developer UI for agent development, testing, and debugging workflows
-  - [DevUI package](./python/packages/devui/)
-
-<p align="center">
-  <a href="https://www.youtube.com/watch?v=mOAaGY4WPvc">
-    <img src="https://img.youtube.com/vi/mOAaGY4WPvc/hqdefault.jpg" alt="See the DevUI in action" width="480">
-  </a>
-</p>
-<p align="center">
-  <a href="https://www.youtube.com/watch?v=mOAaGY4WPvc">
-    See the DevUI in action (1 min)
-  </a>
-</p>
-
-- **Python and C#/.NET Support**: Full framework support for both Python and C#/.NET implementations with consistent APIs
-  - [Python packages](./python/packages/) | [.NET source](./dotnet/src/)
-- **Observability**: Built-in OpenTelemetry integration for distributed tracing, monitoring, and debugging
-  - [Python observability](./python/samples/02-agents/observability/) | [.NET telemetry](./dotnet/samples/02-agents/AgentOpenTelemetry/)
-- **Multiple Agent Provider Support**: Support for various LLM providers with more being added continuously
-  - [Python examples](./python/samples/02-agents/providers/) | [.NET examples](./dotnet/samples/02-agents/AgentProviders/)
-- **Middleware**: Flexible middleware system for request/response processing, exception handling, and custom pipelines
-  - [Python middleware](./python/samples/02-agents/middleware/) | [.NET middleware](./dotnet/samples/02-agents/Agents/Agent_Step11_Middleware/)
-
-### 💬 **We want your feedback!**
-
-- For bugs, please file a [GitHub issue](https://github.com/microsoft/agent-framework/issues).
-
-## Quickstart
-
-### Basic Agent - Python
+#### Basic Agent - Python
 
 Create a simple Azure Responses Agent that writes a haiku about the Microsoft Agent Framework
 
@@ -109,7 +126,7 @@ async def main():
           # project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
           # model=os.environ["FOUNDRY_MODEL_DEPLOYMENT_NAME"],
       ),
-      name="HaikuBot",
+      name="HaikuAgent",
       instructions="You are an upbeat assistant that writes beautifully.",
     )
 
@@ -119,40 +136,24 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-### Basic Agent - .NET
-Create a simple Agent, using Microsoft Foundry with token-based auth, that writes a haiku about the Microsoft Agent Framework
+#### Basic Agent - .NET
+Create a simple Agent, using Microsoft Foundry that writes a haiku about the Microsoft Agent Framework
 
 ```c#
-// dotnet add package Microsoft.Agents.AI.Foundry
-// Use `az login` to authenticate with Azure CLI
-using Azure.AI.Projects;
-using Azure.Identity;
-using System;
+// This sample shows how to create and run a basic agent with AIProjectClient.AsAIAgent(...).
+
 using Azure.AI.Projects;
 using Azure.Identity;
+using Microsoft.Agents.AI;
 
-var endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+string endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
 
-var agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
-    .AsAIAgent(model: deploymentName, name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
-
-Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
-```
-
-Create a simple Agent, using OpenAI Responses, that writes a haiku about the Microsoft Agent Framework
-
-```c#
-// dotnet add package Microsoft.Agents.AI.OpenAI
-using System;
-using OpenAI;
-using OpenAI.Responses;
-
-// Replace the <apikey> with your OpenAI API key.
-var agent = new OpenAIClient("<apikey>")
-    .GetResponsesClient()
-    .AsAIAgent(model: "gpt-5.4-mini", name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
+AIAgent agent =
+    new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
+    .AsAIAgent(model: deploymentName, instructions: "You are an upbeat assistant that writes beautifully.", name: "HaikuAgent");
 
+// Once you have the agent, you can invoke it like any other AIAgent.
 Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
 ```
 
@@ -175,6 +176,12 @@ Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Fram
 - [Hosting](./dotnet/samples/04-hosting): A2A, Durable Agents, Durable Workflows
 - [End-to-End](./dotnet/samples/05-end-to-end): full applications and demos
 
+## Community & Feedback
+
+- **Found a bug?** File a [GitHub issue](https://github.com/microsoft/agent-framework/issues) to help us improve.
+- **Enjoying MAF?** [![GitHub stars](https://img.shields.io/badge/Star-us%20on%20GitHub-yellow)](https://github.com/microsoft/agent-framework) to show your support and help others discover the project.
+- **Have questions?** Join our [Discord](https://discord.gg/b5zjErwbQM) or visit [weekly office hours](./COMMUNITY.md#public-community-office-hours).
+
 ## Troubleshooting
 
 ### Authentication
@@ -187,16 +194,7 @@ Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Fram
 > **Tip:** `DefaultAzureCredential` is convenient for development but in production, consider using a specific credential (e.g., `ManagedIdentityCredential`) to avoid latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 
 ### Environment Variables
-
-The samples typically read configuration from environment variables. Common required variables:
-
-| Variable | Used by | Purpose |
-|----------|---------|---------|
-| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI samples | Your Azure OpenAI resource URL |
-| `AZURE_OPENAI_DEPLOYMENT_NAME` | Azure OpenAI samples | Model deployment name (e.g. `gpt-4o-mini`) |
-| `AZURE_AI_PROJECT_ENDPOINT` | Microsoft Foundry samples | Your Microsoft Foundry project endpoint |
-| `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Microsoft Foundry samples | Model deployment name |
-| `OPENAI_API_KEY` | OpenAI (non-Azure) samples | Your OpenAI platform API key |
+For environment variable configuration specific to each sample, refer to the README in the sample directory ([Python samples](./python/samples/) | [.NET samples](./dotnet/samples/)).
 
 ## Contributor Resources
 

docs/decisions/0024-prompt-injection-defense.md

@@ -0,0 +1,142 @@
+---
+status: proposed
+contact: shruti
+date: 2026-01-14
+deciders: {}
+consulted: {}
+informed: {}
+---
+
+# FIDES - Deterministic Prompt Injection Defense [Costa et al., 2025]
+
+## Context and Problem Statement
+
+AI agents are vulnerable to prompt injection attacks where malicious instructions embedded in external content (e.g., API responses, user input) can manipulate agent behavior. Traditional defenses rely on heuristics and prompt engineering, which are not deterministic and can be bypassed.
+
+We need a systematic, deterministic defense mechanism that prevents untrusted content from influencing agent behavior, provides verifiable security guarantees, maintains audit trails for compliance, and integrates seamlessly with the existing agent framework.
+
+## Decision Drivers
+
+- Agents must not execute actions influenced by untrusted external content (prompt injection defense).
+- The solution must provide deterministic, verifiable security guarantees — not heuristic-based.
+- The solution must maintain audit trails for compliance and security reviews.
+- The solution must integrate non-invasively with the existing middleware pipeline.
+- The solution must be opt-in and backwards compatible with existing agents.
+- Developer experience must remain simple with a clear security model.
+
+## Considered Options
+
+- Information-flow control with label-based middleware (FIDES)
+- Prompt engineering defense
+- Content sanitization
+- Separate agent instances
+- Runtime monitoring only
+
+## Decision Outcome
+
+Chosen option: "Information-flow control with label-based middleware (FIDES)", because it is the only option that provides deterministic, formally verifiable security guarantees while integrating non-invasively with the existing middleware pipeline and remaining fully backwards compatible.
+
+FIDES (Flow Integrity Deterministic Enforcement System) is a label-based security system with four core components:
+
+1. **Content Labeling System** — `IntegrityLabel` (TRUSTED/UNTRUSTED) and `ConfidentialityLabel` (PUBLIC/PRIVATE/USER_IDENTITY) with most-restrictive-wins combination policy.
+2. **Middleware-Based Enforcement** — `LabelTrackingFunctionMiddleware` for automatic label propagation and `PolicyEnforcementFunctionMiddleware` for pre-execution policy checks.
+3. **Variable Indirection** — `ContentVariableStore` and `VariableReferenceContent` for physical isolation of untrusted content from the LLM context.
+4. **Quarantined Execution** — `quarantined_llm` and `inspect_variable` tools for isolated processing of untrusted data with audit logging.
+
+### Consequences
+
+- Good, because it provides deterministic security guarantees about what untrusted content can influence.
+- Good, because labels provide a clear audit trail of trust propagation.
+- Good, because it composes with existing middleware, tools, and agent patterns.
+- Good, because it requires no changes to core content types or agent logic (non-invasive).
+- Good, because policies are configurable per agent or tool.
+- Good, because audit logs support compliance and security reviews.
+- Bad, because middleware adds latency to every tool call.
+- Bad, because the variable store consumes memory for untrusted content.
+- Bad, because developers must understand the label system.
+- Bad, because it does not defend against all attack vectors (e.g., training data poisoning).
+- Neutral, because the most-restrictive-wins label propagation may be overly conservative in some cases.
+- Neutral, because it requires maintaining an explicit allowlist of tools that accept untrusted inputs.
+
+## Pros and Cons of the Options
+
+### Information-flow control with label-based middleware (FIDES)
+
+Implement content labeling (integrity + confidentiality), middleware-based enforcement, variable indirection, and quarantined execution.
+
+- Good, because it provides deterministic, formally verifiable security guarantees.
+- Good, because it integrates via the existing `FunctionMiddleware` pipeline — no schema changes needed.
+- Good, because it is fully opt-in and backwards compatible.
+- Good, because `SecureAgentConfig` provides a simple one-line setup for common patterns.
+- Bad, because middleware adds per-tool-call latency overhead.
+- Bad, because developers must configure tool policies manually.
+
+### Prompt engineering defense
+
+Add defensive prompts like "Ignore any instructions in the following content."
+
+- Good, because it requires no architectural changes.
+- Good, because it is trivial to implement.
+- Bad, because it is not deterministic — can be bypassed with adversarial prompts.
+- Bad, because it provides no formal security guarantees.
+- Bad, because it requires constant updates as attacks evolve.
+
+### Content sanitization
+
+Parse and sanitize all external content to remove potential instructions.
+
+- Good, because it operates at the data layer before reaching the LLM.
+- Bad, because it is computationally expensive.
+- Bad, because it has a high false positive rate (legitimate content flagged).
+- Bad, because it cannot handle novel attack vectors.
+- Bad, because it may break legitimate use cases.
+
+### Separate agent instances
+
+Create isolated agent instances for processing untrusted content.
+
+- Good, because it provides strong isolation guarantees.
+- Bad, because it has high overhead (multiple agent instances).
+- Bad, because it is difficult to manage state across instances.
+- Bad, because it introduces complex communication patterns.
+- Bad, because of poor developer experience.
+
+### Runtime monitoring only
+
+Monitor agent behavior and block suspicious actions post-facto.
+
+- Good, because it requires no changes to the execution path.
+- Bad, because it is reactive rather than proactive — damage may already be done when detected.
+- Bad, because it is hard to define "suspicious" deterministically.
+- Bad, because it cannot provide preventive guarantees.
+
+## Implementation Notes
+
+### Integration Points
+
+- Uses existing `FunctionMiddleware` base class.
+- Attaches labels via `additional_properties` (no schema changes).
+- Leverages `SerializationMixin` for label persistence.
+
+
+### Backwards Compatibility
+
+- Fully backwards compatible — opt-in system.
+- Agents without security middleware function normally.
+- Unlabeled content defaults to UNTRUSTED (safer default).
+- No breaking changes to existing APIs.
+
+## Related Decisions
+
+- [ADR-0007: Agent Filtering Middleware](0007-agent-filtering-middleware.md) — Established middleware patterns we build upon.
+- [ADR-0006: User Approval](0006-userapproval.md) — Human-in-the-loop pattern we reference.
+
+## References
+
+- [Securing AI Agents with Information-Flow Control (Costa et al., 2025)](https://arxiv.org/abs/2505.23643)
+- [Prompt Injection Attack Examples](https://simonwillison.net/2023/Apr/14/worst-that-can-happen/)
+- [Information Flow Control](https://en.wikipedia.org/wiki/Information_flow_(information_theory))
+- [Taint Analysis](https://en.wikipedia.org/wiki/Taint_checking)
+- [Defense in Depth](https://en.wikipedia.org/wiki/Defense_in_depth_(computing))
+- [ ] Performance Benchmarks
+- [ ] User Acceptance Testing

docs/features/FIDES_IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,352 @@
+# FIDES Implementation Summary
+
+## Overview
+
+**FIDES**  is a comprehensive deterministic prompt injection defense system for the agent framework. The implementation provides label-based security mechanisms to defend against prompt injection attacks by tracking integrity and confidentiality of content throughout agent execution.
+
+**🚀 Key Features:**
+- **Context Provider Pattern** - `SecureAgentConfig` extends `ContextProvider`, injecting tools, instructions, and middleware automatically
+- **Automatic Variable Hiding** - UNTRUSTED content is automatically hidden without requiring manual intervention
+- **Per-Item Embedded Labels** - Tools return `list[Content]` with `Content.from_text()` for proper label propagation
+- **SecureAgentConfig** - One-line secure agent configuration via `context_providers=[config]`
+- **Data Exfiltration Prevention** - `max_allowed_confidentiality` prevents sensitive data leakage
+- **Message-Level Label Tracking** (Phase 1) - Track labels on every message in the conversation
+
+## Architecture Components
+
+The FIDES defense system consists of seven main components:
+
+1. **Content Labeling Infrastructure** - Labels for tracking integrity and confidentiality
+2. **Label Tracking Middleware** - Automatically assigns, propagates labels, and hides untrusted content
+3. **Per-Item Embedded Labels** - Tools can return mixed-trust data with per-item security labels
+4. **Policy Enforcement Middleware** - Blocks tool calls that violate security policies
+5. **Security Tools** - Specialized tools for safe handling of untrusted content (`quarantined_llm`, `inspect_variable`)
+6. **SecureAgentConfig** - Context provider for easy secure agent configuration
+7. **Message-Level Label Tracking** - Track labels on every message in the conversation (Phase 1)
+
+## Implementation Details
+
+### Files Created
+
+1. **`python/packages/core/agent_framework/security.py`** (~2950 lines — all security primitives, middleware, tools, and configuration in a single public module)
+   - `IntegrityLabel` enum (TRUSTED/UNTRUSTED)
+   - `ConfidentialityLabel` enum (PUBLIC/PRIVATE/USER_IDENTITY)
+   - `ContentLabel` class with serialization support
+   - `combine_labels()` function for label composition
+   - `ContentVariableStore` for client-side content storage
+   - `VariableReferenceContent` for variable indirection
+   - `LabeledMessage` class (inherits from `Message`) for message-level tracking
+   - `check_confidentiality_allowed()` helper for data exfiltration prevention
+   - `LabelTrackingFunctionMiddleware` - Tracks and propagates security labels
+   - `PolicyEnforcementFunctionMiddleware` - Enforces security policies
+   - `SecureAgentConfig` extends `ContextProvider` - automatic secure agent configuration
+   - `quarantined_llm()` - Isolated LLM calls with labeled data
+   - `inspect_variable()` - Controlled variable content inspection
+   - `store_untrusted_content()` - Helper for manual variable indirection (legacy)
+   - `get_security_tools()` - Returns list of security tools
+   - `SECURITY_TOOL_INSTRUCTIONS` - Detailed guidance for agents
+
+
+2. **`FIDES_DEVELOPER_GUIDE.md`** (~1250 lines)
+   - Located at `python/samples/02-agents/security/FIDES_DEVELOPER_GUIDE.md`
+   - Complete documentation of the FIDES security system
+   - Architecture overview and design rationale
+   - Usage examples (6+ comprehensive scenarios)
+   - Best practices and configuration options
+   - API reference with full parameter documentation
+   - Data exfiltration prevention documentation
+
+3. **`python/packages/core/tests/test_security.py`** (~800+ lines)
+   - Unit tests for ContentLabel and label operations
+   - Tests for ContentVariableStore functionality
+   - Tests for VariableReferenceContent
+   - Middleware behavior tests (label tracking and policy enforcement)
+   - Automatic hiding tests
+   - Per-item embedded label tests
+   - Context label tracking tests
+   - Message-level tracking tests (Phase 1)
+   - Data exfiltration prevention tests
+
+4. **`docs/decisions/0024-prompt-injection-defense.md`**
+   - Architecture Decision Record (ADR)
+   - Design rationale and alternatives considered
+   - Security properties and guarantees
+
+5. **`python/samples/02-agents/security/README.md`**
+   - Sample-focused entry point for the two runnable FIDES security samples
+   - Prerequisites, run commands, and links to the developer guide for deeper details
+
+### Files Modified
+
+1. **`python/packages/core/agent_framework/__init__.py`**
+   - Removed root-level security exports so `agent_framework.security` is the canonical import surface
+
+## Core Features
+
+### 1. Content Labeling Infrastructure
+
+- **IntegrityLabel**: TRUSTED (user input) vs UNTRUSTED (AI-generated, external)
+- **ConfidentialityLabel**: PUBLIC, PRIVATE, USER_IDENTITY
+- **Label Combination**: Most restrictive policy (UNTRUSTED + metadata merging)
+- **Serialization**: Full support for `to_dict()` and `from_dict()`
+
+### 2. Per-Item Embedded Labels
+
+Tools returning mixed-trust data embed labels on individual items using `Content.from_text()`:
+
+```python
+import json
+from agent_framework import Content, tool
+
+@tool(description="Fetch emails from inbox")
+async def fetch_emails(count: int = 5) -> list[Content]:
+    return [
+        Content.from_text(
+            json.dumps({
+                "id": email["id"],
+                "body": email["body"],
+            }),
+            additional_properties={
+                "security_label": {
+                    "integrity": "trusted" if email["internal"] else "untrusted",
+                    "confidentiality": "private",
+                }
+            ),
+        )
+        for email in emails
+    ]
+```
+
+These embedded labels are automatically consumed by `LabelTrackingFunctionMiddleware`, which:
+- Extracts the `security_label` from `additional_properties`
+- Uses the embedded label as the highest-priority source for that item
+- Automatically hides UNTRUSTED items in the variable store
+- Replaces hidden items with `VariableReferenceContent` in the LLM context
+- Preserves TRUSTED items visible to the LLM without tainting the context label
+
+This enables tools to return mixed-trust data where some items (internal emails) remain visible while untrusted items (external emails) are automatically hidden without manual intervention.
+           },
+        )
+        for email in emails
+    ]
+```
+
+### 3. Automatic Variable Hiding
+
+This feature automatically hides any UNTRUSTED content returned by tools while keeping the hiding logic transparent to the developer. Developers do not need to manually call `store_untrusted_content()`. This allows the LLM /agent's context to remain clean and secure. Key aspects include:
+
+- **Automatic Detection**: Middleware checks integrity label after each tool call
+- **Automatic Storage**: UNTRUSTED results/items stored in variable store
+- **Transparent Replacement**: LLM context receives `VariableReferenceContent`
+- **Context Label Protection**: Hidden content does NOT taint context label
+
+### 4. Context Label Tracking
+
+- Context label starts as TRUSTED + PUBLIC
+- Gets updated (tainted) when non-hidden untrusted content enters context
+- Policy enforcement uses context label for validation
+- Provides `get_context_label()` and `reset_context_label()` methods
+
+### 5. Data Exfiltration Prevention
+
+Tools declare `max_allowed_confidentiality` to prevent sensitive data leakage:
+
+```python
+@tool(
+    description="Post to public Slack channel",
+    additional_properties={
+        "max_allowed_confidentiality": "public",  # Blocks PRIVATE data
+    }
+)
+async def post_to_slack(channel: str, message: str) -> dict:
+    return {"status": "posted"}
+```
+
+### 6. SecureAgentConfig (Context Provider)
+
+SecureAgentConfig extends `ContextProvider` for automatic secure agent configuration:
+
+```python
+config = SecureAgentConfig(
+    auto_hide_untrusted=True,
+    allow_untrusted_tools={"search_web", "fetch_data"},
+    block_on_violation=True,
+    quarantine_chat_client=quarantine_client,  # Optional: real LLM for quarantine
+)
+
+# Context provider injects tools, instructions, and middleware automatically
+agent = Agent(
+    client=client,
+    name="secure_assistant",
+    instructions="You are a helpful assistant.",
+    tools=[my_tool],
+    context_providers=[config],  # That's it!
+)
+```
+
+## Security Properties
+
+### Deterministic Defense
+
+1. **Tiered label propagation**: Every tool result receives a label via 3-tier priority (embedded > source_integrity > input labels join)
+2. **Context tracking**: Cumulative security state tracked across turns
+3. **Policy enforcement**: Violations blocked before execution
+4. **Content isolation**: Untrusted content stored as variables
+5. **Taint propagation**: Once context becomes UNTRUSTED, it stays UNTRUSTED
+6. **Data exfiltration prevention**: `max_allowed_confidentiality` gates output destinations
+7. **Audit trail**: All security events logged
+8. **No runtime guessing**: Deterministic label assignment
+
+### Attack Prevention
+
+- **Direct prompt injection**: Variables hide actual content from LLM
+- **Indirect prompt injection**: Labels track untrusted AI-generated calls
+- **Privilege escalation**: Policy blocks untrusted calls to privileged tools
+- **Data exfiltration**: Confidentiality labels + `max_allowed_confidentiality` enforced
+- **Tool misuse**: Only whitelisted tools accept untrusted inputs
+
+## Configuration Options
+
+### LabelTrackingFunctionMiddleware
+- `default_integrity`: Default label for unknown sources
+- `default_confidentiality`: Default confidentiality level
+- `auto_hide_untrusted`: Enable automatic variable hiding (default: True)
+- `hide_threshold`: Integrity level at which hiding occurs (default: UNTRUSTED)
+
+### PolicyEnforcementFunctionMiddleware
+- `allow_untrusted_tools`: Set of tools accepting untrusted inputs
+- `block_on_violation`: Block vs warn on violations
+- `enable_audit_log`: Enable/disable audit logging
+
+### Tool Metadata (via `additional_properties`)
+- `confidentiality`: Tool's output confidentiality level
+- `source_integrity`: Fallback integrity for unlabeled results (data-producing tools only)
+- `accepts_untrusted`: Explicit untrusted input permission
+- `max_allowed_confidentiality`: Maximum allowed input confidentiality (for sink tools)
+- `requires_approval`: Human-in-the-loop requirement
+
+## Usage Pattern
+
+### Recommended: SecureAgentConfig as Context Provider
+
+```python
+from agent_framework.security import SecureAgentConfig
+
+config = SecureAgentConfig(
+    auto_hide_untrusted=True,
+    allow_untrusted_tools={"search_web"},
+    block_on_violation=True,
+)
+
+# Context provider injects everything automatically
+agent = Agent(
+    client=client,
+    name="secure_assistant",
+    instructions="You are a helpful assistant.",
+    tools=[search_web],
+    context_providers=[config],  # Tools, instructions, and middleware injected via before_run()
+)
+```
+
+### Processing Hidden Content with quarantined_llm
+
+```python
+from agent_framework.security import quarantined_llm
+
+# Agent automatically uses quarantined_llm with variable_ids
+result = await quarantined_llm(
+    prompt="Summarize this data",
+    variable_ids=["var_abc123"]  # Reference hidden content by ID
+)
+```
+
+## Testing
+
+Comprehensive test suite with:
+- 115+ unit tests covering all components
+- Label creation, serialization, combination
+- Variable store operations
+- Middleware behavior (tracking and enforcement)
+- Automatic hiding with per-item labels
+- Context label tracking
+- Message-level tracking (Phase 1)
+- Data exfiltration prevention
+- Policy violation scenarios
+- Audit log verification
+
+Run tests:
+```bash
+cd python/packages/core && ../../.venv/bin/pytest tests/test_security.py -v
+```
+
+## Code Statistics
+
+- **Total lines**: ~2,950+ lines (single `security.py` module)
+- **New modules**: 1 (`security.py` — consolidated from 3 original modules)
+- **Total tests**: 115+ unit tests
+- **Documentation**: 1,250+ lines in developer guide
+- **Examples**: 6+ comprehensive scenarios
+
+## Deliverables Checklist
+
+### Core Implementation
+✅ ContentLabel infrastructure with integrity and confidentiality
+✅ ContentVariableStore for variable indirection
+✅ VariableReferenceContent for safe context references
+✅ LabelTrackingFunctionMiddleware for automatic labeling
+✅ PolicyEnforcementFunctionMiddleware for policy enforcement
+✅ quarantined_llm tool for isolated processing
+✅ inspect_variable tool for controlled content access
+✅ store_untrusted_content helper for manual variable indirection
+
+### Automatic Hiding Enhancement
+✅ Auto-hide UNTRUSTED content with `auto_hide_untrusted` flag
+✅ Per-middleware ContentVariableStore instances
+✅ Thread-local storage for middleware access from tools
+✅ Automatic UNTRUSTED content replacement
+
+### Per-Item Embedded Labels
+✅ Support for `additional_properties.security_label` on individual items
+✅ Mixed-trust data handling (hide untrusted, keep trusted visible)
+✅ Fallback to `source_integrity` for unlabeled items
+
+### Context Label Tracking
+✅ Cumulative context label tracking across turns
+✅ Hidden content does NOT taint context
+✅ `get_context_label()` and `reset_context_label()` methods
+✅ Policy enforcement uses context label
+
+### Data Exfiltration Prevention
+✅ `max_allowed_confidentiality` tool property
+✅ `check_confidentiality_allowed()` helper function
+✅ Policy enforcement validates confidentiality flow
+
+### SecureAgentConfig
+✅ Context provider pattern with `ContextProvider` base class
+✅ `before_run()` hook for automatic injection of tools, instructions, and middleware
+✅ One-line secure agent configuration via `context_providers=[config]`
+✅ `get_tools()`, `get_instructions()`, `get_middleware()` methods (for manual use)
+✅ `quarantine_chat_client` support for real LLM calls
+✅ `SECURITY_TOOL_INSTRUCTIONS` constant
+
+### Documentation & Testing
+✅ Complete FIDES Developer Guide (~1250 lines)
+✅ Architecture Decision Record (ADR)
+✅ Quick Start Guide
+✅ Comprehensive test suite (115+ tests)
+✅ Example code with 6+ scenarios
+✅ 3 complete security examples (email, repo confidentiality, GitHub MCP labels)
+
+## Summary
+
+**FIDES** provides a comprehensive, deterministic defense against prompt injection attacks with:
+
+- **Zero-effort protection**: Automatic variable hiding for developers
+- **Context provider pattern**: `SecureAgentConfig` extends `ContextProvider` for automatic setup
+- **Granular control**: Per-item embedded labels via `Content.from_text()` for mixed-trust data
+- **Easy configuration**: `SecureAgentConfig` for one-line setup
+- **Data safety**: Exfiltration prevention via confidentiality gates
+- **Full traceability**: Message-level label tracking
+- **Complete auditability**: All security events logged
+
+The system ensures that untrusted content never directly reaches the LLM context and that all tool calls are policy-checked based on the cumulative security state before execution.

dotnet/Directory.Packages.props

@@ -11,7 +11,7 @@
   </PropertyGroup>
   <ItemGroup>
     <!-- Aspire.* -->
-    <PackageVersion Include="Anthropic" Version="12.13.0" />
+    <PackageVersion Include="Anthropic" Version="12.20.0" />
     <PackageVersion Include="Anthropic.Foundry" Version="0.5.0" />
     <PackageVersion Include="Aspire.Hosting" Version="$(AspireAppHostSdkVersion)" />
     <PackageVersion Include="Aspire.Azure.AI.OpenAI" Version="13.0.0-preview.1.25560.3" />
@@ -25,7 +25,8 @@
     <PackageVersion Include="Azure.AI.AgentServer.Core" Version="1.0.0-beta.23" />
     <PackageVersion Include="Azure.AI.AgentServer.Invocations" Version="1.0.0-beta.3" />
     <PackageVersion Include="Azure.AI.AgentServer.Responses" Version="1.0.0-beta.4" />
-    <PackageVersion Include="Azure.AI.Projects" Version="2.0.0" />
+    <PackageVersion Include="Azure.Search.Documents" Version="12.0.0" />
+    <PackageVersion Include="Azure.AI.Projects" Version="2.1.0-beta.1" />
     <PackageVersion Include="Azure.AI.Agents.Persistent" Version="1.2.0-beta.10" />
     <PackageVersion Include="Azure.AI.OpenAI" Version="2.9.0-beta.1" />
     <PackageVersion Include="Azure.Core" Version="1.53.0" />
@@ -71,12 +72,12 @@
     <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
     <PackageVersion Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.0.0" />
     <!-- Microsoft.Extensions.* -->
-    <PackageVersion Include="Microsoft.Extensions.AI" Version="10.5.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="10.5.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI" Version="10.5.1" />
+    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="10.5.1" />
     <PackageVersion Include="Microsoft.Extensions.AI.Evaluation" Version="10.4.0" />
     <PackageVersion Include="Microsoft.Extensions.AI.Evaluation.Quality" Version="10.4.0" />
     <PackageVersion Include="Microsoft.Extensions.AI.Evaluation.Safety" Version="10.3.0-preview.1.26109.11" />
-    <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.5.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.5.1" />
     <PackageVersion Include="Microsoft.Extensions.Caching.Memory" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Compliance.Abstractions" Version="10.5.0" />
     <PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.1" />
@@ -86,6 +87,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" />
@@ -97,7 +99,7 @@
     <PackageVersion Include="Microsoft.SemanticKernel.Connectors.InMemory" Version="1.67.0-preview" />
     <PackageVersion Include="Microsoft.SemanticKernel.Connectors.Qdrant" Version="1.67.0-preview" />
     <!-- Agent SDKs -->
-    <PackageVersion Include="GitHub.Copilot.SDK" Version="0.1.29" />
+    <PackageVersion Include="GitHub.Copilot.SDK" Version="1.0.0-beta.2" />
     <PackageVersion Include="Microsoft.Agents.CopilotStudio.Client" Version="1.3.171-beta" />
     <!-- M365 Agents SDK -->
     <PackageVersion Include="AdaptiveCards" Version="3.1.0" />
@@ -108,6 +110,8 @@
     <PackageVersion Include="A2A.AspNetCore" Version="1.0.0-preview2" />
     <!-- MCP -->
     <PackageVersion Include="ModelContextProtocol" Version="1.1.0" />
+    <!-- Hyperlight -->
+    <PackageVersion Include="Hyperlight.HyperlightSandbox.Api" Version="0.4.0" />
     <!-- Inference SDKs -->
     <PackageVersion Include="Microsoft.ML.OnnxRuntimeGenAI" Version="0.10.0" />
     <PackageVersion Include="Microsoft.ML.Tokenizers" Version="2.0.0" />
@@ -135,6 +139,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 +194,4 @@
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
   </ItemGroup>
-</Project>
+</Project>

dotnet/README.md

@@ -33,3 +33,4 @@ Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Fram
 - [Design Documents](../docs/design)
 - [Architectural Decision Records](../docs/decisions)
 - [MSFT Learn Docs](https://learn.microsoft.com/agent-framework/overview/agent-framework-overview)
+

dotnet/agent-framework-dotnet.slnx

@@ -65,6 +65,7 @@
     <Project Path="samples/02-agents/Agents/Agent_Step18_CompactionPipeline/Agent_Step18_CompactionPipeline.csproj" />
     <Project Path="samples/02-agents/Agents/Agent_Step19_InFunctionLoopCheckpointing/Agent_Step19_InFunctionLoopCheckpointing.csproj" />
     <Project Path="samples/02-agents/Agents/Agent_Step20_DynamicFunctionTools/Agent_Step20_DynamicFunctionTools.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step21_ShellWithEnvironment/Agent_Step21_ShellWithEnvironment.csproj" />
   </Folder>
   <Folder Name="/Samples/02-agents/DeclarativeAgents/">
     <Project Path="samples/02-agents/DeclarativeAgents/ChatClient/DeclarativeChatClientAgents.csproj" />
@@ -117,6 +118,15 @@
     <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" />
+    <Project Path="samples/02-agents/Harness/ConsoleReactiveFramework/ConsoleReactiveFramework.csproj" />
+    <Project Path="samples/02-agents/Harness/ConsoleReactiveComponents/ConsoleReactiveComponents.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,13 +170,19 @@
     <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step22_MemorySearch/Agent_Step22_MemorySearch.csproj" />
     <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step23_LocalMCP/Agent_Step23_LocalMCP.csproj" />
     <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step24_CodeInterpreterFileDownload/Agent_Step24_CodeInterpreterFileDownload.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step25_ToolboxServerSideTools/Agent_Step25_ToolboxServerSideTools.csproj" />
+    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step25_FoundryToolboxMcp/Agent_Step25_FoundryToolboxMcp.csproj" />
   </Folder>
   <Folder Name="/Samples/02-agents/Evaluation/">
-    <Project Path="samples/02-agents/Evaluation/Evaluation_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/AgentWithCodeAct/">
+    <File Path="samples/02-agents/AgentWithCodeAct/README.md" />
+    <Project Path="samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step01_Interpreter/AgentWithCodeAct_Step01_Interpreter.csproj" />
+    <Project Path="samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step02_ToolEnabled/AgentWithCodeAct_Step02_ToolEnabled.csproj" />
+    <Project Path="samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step03_ManualWiring/AgentWithCodeAct_Step03_ManualWiring.csproj" />
   </Folder>
   <Folder Name="/Samples/02-agents/AgentWithMemory/">
     <File Path="samples/02-agents/AgentWithMemory/README.md" />
@@ -226,6 +242,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" />
@@ -299,15 +316,24 @@
   <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-FoundryAgent/">
     <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-FoundryAgent/HostedFoundryAgent.csproj" />
   </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files/HostedFiles.csproj" />
+  </Folder>
   <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalTools/">
     <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalTools/HostedLocalTools.csproj" />
   </Folder>
   <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-McpTools/">
     <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-McpTools/HostedMcpTools.csproj" />
   </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-Observability/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-Observability/HostedObservability.csproj" />
+  </Folder>
   <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox/">
     <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox/HostedToolbox.csproj" />
   </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/HostedAzureSearchRag.csproj" />
+  </Folder>
   <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-TextRag/">
     <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-TextRag/HostedTextRag.csproj" />
   </Folder>
@@ -315,6 +341,7 @@
     <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Simple/HostedWorkflowSimple.csproj" />
   </Folder>
   <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SessionFilesClient/SessionFilesClient.csproj" />
     <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent/SimpleAgent.csproj" />
   </Folder>
   <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Handoff/">
@@ -347,17 +374,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" />
-  </Folder>  
+    <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" />
@@ -527,6 +554,16 @@
   <Folder Name="/Solution Items/src/Shared/StructuredOutput/">
     <File Path="src/Shared/StructuredOutput/StructuredOutputSchemaUtilities.cs" />
   </Folder>
+  <Folder Name="/Solution Items/src/Shared/Workflows/" />
+  <Folder Name="/Solution Items/src/Shared/Workflows/Execution/">
+    <File Path="src/Shared/Workflows/Execution/README.md" />
+    <File Path="src/Shared/Workflows/Execution/WorkflowFactory.cs" />
+    <File Path="src/Shared/Workflows/Execution/WorkflowRunner.cs" />
+  </Folder>
+  <Folder Name="/Solution Items/src/Shared/Workflows/Settings/">
+    <File Path="src/Shared/Workflows/Settings/Application.cs" />
+    <File Path="src/Shared/Workflows/Settings/README.md" />
+  </Folder>
   <Folder Name="/Solution Items/tests/">
     <File Path="tests/.editorconfig" />
     <File Path="tests/Directory.Build.props" />
@@ -543,8 +580,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" />
@@ -552,9 +589,11 @@
     <Project Path="src/Microsoft.Agents.AI.Hosting.AzureFunctions/Microsoft.Agents.AI.Hosting.AzureFunctions.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.OpenAI/Microsoft.Agents.AI.Hosting.OpenAI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting/Microsoft.Agents.AI.Hosting.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Hyperlight/Microsoft.Agents.AI.Hyperlight.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Mem0/Microsoft.Agents.AI.Mem0.csproj" />
     <Project Path="src/Microsoft.Agents.AI.OpenAI/Microsoft.Agents.AI.OpenAI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Purview/Microsoft.Agents.AI.Purview.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Tools.Shell/Microsoft.Agents.AI.Tools.Shell.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative.Foundry/Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative.Mcp/Microsoft.Agents.AI.Workflows.Declarative.Mcp.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative/Microsoft.Agents.AI.Workflows.Declarative.csproj" />
@@ -568,12 +607,16 @@
     <Project Path="tests/AnthropicChatCompletion.IntegrationTests/AnthropicChatCompletion.IntegrationTests.csproj" />
     <Project Path="tests/AzureAIAgentsPersistent.IntegrationTests/AzureAIAgentsPersistent.IntegrationTests.csproj" />
     <Project Path="tests/CopilotStudio.IntegrationTests/CopilotStudio.IntegrationTests.csproj" />
+    <Project Path="tests/Foundry.Hosting.IntegrationTests/Foundry.Hosting.IntegrationTests.csproj" />
+    <Project Path="tests/Foundry.Hosting.IntegrationTests.TestContainer/Foundry.Hosting.IntegrationTests.TestContainer.csproj" />
     <Project Path="tests/Foundry.IntegrationTests/Foundry.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.DurableTask.IntegrationTests/Microsoft.Agents.AI.DurableTask.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.IntegrationTests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Hyperlight.IntegrationTests/Microsoft.Agents.AI.Hyperlight.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Mem0.IntegrationTests/Microsoft.Agents.AI.Mem0.IntegrationTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Tools.Shell.IntegrationTests/Microsoft.Agents.AI.Tools.Shell.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Workflows.Declarative.IntegrationTests/Microsoft.Agents.AI.Workflows.Declarative.IntegrationTests.csproj" />
     <Project Path="tests/OpenAIAssistant.IntegrationTests/OpenAIAssistant.IntegrationTests.csproj" />
     <Project Path="tests/OpenAIChatCompletion.IntegrationTests/OpenAIChatCompletion.IntegrationTests.csproj" />
@@ -591,15 +634,18 @@
     <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" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AzureFunctions.UnitTests/Microsoft.Agents.AI.Hosting.AzureFunctions.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.UnitTests/Microsoft.Agents.AI.Hosting.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Hyperlight.UnitTests/Microsoft.Agents.AI.Hyperlight.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Mem0.UnitTests/Microsoft.Agents.AI.Mem0.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.OpenAI.UnitTests/Microsoft.Agents.AI.OpenAI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Purview.UnitTests/Microsoft.Agents.AI.Purview.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Tools.Shell.UnitTests/Microsoft.Agents.AI.Tools.Shell.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.UnitTests/Microsoft.Agents.AI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Workflows.Declarative.Mcp.UnitTests/Microsoft.Agents.AI.Workflows.Declarative.Mcp.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests.csproj" />

dotnet/agent-framework-release.slnf

@@ -30,7 +30,8 @@
       "src\\Microsoft.Agents.AI.Workflows.Generators\\Microsoft.Agents.AI.Workflows.Generators.csproj",
       "src\\Microsoft.Agents.AI.Workflows\\Microsoft.Agents.AI.Workflows.csproj",
       "src\\Microsoft.Agents.AI\\Microsoft.Agents.AI.csproj",
-      "src\\Aspire.Hosting.AgentFramework.DevUI\\Aspire.Hosting.AgentFramework.DevUI.csproj"
+      "src\\Aspire.Hosting.AgentFramework.DevUI\\Aspire.Hosting.AgentFramework.DevUI.csproj",
+      "src\\Microsoft.Agents.AI.Hyperlight\\Microsoft.Agents.AI.Hyperlight.csproj"
     ]
   }
 }

dotnet/nuget/nuget-package.props

@@ -1,14 +1,14 @@
 <Project>
   <PropertyGroup>
     <!-- Central version prefix - applies to all nuget packages. -->
-    <VersionPrefix>1.3.0</VersionPrefix>
+    <VersionPrefix>1.5.0</VersionPrefix>
     <RCNumber>1</RCNumber>
-    <DateSuffix>260423</DateSuffix>
+    <DateSuffix>260507</DateSuffix>
     <PackageVersion Condition="'$(IsReleaseCandidate)' == 'true'">$(VersionPrefix)-rc$(RCNumber)</PackageVersion>
     <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).$(DateSuffix).1</PackageVersion>
     <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' == ''">$(VersionPrefix)-preview.$(DateSuffix).1</PackageVersion>
     <PackageVersion Condition="'$(IsReleased)' == 'true'">$(VersionPrefix)</PackageVersion>
-    <GitTag>1.3.0</GitTag>
+    <GitTag>1.5.0</GitTag>
 
     <Configurations>Debug;Release;Publish</Configurations>
     <IsPackable>true</IsPackable>

dotnet/samples/01-get-started/04_memory/Program.cs

@@ -50,12 +50,12 @@ Console.WriteLine(await agent.RunAsync("My name is Ruaidhrí", session));
 Console.WriteLine(await agent.RunAsync("I am 20 years old", session));
 
 // We can serialize the session. The serialized state will include the state of the memory component.
-JsonElement sesionElement = await agent.SerializeSessionAsync(session);
+JsonElement sessionElement = await agent.SerializeSessionAsync(session);
 
 Console.WriteLine("\n>> Use deserialized session with previously created memories\n");
 
 // Later we can deserialize the session and continue the conversation with the previous memory component state.
-var deserializedSession = await agent.DeserializeSessionAsync(sesionElement);
+var deserializedSession = await agent.DeserializeSessionAsync(sessionElement);
 Console.WriteLine(await agent.RunAsync("What is my name and age?", deserializedSession));
 
 Console.WriteLine("\n>> Read memories using memory component\n");

dotnet/samples/02-agents/AgentProviders/Agent_With_GitHubCopilot/Program.cs

@@ -12,7 +12,9 @@ static Task<PermissionRequestResult> PromptPermission(PermissionRequest request,
     Console.Write("Approve? (y/n): ");
 
     string? input = Console.ReadLine()?.Trim().ToUpperInvariant();
-    string kind = input is "Y" or "YES" ? "approved" : "denied-interactively-by-user";
+    PermissionRequestResultKind kind = input is "Y" or "YES"
+                                     ? PermissionRequestResultKind.Approved
+                                     : PermissionRequestResultKind.Rejected;
 
     return Task.FromResult(new PermissionRequestResult { Kind = kind });
 }

dotnet/samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step01_Interpreter/AgentWithCodeAct_Step01_Interpreter.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Hyperlight\Microsoft.Agents.AI.Hyperlight.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step01_Interpreter/Program.cs

@@ -0,0 +1,30 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to use HyperlightCodeActProvider as a sandboxed Python
+// code interpreter: the model can write and execute arbitrary Python code to
+// answer quantitative questions without calling any additional tools.
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Hyperlight;
+using OpenAI.Chat;
+
+var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+var guestPath = Environment.GetEnvironmentVariable("HYPERLIGHT_PYTHON_GUEST_PATH") ?? throw new InvalidOperationException("HYPERLIGHT_PYTHON_GUEST_PATH is not set.");
+
+using var codeAct = new HyperlightCodeActProvider(HyperlightCodeActProviderOptions.CreateForWasm(guestPath));
+
+AIAgent agent = new AzureOpenAIClient(
+    new Uri(endpoint),
+    new DefaultAzureCredential())
+    .GetChatClient(deploymentName)
+    .AsAIAgent(new ChatClientAgentOptions()
+    {
+        ChatOptions = new() { Instructions = "You are a helpful assistant. When the user asks something quantitative, write Python and call `execute_code` instead of guessing." },
+        AIContextProviders = [codeAct],
+    });
+
+Console.WriteLine(await agent.RunAsync("What is the 20th Fibonacci number?"));
+Console.WriteLine(await agent.RunAsync("Compute the mean and standard deviation of [1, 4, 9, 16, 25, 36]."));

dotnet/samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step01_Interpreter/README.md

@@ -0,0 +1,35 @@
+# AgentWithCodeAct_Step01_Interpreter
+
+A minimal CodeAct sample. The agent uses `HyperlightCodeActProvider` as a
+sandboxed Python interpreter: when the user asks something quantitative, the
+model writes Python and invokes the `execute_code` tool rather than answering
+from memory.
+
+## Configuration
+
+| Variable                       | Description                                                                               |
+|--------------------------------|-------------------------------------------------------------------------------------------|
+| `AZURE_OPENAI_ENDPOINT`        | Azure OpenAI endpoint. Required.                                                          |
+| `AZURE_OPENAI_DEPLOYMENT_NAME` | Azure OpenAI deployment. Defaults to `gpt-5.4-mini`.                                      |
+| `HYPERLIGHT_PYTHON_GUEST_PATH` | Absolute path to the Hyperlight Python guest module (`.wasm` or `.aot` file). Required.   |
+
+Authentication uses `DefaultAzureCredential`.
+
+## Getting the guest module
+
+The Python guest module is built from the
+[hyperlight-dev/hyperlight-sandbox](https://github.com/hyperlight-dev/hyperlight-sandbox)
+repository — see its README for the exact `cargo`/`just` invocations and
+the location of the resulting `.wasm` / `.aot` file. Set
+`HYPERLIGHT_PYTHON_GUEST_PATH` to the absolute path of that artifact
+before running the sample.
+
+Hyperlight requires a hardware virtualization back end on the host:
+KVM on Linux or WHP (Windows Hypervisor Platform) on Windows.
+
+## Run
+
+```shell
+cd AgentWithCodeAct_Step01_Interpreter
+dotnet run
+```

dotnet/samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step02_ToolEnabled/AgentWithCodeAct_Step02_ToolEnabled.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Hyperlight\Microsoft.Agents.AI.Hyperlight.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step02_ToolEnabled/Program.cs

@@ -0,0 +1,52 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to use HyperlightCodeActProvider with provider-owned
+// tools (exposed inside the sandbox via `call_tool(...)`). The model can
+// orchestrate those tools in a single Python block, reducing round-trips. A
+// sensitive tool (`send_email`) is additionally wrapped in
+// ApprovalRequiredAIFunction so any code that reaches it requires user approval
+// for the entire execute_code invocation.
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Hyperlight;
+using Microsoft.Extensions.AI;
+using OpenAI.Chat;
+
+var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+var guestPath = Environment.GetEnvironmentVariable("HYPERLIGHT_PYTHON_GUEST_PATH") ?? throw new InvalidOperationException("HYPERLIGHT_PYTHON_GUEST_PATH is not set.");
+
+AIFunction fetchDocs = AIFunctionFactory.Create(
+    (string topic) => $"Docs for {topic}: (...)",
+    name: "fetch_docs",
+    description: "Fetch documentation for a given topic.");
+
+AIFunction queryData = AIFunctionFactory.Create(
+    (string query) => $"Rows for `{query}`: []",
+    name: "query_data",
+    description: "Run a read-only SQL-like query against the sample store.");
+
+AIFunction sendEmail = new ApprovalRequiredAIFunction(
+    AIFunctionFactory.Create(
+        (string to, string subject) => $"Sent '{subject}' to {to}.",
+        name: "send_email",
+        description: "Send an email on behalf of the user."));
+
+var options = HyperlightCodeActProviderOptions.CreateForWasm(guestPath);
+options.Tools = [fetchDocs, queryData, sendEmail];
+
+using var codeAct = new HyperlightCodeActProvider(options);
+
+AIAgent agent = new AzureOpenAIClient(
+    new Uri(endpoint),
+    new DefaultAzureCredential())
+    .GetChatClient(deploymentName)
+    .AsAIAgent(new ChatClientAgentOptions()
+    {
+        ChatOptions = new() { Instructions = "You are a helpful assistant. Prefer orchestrating your work in a single `execute_code` block using `call_tool(...)` over issuing many direct tool calls." },
+        AIContextProviders = [codeAct],
+    });
+
+Console.WriteLine(await agent.RunAsync("Look up docs on 'retries' and query the 'orders' table, then summarize."));

dotnet/samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step02_ToolEnabled/README.md

@@ -0,0 +1,34 @@
+# AgentWithCodeAct_Step02_ToolEnabled
+
+Demonstrates adding provider-owned tools to `HyperlightCodeActProvider`. Those
+tools are **only** available to code running inside the sandbox via
+`call_tool("<name>", ...)` — they are never exposed to the model as direct
+tools. This lets the model orchestrate multiple tool calls in a single Python
+block.
+
+One tool (`send_email`) is wrapped in `ApprovalRequiredAIFunction`, which causes
+the entire `execute_code` invocation to require user approval when that tool
+is configured.
+
+## Configuration
+
+| Variable                       | Description                                                                               |
+|--------------------------------|-------------------------------------------------------------------------------------------|
+| `AZURE_OPENAI_ENDPOINT`        | Azure OpenAI endpoint. Required.                                                          |
+| `AZURE_OPENAI_DEPLOYMENT_NAME` | Azure OpenAI deployment. Defaults to `gpt-5.4-mini`.                                      |
+| `HYPERLIGHT_PYTHON_GUEST_PATH` | Absolute path to the Hyperlight Python guest module (`.wasm` or `.aot` file). Required.   |
+
+## Run
+
+```shell
+cd AgentWithCodeAct_Step02_ToolEnabled
+dotnet run
+```
+
+## Planned follow-up
+
+A more realistic "upload a file (e.g. an Excel workbook), have the agent
+analyze it with code" sample is planned as a separate step that will use
+`HostInputDirectory` together with a guest tool capable of reading the
+uploaded file. It will be added in a follow-up PR once the corresponding
+guest module support is in place.

dotnet/samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step03_ManualWiring/AgentWithCodeAct_Step03_ManualWiring.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Hyperlight\Microsoft.Agents.AI.Hyperlight.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step03_ManualWiring/Program.cs

@@ -0,0 +1,40 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to wire up CodeAct manually using
+// HyperlightExecuteCodeFunction rather than the AIContextProvider. Use this
+// when you want a fixed tool surface for the agent's lifetime and don't need
+// the per-run snapshot/registry semantics of HyperlightCodeActProvider.
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Hyperlight;
+using Microsoft.Extensions.AI;
+using OpenAI.Chat;
+
+var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+var guestPath = Environment.GetEnvironmentVariable("HYPERLIGHT_PYTHON_GUEST_PATH") ?? throw new InvalidOperationException("HYPERLIGHT_PYTHON_GUEST_PATH is not set.");
+
+AIFunction calculate = AIFunctionFactory.Create(
+    (double a, double b) => a * b,
+    name: "multiply",
+    description: "Multiply two numbers.");
+
+var options = HyperlightCodeActProviderOptions.CreateForWasm(guestPath);
+options.Tools = [calculate];
+
+using var executeCode = new HyperlightExecuteCodeFunction(options);
+
+var instructions =
+    "You are a helpful assistant. When math is involved, solve it by writing Python "
+    + "and calling `execute_code` instead of computing values yourself.\n\n"
+    + executeCode.BuildInstructions(toolsVisibleToModel: false);
+
+AIAgent agent = new AzureOpenAIClient(
+    new Uri(endpoint),
+    new DefaultAzureCredential())
+    .GetChatClient(deploymentName)
+    .AsAIAgent(instructions: instructions, tools: [executeCode]);
+
+Console.WriteLine(await agent.RunAsync("What is 12.3 * 4.5? Use the multiply tool from within `execute_code`."));

dotnet/samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step03_ManualWiring/README.md

@@ -0,0 +1,21 @@
+# AgentWithCodeAct_Step03_ManualWiring
+
+Shows how to wire CodeAct manually using `HyperlightExecuteCodeFunction` as a
+direct agent tool instead of via an `AIContextProvider`. This is useful when
+the sandbox's tool surface and capabilities are fixed for the agent's
+lifetime, avoiding per-run snapshot/restore of the provider registry.
+
+## Configuration
+
+| Variable                       | Description                                                                               |
+|--------------------------------|-------------------------------------------------------------------------------------------|
+| `AZURE_OPENAI_ENDPOINT`        | Azure OpenAI endpoint. Required.                                                          |
+| `AZURE_OPENAI_DEPLOYMENT_NAME` | Azure OpenAI deployment. Defaults to `gpt-5.4-mini`.                                      |
+| `HYPERLIGHT_PYTHON_GUEST_PATH` | Absolute path to the Hyperlight Python guest module (`.wasm` or `.aot` file). Required.   |
+
+## Run
+
+```shell
+cd AgentWithCodeAct_Step03_ManualWiring
+dotnet run
+```

dotnet/samples/02-agents/AgentWithCodeAct/README.md

@@ -0,0 +1,16 @@
+# Agent Framework CodeAct (Hyperlight) Samples
+
+These samples show how to enable an agent to write and execute code in a
+Hyperlight-backed sandbox via the CodeAct pattern. Guest code can be pure
+Python (interpreter mode) or orchestrate host-provided tools through
+`call_tool(...)` — all inside a secure sandbox with opt-in filesystem and
+network access.
+
+|Sample|Description|
+|---|---|
+|[Code interpreter](./AgentWithCodeAct_Step01_Interpreter/)|Uses `HyperlightCodeActProvider` as a sandboxed Python interpreter with no host tools.|
+|[Tool-enabled CodeAct](./AgentWithCodeAct_Step02_ToolEnabled/)|Registers provider-owned tools that guest code can orchestrate via `call_tool(...)`, with an approval-required tool for sensitive actions.|
+|[Manual wiring](./AgentWithCodeAct_Step03_ManualWiring/)|Uses `HyperlightExecuteCodeFunction` directly as an agent tool when the sandbox configuration is fixed.|
+
+All samples require a Hyperlight Python guest module. Set
+`HYPERLIGHT_PYTHON_GUEST_PATH` to its absolute path before running.

dotnet/samples/02-agents/Agents/Agent_Step19_InFunctionLoopCheckpointing/Program.cs

@@ -8,6 +8,11 @@
 // even if the process is interrupted mid-loop, but may also result in chat history that is not
 // yet finalized (e.g., tool calls without results) being persisted, which may be undesirable in some cases.
 //
+// Additionally, this sample demonstrates the MessageInjectingChatClient feature, which allows tool
+// code to inject new user messages during the function execution loop. When a tool or anything else enqueues
+// a message via MessageInjectingChatClient.EnqueueMessages during the tool execution loop, the PerServiceCallChatHistoryPersistingChatClient
+// detects the pending message before the next service call and includes the injected message in the request.
+//
 // To use end-of-run persistence instead (atomic run semantics), remove the
 // RequirePerServiceCallChatHistoryPersistence = true setting (or set it to false). End-of-run
 // persistence is the default behavior.
@@ -54,6 +59,37 @@ static string GetTime([Description("The city name.")] string city) =>
         _ => $"{city}: time data not available."
     };
 
+// This tool demonstrates message injection during the function execution loop.
+// When called, it checks travel advisories for a city. If an advisory is active, it uses
+// the ambient run context to resolve MessageInjectingChatClient and injects a follow-up user message
+// asking for alternative destinations. The model will process this injected message on the next
+// service call — even though the parent FunctionInvokingChatClient loop would otherwise stop.
+[Description("Check current travel advisories for a city.")]
+static string CheckTravelAdvisory([Description("The city name.")] string city)
+{
+    // Simulated travel advisory data.
+    var advisory = city.ToUpperInvariant() switch
+    {
+        "LONDON" => "Travel advisory: Severe fog warnings in London. Flights may be delayed or cancelled.",
+        "SEATTLE" => "Travel advisory: Heavy rainfall expected. Flooding possible in low-lying areas.",
+        _ => null
+    };
+
+    if (advisory is null)
+    {
+        return $"{city}: No active travel advisories.";
+    }
+
+    // When an advisory is found, inject a follow-up question so the model automatically
+    // suggests alternatives without the user needing to ask.
+    var runContext = AIAgent.CurrentRunContext!;
+    runContext.Agent.GetService<MessageInjectingChatClient>()?.EnqueueMessages(
+        runContext.Session!,
+        [new ChatMessage(ChatRole.User, $"Given the travel advisory for {city}, what alternative cities would you recommend instead?")]);
+
+    return advisory;
+}
+
 // Create the agent — per-service-call persistence is enabled via RequirePerServiceCallChatHistoryPersistence.
 // The in-memory ChatHistoryProvider is used by default when the service does not require service stored chat
 // history, so for those cases, we can inspect the chat history via session.TryGetInMemoryChatHistory().
@@ -65,10 +101,11 @@ AIAgent agent = chatClient.AsAIAgent(
     {
         Name = "WeatherAssistant",
         RequirePerServiceCallChatHistoryPersistence = true,
+        EnableMessageInjection = true,
         ChatOptions = new()
         {
-            Instructions = "You are a helpful assistant. When asked about multiple cities, call the appropriate tool for each city.",
-            Tools = [AIFunctionFactory.Create(GetWeather), AIFunctionFactory.Create(GetTime)]
+            Instructions = "You are a helpful travel assistant. When asked about cities, call the appropriate tools for each city.",
+            Tools = [AIFunctionFactory.Create(GetWeather), AIFunctionFactory.Create(GetTime), AIFunctionFactory.Create(CheckTravelAdvisory)]
         },
     });
 
@@ -109,6 +146,18 @@ async Task RunNonStreamingAsync()
     response = await agent.RunAsync(FollowUp2, session);
     PrintAgentResponse(response.Text);
     PrintChatHistory(session, "After third run", ref lastChatHistorySize, ref lastConversationId);
+
+    // Fourth turn — demonstrates message injection during the function loop.
+    // The CheckTravelAdvisory tool detects an advisory for London and injects a follow-up
+    // user message asking for alternative cities. After the tool completes, the internal loop
+    // in PerServiceCallChatHistoryPersistingChatClient detects the pending injected message
+    // and calls the service again, so the model answers the follow-up automatically.
+    const string TravelPrompt = "I'm planning to travel to London next week. Check if there are any travel advisories.";
+    PrintUserMessage(TravelPrompt);
+
+    response = await agent.RunAsync(TravelPrompt, session);
+    PrintAgentResponse(response.Text);
+    PrintChatHistory(session, "After travel advisory run", ref lastChatHistorySize, ref lastConversationId);
 }
 
 async Task RunStreamingAsync()
@@ -181,6 +230,30 @@ async Task RunStreamingAsync()
 
     Console.WriteLine();
     PrintChatHistory(session, "After third run", ref lastChatHistorySize, ref lastConversationId);
+
+    // Fourth turn — demonstrates message injection during the function loop (streaming).
+    // The CheckTravelAdvisory tool detects an advisory for London and injects a follow-up
+    // user message asking for alternative cities. After the tool completes, the internal loop
+    // in PerServiceCallChatHistoryPersistingChatClient detects the pending injected message
+    // and calls the service again, so the model answers the follow-up automatically.
+    const string TravelPrompt = "I'm planning to travel to London next week. Check if there are any travel advisories.";
+    PrintUserMessage(TravelPrompt);
+
+    Console.ForegroundColor = ConsoleColor.Cyan;
+    Console.Write("\n[Agent] ");
+    Console.ResetColor();
+
+    await foreach (var update in agent.RunStreamingAsync(TravelPrompt, session))
+    {
+        Console.Write(update);
+
+        // During streaming we should be able to see updates to the chat history
+        // before the full run completes, as each service call is made and persisted.
+        PrintChatHistory(session, "During travel advisory run", ref lastChatHistorySize, ref lastConversationId);
+    }
+
+    Console.WriteLine();
+    PrintChatHistory(session, "After travel advisory run", ref lastChatHistorySize, ref lastConversationId);
 }
 
 void PrintUserMessage(string message)

dotnet/samples/02-agents/Agents/Agent_Step21_ShellWithEnvironment/Agent_Step21_ShellWithEnvironment.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Tools.Shell\Microsoft.Agents.AI.Tools.Shell.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/02-agents/Agents/Agent_Step21_ShellWithEnvironment/Program.cs

@@ -0,0 +1,130 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// Shell tool with environment-aware system prompt
+//
+// WARNING: This sample uses LocalShellExecutor, which executes real commands
+// against the shell on this machine. Approval gating is disabled here so
+// the demo runs unattended; in any real application keep approval on
+// (the default), or use DockerShellExecutor for container isolation. The
+// commands the model emits below are read-only or scoped (echo, cd into
+// a temp folder, set a process-local env var) but a different model or
+// prompt could choose to do something destructive. Run this only in an
+// environment where you are comfortable with the agent typing into your
+// terminal.
+//
+// Demonstrates LocalShellExecutor in both modes paired with
+// ShellEnvironmentProvider, an AIContextProvider that probes the live
+// shell (OS, family, version, CWD, common CLIs) and injects authoritative
+// system-prompt instructions so the agent emits commands in the right
+// idiom (PowerShell vs POSIX).
+//
+// Two runs:
+//   1) Stateless mode: each tool call runs in a fresh shell. Useful when
+//      commands are independent (read-only scripts, version checks, file
+//      listings) and you want strong isolation between calls. Side
+//      effects in one call (cd, exported variables) do NOT carry to the
+//      next.
+//   2) Persistent mode: a single long-lived shell is reused across calls,
+//      so working directory and exported environment variables are
+//      preserved. Useful for multi-step workflows that build state
+//      (cd into a folder and run a sequence of commands there; set a
+//      token in one step and read it in the next).
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Tools.Shell;
+using Microsoft.Extensions.AI;
+using OpenAI.Chat;
+
+var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+
+var chatClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
+    .GetChatClient(deploymentName);
+
+const string Instructions = """
+    You are an agent with a single tool: run_shell. Use it to satisfy the
+    user's request. Do not describe what you would do — actually run the
+    commands. Reply with the final answer derived from real output.
+    """;
+
+// --------------------------------------------------------------------
+// 1. Stateless mode — each call gets a fresh shell.
+// --------------------------------------------------------------------
+Console.WriteLine("### Stateless mode\n");
+await using (var statelessShell = new LocalShellExecutor(new() { Mode = ShellMode.Stateless, AcknowledgeUnsafe = true }))
+{
+    var envProvider = new ShellEnvironmentProvider(statelessShell);
+    var statelessAgent = chatClient.AsAIAgent(new ChatClientAgentOptions
+    {
+        ChatOptions = new()
+        {
+            Instructions = Instructions,
+            Tools = [statelessShell.AsAIFunction(requireApproval: false)],
+        },
+        AIContextProviders = [envProvider],
+    });
+
+    var statelessSession = await statelessAgent.CreateSessionAsync();
+    Console.WriteLine(await statelessAgent.RunAsync("Print the current working directory.", statelessSession));
+    Console.WriteLine();
+
+    // Show that side effects do NOT carry between stateless calls: ask the
+    // agent to cd into the system temp directory in one call, then ask
+    // for the CWD in a second call. Stateless mode means the cd is gone.
+    Console.WriteLine(await statelessAgent.RunAsync("Change directory into the system temp folder, then print the current working directory.", statelessSession));
+    Console.WriteLine();
+    Console.WriteLine(await statelessAgent.RunAsync("In a NEW shell call, print the current working directory again. Tell me whether it matches the temp folder from the previous call.", statelessSession));
+    Console.WriteLine();
+
+    PrintSnapshot(envProvider.CurrentSnapshot!);
+}
+
+// --------------------------------------------------------------------
+// 2. Persistent mode — one shell, reused across calls. State carries.
+// --------------------------------------------------------------------
+Console.WriteLine("\n### Persistent mode\n");
+await using (var persistentShell = new LocalShellExecutor(new() { Mode = ShellMode.Persistent, AcknowledgeUnsafe = true }))
+{
+    var envProvider = new ShellEnvironmentProvider(persistentShell);
+    var persistentAgent = chatClient.AsAIAgent(new ChatClientAgentOptions
+    {
+        ChatOptions = new()
+        {
+            Instructions = Instructions,
+            Tools = [persistentShell.AsAIFunction(requireApproval: false)],
+        },
+        AIContextProviders = [envProvider],
+    });
+
+    var persistentSession = await persistentAgent.CreateSessionAsync();
+
+    // State carries across calls in persistent mode: cd into temp, then
+    // verify the next call sees the new CWD.
+    Console.WriteLine(await persistentAgent.RunAsync("Change directory into the system temp folder, then print the current working directory.", persistentSession));
+    Console.WriteLine();
+    Console.WriteLine(await persistentAgent.RunAsync("In a NEW shell call, print the current working directory again. Tell me whether it still matches the temp folder.", persistentSession));
+    Console.WriteLine();
+
+    // Same idea with an exported variable: set in one call, read in the next.
+    Console.WriteLine(await persistentAgent.RunAsync("Set the environment variable DEMO_TOKEN to the value 'hello-world'.", persistentSession));
+    Console.WriteLine();
+    Console.WriteLine(await persistentAgent.RunAsync("Print the current value of DEMO_TOKEN. Tell me exactly what value the shell reports.", persistentSession));
+    Console.WriteLine();
+
+    PrintSnapshot(envProvider.CurrentSnapshot!);
+}
+
+static void PrintSnapshot(ShellEnvironmentSnapshot snap)
+{
+    Console.WriteLine("--- Captured environment snapshot ---");
+    Console.WriteLine($"  Family:  {snap.Family}");
+    Console.WriteLine($"  OS:      {snap.OSDescription}");
+    Console.WriteLine($"  Shell:   {snap.ShellVersion ?? "(unknown)"}");
+    Console.WriteLine($"  CWD:     {snap.WorkingDirectory}");
+    foreach (var (tool, version) in snap.ToolVersions)
+    {
+        Console.WriteLine($"  {tool,-8} {version ?? "(not installed)"}");
+    }
+}

dotnet/samples/02-agents/AgentsWithFoundry/Agent_Step25_FoundryToolboxMcp/Agent_Step25_FoundryToolboxMcp.csproj

@@ -0,0 +1,21 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Projects" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="ModelContextProtocol" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/02-agents/AgentsWithFoundry/Agent_Step25_FoundryToolboxMcp/Program.cs

@@ -1,93 +1,80 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-// This sample shows how to load a Foundry toolbox and pass its tools as server-side
-// tools when creating an agent. The Foundry platform handles tool execution — the agent
-// process does not invoke tools locally.
+// Foundry Toolbox via MCP (Streamable HTTP).
+//
+// Point an `McpClient` at a Foundry Toolbox's MCP endpoint. The agent
+// discovers the toolbox's tools at runtime and invokes them locally.
 
 using System.ClientModel;
 using System.ClientModel.Primitives;
+using System.Net.Http.Headers;
 using Azure.AI.Projects;
 using Azure.AI.Projects.Agents;
+using Azure.Core;
 using Azure.Identity;
 using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using ModelContextProtocol.Client;
 using OpenAI.Responses;
 
 #pragma warning disable OPENAI001 // Experimental API
 #pragma warning disable AAIP001  // AgentToolboxes is experimental
-#pragma warning disable CS8321   // Local functions may be commented-out alternatives
 
-// Replace with your own Foundry toolbox name.
+// Must match the `<name>` segment of FOUNDRY_TOOLBOX_ENDPOINT.
 const string ToolboxName = "research_toolbox";
-// Used only by CombineToolboxes — swap in a second toolbox you own.
-const string SecondToolboxName = "analysis_toolbox";
-// Replace with any question that exercises the tools configured in your toolbox.
-const string Query = "Introduce yourself and briefly describe the tools you can use to help me.";
+const string Query = "What tools do you have access to?";
 
-string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
-    ?? throw new InvalidOperationException("Set FOUNDRY_PROJECT_ENDPOINT to your Foundry project endpoint.");
-string model = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
+string endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+string toolboxEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_TOOLBOX_ENDPOINT")
+    ?? throw new InvalidOperationException(
+        "FOUNDRY_TOOLBOX_ENDPOINT is not set. Example: " +
+        "https://<account>.services.ai.azure.com/api/projects/<project>/toolsets/<name>/mcp?api-version=2025-05-01-preview");
+
+TokenCredential credential = new DefaultAzureCredential();
+
+// Comment out if the toolbox already exists in your Foundry project.
+await CreateSampleToolboxAsync(ToolboxName, endpoint, credential);
+
+// Inject a fresh Azure AI bearer token on every MCP request.
+using var httpClient = new HttpClient(new BearerTokenHandler(credential, "https://ai.azure.com/.default")
+{
+    InnerHandler = new HttpClientHandler(),
+});
+
+Console.WriteLine($"Connecting to toolbox MCP endpoint: {toolboxEndpoint}");
+
+await using McpClient mcpClient = await McpClient.CreateAsync(
+    new HttpClientTransport(
+        new HttpClientTransportOptions
+        {
+            Endpoint = new Uri(toolboxEndpoint),
+            Name = "foundry_toolbox",
+        },
+        httpClient));
+
+IList<McpClientTool> mcpTools = await mcpClient.ListToolsAsync();
+Console.WriteLine($"Toolbox MCP tools available: {string.Join(", ", mcpTools.Select(t => t.Name))}");
 
 // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
 // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
 // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-var projectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential());
+AIProjectClient aiProjectClient = new(new Uri(endpoint), credential);
 
-await Main(projectClient, model, endpoint);
-// await CombineToolboxes(projectClient, model, endpoint);
+AIAgent agent = aiProjectClient.AsAIAgent(
+    model: deploymentName,
+    instructions: "You are a helpful assistant. Use the available toolbox tools to answer the user.",
+    name: "ToolboxMcpAgent",
+    tools: [.. mcpTools.Cast<AITool>()]);
+
+Console.WriteLine($"\nUser: {Query}\n");
+Console.WriteLine($"Assistant: {await agent.RunAsync(Query)}");
 
 // ---------------------------------------------------------------------------
-// Main: single toolbox
+// Helper: create (or replace) a sample toolbox so the sample runs end-to-end
 // ---------------------------------------------------------------------------
-static async Task Main(AIProjectClient projectClient, string model, string endpoint)
-{
-    Console.WriteLine("=== Foundry Toolbox Server-Side Tools Example ===");
-
-    // Comment out if the toolbox already exists in your Foundry project.
-    await CreateSampleToolboxAsync(ToolboxName, endpoint);
-
-    // Omit the version to resolve the toolbox's current default version at runtime.
-    var tools = await projectClient.GetToolboxToolsAsync(ToolboxName);
-
-    AIAgent agent = projectClient
-        .AsAIAgent(
-            model: model,
-            instructions: "You are a research assistant. Use the available tools to answer questions.",
-            tools: tools.ToList());
-
-    Console.WriteLine($"User: {Query}");
-    Console.WriteLine($"Result: {await agent.RunAsync(Query)}\n");
-}
-
-// ---------------------------------------------------------------------------
-// Alternative: combine tools from multiple toolboxes
-// ---------------------------------------------------------------------------
-static async Task CombineToolboxes(AIProjectClient projectClient, string model, string endpoint)
-{
-    Console.WriteLine("=== Combine Toolboxes Example ===");
-
-    // Comment out if the toolboxes already exist in your Foundry project.
-    await CreateSampleToolboxAsync(ToolboxName, endpoint);
-    await CreateSampleToolboxAsync(SecondToolboxName, endpoint);
-
-    var toolboxA = await projectClient.GetToolboxToolsAsync(ToolboxName);
-    var toolboxB = await projectClient.GetToolboxToolsAsync(SecondToolboxName);
-
-    var allTools = toolboxA.Concat(toolboxB).ToList();
-
-    AIAgent agent = projectClient
-        .AsAIAgent(
-            model: model,
-            instructions: "You are a research assistant. Use all available tools to answer questions.",
-            tools: allTools);
-
-    Console.WriteLine($"User: {Query}");
-    Console.WriteLine($"Combined-toolbox result: {await agent.RunAsync(Query)}\n");
-}
-
-// ---------------------------------------------------------------------------
-// Helper: create (or replace) a sample toolbox so the sample works out-of-the-box
-// ---------------------------------------------------------------------------
-static async Task CreateSampleToolboxAsync(string name, string endpoint)
+static async Task CreateSampleToolboxAsync(string name, string endpoint, TokenCredential credential)
 {
     // Toolboxes are normally configured in the Foundry portal or a deployment
     // script, not the application itself. This helper exists so the sample can
@@ -96,10 +83,7 @@ static async Task CreateSampleToolboxAsync(string name, string endpoint)
     // The Foundry-Features header is currently required for toolbox CRUD operations.
     var options = new AgentAdministrationClientOptions();
     options.AddPolicy(new FoundryFeaturesPolicy("Toolboxes=V1Preview"), PipelinePosition.PerCall);
-    var adminClient = new AgentAdministrationClient(
-        new Uri(endpoint),
-        new DefaultAzureCredential(),
-        options);
+    var adminClient = new AgentAdministrationClient(new Uri(endpoint), credential, options);
     var toolboxClient = adminClient.GetAgentToolboxes();
 
     // Delete existing toolbox if present (ignore 404).
@@ -128,7 +112,7 @@ static async Task CreateSampleToolboxAsync(string name, string endpoint)
 }
 
 // ---------------------------------------------------------------------------
-// Pipeline policy that adds the Foundry-Features header for toolbox CRUD
+// Pipeline policy: adds the Foundry-Features header for toolbox CRUD calls
 // ---------------------------------------------------------------------------
 internal sealed class FoundryFeaturesPolicy(string feature) : PipelinePolicy
 {
@@ -146,3 +130,18 @@ internal sealed class FoundryFeaturesPolicy(string feature) : PipelinePolicy
         return ProcessNextAsync(message, pipeline, currentIndex);
     }
 }
+
+// ---------------------------------------------------------------------------
+// DelegatingHandler: attaches a fresh Azure AI bearer token to every request
+// ---------------------------------------------------------------------------
+internal sealed class BearerTokenHandler(TokenCredential credential, string scope) : DelegatingHandler
+{
+    private readonly TokenRequestContext _tokenContext = new([scope]);
+
+    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
+    {
+        AccessToken token = await credential.GetTokenAsync(this._tokenContext, cancellationToken).ConfigureAwait(false);
+        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token.Token);
+        return await base.SendAsync(request, cancellationToken).ConfigureAwait(false);
+    }
+}

dotnet/samples/02-agents/AgentsWithFoundry/Agent_Step25_FoundryToolboxMcp/README.md

@@ -0,0 +1,31 @@
+# Foundry Toolbox via MCP
+
+This sample shows how to use a Foundry Toolbox by pointing an `McpClient` at the toolbox's MCP endpoint. The agent discovers the toolbox's tools at runtime and invokes them locally over MCP.
+
+## What this sample demonstrates
+
+- Connecting to a Foundry toolbox's MCP endpoint via Streamable HTTP transport
+- Injecting a fresh Azure AI bearer token (`https://ai.azure.com/.default`) on every MCP request
+- Passing the discovered MCP tools to `AIProjectClient.AsAIAgent(...)`
+- Optional helper to create (or replace) a sample toolbox in the project so the sample is runnable end-to-end
+
+## Prerequisites
+
+- A Microsoft Foundry project with a toolbox configured (or let the sample create one for you)
+- Azure CLI installed and authenticated (`az login`)
+
+Set the following environment variables:
+
+```powershell
+$env:AZURE_AI_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project"
+$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-5.4-mini"
+$env:FOUNDRY_TOOLBOX_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project/toolsets/research_toolbox/mcp?api-version=2025-05-01-preview"
+```
+
+The `<name>` segment of `FOUNDRY_TOOLBOX_ENDPOINT` must match the `ToolboxName` constant in `Program.cs`.
+
+## Run the sample
+
+```powershell
+dotnet run
+```

dotnet/samples/02-agents/AgentsWithFoundry/Agent_Step25_ToolboxServerSideTools/README.md

@@ -1,46 +0,0 @@
-# Agent_Step25_ToolboxServerSideTools
-
-This sample demonstrates loading a named Foundry toolbox and passing its tools as
-**server-side tools** when creating an agent via `AsAIAgent()`.
-
-When tools from a toolbox are passed this way, they are sent as tool definitions in
-the Responses API request. The Foundry platform handles tool execution — the agent
-process does not invoke tools locally.
-
-This is the dotnet equivalent of the Python sample:
-`python/samples/02-agents/providers/foundry/foundry_chat_client_with_toolbox.py`
-
-## Prerequisites
-
-- A Microsoft Foundry project
-- `AZURE_AI_PROJECT_ENDPOINT` environment variable set to your Foundry project endpoint
-- `AZURE_AI_MODEL_DEPLOYMENT_NAME` environment variable set (defaults to `gpt-5.4-mini`)
-
-The sample recreates the toolbox on each run, replacing any existing toolbox with
-the same name. Comment out the `CreateSampleToolboxAsync` call if you want to keep
-an existing toolbox unchanged.
-
-## How it works
-
-1. `projectClient.GetToolboxVersionAsync(name)` fetches the toolbox definition from the
-   Foundry project API (resolving the default version if none is specified)
-2. `ToolboxVersion.ToAITools()` converts each tool definition to an `AITool` instance
-3. The tools are passed to `AsAIAgent(tools: ...)` which includes them in the Responses
-   API request as server-side tool definitions
-
-For a one-liner, use `projectClient.GetToolboxToolsAsync(name)` to fetch and convert in one call.
-
-## Sample flows
-
-| Flow | Description |
-|------|-------------|
-| `Main` (default) | Loads a single toolbox and runs an agent with its tools |
-| `CombineToolboxes` | Loads two toolboxes and merges their tools into one agent |
-
-Uncomment the desired flow in the top-level statements to try each one.
-
-## Running the sample
-
-```bash
-dotnet run
-```

dotnet/samples/02-agents/AgentsWithFoundry/README.md

@@ -73,6 +73,7 @@ Some samples require extra tool-specific environment variables. See each sample
 | [Memory search](./Agent_Step22_MemorySearch/) | Memory search tool |
 | [Local MCP](./Agent_Step23_LocalMCP/) | Local MCP client with HTTP transport |
 | [Code interpreter file download](./Agent_Step24_CodeInterpreterFileDownload/) | Download container files generated by code interpreter |
+| [Foundry toolbox via MCP](./Agent_Step25_FoundryToolboxMcp/) | Use a Foundry Toolbox from a non-hosted agent via its MCP endpoint |
 
 ## Running the samples
 

dotnet/samples/02-agents/Harness/ConsoleReactiveComponents/AnsiEscapes.cs

@@ -0,0 +1,90 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Harness.ConsoleReactiveComponents;
+
+/// <summary>
+/// Provides descriptive helpers for common ANSI/VT100 escape sequences used
+/// in the split-console layout (DECSTBM scroll regions, cursor movement, line erasure).
+/// </summary>
+public static class AnsiEscapes
+{
+    /// <summary>
+    /// Sets the scrollable region to rows 1 through <paramref name="bottom"/> (DECSTBM).
+    /// Content outside this region will not scroll.
+    /// </summary>
+    public static string SetScrollRegion(int bottom) => $"\x1b[1;{bottom}r";
+
+    /// <summary>
+    /// Resets the scroll region to the full terminal height (DECSTBM reset).
+    /// </summary>
+    public static string ResetScrollRegion => "\x1b[r";
+
+    /// <summary>
+    /// Moves the cursor to the specified 1-based <paramref name="row"/> and <paramref name="column"/> (CUP).
+    /// </summary>
+    public static string MoveCursor(int row, int column) => $"\x1b[{row};{column}H";
+
+    /// <summary>
+    /// Erases the entire current line (EL 2).
+    /// </summary>
+    public static string EraseEntireLine => "\x1b[2K";
+
+    /// <summary>
+    /// Erases the entire screen.
+    /// </summary>
+    public static string EraseEntireScreen => "\x1b[2J";
+
+    /// <summary>
+    /// Erases the scrollback buffer (ESC[3J). Use alongside <see cref="EraseEntireScreen"/>
+    /// to fully clear both the visible screen and the scroll history.
+    /// </summary>
+    public static string EraseScrollbackBuffer => "\x1b[3J";
+
+    /// <summary>
+    /// Saves the current cursor position (DECSC / SCP).
+    /// Note: most terminals have a single save slot — nested saves are not supported.
+    /// </summary>
+    public static string SaveCursor => "\x1b[s";
+
+    /// <summary>
+    /// Restores the previously saved cursor position (DECRC / RCP).
+    /// </summary>
+    public static string RestoreCursor => "\x1b[u";
+
+    /// <summary>
+    /// Moves the cursor to the specified 1-based <paramref name="row"/> at column 1, then erases the entire line.
+    /// Convenience combination of <see cref="MoveCursor"/> and <see cref="EraseEntireLine"/>.
+    /// </summary>
+    public static string MoveAndEraseLine(int row) => $"\x1b[{row};1H\x1b[2K";
+
+    /// <summary>
+    /// Sets the foreground text color using a <see cref="ConsoleColor"/> value.
+    /// </summary>
+    public static string SetForegroundColor(ConsoleColor color) => $"\x1b[{ConsoleColorToAnsi(color)}m";
+
+    /// <summary>
+    /// Resets all text attributes (color, bold, etc.) to their defaults.
+    /// </summary>
+    public static string ResetAttributes => "\x1b[0m";
+
+    private static int ConsoleColorToAnsi(ConsoleColor color) => color switch
+    {
+        ConsoleColor.Black => 30,
+        ConsoleColor.DarkRed => 31,
+        ConsoleColor.DarkGreen => 32,
+        ConsoleColor.DarkYellow => 33,
+        ConsoleColor.DarkBlue => 34,
+        ConsoleColor.DarkMagenta => 35,
+        ConsoleColor.DarkCyan => 36,
+        ConsoleColor.Gray => 37,
+        ConsoleColor.DarkGray => 90,
+        ConsoleColor.Red => 91,
+        ConsoleColor.Green => 92,
+        ConsoleColor.Yellow => 93,
+        ConsoleColor.Blue => 94,
+        ConsoleColor.Magenta => 95,
+        ConsoleColor.Cyan => 96,
+        ConsoleColor.White => 97,
+        _ => 37
+    };
+}

dotnet/samples/02-agents/Harness/ConsoleReactiveComponents/ConsoleReactiveComponents.csproj

@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="../ConsoleReactiveFramework/ConsoleReactiveFramework.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/02-agents/Harness/ConsoleReactiveComponents/ListSelection.cs

@@ -0,0 +1,151 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Harness.ConsoleReactiveFramework;
+
+namespace Harness.ConsoleReactiveComponents;
+
+/// <summary>
+/// A component that renders a selectable list of items with a cursor indicator.
+/// The selected item is indicated with a "&gt;" prefix and rendered in the highlight color.
+/// Optionally includes a title above the list and a custom text input option at the bottom.
+/// </summary>
+public class ListSelection : ConsoleReactiveComponent<ListSelectionProps, ConsoleReactiveState>
+{
+    /// <summary>
+    /// Calculates the height (in rows) required to render the list,
+    /// including the optional title and custom text input row.
+    /// </summary>
+    /// <param name="props">The list selection props.</param>
+    /// <returns>The number of rows needed.</returns>
+    public static int CalculateHeight(ListSelectionProps props)
+    {
+        int height = props.Items.Count;
+        if (props.CustomTextPlaceholder != null)
+        {
+            height++;
+        }
+
+        height += GetTitleLineCount(props.Title);
+        return height;
+    }
+
+    /// <inheritdoc />
+    public override void RenderCore(ListSelectionProps props, ConsoleReactiveState state)
+    {
+        int row = 0;
+
+        // Render the title lines (if any)
+        if (props.Title is not null)
+        {
+            foreach (string line in props.Title.Split('\n'))
+            {
+                Console.Write(AnsiEscapes.MoveCursor(this.Y + row, this.X));
+                Console.Write(AnsiEscapes.EraseEntireLine);
+                Console.Write(line);
+                row++;
+            }
+        }
+
+        // Render the list items + optional custom text row
+        int totalItems = props.Items.Count + (props.CustomTextPlaceholder != null ? 1 : 0);
+
+        for (int i = 0; i < totalItems; i++)
+        {
+            Console.Write(AnsiEscapes.MoveCursor(this.Y + row, this.X));
+            Console.Write(AnsiEscapes.EraseEntireLine);
+
+            bool isSelected = i == props.SelectedIndex;
+            bool isCustomTextOption = props.CustomTextPlaceholder != null && i == props.Items.Count;
+
+            // Cursor indicator
+            Console.Write(isSelected ? "> " : "  ");
+
+            if (isCustomTextOption)
+            {
+                this.RenderCustomTextOption(props, isSelected);
+            }
+            else
+            {
+                if (isSelected)
+                {
+                    Console.Write(AnsiEscapes.SetForegroundColor(props.HighlightColor));
+                }
+
+                Console.Write(props.Items[i]);
+
+                if (isSelected)
+                {
+                    Console.Write(AnsiEscapes.ResetAttributes);
+                }
+            }
+
+            Console.WriteLine();
+            row++;
+        }
+    }
+
+    /// <summary>
+    /// Gets the number of lines the title occupies, or 0 if no title is set.
+    /// </summary>
+    private static int GetTitleLineCount(string? title) =>
+        title is null ? 0 : title.Split('\n').Length;
+
+    private void RenderCustomTextOption(ListSelectionProps props, bool isSelected)
+    {
+        if (props.CustomText.Length > 0)
+        {
+            // User has typed text — render in highlight color if selected
+            if (isSelected)
+            {
+                Console.Write(AnsiEscapes.SetForegroundColor(props.HighlightColor));
+            }
+
+            Console.Write(props.CustomText);
+
+            if (isSelected)
+            {
+                Console.Write(AnsiEscapes.ResetAttributes);
+            }
+        }
+        else if (!string.IsNullOrWhiteSpace(props.CustomTextPlaceholder))
+        {
+            // No text — show placeholder in dark grey (or highlight color if selected)
+            if (isSelected)
+            {
+                Console.Write(AnsiEscapes.SetForegroundColor(props.HighlightColor));
+            }
+            else
+            {
+                Console.Write(AnsiEscapes.SetForegroundColor(ConsoleColor.DarkGray));
+            }
+
+            Console.Write(" ");
+            Console.Write(props.CustomTextPlaceholder);
+            Console.Write(AnsiEscapes.ResetAttributes);
+        }
+    }
+}
+
+/// <summary>
+/// Props for <see cref="ListSelection"/>.
+/// </summary>
+public record ListSelectionProps : ConsoleReactiveProps
+{
+    /// <summary>Gets the title text displayed above the list items. May contain newlines for multi-line titles.</summary>
+    public string? Title { get; init; }
+
+    /// <summary>Gets the items to display in the list.</summary>
+    public IReadOnlyList<string> Items { get; init; } = Array.Empty<string>();
+
+    /// <summary>Gets the zero-based index of the currently selected item.</summary>
+    public int SelectedIndex { get; init; }
+
+    /// <summary>Gets the highlight color for the active item. Defaults to <see cref="ConsoleColor.Cyan"/>.</summary>
+    public ConsoleColor HighlightColor { get; init; } = ConsoleColor.Cyan;
+
+    /// <summary>Gets the placeholder text for the custom text input option. If <c>null</c>, no custom option is shown.</summary>
+    public string? CustomTextPlaceholder { get; init; }
+
+    /// <summary>Gets the text being typed into the custom text input option.</summary>
+    public string CustomText { get; init; } = "";
+}

dotnet/samples/02-agents/Harness/ConsoleReactiveComponents/TextInput.cs

@@ -0,0 +1,101 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Harness.ConsoleReactiveFramework;
+
+namespace Harness.ConsoleReactiveComponents;
+
+/// <summary>
+/// Props for <see cref="TextInput"/>.
+/// </summary>
+public record TextInputProps : ConsoleReactiveProps
+{
+    /// <summary>Gets the prompt string displayed on the left (e.g. "&gt; " or "user &gt; ").</summary>
+    public string Prompt { get; init; } = "> ";
+
+    /// <summary>Gets the text content to render to the right of the prompt.</summary>
+    public string Text { get; init; } = "";
+
+    /// <summary>Gets the placeholder text shown in dark grey when <see cref="Text"/> is empty.</summary>
+    public string Placeholder { get; init; } = "";
+}
+
+/// <summary>
+/// A component that renders a prompt with text input. Supports multi-line text
+/// where continuation lines are indented to align with the text start position
+/// (i.e. the column after the prompt).
+/// </summary>
+public class TextInput : ConsoleReactiveComponent<TextInputProps, ConsoleReactiveState>
+{
+    /// <summary>
+    /// Calculates the height (in rows) required to render the prompt and text
+    /// given the available width.
+    /// </summary>
+    /// <param name="props">The text input props.</param>
+    /// <param name="availableWidth">The total available width in columns.</param>
+    /// <returns>The number of rows needed.</returns>
+    public static int CalculateHeight(TextInputProps props, int availableWidth)
+    {
+        int promptLength = props.Prompt.Length;
+        int textWidth = availableWidth - promptLength;
+
+        if (textWidth <= 0 || props.Text.Length == 0)
+        {
+            return 1;
+        }
+
+        int lines = 1;
+        int remaining = props.Text.Length - textWidth;
+        while (remaining > 0)
+        {
+            lines++;
+            remaining -= textWidth;
+        }
+
+        return lines;
+    }
+
+    /// <inheritdoc />
+    public override void RenderCore(TextInputProps props, ConsoleReactiveState state)
+    {
+        int promptLength = props.Prompt.Length;
+        int textWidth = this.Width - promptLength;
+        string indent = new(' ', promptLength);
+
+        // First line: prompt + start of text
+        Console.Write(AnsiEscapes.MoveCursor(this.Y, this.X));
+        Console.Write(AnsiEscapes.EraseEntireLine);
+        Console.Write(props.Prompt);
+
+        if (textWidth <= 0 || props.Text.Length == 0)
+        {
+            // Show placeholder if text is empty
+            if (props.Text.Length == 0 && props.Placeholder.Length > 0 && textWidth > 0)
+            {
+                Console.Write(AnsiEscapes.SetForegroundColor(ConsoleColor.DarkGray));
+                Console.Write(" ");
+                Console.Write(props.Placeholder[..Math.Min(props.Placeholder.Length, textWidth - 1)]);
+                Console.Write(AnsiEscapes.ResetAttributes);
+            }
+
+            return;
+        }
+
+        int offset = 0;
+        int firstChunk = Math.Min(textWidth, props.Text.Length);
+        Console.Write(props.Text[offset..firstChunk]);
+        offset = firstChunk;
+
+        // Continuation lines: indented to align with text start
+        int row = 1;
+        while (offset < props.Text.Length)
+        {
+            int chunk = Math.Min(textWidth, props.Text.Length - offset);
+            Console.Write(AnsiEscapes.MoveCursor(this.Y + row, this.X));
+            Console.Write(AnsiEscapes.EraseEntireLine);
+            Console.Write(indent);
+            Console.Write(props.Text[offset..(offset + chunk)]);
+            offset += chunk;
+            row++;
+        }
+    }
+}

dotnet/samples/02-agents/Harness/ConsoleReactiveComponents/TextPanel.cs

@@ -0,0 +1,106 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Harness.ConsoleReactiveFramework;
+
+namespace Harness.ConsoleReactiveComponents;
+
+/// <summary>
+/// Props for <see cref="TextPanel"/>.
+/// </summary>
+public record TextPanelProps : ConsoleReactiveProps
+{
+    /// <summary>Gets the items to render in the panel.</summary>
+    public IReadOnlyList<object> Items { get; init; } = [];
+}
+
+/// <summary>
+/// A component that renders a list of items vertically using a custom render delegate.
+/// Designed for rendering dynamic items in a non-scroll region that may be
+/// re-rendered on each update. If the component's <see cref="ConsoleReactiveComponent.Height"/>
+/// exceeds the number of output lines, leftover lines are erased.
+/// </summary>
+public class TextPanel : ConsoleReactiveComponent<TextPanelProps, ConsoleReactiveState>
+{
+    private readonly Func<object, string> _renderItem;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="TextPanel"/> class.
+    /// </summary>
+    /// <param name="renderItem">A delegate that renders an item and returns the text to display (may contain newlines).</param>
+    public TextPanel(Func<object, string> renderItem)
+    {
+        this._renderItem = renderItem;
+    }
+
+    /// <summary>
+    /// Calculates the height (in lines) needed to render all items.
+    /// </summary>
+    /// <param name="items">The items to measure.</param>
+    /// <param name="renderItem">The render delegate to use for measuring.</param>
+    /// <returns>The total number of lines all items will occupy.</returns>
+    public static int CalculateHeight(IReadOnlyList<object> items, Func<object, string> renderItem)
+    {
+        int total = 0;
+        for (int i = 0; i < items.Count; i++)
+        {
+            string text = renderItem(items[i]);
+            total += CountLines(text);
+        }
+
+        return total;
+    }
+
+    /// <inheritdoc />
+    public override void RenderCore(TextPanelProps props, ConsoleReactiveState state)
+    {
+        int currentRow = 0;
+
+        for (int i = 0; i < props.Items.Count; i++)
+        {
+            string text = this._renderItem(props.Items[i]);
+            string[] lines = text.Split('\n');
+            int lineCount = CountLines(text);
+
+            for (int j = 0; j < lineCount; j++)
+            {
+                Console.Write(AnsiEscapes.MoveAndEraseLine(this.Y + currentRow));
+                Console.Write(lines[j]);
+                currentRow++;
+            }
+        }
+
+        // If the component height exceeds the output, erase leftover lines
+        if (this.Height > currentRow)
+        {
+            for (int i = currentRow; i < this.Height; i++)
+            {
+                Console.Write(AnsiEscapes.MoveAndEraseLine(this.Y + i));
+            }
+        }
+    }
+
+    private static int CountLines(string text)
+    {
+        if (string.IsNullOrEmpty(text))
+        {
+            return 0;
+        }
+
+        int count = 1;
+        for (int i = 0; i < text.Length; i++)
+        {
+            if (text[i] == '\n')
+            {
+                count++;
+            }
+        }
+
+        // If text ends with a newline, don't count the trailing empty line
+        if (text[text.Length - 1] == '\n')
+        {
+            count--;
+        }
+
+        return count;
+    }
+}

dotnet/samples/02-agents/Harness/ConsoleReactiveComponents/TextScrollPanel.cs

@@ -0,0 +1,70 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Harness.ConsoleReactiveFramework;
+
+namespace Harness.ConsoleReactiveComponents;
+
+/// <summary>
+/// Props for <see cref="TextScrollPanel"/>.
+/// </summary>
+public record TextScrollPanelProps : ConsoleReactiveProps
+{
+    /// <summary>Gets the items to render in the scroll panel.</summary>
+    public IReadOnlyList<object> Items { get; init; } = [];
+}
+
+/// <summary>
+/// State for <see cref="TextScrollPanel"/>.
+/// </summary>
+/// <param name="RenderedCount">The number of items already rendered.</param>
+public record TextScrollPanelState(int RenderedCount = 0) : ConsoleReactiveState;
+
+/// <summary>
+/// A component that renders items within a scroll area using a custom render delegate.
+/// All items are considered finalized — only new items since the last render are output.
+/// Use <see cref="Reset"/> to force a full re-render.
+/// </summary>
+public class TextScrollPanel : ConsoleReactiveComponent<TextScrollPanelProps, TextScrollPanelState>
+{
+    private readonly Func<object, string> _renderItem;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="TextScrollPanel"/> class.
+    /// </summary>
+    /// <param name="renderItem">A delegate that renders a single item and returns the text to display (may contain newlines).</param>
+    public TextScrollPanel(Func<object, string> renderItem)
+    {
+        this._renderItem = renderItem;
+        this.State = new TextScrollPanelState();
+    }
+
+    /// <summary>
+    /// Resets the panel so all items will be re-rendered on the next Render call.
+    /// </summary>
+    public void Reset()
+    {
+        this.State = new TextScrollPanelState();
+    }
+
+    /// <inheritdoc />
+    public override void RenderCore(TextScrollPanelProps props, TextScrollPanelState state)
+    {
+        if (props.Items.Count == 0)
+        {
+            return;
+        }
+
+        // Move cursor to the bottom of the scroll area
+        Console.Write(AnsiEscapes.MoveCursor(this.Y + this.Height - 1, this.X));
+
+        // Output only new items since last rendered
+        for (int i = state.RenderedCount; i < props.Items.Count; i++)
+        {
+            string text = this._renderItem(props.Items[i]);
+            Console.Write(text);
+        }
+
+        // Update state to track what we've rendered
+        this.State = new TextScrollPanelState(props.Items.Count);
+    }
+}

dotnet/samples/02-agents/Harness/ConsoleReactiveComponents/TopBottomRule.cs

@@ -0,0 +1,87 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Harness.ConsoleReactiveFramework;
+
+namespace Harness.ConsoleReactiveComponents;
+
+/// <summary>
+/// Props for <see cref="TopBottomRule"/>.
+/// </summary>
+public record TopBottomRuleProps : ConsoleReactiveProps
+{
+    /// <summary>Gets the width of the horizontal rules in characters.</summary>
+    public int Width { get; init; }
+
+    /// <summary>Gets the foreground color of the horizontal rules. If <c>null</c>, the default terminal color is used.</summary>
+    public ConsoleColor? Color { get; init; }
+}
+
+/// <summary>
+/// A component that renders a top and bottom horizontal rule (─) with children
+/// stacked vertically between them.
+/// </summary>
+public class TopBottomRule : ConsoleReactiveComponent<TopBottomRuleProps, ConsoleReactiveState>
+{
+    /// <summary>
+    /// Calculates the total height including the top rule, children, and bottom rule.
+    /// </summary>
+    /// <param name="props">The component props containing children.</param>
+    /// <returns>2 (for the rules) plus the sum of all children heights.</returns>
+    public static int CalculateHeight(TopBottomRuleProps props)
+    {
+        int childrenHeight = 0;
+        foreach (var child in props.Children)
+        {
+            childrenHeight += child.Height;
+        }
+
+        // Top rule + children + bottom rule
+        return 2 + childrenHeight;
+    }
+
+    /// <inheritdoc />
+    public override void RenderCore(TopBottomRuleProps props, ConsoleReactiveState state)
+    {
+        int ruleWidth = props.Width;
+        string rule = new('─', ruleWidth);
+
+        if (props.Color.HasValue)
+        {
+            Console.Write(AnsiEscapes.SetForegroundColor(props.Color.Value));
+        }
+
+        // Top rule
+        Console.Write(AnsiEscapes.MoveCursor(this.Y, this.X));
+        Console.Write(rule);
+
+        // Render children stacked below the top rule
+        int currentY = this.Y + 1;
+
+        if (props.Color.HasValue)
+        {
+            Console.Write(AnsiEscapes.ResetAttributes);
+        }
+
+        foreach (var child in props.Children)
+        {
+            child.X = this.X;
+            child.Y = currentY;
+            child.Render();
+            currentY += child.Height;
+        }
+
+        if (props.Color.HasValue)
+        {
+            Console.Write(AnsiEscapes.SetForegroundColor(props.Color.Value));
+        }
+
+        // Bottom rule
+        Console.Write(AnsiEscapes.MoveCursor(currentY, this.X));
+        Console.Write(rule);
+
+        if (props.Color.HasValue)
+        {
+            Console.Write(AnsiEscapes.ResetAttributes);
+        }
+    }
+}

dotnet/samples/02-agents/Harness/ConsoleReactiveFramework/ConsoleReactiveComponent.cs

@@ -0,0 +1,110 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Harness.ConsoleReactiveFramework;
+
+/// <summary>
+/// Abstract base class for all console UI components. Provides layout properties
+/// (position and size) and a <see cref="Render"/> method for drawing to the console.
+/// Derive from <see cref="ConsoleReactiveComponent{TProps, TState}"/> instead of this class directly.
+/// </summary>
+public abstract class ConsoleReactiveComponent
+{
+    internal ConsoleReactiveComponent()
+    {
+    }
+
+    /// <summary>Gets or sets the 1-based column position of the component.</summary>
+    public int X { get; set; }
+
+    /// <summary>Gets or sets the 1-based row position of the component.</summary>
+    public int Y { get; set; }
+
+    /// <summary>Gets or sets the width of the component in columns.</summary>
+    public int Width { get; set; }
+
+    /// <summary>Gets or sets the height of the component in rows.</summary>
+    public int Height { get; set; }
+
+    /// <summary>Renders the component to the console at its current position.</summary>
+    public abstract void Render();
+}
+
+/// <summary>
+/// Generic base class for console UI components with typed props and state.
+/// Props represent externally supplied configuration; state represents internal mutable data.
+/// </summary>
+/// <typeparam name="TProps">The type of the component's props (external configuration).</typeparam>
+/// <typeparam name="TState">The type of the component's internal state.</typeparam>
+public abstract class ConsoleReactiveComponent<TProps, TState> : ConsoleReactiveComponent
+    where TProps : ConsoleReactiveProps
+    where TState : ConsoleReactiveState
+{
+    private readonly object _renderLock = new();
+    private TProps? _lastRenderedProps;
+    private TState? _lastRenderedState;
+
+    /// <summary>Gets or sets the component's props (external configuration).</summary>
+    public TProps? Props { get; set; }
+
+    /// <summary>Gets or sets the component's internal state.</summary>
+    protected TState? State { get; set; }
+
+    /// <summary>
+    /// Updates the component's state and triggers a re-render.
+    /// </summary>
+    /// <param name="newState">The new state value.</param>
+    public void SetState(TState newState)
+    {
+        this.State = newState;
+        this.Render();
+    }
+
+    /// <summary>
+    /// Renders the component using the current props and state.
+    /// Uses a lock to prevent concurrent renders from multiple sources.
+    /// Skips rendering if neither props nor state have changed since the last render.
+    /// </summary>
+    public override void Render()
+    {
+        lock (this._renderLock)
+        {
+            if (this.Props is null)
+            {
+                return;
+            }
+
+            if (ReferenceEquals(this.Props, this._lastRenderedProps)
+                && ReferenceEquals(this.State, this._lastRenderedState))
+            {
+                return;
+            }
+
+            this.RenderCore(this.Props, this.State!);
+
+            this._lastRenderedProps = this.Props;
+            this._lastRenderedState = this.State;
+        }
+    }
+
+    /// <summary>
+    /// Called by <see cref="Render"/> to perform the actual rendering. Override this in derived classes.
+    /// </summary>
+    /// <param name="props">The current props.</param>
+    /// <param name="state">The current state.</param>
+    public abstract void RenderCore(TProps props, TState state);
+}
+
+/// <summary>
+/// Base record for component props. Provides an optional <see cref="Children"/> collection
+/// for composing child components.
+/// </summary>
+public record ConsoleReactiveProps
+{
+    /// <summary>Gets the child components to render within this component.</summary>
+    public IReadOnlyList<ConsoleReactiveComponent> Children { get; init; } = [];
+}
+
+/// <summary>
+/// Base record for component state.
+/// </summary>
+public record ConsoleReactiveState;

dotnet/samples/02-agents/Harness/ConsoleReactiveFramework/ConsoleReactiveFramework.csproj

@@ -0,0 +1,10 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+</Project>

dotnet/samples/02-agents/Harness/ConsoleReactiveFramework/ConsoleResizeListener.cs

@@ -0,0 +1,83 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Harness.ConsoleReactiveFramework;
+
+/// <summary>
+/// Event args for console resize events, containing the old and new dimensions.
+/// </summary>
+public class ConsoleResizeEventArgs : EventArgs
+{
+    /// <summary>Gets the previous console width.</summary>
+    public int OldWidth { get; }
+
+    /// <summary>Gets the previous console height.</summary>
+    public int OldHeight { get; }
+
+    /// <summary>Gets the new console width.</summary>
+    public int NewWidth { get; }
+
+    /// <summary>Gets the new console height.</summary>
+    public int NewHeight { get; }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ConsoleResizeEventArgs"/> class.
+    /// </summary>
+    /// <param name="oldWidth">The previous width.</param>
+    /// <param name="oldHeight">The previous height.</param>
+    /// <param name="newWidth">The new width.</param>
+    /// <param name="newHeight">The new height.</param>
+    public ConsoleResizeEventArgs(int oldWidth, int oldHeight, int newWidth, int newHeight)
+    {
+        this.OldWidth = oldWidth;
+        this.OldHeight = oldHeight;
+        this.NewWidth = newWidth;
+        this.NewHeight = newHeight;
+    }
+}
+
+/// <summary>
+/// Singleton that polls console dimensions every 16ms and raises the
+/// <see cref="ConsoleResized"/> event when the window size changes.
+/// </summary>
+public sealed class ConsoleResizeListener
+{
+#pragma warning disable IDE0052 // Remove unread private members
+    private readonly Task _task;
+#pragma warning restore IDE0052 // Remove unread private members
+
+    private int _lastWidth;
+    private int _lastHeight;
+
+    private ConsoleResizeListener()
+    {
+        this._lastWidth = Console.WindowWidth;
+        this._lastHeight = Console.WindowHeight;
+        this._task = this.ListenForResizeAsync();
+    }
+
+    /// <summary>Gets the singleton instance of <see cref="ConsoleResizeListener"/>.</summary>
+    public static ConsoleResizeListener Instance { get; } = new ConsoleResizeListener();
+
+    /// <summary>Raised when the console window is resized.</summary>
+    public event EventHandler<ConsoleResizeEventArgs>? ConsoleResized;
+
+    private async Task ListenForResizeAsync()
+    {
+        while (true)
+        {
+            int currentWidth = Console.WindowWidth;
+            int currentHeight = Console.WindowHeight;
+
+            if (currentWidth != this._lastWidth || currentHeight != this._lastHeight)
+            {
+                int oldWidth = this._lastWidth;
+                int oldHeight = this._lastHeight;
+                this._lastWidth = currentWidth;
+                this._lastHeight = currentHeight;
+                this.ConsoleResized?.Invoke(this, new ConsoleResizeEventArgs(oldWidth, oldHeight, currentWidth, currentHeight));
+            }
+
+            await Task.Delay(16);
+        }
+    }
+}

dotnet/samples/02-agents/Harness/ConsoleReactiveFramework/KeyEventListener.cs

@@ -0,0 +1,57 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Harness.ConsoleReactiveFramework;
+
+/// <summary>
+/// Event args for key press events, wrapping a <see cref="ConsoleKeyInfo"/>.
+/// </summary>
+public class KeyPressEventArgs : EventArgs
+{
+    /// <summary>Gets the key information for the pressed key.</summary>
+    public ConsoleKeyInfo KeyInfo { get; }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="KeyPressEventArgs"/> class.
+    /// </summary>
+    /// <param name="keyInfo">The key information.</param>
+    public KeyPressEventArgs(ConsoleKeyInfo keyInfo)
+    {
+        this.KeyInfo = keyInfo;
+    }
+}
+
+/// <summary>
+/// Singleton that polls for console key presses every 16ms and raises the
+/// <see cref="KeyPressed"/> event when a key is detected.
+/// </summary>
+public sealed class KeyEventListener
+{
+#pragma warning disable IDE0052 // Remove unread private members
+    private readonly Task _task;
+#pragma warning restore IDE0052 // Remove unread private members
+
+    private KeyEventListener()
+    {
+        this._task = this.ListenForKeyPressesAsync();
+    }
+
+    /// <summary>Gets the singleton instance of <see cref="KeyEventListener"/>.</summary>
+    public static KeyEventListener Instance { get; } = new KeyEventListener();
+
+    /// <summary>Raised when a key is pressed in the console.</summary>
+    public event EventHandler<KeyPressEventArgs>? KeyPressed;
+
+    private async Task ListenForKeyPressesAsync()
+    {
+        while (true)
+        {
+            while (Console.KeyAvailable)
+            {
+                var keyInfo = Console.ReadKey(intercept: true);
+                this.KeyPressed?.Invoke(this, new KeyPressEventArgs(keyInfo));
+            }
+
+            await Task.Delay(16);
+        }
+    }
+}

dotnet/samples/02-agents/Harness/Harness_ConsoleSandbox/AppComponent.cs

@@ -0,0 +1,315 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Harness.ConsoleReactiveComponents;
+using Harness.ConsoleReactiveFramework;
+
+namespace Harness.ConsoleSandbox;
+
+/// <summary>
+/// Determines which component is shown in the bottom panel.
+/// </summary>
+public enum BottomPanelMode
+{
+    /// <summary>Show the list selection component.</summary>
+    ListSelection,
+
+    /// <summary>Show the text input component.</summary>
+    TextInput
+}
+
+public record AppComponentProps : ConsoleReactiveProps
+{
+    public IReadOnlyList<string> Items { get; init; } = Array.Empty<string>();
+    public IReadOnlyList<object> ScrollItems { get; init; } = [];
+
+    /// <summary>Gets the bottom panel mode.</summary>
+    public BottomPanelMode Mode { get; init; } = BottomPanelMode.ListSelection;
+
+    /// <summary>Gets the prompt string for text input mode.</summary>
+    public string Prompt { get; init; } = "> ";
+
+    /// <summary>Gets the placeholder text shown when the input is empty.</summary>
+    public string Placeholder { get; init; } = "";
+
+    /// <summary>Gets the highlight color for the active list item. Defaults to <see cref="ConsoleColor.Cyan"/>.</summary>
+    public ConsoleColor ListHighlightColor { get; init; } = ConsoleColor.Cyan;
+
+    /// <summary>Gets the placeholder text for the custom text input option in the list. If <c>null</c>, no custom option is shown.</summary>
+    public string? ListCustomTextPlaceholder { get; init; }
+
+    /// <summary>Gets the foreground color for the rule borders. If <c>null</c>, uses the default terminal color.</summary>
+    public ConsoleColor? RuleColor { get; init; }
+}
+
+/// <summary>
+/// Internal state for the <see cref="AppComponent"/>.
+/// </summary>
+public record AppComponentState : ConsoleReactiveState
+{
+    /// <summary>Gets the selected index in list selection mode.</summary>
+    public int SelectedIndex { get; init; }
+
+    /// <summary>Gets the current input text being typed in text input mode.</summary>
+    public string InputText { get; init; } = "";
+
+    /// <summary>Gets the current text being typed into the list's custom text option.</summary>
+    public string ListInputText { get; init; } = "";
+}
+
+public class AppComponent : ConsoleReactiveComponent<AppComponentProps, AppComponentState>
+{
+    private readonly TopBottomRule _rule = new();
+    private readonly ListSelection _listSelection = new();
+    private readonly TextInput _textInput = new();
+    private readonly TextScrollPanel _textScrollPanel;
+    private readonly TextPanel _textPanel;
+    private readonly Func<object, string> _renderItem;
+    private readonly Action<string> _onTextInputSubmit;
+    private readonly Action<string> _onListInputSubmit;
+    private bool _resizedSinceLastRender;
+    private int _lastScrollBottom;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AppComponent"/> class.
+    /// </summary>
+    /// <param name="renderScrollItem">A delegate that renders a single scroll panel item and returns the text to display.</param>
+    /// <param name="onTextInputSubmit">A callback invoked with the input text when the user presses Enter in text input mode.</param>
+    /// <param name="onListInputSubmit">A callback invoked with the selected or typed text when the user presses Enter in list selection mode.</param>
+    public AppComponent(Func<object, string> renderScrollItem, Action<string> onTextInputSubmit, Action<string> onListInputSubmit)
+    {
+        this._renderItem = renderScrollItem;
+        this._onTextInputSubmit = onTextInputSubmit;
+        this._onListInputSubmit = onListInputSubmit;
+        this._textScrollPanel = new TextScrollPanel(renderScrollItem);
+        this._textPanel = new TextPanel(renderScrollItem);
+        this.State = new AppComponentState();
+        KeyEventListener.Instance.KeyPressed += this.OnKeyPressed;
+        ConsoleResizeListener.Instance.ConsoleResized += this.OnConsoleResized;
+    }
+
+    private void OnKeyPressed(object? sender, KeyPressEventArgs e)
+    {
+        if (this.Props!.Mode == BottomPanelMode.TextInput)
+        {
+            this.HandleTextInputKey(e);
+        }
+        else
+        {
+            this.HandleListSelectionKey(e);
+        }
+    }
+
+    private void HandleTextInputKey(KeyPressEventArgs e)
+    {
+        if (e.KeyInfo.Key == ConsoleKey.Enter)
+        {
+            string text = this.State!.InputText;
+            this.SetState(this.State with { InputText = "" });
+            this._onTextInputSubmit(text);
+        }
+        else if (e.KeyInfo.Key == ConsoleKey.Backspace)
+        {
+            if (this.State!.InputText.Length > 0)
+            {
+                this.SetState(this.State with { InputText = this.State.InputText[..^1] });
+            }
+        }
+        else if (e.KeyInfo.KeyChar != '\0' && !char.IsControl(e.KeyInfo.KeyChar))
+        {
+            this.SetState(this.State! with { InputText = this.State.InputText + e.KeyInfo.KeyChar });
+        }
+    }
+
+    private void HandleListSelectionKey(KeyPressEventArgs e)
+    {
+        int maxIndex = this.Props!.Items.Count - 1;
+        if (this.Props.ListCustomTextPlaceholder != null)
+        {
+            maxIndex = this.Props.Items.Count; // extra option at the end
+        }
+
+        bool isOnCustomTextOption = this.Props.ListCustomTextPlaceholder != null
+            && this.State!.SelectedIndex == this.Props.Items.Count;
+
+        if (e.KeyInfo.Key == ConsoleKey.UpArrow)
+        {
+            this.SetState(this.State! with { SelectedIndex = Math.Max(0, this.State.SelectedIndex - 1) });
+        }
+        else if (e.KeyInfo.Key == ConsoleKey.DownArrow)
+        {
+            this.SetState(this.State! with { SelectedIndex = Math.Min(maxIndex, this.State.SelectedIndex + 1) });
+        }
+        else if (e.KeyInfo.Key == ConsoleKey.Enter)
+        {
+            if (isOnCustomTextOption)
+            {
+                string text = this.State!.ListInputText;
+                this.SetState(this.State with { ListInputText = "" });
+                this._onListInputSubmit(text);
+            }
+            else
+            {
+                this._onListInputSubmit(this.Props.Items[this.State!.SelectedIndex]);
+            }
+        }
+        else if (isOnCustomTextOption)
+        {
+            // Typing only works when on the custom text option
+            if (e.KeyInfo.Key == ConsoleKey.Backspace)
+            {
+                if (this.State!.ListInputText.Length > 0)
+                {
+                    this.SetState(this.State with { ListInputText = this.State.ListInputText[..^1] });
+                }
+            }
+            else if (e.KeyInfo.KeyChar != '\0' && !char.IsControl(e.KeyInfo.KeyChar))
+            {
+                this.SetState(this.State! with { ListInputText = this.State.ListInputText + e.KeyInfo.KeyChar });
+            }
+        }
+    }
+
+    private void OnConsoleResized(object? sender, ConsoleResizeEventArgs e)
+    {
+        this._resizedSinceLastRender = true;
+        this.Render();
+    }
+
+    public override void RenderCore(AppComponentProps props, AppComponentState state)
+    {
+        // Determine the text panel height for the last scroll item
+        object? lastItem = props.ScrollItems.Count > 0 ? props.ScrollItems[^1] : null;
+        IReadOnlyList<object> lastItems = lastItem != null ? [lastItem] : [];
+        int textPanelHeight = TextPanel.CalculateHeight(lastItems, this._renderItem);
+        if (textPanelHeight > 0)
+        {
+            textPanelHeight++; // Extra line for spacing between text panel and rule
+        }
+
+        // Build the bottom panel child based on mode
+        ConsoleReactiveComponent bottomChild;
+        int bottomChildHeight;
+
+        if (props.Mode == BottomPanelMode.TextInput)
+        {
+            var textInputProps = new TextInputProps
+            {
+                Prompt = props.Prompt,
+                Text = state.InputText,
+                Placeholder = props.Placeholder
+            };
+
+            bottomChildHeight = TextInput.CalculateHeight(textInputProps, Console.WindowWidth);
+            this._textInput.Width = Console.WindowWidth;
+            this._textInput.Height = bottomChildHeight;
+            this._textInput.Props = textInputProps;
+            bottomChild = this._textInput;
+        }
+        else
+        {
+            var listProps = new ListSelectionProps
+            {
+                Items = props.Items,
+                SelectedIndex = state.SelectedIndex,
+                HighlightColor = props.ListHighlightColor,
+                CustomTextPlaceholder = props.ListCustomTextPlaceholder,
+                CustomText = state.ListInputText
+            };
+
+            bottomChildHeight = ListSelection.CalculateHeight(listProps);
+            this._listSelection.Height = bottomChildHeight;
+            this._listSelection.Props = listProps;
+            bottomChild = this._listSelection;
+        }
+
+        var ruleProps = new TopBottomRuleProps
+        {
+            Width = Console.WindowWidth,
+            Color = props.RuleColor,
+            Children = [bottomChild]
+        };
+
+        int ruleHeight = TopBottomRule.CalculateHeight(ruleProps);
+        int scrollBottom = Console.WindowHeight - ruleHeight - textPanelHeight;
+
+        // If scroll region changed or a clear is needed, reset everything
+        if (this._resizedSinceLastRender || (this._lastScrollBottom != 0 && scrollBottom != this._lastScrollBottom))
+        {
+            Console.Write(AnsiEscapes.EraseEntireScreen);
+            Console.Write(AnsiEscapes.EraseScrollbackBuffer);
+            this._textScrollPanel.Reset();
+            this._resizedSinceLastRender = false;
+        }
+
+        this._lastScrollBottom = scrollBottom;
+
+        Console.Write(AnsiEscapes.SetScrollRegion(scrollBottom));
+
+        // Render text scroll panel in the scroll area (all items except the last)
+        IReadOnlyList<object> scrollItems = props.ScrollItems.Count > 1
+            ? props.ScrollItems.Take(props.ScrollItems.Count - 1).ToList()
+            : [];
+
+        this._textScrollPanel.X = 1;
+        this._textScrollPanel.Y = 1;
+        this._textScrollPanel.Width = Console.WindowWidth;
+        this._textScrollPanel.Height = scrollBottom;
+        this._textScrollPanel.Props = new TextScrollPanelProps
+        {
+            Items = scrollItems
+        };
+        this._textScrollPanel.Render();
+
+        // Render the text panel for the last (dynamic) item just below the scroll region
+        this._textPanel.X = 1;
+        this._textPanel.Y = scrollBottom + 1;
+        this._textPanel.Width = Console.WindowWidth;
+        this._textPanel.Height = textPanelHeight;
+        this._textPanel.Props = new TextPanelProps
+        {
+            Items = lastItems,
+        };
+        this._textPanel.Render();
+
+        // Render the bottom rule + child below the text panel
+        this._rule.X = 1;
+        this._rule.Y = scrollBottom + textPanelHeight + 1;
+        this._rule.Props = ruleProps;
+        this._rule.Render();
+
+        // Position cursor for natural typing appearance
+        if (props.Mode == BottomPanelMode.TextInput)
+        {
+            int promptLength = props.Prompt.Length;
+            int textWidth = Console.WindowWidth - promptLength;
+            int textLength = state.InputText.Length;
+
+            // The TextInput starts at rule.Y + 1 (first row inside the rule)
+            int textInputY = this._rule.Y + 1;
+
+            if (textWidth <= 0 || textLength == 0)
+            {
+                // Cursor right after the prompt
+                Console.Write(AnsiEscapes.MoveCursor(textInputY, promptLength + 1));
+            }
+            else
+            {
+                // Calculate which row and column the cursor lands on
+                int cursorRow = textLength < textWidth ? 0 : 1 + ((textLength - textWidth) / textWidth);
+                int cursorCol = textLength < textWidth ? textLength : (textLength - textWidth) % textWidth;
+                Console.Write(AnsiEscapes.MoveCursor(textInputY + cursorRow, promptLength + cursorCol + 1));
+            }
+        }
+        else if (props.Mode == BottomPanelMode.ListSelection
+            && props.ListCustomTextPlaceholder != null
+            && state.SelectedIndex == props.Items.Count)
+        {
+            // Cursor after the typed text in the custom text option
+            // The custom text option is at rule.Y + 1 + Items.Count (0-based row inside rule)
+            int customOptionY = this._rule.Y + 1 + props.Items.Count;
+            // "> " prefix is 2 chars, then the typed text
+            int cursorCol = 2 + state.ListInputText.Length + 1;
+            Console.Write(AnsiEscapes.MoveCursor(customOptionY, cursorCol));
+        }
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Commands/CommandHandler.cs

@@ -0,0 +1,29 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+
+namespace Harness.Shared.Console.Commands;
+
+/// <summary>
+/// Base class for console command handlers (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 abstract class CommandHandler
+{
+    /// <summary>
+    /// Gets the help text for this command, displayed in the mode-and-help bar.
+    /// 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>
+    public abstract 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>
+    /// <param name="ux">The UX container for rendering output.</param>
+    /// <returns><see langword="true"/> if this handler handled the input; <see langword="false"/> otherwise.</returns>
+    public abstract ValueTask<bool> TryHandleAsync(string input, AgentSession session, HarnessUXContainer ux);
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Commands/ModeCommandHandler.cs

@@ -0,0 +1,66 @@
+// 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 : CommandHandler
+{
+    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 override string? GetHelpText() => this._modeProvider is not null ? "/mode [plan|execute] (show or switch mode)" : null;
+
+    /// <inheritdoc/>
+    public override async ValueTask<bool> TryHandleAsync(string input, AgentSession session, HarnessUXContainer ux)
+    {
+        if (!input.StartsWith("/mode ", StringComparison.OrdinalIgnoreCase) && !input.Equals("/mode", StringComparison.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        if (this._modeProvider is null)
+        {
+            await ux.WriteInfoLineAsync("AgentModeProvider is not available.").ConfigureAwait(false);
+            return true;
+        }
+
+        string[] parts = input.Split(' ', 2, StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+        if (parts.Length < 2)
+        {
+            string current = this._modeProvider.GetMode(session);
+            await ux.WriteInfoLineAsync($"Current mode: {current}").ConfigureAwait(false);
+            return true;
+        }
+
+        string newMode = parts[1];
+
+        try
+        {
+            this._modeProvider.SetMode(session, newMode);
+            ux.CurrentMode = newMode;
+            await ux.WriteInfoLineAsync($"Switched to {newMode} mode.", ModeColors.Get(newMode, this._modeColors)).ConfigureAwait(false);
+        }
+        catch (ArgumentException ex)
+        {
+            await ux.WriteInfoLineAsync(ex.Message, ConsoleColor.Red).ConfigureAwait(false);
+        }
+
+        return true;
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Commands/TodoCommandHandler.cs

@@ -0,0 +1,60 @@
+// 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 : CommandHandler
+{
+    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 override string? GetHelpText() => this._todoProvider is not null ? "/todos (show todo list)" : null;
+
+    /// <inheritdoc/>
+    public override async ValueTask<bool> TryHandleAsync(string input, AgentSession session, HarnessUXContainer ux)
+    {
+        if (!input.Equals("/todos", StringComparison.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        if (this._todoProvider is null)
+        {
+            await ux.WriteInfoLineAsync("TodoProvider is not available.").ConfigureAwait(false);
+            return true;
+        }
+
+        var todos = await this._todoProvider.GetAllTodosAsync(session).ConfigureAwait(false);
+        if (todos.Count == 0)
+        {
+            await ux.WriteInfoLineAsync("No todos yet.").ConfigureAwait(false);
+            return true;
+        }
+
+        await ux.WriteInfoLineAsync("── Todo List ──").ConfigureAwait(false);
+        foreach (var item in todos)
+        {
+            string status = item.IsComplete ? "✓" : "○";
+            ConsoleColor color = item.IsComplete ? ConsoleColor.DarkGray : ConsoleColor.White;
+            string description = string.IsNullOrWhiteSpace(item.Description)
+                ? string.Empty
+                : $" — {item.Description}";
+            await ux.WriteInfoLineAsync($"[{status}] #{item.Id} {item.Title}{description}", color).ConfigureAwait(false);
+        }
+
+        return true;
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Components/AgentModeAndHelp.cs

@@ -0,0 +1,71 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Harness.ConsoleReactiveComponents;
+using Harness.ConsoleReactiveFramework;
+
+namespace Harness.Shared.Console.Components;
+
+/// <summary>
+/// Props for <see cref="AgentModeAndHelp"/>.
+/// </summary>
+public record AgentModeAndHelpProps : ConsoleReactiveProps
+{
+    /// <summary>Gets or sets the current mode name (e.g. "plan", "execute"), or <see langword="null"/> if no mode is active.</summary>
+    public string? Mode { get; set; }
+
+    /// <summary>Gets or sets the foreground color for the mode label.</summary>
+    public ConsoleColor? ModeColor { get; set; }
+
+    /// <summary>Gets or sets the help text to display (e.g. available commands and exit info).</summary>
+    public string? HelpText { get; set; }
+}
+
+/// <summary>
+/// A component that renders a single fixed line below the bottom rule showing
+/// the current agent mode (in the mode colour) and available commands (in dark grey).
+/// </summary>
+public class AgentModeAndHelp : ConsoleReactiveComponent<AgentModeAndHelpProps, ConsoleReactiveState>
+{
+    /// <summary>
+    /// Calculates the height of the component.
+    /// </summary>
+    /// <param name="props">The component props.</param>
+    /// <returns>1 if there is content to display; otherwise 0.</returns>
+    public static int CalculateHeight(AgentModeAndHelpProps props) =>
+        (props.Mode is not null || !string.IsNullOrEmpty(props.HelpText)) ? 1 : 0;
+
+    /// <inheritdoc />
+    public override void RenderCore(AgentModeAndHelpProps props, ConsoleReactiveState state)
+    {
+        if (props.Mode is null && string.IsNullOrEmpty(props.HelpText))
+        {
+            return;
+        }
+
+        System.Console.Write(AnsiEscapes.SaveCursor);
+        System.Console.Write(AnsiEscapes.MoveAndEraseLine(this.Y));
+
+        bool hasMode = props.Mode is not null;
+
+        if (hasMode)
+        {
+            if (props.ModeColor.HasValue)
+            {
+                System.Console.Write(AnsiEscapes.SetForegroundColor(props.ModeColor.Value));
+            }
+
+            System.Console.Write($" [{props.Mode}]");
+            System.Console.Write(AnsiEscapes.ResetAttributes);
+        }
+
+        if (!string.IsNullOrEmpty(props.HelpText))
+        {
+            string prefix = hasMode ? "  " : " ";
+            System.Console.Write(AnsiEscapes.SetForegroundColor(ConsoleColor.DarkGray));
+            System.Console.Write($"{prefix}{props.HelpText}");
+            System.Console.Write(AnsiEscapes.ResetAttributes);
+        }
+
+        System.Console.Write(AnsiEscapes.RestoreCursor);
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Components/AgentStatus.cs

@@ -0,0 +1,120 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Harness.ConsoleReactiveComponents;
+using Harness.ConsoleReactiveFramework;
+
+namespace Harness.Shared.Console.Components;
+
+/// <summary>
+/// Props for <see cref="AgentStatus"/>.
+/// </summary>
+public record AgentStatusProps : ConsoleReactiveProps
+{
+    /// <summary>Gets or sets a value indicating whether the spinner is visible.</summary>
+    public bool ShowSpinner { get; set; }
+
+    /// <summary>Gets or sets the formatted token usage text to display.</summary>
+    public string? UsageText { get; set; }
+}
+
+/// <summary>
+/// State for <see cref="AgentStatus"/>.
+/// </summary>
+/// <param name="SpinnerIndex">The current spinner animation frame index.</param>
+public record AgentStatusState(int SpinnerIndex = 0) : ConsoleReactiveState;
+
+/// <summary>
+/// A component that renders a single-line agent status bar with an animated spinner
+/// and token usage statistics. Positioned above the rule in the non-scrolling area.
+/// </summary>
+public class AgentStatus : ConsoleReactiveComponent<AgentStatusProps, AgentStatusState>, IDisposable
+{
+    private static readonly string[] s_spinnerFrames =
+    [
+        "⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏",
+    ];
+
+    private readonly Timer _timer;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AgentStatus"/> class.
+    /// </summary>
+    public AgentStatus()
+    {
+        this.State = new AgentStatusState();
+        this._timer = new Timer(this.OnTimerTick, null, TimeSpan.Zero, TimeSpan.FromMilliseconds(100));
+    }
+
+    /// <summary>
+    /// Calculates the height of the agent status component.
+    /// </summary>
+    /// <param name="props">The component props.</param>
+    /// <returns>1 if the spinner or usage text is visible; otherwise 0.</returns>
+    public static int CalculateHeight(AgentStatusProps props)
+    {
+        return (props.ShowSpinner || !string.IsNullOrEmpty(props.UsageText)) ? 1 : 0;
+    }
+
+    /// <summary>
+    /// Disposes the internal spinner timer.
+    /// </summary>
+    public void Dispose()
+    {
+        this.Dispose(true);
+        GC.SuppressFinalize(this);
+    }
+
+    /// <summary>
+    /// Releases managed resources.
+    /// </summary>
+    /// <param name="disposing"><c>true</c> to release managed resources.</param>
+    protected virtual void Dispose(bool disposing)
+    {
+        if (disposing)
+        {
+            this._timer.Dispose();
+        }
+    }
+
+    /// <inheritdoc />
+    public override void RenderCore(AgentStatusProps props, AgentStatusState state)
+    {
+        if (!props.ShowSpinner && string.IsNullOrEmpty(props.UsageText))
+        {
+            return;
+        }
+
+        System.Console.Write(AnsiEscapes.SaveCursor);
+        System.Console.Write(AnsiEscapes.MoveAndEraseLine(this.Y));
+
+        if (props.ShowSpinner)
+        {
+            string frame = s_spinnerFrames[state.SpinnerIndex];
+            System.Console.Write(AnsiEscapes.SetForegroundColor(ConsoleColor.Cyan));
+            System.Console.Write($" {frame} ");
+            System.Console.Write(AnsiEscapes.ResetAttributes);
+        }
+        else
+        {
+            System.Console.Write("   ");
+        }
+
+        if (!string.IsNullOrEmpty(props.UsageText))
+        {
+            System.Console.Write(AnsiEscapes.SetForegroundColor(ConsoleColor.DarkGray));
+            System.Console.Write(props.UsageText);
+            System.Console.Write(AnsiEscapes.ResetAttributes);
+        }
+
+        System.Console.Write(AnsiEscapes.RestoreCursor);
+    }
+
+    private void OnTimerTick(object? timerState)
+    {
+        if (this.Props is { ShowSpinner: true })
+        {
+            int nextIndex = ((this.State?.SpinnerIndex ?? 0) + 1) % s_spinnerFrames.Length;
+            this.SetState(new AgentStatusState(nextIndex));
+        }
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/HarnessAppComponent.cs

@@ -0,0 +1,553 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Harness.ConsoleReactiveComponents;
+using Harness.ConsoleReactiveFramework;
+using Harness.Shared.Console.Components;
+
+namespace Harness.Shared.Console;
+
+/// <summary>
+/// Determines which component is shown in the bottom panel.
+/// </summary>
+public enum BottomPanelMode
+{
+    /// <summary>Show the text input component for user input.</summary>
+    TextInput,
+
+    /// <summary>Show the list selection component for interactive prompts.</summary>
+    ListSelection,
+
+    /// <summary>Show a disabled input indicator during agent streaming.</summary>
+    Streaming,
+}
+
+/// <summary>
+/// Event arguments for the <see cref="HarnessAppComponent.InputSubmitted"/> event.
+/// </summary>
+public sealed class InputSubmittedEventArgs : EventArgs
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="InputSubmittedEventArgs"/> class.
+    /// </summary>
+    /// <param name="text">The submitted text.</param>
+    /// <param name="mode">The bottom panel mode in which the input was submitted.</param>
+    public InputSubmittedEventArgs(string text, BottomPanelMode mode)
+    {
+        this.Text = text;
+        this.Mode = mode;
+    }
+
+    /// <summary>Gets the submitted text.</summary>
+    public string Text { get; }
+
+    /// <summary>Gets the bottom panel mode in which the input was submitted.</summary>
+    public BottomPanelMode Mode { get; }
+}
+
+/// <summary>
+/// Props for <see cref="HarnessAppComponent"/>.
+/// </summary>
+public record HarnessAppComponentProps : ConsoleReactiveProps
+{
+    /// <summary>Gets or sets the list selection choices (for ListSelection mode).</summary>
+    public IReadOnlyList<string> Items { get; set; } = Array.Empty<string>();
+
+    /// <summary>Gets or sets the scroll items (output entries) to render in the scroll panel.</summary>
+    public IReadOnlyList<object> ScrollItems { get; set; } = [];
+
+    /// <summary>Gets or sets the bottom panel mode.</summary>
+    public BottomPanelMode Mode { get; set; } = BottomPanelMode.TextInput;
+
+    /// <summary>Gets or sets the prompt string for text input mode.</summary>
+    public string Prompt { get; set; } = "You: ";
+
+    /// <summary>Gets or sets the placeholder text shown when the input is empty.</summary>
+    public string Placeholder { get; set; } = "";
+
+    /// <summary>Gets or sets the highlight color for the active list item.</summary>
+    public ConsoleColor ListHighlightColor { get; set; } = ConsoleColor.Cyan;
+
+    /// <summary>Gets or sets the placeholder text for the custom text input option in the list.</summary>
+    public string? ListCustomTextPlaceholder { get; set; }
+
+    /// <summary>Gets or sets the foreground color for the rule borders and mode label.</summary>
+    public ConsoleColor? ModeColor { get; set; }
+
+    /// <summary>Gets or sets the current mode name displayed below the bottom rule (e.g. "plan").</summary>
+    public string? ModeText { get; set; }
+
+    /// <summary>Gets or sets the help text displayed below the bottom rule (available commands).</summary>
+    public string? HelpText { get; set; }
+
+    /// <summary>Gets or sets the title text displayed above the list selection (for interactive prompts).</summary>
+    public string? ListTitle { get; set; }
+
+    /// <summary>Gets or sets a value indicating whether input is enabled during streaming.</summary>
+    public bool InputEnabled { get; set; }
+
+    /// <summary>Gets or sets the prompt to show during streaming when input is disabled.</summary>
+    public string StreamingPrompt { get; set; } = "(agent is running...)";
+
+    /// <summary>Gets or sets a value indicating whether the agent status spinner is visible.</summary>
+    public bool ShowSpinner { get; set; }
+
+    /// <summary>Gets or sets the formatted token usage text to display in the status bar.</summary>
+    public string? UsageText { get; set; }
+
+    /// <summary>Gets or sets the queued input items to display above the rule.</summary>
+    public IReadOnlyList<object> QueuedItems { get; set; } = [];
+}
+
+/// <summary>
+/// Internal state for <see cref="HarnessAppComponent"/>.
+/// </summary>
+public record HarnessAppComponentState : ConsoleReactiveState
+{
+    /// <summary>Gets the selected index in list selection mode.</summary>
+    public int SelectedIndex { get; init; }
+
+    /// <summary>Gets the current input text being typed.</summary>
+    public string InputText { get; init; } = "";
+
+    /// <summary>Gets the current text being typed into the list's custom text option.</summary>
+    public string ListInputText { get; init; } = "";
+
+    /// <summary>Gets the current console width in columns.</summary>
+    public int ConsoleWidth { get; init; }
+
+    /// <summary>Gets the current console height in rows.</summary>
+    public int ConsoleHeight { get; init; }
+}
+
+/// <summary>
+/// The main application component for the Harness console. Manages the scroll region
+/// and bottom panel (text input, list selection, or streaming indicator), and emits
+/// an <see cref="InputSubmitted"/> event when the user submits text in any mode.
+/// </summary>
+public class HarnessAppComponent : ConsoleReactiveComponent<HarnessAppComponentProps, HarnessAppComponentState>, IDisposable
+{
+    private readonly TopBottomRule _rule = new();
+    private readonly ListSelection _listSelection = new();
+    private readonly TextInput _textInput = new();
+    private readonly TextScrollPanel _textScrollPanel;
+    private readonly TextPanel _textPanel;
+    private readonly TextPanel _queuedPanel;
+    private readonly AgentStatus _agentStatus = new();
+    private readonly AgentModeAndHelp _modeAndHelp = new();
+    private readonly Func<object, string> _renderItem;
+    private bool _resizedSinceLastRender;
+    private bool _deactivated;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="HarnessAppComponent"/> class.
+    /// </summary>
+    /// <param name="renderScrollItem">A delegate that renders a single output entry and returns the text to display.</param>
+    public HarnessAppComponent(Func<object, string> renderScrollItem)
+    {
+        this._renderItem = renderScrollItem;
+        this._textScrollPanel = new TextScrollPanel(renderScrollItem);
+        this._textPanel = new TextPanel(renderScrollItem);
+        this._queuedPanel = new TextPanel(renderScrollItem);
+        this.State = new HarnessAppComponentState
+        {
+            ConsoleWidth = System.Console.WindowWidth,
+            ConsoleHeight = System.Console.WindowHeight,
+        };
+        KeyEventListener.Instance.KeyPressed += this.OnKeyPressed;
+        ConsoleResizeListener.Instance.ConsoleResized += this.OnConsoleResized;
+    }
+
+    /// <summary>
+    /// Gets the 1-based row number of the last row in the output scroll region.
+    /// </summary>
+    public int ScrollRegionBottom { get; private set; }
+
+    /// <summary>
+    /// Occurs when the user submits input via Enter, in any mode (text input, list selection,
+    /// or streaming injection). Consumers inspect <see cref="InputSubmittedEventArgs.Mode"/>
+    /// to decide how to handle the submission.
+    /// </summary>
+    public event EventHandler<InputSubmittedEventArgs>? InputSubmitted;
+
+    /// <summary>
+    /// Deactivates the component, resetting the scroll region and unsubscribing from events.
+    /// This method is idempotent and safe to call multiple times.
+    /// </summary>
+    public void Deactivate()
+    {
+        if (this._deactivated)
+        {
+            return;
+        }
+
+        this._deactivated = true;
+        this._agentStatus.Dispose();
+        KeyEventListener.Instance.KeyPressed -= this.OnKeyPressed;
+        ConsoleResizeListener.Instance.ConsoleResized -= this.OnConsoleResized;
+        System.Console.Write(AnsiEscapes.ResetScrollRegion);
+        System.Console.Write(AnsiEscapes.MoveCursor(System.Console.WindowHeight, 1));
+        System.Console.WriteLine();
+    }
+
+    /// <inheritdoc/>
+    public void Dispose()
+    {
+        this.Dispose(true);
+        GC.SuppressFinalize(this);
+    }
+
+    /// <summary>
+    /// Releases managed resources.
+    /// </summary>
+    /// <param name="disposing"><c>true</c> to release managed resources.</param>
+    protected virtual void Dispose(bool disposing)
+    {
+        if (disposing)
+        {
+            this.Deactivate();
+        }
+    }
+
+    private void OnKeyPressed(object? sender, KeyPressEventArgs e)
+    {
+        if (this.Props!.Mode == BottomPanelMode.TextInput)
+        {
+            this.HandleTextInputKey(e);
+        }
+        else if (this.Props.Mode == BottomPanelMode.ListSelection)
+        {
+            this.HandleListSelectionKey(e);
+        }
+        else if (this.Props.Mode == BottomPanelMode.Streaming && this.Props.InputEnabled)
+        {
+            this.HandleStreamingInputKey(e);
+        }
+    }
+
+    private void HandleTextInputKey(KeyPressEventArgs e)
+    {
+        if (e.KeyInfo.Key == ConsoleKey.Enter)
+        {
+            string text = this.State!.InputText;
+            if (string.IsNullOrWhiteSpace(text))
+            {
+                return;
+            }
+
+            this.SetState(this.State with { InputText = "" });
+            this.InputSubmitted?.Invoke(this, new InputSubmittedEventArgs(text, BottomPanelMode.TextInput));
+        }
+        else if (e.KeyInfo.Key == ConsoleKey.Backspace)
+        {
+            if (this.State!.InputText.Length > 0)
+            {
+                this.SetState(this.State with { InputText = this.State.InputText[..^1] });
+            }
+        }
+        else if (e.KeyInfo.KeyChar != '\0' && !char.IsControl(e.KeyInfo.KeyChar))
+        {
+            this.SetState(this.State! with { InputText = this.State.InputText + e.KeyInfo.KeyChar });
+        }
+    }
+
+    private void HandleListSelectionKey(KeyPressEventArgs e)
+    {
+        int maxIndex = this.Props!.Items.Count - 1;
+        if (this.Props.ListCustomTextPlaceholder != null)
+        {
+            maxIndex = this.Props.Items.Count;
+        }
+
+        bool isOnCustomTextOption = this.Props.ListCustomTextPlaceholder != null
+            && this.State!.SelectedIndex == this.Props.Items.Count;
+
+        if (e.KeyInfo.Key == ConsoleKey.UpArrow)
+        {
+            this.SetState(this.State! with { SelectedIndex = Math.Max(0, this.State.SelectedIndex - 1) });
+        }
+        else if (e.KeyInfo.Key == ConsoleKey.DownArrow)
+        {
+            this.SetState(this.State! with { SelectedIndex = Math.Min(maxIndex, this.State.SelectedIndex + 1) });
+        }
+        else if (e.KeyInfo.Key == ConsoleKey.Enter)
+        {
+            string result = isOnCustomTextOption
+                ? this.State!.ListInputText
+                : this.Props.Items[this.State!.SelectedIndex];
+
+            this.SetState(this.State with { ListInputText = "", SelectedIndex = 0 });
+            this.InputSubmitted?.Invoke(this, new InputSubmittedEventArgs(result, BottomPanelMode.ListSelection));
+        }
+        else if (isOnCustomTextOption)
+        {
+            if (e.KeyInfo.Key == ConsoleKey.Backspace)
+            {
+                if (this.State!.ListInputText.Length > 0)
+                {
+                    this.SetState(this.State with { ListInputText = this.State.ListInputText[..^1] });
+                }
+            }
+            else if (e.KeyInfo.KeyChar != '\0' && !char.IsControl(e.KeyInfo.KeyChar))
+            {
+                this.SetState(this.State! with { ListInputText = this.State.ListInputText + e.KeyInfo.KeyChar });
+            }
+        }
+    }
+
+    private void HandleStreamingInputKey(KeyPressEventArgs e)
+    {
+        // During streaming with input enabled, capture text for message injection
+        if (e.KeyInfo.Key == ConsoleKey.Enter)
+        {
+            string text = this.State!.InputText;
+            if (string.IsNullOrWhiteSpace(text))
+            {
+                return;
+            }
+
+            this.SetState(this.State with { InputText = "" });
+            this.InputSubmitted?.Invoke(this, new InputSubmittedEventArgs(text, BottomPanelMode.Streaming));
+        }
+        else if (e.KeyInfo.Key == ConsoleKey.Backspace)
+        {
+            if (this.State!.InputText.Length > 0)
+            {
+                this.SetState(this.State with { InputText = this.State.InputText[..^1] });
+            }
+        }
+        else if (e.KeyInfo.KeyChar != '\0' && !char.IsControl(e.KeyInfo.KeyChar))
+        {
+            this.SetState(this.State! with { InputText = this.State.InputText + e.KeyInfo.KeyChar });
+        }
+    }
+
+    private void OnConsoleResized(object? sender, ConsoleResizeEventArgs e)
+    {
+        this._resizedSinceLastRender = true;
+        this.SetState(this.State! with
+        {
+            ConsoleWidth = e.NewWidth,
+            ConsoleHeight = e.NewHeight,
+        });
+    }
+
+    /// <inheritdoc />
+    public override void RenderCore(HarnessAppComponentProps props, HarnessAppComponentState state)
+    {
+        // Determine the text panel height for the last scroll item
+        IReadOnlyList<object> lastItems = props.ScrollItems.Count > 0
+            ? [props.ScrollItems[^1]]
+            : [];
+        int textPanelHeight = TextPanel.CalculateHeight(lastItems, this._renderItem);
+        if (textPanelHeight > 0)
+        {
+            textPanelHeight++; // Extra line for spacing between text panel and rule
+        }
+
+        // Calculate queued items panel height
+        int queuedPanelHeight = TextPanel.CalculateHeight(props.QueuedItems, this._renderItem);
+
+        // Build the bottom panel child based on mode
+        ConsoleReactiveComponent bottomChild;
+        int bottomChildHeight;
+
+        if (props.Mode == BottomPanelMode.ListSelection)
+        {
+            var listProps = new ListSelectionProps
+            {
+                Title = props.ListTitle,
+                Items = props.Items,
+                SelectedIndex = state.SelectedIndex,
+                HighlightColor = props.ListHighlightColor,
+                CustomTextPlaceholder = props.ListCustomTextPlaceholder,
+                CustomText = state.ListInputText,
+            };
+
+            bottomChildHeight = ListSelection.CalculateHeight(listProps);
+            this._listSelection.Height = bottomChildHeight;
+            this._listSelection.Props = listProps;
+            bottomChild = this._listSelection;
+        }
+        else if (props.Mode == BottomPanelMode.Streaming)
+        {
+            TextInputProps textInputProps;
+            if (props.InputEnabled)
+            {
+                textInputProps = new TextInputProps
+                {
+                    Prompt = props.Prompt,
+                    Text = state.InputText,
+                    Placeholder = props.Placeholder,
+                };
+            }
+            else
+            {
+                textInputProps = new TextInputProps
+                {
+                    Prompt = props.Prompt,
+                    Text = "",
+                    Placeholder = props.StreamingPrompt,
+                };
+            }
+
+            bottomChildHeight = TextInput.CalculateHeight(textInputProps, state.ConsoleWidth);
+            this._textInput.Width = state.ConsoleWidth;
+            this._textInput.Height = bottomChildHeight;
+            this._textInput.Props = textInputProps;
+            bottomChild = this._textInput;
+        }
+        else
+        {
+            var textInputProps = new TextInputProps
+            {
+                Prompt = props.Prompt,
+                Text = state.InputText,
+                Placeholder = props.Placeholder,
+            };
+
+            bottomChildHeight = TextInput.CalculateHeight(textInputProps, state.ConsoleWidth);
+            this._textInput.Width = state.ConsoleWidth;
+            this._textInput.Height = bottomChildHeight;
+            this._textInput.Props = textInputProps;
+            bottomChild = this._textInput;
+        }
+
+        var ruleProps = new TopBottomRuleProps
+        {
+            Width = state.ConsoleWidth,
+            Color = props.ModeColor,
+            Children = [bottomChild],
+        };
+
+        // Calculate the agent status height
+        var agentStatusProps = new AgentStatusProps
+        {
+            ShowSpinner = props.ShowSpinner,
+            UsageText = props.UsageText,
+        };
+        int agentStatusHeight = AgentStatus.CalculateHeight(agentStatusProps);
+
+        // Calculate the mode-and-help height
+        var modeAndHelpProps = new AgentModeAndHelpProps
+        {
+            Mode = props.ModeText,
+            ModeColor = props.ModeColor,
+            HelpText = props.HelpText,
+        };
+        int modeAndHelpHeight = AgentModeAndHelp.CalculateHeight(modeAndHelpProps);
+
+        int ruleHeight = TopBottomRule.CalculateHeight(ruleProps);
+        int scrollBottom = Math.Max(1, state.ConsoleHeight - ruleHeight - textPanelHeight - agentStatusHeight - queuedPanelHeight - modeAndHelpHeight);
+
+        // If scroll region changed or a clear is needed, reset everything
+        if (this._resizedSinceLastRender || (this.ScrollRegionBottom != 0 && scrollBottom != this.ScrollRegionBottom))
+        {
+            System.Console.Write(AnsiEscapes.EraseEntireScreen);
+            System.Console.Write(AnsiEscapes.EraseScrollbackBuffer);
+            this._textScrollPanel.Reset();
+            this._resizedSinceLastRender = false;
+        }
+
+        this.ScrollRegionBottom = scrollBottom;
+
+        System.Console.Write(AnsiEscapes.SetScrollRegion(scrollBottom));
+
+        // Render text scroll panel in the scroll area (all items except the last)
+        IReadOnlyList<object> scrollItems = props.ScrollItems.Count > 1
+            ? props.ScrollItems.Take(props.ScrollItems.Count - 1).ToList()
+            : [];
+
+        this._textScrollPanel.X = 1;
+        this._textScrollPanel.Y = 1;
+        this._textScrollPanel.Width = state.ConsoleWidth;
+        this._textScrollPanel.Height = scrollBottom;
+        this._textScrollPanel.Props = new TextScrollPanelProps
+        {
+            Items = scrollItems,
+        };
+        this._textScrollPanel.Render();
+
+        // Render the text panel for the last (dynamic) item just below the scroll region
+        this._textPanel.X = 1;
+        this._textPanel.Y = scrollBottom + 1;
+        this._textPanel.Width = state.ConsoleWidth;
+        this._textPanel.Height = textPanelHeight;
+        this._textPanel.Props = new TextPanelProps
+        {
+            Items = lastItems,
+        };
+        this._textPanel.Render();
+
+        // Render queued input items between text panel and agent status
+        int queuedPanelY = scrollBottom + textPanelHeight + 1;
+        this._queuedPanel.X = 1;
+        this._queuedPanel.Y = queuedPanelY;
+        this._queuedPanel.Width = state.ConsoleWidth;
+        this._queuedPanel.Height = queuedPanelHeight;
+        this._queuedPanel.Props = new TextPanelProps
+        {
+            Items = props.QueuedItems,
+        };
+        this._queuedPanel.Render();
+
+        // Render the agent status line between queued items and rule
+        int agentStatusY = queuedPanelY + queuedPanelHeight;
+        this._agentStatus.X = 1;
+        this._agentStatus.Y = agentStatusY;
+        this._agentStatus.Width = state.ConsoleWidth;
+        this._agentStatus.Height = agentStatusHeight;
+        this._agentStatus.Props = agentStatusProps;
+        this._agentStatus.Render();
+
+        // Render the bottom rule + child below the agent status
+        this._rule.X = 1;
+        this._rule.Y = agentStatusY + agentStatusHeight;
+        this._rule.Props = ruleProps;
+        this._rule.Render();
+
+        // Render the mode-and-help line below the bottom rule
+        int modeAndHelpY = this._rule.Y + ruleHeight;
+        this._modeAndHelp.X = 1;
+        this._modeAndHelp.Y = modeAndHelpY;
+        this._modeAndHelp.Width = state.ConsoleWidth;
+        this._modeAndHelp.Height = modeAndHelpHeight;
+        this._modeAndHelp.Props = modeAndHelpProps;
+        this._modeAndHelp.Render();
+
+        // Position cursor for natural typing appearance
+        this.PositionCursor(props, state);
+    }
+
+    private void PositionCursor(HarnessAppComponentProps props, HarnessAppComponentState state)
+    {
+        if (props.Mode == BottomPanelMode.TextInput
+            || (props.Mode == BottomPanelMode.Streaming && props.InputEnabled))
+        {
+            int promptLength = props.Prompt.Length;
+            int textWidth = state.ConsoleWidth - promptLength;
+            int textLength = state.InputText.Length;
+
+            int textInputY = this._rule.Y + 1;
+
+            if (textWidth <= 0 || textLength == 0)
+            {
+                System.Console.Write(AnsiEscapes.MoveCursor(textInputY, promptLength + 1));
+            }
+            else
+            {
+                int cursorRow = textLength < textWidth ? 0 : 1 + ((textLength - textWidth) / textWidth);
+                int cursorCol = textLength < textWidth ? textLength : (textLength - textWidth) % textWidth;
+                System.Console.Write(AnsiEscapes.MoveCursor(textInputY + cursorRow, promptLength + cursorCol + 1));
+            }
+        }
+        else if (props.Mode == BottomPanelMode.ListSelection
+            && props.ListCustomTextPlaceholder != null
+            && state.SelectedIndex == props.Items.Count)
+        {
+            int titleLines = props.ListTitle?.Split('\n').Length ?? 0;
+            int customOptionY = this._rule.Y + 1 + titleLines + props.Items.Count;
+            int cursorCol = 2 + state.ListInputText.Length + 1;
+            System.Console.Write(AnsiEscapes.MoveCursor(customOptionY, cursorCol));
+        }
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/HarnessConsole.cs

@@ -0,0 +1,258 @@
+// 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));
+        }
+
+        var todoProvider = agent.GetService<TodoProvider>();
+        var modeProvider = agent.GetService<AgentModeProvider>();
+        var messageInjector = agent.GetService<MessageInjectingChatClient>();
+
+        var commandHandlers = new List<CommandHandler>
+        {
+            new TodoCommandHandler(todoProvider),
+            new ModeCommandHandler(modeProvider, options.ModeColors),
+        };
+
+        AgentSession session = await agent.CreateSessionAsync();
+
+        using var ux = new HarnessUXContainer(
+            placeholder: userPrompt,
+            initialMode: modeProvider?.GetMode(session),
+            inputEnabled: messageInjector is not null,
+            modeColors: options.ModeColors);
+
+        // Streaming-mode submissions are enqueued for injection; the queued display
+        // is then refreshed from the injector's current pending list.
+        ux.StreamingInputReceived += (sender, e) =>
+        {
+            if (messageInjector is null)
+            {
+                return;
+            }
+
+            messageInjector.EnqueueMessages(session, [new ChatMessage(ChatRole.User, e.Text)]);
+            ux.ShowQueuedMessages(messageInjector.GetPendingMessages(session));
+        };
+
+        var commandHelp = commandHandlers
+            .Select(h => h.GetHelpText())
+            .Where(t => t is not null)
+            .Append("exit (quit)")!;
+
+        ux.Initialize(title, commandHelp!, messageInjector is not null);
+
+        string userInput = await ux.WaitForInputAsync();
+
+        while (!string.IsNullOrWhiteSpace(userInput) && !userInput.Equals("exit", StringComparison.OrdinalIgnoreCase))
+        {
+            ux.WriteUserInputEcho(userInput);
+
+            // Check command handlers first — first one to handle wins.
+            bool handled = false;
+            foreach (var handler in commandHandlers)
+            {
+                if (await handler.TryHandleAsync(userInput, session, ux).ConfigureAwait(false))
+                {
+                    handled = true;
+                    break;
+                }
+            }
+
+            if (!handled)
+            {
+                await RunAgentTurnAsync(agent, session, modeProvider, messageInjector, options, ux, userInput);
+            }
+
+            ux.CurrentMode = modeProvider?.GetMode(session);
+            userInput = await ux.WaitForInputAsync();
+        }
+
+        ux.Deactivate();
+        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,
+        MessageInjectingChatClient? messageInjector,
+        HarnessConsoleOptions options,
+        HarnessUXContainer ux,
+        string userInput)
+    {
+        IList<ChatMessage>? nextMessages = [new ChatMessage(ChatRole.User, userInput)];
+        IReadOnlyList<ChatMessage> lastPendingMessages = messageInjector?.GetPendingMessages(session) ?? [];
+
+        while (nextMessages is not null)
+        {
+            var observers = CreateObservers(options, modeProvider, session);
+
+            var runOptions = new AgentRunOptions();
+            foreach (var observer in observers)
+            {
+                observer.ConfigureRunOptions(runOptions);
+            }
+
+            ux.CurrentMode = modeProvider?.GetMode(session);
+            ux.BeginStreaming();
+            ux.BeginStreamingOutput();
+
+            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 != ux.CurrentMode)
+                        {
+                            ux.CurrentMode = currentMode;
+                        }
+                    }
+
+                    foreach (var content in update.Contents)
+                    {
+                        foreach (var observer in observers)
+                        {
+                            await observer.OnContentAsync(ux, content);
+                        }
+                    }
+
+                    if (!string.IsNullOrEmpty(update.Text))
+                    {
+                        foreach (var observer in observers)
+                        {
+                            await observer.OnTextAsync(ux, update.Text);
+                        }
+                    }
+
+                    SyncQueuedMessageDisplay(messageInjector, session, ux, ref lastPendingMessages);
+                }
+            }
+            catch (Exception ex)
+            {
+                await ux.WriteInfoLineAsync($"❌ Stream error: {ex.GetType().Name}:\n{ex}", ConsoleColor.Red);
+            }
+
+            // Final sync after streaming — messages may have been consumed during the last iteration.
+            SyncQueuedMessageDisplay(messageInjector, session, ux, ref lastPendingMessages);
+
+            // Stop spinner before observer completions (which may prompt for input).
+            ux.StopSpinner();
+
+            // Close the streaming output to provide visual separation from observer output.
+            await ux.EndStreamingOutputAsync();
+
+            var combinedMessages = new List<ChatMessage>();
+            bool hasObserverMessages = false;
+            foreach (var observer in observers)
+            {
+                var messages = await observer.OnStreamCompleteAsync(ux, agent, session, options);
+                if (messages is { Count: > 0 })
+                {
+                    combinedMessages.AddRange(messages);
+                    hasObserverMessages = true;
+                }
+            }
+
+            await ux.WriteNoTextWarningAsync(hasFollowUpMessages: hasObserverMessages);
+
+            ux.EndStreaming();
+
+            nextMessages = combinedMessages.Count > 0 ? combinedMessages : null;
+        }
+    }
+
+    /// <summary>
+    /// Synchronizes the queued items display with the message injector's pending messages.
+    /// Messages that have been consumed (drained by the service) are echoed to the output
+    /// area as regular user-input entries.
+    /// </summary>
+    private static void SyncQueuedMessageDisplay(
+        MessageInjectingChatClient? messageInjector,
+        AgentSession session,
+        HarnessUXContainer ux,
+        ref IReadOnlyList<ChatMessage> lastPendingMessages)
+    {
+        if (messageInjector is null)
+        {
+            return;
+        }
+
+        var pending = messageInjector.GetPendingMessages(session);
+
+        // If previously pending messages exceed current pending count, some were consumed.
+        int consumedCount = lastPendingMessages.Count - pending.Count;
+        for (int i = 0; i < consumedCount && i < lastPendingMessages.Count; i++)
+        {
+            string text = lastPendingMessages[i].Text ?? string.Empty;
+            ux.WriteUserInputEcho(text);
+        }
+
+        lastPendingMessages = pending;
+        ux.ShowQueuedMessages(pending);
+    }
+
+    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),
+        };
+
+        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;
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/HarnessConsoleOptions.cs

@@ -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,
+    };
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/HarnessUXContainer.cs

@@ -0,0 +1,478 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Harness.ConsoleReactiveComponents;
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console;
+
+/// <summary>
+/// Event arguments raised when the user submits text while the bottom panel is in
+/// streaming mode (i.e. an agent turn is in progress).
+/// </summary>
+public sealed class StreamingInputReceivedEventArgs : EventArgs
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="StreamingInputReceivedEventArgs"/> class.
+    /// </summary>
+    /// <param name="text">The submitted text.</param>
+    public StreamingInputReceivedEventArgs(string text)
+    {
+        this.Text = text;
+    }
+
+    /// <summary>
+    /// Gets the submitted text.
+    /// </summary>
+    public string Text { get; }
+}
+
+/// <summary>
+/// Façade over the harness UI: owns the <see cref="HarnessAppComponent"/>, manages
+/// its props, dispatches input submissions, and provides the high-level read/write
+/// operations used by observers, command handlers, and the harness loop.
+/// </summary>
+/// <remarks>
+/// All callers interact with the UI exclusively through this class. The underlying
+/// <see cref="HarnessAppComponent"/> and its props are an implementation detail and
+/// must not be exposed.
+/// </remarks>
+public sealed class HarnessUXContainer : IDisposable
+{
+    /// <summary>
+    /// The prompt displayed in the bottom-panel input area.
+    /// </summary>
+    private const string UserPrompt = "> ";
+
+    private readonly IReadOnlyDictionary<string, ConsoleColor>? _modeColors;
+    private readonly List<object> _outputItems = [];
+    private readonly HarnessAppComponent _appComponent;
+    private readonly object _outputLock = new();
+
+    private TaskCompletionSource<string>? _pendingInputTcs;
+    private OutputEntryType? _lastEntryType;
+    private bool _hasReceivedAnyText;
+    private OutputEntry? _currentStreamingEntry;
+    private string? _currentMode;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="HarnessUXContainer"/> class.
+    /// </summary>
+    /// <param name="placeholder">Placeholder text shown when the input is empty.</param>
+    /// <param name="initialMode">The current agent mode, used to colour the rule and prompt.</param>
+    /// <param name="inputEnabled">Whether the bottom-panel input accepts keystrokes during streaming.</param>
+    /// <param name="modeColors">Optional mapping of mode names to console colors.</param>
+    public HarnessUXContainer(
+        string placeholder,
+        string? initialMode,
+        bool inputEnabled,
+        IReadOnlyDictionary<string, ConsoleColor>? modeColors = null)
+    {
+        this._modeColors = modeColors;
+        this._currentMode = initialMode;
+
+        this._appComponent = new HarnessAppComponent(RenderOutputEntry)
+        {
+            Props = new HarnessAppComponentProps
+            {
+                ScrollItems = this._outputItems,
+                Mode = BottomPanelMode.TextInput,
+                Prompt = UserPrompt,
+                Placeholder = placeholder,
+                ModeColor = ModeColors.Get(initialMode, modeColors),
+                ModeText = initialMode,
+                InputEnabled = inputEnabled,
+            },
+        };
+
+        this._appComponent.InputSubmitted += this.OnInputSubmitted;
+    }
+
+    /// <summary>
+    /// Raised when the user submits text while the bottom panel is in streaming mode.
+    /// Subscribers typically enqueue the text into a message-injecting chat client.
+    /// </summary>
+    public event EventHandler<StreamingInputReceivedEventArgs>? StreamingInputReceived;
+
+    /// <summary>
+    /// Gets or sets the current agent mode (e.g. "plan", "execute"). Updating this
+    /// also refreshes the rule colour and bottom-panel prompt to match the new mode.
+    /// </summary>
+    public string? CurrentMode
+    {
+        get => this._currentMode;
+        set
+        {
+            this._currentMode = value;
+            this._appComponent.Props = this._appComponent.Props! with
+            {
+                ModeColor = ModeColors.Get(value, this._modeColors),
+                ModeText = value,
+            };
+            this._appComponent.Render();
+        }
+    }
+
+    /// <summary>
+    /// Performs the initial screen clear, sets the help text in the mode-and-help bar,
+    /// and adds the title to the output area.
+    /// </summary>
+    /// <param name="title">The title displayed in the console header.</param>
+    /// <param name="commandHelpTexts">The command help strings displayed in the mode-and-help bar.</param>
+    /// <param name="messageInjectionActive">Whether streaming-time message injection is enabled.</param>
+    public void Initialize(string title, IEnumerable<string> commandHelpTexts, bool messageInjectionActive)
+    {
+        // Set the help text on the mode-and-help bar (persists below the rule).
+        this._appComponent.Props = this._appComponent.Props! with
+        {
+            HelpText = string.Join(", ", commandHelpTexts),
+            ModeText = this._currentMode,
+        };
+
+        System.Console.Write(AnsiEscapes.EraseEntireScreen);
+        System.Console.Write(AnsiEscapes.EraseScrollbackBuffer);
+        this._appComponent.Render();
+
+        this.AppendOutputEntries(
+            new OutputEntry(OutputEntryType.InfoLine, $"=== {title} ===\n", ConsoleColor.White),
+            new OutputEntry(OutputEntryType.InfoLine, "\n"));
+    }
+
+    /// <summary>
+    /// Restores the cursor and exits the alternate screen, ending the interactive UI.
+    /// </summary>
+    public void Deactivate() => this._appComponent.Deactivate();
+
+    /// <summary>
+    /// Switches the bottom panel to streaming mode and starts the spinner.
+    /// </summary>
+    public void BeginStreaming()
+    {
+        this._appComponent.Props = this._appComponent.Props! with
+        {
+            Mode = BottomPanelMode.Streaming,
+            ShowSpinner = true,
+        };
+        this._appComponent.Render();
+    }
+
+    /// <summary>
+    /// Stops the spinner without leaving streaming mode. Use between the end of the
+    /// stream and any observer-driven prompts (e.g. tool approvals).
+    /// </summary>
+    public void StopSpinner()
+    {
+        this._appComponent.Props = this._appComponent.Props! with { ShowSpinner = false };
+        this._appComponent.Render();
+    }
+
+    /// <summary>
+    /// Switches the bottom panel back to text-input mode and stops the spinner.
+    /// </summary>
+    public void EndStreaming()
+    {
+        this._appComponent.Props = this._appComponent.Props! with
+        {
+            Mode = BottomPanelMode.TextInput,
+            ShowSpinner = false,
+        };
+        this._appComponent.Render();
+    }
+
+    /// <summary>
+    /// Resets per-turn streaming bookkeeping in preparation for a new agent turn.
+    /// </summary>
+    public void BeginStreamingOutput()
+    {
+        this._hasReceivedAnyText = false;
+        this._currentStreamingEntry = null;
+    }
+
+    /// <summary>
+    /// Sets the formatted usage text shown on the agent status bar.
+    /// </summary>
+    public void SetUsageText(string usageText)
+    {
+        this._appComponent.Props = this._appComponent.Props! with { UsageText = usageText };
+        this._appComponent.Render();
+    }
+
+    /// <summary>
+    /// Clears the usage text from the agent status bar.
+    /// </summary>
+    public void ClearUsageText()
+    {
+        this._appComponent.Props = this._appComponent.Props! with { UsageText = null };
+        this._appComponent.Render();
+    }
+
+    /// <summary>
+    /// Replaces the queued-message display with one entry per pending message.
+    /// </summary>
+    public void ShowQueuedMessages(IReadOnlyList<ChatMessage> pending)
+    {
+        var newQueued = new List<object>(pending.Count);
+        foreach (var msg in pending)
+        {
+            string text = msg.Text ?? string.Empty;
+            newQueued.Add(new OutputEntry(OutputEntryType.UserInput, $"  💬 {text}\n", ConsoleColor.DarkGray));
+        }
+
+        this._appComponent.Props = this._appComponent.Props! with { QueuedItems = newQueued };
+        this._appComponent.Render();
+    }
+
+    /// <summary>
+    /// Echoes a submitted user input as a regular user-input entry in the output area,
+    /// using the current mode-aware prompt prefix.
+    /// </summary>
+    /// <param name="text">The user-entered text.</param>
+    public void WriteUserInputEcho(string text)
+    {
+        this.AppendOutputEntries(new OutputEntry(
+            OutputEntryType.UserInput,
+            $"\nYou: {text}\n",
+            ConsoleColor.Green));
+    }
+
+    /// <summary>
+    /// Writes informational output as an output entry, without a trailing newline.
+    /// </summary>
+    public Task WriteInfoAsync(string text, ConsoleColor? color = null) =>
+        this.WriteInfoCoreAsync(text, color, newLine: false);
+
+    /// <summary>
+    /// Writes informational output as an output entry, followed by a newline.
+    /// </summary>
+    public Task WriteInfoLineAsync(string text, ConsoleColor? color = null) =>
+        this.WriteInfoCoreAsync(text, color, newLine: true);
+
+    private Task WriteInfoCoreAsync(string text, ConsoleColor? color, bool newLine)
+    {
+        // Add a blank line separator when transitioning from streaming text or user input.
+        string prefix = this._lastEntryType is OutputEntryType.StreamingText or OutputEntryType.StreamFooter
+            ? "\n\n  "
+            : "  ";
+
+        string fullText = newLine ? prefix + text + "\n" : prefix + text;
+        this.AppendOutputEntries(new OutputEntry(
+            OutputEntryType.InfoLine,
+            fullText,
+            color ?? ModeColors.Get(this.CurrentMode, this._modeColors)));
+        return Task.CompletedTask;
+    }
+
+    /// <summary>
+    /// Writes streaming text output from the agent. Successive calls accumulate into a
+    /// single streaming entry that is re-rendered by the text panel.
+    /// </summary>
+    public Task WriteTextAsync(string text, ConsoleColor? color = null)
+    {
+        lock (this._outputLock)
+        {
+            this._lastEntryType = OutputEntryType.StreamingText;
+            this._hasReceivedAnyText = true;
+
+            ConsoleColor effectiveColor = color ?? ModeColors.Get(this.CurrentMode, this._modeColors);
+
+            if (this._currentStreamingEntry is not null)
+            {
+                this._currentStreamingEntry = this._currentStreamingEntry with
+                {
+                    Text = this._currentStreamingEntry.Text + text,
+                };
+                this._outputItems[^1] = this._currentStreamingEntry;
+            }
+            else
+            {
+                const string Prefix = "\n";
+                this._currentStreamingEntry = new OutputEntry(OutputEntryType.StreamingText, Prefix + text, effectiveColor);
+                this._outputItems.Add(this._currentStreamingEntry);
+            }
+
+            this._appComponent.Props = this._appComponent.Props! with
+            {
+                ScrollItems = new List<object>(this._outputItems),
+            };
+        }
+
+        this._appComponent.Render();
+        return Task.CompletedTask;
+    }
+
+    /// <summary>
+    /// Writes a blank-line separator to visually close the streaming output section.
+    /// Call before observer completions so their output is visually separated.
+    /// </summary>
+    public Task EndStreamingOutputAsync()
+    {
+        lock (this._outputLock)
+        {
+            this._outputItems.Add(new OutputEntry(OutputEntryType.StreamFooter, "\n"));
+            this._currentStreamingEntry = null;
+            this._lastEntryType = OutputEntryType.StreamFooter;
+            this._appComponent.Props = this._appComponent.Props! with
+            {
+                ScrollItems = new List<object>(this._outputItems),
+            };
+        }
+
+        this._appComponent.Render();
+        return Task.CompletedTask;
+    }
+
+    /// <summary>
+    /// Shows a "(no text response from agent)" warning if no text was received
+    /// and no observer produced follow-up messages. Call after observer completions.
+    /// </summary>
+    /// <param name="hasFollowUpMessages">Whether any observer produced follow-up messages.</param>
+    public Task WriteNoTextWarningAsync(bool hasFollowUpMessages)
+    {
+        if (!this._hasReceivedAnyText && !hasFollowUpMessages)
+        {
+            this.AppendOutputEntries(new OutputEntry(
+                OutputEntryType.StreamFooter,
+                "  (no text response from agent)\n",
+                ConsoleColor.DarkYellow));
+        }
+
+        return Task.CompletedTask;
+    }
+
+    /// <summary>
+    /// Reads a line of input from the user. If <paramref name="prompt"/> is supplied
+    /// it is rendered as an info line above the input row before reading.
+    /// </summary>
+    public async Task<string?> ReadLineAsync(string? prompt = null, ConsoleColor? promptColor = null)
+    {
+        if (prompt is not null)
+        {
+            ConsoleColor ruleColor = ModeColors.Get(this.CurrentMode, this._modeColors);
+            this.AppendOutputEntries(
+                new OutputEntry(OutputEntryType.InfoLine, "\n", ruleColor),
+                new OutputEntry(OutputEntryType.InfoLine, $"  {prompt}", promptColor ?? ruleColor));
+        }
+
+        this._appComponent.Props = this._appComponent.Props! with { Mode = BottomPanelMode.TextInput };
+        this._appComponent.Render();
+
+        string input = await this.WaitForInputAsync();
+
+        this.AppendOutputEntries(new OutputEntry(
+            OutputEntryType.UserInput,
+            $"\nYou: {input}\n",
+            ConsoleColor.Green));
+
+        return input;
+    }
+
+    /// <summary>
+    /// Presents a selection prompt with the given choices and waits for the user's
+    /// selection. The title is displayed above the list in the bottom panel. After
+    /// selection the bottom panel is restored to text-input mode and both the question
+    /// and selection are echoed in the output area.
+    /// </summary>
+    public async Task<string> ReadSelectionAsync(string title, IList<string> choices)
+    {
+        this._appComponent.Props = this._appComponent.Props! with
+        {
+            Mode = BottomPanelMode.ListSelection,
+            Items = choices.ToList(),
+            ListTitle = title,
+            ListCustomTextPlaceholder = "✏️  Type a custom response...",
+        };
+        this._appComponent.Render();
+
+        string selection = await this.WaitForInputAsync();
+
+        this._appComponent.Props = this._appComponent.Props with { Mode = BottomPanelMode.TextInput };
+
+        this.AppendOutputEntries(
+            new OutputEntry(
+                OutputEntryType.InfoLine,
+                $"\n  {title}\n",
+                ModeColors.Get(this.CurrentMode, this._modeColors)),
+            new OutputEntry(
+                OutputEntryType.UserInput,
+                $"\nYou: {selection}\n",
+                ConsoleColor.Green));
+
+        return selection;
+    }
+
+    /// <summary>
+    /// Awaits the next non-streaming user input submission.
+    /// </summary>
+    public Task<string> WaitForInputAsync()
+    {
+        this._pendingInputTcs = new TaskCompletionSource<string>(TaskCreationOptions.RunContinuationsAsynchronously);
+        return this._pendingInputTcs.Task;
+    }
+
+    private void OnInputSubmitted(object? sender, InputSubmittedEventArgs e)
+    {
+        if (e.Mode == BottomPanelMode.Streaming)
+        {
+            this.StreamingInputReceived?.Invoke(this, new StreamingInputReceivedEventArgs(e.Text));
+        }
+        else
+        {
+            var waiter = this._pendingInputTcs;
+            this._pendingInputTcs = null;
+            waiter?.TrySetResult(e.Text);
+        }
+    }
+
+    /// <inheritdoc/>
+    public void Dispose()
+    {
+        this._appComponent.InputSubmitted -= this.OnInputSubmitted;
+        this._appComponent.Deactivate();
+        this._appComponent.Dispose();
+    }
+
+    /// <summary>
+    /// Renders an <see cref="OutputEntry"/> to a string with ANSI color codes.
+    /// Used as the render delegate for the <see cref="HarnessAppComponent"/>.
+    /// </summary>
+    private static string RenderOutputEntry(object item)
+    {
+        if (item is not OutputEntry entry)
+        {
+            return item?.ToString() ?? string.Empty;
+        }
+
+        if (entry.Color.HasValue)
+        {
+            return $"{AnsiEscapes.SetForegroundColor(entry.Color.Value)}{entry.Text}{AnsiEscapes.ResetAttributes}";
+        }
+
+        return entry.Text;
+    }
+
+    /// <summary>
+    /// Appends one or more output entries to the output list under lock,
+    /// updates <see cref="_lastEntryType"/> to the last entry's type, and renders.
+    /// </summary>
+    private void AppendOutputEntries(params OutputEntry[] entries)
+    {
+        lock (this._outputLock)
+        {
+            foreach (OutputEntry entry in entries)
+            {
+                this._outputItems.Add(entry);
+            }
+
+            if (entries.Length > 0)
+            {
+                this._lastEntryType = entries[^1].Type;
+            }
+
+            this._appComponent.Props = this._appComponent.Props! with
+            {
+                ScrollItems = new List<object>(this._outputItems),
+            };
+        }
+
+        this._appComponent.Render();
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Harness_Shared_Console.csproj

@@ -0,0 +1,16 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+    <ProjectReference Include="..\ConsoleReactiveFramework\ConsoleReactiveFramework.csproj" />
+    <ProjectReference Include="..\ConsoleReactiveComponents\ConsoleReactiveComponents.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/02-agents/Harness/Harness_Shared_Console/ModeColors.cs

@@ -0,0 +1,31 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Harness.Shared.Console;
+
+/// <summary>
+/// Helpers for resolving console colours associated with agent modes.
+/// </summary>
+internal static class ModeColors
+{
+    /// <summary>
+    /// Gets the console color associated with a mode name, using the provided color map.
+    /// Falls back to <see cref="ConsoleColor.Gray"/> when the mode is <see langword="null"/>
+    /// or not present in the map.
+    /// </summary>
+    /// <param name="mode">The mode name, or <see langword="null"/> if no mode is active.</param>
+    /// <param name="modeColors">Optional mapping of mode names to console colors.</param>
+    public static ConsoleColor Get(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;
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/ConsoleObserver.cs

@@ -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="ux">The harness UX container, used for rendering output and interacting with the user.</param>
+    /// <param name="content">The content item from the stream.</param>
+    public virtual Task OnContentAsync(HarnessUXContainer ux, AIContent content) => Task.CompletedTask;
+
+    /// <summary>
+    /// Called for each text update in the response stream.
+    /// </summary>
+    /// <param name="ux">The harness UX container, used for rendering output and interacting with the user.</param>
+    /// <param name="text">The text from the update.</param>
+    public virtual Task OnTextAsync(HarnessUXContainer ux, 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="ux">The harness UX container, used for rendering output and interacting with the user.</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(
+        HarnessUXContainer ux,
+        AIAgent agent,
+        AgentSession session,
+        HarnessConsoleOptions options) => Task.FromResult<IList<ChatMessage>?>(null);
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/ErrorDisplayObserver.cs

@@ -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(HarnessUXContainer ux, 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 ux.WriteInfoLineAsync(errorText, ConsoleColor.Red);
+        }
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/PlanningOutputObserver.cs

@@ -0,0 +1,156 @@
+// 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(HarnessUXContainer ux, string text)
+    {
+        // Collect text silently instead of displaying it.
+        this._textCollector.Append(text);
+        return Task.CompletedTask;
+    }
+
+    /// <inheritdoc/>
+    public override async Task<IList<ChatMessage>?> OnStreamCompleteAsync(
+        HarnessUXContainer ux,
+        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 ux.WriteInfoLineAsync($"❌ Failed to parse planning response: {ex.Message}", ConsoleColor.Red);
+            await ux.WriteInfoLineAsync($"(raw response) {collectedText}", ConsoleColor.DarkYellow);
+            return null;
+        }
+
+        if (planningResponse is null)
+        {
+            await ux.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(ux, planningResponse));
+        }
+
+        if (planningResponse.Type == PlanningResponseType.Approval)
+        {
+            var question = planningResponse.Questions.FirstOrDefault();
+            if (question is null)
+            {
+                await ux.WriteInfoLineAsync("(approval response had no content)", ConsoleColor.DarkYellow);
+                return null;
+            }
+
+            string response = await this.RenderApprovalAndCollectResponseAsync(ux, question, options);
+            if (response == "Approved")
+            {
+                this._modeProvider.SetMode(session, options.ExecutionModeName!);
+
+                await ux.WriteInfoLineAsync($"✅ Switched to {options.ExecutionModeName} mode.",
+                    ModeColors.Get(options.ExecutionModeName, options.ModeColors));
+            }
+
+            return AsUserMessages(response);
+        }
+
+        await ux.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(HarnessUXContainer ux, PlanningResponse response)
+    {
+        var answers = new List<string>();
+
+        foreach (var question in response.Questions)
+        {
+            string? answer;
+            if (question.Choices is { Count: > 0 })
+            {
+                answer = await ux.ReadSelectionAsync(
+                    question.Message,
+                    question.Choices);
+            }
+            else
+            {
+                answer = (await ux.ReadLineAsync(question.Message))?.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(HarnessUXContainer ux, PlanningQuestion question, HarnessConsoleOptions options)
+    {
+        var choices = new List<string>
+        {
+            "Approve and switch to execute mode",
+        };
+
+        string selection = await ux.ReadSelectionAsync(question.Message, choices);
+
+        if (selection == choices[0])
+        {
+            return "Approved";
+        }
+
+        // Custom freeform input — treat as suggested changes.
+        return selection;
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/PlanningResponse.cs

@@ -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; }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/PlanningResponseType.cs

@@ -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,
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/ReasoningDisplayObserver.cs

@@ -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(HarnessUXContainer ux, AIContent content)
+    {
+        if (content is TextReasoningContent reasoning && !string.IsNullOrEmpty(reasoning.Text))
+        {
+            await ux.WriteTextAsync(reasoning.Text, ConsoleColor.DarkMagenta);
+        }
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/TextOutputObserver.cs

@@ -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(HarnessUXContainer ux, string text)
+    {
+        await ux.WriteTextAsync(text);
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/ToolApprovalObserver.cs

@@ -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(HarnessUXContainer ux, 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 ux.WriteInfoLineAsync($"⚠️ Approval needed: {toolName}", ConsoleColor.Yellow);
+        }
+    }
+
+    /// <inheritdoc/>
+    public override async Task<IList<ChatMessage>?> OnStreamCompleteAsync(
+        HarnessUXContainer ux,
+        AIAgent agent,
+        AgentSession session,
+        HarnessConsoleOptions options)
+    {
+        if (this._approvalRequests.Count == 0)
+        {
+            return null;
+        }
+
+        var messages = await PromptForApprovalsAsync(ux, this._approvalRequests);
+        this._approvalRequests.Clear();
+        return messages;
+    }
+
+    private static async Task<List<ChatMessage>?> PromptForApprovalsAsync(HarnessUXContainer ux, 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 ux.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 ux.WriteInfoLineAsync($"   {action}", ConsoleColor.DarkGray);
+
+            responses.Add(response);
+        }
+
+        return [new ChatMessage(ChatRole.User, responses)];
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/ToolCallDisplayObserver.cs

@@ -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(HarnessUXContainer ux, AIContent content)
+    {
+        if (content is FunctionCallContent functionCall)
+        {
+            await ux.WriteInfoLineAsync($"🔧 Calling tool: {ToolCallFormatter.Format(functionCall)}...", ConsoleColor.DarkYellow);
+        }
+        else if (content is ToolCallContent toolCall)
+        {
+            await ux.WriteInfoLineAsync($"🔧 Calling tool: {toolCall}...", ConsoleColor.DarkYellow);
+        }
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/ToolCallFormatter.cs

@@ -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), "…");
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/UsageDisplayObserver.cs

@@ -0,0 +1,70 @@
+// 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 Task OnContentAsync(HarnessUXContainer ux, AIContent content)
+    {
+        if (content is UsageContent usage)
+        {
+            if (usage.Details is not null)
+            {
+                ux.SetUsageText(this.FormatUsageBreakdown(usage.Details));
+            }
+            else
+            {
+                ux.SetUsageText("📊 Tokens —");
+            }
+        }
+
+        return Task.CompletedTask;
+    }
+
+    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}";
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/OutputEntry.cs

@@ -0,0 +1,33 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Harness.Shared.Console;
+
+/// <summary>
+/// Represents the type of an output entry in the console conversation.
+/// </summary>
+public enum OutputEntryType
+{
+    /// <summary>User input echo (e.g. "You: hello").</summary>
+    UserInput,
+
+    /// <summary>In-progress streaming text from the agent (accumulated chunk by chunk).</summary>
+    StreamingText,
+
+    /// <summary>Informational line (tool calls, errors, usage, approval requests, etc.).</summary>
+    InfoLine,
+
+    /// <summary>Stream footer (e.g. "(no text response from agent)").</summary>
+    StreamFooter,
+
+    /// <summary>Pending injected message notification.</summary>
+    PendingMessage,
+}
+
+/// <summary>
+/// Represents a single output entry in the console conversation history.
+/// These entries are rendered by the <see cref="HarnessAppComponent"/> via its render delegate.
+/// </summary>
+/// <param name="Type">The type of output entry.</param>
+/// <param name="Text">The text content of the entry.</param>
+/// <param name="Color">Optional foreground color for rendering.</param>
+public record OutputEntry(OutputEntryType Type, string Text, ConsoleColor? Color = null);

dotnet/samples/02-agents/Harness/Harness_Step01_Research/Harness_Step01_Research.csproj

@@ -6,12 +6,15 @@
 
     <Nullable>enable</Nullable>
     <ImplicitUsings>enable</ImplicitUsings>
-    
   </PropertyGroup>
 
   <ItemGroup>
-    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry.Hosting\Microsoft.Agents.AI.Foundry.Hosting.csproj" />
-    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.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>

dotnet/samples/02-agents/Harness/Harness_Step01_Research/Program.cs

@@ -0,0 +1,192 @@
+// 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.
+    .UseMessageInjection()                                  // Allow message injection during the function call loop.
+    .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.
+                        new WebBrowsingToolOptions { AllowPublicNetworks = true }),
+                ],
+                MaxOutputTokens = MaxOutputTokens,                          // Set a high token limit for long research tasks with many tool calls and long outputs.
+                Reasoning = new() { Effort = ReasoningEffort.Medium },
+            },
+        })
+    .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"
+    });

dotnet/samples/02-agents/Harness/Harness_Step01_Research/README.md

@@ -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.

dotnet/samples/02-agents/Harness/Harness_Step01_Research/WebBrowsingTool.cs

@@ -0,0 +1,439 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+using System.Net;
+using System.Net.Sockets;
+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.
+/// Access is controlled by <see cref="WebBrowsingToolOptions"/> — by default, no hosts are accessible.
+/// </summary>
+internal sealed partial class WebBrowsingTool : AIFunction
+{
+    private static readonly HttpClient s_httpClient = new();
+    private readonly AIFunction _inner;
+    private readonly WebBrowsingToolOptions _options;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="WebBrowsingTool"/> class.
+    /// </summary>
+    /// <param name="options">Options controlling which URLs are permitted. By default, no hosts are accessible.</param>
+    public WebBrowsingTool(WebBrowsingToolOptions options)
+    {
+        this._options = options ?? throw new ArgumentNullException(nameof(options));
+        this._inner = AIFunctionFactory.Create(this.DownloadUriAsync);
+    }
+
+    /// <inheritdoc/>
+    public override string Name => this._inner.Name;
+
+    /// <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 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}'.";
+        }
+
+        // Check access policy.
+        string? accessError = await this.CheckAccessAsync(parsedUri, cancellationToken);
+        if (accessError is not null)
+        {
+            return accessError;
+        }
+
+        try
+        {
+            string html = await s_httpClient.GetStringAsync(parsedUri, cancellationToken);
+            return HtmlToMarkdownConverter.Convert(html);
+        }
+        catch (HttpRequestException ex)
+        {
+            return $"Error downloading {uri}: {ex.Message}";
+        }
+    }
+
+    /// <summary>
+    /// Checks whether the given URI is permitted by the configured access policy.
+    /// Returns null if allowed, or an error message string if blocked.
+    /// </summary>
+    private async Task<string?> CheckAccessAsync(Uri uri, CancellationToken cancellationToken)
+    {
+        string host = uri.Host;
+
+        // 1. Check AllowedHosts.
+        if (this._options.AllowedHosts is { Count: > 0 } allowedHosts)
+        {
+            foreach (string pattern in allowedHosts)
+            {
+                if (HostMatchesPattern(host, pattern))
+                {
+                    return null; // Allowed by explicit host list.
+                }
+            }
+        }
+
+        // 2. Short-circuit when the policy is guaranteed to block.
+        if (!this._options.AllowPublicNetworks &&
+            !this._options.AllowPrivateNetworks &&
+            !this._options.AllowAllHosts)
+        {
+            return $"Error: Access to '{host}' is blocked by the current access policy. Configure WebBrowsingToolOptions to allow access.";
+        }
+
+        // 3. Resolve DNS to determine if the host is public or private.
+        IPAddress[] addresses;
+        try
+        {
+            addresses = await Dns.GetHostAddressesAsync(host, cancellationToken);
+        }
+        catch (SocketException)
+        {
+            return $"Error: Could not resolve host '{host}'.";
+        }
+
+        if (addresses.Length == 0)
+        {
+            return $"Error: Could not resolve host '{host}'.";
+        }
+
+        bool isPrivate = Array.Exists(addresses, IsPrivateAddress);
+
+        // 4. If public and AllowPublicNetworks is true → allow.
+        if (!isPrivate && this._options.AllowPublicNetworks)
+        {
+            return null;
+        }
+
+        // 5. If private and AllowPrivateNetworks is true → allow.
+        if (isPrivate && this._options.AllowPrivateNetworks)
+        {
+            return null;
+        }
+
+        // 6. If AllowAllHosts is true → allow.
+        if (this._options.AllowAllHosts)
+        {
+            return null;
+        }
+
+        // 7. Block.
+        string networkType = isPrivate ? "private/internal network" : "public network";
+        return $"Error: Access to '{host}' is blocked. The host resolves to a {networkType} address and the current access policy does not permit this. " +
+               "Configure WebBrowsingToolOptions to allow access.";
+    }
+
+    /// <summary>
+    /// Checks whether a host matches a pattern. Supports exact match and wildcard prefix (e.g., "*.example.com").
+    /// </summary>
+    private static bool HostMatchesPattern(string host, string pattern)
+    {
+        if (string.Equals(host, pattern, StringComparison.OrdinalIgnoreCase))
+        {
+            return true;
+        }
+
+        // Wildcard prefix: "*.example.com" matches "sub.example.com" and "a.b.example.com".
+        if (pattern.StartsWith("*.", StringComparison.Ordinal))
+        {
+            string suffix = pattern[1..]; // ".example.com"
+            return host.EndsWith(suffix, StringComparison.OrdinalIgnoreCase);
+        }
+
+        return false;
+    }
+
+    /// <summary>
+    /// Determines whether an IP address is private, loopback, or link-local.
+    /// </summary>
+    private static bool IsPrivateAddress(IPAddress address)
+    {
+        if (address.IsIPv4MappedToIPv6)
+        {
+            address = address.MapToIPv4();
+        }
+
+        if (IPAddress.IsLoopback(address))
+        {
+            return true;
+        }
+
+        if (address.AddressFamily == AddressFamily.InterNetwork)
+        {
+            byte[] bytes = address.GetAddressBytes();
+            return bytes[0] switch
+            {
+                10 => true,                                          // 10.0.0.0/8
+                172 => bytes[1] >= 16 && bytes[1] <= 31,             // 172.16.0.0/12
+                192 => bytes[1] == 168,                              // 192.168.0.0/16
+                169 => bytes[1] == 254,                              // 169.254.0.0/16 (link-local + metadata)
+                _ => false
+            };
+        }
+
+        if (address.AddressFamily == AddressFamily.InterNetworkV6)
+        {
+            // fe80::/10 (link-local) or fc00::/7 (unique local).
+            byte[] bytes = address.GetAddressBytes();
+            if (bytes[0] == 0xfe && (bytes[1] & 0xc0) == 0x80)
+            {
+                return true; // Link-local
+            }
+
+            if ((bytes[0] & 0xfe) == 0xfc)
+            {
+                return true; // Unique local
+            }
+        }
+
+        return false;
+    }
+
+    /// <summary>
+    /// A simple HTML to Markdown converter using regex-based transformations.
+    /// Handles the most common HTML elements without requiring external dependencies.
+    /// </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();
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Step01_Research/WebBrowsingToolOptions.cs

@@ -0,0 +1,60 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace SampleApp;
+
+/// <summary>
+/// Options that control which URLs the <see cref="WebBrowsingTool"/> is permitted to access.
+/// </summary>
+/// <remarks>
+/// <para>
+/// By default, <b>no hosts are accessible</b>. You must explicitly opt in to one or more
+/// of the access modes below. The validation order is:
+/// </para>
+/// <list type="number">
+/// <item><description>If the host matches an entry in <see cref="AllowedHosts"/>, the request is allowed.</description></item>
+/// <item><description>If the resolved IP is a public address and <see cref="AllowPublicNetworks"/> is <see langword="true"/>, the request is allowed.</description></item>
+/// <item><description>If the resolved IP is a private/loopback/link-local address and <see cref="AllowPrivateNetworks"/> is <see langword="true"/>, the request is allowed.</description></item>
+/// <item><description>If <see cref="AllowAllHosts"/> is <see langword="true"/>, the request is allowed.</description></item>
+/// <item><description>Otherwise, the request is blocked.</description></item>
+/// </list>
+/// </remarks>
+internal sealed class WebBrowsingToolOptions
+{
+    /// <summary>
+    /// Gets or sets a list of host patterns that are always permitted, regardless of other settings.
+    /// Patterns support wildcard prefix matching (e.g., <c>"*.example.com"</c> matches <c>"docs.example.com"</c>).
+    /// Exact host names (e.g., <c>"docs.microsoft.com"</c>) are also supported.
+    /// </summary>
+    /// <remarks>This has the highest priority — if a host matches, it is allowed immediately.</remarks>
+    public IReadOnlyList<string>? AllowedHosts { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether public internet hosts (non-private, non-loopback, non-link-local IPs) are permitted.
+    /// Default is <see langword="false"/>.
+    /// </summary>
+    public bool AllowPublicNetworks { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether private network hosts are permitted.
+    /// This includes RFC 1918 addresses (10.x.x.x, 172.16-31.x.x, 192.168.x.x),
+    /// loopback (127.x.x.x, ::1), link-local (169.254.x.x, fe80::),
+    /// and cloud metadata endpoints (169.254.169.254).
+    /// Default is <see langword="false"/>.
+    /// </summary>
+    /// <remarks>
+    /// <b>Warning:</b> Enabling this allows the agent to make requests to internal services,
+    /// localhost, and cloud metadata endpoints. Only enable this if you understand the SSRF risks.
+    /// </remarks>
+    public bool AllowPrivateNetworks { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether all hosts are permitted without any restriction.
+    /// Default is <see langword="false"/>.
+    /// </summary>
+    /// <remarks>
+    /// <b>⚠️ UNSAFE:</b> Enabling this disables all network boundary checks and allows the agent
+    /// to access any URL, including internal services, cloud metadata endpoints, and localhost.
+    /// Only use this for trusted, isolated environments where SSRF is not a concern.
+    /// </remarks>
+    public bool AllowAllHosts { get; set; }
+}

dotnet/samples/02-agents/Harness/Harness_Step02_Research_WithSubAgents/Harness_Step02_Research_WithSubAgents.csproj

@@ -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>

dotnet/samples/02-agents/Harness/Harness_Step02_Research_WithSubAgents/Program.cs

@@ -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):");

dotnet/samples/02-agents/Harness/Harness_Step02_Research_WithSubAgents/README.md

@@ -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.

dotnet/samples/02-agents/Harness/Harness_Step03_DataProcessing/Harness_Step03_DataProcessing.csproj

@@ -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>

dotnet/samples/02-agents/Harness/Harness_Step03_DataProcessing/Program.cs

@@ -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.");

dotnet/samples/02-agents/Harness/Harness_Step03_DataProcessing/README.md

@@ -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 |

dotnet/samples/02-agents/Harness/Harness_Step03_DataProcessing/data/sales.csv

@@ -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

dotnet/samples/02-agents/Harness/README.md

@@ -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 |

dotnet/samples/02-agents/README.md

@@ -11,11 +11,13 @@ The getting started samples demonstrate the fundamental concepts and functionali
 | [Agent Providers](./AgentProviders/README.md) | Getting started with creating agents using various providers |
 | [Agents With Retrieval Augmented Generation (RAG)](./AgentWithRAG/README.md) | Adding Retrieval Augmented Generation (RAG) capabilities to your agents |
 | [Agents With Memory](./AgentWithMemory/README.md) | Adding memory capabilities to your agents |
+| [Agents With CodeAct (Hyperlight)](./AgentWithCodeAct/README.md) | Enabling sandboxed code execution (CodeAct) for your agents via Hyperlight |
 | [Agent Open Telemetry](./AgentOpenTelemetry/README.md) | Getting started with OpenTelemetry for agents |
 | [Agent With OpenAI exchange types](./AgentWithOpenAI/README.md) | Using OpenAI exchange types with agents |
 | [Agent With Anthropic](./AgentWithAnthropic/README.md) | Getting started with agents using Anthropic Claude |
 | [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 |

dotnet/samples/03-workflows/Declarative/InvokeHttpRequest/InvokeHttpRequest.csproj

@@ -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>

dotnet/samples/03-workflows/Declarative/InvokeHttpRequest/InvokeHttpRequest.yaml

@@ -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"

dotnet/samples/03-workflows/Declarative/InvokeHttpRequest/Program.cs

@@ -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.
+                """
+        };
+    }
+}

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/.env.example

@@ -0,0 +1,8 @@
+AZURE_AI_PROJECT_ENDPOINT=<your-azure-ai-project-endpoint>
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+AZURE_SEARCH_ENDPOINT=<your-azure-search-endpoint>
+AZURE_SEARCH_INDEX_NAME=contoso-outdoors
+AZURE_BEARER_TOKEN_FOUNDRY=DefaultAzureCredential
+AZURE_BEARER_TOKEN_SEARCH=DefaultAzureCredential
+ASPNETCORE_URLS=http://+:8088
+ASPNETCORE_ENVIRONMENT=Development

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/Dockerfile

@@ -0,0 +1,17 @@
+# Use the official .NET 10.0 ASP.NET runtime as a parent image
+FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
+WORKDIR /app
+
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /src
+COPY . .
+RUN dotnet restore
+RUN dotnet publish -c Release -o /app/publish
+
+# Final stage
+FROM base AS final
+WORKDIR /app
+COPY --from=build /app/publish .
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+ENTRYPOINT ["dotnet", "HostedAzureSearchRag.dll"]

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/Dockerfile.contributor

@@ -0,0 +1,23 @@
+# Dockerfile for contributors building from the agent-framework repository source.
+#
+# This project uses ProjectReference to the local Microsoft.Agents.AI.Foundry source,
+# which means a standard multi-stage Docker build cannot resolve dependencies outside
+# this folder. Instead, pre-publish the app targeting the container runtime and copy
+# the output into the container:
+#
+#   dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+#   docker build -f Dockerfile.contributor -t hosted-azure-search-rag .
+#   docker run --rm -p 8088:8088 \
+#     -e AGENT_NAME=hosted-azure-search-rag \
+#     -e AZURE_BEARER_TOKEN_FOUNDRY=$AZURE_BEARER_TOKEN_FOUNDRY \
+#     -e AZURE_BEARER_TOKEN_SEARCH=$AZURE_BEARER_TOKEN_SEARCH \
+#     --env-file .env hosted-azure-search-rag
+#
+# For end-users consuming the NuGet package (not ProjectReference), use the standard
+# Dockerfile which performs a full dotnet restore + publish inside the container.
+FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final
+WORKDIR /app
+COPY out/ .
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+ENTRYPOINT ["dotnet", "HostedAzureSearchRag.dll"]

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/HostedAzureSearchRag.csproj

@@ -0,0 +1,35 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <CentralPackageTransitivePinningEnabled>false</CentralPackageTransitivePinningEnabled>
+    <RootNamespace>HostedAzureSearchRag</RootNamespace>
+    <AssemblyName>HostedAzureSearchRag</AssemblyName>
+    <NoWarn>$(NoWarn);</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Azure.Search.Documents" />
+    <PackageReference Include="DotNetEnv" />
+  </ItemGroup>
+
+  <!-- For contributors: uses ProjectReference to build against local source -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry.Hosting\Microsoft.Agents.AI.Foundry.Hosting.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+  <!-- For end-users: uncomment the PackageReference below and remove the ProjectReferences above
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.Foundry" Version="1.0.0" />
+    <PackageReference Include="Microsoft.Agents.AI.Foundry.Hosting" Version="1.0.0" />
+    <PackageReference Include="Microsoft.Agents.AI.OpenAI" Version="1.0.0" />
+  </ItemGroup>
+  -->
+
+</Project>

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/Program.cs

@@ -0,0 +1,171 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to add Retrieval Augmented Generation (RAG) capabilities to a hosted
+// agent using Azure AI Search. The sample assumes the search index has already been provisioned
+// and populated out of band (see README.md for the required schema and example seed content).
+// A SearchClient-backed adapter is plugged into TextSearchProvider, which runs a keyword search
+// against the index before each model invocation and injects the matching documents into the
+// model context.
+
+using Azure;
+using Azure.AI.Projects;
+using Azure.Core;
+using Azure.Identity;
+using Azure.Search.Documents;
+using Azure.Search.Documents.Models;
+using DotNetEnv;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry.Hosting;
+using Microsoft.Extensions.AI;
+using OpenAI.Chat;
+
+// Load .env file if present (for local development)
+Env.TraversePath().Load();
+
+string projectEndpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";
+
+string searchEndpoint = Environment.GetEnvironmentVariable("AZURE_SEARCH_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_SEARCH_ENDPOINT is not set.");
+string searchIndexName = Environment.GetEnvironmentVariable("AZURE_SEARCH_INDEX_NAME")
+    ?? throw new InvalidOperationException("AZURE_SEARCH_INDEX_NAME is not set.");
+
+// Use a chained credential. Try a temporary dev token first (for local Docker debugging),
+// then fall back to DefaultAzureCredential (for local dev via dotnet run / managed identity in
+// production). The dev credential is scope aware so a single instance serves both Foundry and
+// Azure AI Search clients (each Azure SDK client requests a token for its own audience).
+TokenCredential credential = new ChainedTokenCredential(
+    new DevTemporaryTokenCredential(),
+    new DefaultAzureCredential());
+
+// Connect to the pre-provisioned search index. The caller is expected to have created the
+// index and populated it with documents matching the schema (id / content / sourceName /
+// sourceLink) before running this sample. See README.md for an example provisioning script.
+var searchClient = new SearchClient(new Uri(searchEndpoint), searchIndexName, credential);
+
+TextSearchProviderOptions textSearchOptions = new()
+{
+    SearchTime = TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke,
+    RecentMessageMemoryLimit = 6,
+};
+
+AIAgent agent = new AIProjectClient(new Uri(projectEndpoint), credential)
+    .AsAIAgent(new ChatClientAgentOptions
+    {
+        Name = Environment.GetEnvironmentVariable("AGENT_NAME") ?? "hosted-azure-search-rag",
+        ChatOptions = new ChatOptions
+        {
+            ModelId = deploymentName,
+            Instructions = "You are a helpful support specialist for Contoso Outdoors. " +
+                           "Answer questions using the provided context and cite the source document when available.",
+        },
+        AIContextProviders = [new TextSearchProvider(CreateSearchAdapter(searchClient), textSearchOptions)]
+    });
+
+// Host the agent as a Foundry Hosted Agent using the Responses API.
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddFoundryResponses(agent);
+
+var app = builder.Build();
+app.MapFoundryResponses();
+
+if (app.Environment.IsDevelopment())
+{
+    app.MapFoundryResponses("openai/v1");
+}
+
+app.Run();
+
+// ── Search adapter ───────────────────────────────────────────────────────────
+// Wraps a SearchClient as the delegate TextSearchProvider expects. Keyword/full-text only;
+// no embeddings. Returns the top results and projects them into TextSearchResult entries
+// the provider will inject into the model context.
+
+static Func<string, CancellationToken, Task<IEnumerable<TextSearchProvider.TextSearchResult>>>
+    CreateSearchAdapter(SearchClient client, int top = 3) =>
+    async (query, cancellationToken) =>
+    {
+        var options = new SearchOptions { Size = top };
+        Response<SearchResults<SearchDocument>> response =
+            await client.SearchAsync<SearchDocument>(query, options, cancellationToken).ConfigureAwait(false);
+
+        var results = new List<TextSearchProvider.TextSearchResult>();
+        await foreach (SearchResult<SearchDocument> hit in response.Value.GetResultsAsync().WithCancellation(cancellationToken).ConfigureAwait(false))
+        {
+            results.Add(new TextSearchProvider.TextSearchResult
+            {
+                SourceName = hit.Document.TryGetValue("sourceName", out var name) ? name?.ToString() ?? string.Empty : string.Empty,
+                SourceLink = hit.Document.TryGetValue("sourceLink", out var link) ? link?.ToString() ?? string.Empty : string.Empty,
+                Text = hit.Document.TryGetValue("content", out var content) ? content?.ToString() ?? string.Empty : string.Empty,
+                RawRepresentation = hit
+            });
+        }
+
+        return results;
+    };
+
+/// <summary>
+/// A scope aware <see cref="TokenCredential"/> for local Docker debugging only.
+/// Reads pre-fetched bearer tokens from environment variables, dispensing the right token
+/// based on the requested scope:
+/// <list type="bullet">
+///   <item><description><c>ai.azure.com</c> scopes -> <c>AZURE_BEARER_TOKEN_FOUNDRY</c></description></item>
+///   <item><description><c>search.azure.com</c> scopes -> <c>AZURE_BEARER_TOKEN_SEARCH</c></description></item>
+/// </list>
+/// For any other scope, throws <see cref="CredentialUnavailableException"/> so a chained
+/// credential will fall through. This should NOT be used in production: tokens expire (~1 hour)
+/// and cannot be refreshed.
+///
+/// Generate the tokens on your host and pass them to the container:
+/// <code>
+///   export AZURE_BEARER_TOKEN_FOUNDRY=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
+///   export AZURE_BEARER_TOKEN_SEARCH=$(az account get-access-token --resource https://search.azure.com --query accessToken -o tsv)
+///   docker run -e AZURE_BEARER_TOKEN_FOUNDRY -e AZURE_BEARER_TOKEN_SEARCH ...
+/// </code>
+/// </summary>
+internal sealed class DevTemporaryTokenCredential : TokenCredential
+{
+    private const string FoundryEnvironmentVariable = "AZURE_BEARER_TOKEN_FOUNDRY";
+    private const string SearchEnvironmentVariable = "AZURE_BEARER_TOKEN_SEARCH";
+
+    public override AccessToken GetToken(TokenRequestContext requestContext, CancellationToken cancellationToken)
+        => Resolve(requestContext.Scopes);
+
+    public override ValueTask<AccessToken> GetTokenAsync(TokenRequestContext requestContext, CancellationToken cancellationToken)
+        => new(Resolve(requestContext.Scopes));
+
+    private static AccessToken Resolve(IReadOnlyList<string> scopes)
+    {
+        string? envVar = null;
+        foreach (var scope in scopes)
+        {
+            if (scope.Contains("search.azure.com", StringComparison.OrdinalIgnoreCase))
+            {
+                envVar = SearchEnvironmentVariable;
+                break;
+            }
+
+            if (scope.Contains("ai.azure.com", StringComparison.OrdinalIgnoreCase))
+            {
+                envVar = FoundryEnvironmentVariable;
+                break;
+            }
+        }
+
+        if (envVar is null)
+        {
+            throw new CredentialUnavailableException(
+                $"DevTemporaryTokenCredential cannot serve scopes [{string.Join(", ", scopes)}]; falling through.");
+        }
+
+        var token = Environment.GetEnvironmentVariable(envVar);
+        if (string.IsNullOrEmpty(token) || string.Equals(token, "DefaultAzureCredential", StringComparison.Ordinal))
+        {
+            throw new CredentialUnavailableException(
+                $"{envVar} environment variable is not set; falling through to next credential.");
+        }
+
+        return new AccessToken(token, DateTimeOffset.UtcNow.AddHours(1));
+    }
+}

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/README.md

@@ -0,0 +1,179 @@
+# Hosted-AzureSearchRag
+
+A hosted agent with **Retrieval Augmented Generation (RAG)** capabilities backed by **Azure AI Search**. The agent grounds its answers in product documentation by running a keyword search against an Azure AI Search index before each model invocation, then citing the source in its response.
+
+This sample is the Azure AI Search counterpart to `Hosted-TextRag`. Where `Hosted-TextRag` uses a mock in-process search function, this sample talks to a real Azure AI Search index that is provisioned out of band (see "Provisioning the search index" below).
+
+## Prerequisites
+
+- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
+- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- An Azure AI Search service ([create one](https://learn.microsoft.com/azure/search/search-create-service-portal))
+- **A pre-provisioned search index** with the schema and content described in the next section
+- Azure CLI logged in (`az login`)
+
+### Required RBAC
+
+Your identity (or the Managed Identity running the container in production) needs:
+
+- **Azure AI User** on the Foundry project scope
+- **Search Index Data Reader** on the Azure AI Search service (the sample only reads from the index)
+
+## Provisioning the search index (one time)
+
+The sample assumes the search index already exists and contains documents the agent can retrieve from. Provision it once via the Azure Portal, the [REST API](https://learn.microsoft.com/azure/search/search-how-to-create-search-index), or the snippet below.
+
+### Index schema
+
+| Field | Type | Attributes |
+|---|---|---|
+| `id` | `Edm.String` | key, filterable |
+| `content` | `Edm.String` | searchable (full-text) |
+| `sourceName` | `Edm.String` | retrievable, filterable |
+| `sourceLink` | `Edm.String` | retrievable |
+
+### Example: provision and seed via Azure CLI + REST
+
+```bash
+SEARCH_ENDPOINT="https://<your-search>.search.windows.net"
+INDEX_NAME="contoso-outdoors"
+TOKEN=$(az account get-access-token --resource https://search.azure.com --query accessToken -o tsv)
+
+# 1. Create the index.
+curl -X PUT "$SEARCH_ENDPOINT/indexes/$INDEX_NAME?api-version=2024-07-01" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{
+    "name": "contoso-outdoors",
+    "fields": [
+      { "name": "id",         "type": "Edm.String", "key": true,  "filterable": true,  "searchable": false, "retrievable": true },
+      { "name": "content",    "type": "Edm.String", "key": false, "filterable": false, "searchable": true,  "retrievable": true, "analyzer": "standard.lucene" },
+      { "name": "sourceName", "type": "Edm.String", "key": false, "filterable": true,  "searchable": false, "retrievable": true },
+      { "name": "sourceLink", "type": "Edm.String", "key": false, "filterable": false, "searchable": false, "retrievable": true }
+    ]
+  }'
+
+# 2. Upload three Contoso Outdoors documents matching the queries below.
+curl -X POST "$SEARCH_ENDPOINT/indexes/$INDEX_NAME/docs/index?api-version=2024-07-01" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{
+    "value": [
+      { "@search.action": "mergeOrUpload", "id": "return-policy",  "sourceName": "Contoso Outdoors Return Policy",     "sourceLink": "https://contoso.com/policies/returns",       "content": "Customers may return any item within 30 days of delivery. Items should be unused and include original packaging. Refunds are issued to the original payment method within 5 business days of inspection. As a thank you, every accepted return ships back with a complimentary Contoso TrailRunner sticker pack, item code TR-CANARY-7821." },
+      { "@search.action": "mergeOrUpload", "id": "shipping-guide", "sourceName": "Contoso Outdoors Shipping Guide",    "sourceLink": "https://contoso.com/help/shipping",          "content": "Standard shipping is free on orders over $50 and typically arrives in 3-5 business days within the continental United States. Expedited options are available at checkout. Use promo code SHIP-CANARY-4493 at checkout for a one-time free overnight upgrade on your first order." },
+      { "@search.action": "mergeOrUpload", "id": "tent-care",      "sourceName": "TrailRunner Tent Care Instructions", "sourceLink": "https://contoso.com/manuals/trailrunner-tent", "content": "Clean the tent fabric with lukewarm water and a non-detergent soap. Allow it to air dry completely before storage and avoid prolonged UV exposure to extend the lifespan of the waterproof coating. Replacement waterproofing kits are stocked under SKU TENT-CANARY-9067." }
+    ]
+  }'
+```
+
+You can also point the sample at any existing index that exposes the four fields above; the sample reads `content`, `sourceName`, and `sourceLink` as projected by the search results.
+
+## Configuration
+
+Copy the template and fill in your endpoints:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env`:
+
+```env
+AZURE_AI_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+AZURE_SEARCH_ENDPOINT=https://<your-search>.search.windows.net
+AZURE_SEARCH_INDEX_NAME=contoso-outdoors
+AZURE_BEARER_TOKEN_FOUNDRY=DefaultAzureCredential
+AZURE_BEARER_TOKEN_SEARCH=DefaultAzureCredential
+ASPNETCORE_URLS=http://+:8088
+ASPNETCORE_ENVIRONMENT=Development
+```
+
+> **Note:** `.env` is gitignored. The `.env.example` template is checked in as a reference.
+
+## Running directly (contributors)
+
+This project uses `ProjectReference` to build against the local Agent Framework source.
+
+```bash
+cd dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag
+AGENT_NAME=hosted-azure-search-rag dotnet run
+```
+
+The agent will start on `http://localhost:8088`. The sample assumes the search index has already been provisioned and seeded (see "Provisioning the search index" above).
+
+### Test it
+
+Using the Azure Developer CLI:
+
+```bash
+azd ai agent invoke --local "What is your return policy?"
+azd ai agent invoke --local "How long does shipping take?"
+azd ai agent invoke --local "How do I clean my tent?"
+```
+
+Or with curl:
+
+```bash
+curl -X POST http://localhost:8088/responses \
+  -H "Content-Type: application/json" \
+  -d '{"input": "What is your return policy?", "model": "hosted-azure-search-rag"}'
+```
+
+## Running with Docker
+
+Since this project uses `ProjectReference`, use `Dockerfile.contributor` which takes a pre-published output.
+
+### 1. Publish for the container runtime (Linux Alpine)
+
+```bash
+dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+```
+
+### 2. Build the Docker image
+
+```bash
+docker build -f Dockerfile.contributor -t hosted-azure-search-rag .
+```
+
+### 3. Run the container
+
+Generate two bearer tokens on your host (one per audience) and pass them to the container. A single Azure AD token has only one `aud` claim, so Foundry and Azure AI Search require separate tokens.
+
+```bash
+# Generate tokens (each expires in ~1 hour)
+export AZURE_BEARER_TOKEN_FOUNDRY=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
+export AZURE_BEARER_TOKEN_SEARCH=$(az account get-access-token --resource https://search.azure.com --query accessToken -o tsv)
+
+# Run with both tokens
+docker run --rm -p 8088:8088 \
+  -e AGENT_NAME=hosted-azure-search-rag \
+  -e AZURE_BEARER_TOKEN_FOUNDRY=$AZURE_BEARER_TOKEN_FOUNDRY \
+  -e AZURE_BEARER_TOKEN_SEARCH=$AZURE_BEARER_TOKEN_SEARCH \
+  --env-file .env \
+  hosted-azure-search-rag
+```
+
+### 4. Test it
+
+Using the Azure Developer CLI:
+
+```bash
+azd ai agent invoke --local "What is your return policy?"
+```
+
+## How RAG works in this sample
+
+The `TextSearchProvider` runs a keyword search against the configured Azure AI Search index **before each model invocation**. When the index is seeded with the three Contoso Outdoors documents from the provisioning section above:
+
+| User query mentions | Search result injected |
+|---|---|
+| "return", "refund" | Contoso Outdoors Return Policy (canary token: `TR-CANARY-7821`) |
+| "shipping", "promo" | Contoso Outdoors Shipping Guide (canary token: `SHIP-CANARY-4493`) |
+| "tent", "fabric" | TrailRunner Tent Care Instructions (canary token: `TENT-CANARY-9067`) |
+
+The model receives the top three search results as additional context and cites the source in its response. Each seeded document includes a unique `*-CANARY-*` token that does not exist in any model training data, so the integration tests can prove an answer was grounded in retrieved content (not fabricated from training) by asking for the canary and asserting it appears in the response.
+
+Replace the seed documents (or point the sample at an existing index with your own content) to ground the agent in your own knowledge base.
+
+## NuGet package users
+
+If you are consuming the Agent Framework as a NuGet package (not building from source), use the standard `Dockerfile` instead of `Dockerfile.contributor`. See the commented section in `HostedAzureSearchRag.csproj` for the `PackageReference` alternative.

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/agent.manifest.yaml

@@ -0,0 +1,31 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/AgentManifest.yaml
+name: hosted-azure-search-rag
+displayName: "Hosted Azure AI Search RAG Agent"
+
+description: >
+  A support specialist agent for Contoso Outdoors with RAG capabilities backed by
+  Azure AI Search. Uses TextSearchProvider with a SearchClient adapter to ground
+  answers in product documentation indexed in Azure AI Search before each model
+  invocation.
+
+metadata:
+  tags:
+    - AI Agent Hosting
+    - Azure AI AgentServer
+    - Responses Protocol
+    - RAG
+    - Azure AI Search
+    - Agent Framework
+
+template:
+  name: hosted-azure-search-rag
+  kind: hosted
+  protocols:
+    - protocol: responses
+      version: 1.0.0
+  resources:
+    cpu: "0.25"
+    memory: 0.5Gi
+parameters:
+  properties: []
+resources: []

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/agent.yaml

@@ -0,0 +1,9 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml
+kind: hosted
+name: hosted-azure-search-rag
+protocols:
+  - protocol: responses
+    version: 1.0.0
+resources:
+  cpu: "0.25"
+  memory: 0.5Gi

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files/.dockerignore

@@ -0,0 +1,6 @@
+**/bin
+**/obj
+**/.vs
+**/.vscode
+.env
+*.user

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files/.env.example

@@ -0,0 +1,5 @@
+AZURE_AI_PROJECT_ENDPOINT=<your-azure-ai-project-endpoint>
+ASPNETCORE_URLS=http://+:8088
+ASPNETCORE_ENVIRONMENT=Development
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+AZURE_BEARER_TOKEN=DefaultAzureCredential

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files/Dockerfile

@@ -0,0 +1,17 @@
+# Use the official .NET 10.0 ASP.NET runtime as a parent image
+FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
+WORKDIR /app
+
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /src
+COPY . .
+RUN dotnet restore
+RUN dotnet publish -c Release -o /app/publish
+
+# Final stage
+FROM base AS final
+WORKDIR /app
+COPY --from=build /app/publish .
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+ENTRYPOINT ["dotnet", "HostedFiles.dll"]

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files/Dockerfile.contributor

@@ -0,0 +1,19 @@
+# Dockerfile for contributors building from the agent-framework repository source.
+#
+# This project uses ProjectReference to the local Microsoft.Agents.AI.Foundry source,
+# which means a standard multi-stage Docker build cannot resolve dependencies outside
+# this folder. Instead, pre-publish the app targeting the container runtime and copy
+# the output into the container:
+#
+#   dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+#   docker build -f Dockerfile.contributor -t hosted-files .
+#   docker run --rm -p 8088:8088 -e AGENT_NAME=hosted-files -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN --env-file .env hosted-files
+#
+# For end-users consuming the NuGet package (not ProjectReference), use the standard
+# Dockerfile which performs a full dotnet restore + publish inside the container.
+FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final
+WORKDIR /app
+COPY out/ .
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+ENTRYPOINT ["dotnet", "HostedFiles.dll"]

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files/HostedFiles.csproj

@@ -0,0 +1,40 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <CentralPackageTransitivePinningEnabled>false</CentralPackageTransitivePinningEnabled>
+    <RootNamespace>HostedFiles</RootNamespace>
+    <AssemblyName>HostedFiles</AssemblyName>
+    <NoWarn>$(NoWarn);</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="DotNetEnv" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <!-- Bake demo resources into the published output so the deployed agent's
+         tools can read them from /app/resources/ inside the container. -->
+    <Content Include="resources\**\*">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </Content>
+  </ItemGroup>
+
+  <!-- For contributors: uses ProjectReference to build against local source -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry.Hosting\Microsoft.Agents.AI.Foundry.Hosting.csproj" />
+  </ItemGroup>
+
+  <!-- For end-users: uncomment the PackageReference below and remove the ProjectReference above
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.Foundry" Version="1.0.0" />
+    <PackageReference Include="Microsoft.Agents.AI.Foundry.Hosting" Version="1.0.0" />
+  </ItemGroup>
+  -->
+
+</Project>

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files/Program.cs

@@ -0,0 +1,223 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// Hosted Files Agent - A hosted agent that exposes two distinct file knowledge sources
+// through scoped, security-hardened tools:
+//
+//   * Bundled files (image-baked) — files copied into the published output via the csproj
+//     <Content Include="resources\**"> rule. Live at /app/resources/ inside the container.
+//     Author-shipped knowledge that ships with every session.
+//
+//   * Session files (per-session $HOME volume) — files uploaded at runtime via the alpha
+//     Azure.AI.Projects.AgentSessionFiles SDK. Live at $HOME inside the per-session
+//     container, which the platform sets to /home/session by default
+//     (container-image-spec.md line 127, "If you use the session files API, $HOME is
+//     also the base path for those operations").
+//
+// Each source is exposed via a separate tool pair, each rooted at its own directory.
+// Tools take a fileName, not a path: Path.GetFileName strips any directory components,
+// then a canonicalize + StartsWith(root) check enforces the boundary. The model cannot
+// be tricked into reading /etc/passwd or any path outside its tool's root, even via
+// indirect prompt injection in an uploaded file.
+//
+// Required environment variables:
+//   AZURE_AI_PROJECT_ENDPOINT         - Azure AI Foundry project endpoint
+//   AZURE_AI_MODEL_DEPLOYMENT_NAME    - Model deployment name (default: gpt-4o)
+//
+// Optional:
+//   AGENT_NAME                        - Agent name (default: hosted-files)
+//   BUNDLED_FILES_DIR                 - Override the bundled-files root
+//                                       (default: <baseDir>/resources, i.e. /app/resources/)
+//   HOME                              - Standard env var; the per-session sandbox volume
+//                                       (default: /home/session in the platform-managed container)
+
+using System.ComponentModel;
+using Azure.AI.Projects;
+using Azure.Core;
+using Azure.Identity;
+using DotNetEnv;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry.Hosting;
+using Microsoft.Extensions.AI;
+
+// Load .env file if present (for local development)
+Env.TraversePath().Load();
+
+// Bypass SampleEnvironment alias (which prompts on missing env vars) for optional values.
+string? GetOptionalEnv(string key) => System.Environment.GetEnvironmentVariable(key);
+
+string endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
+string deploymentName = GetOptionalEnv("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";
+
+// Use a chained credential: try a temporary dev token first (for local Docker debugging),
+// then fall back to DefaultAzureCredential (for local dev via dotnet run / managed identity in production).
+TokenCredential credential = new ChainedTokenCredential(
+    new DevTemporaryTokenCredential(),
+    new DefaultAzureCredential());
+
+// ── File roots (canonicalized once) ──────────────────────────────────────────
+
+// Bundled root: where csproj <Content Include="resources\**"> lands at runtime.
+// In the container that resolves to /app/resources/.
+string bundledRoot = Path.GetFullPath(
+    GetOptionalEnv("BUNDLED_FILES_DIR")
+    ?? Path.Combine(AppContext.BaseDirectory, "resources"));
+
+// Session root: the per-session $HOME volume mounted by the Foundry platform.
+// Files uploaded via AgentSessionFiles.UploadSessionFileAsync(sessionStoragePath: "foo")
+// land at $HOME/foo per container-image-spec.md line 172.
+string sessionRoot = Path.GetFullPath(
+    GetOptionalEnv("HOME")
+    ?? "/home/session");
+
+// ── Tools: bundled files (image-baked, /app/resources/) ──────────────────────
+
+[Description("List the names of files bundled with the agent (built-in knowledge that ships with the image).")]
+string ListBundledFiles() => SafeListNames(bundledRoot);
+
+[Description("Read the full text contents of a bundled file by name. Bundled files are built-in knowledge shipped with the agent image.")]
+string ReadBundledFile(
+    [Description("Name of the bundled file (no directory components). Must be one of the names returned by ListBundledFiles.")] string fileName)
+    => SafeRead(bundledRoot, fileName, scope: "bundled files");
+
+// ── Tools: session files (per-session $HOME) ─────────────────────────────────
+
+[Description("List the names of files uploaded into the current session sandbox by the user (e.g., via AgentSessionFiles.UploadSessionFileAsync).")]
+string ListSessionFiles() => SafeListNames(sessionRoot);
+
+[Description("Read the full text contents of a file uploaded into the current session by name. Session files are user-supplied data that lives only for the lifetime of this session.")]
+string ReadSessionFile(
+    [Description("Name of the session file (no directory components). Must be one of the names returned by ListSessionFiles.")] string fileName)
+    => SafeRead(sessionRoot, fileName, scope: "session files");
+
+// ── Path-safe helpers (defense-in-depth: GetFileName + canonicalize + StartsWith(root)) ──
+
+string SafeListNames(string root)
+{
+    try
+    {
+        if (!Directory.Exists(root))
+        {
+            return string.Empty;
+        }
+
+        return string.Join(
+            Environment.NewLine,
+            Directory.EnumerateFiles(root).Select(Path.GetFileName));
+    }
+    catch (Exception ex)
+    {
+        return $"Error listing files: {ex.Message}";
+    }
+}
+
+string SafeRead(string root, string fileName, string scope)
+{
+    try
+    {
+        // Step 1: strip any directory components the model might have included.
+        string safeName = Path.GetFileName(fileName);
+        if (string.IsNullOrEmpty(safeName))
+        {
+            return $"File '{fileName}' not found in {scope}.";
+        }
+
+        // Step 2: combine with the root and canonicalize.
+        string fullPath = Path.GetFullPath(Path.Combine(root, safeName));
+
+        // Step 3: enforce the prefix boundary so a crafted name still cannot escape.
+        string rootPrefix = root.EndsWith(Path.DirectorySeparatorChar)
+            ? root
+            : root + Path.DirectorySeparatorChar;
+        if (!fullPath.StartsWith(rootPrefix, StringComparison.Ordinal))
+        {
+            return $"File '{fileName}' not found in {scope}.";
+        }
+
+        return File.Exists(fullPath)
+            ? File.ReadAllText(fullPath)
+            : $"File '{fileName}' not found in {scope}.";
+    }
+    catch (Exception ex)
+    {
+        return $"Error reading '{fileName}': {ex.Message}";
+    }
+}
+
+// ── Create and host the agent ────────────────────────────────────────────────
+
+AIAgent agent = new AIProjectClient(new Uri(endpoint), credential)
+    .AsAIAgent(
+        model: deploymentName,
+        instructions: """
+            You are a friendly assistant that answers questions over two file sources:
+
+              - Bundled files: built-in knowledge that ships with the agent image
+                (e.g., reference reports the author packaged with you). Tools:
+                ListBundledFiles, ReadBundledFile.
+
+              - Session files: user-uploaded data for this session only (e.g., a CSV
+                the user wants you to analyse). Tools: ListSessionFiles, ReadSessionFile.
+
+            Pick the tool pair by intent. If a name could match either source, list
+            both first. Always read the file before answering; do not guess. Quote
+            numbers and figures verbatim from the file.
+            """,
+        name: GetOptionalEnv("AGENT_NAME") ?? "hosted-files",
+        description: "Hosted agent that answers questions over bundled (image-baked) and session-uploaded files via two scoped tool pairs.",
+        tools:
+        [
+            AIFunctionFactory.Create(ListBundledFiles),
+            AIFunctionFactory.Create(ReadBundledFile),
+            AIFunctionFactory.Create(ListSessionFiles),
+            AIFunctionFactory.Create(ReadSessionFile),
+        ]);
+
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddFoundryResponses(agent);
+
+var app = builder.Build();
+app.MapFoundryResponses();
+
+if (app.Environment.IsDevelopment())
+{
+    app.MapFoundryResponses("openai/v1");
+}
+
+app.Run();
+
+/// <summary>
+/// A <see cref="TokenCredential"/> for local Docker debugging only.
+/// Reads a pre-fetched bearer token from the <c>AZURE_BEARER_TOKEN</c> environment variable
+/// once at startup. This should NOT be used in production.
+///
+/// Generate a token on your host and pass it to the container:
+///   export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
+///   docker run -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN ...
+/// </summary>
+internal sealed class DevTemporaryTokenCredential : TokenCredential
+{
+    private const string EnvironmentVariable = "AZURE_BEARER_TOKEN";
+    private readonly string? _token;
+
+    public DevTemporaryTokenCredential()
+    {
+        this._token = System.Environment.GetEnvironmentVariable(EnvironmentVariable);
+    }
+
+    public override AccessToken GetToken(TokenRequestContext requestContext, CancellationToken cancellationToken)
+        => this.GetAccessToken();
+
+    public override ValueTask<AccessToken> GetTokenAsync(TokenRequestContext requestContext, CancellationToken cancellationToken)
+        => new(this.GetAccessToken());
+
+    private AccessToken GetAccessToken()
+    {
+        if (string.IsNullOrEmpty(this._token) || this._token == "DefaultAzureCredential")
+        {
+            throw new CredentialUnavailableException($"{EnvironmentVariable} environment variable is not set.");
+        }
+
+        return new AccessToken(this._token, DateTimeOffset.UtcNow.AddHours(1));
+    }
+}

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files/README.md

@@ -0,0 +1,128 @@
+# Hosted-Files
+
+A hosted agent that demonstrates **two distinct file knowledge sources** through scoped, security-hardened tools:
+
+- **Bundled files** (image-baked) — files the author packages with the agent at build time. Live at `/app/resources/` inside the container, copied from this project's [`resources/`](./resources/) folder via the csproj `<Content Include="resources\**\*" CopyToOutputDirectory="PreserveNewest" />` rule.
+- **Session files** (per-session `$HOME` volume) — files the user uploads at runtime via the alpha `Azure.AI.Projects.AgentSessionFiles` SDK. Live at `$HOME` inside the per-session container. The Foundry platform sets `HOME=/home/session` by default and roots the session-files API there per [`container-image-spec.md` line 172](https://github.com/microsoft/foundrysdk-specs/blob/main/specs/agents/hosted_agents/container-spec/docs/container-image-spec.md): *"If you use the session files API, `$HOME` is also the base path for those operations; any paths given in those API endpoints will be relative to `$HOME`."*
+
+## Tool surface
+
+Each source is exposed via its own tool pair, rooted at its own directory. The model picks by intent.
+
+| Tool | Source | Root |
+|------|--------|------|
+| `ListBundledFiles` | Bundled (image-baked) | `/app/resources/` |
+| `ReadBundledFile` | Bundled (image-baked) | `/app/resources/` |
+| `ListSessionFiles` | Session-uploaded | `$HOME` (`/home/session`) |
+| `ReadSessionFile` | Session-uploaded | `$HOME` (`/home/session`) |
+
+## Security model — distinct tools, distinct sandboxes
+
+Each tool takes a `fileName` (no directory components allowed) and enforces three layers of defence inside the implementation:
+
+1. **`Path.GetFileName(input)`** strips any directory parts from the model-supplied name. `"../../etc/passwd"` becomes `"passwd"`.
+2. **`Path.GetFullPath(Combine(root, name))`** canonicalises the path.
+3. **`fullPath.StartsWith(root + DirectorySeparatorChar)`** rejects anything that resolves outside the tool's root.
+
+Failures return a controlled `"File '<input>' not found in <scope>."` rather than throwing or exposing the canonical path.
+
+This is why the agent has four narrowly-scoped tools instead of a single `ReadFile(path)`:
+
+- **Smaller per-tool attack surface.** Each tool has one purpose, one root, and no path-typed parameter. Even a buggy implementation can only leak its own directory.
+- **Cross-boundary access is impossible by schema.** A prompt-injection attempt to make the bundled tool read a session path (or vice versa) does not even compile in the tool schema the model sees.
+- **Read-only, non-recursive listing.** No write tools, no glob, no `..`.
+
+## Companion
+
+[`Using-Samples/SessionFilesClient`](../Using-Samples/SessionFilesClient/) — a thin chat REPL (same shape as [`SimpleAgent`](../Using-Samples/SimpleAgent/)) that points at the deployed Hosted-Files endpoint via `FoundryAgent` and lets you ask questions whose answers come from either file source.
+
+## Live proof of the session-files contract
+
+The end-to-end alpha-SDK round trip (client uploads via `AgentSessionFiles.UploadSessionFileAsync` → file arrives at `$HOME/<name>` inside the per-session container → agent's `ReadSessionFile` tool reads it → response quotes the verbatim contents) is exercised live by [`SessionFilesHostedAgentTests.UploadedFile_IsReadByHostedAgentAsync`](../../../../../tests/Foundry.Hosting.IntegrationTests/SessionFilesHostedAgentTests.cs) against the matching `session-files` scenario in the integration test container.
+
+## Prerequisites
+
+- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
+- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- Azure CLI logged in (`az login`)
+
+## Configuration
+
+Copy the template and fill in your project endpoint:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env`:
+
+```env
+AZURE_AI_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>
+ASPNETCORE_URLS=http://+:8088
+ASPNETCORE_ENVIRONMENT=Development
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+```
+
+> `.env` is gitignored. The `.env.example` template is checked in as a reference.
+
+## Running directly (contributors)
+
+```bash
+cd dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files
+AGENT_NAME=hosted-files dotnet run
+```
+
+The agent starts on `http://localhost:8088`.
+
+## Try it from the SessionFilesClient REPL
+
+### Bundled files (works against any deployment, including local)
+
+```bash
+cd ../Using-Samples/SessionFilesClient
+$env:AGENT_ENDPOINT = "http://localhost:8088"
+$env:AGENT_NAME = "hosted-files"
+dotnet run
+
+You> What is the total revenue in the contoso file?
+Agent> The contoso file reports total revenue of "$1,482.6M".
+```
+
+The agent calls `ListBundledFiles`, sees `contoso_q1_2026_report.txt`, calls `ReadBundledFile("contoso_q1_2026_report.txt")` (which resolves under `/app/resources/`), and quotes the figure verbatim.
+
+### Session files (against a deployed agent)
+
+Upload a file to a specific session via `azd ai agent files upload` or via the alpha `AgentSessionFiles` SDK (see the integration test for the SDK call), then ask the agent about it. The agent's `ReadSessionFile` tool reads from `$HOME` and surfaces the content the same way.
+
+## Running with Docker
+
+This project uses `ProjectReference`, so use `Dockerfile.contributor` which takes a pre-published output:
+
+```bash
+dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+docker build -f Dockerfile.contributor -t hosted-files .
+
+export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
+docker run --rm -p 8088:8088 \
+  -e AGENT_NAME=hosted-files \
+  -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN \
+  --env-file .env \
+  hosted-files
+```
+
+The bundled `resources/` folder is part of the published output and ships inside the image.
+
+## NuGet package users
+
+If consuming the Agent Framework as a NuGet package, use the standard `Dockerfile` instead of `Dockerfile.contributor` and switch the `ProjectReference` entries in `HostedFiles.csproj` to `PackageReference` (commented section in the csproj).
+
+## Adding more bundled files
+
+Drop additional text files into [`resources/`](./resources/). The csproj `<Content Include="resources\**\*" CopyToOutputDirectory="PreserveNewest" />` rule picks them up on the next `dotnet build` / `docker build`.
+
+## Overrides
+
+| Env var | Purpose | Default |
+|---------|---------|---------|
+| `BUNDLED_FILES_DIR` | Override the bundled-files root the tools read from. | `<process base dir>/resources` (`/app/resources/` in container) |
+| `HOME` | The per-session sandbox volume root the session-files tools read from. Set by the Foundry platform; can be overridden for local testing. | `/home/session` |

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files/agent.manifest.yaml

@@ -0,0 +1,30 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/AgentManifest.yaml
+name: hosted-files
+displayName: "Hosted Files Agent"
+
+description: >
+  A hosted agent that answers questions over a small set of files bundled
+  with its container image (under /app/resources/). Two local C# function
+  tools (ListFiles, ReadFile) surface the bundled file contents to the model.
+
+metadata:
+  tags:
+    - AI Agent Hosting
+    - Azure AI AgentServer
+    - Responses Protocol
+    - Bundled Files
+    - Local Tools
+    - Agent Framework
+
+template:
+  name: hosted-files
+  kind: hosted
+  protocols:
+    - protocol: responses
+      version: 1.0.0
+  resources:
+    cpu: "0.25"
+    memory: 0.5Gi
+parameters:
+  properties: []
+resources: []