Revert unnecessary bool simplification in WorkflowAgent input selection

Polish WorkflowAgent restore resume logic and tests
Fix WorkflowAgent pending request resume after session restore
2026-06-16 21:04:09 +08:00 · 2026-05-27 21:30:44 +00:00 · 2026-05-27 18:38:44 +00:00 · 2026-05-27 18:37:40 +00:00 · 2026-05-27 18:29:13 +00:00 · 2026-05-27 14:54:00 +01:00
546 changed files with 39150 additions and 5693 deletions
@@ -1,15 +1,19 @@
 {
  "name": "Python 3",
-  "image": "mcr.microsoft.com/devcontainers/python:3.13-bullseye",
+  "image": "mcr.microsoft.com/devcontainers/python:3.14-bookworm",
  "features": {
    "ghcr.io/va-h/devcontainers-features/uv:1": {},
-    "ghcr.io/devcontainers/features/azure-cli:1.2.8": {}
+    "ghcr.io/devcontainers/features/docker-in-docker:3": {},
+    "ghcr.io/devcontainers/features/azure-cli:1.2.9": {},
+    "ghcr.io/devcontainers/features/copilot-cli:1": {}
  },
  "postCreateCommand": "bash ./devsetup.sh",
  "workspaceFolder": "/workspaces/agent-framework/python/",
  "customizations": {
    "vscode": {
      "extensions": [
+        "GitHub.copilot",
+        "GitHub.vscode-github-actions",
        "ms-python.python",
        "ms-windows-ai-studio.windows-ai-studio",
        "littlefoxteam.vscode-python-test-adapter"
@@ -8,7 +8,7 @@ ignorePatterns:
  - pattern: "./blob"
  - pattern: "./issues"
  - pattern: "./discussions"
-  - pattern: "./pulls"
+  - pattern: "./pull"
  - pattern: "https:\/\/platform.openai.com"
  - pattern: "http:\/\/localhost"
  - pattern: "http:\/\/127.0.0.1"
@@ -17,7 +17,7 @@ runs:
    using: "composite"
    steps:
      - name: Set up uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
        with:
            version-file: "python/pyproject.toml"
            enable-cache: true
@@ -32,7 +32,13 @@ runs:
              if grep -q "name = \"$pkg\"" "$f"; then
                pkg_dir=$(dirname "$f" | sed 's|python/||')
                echo "Excluding workspace package: $pkg ($pkg_dir)"
-                sed -i.bak '/\[tool\.uv\.workspace\]/a\exclude = ["'"$pkg_dir"'"]' python/pyproject.toml
+                if awk '/^\[tool\.uv\.workspace\]/{f=1;next} /^\[/{f=0} f && /^exclude = \[/{found=1} END{exit !found}' python/pyproject.toml; then
+                  if ! awk '/^\[tool\.uv\.workspace\]/{f=1;next} /^\[/{f=0} f && /^exclude = \[/ && index($0, "\"'"$pkg_dir"'\"")' python/pyproject.toml | grep -q .; then
+                    sed -i.bak '/\[tool\.uv\.workspace\]/,/^\[/ { /^exclude = \[/ s|\]|, "'"$pkg_dir"'"]| }' python/pyproject.toml
+                  fi
+                else
+                  sed -i.bak '/\[tool\.uv\.workspace\]/a\exclude = ["'"$pkg_dir"'"]' python/pyproject.toml
+                fi
                sed -i.bak '/'"$pkg"' = { workspace = true }/d' python/pyproject.toml
              fi
            done
@@ -40,4 +46,4 @@ runs:
      - name: Install the project
        shell: bash
        run: |
-          cd python && uv sync --all-packages --all-extras --dev -U --prerelease=if-necessary-or-explicit
+          cd python && uv sync --all-packages --all-extras --dev --prerelease=if-necessary-or-explicit
@@ -24,7 +24,7 @@ runs:
  using: "composite"
  steps:
    - name: Set up Node.js environment
-      uses: actions/setup-node@v6
+      uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
      with:
        node-version: 22

@@ -37,7 +37,7 @@ runs:
      run: copilot --version && copilot -p "What can you do in one sentence?"

    - name: Azure CLI Login
-      uses: azure/login@v2
+      uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
      with:
        client-id: ${{ inputs.azure-client-id }}
        tenant-id: ${{ inputs.azure-tenant-id }}
@@ -44,9 +44,15 @@ updates:

  # Maintain dependencies for github-actions
  - package-ecosystem: "github-actions"
-    # Workflow files stored in the
-    # default location of `.github/workflows`
-    directory: "/"
+    # Cover both the standard workflow location and our composite actions.
+    # With `directory: "/"` Dependabot only scans `.github/workflows/*.{yml,yaml}`
+    # plus a root-level `action.yml/action.yaml`. It does NOT recurse into
+    # `.github/actions/*/action.yml`, so the glob below is required to keep the
+    # composite actions in `.github/actions/<name>/` up to date as well.
+    # Ref: https://docs.github.com/en/code-security/dependabot/working-with-dependabot/dependabot-options-reference#directories-or-directory--
+    directories:
+      - "/"
+      - "/.github/actions/*"
    schedule:
      interval: "weekly"
      day: "sunday"
@@ -32,13 +32,13 @@ jobs:

    steps:
      - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          persist-credentials: false

      # Initializes the CodeQL tools for scanning.
      - name: Initialize CodeQL
-        uses: github/codeql-action/init@v4
+        uses: github/codeql-action/init@9e0d7b8d25671d64c341c19c0152d693099fb5ba # v4
        with:
          languages: ${{ matrix.language }}
          # If you wish to specify custom queries, you can do so here or in a config file.
@@ -51,7 +51,7 @@ jobs:
      # Autobuild attempts to build any compiled languages  (C/C++, C#, Go, or Java).
      # If this step fails, then you should remove it and run the build manually (see below)
      - name: Autobuild
-        uses: github/codeql-action/autobuild@v4
+        uses: github/codeql-action/autobuild@9e0d7b8d25671d64c341c19c0152d693099fb5ba # v4

      # ℹ️ Command-line programs to run using the OS shell.
      # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
@@ -64,6 +64,6 @@ jobs:
      #     ./location_of_script_within_repo/buildscript.sh

      - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v4
+        uses: github/codeql-action/analyze@9e0d7b8d25671d64c341c19c0152d693099fb5ba # v4
        with:
          category: "/language:${{matrix.language}}"
@@ -66,7 +66,7 @@ jobs:

      - name: Check PR author team membership
        id: check
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
        env:
          TEAM_NAME: ${{ secrets.DEVELOPER_TEAM }}
          PR_NUMBER: ${{ steps.pr.outputs.pr_number }}
@@ -116,7 +116,7 @@ jobs:
    steps:
      # Safe checkout: base repo only, not the untrusted PR head.
      - name: Checkout target repo base
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          ref: ${{ github.event_name == 'pull_request_target' && github.event.pull_request.base.sha || github.sha }}
          fetch-depth: 0
@@ -125,7 +125,7 @@ jobs:

      # Private DevFlow checkout: the PAT/token grants access to this repo's code.
      - name: Checkout DevFlow
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          repository: ${{ env.DEVFLOW_REPOSITORY }}
          ref: ${{ env.DEVFLOW_REF }}
@@ -135,12 +135,12 @@ jobs:
          path: devflow

      - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
        with:
          python-version: "3.13"

      - name: Set up uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
        with:
          version: "0.11.x"
          enable-cache: true
@@ -41,8 +41,8 @@ jobs:
      functionsChanged: ${{ steps.filter.outputs.functions }}
      coreChanged: ${{ steps.filter.outputs.core }}
    steps:
-      - uses: actions/checkout@v6
-      - uses: dorny/paths-filter@v3
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: dorny/paths-filter@d1c1ffe0248fe513906c8e24db8ea791d46f8590 # v3
        id: filter
        with:
          filters: |
@@ -111,7 +111,7 @@ jobs:

    runs-on: ${{ matrix.os }}
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
            persist-credentials: false
            sparse-checkout: |
@@ -122,7 +122,7 @@ jobs:
              declarative-agents

      - name: Setup dotnet
-        uses: actions/setup-dotnet@v5.2.0
+        uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7 # v5.2.0
        with:
          global-json-file: ${{ github.workspace }}/dotnet/global.json
      - name: Build dotnet solutions
@@ -181,7 +181,7 @@ jobs:
    runs-on: ${{ matrix.os }}
    environment: ${{ matrix.environment }}
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
            persist-credentials: false
            sparse-checkout: |
@@ -202,7 +202,7 @@ jobs:
          echo "COSMOSDB_EMULATOR_AVAILABLE=true" >> $env:GITHUB_ENV

      - name: Setup dotnet
-        uses: actions/setup-dotnet@v5.2.0
+        uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7 # v5.2.0
        with:
          global-json-file: ${{ github.workspace }}/dotnet/global.json

@@ -271,7 +271,7 @@ jobs:

      - name: Azure CLI Login
        if: github.event_name != 'pull_request' && matrix.integration-tests
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -318,7 +318,7 @@ jobs:
      # Generate test reports and check coverage
      - name: Generate test reports
        if: matrix.targetFramework == env.COVERAGE_FRAMEWORK
-        uses: danielpalme/ReportGenerator-GitHub-Action@5.5.3
+        uses: danielpalme/ReportGenerator-GitHub-Action@2a82782178b2816d9d6960a7345fdd164791b323 # 5.5.3
        with:
          reports: "./TestResults/Coverage/**/*.cobertura.xml"
          targetdir: "./TestResults/Reports"
@@ -326,7 +326,7 @@ jobs:

      - name: Upload coverage report artifact
        if: matrix.targetFramework == env.COVERAGE_FRAMEWORK
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: CoverageReport-${{ matrix.os }}-${{ matrix.targetFramework }}-${{ matrix.configuration }} # Artifact name
          path: ./TestResults/Reports # Directory containing files to upload
@@ -338,7 +338,7 @@ jobs:

      - name: Upload integration test results
        if: always() && github.event_name != 'pull_request' && matrix.integration-tests
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: dotnet-test-results-${{ matrix.targetFramework }}-${{ matrix.os }}
          path: IntegrationTestResults/**/*.junit
@@ -356,7 +356,7 @@ jobs:
    env:
      configuration: Release
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          persist-credentials: false
          sparse-checkout: |
@@ -366,7 +366,7 @@ jobs:
            python

      - name: Setup dotnet
-        uses: actions/setup-dotnet@v5.2.0
+        uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7 # v5.2.0
        with:
          global-json-file: ${{ github.workspace }}/dotnet/global.json

@@ -381,7 +381,7 @@ jobs:
        run: dotnet build dotnet/tests/Foundry.Hosting.IntegrationTests/Foundry.Hosting.IntegrationTests.csproj -c "$configuration" --warnaserror

      - name: Azure CLI Login
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -442,7 +442,7 @@ jobs:
    runs-on: ubuntu-latest
    environment: integration
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          persist-credentials: false
          sparse-checkout: |
@@ -453,7 +453,7 @@ jobs:
            declarative-agents

      - name: Setup dotnet
-        uses: actions/setup-dotnet@v5.2.0
+        uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7 # v5.2.0
        with:
          global-json-file: ${{ github.workspace }}/dotnet/global.json

@@ -465,7 +465,7 @@ jobs:
          dotnet build ./tests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests -c Release -f net10.0 --warnaserror

      - name: Azure CLI Login
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -522,7 +522,7 @@ jobs:

      - name: Upload functions test results
        if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: dotnet-test-results-functions-net10.0-ubuntu-latest
          path: IntegrationTestResults/**/*.junit
@@ -560,14 +560,14 @@ jobs:
      - name: Fail workflow if tests failed
        id: check_tests_failed
        if: contains(join(needs.*.result, ','), 'failure')
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
        with:
          script: core.setFailed('Integration Tests Failed!')

      - name: Fail workflow if tests cancelled
        id: check_tests_cancelled
        if: contains(join(needs.*.result, ','), 'cancelled')
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
        with:
          script: core.setFailed('Integration Tests Cancelled!')

@@ -585,7 +585,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          persist-credentials: false
          sparse-checkout: |
@@ -597,12 +597,12 @@ jobs:
          python-version: "3.13"
          os: ${{ runner.os }}
      - name: Download all test results from current run
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
        with:
          pattern: dotnet-test-results-*
          path: dotnet-test-results/
      - name: Restore report history cache
-        uses: actions/cache/restore@v4
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
        with:
          path: python/dotnet-integration-report-history.json
          key: dotnet-integration-report-history-${{ github.run_id }}
@@ -619,13 +619,13 @@ jobs:
        run: cat dotnet-integration-test-report.md >> $GITHUB_STEP_SUMMARY
      - name: Save report history cache
        if: always()
-        uses: actions/cache/save@v4
+        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # 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
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: dotnet-integration-test-report
          path: |
@@ -30,7 +30,7 @@ jobs:

    steps:
      - name: Check out code
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          fetch-depth: 0
          persist-credentials: false
@@ -42,7 +42,7 @@ jobs:
      - name: Get changed files
        id: changed-files
        if: github.event_name == 'pull_request'
-        uses: jitterbit/get-changed-files@v1
+        uses: jitterbit/get-changed-files@b17fbb00bdc0c0f63fcf166580804b4d2cdc2a42 # v1
        continue-on-error: true

      - name: No C# files changed
@@ -29,7 +29,7 @@ jobs:
    environment: integration
    timeout-minutes: 60
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          ref: ${{ inputs.checkout-ref }}
          persist-credentials: false
@@ -50,7 +50,7 @@ jobs:
          echo "COSMOS_EMULATOR_AVAILABLE=true" >> $env:GITHUB_ENV

      - name: Setup dotnet
-        uses: actions/setup-dotnet@v5.2.0
+        uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7 # v5.2.0
        with:
          global-json-file: ${{ github.workspace }}/dotnet/global.json

@@ -63,7 +63,7 @@ jobs:
          done

      - name: Azure CLI Login
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -41,7 +41,7 @@ jobs:
    environment: 'integration'
    timeout-minutes: 90
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          persist-credentials: false
          sparse-checkout: |
@@ -52,13 +52,13 @@ jobs:
            declarative-agents

      - name: Setup dotnet
-        uses: actions/setup-dotnet@v5.2.0
+        uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7 # v5.2.0
        with:
          global-json-file: ${{ github.workspace }}/dotnet/global.json

      - name: Azure CLI Login
        if: github.event_name != 'pull_request'
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -123,7 +123,7 @@ jobs:

      - name: Upload results
        if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: verify-samples-results
          path: |
@@ -53,7 +53,7 @@ jobs:
          echo "repo=${GITHUB_REPOSITORY}" >> "$GITHUB_OUTPUT"

      - name: Checkout scripts
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          sparse-checkout: .github/scripts
          fetch-depth: 1
@@ -61,7 +61,7 @@ jobs:

      - name: Check issue author team membership
        id: check
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
        env:
          TEAM_NAME: ${{ secrets.DEVELOPER_TEAM }}
          ISSUE_NUMBER: ${{ steps.issue.outputs.issue_number }}
@@ -93,7 +93,7 @@ jobs:
    steps:
      # Safe checkout: base repo only.
      - name: Checkout target repo base
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          fetch-depth: 0
          persist-credentials: false
@@ -101,7 +101,7 @@ jobs:

      # Private DevFlow (maf-dashboard) checkout.
      - name: Checkout DevFlow
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          repository: ${{ env.DEVFLOW_REPOSITORY }}
          ref: ${{ env.DEVFLOW_REF }}
@@ -111,12 +111,12 @@ jobs:
          path: devflow

      - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
        with:
          python-version: "3.13"

      - name: Set up uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
        with:
          version: "0.11.x"
          enable-cache: true
@@ -126,7 +126,7 @@ jobs:
        run: uv sync --frozen

      - name: Azure CLI Login
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -137,6 +137,7 @@ jobs:
        working-directory: ${{ env.DEVFLOW_PATH }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          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 }}
@@ -149,16 +150,14 @@ jobs:
            --apply-labels

      - name: Stop after spam gate
-        if: ${{ steps.spam.outputs.decision != 'allow' }}
+        if: ${{ steps.spam.outputs.allow_triage != 'true' }}
        shell: bash
-        env:
-          SPAM_DECISION: ${{ steps.spam.outputs.decision }}
        run: |
-          echo "Stopping: spam gate decided: ${SPAM_DECISION}"
+          echo "Stopping: issue triage preflight did not allow automation."
          exit 1

      - name: Reproduce reported issue
-        if: ${{ steps.spam.outputs.decision == 'allow' }}
+        if: ${{ steps.spam.outputs.allow_triage == 'true' }}
        id: repro
        working-directory: ${{ env.DEVFLOW_PATH }}
        env:
@@ -13,7 +13,7 @@ jobs:
    permissions:
      issues: write
    steps:
-      - uses: actions/github-script@v8
+      - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
        with:
          github-token: ${{ secrets.GH_ACTIONS_PR_WRITE }}
          script: |
@@ -16,6 +16,6 @@ jobs:
      pull-requests: write

    steps:
-      - uses: actions/labeler@v6
+      - uses: actions/labeler@f27b608878404679385c85cfa523b85ccb86e213 # v6
        with:
          repo-token: "${{ secrets.GH_ACTIONS_PR_WRITE }}"
@@ -15,7 +15,7 @@ jobs:
      pull-requests: write

    steps:
-      - uses: actions/github-script@v8
+      - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
        name: "Issue/PR: update title"
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -19,13 +19,13 @@ jobs:
    runs-on: ubuntu-22.04
    # check out the latest version of the code
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          persist-credentials: false

      # Checks the status of hyperlinks in all files
      - name: Run linkspector
-        uses: umbrelladocs/action-linkspector@v1
+        uses: umbrelladocs/action-linkspector@963b6264d7de32c904942a70b488d3407453049e # v1
        with:
          reporter: local
          filter_mode: nofilter
@@ -19,7 +19,7 @@ jobs:
    steps:
      - name: Wait for required checks
        if: github.event_name == 'pull_request'
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
        env:
          TIMEOUT_SECONDS: "3600"
          INTERVAL_SECONDS: "30"
@@ -27,7 +27,7 @@ jobs:
    env:
      UV_PYTHON: ${{ matrix.python-version }}
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          fetch-depth: 0
      - name: Set up python and install the project
@@ -38,11 +38,11 @@ jobs:
          os: ${{ runner.os }}
        env:
          UV_CACHE_DIR: /tmp/.uv-cache
-      - uses: actions/cache@v5
+      - uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
        with:
          path: ~/.cache/prek
          key: prek|${{ matrix.python-version }}|${{ hashFiles('python/.pre-commit-config.yaml') }}
-      - uses: j178/prek-action@v1
+      - uses: j178/prek-action@0bb87d7f00b0c99306c8bcb8b8beba1eb581c037 # v1
        name: Run Pre-commit Hooks (excluding poe-check)
        env:
          SKIP: poe-check
@@ -64,7 +64,7 @@ jobs:
    env:
      UV_PYTHON: ${{ matrix.python-version }}
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          fetch-depth: 0
      - name: Set up python and install the project
@@ -93,7 +93,7 @@ jobs:
    env:
      UV_PYTHON: ${{ matrix.python-version }}
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          fetch-depth: 0
      - name: Set up python and install the project
@@ -124,7 +124,7 @@ jobs:
    env:
      UV_PYTHON: ${{ matrix.python-version }}
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          fetch-depth: 0
      - name: Set up python and install the project
@@ -22,7 +22,7 @@ jobs:
      UV_PYTHON: "3.13"
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          fetch-depth: 0

@@ -44,7 +44,7 @@ jobs:
      - name: Upload dependency range report
        # Always publish the report so failures are inspectable even when validation fails.
        if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: dependency-range-results
          path: python/scripts/dependencies/dependency-range-results.json
@@ -53,7 +53,7 @@ jobs:
      - name: Create issues for failed dependency candidates
        # Always process the report so failed candidates create actionable tracking issues.
        if: always()
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
        with:
          script: |
            const fs = require("fs")
@@ -18,7 +18,7 @@ jobs:
      UV_PYTHON: "3.13"
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          fetch-depth: 0

@@ -24,9 +24,9 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - name: Set up uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
        with:
          version-file: "python/pyproject.toml"
          enable-cache: true
@@ -36,7 +36,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          ref: ${{ inputs.checkout-ref }}
          persist-credentials: false
@@ -69,7 +69,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          ref: ${{ inputs.checkout-ref }}
          persist-credentials: false
@@ -90,7 +90,7 @@ jobs:
          --junitxml=pytest.xml
      - name: Upload test results
        if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: test-results-openai
          path: ./python/pytest.xml
@@ -112,7 +112,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          ref: ${{ inputs.checkout-ref }}
          persist-credentials: false
@@ -123,7 +123,7 @@ jobs:
          python-version: ${{ env.UV_PYTHON }}
          os: ${{ runner.os }}
      - name: Azure CLI Login
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -141,7 +141,7 @@ jobs:
          --junitxml=pytest.xml
      - name: Upload test results
        if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: test-results-azure-openai
          path: ./python/pytest.xml
@@ -163,7 +163,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          ref: ${{ inputs.checkout-ref }}
          persist-credentials: false
@@ -177,7 +177,7 @@ jobs:
        run: curl -fsSL https://ollama.com/install.sh | sh
        working-directory: .
      - name: Cache Ollama models
-        uses: actions/cache@v4
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
        with:
          path: ~/.ollama/models
          key: ollama-models-qwen2.5-1.5b-nomic-embed-text-v1
@@ -231,7 +231,7 @@ jobs:
          --junitxml=pytest.xml
      - name: Upload test results
        if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: test-results-misc
          path: ./python/pytest.xml
@@ -283,7 +283,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          ref: ${{ inputs.checkout-ref }}
          persist-credentials: false
@@ -294,7 +294,7 @@ jobs:
          python-version: ${{ env.UV_PYTHON }}
          os: ${{ runner.os }}
      - name: Azure CLI Login
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -315,7 +315,7 @@ jobs:
          --junitxml=pytest.xml
      - name: Upload test results
        if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: test-results-functions
          path: ./python/pytest.xml
@@ -341,7 +341,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          ref: ${{ inputs.checkout-ref }}
          persist-credentials: false
@@ -352,7 +352,7 @@ jobs:
          python-version: ${{ env.UV_PYTHON }}
          os: ${{ runner.os }}
      - name: Azure CLI Login
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -369,7 +369,7 @@ jobs:
          --junitxml=pytest.xml
      - name: Upload test results
        if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: test-results-foundry
          path: ./python/pytest.xml
@@ -388,7 +388,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          ref: ${{ inputs.checkout-ref }}
          persist-credentials: false
@@ -399,7 +399,7 @@ jobs:
          python-version: ${{ env.UV_PYTHON }}
          os: ${{ runner.os }}
      - name: Azure CLI Login
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -416,7 +416,7 @@ jobs:
          --junitxml=pytest.xml
      - name: Upload test results
        if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: test-results-foundry-hosting
          path: ./python/pytest.xml
@@ -443,7 +443,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          ref: ${{ inputs.checkout-ref }}
          persist-credentials: false
@@ -468,7 +468,7 @@ jobs:
        run: uv run --directory packages/azure-cosmos poe integration-tests -n logical --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5 --junitxml=${{ github.workspace }}/python/pytest.xml
      - name: Upload test results
        if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: test-results-cosmos
          path: ./python/pytest.xml
@@ -496,7 +496,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          ref: ${{ inputs.checkout-ref }}
          persist-credentials: false
@@ -506,12 +506,12 @@ jobs:
          python-version: ${{ env.UV_PYTHON }}
          os: ${{ runner.os }}
      - name: Download all test results from current run
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
        with:
          pattern: test-results-*
          path: test-results/
      - name: Restore report history cache
-        uses: actions/cache/restore@v4
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
        with:
          path: python/integration-report-history.json
          key: integration-report-history-integration-${{ github.run_id }}
@@ -528,13 +528,13 @@ jobs:
        run: cat integration-test-report.md >> $GITHUB_STEP_SUMMARY
      - name: Save report history cache
        if: always()
-        uses: actions/cache/save@v4
+        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
        with:
          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
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: integration-test-report
          path: |
@@ -558,12 +558,12 @@ jobs:
    steps:
      - name: Fail workflow if tests failed
        if: contains(join(needs.*.result, ','), 'failure')
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
        with:
          script: core.setFailed('Integration Tests Failed!')

      - name: Fail workflow if tests cancelled
        if: contains(join(needs.*.result, ','), 'cancelled')
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
        with:
          script: core.setFailed('Integration Tests Cancelled!')
@@ -24,8 +24,8 @@ jobs:
    outputs:
      pythonChanges: ${{ steps.filter.outputs.python}}
    steps:
-      - uses: actions/checkout@v6
-      - uses: dorny/paths-filter@v3
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: dorny/paths-filter@d1c1ffe0248fe513906c8e24db8ea791d46f8590 # v3
        id: filter
        with:
          filters: |
@@ -59,7 +59,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Set up python and install the project
        id: python-setup
@@ -94,7 +94,7 @@ jobs:
      # Surface failing tests
      - name: Surface failing tests
        if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
+        uses: pmeier/pytest-results-action@20b595761ba9bf89e115e875f8bc863f913bc8ad # v0.7.2
        with:
          path: ./python/packages/lab/**.xml
          summary: true
@@ -41,8 +41,8 @@ jobs:
      foundryHostingChanged: ${{ steps.filter.outputs.foundry_hosting }}
      cosmosChanged: ${{ steps.filter.outputs.cosmos }}
    steps:
-      - uses: actions/checkout@v6
-      - uses: dorny/paths-filter@v3
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: dorny/paths-filter@d1c1ffe0248fe513906c8e24db8ea791d46f8590 # v3
        id: filter
        with:
          filters: |
@@ -106,7 +106,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - name: Set up python and install the project
        id: python-setup
        uses: ./.github/actions/python-setup
@@ -123,7 +123,7 @@ jobs:
        working-directory: ./python
      - name: Surface failing tests
        if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
+        uses: pmeier/pytest-results-action@20b595761ba9bf89e115e875f8bc863f913bc8ad # v0.7.2
        with:
          path: ./python/pytest.xml
          summary: true
@@ -153,7 +153,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - name: Set up python and install the project
        id: python-setup
        uses: ./.github/actions/python-setup
@@ -177,7 +177,7 @@ jobs:
        working-directory: ./python
      - name: Surface failing tests
        if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
+        uses: pmeier/pytest-results-action@20b595761ba9bf89e115e875f8bc863f913bc8ad # v0.7.2
        with:
          path: ./python/pytest.xml
          summary: true
@@ -186,7 +186,7 @@ jobs:
          title: OpenAI integration test results
      - name: Upload test results
        if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: test-results-openai
          path: ./python/pytest.xml
@@ -214,7 +214,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - name: Set up python and install the project
        id: python-setup
        uses: ./.github/actions/python-setup
@@ -223,7 +223,7 @@ jobs:
          os: ${{ runner.os }}
      - name: Azure CLI Login
        if: github.event_name != 'pull_request'
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -247,7 +247,7 @@ jobs:
        working-directory: ./python
      - name: Surface failing tests
        if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
+        uses: pmeier/pytest-results-action@20b595761ba9bf89e115e875f8bc863f913bc8ad # v0.7.2
        with:
          path: ./python/pytest.xml
          summary: true
@@ -256,7 +256,7 @@ jobs:
          title: Azure OpenAI integration test results
      - name: Upload test results
        if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: test-results-azure-openai
          path: ./python/pytest.xml
@@ -284,7 +284,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - name: Set up python and install the project
        id: python-setup
        uses: ./.github/actions/python-setup
@@ -295,7 +295,7 @@ jobs:
        run: curl -fsSL https://ollama.com/install.sh | sh
        working-directory: .
      - name: Cache Ollama models
-        uses: actions/cache@v4
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
        with:
          path: ~/.ollama/models
          key: ollama-models-qwen2.5-1.5b-nomic-embed-text-v1
@@ -370,7 +370,7 @@ jobs:
          kill -KILL -- "-$server_pid" 2>/dev/null || kill -KILL "$server_pid" 2>/dev/null || true
      - name: Surface failing tests
        if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
+        uses: pmeier/pytest-results-action@20b595761ba9bf89e115e875f8bc863f913bc8ad # v0.7.2
        with:
          path: ./python/pytest.xml
          summary: true
@@ -379,7 +379,7 @@ jobs:
          title: Misc integration test results
      - name: Upload test results
        if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: test-results-misc
          path: ./python/pytest.xml
@@ -417,7 +417,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - name: Set up python and install the project
        id: python-setup
        uses: ./.github/actions/python-setup
@@ -426,7 +426,7 @@ jobs:
          os: ${{ runner.os }}
      - name: Azure CLI Login
        if: github.event_name != 'pull_request'
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -448,7 +448,7 @@ jobs:
        working-directory: ./python
      - name: Surface failing tests
        if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
+        uses: pmeier/pytest-results-action@20b595761ba9bf89e115e875f8bc863f913bc8ad # v0.7.2
        with:
          path: ./python/pytest.xml
          summary: true
@@ -457,7 +457,7 @@ jobs:
          title: Functions integration test results
      - name: Upload test results
        if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: test-results-functions
          path: ./python/pytest.xml
@@ -488,7 +488,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - name: Set up python and install the project
        id: python-setup
        uses: ./.github/actions/python-setup
@@ -497,7 +497,7 @@ jobs:
          os: ${{ runner.os }}
      - name: Azure CLI Login
        if: github.event_name != 'pull_request'
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -515,7 +515,7 @@ jobs:
        working-directory: ./python
      - name: Surface failing tests
        if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
+        uses: pmeier/pytest-results-action@20b595761ba9bf89e115e875f8bc863f913bc8ad # v0.7.2
        with:
          path: ./python/pytest.xml
          summary: true
@@ -524,7 +524,7 @@ jobs:
          title: Test results
      - name: Upload test results
        if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: test-results-foundry
          path: ./python/pytest.xml
@@ -549,7 +549,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - name: Set up python and install the project
        id: python-setup
        uses: ./.github/actions/python-setup
@@ -558,7 +558,7 @@ jobs:
          os: ${{ runner.os }}
      - name: Azure CLI Login
        if: github.event_name != 'pull_request'
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -576,7 +576,7 @@ jobs:
        working-directory: ./python
      - name: Surface failing tests
        if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
+        uses: pmeier/pytest-results-action@20b595761ba9bf89e115e875f8bc863f913bc8ad # v0.7.2
        with:
          path: ./python/pytest.xml
          summary: true
@@ -585,7 +585,7 @@ jobs:
          title: Foundry Hosting integration test results
      - name: Upload test results
        if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: test-results-foundry-hosting
          path: ./python/pytest.xml
@@ -620,7 +620,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - name: Set up python and install the project
        id: python-setup
        uses: ./.github/actions/python-setup
@@ -643,7 +643,7 @@ jobs:
        working-directory: ./python
      - name: Surface failing tests
        if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
+        uses: pmeier/pytest-results-action@20b595761ba9bf89e115e875f8bc863f913bc8ad # v0.7.2
        with:
          path: ./python/pytest.xml
          summary: true
@@ -652,7 +652,7 @@ jobs:
          title: Cosmos integration test results
      - name: Upload test results
        if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: test-results-cosmos
          path: ./python/pytest.xml
@@ -680,19 +680,19 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - name: Set up python and install the project
        uses: ./.github/actions/python-setup
        with:
          python-version: ${{ env.UV_PYTHON }}
          os: ${{ runner.os }}
      - name: Download all test results from current run
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
        with:
          pattern: test-results-*
          path: test-results/
      - name: Restore report history cache
-        uses: actions/cache/restore@v4
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
        with:
          path: python/integration-report-history.json
          key: integration-report-history-merge-${{ github.run_id }}
@@ -709,13 +709,13 @@ jobs:
        run: cat integration-test-report.md >> $GITHUB_STEP_SUMMARY
      - name: Save report history cache
        if: always()
-        uses: actions/cache/save@v4
+        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
        with:
          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
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: integration-test-report
          path: |
@@ -740,13 +740,13 @@ jobs:
      - name: Fail workflow if tests failed
        id: check_tests_failed
        if: contains(join(needs.*.result, ','), 'failure')
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
        with:
          script: core.setFailed('Integration Tests Failed!')

      - name: Fail workflow if tests cancelled
        id: check_tests_cancelled
        if: contains(join(needs.*.result, ','), 'cancelled')
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
        with:
          script: core.setFailed('Integration Tests Cancelled!')
@@ -23,7 +23,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - name: Set up python and install the project
        id: python-setup
        uses: ./.github/actions/python-setup
@@ -56,7 +56,7 @@ jobs:
      - name: Build the package
        run: uv run poe --directory packages/${{ env.PACKAGE }} build
      - name: Release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2
        with:
          files: |
            python/dist/*
@@ -29,7 +29,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Setup environment
        uses: ./.github/actions/sample-validation-setup
@@ -49,7 +49,7 @@ jobs:
          cd scripts && uv run python -m sample_validation --subdir 01-get-started --save-report --report-name 01-get-started

      - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        if: always()
        with:
          name: validation-report-01-get-started
@@ -82,7 +82,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Setup environment
        uses: ./.github/actions/sample-validation-setup
@@ -111,7 +111,7 @@ jobs:
          cd scripts && uv run python -m sample_validation --subdir 02-agents --exclude providers --save-report --report-name 02-agents

      - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        if: always()
        with:
          name: validation-report-02-agents
@@ -130,7 +130,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Setup environment
        uses: ./.github/actions/sample-validation-setup
@@ -152,7 +152,7 @@ jobs:
          cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/openai --save-report --report-name 02-agents-openai

      - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        if: always()
        with:
          name: validation-report-02-agents-openai
@@ -170,7 +170,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Setup environment
        uses: ./.github/actions/sample-validation-setup
@@ -191,7 +191,7 @@ jobs:
          cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/azure --save-report --report-name 02-agents-azure

      - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        if: always()
        with:
          name: validation-report-02-agents-azure
@@ -208,7 +208,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Setup environment
        uses: ./.github/actions/sample-validation-setup
@@ -228,7 +228,7 @@ jobs:
          cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/anthropic --save-report --report-name 02-agents-anthropic

      - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        if: always()
        with:
          name: validation-report-02-agents-anthropic
@@ -242,7 +242,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Setup environment
        uses: ./.github/actions/sample-validation-setup
@@ -257,7 +257,7 @@ jobs:
          cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/github_copilot --save-report --report-name 02-agents-github-copilot

      - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        if: always()
        with:
          name: validation-report-02-agents-github-copilot
@@ -274,7 +274,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Setup environment
        uses: ./.github/actions/sample-validation-setup
@@ -289,7 +289,7 @@ jobs:
          cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/amazon --save-report --report-name 02-agents-amazon

      - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        if: always()
        with:
          name: validation-report-02-agents-amazon
@@ -306,7 +306,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Setup environment
        uses: ./.github/actions/sample-validation-setup
@@ -321,7 +321,7 @@ jobs:
          cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/ollama --save-report --report-name 02-agents-ollama

      - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        if: always()
        with:
          name: validation-report-02-agents-ollama
@@ -341,7 +341,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Setup environment
        uses: ./.github/actions/sample-validation-setup
@@ -363,7 +363,7 @@ jobs:
          cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/foundry --save-report --report-name 02-agents-foundry

      - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        if: always()
        with:
          name: validation-report-02-agents-foundry
@@ -383,7 +383,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Setup environment
        uses: ./.github/actions/sample-validation-setup
@@ -405,7 +405,7 @@ jobs:
          cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/copilotstudio --save-report --report-name 02-agents-copilotstudio

      - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        if: always()
        with:
          name: validation-report-02-agents-copilotstudio
@@ -419,7 +419,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Setup environment
        uses: ./.github/actions/sample-validation-setup
@@ -434,7 +434,7 @@ jobs:
          cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/custom --save-report --report-name 02-agents-custom

      - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        if: always()
        with:
          name: validation-report-02-agents-custom
@@ -451,7 +451,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Setup environment
        uses: ./.github/actions/sample-validation-setup
@@ -471,7 +471,7 @@ jobs:
          cd scripts && uv run python -m sample_validation --subdir 03-workflows --save-report --report-name 03-workflows

      - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        if: always()
        with:
          name: validation-report-03-workflows
@@ -491,7 +491,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Setup environment
        uses: ./.github/actions/sample-validation-setup
@@ -506,7 +506,7 @@ jobs:
          cd scripts && uv run python -m sample_validation --subdir 04-hosting --save-report --report-name 04-hosting

      - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        if: always()
        with:
          name: validation-report-04-hosting
@@ -534,7 +534,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Setup environment
        uses: ./.github/actions/sample-validation-setup
@@ -549,7 +549,7 @@ jobs:
          cd scripts && uv run python -m sample_validation --subdir 05-end-to-end --save-report --report-name 05-end-to-end

      - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        if: always()
        with:
          name: validation-report-05-end-to-end
@@ -574,7 +574,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Setup environment
        uses: ./.github/actions/sample-validation-setup
@@ -599,7 +599,7 @@ jobs:
          cd scripts && uv run python -m sample_validation --subdir autogen-migration --save-report --report-name autogen-migration

      - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        if: always()
        with:
          name: validation-report-autogen-migration
@@ -633,7 +633,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Setup environment
        uses: ./.github/actions/sample-validation-setup
@@ -662,7 +662,7 @@ jobs:
          cd scripts && uv run python -m sample_validation --subdir semantic-kernel-migration --save-report --report-name semantic-kernel-migration

      - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        if: always()
        with:
          name: validation-report-semantic-kernel-migration
@@ -690,10 +690,10 @@ jobs:
      - validate-autogen-migration
      - validate-semantic-kernel-migration
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Download all validation reports
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7
        with:
          pattern: validation-report-*
          path: reports/
@@ -701,7 +701,7 @@ jobs:

      - name: Restore validation history
        id: cache-restore
-        uses: actions/cache/restore@v4
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
        with:
          path: validation-history/
          key: validation-history-${{ github.run_id }}
@@ -719,13 +719,13 @@ jobs:
        run: cat trend-report.md >> "$GITHUB_STEP_SUMMARY"

      - name: Save validation history
-        uses: actions/cache/save@v4
+        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
        with:
          path: validation-history/
          key: validation-history-${{ github.run_id }}

      - name: Upload trend report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        if: always()
        with:
          name: validation-trend-report
@@ -19,9 +19,9 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - name: Download coverage report
-        uses: actions/download-artifact@v8
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
        with:
          github-token: ${{ secrets.GH_ACTIONS_PR_WRITE }}
          run-id: ${{ github.event.workflow_run.id }}
@@ -46,7 +46,7 @@ jobs:
          echo "PR_NUMBER=$PR_NUMBER" >> "$GITHUB_ENV"
      - name: Pytest coverage comment
        id: coverageComment
-        uses: MishaKav/pytest-coverage-comment@v1.6.0
+        uses: MishaKav/pytest-coverage-comment@26f986d2599c288bb62f623d29c2da98609e9cd4 # v1.6.0
        with:
          github-token: ${{ secrets.GH_ACTIONS_PR_WRITE }}
          issue-number: ${{ env.PR_NUMBER }}
@@ -22,7 +22,7 @@ jobs:
    env:
      UV_PYTHON: "3.11"
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      # Save the PR number to a file since the workflow_run event
      # in the coverage report workflow does not have access to it
      - name: Save PR number
@@ -42,7 +42,7 @@ jobs:
      - name: Check coverage threshold
        run: python ${{ github.workspace }}/.github/workflows/python-check-coverage.py python-coverage.xml ${{ env.COVERAGE_THRESHOLD }}
      - name: Upload coverage report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          path: |
            python/python-coverage.xml
@@ -27,7 +27,7 @@ jobs:
      run:
        working-directory: python
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - name: Set up python and install the project
        id: python-setup
        uses: ./.github/actions/python-setup
@@ -46,7 +46,7 @@ jobs:
      # Surface failing tests
      - name: Surface failing tests
        if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
+        uses: pmeier/pytest-results-action@20b595761ba9bf89e115e875f8bc863f913bc8ad # v0.7.2
        with:
          path: ./python/pytest.xml
          summary: true
@@ -31,9 +31,9 @@ jobs:
      issues: write
      pull-requests: write
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
        with:
          python-version: '3.13'

@@ -0,0 +1,84 @@
+---
+status: accepted
+contact: rogerbarreto
+date: 2026-05-07
+deciders: rogerbarreto
+consulted: []
+informed: []
+---
+
+# Hosted session identity context for Foundry Hosting
+
+## Context and Problem Statement
+
+Server-hosted Foundry agents need a way to scope per-user state (most notably `FoundryMemoryProvider` memories) by the end user that initiated the request. The Foundry platform already injects `x-agent-user-isolation-key` and `x-agent-chat-isolation-key` headers on every Responses request, but the agent-framework hosting layer did not surface those values to `AIContextProvider` instances. The provider's `stateInitializer` only received an `AgentSession?` with no identity attached, so per-user scoping was impossible without out-of-band plumbing.
+
+## Decision Drivers
+
+- Memory and any future user-private context must be partitioned per end user without per-sample boilerplate.
+- The identity must be **read-only** from the perspective of `AIContextProvider`s, so a buggy or hostile provider cannot escalate or leak across users.
+- The persisted session must validate against the live request on every resume to defend against session-id leak and in-process tampering.
+- The change must work for every existing hosted-agent type (`ChatClientAgent`, `FoundryAgent`, future ones) without per-type refactoring of cast-heavy code paths in `Microsoft.Agents.AI`.
+- Local Docker debugging must remain possible when the platform headers are absent.
+
+## Considered Options
+
+1. **`HostedSessionContext` stored in `AgentSessionStateBag`, exposed via a public read accessor and an `internal` setter.** Hosting writes once on session creation and validates on every resume.
+2. **Specialised `HostedAgentSession : AgentSession` wrapper** that carries `UserId`/`ChatId` properties, with `GetService<ChatClientAgentSession>()` as the unwrap escape hatch.
+3. **New property on `AgentSession` base class** (`HostedSessionContext? HostedContext { get; internal set; }`).
+4. **AsyncLocal middleware** that reads the headers and stuffs them into a per-request `AsyncLocal<HostedSessionContext>` consumed by the provider.
+
+For the source of identity:
+- A. The platform-injected `IsolationContext` exposed by `ResponseContext.Isolation` (typed `UserIsolationKey`/`ChatIsolationKey`).
+- B. The OpenAI Responses spec's top-level `request.User` field.
+- C. A custom HTTP header `x-client-user`.
+
+## Decision Outcome
+
+**Option 1** was chosen for the storage shape, sourced from **Option A** (`ResponseContext.Isolation`).
+
+Rationale:
+
+- **Wrapper rejected (Option 2).** `ChatClientAgentSession` is `sealed` and `ChatClientAgent` rejects any other session type via direct `is not ChatClientAgentSession` checks at multiple call sites. Wrapping would force non-trivial refactors across `Microsoft.Agents.AI` and a corresponding repeat for every other agent type.
+- **Base-class property rejected (Option 3).** Leaks "hosted" semantics into the universal `AgentSession` abstraction used by Durable, A2A, and CopilotStudio agents that have no notion of a hosted user.
+- **AsyncLocal rejected (Option 4).** Surfaces the concept only locally, requires every consumer to re-implement the bridge, and cannot be enforced as read-only.
+- **`request.User` rejected (Option B).** Set by the caller, not the platform. Forging it client-side trivially defeats per-user partitioning.
+- **`x-client-user` rejected (Option C).** Non-standard, requires custom HTTP plumbing, and duplicates the platform-provided isolation contract.
+
+Implementation summary in `Microsoft.Agents.AI.Foundry.Hosting`:
+
+| Type | Visibility | Purpose |
+|---|---|---|
+| `HostedSessionContext` | public sealed | Captures `UserId` and `ChatId` (both required, non-whitespace). |
+| `HostedSessionContextExtensions.GetHostedContext` | public | Read accessor for `AIContextProvider`s. |
+| `HostedSessionContextExtensions.SetHostedContext` | internal | Writer reserved for the hosting assembly. Backed by `AgentSessionStateBag` under a well-known key for serialisation. |
+| `HostedSessionIsolationKeyProvider` (abstract) | public | DI-resolvable factory. Async signature: `ValueTask<HostedSessionContext?> GetKeysAsync(ResponseContext, CreateResponse, CancellationToken)`. |
+| `PlatformHostedSessionIsolationKeyProvider` | internal sealed | Default implementation. Maps `context.Isolation.UserIsolationKey` and `context.Isolation.ChatIsolationKey`. Returns `null` when either is absent. |
+
+Behaviour added to `AgentFrameworkResponseHandler.CreateAsync`:
+
+1. Resolve `HostedSessionIsolationKeyProvider` from DI; fall back to `PlatformHostedSessionIsolationKeyProvider`.
+2. Call `GetKeysAsync(context, request, cancellationToken)`. A `null` result throws `InvalidOperationException` (becomes 500). A null/whitespace `UserId` or `ChatId` is rejected by `HostedSessionContext`'s constructor.
+3. Branch on the **session's existing context**, not on whether a `conversation_id` was supplied:
+   - **No session (`session is null`):** nothing to stamp; skip.
+   - **Session present but un-stamped (`GetHostedContext() is null`):** treat as fresh. This covers both newly-created sessions and pre-existing sessions whose `conversation_id` was provisioned externally (e.g. via `conversations.CreateProjectConversationAsync()`) before the first hosted-agent request. Stamp the resolved identity now.
+   - **Session present with stamped context:** strict resume. The persisted `UserId` and `ChatId` must equal the resolved values exactly. Mismatch throws `ResponsesApiException` with status 403 and body `Hosted session identity context mismatch`.
+
+## Consequences
+
+Positive:
+
+- Per-user memory partitioning works out of the box for any agent that consumes a `Microsoft.Agents.AI.Foundry.FoundryMemoryProvider` configured to read `session.GetHostedContext().UserId`.
+- Cross-user session-id leak and in-process tampering of the persisted identity both surface as a 403 with a deliberately uninformative body.
+- The identity is opaque to the framework, matching the platform's semantics. The framework never inspects user identity; the `IsolationContext` keys are pre-partitioned per agent.
+
+Negative:
+
+- Every existing hosted sample fails locally without a `HostedSessionIsolationKeyProvider` registered, because the platform headers are absent outside the platform. Mitigated by shipping `Hosted_Shared_Contributor_Setup` with `DevTemporaryLocalSessionIsolationKeyProvider` and `AddDevTemporaryLocalContributorSetup`, and migrating all 9 existing responses samples.
+- An attacker who can plant an un-stamped session under a victim's `conversation_id` *before* the victim's first hosted-agent request would be stamped with the attacker's identity on that first request. This is not a regression vs. behaviour without this contract, and is mitigated in practice because the `conversation_id` namespace is allocated by the platform per project. Once a session is stamped, the strict equality check fully defends the resume path.
+
+## Out of scope
+
+- Per-request `User` field on `CreateResponse` is intentionally not consumed; only the platform `IsolationContext` headers carry trustworthy identity.
+- Generic (non-Foundry) hosting layers can re-define an equivalent type if needed; nothing in this ADR is moved into `Microsoft.Agents.AI.Hosting` because `Microsoft.Agents.AI.Foundry.Hosting` does not depend on it.
+- HMAC tamper signatures over the persisted context are not implemented; comparison against `ResponseContext.Isolation` on every request is sufficient because the platform sets those headers at the trust boundary.
@@ -26,10 +26,10 @@
    <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.Search.Documents" Version="12.0.0" />
-    <PackageVersion Include="Azure.AI.Projects" Version="2.1.0-beta.1" />
+    <PackageVersion Include="Azure.AI.Projects" Version="2.1.0-beta.2" />
    <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" />
+    <PackageVersion Include="Azure.Core" Version="1.55.0" />
    <PackageVersion Include="Azure.Identity" Version="1.21.0" />
    <PackageVersion Include="DotNetEnv" Version="3.1.1" />
    <PackageVersion Include="Azure.Monitor.OpenTelemetry.Exporter" Version="1.5.0" />
@@ -44,7 +44,7 @@
    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.6" />
    <PackageVersion Include="Microsoft.Bcl.HashCode" Version="6.0.0" />
    <PackageVersion Include="Microsoft.Bcl.Memory" Version="10.0.5" />
-    <PackageVersion Include="System.ClientModel" Version="1.10.0" />
+    <PackageVersion Include="System.ClientModel" Version="1.11.0" />
    <PackageVersion Include="System.CodeDom" Version="10.0.0" />
    <PackageVersion Include="System.Collections.Immutable" Version="10.0.1" />
    <PackageVersion Include="System.CommandLine" Version="2.0.0-rc.2.25502.107" />
@@ -112,6 +112,7 @@
    <PackageVersion Include="ModelContextProtocol" Version="1.1.0" />
    <!-- Hyperlight -->
    <PackageVersion Include="Hyperlight.HyperlightSandbox.Api" Version="0.4.0" />
+    <PackageVersion Include="Hyperlight.HyperlightSandbox.Guest.Python" Version="0.4.0" />
    <!-- Inference SDKs -->
    <PackageVersion Include="Microsoft.ML.OnnxRuntimeGenAI" Version="0.10.0" />
    <PackageVersion Include="Microsoft.ML.Tokenizers" Version="2.0.0" />
@@ -121,9 +121,11 @@
  <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_Shared_Console_OpenAI/Harness_Shared_Console_OpenAI.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_Step02_Research_WithBackgroundAgents/Harness_Step02_Research_WithBackgroundAgents.csproj" />
    <Project Path="samples/02-agents/Harness/Harness_Step03_DataProcessing/Harness_Step03_DataProcessing.csproj" />
+    <Project Path="samples/02-agents/Harness/Harness_Step04_CodeExecution/Harness_Step04_CodeExecution.csproj" />
    <Project Path="samples/02-agents/Harness/ConsoleReactiveFramework/ConsoleReactiveFramework.csproj" />
    <Project Path="samples/02-agents/Harness/ConsoleReactiveComponents/ConsoleReactiveComponents.csproj" />
  </Folder>
@@ -210,6 +212,7 @@
  </Folder>
  <Folder Name="/Samples/02-agents/ModelContextProtocol/">
    <File Path="samples/02-agents/ModelContextProtocol/README.md" />
+    <Project Path="samples/02-agents/ModelContextProtocol/Agent_MCP_LongRunningTask_Client/Agent_MCP_LongRunningTask_Client.csproj" />
    <Project Path="samples/02-agents/ModelContextProtocol/Agent_MCP_Server/Agent_MCP_Server.csproj" />
    <Project Path="samples/02-agents/ModelContextProtocol/Agent_MCP_Server_Auth/Agent_MCP_Server_Auth.csproj" />
    <Project Path="samples/02-agents/ModelContextProtocol/FoundryAgent_Hosted_MCP/FoundryAgent_Hosted_MCP.csproj" />
@@ -279,6 +282,7 @@
  </Folder>
  <Folder Name="/Samples/03-workflows/Orchestration/">
    <Project Path="samples/03-workflows/Orchestration/Handoff/Handoff.csproj" />
+    <Project Path="samples/03-workflows/Orchestration/Magentic/Magentic.csproj" />
  </Folder>
  <Folder Name="/Samples/03-workflows/Observability/">
    <Project Path="samples/03-workflows/Observability/ApplicationInsights/ApplicationInsights.csproj" />
@@ -327,9 +331,15 @@
  <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-MemoryAgent/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-MemoryAgent/HostedMemoryAgent.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_Shared_Contributor_Setup/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted_Shared_Contributor_Setup/Hosted_Shared_Contributor_Setup.csproj" />
+  </Folder>
  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox/">
    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox/HostedToolbox.csproj" />
  </Folder>
@@ -349,6 +359,9 @@
  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Handoff/">
    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Handoff/HostedWorkflowHandoff.csproj" />
  </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-AgentSkills/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-AgentSkills/HostedAgentSkills.csproj" />
+  </Folder>
  <Folder Name="/Samples/04-hosting/DurableAgents/" />
  <Folder Name="/Samples/04-hosting/DurableAgents/AzureFunctions/">
    <File Path="samples/04-hosting/DurableAgents/AzureFunctions/.editorconfig" />
@@ -593,6 +606,7 @@
    <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.Mcp/Microsoft.Agents.AI.Mcp.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" />
@@ -646,6 +660,7 @@
    <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.Mcp.UnitTests/Microsoft.Agents.AI.Mcp.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" />
@@ -26,6 +26,7 @@
      "src\\Microsoft.Agents.AI.Mem0\\Microsoft.Agents.AI.Mem0.csproj",
      "src\\Microsoft.Agents.AI.OpenAI\\Microsoft.Agents.AI.OpenAI.csproj",
      "src\\Microsoft.Agents.AI.Purview\\Microsoft.Agents.AI.Purview.csproj",
+      "src\\Microsoft.Agents.AI.Tools.Shell\\Microsoft.Agents.AI.Tools.Shell.csproj",
      "src\\Microsoft.Agents.AI.Workflows.Declarative.Foundry\\Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj",
      "src\\Microsoft.Agents.AI.Workflows.Declarative\\Microsoft.Agents.AI.Workflows.Declarative.csproj",
      "src\\Microsoft.Agents.AI.Workflows.Generators\\Microsoft.Agents.AI.Workflows.Generators.csproj",
@@ -1151,6 +1151,25 @@ internal static class AgentsSamples
            SkipReason = "Runs as an MCP stdio server that does not exit on its own.",
        },

+        new SampleDefinition
+        {
+            Name = "Agent_MCP_LongRunningTask_Client",
+            ProjectPath = "samples/02-agents/ModelContextProtocol/Agent_MCP_LongRunningTask_Client",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            MustContain =
+            [
+                "=== Transparent long-running MCP task (RunAsync) ===",
+                "=== Transparent long-running MCP task (RunStreamingAsync) ===",
+            ],
+            ExpectedOutputDescription =
+            [
+                "The output should show an agent analyzing a dataset named 'sales-2025-q1' and producing a summary mentioning rows, revenue, anomalies, or outliers.",
+                "The output should contain both a non-streaming response (after RunAsync) and a streaming response (after RunStreamingAsync) for the same analysis question.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
        new SampleDefinition
        {
            Name = "AGUI_Step01_GettingStarted_Client",
@@ -1,14 +1,14 @@
 <Project>
  <PropertyGroup>
    <!-- Central version prefix - applies to all nuget packages. -->
-    <VersionPrefix>1.6.1</VersionPrefix>
+    <VersionPrefix>1.7.0</VersionPrefix>
    <RCNumber>1</RCNumber>
-    <DateSuffix>260514</DateSuffix>
+    <DateSuffix>260526</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.6.1</GitTag>
+    <GitTag>1.7.0</GitTag>

    <Configurations>Debug;Release;Publish</Configurations>
    <IsPackable>true</IsPackable>
@@ -24,6 +24,7 @@ string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYM
 var skillsProvider = new AgentSkillsProvider(
    Path.Combine(AppContext.BaseDirectory, "skills"),
    SubprocessScriptRunner.RunAsync);
+
 // --- Agent Setup ---
 AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
    .GetResponsesClient()
@@ -51,7 +51,7 @@ Console.WriteLine($"Agent: {response.Text}");
 /// Properties annotated with <see cref="AgentSkillResourceAttribute"/> are automatically
 /// discovered as skill resources, and methods annotated with <see cref="AgentSkillScriptAttribute"/>
 /// are automatically discovered as skill scripts. Alternatively,
-/// <see cref="AgentSkill.Resources"/> and <see cref="AgentSkill.Scripts"/> can be overridden.
+/// <see cref="AgentClassSkill{TSelf}.Resources"/> and <see cref="AgentClassSkill{TSelf}.Scripts"/> can be overridden.
 /// </remarks>
 internal sealed class UnitConverterSkill : AgentClassSkill<UnitConverterSkill>
 {
@@ -24,6 +24,11 @@ public static class AnsiEscapes
    /// </summary>
    public static string MoveCursor(int row, int column) => $"\x1b[{row};{column}H";

+    /// <summary>
+    /// Erases the current line from the cursor position to the end of the line (EL 0).
+    /// </summary>
+    public static string EraseToEndOfLine => "\x1b[0K";
+
    /// <summary>
    /// Erases the entire current line (EL 2).
    /// </summary>
@@ -39,9 +39,9 @@ public class ListSelection : ConsoleReactiveComponent<ListSelectionProps, Consol
        {
            foreach (string line in props.Title.Split('\n'))
            {
-                Console.Write(AnsiEscapes.MoveCursor(this.Y + row, this.X));
-                Console.Write(AnsiEscapes.EraseEntireLine);
+                Console.Write(AnsiEscapes.MoveCursor(props.Y + row, props.X));
                Console.Write(line);
+                Console.Write(AnsiEscapes.EraseToEndOfLine);
                row++;
            }
        }
@@ -51,8 +51,7 @@ public class ListSelection : ConsoleReactiveComponent<ListSelectionProps, Consol

        for (int i = 0; i < totalItems; i++)
        {
-            Console.Write(AnsiEscapes.MoveCursor(this.Y + row, this.X));
-            Console.Write(AnsiEscapes.EraseEntireLine);
+            Console.Write(AnsiEscapes.MoveCursor(props.Y + row, props.X));

            bool isSelected = i == props.SelectedIndex;
            bool isCustomTextOption = props.CustomTextPlaceholder != null && i == props.Items.Count;
@@ -72,6 +71,7 @@ public class ListSelection : ConsoleReactiveComponent<ListSelectionProps, Consol
                }

                Console.Write(props.Items[i]);
+                Console.Write(AnsiEscapes.EraseToEndOfLine);

                if (isSelected)
                {
@@ -101,6 +101,7 @@ public class ListSelection : ConsoleReactiveComponent<ListSelectionProps, Consol
            }

            Console.Write(props.CustomText);
+            Console.Write(AnsiEscapes.EraseToEndOfLine);

            if (isSelected)
            {
@@ -121,6 +122,7 @@ public class ListSelection : ConsoleReactiveComponent<ListSelectionProps, Consol

            Console.Write(" ");
            Console.Write(props.CustomTextPlaceholder);
+            Console.Write(AnsiEscapes.EraseToEndOfLine);
            Console.Write(AnsiEscapes.ResetAttributes);
        }
    }
@@ -58,11 +58,11 @@ public class TextInput : ConsoleReactiveComponent<TextInputProps, ConsoleReactiv
    public override void RenderCore(TextInputProps props, ConsoleReactiveState state)
    {
        int promptLength = props.Prompt.Length;
-        int textWidth = this.Width - promptLength;
+        int textWidth = props.Width - promptLength;
        string indent = new(' ', promptLength);

        // First line: prompt + start of text
-        Console.Write(AnsiEscapes.MoveCursor(this.Y, this.X));
+        Console.Write(AnsiEscapes.MoveCursor(props.Y, props.X));
        Console.Write(AnsiEscapes.EraseEntireLine);
        Console.Write(props.Prompt);

@@ -90,7 +90,7 @@ public class TextInput : ConsoleReactiveComponent<TextInputProps, ConsoleReactiv
        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.MoveCursor(props.Y + row, props.X));
            Console.Write(AnsiEscapes.EraseEntireLine);
            Console.Write(indent);
            Console.Write(props.Text[offset..(offset + chunk)]);
@@ -17,7 +17,7 @@ public record TextPanelProps : ConsoleReactiveProps
 /// <summary>
 /// A component that renders a list of pre-rendered string items vertically.
 /// 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"/>
+/// re-rendered on each update. If the component's <see cref="ConsoleReactiveProps.Height"/>
 /// exceeds the number of output lines, leftover lines are erased.
 /// </summary>
 public class TextPanel : ConsoleReactiveComponent<TextPanelProps, ConsoleReactiveState>
@@ -51,18 +51,18 @@ public class TextPanel : ConsoleReactiveComponent<TextPanelProps, ConsoleReactiv

            for (int j = 0; j < lineCount; j++)
            {
-                Console.Write(AnsiEscapes.MoveAndEraseLine(this.Y + currentRow));
+                Console.Write(AnsiEscapes.MoveAndEraseLine(props.Y + currentRow));
                Console.Write(lines[j]);
                currentRow++;
            }
        }

        // If the component height exceeds the output, erase leftover lines
-        if (this.Height > currentRow)
+        if (props.Height > currentRow)
        {
-            for (int i = currentRow; i < this.Height; i++)
+            for (int i = currentRow; i < props.Height; i++)
            {
-                Console.Write(AnsiEscapes.MoveAndEraseLine(this.Y + i));
+                Console.Write(AnsiEscapes.MoveAndEraseLine(props.Y + i));
            }
        }
    }
@@ -17,16 +17,19 @@ public record TextScrollPanelProps : ConsoleReactiveProps
 /// <summary>
 /// State for <see cref="TextScrollPanel"/>.
 /// </summary>
-/// <param name="RenderedCount">The number of items already rendered.</param>
-public record TextScrollPanelState(int RenderedCount = 0) : ConsoleReactiveState;
+public record TextScrollPanelState : ConsoleReactiveState;

 /// <summary>
 /// A component that renders pre-rendered string items within a scroll area.
-/// All items are considered finalized — only new items since the last render are output.
-/// Use <see cref="Reset"/> to force a full re-render.
+/// The last rendered item is considered dynamic and will be re-rendered on each call.
+/// All prior items are considered finalized and are not re-rendered.
+/// Use <see cref="Invalidate"/> to force a full re-render.
 /// </summary>
 public class TextScrollPanel : ConsoleReactiveComponent<TextScrollPanelProps, TextScrollPanelState>
 {
+    private int _renderedCount;
+    private int _lastItemOffsetFromBottom;
+
    /// <summary>
    /// Initializes a new instance of the <see cref="TextScrollPanel"/> class.
    /// </summary>
@@ -35,12 +38,12 @@ public class TextScrollPanel : ConsoleReactiveComponent<TextScrollPanelProps, Te
        this.State = new TextScrollPanelState();
    }

-    /// <summary>
-    /// Resets the panel so all items will be re-rendered on the next Render call.
-    /// </summary>
-    public void Reset()
+    /// <inheritdoc />
+    public override void Invalidate()
    {
-        this.State = new TextScrollPanelState();
+        this._renderedCount = 0;
+        this._lastItemOffsetFromBottom = 0;
+        base.Invalidate();
    }

    /// <inheritdoc />
@@ -51,16 +54,59 @@ public class TextScrollPanel : ConsoleReactiveComponent<TextScrollPanelProps, Te
            return;
        }

-        // Move cursor to the bottom of the scroll area
-        Console.Write(AnsiEscapes.MoveCursor(this.Y + this.Height - 1, this.X));
+        int bottomRow = props.Y + props.Height - 1;

-        // Output only new items since last rendered
-        for (int i = state.RenderedCount; i < props.Items.Count; i++)
+        // Determine the first item to render. If we previously rendered items,
+        // re-render the last one (it may have changed/grown) from its stored position.
+        int startIndex = this._renderedCount > 0 ? this._renderedCount - 1 : 0;
+
+        if (this._renderedCount > 0 && this._lastItemOffsetFromBottom > 0)
+        {
+            // Reposition cursor to where the last rendered item began
+            Console.Write(AnsiEscapes.MoveCursor(bottomRow - this._lastItemOffsetFromBottom, props.X));
+        }
+        else
+        {
+            // First render — position at the bottom of the scroll area
+            Console.Write(AnsiEscapes.MoveCursor(bottomRow, props.X));
+        }
+
+        // Render from startIndex onwards
+        for (int i = startIndex; i < props.Items.Count; i++)
        {
            Console.Write(props.Items[i]);
        }

-        // Update state to track what we've rendered
-        this.State = new TextScrollPanelState(props.Items.Count);
+        // Calculate the offset from bottom for the start of the new last item
+        int lastItemLines = CountLines(props.Items[^1]);
+        this._lastItemOffsetFromBottom = lastItemLines > 0 ? lastItemLines - 1 : 0;
+
+        // Update rendered count
+        this._renderedCount = props.Items.Count;
+    }
+
+    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;
    }
 }
@@ -9,9 +9,6 @@ namespace Harness.ConsoleReactiveComponents;
 /// </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; }
 }
@@ -32,7 +29,7 @@ public class TopBottomRule : ConsoleReactiveComponent<TopBottomRuleProps, Consol
        int childrenHeight = 0;
        foreach (var child in props.Children)
        {
-            childrenHeight += child.Height;
+            childrenHeight += child.BaseProps?.Height ?? 0;
        }

        // Top rule + children + bottom rule
@@ -51,11 +48,11 @@ public class TopBottomRule : ConsoleReactiveComponent<TopBottomRuleProps, Consol
        }

        // Top rule
-        Console.Write(AnsiEscapes.MoveCursor(this.Y, this.X));
+        Console.Write(AnsiEscapes.MoveCursor(props.Y, props.X));
        Console.Write(rule);

        // Render children stacked below the top rule
-        int currentY = this.Y + 1;
+        int currentY = props.Y + 1;

        if (props.Color.HasValue)
        {
@@ -64,10 +61,9 @@ public class TopBottomRule : ConsoleReactiveComponent<TopBottomRuleProps, Consol

        foreach (var child in props.Children)
        {
-            child.X = this.X;
-            child.Y = currentY;
+            child.BaseProps = child.BaseProps! with { X = props.X, Y = currentY };
            child.Render();
-            currentY += child.Height;
+            currentY += child.BaseProps.Height;
        }

        if (props.Color.HasValue)
@@ -76,7 +72,7 @@ public class TopBottomRule : ConsoleReactiveComponent<TopBottomRuleProps, Consol
        }

        // Bottom rule
-        Console.Write(AnsiEscapes.MoveCursor(currentY, this.X));
+        Console.Write(AnsiEscapes.MoveCursor(currentY, props.X));
        Console.Write(rule);

        if (props.Color.HasValue)
@@ -3,8 +3,8 @@
 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.
+/// Abstract base class for all console UI components. Provides access to layout
+/// through <see cref="BaseProps"/> 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
@@ -13,20 +13,21 @@ public abstract class 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>
+    /// Gets or sets the component's props as the base <see cref="ConsoleReactiveProps"/> type.
+    /// Used by parent components to set layout (X, Y, Width, Height) on children without
+    /// knowing the concrete props type.
+    /// </summary>
+    public abstract ConsoleReactiveProps? BaseProps { get; set; }

    /// <summary>Renders the component to the console at its current position.</summary>
    public abstract void Render();
+
+    /// <summary>
+    /// Invalidates the component's cached render state, causing the next <see cref="Render"/> call
+    /// to proceed even if props and state have not changed. Use after a screen erase to force repaint.
+    /// </summary>
+    public abstract void Invalidate();
 }

 /// <summary>
@@ -46,6 +47,13 @@ public abstract class ConsoleReactiveComponent<TProps, TState> : ConsoleReactive
    /// <summary>Gets or sets the component's props (external configuration).</summary>
    public TProps? Props { get; set; }

+    /// <inheritdoc/>
+    public override ConsoleReactiveProps? BaseProps
+    {
+        get => this.Props;
+        set => this.Props = (TProps?)value;
+    }
+
    /// <summary>Gets or sets the component's internal state.</summary>
    protected TState? State { get; set; }

@@ -73,8 +81,8 @@ public abstract class ConsoleReactiveComponent<TProps, TState> : ConsoleReactive
                return;
            }

-            if (ReferenceEquals(this.Props, this._lastRenderedProps)
-                && ReferenceEquals(this.State, this._lastRenderedState))
+            if (EqualityComparer<TProps>.Default.Equals(this.Props, this._lastRenderedProps)
+                && EqualityComparer<TState>.Default.Equals(this.State, this._lastRenderedState))
            {
                return;
            }
@@ -86,6 +94,16 @@ public abstract class ConsoleReactiveComponent<TProps, TState> : ConsoleReactive
        }
    }

+    /// <inheritdoc/>
+    public override void Invalidate()
+    {
+        lock (this._renderLock)
+        {
+            this._lastRenderedProps = default;
+            this._lastRenderedState = default;
+        }
+    }
+
    /// <summary>
    /// Called by <see cref="Render"/> to perform the actual rendering. Override this in derived classes.
    /// </summary>
@@ -95,11 +113,23 @@ public abstract class ConsoleReactiveComponent<TProps, TState> : ConsoleReactive
 }

 /// <summary>
-/// Base record for component props. Provides an optional <see cref="Children"/> collection
-/// for composing child components.
+/// Base record for component props. Provides layout properties (position and size)
+/// and an optional <see cref="Children"/> collection for composing child components.
 /// </summary>
 public record ConsoleReactiveProps
 {
+    /// <summary>Gets the 1-based column position of the component.</summary>
+    public int X { get; init; }
+
+    /// <summary>Gets the 1-based row position of the component.</summary>
+    public int Y { get; init; }
+
+    /// <summary>Gets the width of the component in columns.</summary>
+    public int Width { get; init; }
+
+    /// <summary>Gets the height of the component in rows.</summary>
+    public int Height { get; init; }
+
    /// <summary>Gets the child components to render within this component.</summary>
    public IReadOnlyList<ConsoleReactiveComponent> Children { get; init; } = [];
 }
@@ -0,0 +1,36 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Harness.ConsoleReactiveFramework;
+
+/// <summary>
+/// Caches the result of a mapping function and only recomputes when the input changes.
+/// </summary>
+/// <typeparam name="TInput">The type of the input value.</typeparam>
+/// <typeparam name="TOutput">The type of the mapped output value.</typeparam>
+public class ConsoleReactiveMemo<TInput, TOutput>
+{
+    private TInput? _previousInput;
+    private TOutput? _cachedOutput;
+    private bool _hasValue;
+
+    /// <summary>
+    /// Returns the cached output if <paramref name="input"/> equals the previously stored input;
+    /// otherwise invokes <paramref name="mapper"/> to compute and cache a new output.
+    /// </summary>
+    /// <param name="input">The current input value.</param>
+    /// <param name="mapper">A function that maps the input to an output value.</param>
+    /// <returns>The cached or newly computed output.</returns>
+    public TOutput Map(TInput input, Func<TInput, TOutput> mapper)
+    {
+        ArgumentNullException.ThrowIfNull(mapper);
+
+        if (!this._hasValue || !EqualityComparer<TInput>.Default.Equals(input, this._previousInput))
+        {
+            this._previousInput = input;
+            this._cachedOutput = mapper(input);
+            this._hasValue = true;
+        }
+
+        return this._cachedOutput!;
+    }
+}
@@ -0,0 +1,98 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using Microsoft.Agents.AI;
+
+namespace Harness.Shared.Console.Commands;
+
+/// <summary>
+/// Handles <c>/session-export &lt;filename&gt;</c> and <c>/session-import &lt;filename&gt;</c>
+/// commands for serializing the current session to a file and restoring a session from a file.
+/// </summary>
+public sealed class SessionCommandHandler : CommandHandler
+{
+    private readonly AIAgent _agent;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="SessionCommandHandler"/> class.
+    /// </summary>
+    /// <param name="agent">The agent used for session serialization and deserialization.</param>
+    public SessionCommandHandler(AIAgent agent)
+    {
+        this._agent = agent;
+    }
+
+    /// <inheritdoc/>
+    public override string? GetHelpText() => "/session-export <file> | /session-import <file>";
+
+    /// <inheritdoc/>
+    public override async ValueTask<bool> TryHandleAsync(string input, AgentSession session, IUXStateDriver ux)
+    {
+        string command = input.Split(' ', 2)[0];
+
+        if (command.Equals("/session-export", StringComparison.OrdinalIgnoreCase))
+        {
+            await this.HandleExportAsync(input, session, ux).ConfigureAwait(false);
+            return true;
+        }
+
+        if (command.Equals("/session-import", StringComparison.OrdinalIgnoreCase))
+        {
+            await this.HandleImportAsync(input, ux).ConfigureAwait(false);
+            return true;
+        }
+
+        return false;
+    }
+
+    private async Task HandleExportAsync(string input, AgentSession session, IUXStateDriver ux)
+    {
+        string[] parts = input.Split(' ', 2, StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+        if (parts.Length < 2)
+        {
+            await ux.WriteInfoLineAsync("Usage: /session-export <filename>").ConfigureAwait(false);
+            return;
+        }
+
+        string filename = parts[1];
+        try
+        {
+            JsonElement serialized = await this._agent.SerializeSessionAsync(session).ConfigureAwait(false);
+            string json = JsonSerializer.Serialize(serialized);
+            await File.WriteAllTextAsync(filename, json).ConfigureAwait(false);
+            await ux.WriteInfoLineAsync($"Session exported to {filename}").ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            await ux.WriteInfoLineAsync($"Failed to export session to {filename}: {ex.Message}").ConfigureAwait(false);
+        }
+    }
+
+    private async Task HandleImportAsync(string input, IUXStateDriver ux)
+    {
+        string[] parts = input.Split(' ', 2, StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+        if (parts.Length < 2)
+        {
+            await ux.WriteInfoLineAsync("Usage: /session-import <filename>").ConfigureAwait(false);
+            return;
+        }
+
+        string filename = parts[1];
+        try
+        {
+            string json = await File.ReadAllTextAsync(filename).ConfigureAwait(false);
+            JsonElement element = JsonSerializer.Deserialize<JsonElement>(json);
+            AgentSession newSession = await this._agent.DeserializeSessionAsync(element).ConfigureAwait(false);
+            await ux.ReplaceSessionAsync(newSession).ConfigureAwait(false);
+            await ux.WriteInfoLineAsync($"Session imported from {filename}").ConfigureAwait(false);
+        }
+        catch (FileNotFoundException)
+        {
+            await ux.WriteInfoLineAsync($"File not found: {filename}").ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            await ux.WriteInfoLineAsync($"Failed to import session from {filename}: {ex.Message}").ConfigureAwait(false);
+        }
+    }
+}
@@ -43,7 +43,7 @@ public class AgentModeAndHelp : ConsoleReactiveComponent<AgentModeAndHelpProps,
        }

        System.Console.Write(AnsiEscapes.SaveCursor);
-        System.Console.Write(AnsiEscapes.MoveAndEraseLine(this.Y));
+        System.Console.Write(AnsiEscapes.MoveAndEraseLine(props.Y));

        bool hasMode = props.Mode is not null;

@@ -35,6 +35,7 @@ public class AgentStatus : ConsoleReactiveComponent<AgentStatusProps, AgentStatu
    ];

    private readonly Timer _timer;
+    private AgentStatusProps? _previousProps;

    /// <summary>
    /// Initializes a new instance of the <see cref="AgentStatus"/> class.
@@ -85,7 +86,12 @@ public class AgentStatus : ConsoleReactiveComponent<AgentStatusProps, AgentStatu
        }

        System.Console.Write(AnsiEscapes.SaveCursor);
-        System.Console.Write(AnsiEscapes.MoveAndEraseLine(this.Y));
+        System.Console.Write(AnsiEscapes.MoveCursor(props.Y, props.X));
+        if (props != this._previousProps)
+        {
+            System.Console.Write(AnsiEscapes.EraseToEndOfLine);
+            this._previousProps = props;
+        }

        if (props.ShowSpinner)
        {
@@ -0,0 +1,67 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics;
+using System.Globalization;
+using OpenTelemetry;
+
+namespace Harness.Shared.Console;
+
+/// <summary>
+/// A simple OpenTelemetry span exporter that writes completed activities (spans) to a text file.
+/// Each span is formatted as a human-readable block with timestamps, operation name, duration,
+/// status, and any tags/events.
+/// </summary>
+public sealed class FileSpanExporter : BaseExporter<Activity>
+{
+    private readonly string _filePath;
+    private readonly object _lock = new();
+
+    public FileSpanExporter(string filePath)
+    {
+        this._filePath = filePath;
+        Directory.CreateDirectory(Path.GetDirectoryName(filePath)!);
+    }
+
+    public override ExportResult Export(in Batch<Activity> batch)
+    {
+        lock (this._lock)
+        {
+            using var writer = new StreamWriter(this._filePath, append: true);
+            foreach (var activity in batch)
+            {
+                WriteActivity(writer, activity);
+            }
+        }
+
+        return ExportResult.Success;
+    }
+
+    private static void WriteActivity(StreamWriter writer, Activity activity)
+    {
+        var start = activity.StartTimeUtc.ToString("yyyy-MM-dd HH:mm:ss.fff", CultureInfo.InvariantCulture);
+        var duration = activity.Duration.TotalMilliseconds.ToString("F1", CultureInfo.InvariantCulture);
+
+        writer.WriteLine($"[{start}] {activity.OperationName} ({duration}ms) [{activity.Status}]");
+
+        if (!string.IsNullOrEmpty(activity.DisplayName) && activity.DisplayName != activity.OperationName)
+        {
+            writer.WriteLine($"  DisplayName: {activity.DisplayName}");
+        }
+
+        foreach (var tag in activity.Tags)
+        {
+            writer.WriteLine($"  {tag.Key}: {tag.Value}");
+        }
+
+        foreach (var ev in activity.Events)
+        {
+            writer.WriteLine($"  Event: {ev.Name} @ {ev.Timestamp:HH:mm:ss.fff}");
+            foreach (var tag in ev.Tags)
+            {
+                writer.WriteLine($"    {tag.Key}: {tag.Value}");
+            }
+        }
+
+        writer.WriteLine();
+    }
+}
@@ -19,15 +19,15 @@ namespace Harness.Shared.Console;
 public sealed class HarnessAgentRunner : IDisposable
 {
    private readonly AIAgent _agent;
-    private readonly AgentSession _session;
    private readonly AgentModeProvider? _modeProvider;
    private readonly MessageInjectingChatClient? _messageInjector;
    private readonly IReadOnlyList<CommandHandler> _commandHandlers;
    private readonly IReadOnlyList<ConsoleObserver> _observers;
    private readonly IUXStateDriver _ux;
-
    private readonly SemaphoreSlim _inputGate = new(1, 1);

+    private AgentSession _session;
+
    /// <summary>
    /// Initializes a new instance of the <see cref="HarnessAgentRunner"/> class.
    /// </summary>
@@ -62,6 +62,25 @@ public sealed class HarnessAgentRunner : IDisposable
    /// </summary>
    public string HelpText { get; }

+    /// <summary>
+    /// Replaces the current session with the specified session. Used by the UX driver
+    /// when importing a serialized session. Acquires the input gate to ensure no
+    /// concurrent agent turn is reading the session.
+    /// </summary>
+    /// <param name="newSession">The new session to use.</param>
+    internal async Task ReplaceSessionAsync(AgentSession newSession)
+    {
+        await this._inputGate.WaitAsync().ConfigureAwait(false);
+        try
+        {
+            this._session = newSession;
+        }
+        finally
+        {
+            this._inputGate.Release();
+        }
+    }
+
    /// <inheritdoc/>
    public void Dispose() => this._inputGate.Dispose();

@@ -173,6 +192,11 @@ public sealed class HarnessAgentRunner : IDisposable
                        }
                    }

+                    foreach (var observer in this._observers)
+                    {
+                        await observer.OnResponseUpdateAsync(this._ux, update, this._agent, this._session).ConfigureAwait(false);
+                    }
+
                    if (!string.IsNullOrEmpty(update.Text))
                    {
                        foreach (var observer in this._observers)
@@ -19,7 +19,6 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
    private readonly ListSelection _listSelection = new();
    private readonly TextInput _textInput = new();
    private readonly TextScrollPanel _textScrollPanel = new();
-    private readonly TextPanel _textPanel = new();
    private readonly TextPanel _queuedPanel = new();
    private readonly AgentStatus _agentStatus = new();
    private readonly AgentModeAndHelp _modeAndHelp = new();
@@ -63,6 +62,7 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
            getState: () => this.State!,
            setState: s => this.SetState(s),
            requestShutdown: () => this._shutdownTcs.TrySetResult(true),
+            replaceSession: s => this.Runner!.ReplaceSessionAsync(s),
            modeColors: modeColors);

        this.Runner = runnerFactory(this._uxDriver);
@@ -340,16 +340,6 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
            return;
        }

-        // Determine the text panel height for the last scroll item
-        IReadOnlyList<string> lastItems = state.ScrollAreaContentItems.Count > 0
-            ? [state.ScrollAreaContentItems[^1]]
-            : [];
-        int textPanelHeight = TextPanel.CalculateHeight(lastItems);
-        if (textPanelHeight > 0)
-        {
-            textPanelHeight++; // Extra line for spacing between text panel and rule
-        }
-
        // Calculate queued items panel height
        int queuedPanelHeight = TextPanel.CalculateHeight(state.QueuedItems);

@@ -370,7 +360,7 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
            };

            bottomChildHeight = ListSelection.CalculateHeight(listProps);
-            this._listSelection.Height = bottomChildHeight;
+            listProps = listProps with { Height = bottomChildHeight };
            this._listSelection.Props = listProps;
            bottomChild = this._listSelection;
        }
@@ -397,8 +387,7 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
            }

            bottomChildHeight = TextInput.CalculateHeight(textInputProps, state.ConsoleWidth);
-            this._textInput.Width = state.ConsoleWidth;
-            this._textInput.Height = bottomChildHeight;
+            textInputProps = textInputProps with { Width = state.ConsoleWidth, Height = bottomChildHeight };
            this._textInput.Props = textInputProps;
            bottomChild = this._textInput;
        }
@@ -412,8 +401,7 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
            };

            bottomChildHeight = TextInput.CalculateHeight(textInputProps, state.ConsoleWidth);
-            this._textInput.Width = state.ConsoleWidth;
-            this._textInput.Height = bottomChildHeight;
+            textInputProps = textInputProps with { Width = state.ConsoleWidth, Height = bottomChildHeight };
            this._textInput.Props = textInputProps;
            bottomChild = this._textInput;
        }
@@ -445,7 +433,7 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
        int modeAndHelpHeight = showStatusAndHelp ? AgentModeAndHelp.CalculateHeight(modeAndHelpProps) : 0;

        int ruleHeight = TopBottomRule.CalculateHeight(ruleProps);
-        int nonScrollHeight = ruleHeight + textPanelHeight + agentStatusHeight + queuedPanelHeight + modeAndHelpHeight + 1; // +1 for bottom padding
+        int nonScrollHeight = ruleHeight + agentStatusHeight + queuedPanelHeight + modeAndHelpHeight + 1; // +1 for bottom padding
        int scrollBottom = Math.Max(1, state.ConsoleHeight - nonScrollHeight);

        // If scroll region changed or a clear is needed, reset everything
@@ -456,7 +444,16 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
            System.Console.Write(AnsiEscapes.ResetScrollRegion);
            System.Console.Write(AnsiEscapes.EraseEntireScreen);
            System.Console.Write(AnsiEscapes.EraseScrollbackBuffer);
-            this._textScrollPanel.Reset();
+
+            // Invalidate all children so they re-render even if props haven't changed
+            this._rule.Invalidate();
+            this._textScrollPanel.Invalidate();
+            this._queuedPanel.Invalidate();
+            this._agentStatus.Invalidate();
+            this._modeAndHelp.Invalidate();
+            this._textInput.Invalidate();
+            this._listSelection.Invalidate();
+
            this._resizedSinceLastRender = false;
        }

@@ -464,40 +461,25 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps

        System.Console.Write(AnsiEscapes.SetScrollRegion(scrollBottom));

-        // Render text scroll panel in the scroll area (all items except the last)
-        IReadOnlyList<string> scrollItems = state.ScrollAreaContentItems.Count > 1
-            ? state.ScrollAreaContentItems.Take(state.ScrollAreaContentItems.Count - 1).ToList()
-            : [];
-
-        this._textScrollPanel.X = 1;
-        this._textScrollPanel.Y = 1;
-        this._textScrollPanel.Width = state.ConsoleWidth;
-        this._textScrollPanel.Height = scrollBottom;
+        // Render text scroll panel in the scroll area
        this._textScrollPanel.Props = new TextScrollPanelProps
        {
-            Items = scrollItems,
+            X = 1,
+            Y = 1,
+            Width = state.ConsoleWidth,
+            Height = scrollBottom,
+            Items = state.ScrollAreaContentItems,
        };
        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;
+        // Render queued input items between scroll area and agent status
+        int queuedPanelY = scrollBottom + 1;
        this._queuedPanel.Props = new TextPanelProps
        {
+            X = 1,
+            Y = queuedPanelY,
+            Width = state.ConsoleWidth,
+            Height = queuedPanelHeight,
            Items = state.QueuedItems,
        };
        this._queuedPanel.Render();
@@ -506,32 +488,41 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
        int agentStatusY = queuedPanelY + queuedPanelHeight;
        if (showStatusAndHelp)
        {
-            this._agentStatus.X = 1;
-            this._agentStatus.Y = agentStatusY;
-            this._agentStatus.Width = state.ConsoleWidth;
-            this._agentStatus.Height = agentStatusHeight;
-            this._agentStatus.Props = agentStatusProps;
+            this._agentStatus.Props = agentStatusProps with
+            {
+                X = 1,
+                Y = agentStatusY,
+                Width = state.ConsoleWidth,
+                Height = agentStatusHeight,
+            };
            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.Props = ruleProps with
+        {
+            X = 1,
+            Y = agentStatusY + agentStatusHeight,
+        };
        this._rule.Render();

        // Render the mode-and-help line below the bottom rule
        if (showStatusAndHelp)
        {
-            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;
+            int modeAndHelpY = agentStatusY + agentStatusHeight + ruleHeight;
+            this._modeAndHelp.Props = modeAndHelpProps with
+            {
+                X = 1,
+                Y = modeAndHelpY,
+                Width = state.ConsoleWidth,
+                Height = modeAndHelpHeight,
+            };
            this._modeAndHelp.Render();
        }

+        // Clear the bottom padding line
+        System.Console.Write(AnsiEscapes.MoveAndEraseLine(state.ConsoleHeight));
+
        // Position cursor for natural typing appearance
        this.PositionCursor(state);
    }
@@ -545,7 +536,7 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
            int textWidth = state.ConsoleWidth - promptLength;
            int textLength = state.InputText.Length;

-            int textInputY = this._rule.Y + 1;
+            int textInputY = (this._rule.Props?.Y ?? 0) + 1;

            if (textWidth <= 0 || textLength == 0)
            {
@@ -563,7 +554,7 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
            && state.ListSelectionIndex == state.ListSelectionOptions.Count)
        {
            int titleLines = state.ListSelectionTitle?.Split('\n').Length ?? 0;
-            int customOptionY = this._rule.Y + 1 + titleLines + state.ListSelectionOptions.Count;
+            int customOptionY = (this._rule.Props?.Y ?? 0) + 1 + titleLines + state.ListSelectionOptions.Count;
            int cursorCol = 2 + state.ListSelectionCustomInputText.Length + 1;
            System.Console.Write(AnsiEscapes.MoveCursor(customOptionY, cursorCol));
        }
@@ -1,5 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.

+using System.Text;
 using Harness.ConsoleReactiveComponents;
 using Microsoft.Agents.AI;

@@ -24,6 +25,8 @@ public static class HarnessConsole
    {
        options ??= new();

+        System.Console.OutputEncoding = Encoding.UTF8;
+
        // Null means use defaults; an explicit (possibly empty) list means use exactly what was provided.
        var observers = options.Observers
            ?? HarnessConsoleOptions.BuildDefaultObservers();
@@ -33,7 +36,9 @@ public static class HarnessConsole
        var modeProvider = agent.GetService<AgentModeProvider>();
        var messageInjector = agent.GetService<MessageInjectingChatClient>();

-        AgentSession session = await agent.CreateSessionAsync();
+        AgentSession session = options.SessionFactory is not null
+            ? await options.SessionFactory(agent)
+            : await agent.CreateSessionAsync();

        using var component = new HarnessAppComponent(
            placeholder: userPrompt,
@@ -63,6 +68,7 @@ public static class HarnessConsole

        System.Console.ResetColor();
        System.Console.Write(AnsiEscapes.ResetScrollRegion);
+        System.Console.Write(AnsiEscapes.EraseScrollbackBuffer);
        System.Console.Write(AnsiEscapes.EraseEntireScreen);
        System.Console.Write(AnsiEscapes.MoveCursor(1, 1));
        System.Console.WriteLine("Goodbye!");
@@ -45,6 +45,12 @@ public class HarnessConsoleOptions
    /// </summary>
    public Dictionary<string, ConsoleColor> ModeColors { get; set; } = new(DefaultModeColors, StringComparer.OrdinalIgnoreCase);

+    /// <summary>
+    /// Gets or sets an optional factory for creating the <see cref="AgentSession"/>.
+    /// When <see langword="null"/> (the default), <see cref="AIAgent.CreateSessionAsync"/> is used.
+    /// </summary>
+    public Func<AIAgent, Task<AgentSession>>? SessionFactory { get; set; }
+
    /// <summary>
    /// Creates the default set of observers without planning support.
    /// Includes tool call display, tool approval, error display, reasoning display,
@@ -128,6 +134,7 @@ public class HarnessConsoleOptions
            new ExitCommandHandler(),
            new TodoCommandHandler(todoProvider),
            new ModeCommandHandler(modeProvider, modeColors ?? DefaultModeColors),
+            new SessionCommandHandler(agent),
        ];
    }
 }
@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.

 using Harness.ConsoleReactiveComponents;
+using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;

 namespace Harness.Shared.Console;
@@ -16,6 +17,7 @@ internal sealed class HarnessConsoleUXStateDriver : IUXStateDriver
    private readonly Func<HarnessAppComponentState> _getState;
    private readonly Action<HarnessAppComponentState> _setState;
    private readonly Action _requestShutdown;
+    private readonly Func<AgentSession, Task> _replaceSession;
    private readonly IReadOnlyDictionary<string, ConsoleColor>? _modeColors;
    private readonly List<string> _outputItems = [];
    private readonly object _stateLock = new();
@@ -32,16 +34,19 @@ internal sealed class HarnessConsoleUXStateDriver : IUXStateDriver
    /// <param name="getState">Returns the component's current state.</param>
    /// <param name="setState">Replaces the component's state and triggers a re-render.</param>
    /// <param name="requestShutdown">Callback invoked when a command handler requests application shutdown.</param>
+    /// <param name="replaceSession">Callback invoked to replace the current agent session (e.g., on import).</param>
    /// <param name="modeColors">Optional mapping of mode names to console colors.</param>
    public HarnessConsoleUXStateDriver(
        Func<HarnessAppComponentState> getState,
        Action<HarnessAppComponentState> setState,
        Action requestShutdown,
+        Func<AgentSession, Task> replaceSession,
        IReadOnlyDictionary<string, ConsoleColor>? modeColors = null)
    {
        this._getState = getState;
        this._setState = setState;
        this._requestShutdown = requestShutdown;
+        this._replaceSession = replaceSession;
        this._modeColors = modeColors;
        this._currentMode = getState().ModeText;
    }
@@ -405,4 +410,7 @@ internal sealed class HarnessConsoleUXStateDriver : IUXStateDriver

    /// <inheritdoc/>
    public void RequestShutdown() => this._requestShutdown();
+
+    /// <inheritdoc/>
+    public Task ReplaceSessionAsync(AgentSession newSession) => this._replaceSession(newSession);
 }
@@ -0,0 +1,55 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+#pragma warning disable VSTHRD002 // Synchronous waits are required by OpenTelemetry enrichment callbacks.
+
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+
+namespace Harness.Shared.Console;
+
+/// <summary>
+/// Provides factory methods for creating pre-configured OpenTelemetry tracing for harness samples.
+/// </summary>
+public static class HarnessTracing
+{
+    /// <summary>
+    /// Creates a <see cref="TracerProvider"/> that captures spans from the specified source and HTTP client activity,
+    /// enriching HTTP spans with full request/response headers and bodies, and exports all spans to a timestamped
+    /// text file in the application base directory.
+    /// </summary>
+    /// <param name="sourceName">The activity source name to subscribe to (e.g., "Harness.Research").</param>
+    /// <returns>A configured <see cref="TracerProvider"/>, or <see langword="null"/> if the builder returns null.</returns>
+    public static TracerProvider? CreateFileTracerProvider(string sourceName)
+    {
+        var traceLogPath = Path.Combine(AppContext.BaseDirectory, $"traces_{DateTime.UtcNow:yyyyMMdd_HHmmss}_{Guid.NewGuid()}.log");
+
+        return Sdk.CreateTracerProviderBuilder()
+            .AddSource(sourceName)
+            .AddHttpClientInstrumentation((options) =>
+            {
+                options.EnrichWithHttpRequestMessage = (activity, request) =>
+                {
+                    activity.SetTag("http.request.headers", request.Headers.ToString());
+                    if (request.Content != null)
+                    {
+                        activity.SetTag("http.request.content.headers", request.Content.Headers.ToString());
+                        var content = request.Content.ReadAsStringAsync().GetAwaiter().GetResult();
+                        activity.SetTag("http.request.content.body", content);
+                    }
+                };
+
+                options.EnrichWithHttpResponseMessage = (activity, response) =>
+                {
+                    activity.SetTag("http.response.headers", response.Headers.ToString());
+                    if (response.Content != null)
+                    {
+                        activity.SetTag("http.response.content.headers", response.Content.Headers.ToString());
+                        var content = response.Content.ReadAsStringAsync().GetAwaiter().GetResult();
+                        activity.SetTag("http.response.content.body", content);
+                    }
+                };
+            })
+            .AddProcessor(new SimpleActivityExportProcessor(new FileSpanExporter(traceLogPath)))
+            .Build();
+    }
+}
@@ -7,6 +7,11 @@
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

+  <ItemGroup>
+    <PackageReference Include="OpenTelemetry" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.Http" />
+  </ItemGroup>
+
  <ItemGroup>
    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
    <ProjectReference Include="..\ConsoleReactiveFramework\ConsoleReactiveFramework.csproj" />
@@ -1,5 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.

+using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;

 namespace Harness.Shared.Console;
@@ -117,4 +118,11 @@ public interface IUXStateDriver
    /// on the owning component.
    /// </summary>
    void RequestShutdown();
+
+    /// <summary>
+    /// Replaces the current agent session with the specified session (e.g., after importing
+    /// a serialized session from a file).
+    /// </summary>
+    /// <param name="newSession">The new session to use.</param>
+    Task ReplaceSessionAsync(AgentSession newSession);
 }
@@ -24,6 +24,17 @@ public abstract class ConsoleObserver
    {
    }

+    /// <summary>
+    /// Called for each <see cref="AgentResponseUpdate"/> in the response stream, regardless of
+    /// whether it contains content. Override to inspect update-level metadata such as
+    /// <see cref="AgentResponseUpdate.RawRepresentation"/> for provider-specific events.
+    /// </summary>
+    /// <param name="ux">The UX state driver, used for rendering output.</param>
+    /// <param name="update">The streaming response update.</param>
+    /// <param name="agent">The agent being interacted with.</param>
+    /// <param name="session">The current agent session.</param>
+    public virtual Task OnResponseUpdateAsync(IUXStateDriver ux, AgentResponseUpdate update, AIAgent agent, AgentSession session) => Task.CompletedTask;
+
    /// <summary>
    /// Called for each <see cref="AIContent"/> item in the response stream.
    /// </summary>
@@ -31,6 +31,10 @@ public sealed class ToolCallDisplayObserver : ConsoleObserver
        {
            await ux.WriteInfoLineAsync($"🔧 Calling tool: {ToolCallFormatter.Format(this._formatters, functionCall)}...", ConsoleColor.DarkYellow);
        }
+        else if (content is WebSearchToolCallContent)
+        {
+            // Handled by OpenAIResponsesWebSearchDisplayObserver when present; skip here to avoid duplication.
+        }
        else if (content is ToolCallContent toolCall)
        {
            await ux.WriteInfoLineAsync($"🔧 Calling tool: {toolCall}...", ConsoleColor.DarkYellow);
@@ -6,26 +6,26 @@ using Microsoft.Extensions.AI;
 namespace Harness.Shared.Console.ToolFormatters;

 /// <summary>
-/// Formats <c>SubAgents_*</c> tool calls with human-readable details
+/// Formats <c>BackgroundAgents_*</c> tool calls with human-readable details
 /// for task start, continue, wait, and result retrieval operations.
 /// </summary>
-public sealed class SubAgentToolFormatter : ToolCallFormatter
+public sealed class BackgroundAgentToolFormatter : ToolCallFormatter
 {
    /// <inheritdoc/>
-    public override bool CanFormat(FunctionCallContent call) => call.Name.StartsWith("SubAgents_", StringComparison.Ordinal);
+    public override bool CanFormat(FunctionCallContent call) => call.Name.StartsWith("BackgroundAgents_", StringComparison.Ordinal);

    /// <inheritdoc/>
    public override string? FormatDetail(FunctionCallContent call) => call.Name switch
    {
-        "SubAgents_StartTask" => FormatStartSubTask(call),
-        "SubAgents_WaitForFirstCompletion" => FormatIdList(call, "taskIds", "Wait for"),
-        "SubAgents_GetTaskResults" => FormatSingleId(call, "taskId"),
-        "SubAgents_ContinueTask" => FormatContinueTask(call),
-        "SubAgents_ClearCompletedTask" => FormatSingleId(call, "taskId"),
+        "BackgroundAgents_StartTask" => FormatStartBackgroundTask(call),
+        "BackgroundAgents_WaitForFirstCompletion" => FormatIdList(call, "taskIds", "Wait for"),
+        "BackgroundAgents_GetTaskResults" => FormatSingleId(call, "taskId"),
+        "BackgroundAgents_ContinueTask" => FormatContinueTask(call),
+        "BackgroundAgents_ClearCompletedTask" => FormatSingleId(call, "taskId"),
        _ => null,
    };

-    private static string? FormatStartSubTask(FunctionCallContent call)
+    private static string? FormatStartBackgroundTask(FunctionCallContent call)
    {
        string? agentName = GetStringArgumentValue(call, "agentName");
        string? description = GetStringArgumentValue(call, "description");
@@ -5,17 +5,17 @@ using Microsoft.Extensions.AI;
 namespace Harness.Shared.Console.ToolFormatters;

 /// <summary>
-/// Formats <c>AgentMode_*</c> tool calls, showing the target mode for Set operations.
+/// Formats <c>mode_*</c> tool calls, showing the target mode for Set operations.
 /// </summary>
 public sealed class ModeToolFormatter : ToolCallFormatter
 {
    /// <inheritdoc/>
-    public override bool CanFormat(FunctionCallContent call) => call.Name.StartsWith("AgentMode_", StringComparison.Ordinal);
+    public override bool CanFormat(FunctionCallContent call) => call.Name.StartsWith("mode_", StringComparison.Ordinal);

    /// <inheritdoc/>
    public override string? FormatDetail(FunctionCallContent call) => call.Name switch
    {
-        "AgentMode_Set" => FormatStringArg(call, "mode"),
+        "mode_set" => FormatStringArg(call, "mode"),
        _ => null,
    };

@@ -19,7 +19,7 @@ public sealed class TodoToolFormatter : ToolCallFormatter
    public override string? FormatDetail(FunctionCallContent call) => call.Name switch
    {
        "TodoList_Add" => FormatAddTodos(call),
-        "TodoList_Complete" => FormatIdList(call, "ids", "Complete"),
+        "TodoList_Complete" => FormatCompleteTodos(call),
        "TodoList_Remove" => FormatIdList(call, "ids", "Remove"),
        _ => null,
    };
@@ -64,6 +64,50 @@ public sealed class TodoToolFormatter : ToolCallFormatter
        return sb.ToString();
    }

+    private static string? FormatCompleteTodos(FunctionCallContent call)
+    {
+        if (call.Arguments?.TryGetValue("items", out object? itemsObj) != true || itemsObj is null)
+        {
+            return null;
+        }
+
+        var entries = new List<(int Id, string? Reason)>();
+
+        if (itemsObj is JsonElement jsonArray && jsonArray.ValueKind == JsonValueKind.Array)
+        {
+            foreach (JsonElement item in jsonArray.EnumerateArray())
+            {
+                if (!item.TryGetProperty("id", out JsonElement idElement) || !idElement.TryGetInt32(out int id))
+                {
+                    continue;
+                }
+
+                string? reason = item.TryGetProperty("reason", out JsonElement reasonElement)
+                    ? reasonElement.GetString()
+                    : null;
+                entries.Add((id, reason));
+            }
+        }
+
+        if (entries.Count == 0)
+        {
+            return null;
+        }
+
+        var sb = new StringBuilder();
+        for (int i = 0; i < entries.Count; i++)
+        {
+            string connector = i < entries.Count - 1 ? "├─" : "└─";
+            sb.Append($"\n   {connector} Complete #{entries[i].Id}");
+            if (!string.IsNullOrEmpty(entries[i].Reason))
+            {
+                sb.Append($" — {Truncate(entries[i].Reason!, 80)}");
+            }
+        }
+
+        return sb.ToString();
+    }
+
    private static string? FormatIdList(FunctionCallContent call, string paramName, string verb)
    {
        List<int>? ids = GetIntListArgumentValue(call, paramName);
@@ -56,7 +56,7 @@ public abstract class ToolCallFormatter
        [
            new TodoToolFormatter(),
            new ModeToolFormatter(),
-            new SubAgentToolFormatter(),
+            new BackgroundAgentToolFormatter(),
            new FileMemoryToolFormatter(),
            new WebSearchToolFormatter(),
            new FallbackToolFormatter(),
@@ -0,0 +1,19 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="OpenAI" />
+    <PackageReference Include="Microsoft.Extensions.AI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\Harness_Shared_Console\Harness_Shared_Console.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,61 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+#pragma warning disable OPENAI001 // Suppress experimental API warnings for Responses API usage.
+
+using Harness.Shared.Console.Observers;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using OpenAI.Responses;
+
+namespace Harness.Shared.Console.OpenAI;
+
+/// <summary>
+/// Detects and displays error/incomplete status from OpenAI Responses API streaming updates.
+/// Handles <see cref="StreamingResponseFailedUpdate"/> and <see cref="StreamingResponseIncompleteUpdate"/>
+/// which are not surfaced as <see cref="ErrorContent"/> by the chat client.
+/// </summary>
+/// <remarks>
+/// Note: <see cref="StreamingResponseErrorUpdate"/> is already handled by the SDK — it produces
+/// an <see cref="ErrorContent"/> which is displayed by <see cref="ErrorDisplayObserver"/>.
+/// This observer covers the cases where the SDK does not produce <see cref="ErrorContent"/>.
+/// </remarks>
+public sealed class OpenAIResponsesErrorObserver : ConsoleObserver
+{
+    /// <inheritdoc/>
+    public override async Task OnResponseUpdateAsync(IUXStateDriver ux, AgentResponseUpdate update, AIAgent agent, AgentSession session)
+    {
+        // AgentResponseUpdate.RawRepresentation is the ChatResponseUpdate,
+        // whose RawRepresentation is the underlying StreamingResponseUpdate.
+        object? rawUpdate = (update.RawRepresentation as ChatResponseUpdate)?.RawRepresentation
+            ?? update.RawRepresentation;
+
+        switch (rawUpdate)
+        {
+            case StreamingResponseFailedUpdate failedUpdate:
+                // Only display if the response has error details populated.
+                // When error is null, a follow-up StreamingResponseErrorUpdate typically
+                // carries the real error — the SDK surfaces that as ErrorContent,
+                // which is displayed by ErrorDisplayObserver.
+                if (failedUpdate.Response?.Error is { } error)
+                {
+                    string errorMessage = error.Message ?? "Unknown error";
+                    string? errorCode = error.Code.ToString();
+                    string errorText = $"❌ Response failed: {errorMessage}";
+                    if (!string.IsNullOrEmpty(errorCode))
+                    {
+                        errorText += $" (code: {errorCode})";
+                    }
+
+                    await ux.WriteInfoLineAsync(errorText, ConsoleColor.Red);
+                }
+
+                break;
+
+            case StreamingResponseIncompleteUpdate incompleteUpdate:
+                string? reason = incompleteUpdate.Response?.IncompleteStatusDetails?.Reason?.ToString();
+                string incompleteText = $"⚠️ Response incomplete: {reason ?? "unknown reason"}";
+                await ux.WriteInfoLineAsync(incompleteText, ConsoleColor.Yellow);
+                break;
+        }
+    }
+}
@@ -0,0 +1,205 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+#pragma warning disable OPENAI001 // Suppress experimental API warnings for Responses API usage.
+
+using System.Text;
+using Harness.Shared.Console.Observers;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using OpenAI.Responses;
+
+namespace Harness.Shared.Console.OpenAI;
+
+/// <summary>
+/// Displays web search activity in the scroll area. Shows search queries,
+/// page opens, and find-in-page actions as they stream in from the API.
+/// </summary>
+public sealed class OpenAIResponsesWebSearchDisplayObserver : ConsoleObserver
+{
+    private const int MaxQueryDisplayLength = 120;
+
+    /// <inheritdoc/>
+    public override async Task OnContentAsync(IUXStateDriver ux, AIContent content, AIAgent agent, AgentSession session)
+    {
+        if (content is WebSearchToolResultContent resultContent
+            && resultContent.RawRepresentation is WebSearchCallResponseItem wscri)
+        {
+            await WriteActionAsync(ux, wscri, resultContent.Outputs);
+        }
+    }
+
+    private static async Task WriteActionAsync(IUXStateDriver ux, WebSearchCallResponseItem wscri, IList<AIContent>? outputs)
+    {
+        WebSearchAction? action = wscri.Action;
+        if (action is null)
+        {
+            await ux.WriteInfoLineAsync("🌐 Web Search Tool (no action details)", ConsoleColor.DarkCyan);
+            return;
+        }
+
+        switch (action)
+        {
+            case WebSearchFindInPageAction findInPage:
+                await WriteFindInPageAsync(ux, findInPage);
+                break;
+
+            case WebSearchOpenPageAction openPage:
+                await WriteOpenPageAsync(ux, openPage);
+                break;
+
+            case WebSearchSearchAction search:
+                await WriteSearchAsync(ux, search, outputs);
+                break;
+
+            default:
+                await ux.WriteInfoLineAsync("🌐 Web Search Tool (unknown action)", ConsoleColor.DarkCyan);
+                break;
+        }
+    }
+
+    private static async Task WriteSearchAsync(IUXStateDriver ux, WebSearchSearchAction search, IList<AIContent>? outputs)
+    {
+        // Read queries directly from the typed action.
+        IList<string> queries = search.Queries;
+
+        if (queries.Count == 0)
+        {
+            await ux.WriteInfoLineAsync("🌐 Web Search Tool: search", ConsoleColor.DarkCyan);
+            return;
+        }
+
+        var sb = new StringBuilder();
+        sb.Append("🌐 Web Search Tool: search");
+
+        // Show the search queries.
+        bool hasResults = outputs is { Count: > 0 };
+        for (int i = 0; i < queries.Count; i++)
+        {
+            string connector = (i < queries.Count - 1 || hasResults) ? "├─" : "└─";
+            string query = Truncate(queries[i], MaxQueryDisplayLength);
+            sb.Append($"\n   {connector} \"{query}\"");
+        }
+
+        // Show search result sources (URLs + titles) when available.
+        // Sources come from M.E.AI's Outputs when IncludedResponseProperty.WebSearchCallActionSources is set,
+        // or directly from the SDK's WebSearchSearchAction.Sources.
+        if (hasResults)
+        {
+            sb.Append("\n   │");
+            for (int i = 0; i < outputs!.Count; i++)
+            {
+                string connector = i < outputs.Count - 1 ? "├─" : "└─";
+                string line = FormatOutput(outputs[i]);
+                sb.Append($"\n   {connector} {line}");
+            }
+        }
+        else if (search.Sources is { Count: > 0 } sources)
+        {
+            sb.Append("\n   │");
+            for (int i = 0; i < sources.Count; i++)
+            {
+                string connector = i < sources.Count - 1 ? "├─" : "└─";
+                string line = FormatSource(sources[i]);
+                sb.Append($"\n   {connector} {line}");
+            }
+        }
+
+        await ux.WriteInfoLineAsync(sb.ToString(), ConsoleColor.DarkCyan);
+    }
+
+    private static async Task WriteOpenPageAsync(IUXStateDriver ux, WebSearchOpenPageAction openPage)
+    {
+        string url = openPage.Uri?.AbsoluteUri ?? "(unknown)";
+        await ux.WriteInfoLineAsync(
+            $"🌐 Web Search Tool: open page\n   └─ {url}",
+            ConsoleColor.DarkCyan);
+    }
+
+    private static async Task WriteFindInPageAsync(IUXStateDriver ux, WebSearchFindInPageAction findInPage)
+    {
+        string url = findInPage.Uri?.AbsoluteUri ?? "(unknown)";
+        string pattern = findInPage.Pattern ?? "(unknown)";
+
+        await ux.WriteInfoLineAsync(
+            $"🌐 Web Search Tool: find in page\n   ├─ \"{Truncate(pattern, MaxQueryDisplayLength)}\"\n   └─ {url}",
+            ConsoleColor.DarkCyan);
+    }
+
+    /// <summary>
+    /// Formats a single search result source from the SDK's <see cref="WebSearchActionSource"/> for display.
+    /// </summary>
+    private static string FormatSource(WebSearchActionSource source)
+    {
+        if (source is WebSearchActionUriSource uriSource)
+        {
+            string url = uriSource.Uri?.AbsoluteUri ?? "(unknown)";
+
+            // WebSearchActionUriSource doesn't expose a title property,
+            // but the API may include one in the raw response JSON.
+            string? title = GetTitleFromRawRepresentation(uriSource);
+
+            return title is not null
+                ? $"{Truncate(title, MaxQueryDisplayLength)} — {url}"
+                : url;
+        }
+
+        return source.ToString() ?? "(unknown source)";
+    }
+
+    /// <summary>
+    /// Formats a single search result output from M.E.AI's <see cref="AIContent"/> for display.
+    /// </summary>
+    private static string FormatOutput(AIContent output)
+    {
+        if (output is UriContent uriContent)
+        {
+            string url = uriContent.Uri?.AbsoluteUri ?? "(unknown)";
+
+            // Try to extract a title from the raw JSON of the source.
+            // The SDK's WebSearchActionUriSource doesn't expose a title property,
+            // but the API may include one in the raw response.
+            string? title = GetTitleFromRawRepresentation(uriContent.RawRepresentation)
+                ?? (uriContent.AdditionalProperties?.TryGetValue("title", out var t) is true ? t?.ToString() : null);
+
+            return title is not null
+                ? $"{Truncate(title, MaxQueryDisplayLength)} — {url}"
+                : url;
+        }
+
+        return output.ToString() ?? "(unknown output)";
+    }
+
+    /// <summary>
+    /// Attempts to extract a "title" field from a raw representation object by serializing it to JSON.
+    /// The SDK's <see cref="WebSearchActionUriSource"/> doesn't expose a title property,
+    /// but the API may include one in the raw JSON — this is forward-compatible for when
+    /// the SDK adds title support.
+    /// </summary>
+    private static string? GetTitleFromRawRepresentation(object? rawRepresentation)
+    {
+        if (rawRepresentation is null)
+        {
+            return null;
+        }
+
+        try
+        {
+            var data = System.ClientModel.Primitives.ModelReaderWriter.Write(rawRepresentation);
+            using var doc = System.Text.Json.JsonDocument.Parse(data);
+            if (doc.RootElement.TryGetProperty("title", out var titleEl)
+                && titleEl.ValueKind == System.Text.Json.JsonValueKind.String)
+            {
+                return titleEl.GetString();
+            }
+        }
+        catch
+        {
+            // Serialization may not be supported for this object type.
+        }
+
+        return null;
+    }
+
+    private static string Truncate(string text, int maxLength)
+        => text.Length <= maxLength ? text : string.Concat(text.AsSpan(0, maxLength - 1), "…");
+}
@@ -13,9 +13,10 @@
  </ItemGroup>

  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Harness\Microsoft.Agents.AI.Harness.csproj" />
-    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
    <ProjectReference Include="..\Harness_Shared_Console\Harness_Shared_Console.csproj" />
+    <ProjectReference Include="..\Harness_Shared_Console_OpenAI\Harness_Shared_Console_OpenAI.csproj" />
  </ItemGroup>

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

-// This sample demonstrates how to use a HarnessAgent with the Harness AIContextProviders
-// (TodoProvider and AgentModeProvider) for interactive research tasks with web search
-// capabilities powered by Azure AI Foundry.
+// This sample demonstrates how to use a HarnessAgent for interactive research tasks.
+// The HarnessAgent comes pre-configured with TodoProvider, AgentModeProvider, FileMemoryProvider,
+// ToolApproval, WebSearch, and OpenTelemetry — so this sample only needs custom instructions
+// and a WebBrowsingTool.
 // The agent plans research tasks, creates a todo list, gets user approval,
 // and then executes each step — all within an interactive conversation loop.
 //
@@ -15,147 +16,89 @@
 #pragma warning disable MAAI001  // Suppress experimental API warnings for Agents AI experiments.

 using System.ClientModel.Primitives;
+using Azure.AI.Projects;
 using Azure.Identity;
 using Harness.Shared.Console;
+using Harness.Shared.Console.OpenAI;
 using Harness.Shared.Console.ToolFormatters;
 using Microsoft.Agents.AI;
 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 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";

 const int MaxContextWindowTokens = 1_050_000;
 const int MaxOutputTokens = 128_000;
+const string TracingSourceName = "Harness.Research";
+
+// Set up OpenTelemetry tracing that writes spans to a text file.
+// This captures all agent activity (tool calls, model invocations, compaction, etc.)
+// as well as HTTP requests made by the underlying HttpClient transport.
+using var tracerProvider = HarnessTracing.CreateFileTracerProvider(TracingSourceName);

 // Create a HarnessAgent with the Harness providers (TodoProvider and AgentModeProvider)
 // and research-focused instructions including the mandatory planning workflow.
 var instructions =
    """
+    ## Research Assistant 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**
+    ### 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**
+    ### Presenting results

    When presenting your final findings:
+    - Use Markdown formatting for clarity.
    - 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.
+    - In addition to returning the results to the user, save the final research report to file memory so it survives compaction and can be referenced later.
    """;

 // Create the agent using AsHarnessAgent, which pre-configures function invocation,
-// per-service-call chat history persistence, and in-loop compaction.
-// Then wrap with UseToolApproval to allow auto-approving tools once confirmed.
+// per-service-call chat history persistence, in-loop compaction, TodoProvider, AgentModeProvider,
+// FileMemoryProvider, ToolApproval, WebSearch, AgentSkillsProvider, and OpenTelemetry.
+// Only custom instructions, a WebBrowsingTool, and FileAccess opt-out are needed.
 AIAgent agent =
    // Create an OpenAIClient that communicates with the Foundry responses service.
-    new OpenAIClient(
+    new AIProjectClient(
+        new Uri(endpoint),
        // 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.
-        })
+        new DefaultAzureCredential(),
+        new AIProjectClientOptions { RetryPolicy = new ClientRetryPolicy(3) })  // Enable retries to improve resiliency.
+    .GetProjectOpenAIClient()
    .GetResponsesClient()
-    .AsIChatClientWithStoredOutputDisabled(deploymentName)   // We want to manage chat history locally (not stored in the responses service), so that we can manage compaction ourselves.
+    .AsIChatClient(deploymentName)
    .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
    {
        Name = "ResearchAgent",
        Description = "A research assistant that plans and executes research tasks.",
-        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() })
-        ],
+        DisableFileAccess = true,                           // If enabled, this would allow the agent to read/write files in a working directory
+        OpenTelemetrySourceName = TracingSourceName,        // Use our custom source name so spans are captured by the TracerProvider above.
+        FileMemoryStore = new FileSystemAgentFileStore(     // Configure the file memory provider to store files in a local folder called "agent-files".
+            Path.Combine(AppContext.BaseDirectory, "agent-files")),
        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 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.
+            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(
@@ -163,12 +106,15 @@ await HarnessConsole.RunAgentAsync(
    userPrompt: "Enter a research topic to get started.",
    new HarnessConsoleOptions
    {
-        Observers = HarnessConsoleOptions.BuildObserversWithPlanning(
-            agent,
-            planModeName: "plan",
-            executionModeName: "execute",
-            maxContextWindowTokens: MaxContextWindowTokens,
-            maxOutputTokens: MaxOutputTokens,
-            toolFormatters: [new DownloadUriToolFormatter(), .. ToolCallFormatter.BuildDefaultToolFormatters()]),
+        Observers = [
+            new OpenAIResponsesWebSearchDisplayObserver(),
+            new OpenAIResponsesErrorObserver(),
+            .. HarnessConsoleOptions.BuildObserversWithPlanning(
+                agent,
+                planModeName: "plan",
+                executionModeName: "execute",
+                maxContextWindowTokens: MaxContextWindowTokens,
+                maxOutputTokens: MaxOutputTokens,
+                toolFormatters: [new DownloadUriToolFormatter(), .. ToolCallFormatter.BuildDefaultToolFormatters()])],
        CommandHandlers = HarnessConsoleOptions.BuildDefaultCommandHandlers(agent),
    });
@@ -13,9 +13,10 @@
  </ItemGroup>

  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Harness\Microsoft.Agents.AI.Harness.csproj" />
-    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
    <ProjectReference Include="..\Harness_Shared_Console\Harness_Shared_Console.csproj" />
+    <ProjectReference Include="..\Harness_Shared_Console_OpenAI\Harness_Shared_Console_OpenAI.csproj" />
  </ItemGroup>

 </Project>
@@ -0,0 +1,121 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to use the BackgroundAgentsProvider to delegate work to background 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 background agent.
+// The HarnessAgent provides built-in WebSearch (HostedWebSearchTool) so no manual web search
+// tool configuration is needed on the background agent.
+//
+// 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.AI.Projects;
+using Azure.Identity;
+using Harness.Shared.Console;
+using Harness.Shared.Console.OpenAI;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.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";
+
+const int MaxContextWindowTokens = 1_050_000;
+const int MaxOutputTokens = 128_000;
+const string TracingSourceName = "Harness.SubAgents";
+
+// Set up OpenTelemetry tracing that writes spans to a text file.
+using var tracerProvider = HarnessTracing.CreateFileTracerProvider(TracingSourceName);
+
+// Create the AIProjectClient for communicating with the Foundry responses service.
+var projectClient = new AIProjectClient(
+    new Uri(endpoint),
+    new DefaultAzureCredential(),
+    new AIProjectClientOptions { RetryPolicy = new ClientRetryPolicy(3) });
+
+// --- Background agent: Web Search Agent ---
+// This agent uses the HarnessAgent's built-in HostedWebSearchTool to search the web.
+// Features not needed by this sub-agent are disabled.
+AIAgent webSearchAgent =
+    projectClient
+    .GetProjectOpenAIClient()
+    .GetResponsesClient()
+    .AsIChatClient(deploymentName)
+    .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
+    {
+        Name = "WebSearchAgent",
+        Description = "An agent that can search the web to find information.",
+        OpenTelemetrySourceName = TracingSourceName,
+        DisableTodoProvider = true,
+        DisableAgentModeProvider = true,
+        DisableFileMemory = true,   // If enabled, this would allow the agent to store memories as files in a directory associated with the current session
+        DisableFileAccess = true,   // If enabled, this would allow the agent to read/write files in a working directory
+        DisableToolApproval = true, // If enabled, this allows don't-ask-again approval functionality.
+        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.",
+        },
+    });
+
+// --- Parent agent: Stock Price Researcher ---
+// This agent orchestrates the background agent to look up stock prices in parallel.
+var parentInstructions =
+    """
+    You are a stock price research assistant. You have access to a web search background 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 background task on the WebSearchAgent asking it to find the closing price on December 31, 2025.
+       - Start all background tasks before waiting for any of them to complete, so they run concurrently.
+    2. Wait for all background tasks to complete.
+    3. Retrieve the results from each background 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 background agent. Do not try to answer from memory.
+    - If a background task fails or returns unclear results, continue the task with a more specific query.
+    - Present results in a clean markdown table format.
+    """;
+
+// --- Parent agent: Stock Price Researcher ---
+// This agent orchestrates the sub-agent to look up stock prices in parallel.
+// Most features are disabled since the parent only needs SubAgentsProvider.
+AIAgent parentAgent =
+    projectClient
+    .GetProjectOpenAIClient()
+    .GetResponsesClient()
+    .AsIChatClient(deploymentName)
+    .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
+    {
+        Name = "StockPriceResearcher",
+        Description = "An agent that researches stock prices using background agents.",
+        OpenTelemetrySourceName = TracingSourceName,
+        DisableTodoProvider = true,
+        DisableAgentModeProvider = true,
+        DisableFileMemory = true,   // If enabled, this would allow the agent to store memories as files in a directory associated with the current session
+        DisableFileAccess = true,   // If enabled, this would allow the agent to read/write files in a working directory
+        DisableToolApproval = true, // If enabled, this allows don't-ask-again approval functionality.
+        DisableWebSearch = true,
+        BackgroundAgents = [webSearchAgent],
+        ChatOptions = new ChatOptions
+        {
+            Instructions = parentInstructions,
+            MaxOutputTokens = 16_000,
+        },
+    });
+
+// Run the interactive console session.
+await HarnessConsole.RunAgentAsync(
+    parentAgent,
+    userPrompt: "Enter a list of stock tickers (e.g., BAC, MSFT, BA):",
+    options: new HarnessConsoleOptions
+    {
+        Observers = [new OpenAIResponsesErrorObserver(), .. HarnessConsoleOptions.BuildDefaultObservers()],
+    });
@@ -1,24 +1,24 @@
-# Harness Step 02 — SubAgents (Stock Price Research)
+# Harness Step 02 — BackgroundAgents (Stock Price Research)

-This sample demonstrates how to use the **SubAgentsProvider** to delegate work from a parent agent to sub-agents. Both agents use `HarnessAgent` for pre-configured function invocation, per-service-call persistence, and context-window compaction.
+This sample demonstrates how to use the **BackgroundAgentsProvider** to delegate work from a parent agent to background agents. Both agents use `HarnessAgent` for pre-configured function invocation, per-service-call persistence, and context-window compaction.

 ## 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.
+A parent agent receives a list of stock tickers and uses a web-search background agent to find the closing price for each ticker on December 31, 2025. The background tasks run concurrently, and results are presented in a summary table.

 ### Architecture

 ```
-┌─────────────────────────────────┐
-│     StockPriceResearcher        │
-│         (Parent Agent)          │
-│                                 │
-│  SubAgentsProvider              │
-│    ├─ SubAgents_StartTask       │
-│    ├─ SubAgents_WaitFor...      │
-│    ├─ SubAgents_GetTaskResults  │
-│    └─ ...                       │
-└────────────┬────────────────────┘
+┌────────────────────────────────────────┐
+│     StockPriceResearcher               │
+│         (Parent Agent)                 │
+│                                        │
+│  BackgroundAgentsProvider              │
+│    ├─ BackgroundAgents_StartTask       │
+│    ├─ BackgroundAgents_WaitFor...      │
+│    ├─ BackgroundAgents_GetTaskResults  │
+│    └─ ...                              │
+└────────────┬───────────────────────────┘
             │  delegates to
             ▼
 ┌─────────────────────────────────┐
@@ -40,7 +40,7 @@ A parent agent receives a list of stock tickers and uses a web-search sub-agent
 ## Running the Sample

 ```bash
-cd dotnet/samples/02-agents/Harness/Harness_Step02_Research_WithSubAgents
+cd dotnet/samples/02-agents/Harness/Harness_Step02_Research_WithBackgroundAgents
 dotnet run
 ```

@@ -50,4 +50,4 @@ 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.
+The parent agent will delegate each ticker lookup to the web search background agent concurrently and present the results in a table.
@@ -1,106 +0,0 @@
-// 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";
-
-const int MaxContextWindowTokens = 1_050_000;
-const int MaxOutputTokens = 128_000;
-
-// --- 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)
-    .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
-    {
-        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)
-    .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
-    {
-        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,
-    userPrompt: "Enter a list of stock tickers (e.g., BAC, MSFT, BA):");
@@ -13,13 +13,13 @@
  </ItemGroup>

  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Harness\Microsoft.Agents.AI.Harness.csproj" />
-    <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" />
+    <Content Include="working\**\*" CopyToOutputDirectory="PreserveNewest" />
  </ItemGroup>

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

-// This sample demonstrates how to use a HarnessAgent with the FileAccessProvider
+// This sample demonstrates how to use a HarnessAgent with the default 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.
+// The sample includes a pre-populated `working/` folder with sales transaction data.
+// The HarnessAgent's default FileAccessProvider uses `{cwd}/working` as its working directory,
+// which matches this sample's folder layout.
 // Ask the agent to analyze the data, produce summaries, or create new output files.
 //
 // Special commands:
@@ -14,22 +16,21 @@
 #pragma warning disable MAAI001  // Suppress experimental API warnings for Agents AI experiments.

 using System.ClientModel.Primitives;
+using Azure.AI.Projects;
 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 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";

 const int MaxContextWindowTokens = 1_050_000;
 const int MaxOutputTokens = 128_000;
+const string TracingSourceName = "Harness.DataProcessing";

-// 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);
+// Set up OpenTelemetry tracing that writes spans to a text file.
+using var tracerProvider = HarnessTracing.CreateFileTracerProvider(TracingSourceName);

 var instructions =
    """
@@ -56,25 +57,27 @@ var instructions =
    - 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 the chat client from the OpenAI provider.
+// Create the agent using AsHarnessAgent. The FileAccessStore is explicitly set to the
+// sample's working/ folder (copied to the output directory) so it works regardless of cwd.
+// Unused features are disabled.
 AIAgent agent =
-    new OpenAIClient(
-        new BearerTokenPolicy(new DefaultAzureCredential(), "https://ai.azure.com/.default"),
-        new OpenAIClientOptions()
-        {
-            Endpoint = new Uri(endpoint),
-            RetryPolicy = new ClientRetryPolicy(3)
-        })
+    new AIProjectClient(
+        new Uri(endpoint),
+        new DefaultAzureCredential(),
+        new AIProjectClientOptions { RetryPolicy = new ClientRetryPolicy(3) })
+    .GetProjectOpenAIClient()
    .GetResponsesClient()
-    .AsIChatClientWithStoredOutputDisabled(deploymentName)
+    .AsIChatClient(deploymentName)
    .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
    {
        Name = "DataAnalyst",
        Description = "A data analyst assistant that reads, analyzes, and processes data files.",
-        AIContextProviders =
-        [
-            new FileAccessProvider(fileStore),
-        ],
+        OpenTelemetrySourceName = TracingSourceName,
+        FileAccessStore = new FileSystemAgentFileStore(Path.Combine(AppContext.BaseDirectory, "working")),
+        DisableTodoProvider = true,
+        DisableAgentModeProvider = true,
+        DisableFileMemory = true,   // If enabled, this would allow the agent to store memories as files in a directory associated with the current session
+        DisableWebSearch = true,
        ChatOptions = new ChatOptions
        {
            Instructions = instructions,
@@ -1,11 +1,11 @@
 # What this sample demonstrates

-This sample demonstrates how to use a `HarnessAgent` with the `FileAccessProvider` to give an agent access to a folder of data files for reading, analyzing, and writing results. The `HarnessAgent` pre-configures function invocation, per-service-call chat history persistence, and in-loop compaction — so the sample only needs to supply the chat client, token limits, and application-specific options.
+This sample demonstrates how to use a `HarnessAgent` with the default `FileAccessProvider` to give an agent access to a folder of data files for reading, analyzing, and writing results. The `HarnessAgent` pre-configures function invocation, per-service-call chat history persistence, in-loop compaction, tool approval, and OpenTelemetry — so the sample only needs to supply the chat client, token limits, custom instructions, and opt out of unused features.

 Key features showcased:

 - **HarnessAgent** — a pre-configured agent that wraps a `ChatClientAgent` with function invocation, per-service-call persistence, and context-window compaction
- **FileAccessProvider** — gives the agent tools to read, write, list, search, and delete files in a shared data folder
+- **FileAccessProvider** — the HarnessAgent's default file access provider uses `{cwd}/working` as its working directory, matching this sample's `working/` 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
@@ -39,7 +39,7 @@ 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).
+The sample starts an interactive conversation with a data analyst agent. The `working/` 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:

@@ -53,7 +53,7 @@ E.g. try the following prompt `Please process the sales.csv file by first filter

 ## Sample Data

-The included `data/sales.csv` contains sales transactions from January to March 2025 with the following columns:
+The included `working/sales.csv` contains sales transactions from January to March 2025 with the following columns:

 | Column | Description |
 | --- | --- |
@@ -0,0 +1,29 @@
+<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="Hyperlight.HyperlightSandbox.Guest.Python" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Harness\Microsoft.Agents.AI.Harness.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Hyperlight\Microsoft.Agents.AI.Hyperlight.csproj" />
+    <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="skills\**\*" CopyToOutputDirectory="PreserveNewest" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,122 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates a HarnessAgent with ALL features enabled, plus:
+// - Hyperlight CodeAct (HyperlightCodeActProvider) for sandboxed Python code execution
+// - Skills (AgentSkillsProvider) discovering a local "regex-tester" skill
+//
+// The agent can plan tasks with todos, manage modes, store memories, read/write files,
+// search the web, approve sensitive tools, discover and use skills, and execute arbitrary
+// Python code in a Hyperlight sandbox — all pre-configured by the HarnessAgent.
+//
+// Try asking: "Help me write a regex that matches valid email addresses, then test it."
+//
+// Special commands:
+//   /todos  — Display the current todo list without invoking the agent.
+//   /mode   — Get or set the current agent mode.
+//   /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.AI.Projects;
+using Azure.Identity;
+using Harness.Shared.Console;
+using HyperlightSandbox.Guest.Python;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Hyperlight;
+using Microsoft.Extensions.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";
+
+const int MaxContextWindowTokens = 1_050_000;
+const int MaxOutputTokens = 128_000;
+const string TracingSourceName = "Harness.CodeExecution";
+
+// Set up OpenTelemetry tracing that writes spans to a text file.
+using var tracerProvider = HarnessTracing.CreateFileTracerProvider(TracingSourceName);
+
+// Create the HyperlightCodeActProvider with the Python/Wasm backend.
+// The guest module path is resolved automatically from the Hyperlight.HyperlightSandbox.Guest.Python NuGet package.
+using var codeAct = new HyperlightCodeActProvider(
+    HyperlightCodeActProviderOptions.CreateForWasm(PythonGuestModule.GetModulePath()));
+
+var instructions =
+    """
+    ## Technical Assistant Instructions
+
+    You are a code-powered technical assistant. You can execute Python code in a sandboxed environment
+    to solve problems precisely rather than guessing. You also have access to skills that provide
+    structured workflows for specific technical tasks.
+
+    ### Code Execution
+
+    When a problem requires computation, validation, or testing:
+    - Write Python code and use `execute_code` to run it in the sandbox.
+    - Always verify results by running the code rather than reasoning about what would happen.
+    - If code fails, read the error message carefully, fix the issue, and retry.
+
+    ### Skills
+
+    You have access to discoverable skills. When a task matches a skill's description:
+    - Follow the skill's instructions carefully.
+    - Use the skill's reference materials for context.
+    - Combine the skill's workflow with code execution when appropriate.
+
+    ### Planning and Research
+
+    For complex tasks:
+    - Break the problem into steps using your todo list.
+    - Research background information using web search when needed.
+    - Save important findings to file memory for later reference.
+
+    ### Presenting Results
+
+    - Show your work: include the code you ran and its output.
+    - Explain what each part of your solution does.
+    - If applicable, save final results to file memory.
+    """;
+
+// Create the agent with ALL HarnessAgent features enabled plus Hyperlight CodeAct.
+// No Disable* flags are set — TodoProvider, AgentModeProvider, FileMemory, FileAccess,
+// ToolApproval, WebSearch, and AgentSkillsProvider are all active.
+AIAgent agent =
+    new AIProjectClient(
+        new Uri(endpoint),
+        new DefaultAzureCredential(),
+        new AIProjectClientOptions { RetryPolicy = new ClientRetryPolicy(3) })
+    .GetProjectOpenAIClient()
+    .GetResponsesClient()
+    .AsIChatClient(deploymentName)
+    .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
+    {
+        Name = "CodeExecutionAgent",
+        Description = "A technical assistant with sandboxed code execution and skill-based workflows.",
+        OpenTelemetrySourceName = TracingSourceName,
+        // Point the file memory at a local folder for persistent memory across sessions.
+        FileMemoryStore = new FileSystemAgentFileStore(Path.Combine(AppContext.BaseDirectory, "agent-files")),
+        // Add the HyperlightCodeActProvider so the agent can execute Python code in a sandbox.
+        AIContextProviders = [codeAct],
+        ChatOptions = new ChatOptions
+        {
+            Instructions = instructions,
+            MaxOutputTokens = MaxOutputTokens,
+            Reasoning = new() { Effort = ReasoningEffort.Medium },
+        },
+    });
+
+// Run the interactive console session using the shared HarnessConsole helper.
+await HarnessConsole.RunAgentAsync(
+    agent,
+    userPrompt: "Ask me a technical question, or try: \"Help me write a regex that matches valid email addresses.\"",
+    new HarnessConsoleOptions
+    {
+        Observers = HarnessConsoleOptions.BuildObserversWithPlanning(
+            agent,
+            planModeName: "plan",
+            executionModeName: "execute",
+            maxContextWindowTokens: MaxContextWindowTokens,
+            maxOutputTokens: MaxOutputTokens),
+        CommandHandlers = HarnessConsoleOptions.BuildDefaultCommandHandlers(agent),
+    });
@@ -0,0 +1,51 @@
+# Harness Step 04 — Code Execution (Hyperlight + Skills)
+
+This sample demonstrates a HarnessAgent with **all features enabled**, plus:
+
+- **Hyperlight CodeAct** — sandboxed Python code execution via `execute_code` (requires KVM)
+- **Skills** — file-based skill discovery (a `regex-tester` skill is included)
+
+The agent can plan tasks, manage modes, store memories, read/write files, search the web, approve sensitive operations, discover and use skills, and execute arbitrary Python code — all pre-configured by the HarnessAgent.
+
+## Prerequisites
+
+- .NET 10 SDK
+- An Azure AI Foundry project endpoint
+- KVM-capable host (the Hyperlight sandbox runs code in micro-VMs)
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `AZURE_AI_PROJECT_ENDPOINT` | Your Azure AI Foundry project endpoint |
+| `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Model deployment name (default: `gpt-5.4`) |
+
+## Running
+
+```bash
+dotnet run
+```
+
+## What to Try
+
+- **Regex testing**: "Help me write a regex that matches valid email addresses, then test it against some examples."
+- **Code execution**: "Calculate the first 20 prime numbers using the Sieve of Eratosthenes."
+- **Skill + code combo**: "I need a regex for ISO 8601 dates — test it thoroughly with edge cases."
+
+## Included Skill
+
+The `skills/regex-tester/` skill instructs the agent to validate regex patterns by executing Python test code in the Hyperlight sandbox. It includes a regex cheatsheet as reference material.
+
+## Features Enabled
+
+| Feature | Description |
+|---------|-------------|
+| TodoProvider | Task planning and tracking (`/todos` command) |
+| AgentModeProvider | Mode switching (`/mode` command) |
+| FileMemoryProvider | Persistent memory stored as files |
+| FileAccessProvider | Read/write files in a working directory |
+| ToolApproval | Don't-ask-again approval for sensitive tools |
+| WebSearch | Built-in hosted web search |
+| AgentSkillsProvider | Discovers and uses skills from the `skills/` folder |
+| HyperlightCodeActProvider | Sandboxed Python execution via `execute_code` |
+| OpenTelemetry | Trace logging to a text file |
@@ -0,0 +1,36 @@
+---
+name: regex-tester
+description: Validate, test, and debug regular expressions by executing them against sample inputs. Use when asked to build, verify, or explain a regex pattern.
+---
+
+## Usage
+
+When the user asks you to create, validate, or debug a regular expression:
+
+1. **Understand the requirement** — clarify what the pattern should match and what it should reject.
+2. **Consult the cheatsheet** — review `references/regex-cheatsheet.md` for syntax reminders if needed.
+3. **Write and execute test code** — use the `execute_code` tool to run Python code that:
+   - Compiles the regex with `re.compile()`
+   - Tests it against a set of positive examples (should match) and negative examples (should not match)
+   - Extracts and displays any capturing groups
+   - Reports pass/fail for each test case
+4. **Iterate** — if any test fails, refine the pattern and re-run until all cases pass.
+5. **Present the result** — give the user the final pattern, explain what each part does, and show the test results.
+
+## Example Test Script
+
+```python
+import re
+
+pattern = re.compile(r'^[\w.+-]+@[\w-]+\.[\w.-]+$')
+
+positives = ["user@example.com", "first.last+tag@sub.domain.org"]
+negatives = ["@missing.com", "no-at-sign", "spaces in@address.com"]
+
+for s in positives:
+    assert pattern.match(s), f"FAIL: expected match for '{s}'"
+for s in negatives:
+    assert not pattern.match(s), f"FAIL: expected no match for '{s}'"
+
+print("All tests passed!")
+```
@@ -0,0 +1,97 @@
+# Regex Quick Reference (Python `re` module)
+
+## Character Classes
+
+| Pattern | Matches |
+|---------|---------|
+| `.`     | Any character except newline |
+| `\d`    | Digit `[0-9]` |
+| `\D`    | Non-digit |
+| `\w`    | Word character `[a-zA-Z0-9_]` |
+| `\W`    | Non-word character |
+| `\s`    | Whitespace `[ \t\n\r\f\v]` |
+| `\S`    | Non-whitespace |
+| `[abc]` | Any of a, b, or c |
+| `[^abc]`| Any character except a, b, c |
+| `[a-z]` | Range: a through z |
+
+## Quantifiers
+
+| Pattern | Meaning |
+|---------|---------|
+| `*`     | 0 or more (greedy) |
+| `+`     | 1 or more (greedy) |
+| `?`     | 0 or 1 (greedy) |
+| `{n}`   | Exactly n |
+| `{n,}`  | n or more |
+| `{n,m}` | Between n and m |
+| `*?`, `+?`, `??` | Non-greedy versions |
+
+## Anchors
+
+| Pattern | Meaning |
+|---------|---------|
+| `^`     | Start of string (or line with `re.MULTILINE`) |
+| `$`     | End of string (or line with `re.MULTILINE`) |
+| `\b`    | Word boundary |
+| `\B`    | Non-word boundary |
+
+## Groups and Backreferences
+
+| Pattern | Meaning |
+|---------|---------|
+| `(...)` | Capturing group |
+| `(?:...)`| Non-capturing group |
+| `(?P<name>...)` | Named group |
+| `\1`    | Backreference to group 1 |
+| `(?=...)` | Positive lookahead |
+| `(?!...)` | Negative lookahead |
+| `(?<=...)` | Positive lookbehind |
+| `(?<!...)` | Negative lookbehind |
+
+## Flags
+
+| Flag | Effect |
+|------|--------|
+| `re.IGNORECASE` / `re.I` | Case-insensitive matching |
+| `re.MULTILINE` / `re.M`  | `^`/`$` match line boundaries |
+| `re.DOTALL` / `re.S`     | `.` matches newline |
+| `re.VERBOSE` / `re.X`    | Allow comments and whitespace |
+
+## Common Patterns
+
+| Use Case | Pattern |
+|----------|---------|
+| Email (simple) | `^[\w.+-]+@[\w-]+\.[\w.-]+$` |
+| IPv4 address | `^\d{1,3}(\.\d{1,3}){3}$` |
+| ISO date | `^\d{4}-\d{2}-\d{2}$` |
+| URL (http/https) | `^https?://[^\s/$.?#].[^\s]*$` |
+| Phone (US) | `^(\+1)?[-.\s]?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}$` |
+
+## Python API
+
+```python
+import re
+
+# Test if a string matches
+re.match(r'pattern', "string")       # match at start
+re.search(r'pattern', "string")      # match anywhere
+re.fullmatch(r'pattern', "string")   # match entire string
+
+# Find all matches
+re.findall(r'\d+', "abc 123 def 456")  # ['123', '456']
+
+# Named groups
+m = re.match(r'(?P<year>\d{4})-(?P<month>\d{2})-(?P<day>\d{2})', "2025-01-15")
+m.group('year')   # '2025'
+
+# Replace
+re.sub(r'\d+', 'X', "abc 123 def")   # 'abc X def'
+
+# Split
+re.split(r',+', "a,b,,c")            # ['a', 'b', 'c']
+
+# Compile for reuse
+pattern = re.compile(r'^\d{4}-\d{2}-\d{2}$')
+pattern.match("2025-01-15")           # Match object
+```
@@ -7,5 +7,5 @@ Samples demonstrating the [Harness AIContextProviders](../../../src/Microsoft.Ag
 | 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_Step02_Research_WithBackgroundAgents](./Harness_Step02_Research_WithBackgroundAgents/README.md) | Using BackgroundAgentsProvider to delegate stock price lookups to a web-search background 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 |
@@ -0,0 +1,25 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <NoWarn>$(NoWarn);MAAI001;MEAI001;MCPEXP001</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+    <PackageReference Include="Microsoft.Extensions.Hosting" />
+    <PackageReference Include="ModelContextProtocol" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Mcp\Microsoft.Agents.AI.Mcp.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,145 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates the Microsoft Agent Framework's MCP long-running task support.
+//
+// A small MCP server (hosted in this same executable when launched with "--server") exposes
+// a single task-supporting tool "AnalyzeDataset" that simulates ~15 seconds of work. The
+// client (default mode) connects to it over stdio via Microsoft.Agents.AI.Mcp's
+// McpClientTaskExtensions.ListAgentToolsWithTaskSupportAsync, hands the wrapped tools to a
+// ChatClientAgent, and exercises both invocation styles:
+//   * RunAsync          — blocks until the agent's final response is ready.
+//   * RunStreamingAsync — yields response updates as the model produces them; the model
+//                         still waits for the tool's terminal result before it can begin
+//                         producing the final answer, so the perceived "pause" reflects
+//                         tool execution time, not stream-channel latency.
+//
+// In both cases the wrapper transparently:
+//   1. Calls tools/call with task augmentation (CallToolAsTaskAsync)
+//   2. Polls tasks/get until terminal (PollTaskUntilCompleteAsync)
+//   3. Fetches tasks/result and returns the final result to the function-calling loop
+//
+// No application-level loop or continuation tokens are required in either mode.
+
+using System.ComponentModel;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Mcp;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using ModelContextProtocol;
+using ModelContextProtocol.Client;
+using ModelContextProtocol.Protocol;
+using ModelContextProtocol.Server;
+using OpenAI.Chat;
+
+if (args.Length > 0 && args[0] == "--server")
+{
+    await RunMcpServerAsync();
+    return;
+}
+
+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";
+
+// Launch this same assembly as a stdio MCP server in a child process.
+var thisAssemblyPath = typeof(Program).Assembly.Location;
+await using var mcpClient = await McpClient.CreateAsync(new StdioClientTransport(new()
+{
+    Name = "DatasetAnalyzer",
+    Command = "dotnet",
+    Arguments = [thisAssemblyPath, "--server"],
+}));
+
+// Wrap each MCP tool with task-aware behavior. The wrapper inspects the server's
+// execution.taskSupport on each tool and, when it is Required, drives the task lifecycle
+// transparently within the agent's tool loop. Tools that don't require task semantics are
+// returned as-is and invoked inline.
+var taskOptions = new McpTaskOptions
+{
+    DefaultTimeToLive = TimeSpan.FromMinutes(5),
+};
+var mcpTools = await mcpClient.ListAgentToolsWithTaskSupportAsync(taskOptions);
+
+// 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.
+AIAgent agent = new AzureOpenAIClient(
+    new Uri(endpoint),
+    new DefaultAzureCredential())
+     .GetChatClient(deploymentName)
+     .AsAIAgent(
+        instructions: "You answer data-analysis questions by invoking the available tools. Always invoke a tool when one matches the request.",
+        tools: [.. mcpTools.Cast<AITool>()]);
+
+const string Prompt = "Analyze the dataset named 'sales-2025-q1' and summarize the findings.";
+
+Console.WriteLine("=== Transparent long-running MCP task (RunAsync) ===");
+Console.WriteLine("Asking the agent to analyze a dataset; the tool takes ~15s to complete.");
+Console.WriteLine("RunAsync blocks while the wrapper polls the task to completion.");
+Console.WriteLine();
+
+var stopwatch = System.Diagnostics.Stopwatch.StartNew();
+var response = await agent.RunAsync(Prompt);
+stopwatch.Stop();
+
+Console.WriteLine($"Agent response (after {stopwatch.Elapsed.TotalSeconds:F1}s):");
+Console.WriteLine(response.Text);
+
+Console.WriteLine();
+Console.WriteLine("=== Transparent long-running MCP task (RunStreamingAsync) ===");
+Console.WriteLine("Same request via the streaming API. Updates only begin to arrive after the");
+Console.WriteLine("tool's task reaches the Completed state, since the model needs the tool result");
+Console.WriteLine("before it can produce its final answer.");
+Console.WriteLine();
+
+stopwatch.Restart();
+await foreach (var update in agent.RunStreamingAsync(Prompt))
+{
+    Console.Write(update.Text);
+}
+stopwatch.Stop();
+
+Console.WriteLine();
+Console.WriteLine($"(Streaming completed after {stopwatch.Elapsed.TotalSeconds:F1}s.)");
+
+// --- Server mode (launched as a child process via --server) ---------------------------------
+static async Task RunMcpServerAsync()
+{
+    var builder = Host.CreateApplicationBuilder();
+
+    // Critical for stdio transport: any provider that writes to stdout will corrupt the
+    // JSON-RPC channel. Clear all providers; the MCP SDK routes its own diagnostics
+    // appropriately.
+    builder.Logging.ClearProviders();
+    builder.Logging.AddConsole(o => o.LogToStandardErrorThreshold = LogLevel.Trace);
+
+    builder.Services.AddMcpServer(o =>
+    {
+        o.TaskStore = new InMemoryMcpTaskStore();
+        o.ServerInfo = new Implementation { Name = "DatasetAnalyzer", Version = "1.0.0" };
+    })
+    .WithStdioServerTransport()
+    .WithTools<DatasetAnalysisTools>();
+
+    await builder.Build().RunAsync();
+}
+
+#pragma warning disable CA1812 // Discovered by MCP SDK via [McpServerToolType] attribute
+[McpServerToolType]
+internal sealed class DatasetAnalysisTools
+#pragma warning restore CA1812
+{
+    [McpServerTool(Name = "AnalyzeDataset", TaskSupport = ToolTaskSupport.Required)]
+    [Description("Analyze a tabular dataset and return summary statistics. This tool simulates a long-running analytic job (~15 seconds).")]
+    public static async Task<string> AnalyzeDatasetAsync(
+        [Description("The dataset identifier, e.g. 'sales-2025-q1'.")] string datasetName,
+        CancellationToken cancellationToken)
+    {
+        await Task.Delay(TimeSpan.FromSeconds(15), cancellationToken).ConfigureAwait(false);
+
+        return $"Findings for '{datasetName}': 12,403 rows; avg revenue $48,712; 3 anomalies detected in week 7; outliers concentrated in EMEA region.";
+    }
+}
@@ -0,0 +1,60 @@
+# Agent with MCP long-running task (transparent polling)
+
+This sample demonstrates Microsoft Agent Framework's MCP long-running task support: an agent invokes an MCP tool whose execution takes too long for a single request/response cycle, and the framework polls it to completion behind the function-calling loop. From the agent's perspective the tool simply returns its result.
+
+## What this sample shows
+
+- Using `McpClient.ListAgentToolsWithTaskSupportAsync(...)` (in `Microsoft.Agents.AI.Mcp`) to wrap MCP tools with task-aware behavior.
+- Configuring `McpTaskOptions.DefaultTimeToLive` to bound the server-side task.
+- Hosting a small MCP server (in this same executable, launched with `--server`) that advertises `execution.taskSupport=required` on a tool that sleeps for ~15 seconds.
+- No application-level polling, continuation tokens, or `AllowBackgroundResponses` flag are required.
+
+The decorator drives the lifecycle internally:
+
+1. `tools/call` augmented with task metadata (`CallToolAsTaskAsync`)
+2. `tasks/get` polled until terminal (`PollTaskUntilCompleteAsync`)
+3. `tasks/result` retrieved (`GetTaskResultAsync`) and returned to the function-calling loop
+
+The sample exercises both invocation styles against the same wrapper:
+
+- `agent.RunAsync(...)` blocks until the tool completes (~15 seconds in this sample) and returns the final response.
+- `agent.RunStreamingAsync(...)` returns immediately and yields `AgentResponseUpdate` chunks as the model emits them; in this scenario the model only begins streaming its answer once the wrapped tool's task reaches the `Completed` state, so the perceived "pause" before tokens arrive reflects tool execution time, not stream-channel latency.
+
+# Prerequisites
+
+- .NET 10 SDK or later
+- Azure OpenAI service endpoint and a chat-completions deployment
+- Azure CLI installed and authenticated (`az login`)
+
+Set the following environment variables:
+
+```powershell
+$env:AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
+$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-5.4-mini"  # optional; defaults to gpt-5.4-mini
+```
+
+# Running
+
+```powershell
+cd Agent_MCP_LongRunningTask_Client
+dotnet run
+```
+
+You should see output similar to:
+
+```
+=== Transparent long-running MCP task (RunAsync) ===
+Asking the agent to analyze a dataset; the tool takes ~15s to complete.
+RunAsync blocks while the wrapper polls the task to completion.
+
+Agent response (after 15.4s):
+The 'sales-2025-q1' dataset contains 12,403 rows ...
+
+=== Transparent long-running MCP task (RunStreamingAsync) ===
+Same request via the streaming API. Updates only begin to arrive after the
+tool's task reaches the Completed state, since the model needs the tool result
+before it can produce its final answer.
+
+The 'sales-2025-q1' dataset contains 12,403 rows ...
+(Streaming completed after 15.7s.)
+```
@@ -22,6 +22,7 @@ Before you begin, ensure you have the following prerequisites:
 |[Agent with MCP server tools](./Agent_MCP_Server/)|This sample demonstrates how to use MCP server tools with a simple agent|
 |[Agent with MCP server tools and authorization](./Agent_MCP_Server_Auth/)|This sample demonstrates how to use MCP Server tools from a protected MCP server with a simple agent|
 |[Responses Agent with Hosted MCP tool](./ResponseAgent_Hosted_MCP/)|This sample demonstrates how to use the Hosted MCP tool with the Responses Service, where the service invokes any MCP tools directly|
+|[Agent with long-running MCP task (transparent polling)](./Agent_MCP_LongRunningTask_Client/)|This sample demonstrates how an agent transparently drives a long-running MCP task (SEP-2663) to completion. The wrapper polls the task internally on both `RunAsync` and `RunStreamingAsync` invocations.|

 ## Running the samples from the console

@@ -0,0 +1,23 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <NoWarn>$(NoWarn);MAAIW001;OPENAI001</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Projects" />
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,193 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample ports the Python Magentic orchestration sample to .NET.
+// A Magentic workflow coordinates a researcher and a coder, streams orchestration
+// events as the plan evolves, and prints the final conversation transcript.
+
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Agents.AI.Workflows.Specialized.Magentic;
+using Microsoft.Extensions.AI;
+
+namespace WorkflowMagenticOrchestrationSample;
+
+/// <summary>
+/// Demonstrates Magentic orchestration with a researcher, a coder, and an LLM manager.
+/// </summary>
+/// <remarks>
+/// Pre-requisites:
+/// - An Azure AI Foundry project endpoint and model deployment must be configured.
+/// - Run <c>az login</c> before executing the sample.
+/// </remarks>
+public static class Program
+{
+    private const string TaskPrompt =
+        "I am preparing a report on the energy efficiency of different machine learning model architectures. " +
+        "Compare the estimated training and inference energy consumption of ResNet-50, BERT-base, and GPT-2 " +
+        "on standard datasets (e.g., ImageNet for ResNet, GLUE for BERT, WebText for GPT-2). " +
+        "Then, estimate the CO2 emissions associated with each, assuming training on an Azure Standard_NC6s_v3 " +
+        "VM for 24 hours. Provide tables for clarity, and recommend the most energy-efficient model " +
+        "per task type (image classification, text classification, and text generation).";
+
+    private static async Task Main()
+    {
+        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";
+
+        // 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.
+        AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
+
+        AIAgent researcherAgent = projectClient.AsAIAgent(
+            deploymentName,
+            name: "ResearcherAgent",
+            description: "Specialist in research and information gathering.",
+            instructions: "You are a researcher. Find relevant information without doing additional computation or quantitative analysis.");
+
+        AIAgent coderAgent = projectClient.AsAIAgent(
+            deploymentName,
+            name: "CoderAgent",
+            description: "A helpful assistant that writes and executes code to analyze data.",
+            instructions: "You solve quantitative questions by writing and running code. Show the analysis and the computation process clearly.",
+            tools: [new HostedCodeInterpreterTool()]);
+
+        AIAgent managerAgent = projectClient.AsAIAgent(
+            deploymentName,
+            name: "MagenticManager",
+            description: "Orchestrator that coordinates the research and coding workflow.",
+            instructions: "You coordinate the team to complete complex tasks efficiently.");
+
+        Workflow workflow = new MagenticWorkflowBuilder(managerAgent)
+            .AddParticipants([researcherAgent, coderAgent])
+            .WithName("Magentic Orchestration Workflow")
+            .WithDescription("Coordinates a researcher and coder to solve a complex analytical task.")
+            .RequirePlanSignoff(false)
+            .WithMaxRounds(10)
+            .WithMaxStalls(3)
+            .WithMaxResets(2)
+            .Build();
+
+        Console.WriteLine("Building Magentic workflow...");
+        Console.WriteLine();
+        Console.WriteLine($"Task: {TaskPrompt}");
+        Console.WriteLine();
+        Console.WriteLine("Starting workflow execution...");
+
+        await using StreamingRun run = await InProcessExecution.RunStreamingAsync(
+            workflow,
+            new List<ChatMessage> { new(ChatRole.User, TaskPrompt) });
+
+        await run.TrySendMessageAsync(new TurnToken(emitEvents: true));
+
+        string? lastResponseId = null;
+        WorkflowOutputEvent? finalOutput = null;
+
+        await foreach (WorkflowEvent workflowEvent in run.WatchStreamAsync())
+        {
+            switch (workflowEvent)
+            {
+                case AgentResponseUpdateEvent updateEvent:
+                    WriteStreamingUpdate(updateEvent, ref lastResponseId);
+                    break;
+
+                case MagenticPlanCreatedEvent planCreated:
+                    WriteMagenticMessage("Initial Plan", planCreated.FullTaskLedger.Text);
+                    PauseIfInteractive();
+                    break;
+
+                case MagenticReplannedEvent replanned:
+                    WriteMagenticMessage("Replanned", replanned.FullTaskLedger.Text);
+                    PauseIfInteractive();
+                    break;
+
+                case MagenticProgressLedgerUpdatedEvent progressUpdated:
+                    WriteMagenticMessage("Progress Ledger", FormatProgressLedger(progressUpdated.ProgressLedger));
+                    PauseIfInteractive();
+                    break;
+
+                case WorkflowOutputEvent outputEvent when outputEvent.Is<List<ChatMessage>>():
+                    finalOutput = outputEvent;
+                    break;
+
+                case WorkflowErrorEvent workflowError:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Error.WriteLine(workflowError.Exception?.ToString() ?? "Unknown workflow error occurred.");
+                    Console.ResetColor();
+                    break;
+
+                case ExecutorFailedEvent executorFailed:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Error.WriteLine($"Executor '{executorFailed.ExecutorId}' failed with {(executorFailed.Data is null ? "unknown error" : $"exception {executorFailed.Data}")}.");
+                    Console.ResetColor();
+                    break;
+            }
+        }
+
+        if (finalOutput?.As<List<ChatMessage>>() is { } transcript)
+        {
+            Console.WriteLine();
+            Console.WriteLine(new string('=', 80));
+            Console.WriteLine();
+            Console.WriteLine("Final Conversation Transcript:");
+            Console.WriteLine();
+
+            foreach (ChatMessage message in transcript)
+            {
+                Console.WriteLine($"{message.AuthorName ?? message.Role.ToString()}: {message.Text}");
+                Console.WriteLine();
+            }
+        }
+    }
+
+    private static void WriteStreamingUpdate(AgentResponseUpdateEvent updateEvent, ref string? lastResponseId)
+    {
+        string responseId = updateEvent.Update.ResponseId ?? updateEvent.Update.MessageId ?? updateEvent.ExecutorId;
+        if (!string.Equals(responseId, lastResponseId, StringComparison.Ordinal))
+        {
+            if (lastResponseId is not null)
+            {
+                Console.WriteLine();
+                Console.WriteLine();
+            }
+
+            Console.Write($"- {updateEvent.ExecutorId}: ");
+            lastResponseId = responseId;
+        }
+
+        if (!string.IsNullOrEmpty(updateEvent.Update.Text))
+        {
+            Console.Write(updateEvent.Update.Text);
+        }
+    }
+
+    private static void WriteMagenticMessage(string title, string? content)
+    {
+        Console.WriteLine();
+        Console.WriteLine($"[Magentic {title}]");
+        Console.WriteLine(content);
+    }
+
+    private static string FormatProgressLedger(MagenticProgressLedger ledger) =>
+        string.Join(Environment.NewLine,
+            $"Request satisfied: {ledger.IsRequestSatisfied}",
+            $"In loop: {ledger.IsInLoop}",
+            $"Making progress: {ledger.IsProgressBeingMade}",
+            $"Next speaker: {ledger.NextSpeaker}",
+            $"Instruction: {ledger.InstructionOrQuestion}");
+
+    private static void PauseIfInteractive()
+    {
+        if (Console.IsInputRedirected || Console.IsOutputRedirected)
+        {
+            return;
+        }
+
+        Console.Write("Press Enter to continue...");
+        Console.ReadLine();
+        Console.WriteLine();
+    }
+}
@@ -0,0 +1,40 @@
+# Magentic Orchestration Sample
+
+This sample showcases the Magentic Orchestration Pattern in .NET, setting up a team with three roles:
+
+- **ResearcherAgent** gathers factual background information.
+- **CoderAgent** uses `HostedCodeInterpreterTool` for quantitative analysis.
+- **MagenticManager** plans the work, tracks progress, and decides who should act next.
+
+## What This Sample Demonstrates
+
+- Building a Magentic workflow with `MagenticWorkflowBuilder`
+- Combining standard responses-based agents with a code interpreter-enabled participant
+- Streaming orchestration events such as the initial plan, replans, and progress-ledger updates
+- Printing the final multi-agent conversation transcript
+
+## Prerequisites
+
+- `AZURE_AI_PROJECT_ENDPOINT` set to your Azure AI Foundry project endpoint
+- `AZURE_AI_MODEL_DEPLOYMENT_NAME` set to your model deployment name (defaults to `gpt-5.4-mini`)
+- `az login` completed before running the sample
+
+## Running the Sample
+
+```bash
+dotnet run
+```
+
+## Expected Output
+
+The sample prints:
+
+1. The original task prompt
+2. Streamed updates from the participating agents
+3. Magentic plan and progress-ledger events as the workflow coordinates the team
+4. The final conversation transcript returned by the workflow
+
+## Related Samples
+
+- [Handoff Orchestration](../Handoff) - another multi-agent orchestration pattern in .NET workflows
+- [Python Magentic workflow sample](../../../../../python/samples/03-workflows/orchestrations/magentic.py) - the source scenario that this sample ports
@@ -62,3 +62,4 @@ Once completed, please proceed to the other samples listed below.
 | Sample | Concepts |
 |--------|----------|
 | [Handoff Orchestration](./Orchestration/Handoff) | Introduces the Handoff Orchestration pattern |
+| [Magentic Orchestration](./Orchestration/Magentic) | Coordinates multiple agents with a Magentic manager, streamed plan events, and a final transcript |
@@ -0,0 +1,14 @@
+AZURE_AI_PROJECT_ENDPOINT=<your-azure-ai-project-endpoint>
+ASPNETCORE_URLS=http://+:8088
+ASPNETCORE_ENVIRONMENT=Development
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+AGENT_NAME=hosted-agent-skills
+SKILL_NAMES=support-style,escalation-policy
+# Set to true to provision sample skills to Foundry on startup (first-run convenience).
+# In production, skills are provisioned externally — leave this unset or false.
+PROVISION_SAMPLE_SKILLS=true
+AZURE_BEARER_TOKEN=DefaultAzureCredential
+# When running outside the Foundry platform the platform-injected isolation keys are absent.
+# These two variables provide fallback values for local Docker debugging only.
+HOSTED_USER_ISOLATION_KEY=local-dev-user
+HOSTED_CHAT_ISOLATION_KEY=local-dev-chat
@@ -0,0 +1,26 @@
+# Dockerfile for end-users consuming the Agent Framework via NuGet packages.
+#
+# This Dockerfile performs a full `dotnet restore` and `dotnet publish` inside the container,
+# which only succeeds when the project references its dependencies via PackageReference (see the
+# commented-out section in HostedAgentSkills.csproj). Contributors building from the
+# agent-framework repository source must use Dockerfile.contributor instead because
+# ProjectReference dependencies live outside this folder and cannot be restored from inside
+# this build context.
+#
+# 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", "HostedAgentSkills.dll"]
@@ -0,0 +1,23 @@
+# Dockerfile for contributors building from the agent-framework repository source.
+#
+# This project uses ProjectReference to the local Microsoft.Agents.AI 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-agent-skills .
+#   docker run --rm -p 8088:8088 \
+#     -e AGENT_NAME=hosted-agent-skills \
+#     -e HOSTED_USER_ISOLATION_KEY=alice \
+#     -e HOSTED_CHAT_ISOLATION_KEY=alice-chat-1 \
+#     --env-file .env hosted-agent-skills
+#
+# 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", "HostedAgentSkills.dll"]
@@ -0,0 +1,40 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <CentralPackageTransitivePinningEnabled>false</CentralPackageTransitivePinningEnabled>
+    <RootNamespace>HostedAgentSkills</RootNamespace>
+    <AssemblyName>HostedAgentSkills</AssemblyName>
+    <NoWarn>$(NoWarn);MEAI001;OPENAI001;AAIP001</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Projects" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="DotNetEnv" />
+  </ItemGroup>
+
+  <!-- For contributors: uses ProjectReference to build against local source -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+    <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="..\Hosted_Shared_Contributor_Setup\Hosted_Shared_Contributor_Setup.csproj" />
+  </ItemGroup>
+
+  <!-- For end-users: uncomment the PackageReference below and remove the ProjectReferences above
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI" Version="1.6.1" />
+    <PackageReference Include="Microsoft.Agents.AI.Foundry" Version="1.6.1-preview.260514.1" />
+    <PackageReference Include="Microsoft.Agents.AI.Foundry.Hosting" Version="1.6.1-preview.260514.1" />
+  </ItemGroup>
+  -->
+
+  <!-- Include the skills/ directory in the publish output so the sample can provision them -->
+  <ItemGroup>
+    <None Include="skills\**\*" CopyToOutputDirectory="PreserveNewest" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,215 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// Hosted-AgentSkills
+//
+// Demonstrates how to host an agent that loads its behavioral guidelines from Foundry Skills at
+// startup. Skills are authored as SKILL.md files, uploaded to Foundry via the Skills REST API,
+// and downloaded by the agent on boot so guideline updates ship without code changes.
+//
+// The agent uses AgentSkillsProvider from the Agent Framework which implements the progressive
+// disclosure pattern from the Agent Skills specification (https://agentskills.io/):
+//   1. Advertise — skill names and descriptions are injected into the system prompt.
+//   2. Load — the model calls load_skill to retrieve the full SKILL.md body on demand.
+//
+// IMPORTANT: In production, skill provisioning (uploading SKILL.md files to Foundry) is an
+// external concern — it is NOT the hosted agent's responsibility. The provisioning helper below
+// is included for sample convenience only, so the sample is self-contained and runnable without
+// a separate setup step. A real deployment pipeline would provision skills separately (e.g., via
+// a CI/CD step, a CLI script, or a management portal).
+
+#pragma warning disable AAIP001 // ProjectAgentSkills is experimental
+
+using System.ClientModel;
+using System.IO.Compression;
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Azure.Core;
+using Azure.Identity;
+using DotNetEnv;
+using Hosted_Shared_Contributor_Setup;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry.Hosting;
+using Microsoft.Extensions.AI;
+
+// Load .env file if present (for local development)
+Env.TraversePath().Load();
+
+string endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";
+string skillNames = Environment.GetEnvironmentVariable("SKILL_NAMES")
+    ?? throw new InvalidOperationException("SKILL_NAMES is not set. Provide a comma-separated list of skill names (e.g., support-style,escalation-policy).");
+
+string[] requestedSkills = skillNames.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+if (requestedSkills.Length == 0)
+{
+    throw new InvalidOperationException("SKILL_NAMES must list at least one skill name.");
+}
+
+// Validate skill names to prevent path traversal.
+foreach (string name in requestedSkills)
+{
+    if (name.Contains('.') || name.Contains('/') || name.Contains('\\') || Path.IsPathRooted(name))
+    {
+        throw new InvalidOperationException(
+            $"Invalid skill name '{name}': skill names must not contain path separators or dots.");
+    }
+}
+
+// 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());
+
+AIProjectClient projectClient = new(new Uri(endpoint), credential);
+ProjectAgentSkills skillsClient = projectClient.AgentAdministrationClient.GetAgentSkills();
+
+// ── Provision skills (sample convenience only — NOT a production pattern) ─────
+// In production, skills are provisioned externally (e.g., via CI/CD or a management script).
+// This helper ensures the sample's SKILL.md files exist in Foundry so the sample is runnable
+// out of the box without a separate setup step. Set PROVISION_SAMPLE_SKILLS=true to enable.
+string sourceSkillsDir = Path.Combine(AppContext.BaseDirectory, "skills");
+bool provisionEnabled = string.Equals(
+    Environment.GetEnvironmentVariable("PROVISION_SAMPLE_SKILLS"), "true", StringComparison.OrdinalIgnoreCase);
+if (provisionEnabled && Directory.Exists(sourceSkillsDir))
+{
+    await EnsureSkillsProvisionedAsync(skillsClient, sourceSkillsDir, requestedSkills);
+}
+
+// ── Download skills from Foundry ─────────────────────────────────────────────
+// Pull the latest copy of each skill from Foundry into a runtime-only folder.
+// This directory is recreated on every startup so the agent always picks up
+// the latest version of each skill.
+string downloadedSkillsDir = Path.Combine(AppContext.BaseDirectory, "downloaded_skills");
+await DownloadSkillsAsync(skillsClient, requestedSkills, downloadedSkillsDir);
+
+// ── Wire skills into the agent ───────────────────────────────────────────────
+// AgentSkillsProvider implements progressive disclosure: skill names and descriptions
+// are advertised in the system prompt (~100 tokens per skill), and the full SKILL.md
+// body is loaded on demand when the model calls the load_skill tool.
+AgentSkillsProvider skillsProvider = new(downloadedSkillsDir);
+
+ChatClientAgent agent = projectClient.AsAIAgent(new ChatClientAgentOptions
+{
+    Name = Environment.GetEnvironmentVariable("AGENT_NAME") ?? "hosted-agent-skills",
+    ChatOptions = new ChatOptions
+    {
+        ModelId = deploymentName,
+        Instructions = "You are a customer-support assistant for Contoso Outdoors.",
+    },
+    AIContextProviders = [skillsProvider]
+});
+
+// Host the agent as a Foundry Hosted Agent using the Responses API.
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddFoundryResponses(agent);
+builder.Services.AddDevTemporaryLocalContributorSetup(); // Local Docker debugging only - must not be used in production.
+
+var app = builder.Build();
+app.MapFoundryResponses();
+
+// Contributor-only: in Development, also map the per-agent OpenAI route shape that live Foundry uses
+// so a local REPL client can target this server via AIProjectClient.AsAIAgent(Uri agentEndpoint).
+// Do not use this in production. Hosted Foundry agents only support the agent-endpoint path.
+app.MapDevTemporaryLocalAgentEndpoint();
+
+app.Run();
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+// Downloads each named skill from Foundry and extracts the ZIP archive into a
+// separate subdirectory under the target directory.
+static async Task DownloadSkillsAsync(ProjectAgentSkills skillsClient, string[] skillNames, string targetDir)
+{
+    if (Directory.Exists(targetDir))
+    {
+        Directory.Delete(targetDir, recursive: true);
+    }
+
+    Directory.CreateDirectory(targetDir);
+
+    foreach (string name in skillNames)
+    {
+        Console.WriteLine($"Downloading skill '{name}' from Foundry...");
+        BinaryData zipData = await skillsClient.DownloadSkillAsync(name);
+
+        string skillDir = Path.Combine(targetDir, name);
+        Directory.CreateDirectory(skillDir);
+
+        using var zipStream = zipData.ToStream();
+        using var archive = new ZipArchive(zipStream, ZipArchiveMode.Read);
+        SafeExtractZip(archive, skillDir);
+
+        if (!File.Exists(Path.Combine(skillDir, "SKILL.md")))
+        {
+            throw new InvalidOperationException(
+                $"Downloaded archive for '{name}' did not contain a SKILL.md at the root.");
+        }
+    }
+}
+
+// Extracts a ZIP archive into a destination directory, rejecting entries that would
+// escape the target path (zip-slip guard).
+static void SafeExtractZip(ZipArchive archive, string destinationDir)
+{
+    string destRoot = Path.GetFullPath(destinationDir);
+    string destRootWithSep = Path.EndsInDirectorySeparator(destRoot)
+        ? destRoot
+        : destRoot + Path.DirectorySeparatorChar;
+
+    // Use ordinal comparison on Unix (case-sensitive FS) and ordinal-ignore-case on Windows.
+    var comparison = OperatingSystem.IsWindows()
+        ? StringComparison.OrdinalIgnoreCase
+        : StringComparison.Ordinal;
+
+    foreach (ZipArchiveEntry entry in archive.Entries)
+    {
+        string entryPath = Path.GetFullPath(Path.Combine(destRoot, entry.FullName));
+        if (!entryPath.StartsWith(destRootWithSep, comparison)
+            && !string.Equals(entryPath, destRoot, comparison))
+        {
+            throw new InvalidOperationException(
+                $"Refusing to extract unsafe path '{entry.FullName}' outside of '{destRoot}'.");
+        }
+
+        if (string.IsNullOrEmpty(entry.Name))
+        {
+            // Directory entry — ensure it exists.
+            Directory.CreateDirectory(entryPath);
+        }
+        else
+        {
+            Directory.CreateDirectory(Path.GetDirectoryName(entryPath)!);
+            entry.ExtractToFile(entryPath, overwrite: true);
+        }
+    }
+}
+
+// Ensures each requested skill is provisioned in Foundry. For each skill name, checks whether
+// the skill exists and uploads it from the local source directory if it does not.
+//
+// This is a sample convenience helper — in production, skill provisioning is an external concern.
+static async Task EnsureSkillsProvisionedAsync(ProjectAgentSkills skillsClient, string sourceDir, string[] skillNames)
+{
+    foreach (string name in skillNames)
+    {
+        string skillPath = Path.Combine(sourceDir, name);
+        if (!Directory.Exists(skillPath) || !File.Exists(Path.Combine(skillPath, "SKILL.md")))
+        {
+            continue; // No local source for this skill — skip provisioning.
+        }
+
+        try
+        {
+            await skillsClient.GetSkillAsync(name);
+            Console.WriteLine($"Skill '{name}' already exists in Foundry.");
+        }
+        catch (ClientResultException ex) when (ex.Status == 404)
+        {
+            Console.WriteLine($"Provisioning skill '{name}' from {skillPath}...");
+            AgentsSkill imported = await skillsClient.CreateSkillFromPackageAsync(skillPath);
+            Console.WriteLine($"  Imported skill '{imported.Name}' (id={imported.SkillId}, has_blob={imported.HasBlob}).");
+        }
+    }
+}
@@ -0,0 +1,109 @@
+# What this sample demonstrates
+
+An [Agent Framework](https://github.com/microsoft/agent-framework) agent that loads its behavioral guidelines from [**Foundry Skills**](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/skills) at startup, hosted using the **Responses protocol**. Skills are authored once as `SKILL.md` files, uploaded to your Foundry project through the Skills REST API, and downloaded by the agent on boot so updates ship without code changes.
+
+## How It Works
+
+### Authoring skills
+
+Each skill is a Markdown file with a YAML front matter block. This sample ships two source skills under [`skills/`](skills/):
+
+| Skill | Purpose |
+|---|---|
+| [`support-style`](skills/support-style/SKILL.md) | Voice, formatting, and signature rules for Contoso Outdoors support replies. |
+| [`escalation-policy`](skills/escalation-policy/SKILL.md) | When and how to escalate a customer ticket. |
+
+Each `SKILL.md` includes a unique `*-CANARY-*` token that the model is asked to echo, so you can prove the skill was loaded from Foundry (not hallucinated) by checking the response.
+
+> The `name` and `description` values in the YAML front matter must be **unquoted** — quoting them causes the Skills REST API to return HTTP 500 on import.
+
+### Uploading skills
+
+The sample includes a convenience provisioning step that checks whether each skill exists in Foundry and uploads it if not, gated behind the `PROVISION_SAMPLE_SKILLS=true` env var. **In production, skill provisioning is an external concern** — it is NOT the hosted agent's responsibility. A real deployment pipeline would provision skills separately (e.g., via a CI/CD step, a CLI script, or a management portal).
+
+The provisioning uses `ProjectAgentSkills.CreateSkillFromPackageAsync(directoryPath)` from the `Azure.AI.Projects.Agents` SDK. The method packages the `SKILL.md` file as a ZIP and uploads it to Foundry.
+
+### Downloading skills at agent startup
+
+[`Program.cs`](Program.cs) reads the comma-separated `SKILL_NAMES` env var and for each skill name downloads the ZIP archive from Foundry via `ProjectAgentSkills.DownloadSkillAsync(name)`, then unpacks it into a **separate runtime directory** at `downloaded_skills/<name>/` (kept distinct from the static `skills/` source folder).
+
+An [`AgentSkillsProvider`](../../../../../src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs) is then built over `downloaded_skills/` and attached to the agent as a context provider. The provider follows the [Agent Skills](https://agentskills.io/) progressive-disclosure pattern:
+
+1. **Advertise** — skill names and descriptions are injected into the system prompt at session start (~100 tokens per skill).
+2. **Load** — the model calls the `load_skill` tool when it decides a skill is relevant to the user's turn, and the full `SKILL.md` body is returned.
+
+This means the model only pays the token cost for a skill's full body when it actually needs it, and updating a skill in Foundry + restarting the agent is enough to pick up the change — no code redeploy required.
+
+> **Note:** This sample supports instruction-only and resource-based skills. If your downloaded skills contain scripts, add a script runner when constructing the `AgentSkillsProvider`.
+
+### Agent Hosting
+
+The agent is hosted using the [Agent Framework](https://github.com/microsoft/agent-framework) with the Responses API hosting layer (`AddFoundryResponses` / `MapFoundryResponses`).
+
+## Prerequisites
+
+- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- 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. This single role covers both authoring skills and downloading them.
+
+## Running the Agent Host
+
+Set the required environment variables and run the sample with `dotnet run`:
+
+```bash
+export AZURE_AI_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
+export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o"
+export SKILL_NAMES="support-style,escalation-policy"
+export PROVISION_SAMPLE_SKILLS="true"   # First run only — provisions skills to Foundry
+```
+
+Or in PowerShell:
+
+```powershell
+$env:SKILL_NAMES="support-style,escalation-policy"
+$env:PROVISION_SAMPLE_SKILLS="true"     # First run only — provisions skills to Foundry
+```
+
+You can also place these in a `.env` file next to `Program.cs` — see [`.env.example`](.env.example).
+
+On startup you should see:
+
+```text
+Skill 'support-style' already exists in Foundry.
+Skill 'escalation-policy' already exists in Foundry.
+Downloading skill 'support-style' from Foundry...
+Downloading skill 'escalation-policy' from Foundry...
+```
+
+The downloaded `SKILL.md` files land under `downloaded_skills/<name>/SKILL.md` next to the published output. This directory is recreated from scratch on every run, so deleting it manually is never necessary.
+
+## Interacting with the agent
+
+> Send a POST request to the server with a JSON body containing an `"input"` field to interact with the agent. For example:
+
+```bash
+curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "Hi, I am Alex. I just want to confirm I can return my tent within 30 days."}'
+curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "I want a $750 refund on Order #A-1042 right now or I am calling my lawyer."}'
+```
+
+| Prompt mentions | Skill that should drive the response |
+|---|---|
+| Routine return / shipping / care question | Model loads `support-style` (canary `STYLE-CANARY-3318`) — no escalation. |
+| Injury, legal threat, press, or refund > $500 | Model loads `escalation-policy` (canary `ESC-CANARY-7742`) **and** `support-style`. |
+
+Because skills are loaded on demand, the canary token in a response also proves the model actually invoked `load_skill` for the matching skill (not just saw its name in the advertised list).
+
+## Deploying the Agent to Foundry
+
+When deploying to Foundry, make sure `SKILL_NAMES` is set in your `azd` environment so it gets injected into the hosted container per [`agent.manifest.yaml`](agent.manifest.yaml):
+
+```bash
+azd env set SKILL_NAMES "support-style,escalation-policy"
+```
+
+The deployed agent's Managed Identity needs **Azure AI User** on the Foundry project to download skills at startup.
+
+> The `skills/` source folder is **not** deployed to Foundry — only the downloaded skills are used at runtime. The provisioning step must have been run against the same Foundry project before the agent can download the skills.
@@ -0,0 +1,41 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/AgentManifest.yaml
+name: hosted-agent-skills
+displayName: "Hosted Agent Skills"
+
+description: >
+  An Agent Framework agent that downloads its behavioral guidelines from the Foundry
+  Skills REST API at startup, demonstrating how to decouple behavioral guidelines
+  (tone, escalation policy, etc.) from agent code using AgentSkillsProvider.
+
+metadata:
+  tags:
+    - AI Agent Hosting
+    - Azure AI AgentServer
+    - Responses Protocol
+    - Agent Framework
+    - Agent Skills
+    - Foundry Skills
+
+template:
+  name: hosted-agent-skills
+  kind: hosted
+  protocols:
+    - protocol: responses
+      version: 1.0.0
+  resources:
+    cpu: "0.25"
+    memory: 0.5Gi
+  environment_variables:
+    - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
+      value: "{{AZURE_AI_MODEL_DEPLOYMENT_NAME}}"
+    - name: SKILL_NAMES
+      value: "{{SKILL_NAMES}}"
+parameters:
+  properties:
+    - name: SKILL_NAMES
+      secret: false
+      description: Comma-separated list of Foundry skill names to download at startup (e.g., support-style,escalation-policy)
+resources:
+  - kind: model
+    id: gpt-4.1-mini
+    name: AZURE_AI_MODEL_DEPLOYMENT_NAME
@@ -0,0 +1,14 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml
+kind: hosted
+name: hosted-agent-skills
+protocols:
+  - protocol: responses
+    version: 1.0.0
+resources:
+  cpu: "0.25"
+  memory: 0.5Gi
+environment_variables:
+  - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
+    value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
+  - name: SKILL_NAMES
+    value: ${SKILL_NAMES}
@@ -0,0 +1,100 @@
+#requires -Version 7
+<#
+.SYNOPSIS
+  Local smoke test for the Hosted-AgentSkills sample.
+.DESCRIPTION
+  Publishes the sample, builds the contributor Docker image, runs the container, drives
+  two conversations via curl invocations, and asserts that the agent loaded the correct
+  Foundry Skill for each prompt (verified via canary tokens in the response).
+  Exits non-zero on failure.
+
+  Prerequisites:
+    - Docker
+    - az login (token is fetched from the host)
+    - .env populated with AZURE_AI_PROJECT_ENDPOINT and model deployment
+    - Skills provisioned to Foundry (set PROVISION_SAMPLE_SKILLS=true on first run)
+.NOTES
+  This script is for local Docker debugging only. The Foundry platform supplies the
+  isolation keys for every inbound request in production and the dev fallback used here
+  must not be enabled in production deployments.
+#>
+
+[CmdletBinding()]
+param(
+    [int]$Port = 8088,
+    [string]$ImageName = 'hosted-agent-skills-smoke',
+    [string]$ContainerName = 'hosted-agent-skills-smoke'
+)
+
+$ErrorActionPreference = 'Stop'
+Set-Location -Path $PSScriptRoot/..
+
+if (-not (Test-Path .env)) {
+    throw '.env not found. Copy .env.example to .env and fill in AZURE_AI_PROJECT_ENDPOINT.'
+}
+
+Write-Host '==> Publishing sample for linux-musl-x64 ...'
+dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out --tl:off | Out-Host
+if ($LASTEXITCODE -ne 0) { throw 'dotnet publish failed.' }
+
+Write-Host '==> Building docker image ...'
+docker build -f Dockerfile.contributor -t $ImageName . | Out-Host
+if ($LASTEXITCODE -ne 0) { throw 'docker build failed.' }
+
+Write-Host '==> Fetching bearer token ...'
+$bearer = az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv
+if (-not $bearer) { throw 'Failed to obtain bearer token. Run az login.' }
+
+function Start-Container {
+    docker rm -f $ContainerName 2>$null | Out-Null
+    docker run -d --name $ContainerName -p ${Port}:8088 `
+        -e AGENT_NAME=hosted-agent-skills `
+        -e AZURE_BEARER_TOKEN=$bearer `
+        -e HOSTED_USER_ISOLATION_KEY=smoke-user `
+        -e HOSTED_CHAT_ISOLATION_KEY=smoke-chat-1 `
+        --env-file .env `
+        $ImageName | Out-Host
+    if ($LASTEXITCODE -ne 0) { throw "docker run failed." }
+    # Wait for the server to start and download skills from Foundry.
+    Write-Host '  Waiting for startup (skill download + server ready) ...'
+    Start-Sleep -Seconds 15
+}
+
+function Invoke-Agent([string]$Prompt, [string]$PreviousResponseId = $null) {
+    $body = @{ input = $Prompt; model = 'hosted-agent-skills' }
+    if ($PreviousResponseId) { $body['previous_response_id'] = $PreviousResponseId }
+    $json = $body | ConvertTo-Json -Compress
+    $resp = Invoke-RestMethod -Method Post -Uri "http://localhost:$Port/responses" -ContentType 'application/json' -Body $json
+    return $resp
+}
+
+function Get-ResponseText($response) {
+    return ($response.output | ForEach-Object { $_.content | ForEach-Object { $_.text } }) -join ' '
+}
+
+function Assert-Contains([string]$Haystack, [string]$Needle, [string]$Label) {
+    if ($Haystack -notmatch [regex]::Escape($Needle)) {
+        throw "FAILED [$Label]: expected response to contain '$Needle' but got: $Haystack"
+    }
+    Write-Host "PASS  [$Label]: response contains '$Needle'."
+}
+
+try {
+    Start-Container
+
+    Write-Host '==> Test 1: Routine support question -> support-style skill ...'
+    $r1 = Invoke-Agent -Prompt 'Hi, I am Alex. I just want to confirm I can return my tent within 30 days.'
+    $text1 = Get-ResponseText $r1
+    Assert-Contains $text1 'STYLE-CANARY-3318' 'routine question: support-style canary'
+
+    Write-Host '==> Test 2: Escalation trigger -> escalation-policy skill ...'
+    $r2 = Invoke-Agent -Prompt 'I want a $750 refund on Order #A-1042 right now or I am calling my lawyer.'
+    $text2 = Get-ResponseText $r2
+    Assert-Contains $text2 'ESC-CANARY-7742' 'escalation trigger: escalation-policy canary'
+
+    Write-Host ''
+    Write-Host '==> All smoke assertions passed.'
+}
+finally {
+    docker rm -f $ContainerName 2>$null | Out-Null
+}
--- a/Show More
+++ b/Show More