Fix Foreach body exit wiring in declarative workflows

.NET: Add MCP long-running task support for MCP client tools (#5994 )
* Add MCP long-running task support for MCP client tools * Fixed project file formatting issue. * Removed experimentation tag from MCP alpha project. * Addressed PR comments
2026-06-16 21:04:09 +08:00 · 2026-05-22 15:19:36 -07:00 · 2026-05-22 19:09:54 +00:00 · 2026-05-22 19:09:18 +00:00 · 2026-05-22 18:15:06 +00:00 · 2026-05-22 15:31:18 +00:00
244 changed files with 18312 additions and 1832 deletions
@@ -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
@@ -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 }}
@@ -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'

@@ -121,6 +121,7 @@
  <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_WithBackgroundAgents/Harness_Step02_Research_WithBackgroundAgents.csproj" />
    <Project Path="samples/02-agents/Harness/Harness_Step03_DataProcessing/Harness_Step03_DataProcessing.csproj" />
@@ -211,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" />
@@ -280,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" />
@@ -600,6 +603,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" />
@@ -653,6 +657,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" />
@@ -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.6.2</VersionPrefix>
    <RCNumber>1</RCNumber>
-    <DateSuffix>260514</DateSuffix>
+    <DateSuffix>260521</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.6.2</GitTag>

    <Configurations>Debug;Release;Publish</Configurations>
    <IsPackable>true</IsPackable>
@@ -192,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)
@@ -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>
@@ -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;
+        }
+    }
+}
@@ -3,19 +3,18 @@
 #pragma warning disable OPENAI001 // Suppress experimental API warnings for Responses API usage.

 using System.Text;
-using Harness.Shared.Console;
 using Harness.Shared.Console.Observers;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 using OpenAI.Responses;

-namespace SampleApp;
+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>
-internal sealed class OpenAIResponsesWebSearchDisplayObserver : ConsoleObserver
+public sealed class OpenAIResponsesWebSearchDisplayObserver : ConsoleObserver
 {
    private const int MaxQueryDisplayLength = 120;

@@ -16,6 +16,7 @@
    <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="..\Harness_Shared_Console\Harness_Shared_Console.csproj" />
+    <ProjectReference Include="..\Harness_Shared_Console_OpenAI\Harness_Shared_Console_OpenAI.csproj" />
  </ItemGroup>

 </Project>
@@ -19,6 +19,7 @@ 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;
@@ -107,6 +108,7 @@ await HarnessConsole.RunAgentAsync(
    {
        Observers = [
            new OpenAIResponsesWebSearchDisplayObserver(),
+            new OpenAIResponsesErrorObserver(),
            .. HarnessConsoleOptions.BuildObserversWithPlanning(
                agent,
                planModeName: "plan",
@@ -16,6 +16,7 @@
    <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="..\Harness_Shared_Console\Harness_Shared_Console.csproj" />
+    <ProjectReference Include="..\Harness_Shared_Console_OpenAI\Harness_Shared_Console_OpenAI.csproj" />
  </ItemGroup>

 </Project>
@@ -16,6 +16,7 @@ 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;

@@ -102,10 +103,7 @@ AIAgent parentAgent =
        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,
-        AIContextProviders =
-        [
-            new BackgroundAgentsProvider([webSearchAgent]),
-        ],
+        BackgroundAgents = [webSearchAgent],
        ChatOptions = new ChatOptions
        {
            Instructions = parentInstructions,
@@ -116,4 +114,8 @@ AIAgent parentAgent =
 // Run the interactive console session.
 await HarnessConsole.RunAgentAsync(
    parentAgent,
-    userPrompt: "Enter a list of stock tickers (e.g., BAC, MSFT, BA):");
+    userPrompt: "Enter a list of stock tickers (e.g., BAC, MSFT, BA):",
+    options: new HarnessConsoleOptions
+    {
+        Observers = [new OpenAIResponsesErrorObserver(), .. HarnessConsoleOptions.BuildDefaultObservers()],
+    });
@@ -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 |
@@ -28,9 +28,7 @@ public sealed class A2AAgent : AIAgent
    private static readonly AIAgentMetadata s_agentMetadata = new("a2a");

    private readonly IA2AClient _a2aClient;
-    private readonly string? _id;
-    private readonly string? _name;
-    private readonly string? _description;
+    private readonly A2AAgentOptions _agentOptions;
    private readonly ILogger _logger;

    /// <summary>
@@ -38,17 +36,37 @@ public sealed class A2AAgent : AIAgent
    /// </summary>
    /// <param name="a2aClient">The A2A client to use for interacting with A2A agents.</param>
    /// <param name="id">The unique identifier for the agent.</param>
-    /// <param name="name">The the name of the agent.</param>
+    /// <param name="name">The name of the agent.</param>
    /// <param name="description">The description of the agent.</param>
    /// <param name="loggerFactory">Optional logger factory to use for logging.</param>
    public A2AAgent(IA2AClient a2aClient, string? id = null, string? name = null, string? description = null, ILoggerFactory? loggerFactory = null)
+        : this(
+              a2aClient,
+              new A2AAgentOptions
+              {
+                  Id = id,
+                  Name = name,
+                  Description = description
+              },
+              loggerFactory)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="A2AAgent"/> class.
+    /// </summary>
+    /// <param name="a2aClient">The A2A client to use for interacting with A2A agents.</param>
+    /// <param name="options">
+    /// Configuration options that control the agent's identity, including its identifier, name, and description.
+    /// </param>
+    /// <param name="loggerFactory">Optional logger factory to use for logging.</param>
+    public A2AAgent(IA2AClient a2aClient, A2AAgentOptions options, ILoggerFactory? loggerFactory = null)
    {
        _ = Throw.IfNull(a2aClient);
+        _ = Throw.IfNull(options);

        this._a2aClient = a2aClient;
-        this._id = id;
-        this._name = name;
-        this._description = description;
+        this._agentOptions = options.Clone();
        this._logger = (loggerFactory ?? NullLoggerFactory.Instance).CreateLogger<A2AAgent>();
    }

@@ -216,13 +234,13 @@ public sealed class A2AAgent : AIAgent
    }

    /// <inheritdoc/>
-    protected override string? IdCore => this._id;
+    protected override string? IdCore => this._agentOptions.Id;

    /// <inheritdoc/>
-    public override string? Name => this._name;
+    public override string? Name => this._agentOptions.Name;

    /// <inheritdoc/>
-    public override string? Description => this._description;
+    public override string? Description => this._agentOptions.Description;

    /// <inheritdoc/>
    public override object? GetService(Type serviceType, object? serviceKey = null)
@@ -456,6 +474,7 @@ public sealed class A2AAgent : AIAgent
            ResponseId = statusUpdateEvent.TaskId,
            RawRepresentation = statusUpdateEvent,
            Role = ChatRole.Assistant,
+            MessageId = statusUpdateEvent.Status.Message?.MessageId,
            FinishReason = MapTaskStateToFinishReason(statusUpdateEvent.Status.State),
            AdditionalProperties = statusUpdateEvent.Metadata?.ToAdditionalProperties() ?? [],
            Contents = statusUpdateEvent.Status.GetUserInputRequests(),
@@ -0,0 +1,40 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI.A2A;
+
+/// <summary>
+/// Represents configuration options for an <see cref="A2AAgent"/>, including its identifier, name, and description.
+/// </summary>
+/// <remarks>
+/// This class is used to encapsulate information about an A2A agent, such as its unique
+/// identifier, display name, and a descriptive summary. It provides an alternative to passing
+/// these values as individual constructor parameters.
+/// </remarks>
+public sealed class A2AAgentOptions
+{
+    /// <summary>
+    /// Gets or sets the agent id.
+    /// </summary>
+    public string? Id { get; set; }
+
+    /// <summary>
+    /// Gets or sets the agent name.
+    /// </summary>
+    public string? Name { get; set; }
+
+    /// <summary>
+    /// Gets or sets the agent description.
+    /// </summary>
+    public string? Description { get; set; }
+
+    /// <summary>
+    /// Creates a new instance of <see cref="A2AAgentOptions"/> with the same values as this instance.
+    /// </summary>
+    public A2AAgentOptions Clone()
+        => new()
+        {
+            Id = this.Id,
+            Name = this.Name,
+            Description = this.Description
+        };
+}
@@ -2,7 +2,9 @@

 using System.Net.Http;
 using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.A2A;
 using Microsoft.Extensions.Logging;
+using Microsoft.Shared.Diagnostics;

 namespace A2A;

@@ -36,4 +38,39 @@ public static class A2AAgentCardExtensions

        return a2aClient.AsAIAgent(name: card.Name, description: card.Description, loggerFactory: loggerFactory);
    }
+
+    /// <summary>
+    /// Retrieves an instance of <see cref="AIAgent"/> for an existing A2A agent.
+    /// </summary>
+    /// <remarks>
+    /// This method can be used to access A2A agents that support the
+    /// <see href="https://github.com/a2aproject/A2A/blob/main/docs/topics/agent-discovery.md#2-curated-registries-catalog-based-discovery">Curated Registries (Catalog-Based Discovery)</see>
+    /// discovery mechanism. When <paramref name="agentOptions"/> is provided, any non-null values override
+    /// the corresponding values from the <see cref="AgentCard"/>.
+    /// </remarks>
+    /// <param name="card">The <see cref="AgentCard" /> to use for the agent creation.</param>
+    /// <param name="agentOptions">
+    /// Configuration options that control the agent's identity. When provided, non-null values override the
+    /// corresponding values from the agent card.
+    /// </param>
+    /// <param name="httpClient">The <see cref="HttpClient"/> to use for HTTP requests.</param>
+    /// <param name="clientOptions">
+    /// Optional <see cref="A2AClientOptions"/> controlling protocol binding preference.
+    /// When not provided, defaults to preferring HTTP+JSON first, with JSON-RPC as fallback.
+    /// </param>
+    /// <param name="loggerFactory">The logger factory for enabling logging within the agent.</param>
+    /// <returns>An <see cref="AIAgent"/> instance backed by the A2A agent.</returns>
+    public static AIAgent AsAIAgent(this AgentCard card, A2AAgentOptions agentOptions, HttpClient? httpClient = null, A2AClientOptions? clientOptions = null, ILoggerFactory? loggerFactory = null)
+    {
+        _ = Throw.IfNull(card);
+        _ = Throw.IfNull(agentOptions);
+
+        var a2aClient = A2AClientFactory.Create(card, httpClient, clientOptions);
+
+        var mergedOptions = agentOptions.Clone();
+        mergedOptions.Name ??= card.Name;
+        mergedOptions.Description ??= card.Description;
+
+        return a2aClient.AsAIAgent(mergedOptions, loggerFactory);
+    }
 }
@@ -6,6 +6,7 @@ using System.Threading.Tasks;
 using Microsoft.Agents.AI;
 using Microsoft.Agents.AI.A2A;
 using Microsoft.Extensions.Logging;
+using Microsoft.Shared.Diagnostics;

 namespace A2A;

@@ -48,4 +49,39 @@ public static class A2ACardResolverExtensions

        return agentCard.AsAIAgent(httpClient, options, loggerFactory);
    }
+
+    /// <summary>
+    /// Retrieves an instance of <see cref="AIAgent"/> for an existing A2A agent.
+    /// </summary>
+    /// <remarks>
+    /// This method can be used to access A2A agents that support the
+    /// <see href="https://github.com/a2aproject/A2A/blob/main/docs/topics/agent-discovery.md#1-well-known-uri">Well-Known URI</see>
+    /// discovery mechanism. When <paramref name="agentOptions"/> is provided, any non-null values override
+    /// the corresponding values from the resolved <see cref="AgentCard"/>.
+    /// </remarks>
+    /// <param name="resolver">The <see cref="A2ACardResolver" /> to use for the agent creation.</param>
+    /// <param name="agentOptions">
+    /// Configuration options that control the agent's identity. When provided, non-null values override the
+    /// corresponding values from the resolved agent card.
+    /// </param>
+    /// <param name="httpClient">
+    /// The <see cref="HttpClient"/> to use for HTTP requests made by the created A2A client.
+    /// This is not used for fetching the agent card; the resolver uses its own configured client for that.
+    /// </param>
+    /// <param name="clientOptions">
+    /// Optional <see cref="A2AClientOptions"/> controlling protocol binding preference.
+    /// When not provided, defaults to preferring HTTP+JSON first, with JSON-RPC as fallback.
+    /// </param>
+    /// <param name="loggerFactory">The logger factory for enabling logging within the agent.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>An <see cref="AIAgent"/> instance backed by the A2A agent.</returns>
+    public static async Task<AIAgent> GetAIAgentAsync(this A2ACardResolver resolver, A2AAgentOptions agentOptions, HttpClient? httpClient = null, A2AClientOptions? clientOptions = null, ILoggerFactory? loggerFactory = null, CancellationToken cancellationToken = default)
+    {
+        _ = Throw.IfNull(agentOptions);
+
+        // Obtain the agent card from the resolver.
+        var agentCard = await resolver.GetAgentCardAsync(cancellationToken).ConfigureAwait(false);
+
+        return agentCard.AsAIAgent(agentOptions, httpClient, clientOptions, loggerFactory);
+    }
 }
@@ -3,6 +3,7 @@
 using Microsoft.Agents.AI;
 using Microsoft.Agents.AI.A2A;
 using Microsoft.Extensions.Logging;
+using Microsoft.Shared.Diagnostics;

 namespace A2A;

@@ -31,10 +32,32 @@ public static class A2AClientExtensions
    /// </remarks>
    /// <param name="client">The <see cref="IA2AClient" /> to use for the agent.</param>
    /// <param name="id">The unique identifier for the agent.</param>
-    /// <param name="name">The the name of the agent.</param>
+    /// <param name="name">The name of the agent.</param>
    /// <param name="description">The description of the agent.</param>
    /// <param name="loggerFactory">Optional logger factory for enabling logging within the agent.</param>
    /// <returns>An <see cref="AIAgent"/> instance backed by the A2A agent.</returns>
    public static AIAgent AsAIAgent(this IA2AClient client, string? id = null, string? name = null, string? description = null, ILoggerFactory? loggerFactory = null) =>
        new A2AAgent(client, id, name, description, loggerFactory);
+
+    /// <summary>
+    /// Retrieves an instance of <see cref="AIAgent"/> for an existing A2A agent.
+    /// </summary>
+    /// <remarks>
+    /// This method can be used to access A2A agents that support the
+    /// <see href="https://github.com/a2aproject/A2A/blob/main/docs/topics/agent-discovery.md#3-direct-configuration--private-discovery">Direct Configuration / Private Discovery</see>
+    /// discovery mechanism.
+    /// </remarks>
+    /// <param name="client">The <see cref="IA2AClient" /> to use for the agent.</param>
+    /// <param name="options">
+    /// Configuration options that control the agent's identity, including its identifier, name, and description.
+    /// </param>
+    /// <param name="loggerFactory">Optional logger factory for enabling logging within the agent.</param>
+    /// <returns>An <see cref="AIAgent"/> instance backed by the A2A agent.</returns>
+    public static AIAgent AsAIAgent(this IA2AClient client, A2AAgentOptions options, ILoggerFactory? loggerFactory = null)
+    {
+        _ = Throw.IfNull(client);
+        _ = Throw.IfNull(options);
+
+        return new A2AAgent(client, options, loggerFactory);
+    }
 }
@@ -1,5 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.

+using System;
 using System.ClientModel.Primitives;
 using System.Collections.Generic;
 using System.Reflection;
@@ -9,8 +10,11 @@ using Microsoft.Extensions.AI;
 namespace Microsoft.Agents.AI.Foundry.Hosting;

 /// <summary>
-/// Pipeline policy that appends the hosted-agent <c>User-Agent</c> segment
-/// (e.g. <c>"foundry-hosting/agent-framework-dotnet/{version}"</c>) to outgoing requests.
+/// Pipeline policy that emits the hosted-agent <c>User-Agent</c> segment
+/// (<c>"foundry-hosting/agent-framework-dotnet/{version}"</c>), matching Python's hosted
+/// contract (<c>foundry-hosting/agent-framework-python/{version}</c>, see
+/// <c>python/packages/core/agent_framework/_telemetry.py</c>: the hosted prefix is joined
+/// with the base agent-framework segment into a single combined User-Agent value).
 /// </summary>
 /// <remarks>
 /// <para>
@@ -19,6 +23,12 @@ namespace Microsoft.Agents.AI.Foundry.Hosting;
 /// is already present in the <c>User-Agent</c> header, the policy does not append it again.
 /// </para>
 /// <para>
+/// When a bare <c>agent-framework-dotnet/{version}</c> segment is already present (stamped by
+/// the framework-wide <c>AgentFrameworkUserAgentPolicy</c> registered by
+/// <c>FoundryChatClient</c>), this policy <em>replaces</em> that segment with the combined
+/// hosted form so the wire never carries both forms simultaneously, preserving Python parity.
+/// </para>
+/// <para>
 /// This policy is added at hosted-agent resolution time via the MEAI 10.5.1
 /// <see cref="OpenAIRequestPolicies"/> hook on the agent's underlying chat client. It is only
 /// registered when an agent is resolved by the Foundry hosting layer.
@@ -30,6 +40,12 @@ internal sealed class HostedAgentUserAgentPolicy : PipelinePolicy

    private static readonly string s_supplementValue = CreateSupplementValue();

+    /// <summary>Bare segment stamped by <c>AgentFrameworkUserAgentPolicy</c> in the non-hosted scenario; this policy upgrades it in-place when both run.</summary>
+    private const string BareAgentFrameworkPrefix = "agent-framework-dotnet/";
+
+    /// <summary>Combined hosted segment that this policy emits. Recognized in-place so callers whose pipelines already carry a (possibly different-version) combined segment get it replaced rather than double-prefixed (Q-D fix).</summary>
+    private const string CombinedHostedPrefix = "foundry-hosting/agent-framework-dotnet/";
+
    public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
    {
        AppendHeader(message);
@@ -46,13 +62,52 @@ internal sealed class HostedAgentUserAgentPolicy : PipelinePolicy
    {
        if (message.Request.Headers.TryGetValue("User-Agent", out var existing) && !string.IsNullOrEmpty(existing))
        {
-            // Guard against double-append on retries or when the policy
-            // is registered on multiple pipeline positions.
-            if (existing.Contains(s_supplementValue))
+            // Guard against double-append on retries or when the policy is registered on
+            // multiple pipeline positions.
+            if (existing!.Contains(s_supplementValue))
            {
                return;
            }

+            // Combined-form check first: if the caller's pipeline already has
+            // `foundry-hosting/agent-framework-dotnet/{version}` (with a version that differs
+            // from ours — otherwise the .Contains above would have returned early), replace the
+            // entire combined span in place. Without this, the bare-prefix search below would
+            // match `agent-framework-dotnet/` *inside* the combined segment and produce a
+            // malformed `foundry-hosting/foundry-hosting/agent-framework-dotnet/...` value.
+            var combinedIdx = existing.IndexOf(CombinedHostedPrefix, StringComparison.Ordinal);
+            if (combinedIdx >= 0)
+            {
+                var combinedEnd = existing.IndexOf(' ', combinedIdx);
+                if (combinedEnd < 0)
+                {
+                    combinedEnd = existing.Length;
+                }
+
+                var replacedCombined = string.Concat(existing.AsSpan(0, combinedIdx), s_supplementValue.AsSpan(), existing.AsSpan(combinedEnd));
+                message.Request.Headers.Set("User-Agent", replacedCombined);
+                return;
+            }
+
+            // If the bare agent-framework segment is present (stamped by
+            // AgentFrameworkUserAgentPolicy when not hosted), upgrade it in place to the
+            // combined hosted form so the wire never carries both segments simultaneously.
+            // Mirrors Python where get_user_agent() returns a single combined string when the
+            // hosted prefix is registered.
+            var idx = existing.IndexOf(BareAgentFrameworkPrefix, StringComparison.Ordinal);
+            if (idx >= 0)
+            {
+                var end = existing.IndexOf(' ', idx);
+                if (end < 0)
+                {
+                    end = existing.Length;
+                }
+
+                var replaced = string.Concat(existing.AsSpan(0, idx), s_supplementValue.AsSpan(), existing.AsSpan(end));
+                message.Request.Headers.Set("User-Agent", replaced);
+                return;
+            }
+
            message.Request.Headers.Set("User-Agent", $"{existing} {s_supplementValue}");
        }
        else
@@ -23,7 +23,7 @@ namespace Azure.AI.Projects;
 /// Provides extension methods for <see cref="AIProjectClient"/>.
 /// </summary>
 [Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
-public static partial class AzureAIProjectChatClientExtensions
+public static partial class AIProjectClientExtensions
 {
    /// <summary>
    /// Uses an existing server side agent, wrapped as a <see cref="ChatClientAgent"/> using the provided <see cref="AIProjectClient"/> and <see cref="AgentReference"/>.
@@ -63,7 +63,7 @@ public static partial class AzureAIProjectChatClientExtensions
            clientFactory,
            services);

-        return new FoundryAgent(aiProjectClient, innerAgent);
+        return new FoundryAgent(innerAgent);
    }

    /// <summary>
@@ -132,7 +132,7 @@ public static partial class AzureAIProjectChatClientExtensions
            !allowDeclarativeMode,
            services);

-        return new FoundryAgent(aiProjectClient, innerAgent);
+        return new FoundryAgent(innerAgent);
    }

    /// <summary>
@@ -165,7 +165,7 @@ public static partial class AzureAIProjectChatClientExtensions
            !allowDeclarativeMode,
            services);

-        return new FoundryAgent(aiProjectClient, innerAgent);
+        return new FoundryAgent(innerAgent);
    }

    /// <summary>
@@ -246,7 +246,7 @@ public static partial class AzureAIProjectChatClientExtensions
        Func<IChatClient, IChatClient>? clientFactory,
        IServiceProvider? services)
    {
-        IChatClient chatClient = new AzureAIProjectChatClient(aiProjectClient, agentVersion, agentOptions.ChatOptions);
+        IChatClient chatClient = new FoundryChatClient(aiProjectClient, agentVersion, agentOptions.ChatOptions);

        if (clientFactory is not null)
        {
@@ -268,10 +268,7 @@ public static partial class AzureAIProjectChatClientExtensions
        Throw.IfNull(agentOptions.ChatOptions);
        Throw.IfNullOrWhitespace(agentOptions.ChatOptions.ModelId);

-        IChatClient chatClient = aiProjectClient
-            .GetProjectOpenAIClient()
-            .GetResponsesClient()
-            .AsIChatClient(agentOptions.ChatOptions.ModelId);
+        IChatClient chatClient = new FoundryChatClient(aiProjectClient, agentOptions.ChatOptions.ModelId);

        if (clientFactory is not null)
        {
@@ -298,7 +295,7 @@ public static partial class AzureAIProjectChatClientExtensions
        Func<IChatClient, IChatClient>? clientFactory,
        IServiceProvider? services)
    {
-        IChatClient chatClient = new AzureAIProjectChatClient(aiProjectClient, agentRecord, agentOptions.ChatOptions);
+        IChatClient chatClient = new FoundryChatClient(aiProjectClient, agentRecord, agentOptions.ChatOptions);

        if (clientFactory is not null)
        {
@@ -316,7 +313,7 @@ public static partial class AzureAIProjectChatClientExtensions
        Func<IChatClient, IChatClient>? clientFactory,
        IServiceProvider? services)
    {
-        IChatClient chatClient = new AzureAIProjectChatClient(aiProjectClient, agentReference, defaultModelId: null, agentOptions.ChatOptions);
+        IChatClient chatClient = new FoundryChatClient(aiProjectClient, agentReference, defaultModelId: null, agentOptions.ChatOptions);

        if (clientFactory is not null)
        {
@@ -0,0 +1,88 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ClientModel.Primitives;
+using System.Collections.Generic;
+using System.Reflection;
+using System.Threading.Tasks;
+
+namespace Microsoft.Agents.AI.Foundry;
+
+/// <summary>
+/// Framework-wide pipeline policy that appends the <c>agent-framework-dotnet/{version}</c>
+/// segment to outgoing <c>User-Agent</c> headers, mirroring the
+/// <c>agent-framework-python/{version}</c> contract used by every Python provider package.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The segment value is computed once from the <c>Microsoft.Agents.AI.Foundry</c> assembly's
+/// <see cref="AssemblyInformationalVersionAttribute"/>. The policy is idempotent on retries: if
+/// the segment is already present in the <c>User-Agent</c> header, the policy does not append
+/// it again.
+/// </para>
+/// <para>
+/// The policy is registered by <c>FoundryChatClient</c> on the underlying chat client's
+/// <c>OpenAIRequestPolicies</c> hook so every outbound Foundry call carries the segment. The
+/// policy is currently colocated with the Foundry package; it is expected to migrate to a
+/// framework-wide location (such as <c>Microsoft.Agents.AI</c>) once another provider package
+/// adopts the same User-Agent contract.
+/// </para>
+/// </remarks>
+internal sealed class AgentFrameworkUserAgentPolicy : PipelinePolicy
+{
+    /// <summary>Gets the singleton policy instance.</summary>
+    public static AgentFrameworkUserAgentPolicy Instance { get; } = new AgentFrameworkUserAgentPolicy();
+
+    private static readonly string s_segmentValue = CreateSegmentValue();
+
+    public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+    {
+        AppendHeader(message);
+        ProcessNext(message, pipeline, currentIndex);
+    }
+
+    public override async ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+    {
+        AppendHeader(message);
+        await ProcessNextAsync(message, pipeline, currentIndex).ConfigureAwait(false);
+    }
+
+    private static void AppendHeader(PipelineMessage message)
+    {
+        if (message.Request.Headers.TryGetValue("User-Agent", out var existing) && !string.IsNullOrEmpty(existing))
+        {
+            // Guard against double-append on retries or when the policy
+            // is registered on multiple pipeline positions.
+            if (existing!.Contains(s_segmentValue))
+            {
+                return;
+            }
+
+            message.Request.Headers.Set("User-Agent", $"{existing} {s_segmentValue}");
+        }
+        else
+        {
+            message.Request.Headers.Set("User-Agent", s_segmentValue);
+        }
+    }
+
+    private static string CreateSegmentValue()
+    {
+        const string Name = "agent-framework-dotnet";
+
+        if (typeof(AgentFrameworkUserAgentPolicy).Assembly.GetCustomAttribute<AssemblyInformationalVersionAttribute>()?.InformationalVersion is string version)
+        {
+            int pos = version.IndexOf('+');
+            if (pos >= 0)
+            {
+                version = version.Substring(0, pos);
+            }
+
+            if (version.Length > 0)
+            {
+                return $"{Name}/{version}";
+            }
+        }
+
+        return Name;
+    }
+}
@@ -1,165 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using System;
-using System.Collections.Generic;
-using System.Diagnostics.CodeAnalysis;
-using System.Runtime.CompilerServices;
-using System.Threading;
-using System.Threading.Tasks;
-using Azure.AI.Extensions.OpenAI;
-using Azure.AI.Projects;
-using Azure.AI.Projects.Agents;
-using Microsoft.Extensions.AI;
-using Microsoft.Shared.DiagnosticIds;
-using Microsoft.Shared.Diagnostics;
-using OpenAI.Responses;
-
-namespace Microsoft.Agents.AI.Foundry;
-
-/// <summary>
-/// Provides a chat client implementation that integrates with Azure AI Agents, enabling chat interactions using
-/// Azure-specific agent capabilities.
-/// </summary>
-[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
-internal sealed class AzureAIProjectChatClient : DelegatingChatClient
-{
-    private readonly ChatClientMetadata? _metadata;
-    private readonly AIProjectClient _agentClient;
-    private readonly ProjectsAgentVersion? _agentVersion;
-    private readonly ProjectsAgentRecord? _agentRecord;
-    private readonly ChatOptions? _chatOptions;
-    private readonly AgentReference _agentReference;
-
-    /// <summary>
-    /// Initializes a new instance of the <see cref="AzureAIProjectChatClient"/> class.
-    /// </summary>
-    /// <param name="aiProjectClient">An instance of <see cref="AIProjectClient"/> to interact with Azure AI Agents services.</param>
-    /// <param name="agentReference">An instance of <see cref="AgentReference"/> representing the specific agent to use.</param>
-    /// <param name="defaultModelId">The default model to use for the agent, if applicable.</param>
-    /// <param name="chatOptions">An instance of <see cref="ChatOptions"/> representing the options on how the agent was predefined.</param>
-    /// <remarks>
-    /// The <see cref="IChatClient"/> provided should be decorated with a <see cref="AzureAIProjectChatClient"/> for proper functionality.
-    /// </remarks>
-    internal AzureAIProjectChatClient(AIProjectClient aiProjectClient, AgentReference agentReference, string? defaultModelId, ChatOptions? chatOptions)
-        : base(Throw.IfNull(aiProjectClient)
-            .GetProjectOpenAIClient()
-            .GetProjectResponsesClientForAgent(agentReference)
-            .AsIChatClient())
-    {
-        this._agentClient = aiProjectClient;
-        this._agentReference = Throw.IfNull(agentReference);
-        this._metadata = new ChatClientMetadata("microsoft.foundry", defaultModelId: defaultModelId);
-        this._chatOptions = chatOptions;
-    }
-
-    /// <summary>
-    /// Initializes a new instance of the <see cref="AzureAIProjectChatClient"/> class.
-    /// </summary>
-    /// <param name="aiProjectClient">An instance of <see cref="AIProjectClient"/> to interact with Azure AI Agents services.</param>
-    /// <param name="agentRecord">An instance of <see cref="ProjectsAgentRecord"/> representing the specific agent to use.</param>
-    /// <param name="chatOptions">An instance of <see cref="ChatOptions"/> representing the options on how the agent was predefined.</param>
-    /// <remarks>
-    /// The <see cref="IChatClient"/> provided should be decorated with a <see cref="AzureAIProjectChatClient"/> for proper functionality.
-    /// </remarks>
-    internal AzureAIProjectChatClient(AIProjectClient aiProjectClient, ProjectsAgentRecord agentRecord, ChatOptions? chatOptions)
-        : this(aiProjectClient, Throw.IfNull(agentRecord).GetLatestVersion(), chatOptions)
-    {
-        this._agentRecord = agentRecord;
-    }
-
-    internal AzureAIProjectChatClient(AIProjectClient aiProjectClient, ProjectsAgentVersion agentVersion, ChatOptions? chatOptions)
-        : this(
-              aiProjectClient,
-              CreateAgentReference(Throw.IfNull(agentVersion)),
-              (agentVersion.Definition as DeclarativeAgentDefinition)?.Model,
-              chatOptions)
-    {
-        this._agentVersion = agentVersion;
-    }
-
-    /// <summary>
-    /// Creates an <see cref="AgentReference"/> from an <see cref="ProjectsAgentVersion"/>.
-    /// Uses the agent version's version if available, otherwise defaults to "latest".
-    /// </summary>
-    /// <param name="agentVersion">The agent version to create a reference from.</param>
-    /// <returns>An <see cref="AgentReference"/> for the specified agent version.</returns>
-    private static AgentReference CreateAgentReference(ProjectsAgentVersion agentVersion)
-    {
-        // If the version is null, empty, or whitespace, use "latest" as the default.
-        // This handles cases where hosted agents (like MCP agents) may not have a version assigned.
-        var version = string.IsNullOrWhiteSpace(agentVersion.Version) ? "latest" : agentVersion.Version;
-        return new AgentReference(agentVersion.Name, version);
-    }
-
-    /// <inheritdoc/>
-    public override object? GetService(Type serviceType, object? serviceKey = null)
-    {
-        return (serviceKey is null && serviceType == typeof(ChatClientMetadata))
-            ? this._metadata
-            : (serviceKey is null && serviceType == typeof(AIProjectClient))
-            ? this._agentClient
-            : (serviceKey is null && serviceType == typeof(ProjectsAgentVersion))
-            ? this._agentVersion
-            : (serviceKey is null && serviceType == typeof(ProjectsAgentRecord))
-            ? this._agentRecord
-            : (serviceKey is null && serviceType == typeof(AgentReference))
-            ? this._agentReference
-            : base.GetService(serviceType, serviceKey);
-    }
-
-    /// <inheritdoc/>
-    public override async Task<ChatResponse> GetResponseAsync(IEnumerable<ChatMessage> messages, ChatOptions? options = null, CancellationToken cancellationToken = default)
-    {
-        var agentOptions = this.GetAgentEnabledChatOptions(options);
-
-        return await base.GetResponseAsync(messages, agentOptions, cancellationToken).ConfigureAwait(false);
-    }
-
-    /// <inheritdoc/>
-    public override async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(IEnumerable<ChatMessage> messages, ChatOptions? options = null, [EnumeratorCancellation] CancellationToken cancellationToken = default)
-    {
-        var agentOptions = this.GetAgentEnabledChatOptions(options);
-
-        await foreach (var chunk in base.GetStreamingResponseAsync(messages, agentOptions, cancellationToken).ConfigureAwait(false))
-        {
-            yield return chunk;
-        }
-    }
-
-    private ChatOptions GetAgentEnabledChatOptions(ChatOptions? options)
-    {
-        // Start with a clone of the base chat options defined for the agent, if any.
-        ChatOptions agentEnabledChatOptions = this._chatOptions?.Clone() ?? new();
-
-        // Ignore per-request all options that can't be overridden.
-        agentEnabledChatOptions.Instructions = null;
-        agentEnabledChatOptions.Tools = null;
-        agentEnabledChatOptions.Temperature = null;
-        agentEnabledChatOptions.TopP = null;
-        agentEnabledChatOptions.PresencePenalty = null;
-        agentEnabledChatOptions.ResponseFormat = null;
-
-        // Use the conversation from the request, or the one defined at the client level.
-        agentEnabledChatOptions.ConversationId = options?.ConversationId ?? this._chatOptions?.ConversationId;
-
-        // Preserve the original RawRepresentationFactory
-        var originalFactory = options?.RawRepresentationFactory;
-
-        agentEnabledChatOptions.RawRepresentationFactory = (client) =>
-        {
-            if (originalFactory?.Invoke(this) is not CreateResponseOptions responseCreationOptions)
-            {
-                responseCreationOptions = new CreateResponseOptions();
-            }
-
-            responseCreationOptions.Agent = this._agentReference;
-#pragma warning disable SCME0001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
-            responseCreationOptions.Patch.Remove("$.model"u8);
-#pragma warning restore SCME0001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
-
-            return responseCreationOptions;
-        };
-
-        return agentEnabledChatOptions;
-    }
-}
@@ -1,35 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using System;
-using Azure.AI.Projects;
-using Microsoft.Extensions.AI;
-using Microsoft.Shared.Diagnostics;
-
-namespace Microsoft.Agents.AI.Foundry;
-
-#pragma warning disable OPENAI001
-internal sealed class AzureAIProjectResponsesChatClient : DelegatingChatClient
-{
-    private readonly ChatClientMetadata _metadata;
-    private readonly AIProjectClient _aiProjectClient;
-
-    internal AzureAIProjectResponsesChatClient(AIProjectClient aiProjectClient, string defaultModelId)
-        : base(Throw.IfNull(aiProjectClient)
-            .GetProjectOpenAIClient()
-            .GetProjectResponsesClientForModel(Throw.IfNullOrWhitespace(defaultModelId))
-            .AsIChatClient())
-    {
-        this._aiProjectClient = aiProjectClient;
-        this._metadata = new ChatClientMetadata("microsoft.foundry", defaultModelId: defaultModelId);
-    }
-
-    public override object? GetService(Type serviceType, object? serviceKey = null)
-    {
-        return (serviceKey is null && serviceType == typeof(ChatClientMetadata))
-            ? this._metadata
-            : (serviceKey is null && serviceType == typeof(AIProjectClient))
-            ? this._aiProjectClient
-            : base.GetService(serviceType, serviceKey);
-    }
-}
-#pragma warning restore OPENAI001
@@ -0,0 +1,42 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+using System.Threading;
+using System.Threading.Tasks;
+using Azure.AI.Extensions.OpenAI;
+using Azure.AI.Projects.Agents;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI.Foundry;
+
+/// <summary>
+/// Foundry-specific extensions on <see cref="ChatClientAgent"/>. Mirrors Python's free
+/// <c>to_prompt_agent(agent)</c> function for agents whose underlying chat client is a
+/// <see cref="FoundryChatClient"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
+public static class ChatClientAgentFoundryExtensions
+{
+    /// <summary>
+    /// Converts the supplied agent into a <see cref="ProjectsAgentDefinition"/> ready to publish
+    /// via <c>AgentAdministrationClient.CreateAgentVersionAsync</c>.
+    /// </summary>
+    /// <remarks>
+    /// Only works on agents whose chat client is a <see cref="FoundryChatClient"/> and whose
+    /// construction mode is convertible. The Agent Endpoint construction mode (Mode 3) is not
+    /// convertible because no local definition exists; conversion in that case throws.
+    /// </remarks>
+    /// <param name="agent">The chat client agent to convert.</param>
+    /// <param name="cancellationToken">A token that can cancel an internal server-side fetch when the agent was constructed from a bare <see cref="AgentReference"/>.</param>
+    /// <returns>A <see cref="ProjectsAgentDefinition"/> suitable for publishing.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="agent"/> is <see langword="null"/>.</exception>
+    /// <exception cref="InvalidOperationException">The agent's chat client is not a <see cref="FoundryChatClient"/>; the agent was constructed via the Agent Endpoint mode (Mode 3); no model id is set on the agent's <see cref="ChatOptions"/> for the Responses Agent mode (Mode 1); or the agent contains an <see cref="AITool"/> that cannot be converted to a <c>ResponseTool</c>.</exception>
+    public static Task<ProjectsAgentDefinition> ToPromptAgentAsync(this ChatClientAgent agent, CancellationToken cancellationToken = default)
+    {
+        Throw.IfNull(agent);
+        return FoundryPromptAgentConverter.ConvertAsync(agent.ChatClient, agent.GetService<ChatOptions>(), cancellationToken);
+    }
+}
@@ -39,11 +39,6 @@ namespace Microsoft.Agents.AI.Foundry;
 [Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
 public sealed class FoundryAgent : DelegatingAIAgent
 {
-    /// <summary>
-    /// The cached <see cref="AIProjectClient"/> supplied to or constructed by the active constructor.
-    /// </summary>
-    private readonly AIProjectClient _aiProjectClient;
-
    /// <summary>
    /// Initializes a new instance of the <see cref="FoundryAgent"/> class using the direct Responses API path.
    /// </summary>
@@ -73,9 +68,8 @@ public sealed class FoundryAgent : DelegatingAIAgent
        : base(CreateInnerAgent(
            CreateProjectClient(projectEndpoint, credential, clientOptions),
            model, instructions, name, description, tools, clientFactory, loggerFactory, services,
-            out var aiProjectClient))
+            out _))
    {
-        this._aiProjectClient = aiProjectClient;
    }

    /// <summary>
@@ -87,9 +81,11 @@ public sealed class FoundryAgent : DelegatingAIAgent
    /// </param>
    /// <param name="credential">The authentication credential.</param>
    /// <param name="clientOptions">
-    /// Optional configuration for the underlying <see cref="ProjectResponsesClient"/>. When supplied:
+    /// Optional configuration for the underlying <see cref="ProjectOpenAIClient"/>. When supplied:
    /// <list type="bullet">
    ///   <item><description>The instance is passed through to the per-agent client; pipeline policies added via <c>AddPolicy(...)</c> on it execute on the per-agent traffic.</description></item>
+    ///   <item><description><c>Endpoint</c> and <see cref="ProjectOpenAIClientOptions.AgentName"/> are owned by this constructor and are overwritten with values derived from <paramref name="agentEndpoint"/>; any caller value is replaced.</description></item>
+    ///   <item><description>For the project-level conversations client a separate fresh options bag is built that copies only <see cref="ClientPipelineOptions.RetryPolicy"/>, <see cref="ClientPipelineOptions.NetworkTimeout"/>, <see cref="ClientPipelineOptions.Transport"/>, and <c>UserAgentApplicationId</c>; pipeline policies added via <c>AddPolicy(...)</c> do <strong>not</strong> propagate to the conversations pipeline.</description></item>
    /// </list>
    /// </param>
    /// <param name="tools">Optional tools to use when interacting with the agent.</param>
@@ -113,43 +109,37 @@ public sealed class FoundryAgent : DelegatingAIAgent
        IList<AITool>? tools = null,
        Func<IChatClient, IChatClient>? clientFactory = null,
        IServiceProvider? services = null)
-        : base(CreateInnerAgentFromAgentEndpoint(agentEndpoint, credential, clientOptions, tools, clientFactory, services, out var aiProjectClient))
+        : base(CreateInnerAgentFromAgentEndpoint(agentEndpoint, credential, clientOptions, tools, clientFactory, services))
    {
-        this._aiProjectClient = aiProjectClient;
    }

    /// <summary>
-    /// Initializes a new instance of the <see cref="FoundryAgent"/> class from an agent-specific
-    /// endpoint while reusing an existing <see cref="AIProjectClient"/>.
+    /// Internal constructor used by the <c>AsAIAgent(this AIProjectClient, Uri, ...)</c>
+    /// extension where the caller already has an <see cref="AIProjectClient"/> and the agent
+    /// endpoint URI. Reuses the supplied client's pipeline (no new credential or transport is
+    /// stamped) and surfaces the agent through a <see cref="FoundryChatClient"/> just like the
+    /// public agent-endpoint ctor.
    /// </summary>
-    /// <param name="aiProjectClient">An existing <see cref="AIProjectClient"/> rooted at the same project as <paramref name="agentEndpoint"/>.</param>
-    /// <param name="agentEndpoint">
-    /// The agent-specific endpoint URI. Must be of the shape
-    /// <c>https://&lt;host&gt;/.../projects/&lt;project&gt;/agents/&lt;agentName&gt;/endpoint/protocols/openai</c>.
-    /// </param>
-    /// <param name="tools">Optional tools to use when interacting with the agent.</param>
-    /// <param name="clientFactory">Provides a way to customize the creation of the underlying <see cref="IChatClient"/>.</param>
-    /// <param name="services">Optional service provider for resolving dependencies required by AI functions.</param>
-    /// <exception cref="ArgumentNullException"><paramref name="aiProjectClient"/> or <paramref name="agentEndpoint"/> is null.</exception>
-    /// <exception cref="ArgumentException"><paramref name="agentEndpoint"/> does not match the expected agent-endpoint shape.</exception>
    internal FoundryAgent(
        AIProjectClient aiProjectClient,
        Uri agentEndpoint,
        IList<AITool>? tools = null,
        Func<IChatClient, IChatClient>? clientFactory = null,
        IServiceProvider? services = null)
-        : base(BuildAgentEndpointInnerAgent(aiProjectClient, agentEndpoint, clientOptions: null, tools, clientFactory, services))
+        : base(CreateInnerAgentFromAgentEndpointReusingProjectClient(aiProjectClient, agentEndpoint, tools, clientFactory, services))
    {
-        this._aiProjectClient = Throw.IfNull(aiProjectClient);
    }

    /// <summary>
-    /// Internal constructor used by <c>AsAIAgent</c> extension methods that already have an <see cref="AIProjectClient"/> and a configured <see cref="ChatClientAgent"/>.
+    /// Internal constructor used by <c>AsAIAgent</c> extension methods that already have a
+    /// configured <see cref="ChatClientAgent"/>. The inner agent already routes through a
+    /// <see cref="FoundryChatClient"/> whose <c>GetService&lt;AIProjectClient&gt;()</c> surfaces
+    /// the project client to downstream callers, so the agent does not also need a private
+    /// <see cref="AIProjectClient"/> reference here.
    /// </summary>
-    internal FoundryAgent(AIProjectClient aiProjectClient, ChatClientAgent innerAgent)
+    internal FoundryAgent(ChatClientAgent innerAgent)
        : base(WireClientHeaders(Throw.IfNull(innerAgent)))
    {
-        this._aiProjectClient = Throw.IfNull(aiProjectClient);
    }

    #region Convenience methods
@@ -182,7 +172,13 @@ public sealed class FoundryAgent : DelegatingAIAgent
    /// <returns>A <see cref="ChatClientAgentSession"/> linked to the newly created server-side conversation.</returns>
    public async Task<ChatClientAgentSession> CreateConversationSessionAsync(CancellationToken cancellationToken = default)
    {
-        var conversationsClient = this._aiProjectClient.ProjectOpenAIClient.GetProjectConversationsClient();
+        // The inner FoundryChatClient surfaces an AIProjectClient via GetService for all
+        // three construction modes (Plan #2 Agent Endpoint mode materialization). Resolve it through the
+        // delegating chain at call time instead of caching a private reference on this agent.
+        var aiProjectClient = this.GetService<AIProjectClient>()
+            ?? throw new InvalidOperationException(
+                "FoundryAgent inner chain does not expose an AIProjectClient; cannot create a project-level conversation session.");
+        var conversationsClient = aiProjectClient.GetProjectOpenAIClient().GetProjectConversationsClient();

        var conversation = (await conversationsClient.CreateProjectConversationAsync(options: null, cancellationToken).ConfigureAwait(false)).Value;

@@ -196,17 +192,6 @@ public sealed class FoundryAgent : DelegatingAIAgent

    #endregion

-    /// <inheritdoc/>
-    public override object? GetService(Type serviceType, object? serviceKey = null)
-    {
-        if (serviceKey is null && serviceType == typeof(AIProjectClient))
-        {
-            return this._aiProjectClient;
-        }
-
-        return base.GetService(serviceType, serviceKey);
-    }
-
    #region Private helpers

    private static AIAgent CreateInnerAgent(
@@ -251,7 +236,7 @@ public sealed class FoundryAgent : DelegatingAIAgent
        Throw.IfNull(agentOptions.ChatOptions);
        Throw.IfNullOrWhitespace(agentOptions.ChatOptions.ModelId);

-        IChatClient chatClient = new AzureAIProjectResponsesChatClient(aiProjectClient, agentOptions.ChatOptions.ModelId);
+        IChatClient chatClient = new FoundryChatClient(aiProjectClient, agentOptions.ChatOptions.ModelId);

        if (clientFactory is not null)
        {
@@ -288,16 +273,10 @@ public sealed class FoundryAgent : DelegatingAIAgent
    }

    /// <summary>
-    /// Builds the inner <see cref="ChatClientAgent"/> for the agent-endpoint constructor by
-    /// constructing a project-scoped <see cref="ProjectOpenAIClient"/> and using
-    /// <see cref="ProjectOpenAIClient.GetProjectResponsesClientForAgentEndpoint(string, string?, ProjectOpenAIClientOptions?)"/>.
-    /// This routes the outbound URL through the per-agent endpoint shape that the Foundry service
-    /// expects for hosted agents and lets the SDK auto-append the <c>api-version</c> query string.
-    /// Caller-supplied <paramref name="clientOptions"/> are passed through to the per-agent
-    /// client with <c>Endpoint</c> and
-    /// <see cref="ProjectOpenAIClientOptions.AgentName"/> overridden by values derived from
-    /// <paramref name="agentEndpoint"/>; any policies the caller added via <c>AddPolicy</c>
-    /// remain in effect on the per-agent pipeline. The MEAI user-agent policy is appended last.
+    /// Builds the inner <see cref="ChatClientAgent"/> for the agent-endpoint constructor. The
+    /// per-agent <see cref="ProjectOpenAIClient"/> shape and URL parsing are owned by
+    /// <see cref="FoundryChatClient"/>; we just construct it in the Agent Endpoint mode (Mode 3)
+    /// and pass the inner chat client through any caller-provided <paramref name="clientFactory"/>.
    /// </summary>
    private static AIAgent CreateInnerAgentFromAgentEndpoint(
        Uri agentEndpoint,
@@ -305,44 +284,14 @@ public sealed class FoundryAgent : DelegatingAIAgent
        ProjectOpenAIClientOptions? clientOptions,
        IList<AITool>? tools,
        Func<IChatClient, IChatClient>? clientFactory,
-        IServiceProvider? services,
-        out AIProjectClient outClient)
+        IServiceProvider? services)
    {
        Throw.IfNull(agentEndpoint);
        Throw.IfNull(credential);

-        var (_, projectRoot) = ParseAgentEndpoint(agentEndpoint);
-        outClient = CreateProjectClient(projectRoot, credential, CreateProjectClientOptions(clientOptions));
+        IChatClient chatClient = new FoundryChatClient(agentEndpoint, credential, clientOptions);
+        var agentName = ((FoundryChatClient)chatClient).AgentName!;

-        return BuildAgentEndpointInnerAgent(outClient, agentEndpoint, clientOptions, tools, clientFactory, services);
-    }
-
-    /// <summary>
-    /// Builds the inner <see cref="ChatClientAgent"/> for an agent endpoint against a pre-built
-    /// <see cref="AIProjectClient"/>. The caller is responsible for ensuring the supplied client
-    /// is rooted at the same project as <paramref name="agentEndpoint"/>; the agent name is
-    /// parsed from the endpoint URI and passed to
-    /// <see cref="ProjectOpenAIClient.GetProjectResponsesClientForAgentEndpoint(string, string?, ProjectOpenAIClientOptions?)"/>.
-    /// </summary>
-    private static AIAgent BuildAgentEndpointInnerAgent(
-        AIProjectClient aiProjectClient,
-        Uri agentEndpoint,
-        ProjectOpenAIClientOptions? clientOptions,
-        IList<AITool>? tools,
-        Func<IChatClient, IChatClient>? clientFactory,
-        IServiceProvider? services)
-    {
-        Throw.IfNull(aiProjectClient);
-        Throw.IfNull(agentEndpoint);
-
-        var (agentName, _) = ParseAgentEndpoint(agentEndpoint);
-
-        var perAgentOptions = clientOptions ?? new ProjectOpenAIClientOptions();
-        perAgentOptions.AddPolicy(RequestOptionsExtensions.UserAgentPolicy, PipelinePosition.PerCall);
-
-        IChatClient chatClient = aiProjectClient.ProjectOpenAIClient
-            .GetProjectResponsesClientForAgentEndpoint(agentName, options: perAgentOptions)
-            .AsIChatClient();
        if (clientFactory is not null)
        {
            chatClient = clientFactory(chatClient);
@@ -358,6 +307,46 @@ public sealed class FoundryAgent : DelegatingAIAgent
        return WireClientHeaders(new ChatClientAgent(chatClient, agentOptions, services: services));
    }

+    /// <summary>
+    /// Variant of <see cref="CreateInnerAgentFromAgentEndpoint"/> that reuses an existing
+    /// <see cref="AIProjectClient"/>'s pipeline instead of stamping a fresh credential. Used by
+    /// the <c>AsAIAgent(AIProjectClient, Uri agentEndpoint, ...)</c> extension overload.
+    /// </summary>
+    private static AIAgent CreateInnerAgentFromAgentEndpointReusingProjectClient(
+        AIProjectClient aiProjectClient,
+        Uri agentEndpoint,
+        IList<AITool>? tools,
+        Func<IChatClient, IChatClient>? clientFactory,
+        IServiceProvider? services)
+    {
+        Throw.IfNull(aiProjectClient);
+        Throw.IfNull(agentEndpoint);
+
+        IChatClient chatClient = new FoundryChatClient(aiProjectClient, agentEndpoint, clientOptions: null);
+        var agentName = ((FoundryChatClient)chatClient).AgentName!;
+
+        if (clientFactory is not null)
+        {
+            chatClient = clientFactory(chatClient);
+        }
+
+        ChatClientAgentOptions agentOptions = new()
+        {
+            Id = agentName,
+            Name = agentName,
+            ChatOptions = new() { Tools = tools },
+        };
+
+        return WireClientHeaders(new ChatClientAgent(chatClient, agentOptions, services: services));
+    }
+
+    /// <summary>
+    /// Parses an agent endpoint URI. Delegates to <see cref="FoundryChatClient.ParseAgentEndpoint(Uri)"/>
+    /// so the chat client and the agent share a single source of truth for the URL shape.
+    /// </summary>
+    internal static (string AgentName, Uri ProjectRoot) ParseAgentEndpoint(Uri agentEndpoint)
+        => FoundryChatClient.ParseAgentEndpoint(agentEndpoint);
+
    /// <summary>
    /// Parses an agent endpoint URI of shape
    /// <c>https://&lt;host&gt;/.../projects/&lt;project&gt;/agents/&lt;agentName&gt;/endpoint/protocols/openai</c>
@@ -369,90 +358,12 @@ public sealed class FoundryAgent : DelegatingAIAgent
    /// strips query string and fragment. Throws <see cref="ArgumentException"/> for inputs that
    /// do not match the expected shape.
    /// </remarks>
-    /// <exception cref="ArgumentException">
-    /// The endpoint is missing the <c>/agents/</c> segment, has an empty agent name, or has a
-    /// suffix other than <c>/endpoint/protocols/openai</c>.
-    /// </exception>
-    internal static (string AgentName, Uri ProjectRoot) ParseAgentEndpoint(Uri agentEndpoint)
-    {
-        Throw.IfNull(agentEndpoint);
-
-        const string AgentsSegment = "/agents/";
-        const string ExpectedSuffix = "/endpoint/protocols/openai";
-
-        var path = agentEndpoint.AbsolutePath.TrimEnd('/');
-        var idx = path.IndexOf(AgentsSegment, StringComparison.OrdinalIgnoreCase);
-        if (idx < 0)
-        {
-            throw new ArgumentException(
-                $"Expected an agent endpoint of shape 'https://<host>/.../projects/<project>/agents/<agentName>/endpoint/protocols/openai' but got '{agentEndpoint}'.",
-                nameof(agentEndpoint));
-        }
-
-        var afterAgents = path.Substring(idx + AgentsSegment.Length);
-        var nextSlash = afterAgents.IndexOf('/');
-        if (nextSlash <= 0)
-        {
-            throw new ArgumentException(
-                $"Agent endpoint '{agentEndpoint}' is missing the '<agentName>{ExpectedSuffix}' suffix.",
-                nameof(agentEndpoint));
-        }
-
-        var agentName = afterAgents.Substring(0, nextSlash);
-        var suffix = afterAgents.Substring(nextSlash);
-        if (!string.Equals(suffix, ExpectedSuffix, StringComparison.OrdinalIgnoreCase))
-        {
-            throw new ArgumentException(
-                $"Agent endpoint '{agentEndpoint}' has an unexpected suffix '{suffix}'. Expected '{ExpectedSuffix}'.",
-                nameof(agentEndpoint));
-        }
-
-        var rootPath = path.Substring(0, idx);
-        var projectRoot = new UriBuilder(agentEndpoint)
-        {
-            Path = rootPath,
-            Query = string.Empty,
-            Fragment = string.Empty,
-        }.Uri;
-
-        return (agentName, projectRoot);
-    }
-
    private static AIProjectClient CreateProjectClient(Uri endpoint, AuthenticationTokenProvider credential, AIProjectClientOptions? clientOptions = null)
    {
        Throw.IfNull(endpoint);
        Throw.IfNull(credential);

-        clientOptions ??= new AIProjectClientOptions();
-        clientOptions.AddPolicy(RequestOptionsExtensions.UserAgentPolicy, PipelinePosition.PerCall);
-        return new AIProjectClient(endpoint, credential, clientOptions);
-    }
-
-    internal static AIProjectClientOptions? CreateProjectClientOptions(ProjectOpenAIClientOptions? clientOptions)
-    {
-        if (clientOptions is null)
-        {
-            return null;
-        }
-
-        // Copy pipeline behavior the caller configured on the per-agent options bag onto the
-        // project-level options bag so the agent endpoint client honors it. UserAgentApplicationId
-        // is project-level (not derived from the agent endpoint), so it must be carried through too.
-        var projectOptions = new AIProjectClientOptions
-        {
-            Transport = clientOptions.Transport,
-            RetryPolicy = clientOptions.RetryPolicy,
-            NetworkTimeout = clientOptions.NetworkTimeout,
-            MessageLoggingPolicy = clientOptions.MessageLoggingPolicy,
-            UserAgentApplicationId = clientOptions.UserAgentApplicationId,
-        };
-
-        if (clientOptions.ClientLoggingOptions is not null)
-        {
-            projectOptions.ClientLoggingOptions = clientOptions.ClientLoggingOptions;
-        }
-
-        return projectOptions;
+        return new AIProjectClient(endpoint, credential, clientOptions ?? new AIProjectClientOptions());
    }

    #endregion
@@ -0,0 +1,116 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Threading;
+using System.Threading.Tasks;
+using Azure.AI.Extensions.OpenAI;
+using Azure.AI.Projects.Agents;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+using OpenAI.Files;
+using OpenAI.VectorStores;
+
+#pragma warning disable OPENAI001
+
+namespace Microsoft.Agents.AI.Foundry;
+
+/// <summary>
+/// Foundry-specific extensions on <see cref="FoundryAgent"/>. Hosts the prompt-agent converter
+/// plus thin forwarders that surface the file and vector-store helpers from the inner
+/// <see cref="FoundryChatClient"/> at the agent level so callers do not need to drop down to
+/// <c>agent.GetService&lt;FoundryChatClient&gt;().X()</c> for common workflows.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
+public static class FoundryAgentExtensions
+{
+    /// <summary>
+    /// Converts the supplied <see cref="FoundryAgent"/> into a <see cref="ProjectsAgentDefinition"/>
+    /// ready to publish via <c>AgentAdministrationClient.CreateAgentVersionAsync</c>.
+    /// </summary>
+    /// <remarks>
+    /// The Agent Endpoint construction mode (Mode 3) is not convertible because no local
+    /// definition exists; conversion in that case throws <see cref="InvalidOperationException"/>.
+    /// </remarks>
+    /// <param name="agent">The Foundry agent to convert.</param>
+    /// <param name="cancellationToken">A token that can cancel an internal server-side fetch when the agent was constructed from a bare <see cref="AgentReference"/>.</param>
+    /// <returns>A <see cref="ProjectsAgentDefinition"/> suitable for publishing.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="agent"/> is <see langword="null"/>.</exception>
+    /// <exception cref="InvalidOperationException">The agent's chat client is not a <see cref="FoundryChatClient"/>; the agent was constructed via the Agent Endpoint mode (Mode 3); no model id is set on the agent's <see cref="ChatOptions"/> for the Responses Agent mode (Mode 1); or the agent contains an <see cref="AITool"/> that cannot be converted to a <c>ResponseTool</c>.</exception>
+    public static Task<ProjectsAgentDefinition> ToPromptAgentAsync(this FoundryAgent agent, CancellationToken cancellationToken = default)
+    {
+        Throw.IfNull(agent);
+
+        var innerChatClient = agent.GetService<IChatClient>()
+            ?? throw new InvalidOperationException(
+                "ToPromptAgentAsync could not resolve the inner IChatClient on the FoundryAgent.");
+        var chatOptions = agent.GetService<ChatOptions>();
+        return FoundryPromptAgentConverter.ConvertAsync(innerChatClient, chatOptions, cancellationToken);
+    }
+
+    /// <summary>
+    /// Uploads a file to the project. Thin forwarder to
+    /// <see cref="FoundryChatClient.UploadFileAsync(string, FileUploadPurpose, CancellationToken)"/>
+    /// on the agent's inner <see cref="FoundryChatClient"/>.
+    /// </summary>
+    /// <param name="agent">The Foundry agent whose inner chat client owns the upload pipeline.</param>
+    /// <param name="filePath">Path to the file to upload.</param>
+    /// <param name="purpose">The upload purpose (e.g. <see cref="FileUploadPurpose.Assistants"/>).</param>
+    /// <param name="cancellationToken">A token that can cancel the upload.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="agent"/> is <see langword="null"/>.</exception>
+    /// <exception cref="InvalidOperationException">The agent does not expose a <see cref="FoundryChatClient"/> via <see cref="AIAgent.GetService{TService}(object?)"/>.</exception>
+    public static Task<OpenAIFile> UploadFileAsync(this FoundryAgent agent, string filePath, FileUploadPurpose purpose, CancellationToken cancellationToken = default)
+        => RequireFoundryChatClient(agent).UploadFileAsync(filePath, purpose, cancellationToken);
+
+    /// <summary>
+    /// Deletes a previously uploaded file. Thin forwarder to
+    /// <see cref="FoundryChatClient.DeleteFileAsync(string, CancellationToken)"/>.
+    /// </summary>
+    /// <param name="agent">The Foundry agent whose inner chat client owns the file pipeline.</param>
+    /// <param name="fileId">The file id returned by <see cref="UploadFileAsync(FoundryAgent, string, FileUploadPurpose, CancellationToken)"/>.</param>
+    /// <param name="cancellationToken">A token that can cancel the delete.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="agent"/> is <see langword="null"/>.</exception>
+    /// <exception cref="InvalidOperationException">The agent does not expose a <see cref="FoundryChatClient"/>.</exception>
+    public static Task<FileDeletionResult> DeleteFileAsync(this FoundryAgent agent, string fileId, CancellationToken cancellationToken = default)
+        => RequireFoundryChatClient(agent).DeleteFileAsync(fileId, cancellationToken);
+
+    /// <summary>
+    /// Uploads the supplied files, creates a vector store containing them, and waits until the
+    /// store leaves the in-progress state. Thin forwarder to
+    /// <see cref="FoundryChatClient.CreateVectorStoreAsync(string, IEnumerable{string}, TimeSpan?, TimeSpan?, CancellationToken)"/>.
+    /// </summary>
+    /// <param name="agent">The Foundry agent whose inner chat client owns the file and vector-store pipeline.</param>
+    /// <param name="name">The vector store name.</param>
+    /// <param name="filePaths">Paths to files to upload and attach to the store.</param>
+    /// <param name="expiresAfter">Optional last-active-at expiration window.</param>
+    /// <param name="pollingTimeout">Optional upper bound on the wait for the vector store to leave the in-progress state. Defaults to 5 minutes; pass <see cref="Timeout.InfiniteTimeSpan"/> to disable.</param>
+    /// <param name="cancellationToken">A token that can cancel the orchestration.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="agent"/> is <see langword="null"/>.</exception>
+    /// <exception cref="InvalidOperationException">The agent does not expose a <see cref="FoundryChatClient"/>.</exception>
+    /// <exception cref="TimeoutException">The vector store did not leave the in-progress state within <paramref name="pollingTimeout"/>.</exception>
+    public static Task<VectorStore> CreateVectorStoreAsync(this FoundryAgent agent, string name, IEnumerable<string> filePaths, TimeSpan? expiresAfter = null, TimeSpan? pollingTimeout = null, CancellationToken cancellationToken = default)
+        => RequireFoundryChatClient(agent).CreateVectorStoreAsync(name, filePaths, expiresAfter, pollingTimeout, cancellationToken);
+
+    /// <summary>
+    /// Deletes a vector store. Thin forwarder to
+    /// <see cref="FoundryChatClient.DeleteVectorStoreAsync(string, CancellationToken)"/>.
+    /// </summary>
+    /// <param name="agent">The Foundry agent whose inner chat client owns the vector-store pipeline.</param>
+    /// <param name="vectorStoreId">The vector store id.</param>
+    /// <param name="cancellationToken">A token that can cancel the delete.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="agent"/> is <see langword="null"/>.</exception>
+    /// <exception cref="InvalidOperationException">The agent does not expose a <see cref="FoundryChatClient"/>.</exception>
+    public static Task<VectorStoreDeletionResult> DeleteVectorStoreAsync(this FoundryAgent agent, string vectorStoreId, CancellationToken cancellationToken = default)
+        => RequireFoundryChatClient(agent).DeleteVectorStoreAsync(vectorStoreId, cancellationToken);
+
+    private static FoundryChatClient RequireFoundryChatClient(FoundryAgent agent)
+    {
+        Throw.IfNull(agent);
+        return agent.GetService<FoundryChatClient>()
+            ?? throw new InvalidOperationException(
+                "FoundryAgent does not expose a FoundryChatClient via GetService<FoundryChatClient>(). " +
+                "File and vector-store helpers require the agent's inner chat client to be a FoundryChatClient.");
+    }
+}
@@ -0,0 +1,703 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.ClientModel;
+using System.ClientModel.Primitives;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.IO;
+using System.Runtime.CompilerServices;
+using System.Threading;
+using System.Threading.Tasks;
+using Azure.AI.Extensions.OpenAI;
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+using OpenAI.Files;
+using OpenAI.Responses;
+using OpenAI.VectorStores;
+
+#pragma warning disable OPENAI001
+
+namespace Microsoft.Agents.AI.Foundry;
+
+/// <summary>
+/// Foundry chat-client decorator that unifies the three Foundry chat-client construction
+/// modes (Responses Agent, Prompt Agent, Agent Endpoint) behind a single type and centralizes
+/// Foundry-specific concerns: <c>microsoft.foundry</c> telemetry tagging,
+/// <c>agent-framework-dotnet/{version}</c> User-Agent stamping, <c>x-ms-served-model</c>
+/// response-header capture, and (for Prompt Agents) per-request payload mutation that injects
+/// the agent reference and strips per-request overrides that the server owns.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Replaces the previous <c>AzureAIProjectChatClient</c> and <c>AzureAIProjectResponsesChatClient</c>
+/// decorators. All Foundry entry points (the public <c>FoundryAgent</c> constructors and the
+/// <c>AIProjectClientExtensions.AsAIAgent</c> overloads) now construct a
+/// <see cref="FoundryChatClient"/> internally, so telemetry and the agent-framework User-Agent
+/// segment are uniform across paths.
+/// </para>
+/// <para>
+/// The three construction modes are:
+/// </para>
+/// <list type="bullet">
+///   <item><description><b>Responses Agent</b> (Mode 1): direct Responses API call against a project-level model id; no server-side agent definition exists. Constructed from <c>(AIProjectClient, modelId)</c>.</description></item>
+///   <item><description><b>Prompt Agent</b> (Mode 2): server-side agent definition (a <see cref="ProjectsAgentDefinition"/>, typically a <see cref="DeclarativeAgentDefinition"/>) invoked by <see cref="AgentReference"/> against the project Responses URL. Constructed from <see cref="AgentReference"/>, <see cref="ProjectsAgentVersion"/>, or <see cref="ProjectsAgentRecord"/>.</description></item>
+///   <item><description><b>Agent Endpoint</b> (Mode 3): invocation via the per-agent endpoint URL <c>…/projects/{p}/agents/{name}/endpoint/protocols/openai</c>. The agent behind the endpoint can be either a hosted (container-backed) agent or a Prompt Agent. Constructed from <c>(Uri agentEndpoint, credential)</c>.</description></item>
+/// </list>
+/// <para>
+/// Note: "Hosted Agent" refers to a container-based runtime agent (see
+/// <c>Microsoft.Agents.AI.Foundry.Hosting</c>) and is the <i>kind</i> of agent that may sit
+/// behind an Agent Endpoint. It is not synonymous with the Agent Endpoint mode itself.
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
+public sealed class FoundryChatClient : DelegatingChatClient
+{
+    private readonly ChatClientMetadata _metadata;
+    private readonly AIProjectClient? _aiProjectClient;
+    private readonly AgentReference? _agentReference;
+    private readonly ProjectsAgentVersion? _agentVersion;
+    private readonly ProjectsAgentRecord? _agentRecord;
+    private readonly ChatOptions? _baseChatOptions;
+
+    /// <summary>
+    /// Initializes a new instance for the Responses Agent mode (Mode 1): direct Responses API
+    /// call against a project-level model id; no server-side agent definition exists.
+    /// </summary>
+    /// <param name="aiProjectClient">The project client.</param>
+    /// <param name="modelId">The model deployment id.</param>
+    internal FoundryChatClient(AIProjectClient aiProjectClient, string modelId)
+        : base(Throw.IfNull(aiProjectClient)
+            .GetProjectOpenAIClient()
+            .GetProjectResponsesClientForModel(Throw.IfNullOrWhitespace(modelId))
+            .AsIChatClient())
+    {
+        this._aiProjectClient = aiProjectClient;
+        this._metadata = new ChatClientMetadata("microsoft.foundry", defaultModelId: modelId);
+        TryRegisterAgentFrameworkUserAgentPolicy(this.InnerClient);
+        TryRegisterServedModelPolicy(this.InnerClient);
+    }
+
+    /// <summary>
+    /// Initializes a new instance for the Prompt Agent mode (Mode 2): server-side agent
+    /// definition invoked by <see cref="AgentReference"/>.
+    /// </summary>
+    internal FoundryChatClient(AIProjectClient aiProjectClient, AgentReference agentReference, string? defaultModelId, ChatOptions? baseChatOptions)
+        : base(Throw.IfNull(aiProjectClient)
+            .GetProjectOpenAIClient()
+            .GetProjectResponsesClientForAgent(Throw.IfNull(agentReference))
+            .AsIChatClient())
+    {
+        this._aiProjectClient = aiProjectClient;
+        this._agentReference = agentReference;
+        this._metadata = new ChatClientMetadata("microsoft.foundry", defaultModelId: defaultModelId);
+        this._baseChatOptions = baseChatOptions;
+        this.AgentName = agentReference.Name;
+        TryRegisterAgentFrameworkUserAgentPolicy(this.InnerClient);
+        TryRegisterServedModelPolicy(this.InnerClient);
+    }
+
+    /// <summary>
+    /// Initializes a new instance for the Prompt Agent mode (Mode 2, record variant):
+    /// server-side agent definition invoked by record, resolving to the latest version.
+    /// </summary>
+    internal FoundryChatClient(AIProjectClient aiProjectClient, ProjectsAgentRecord agentRecord, ChatOptions? baseChatOptions)
+        : this(aiProjectClient, Throw.IfNull(agentRecord).GetLatestVersion(), baseChatOptions)
+    {
+        this._agentRecord = agentRecord;
+    }
+
+    /// <summary>
+    /// Initializes a new instance for the Prompt Agent mode (Mode 2, version variant):
+    /// server-side agent definition invoked by a specific version.
+    /// </summary>
+    internal FoundryChatClient(AIProjectClient aiProjectClient, ProjectsAgentVersion agentVersion, ChatOptions? baseChatOptions)
+        : this(
+              aiProjectClient,
+              CreateAgentReference(Throw.IfNull(agentVersion)),
+              (agentVersion.Definition as DeclarativeAgentDefinition)?.Model,
+              baseChatOptions)
+    {
+        this._agentVersion = agentVersion;
+    }
+
+    /// <summary>
+    /// Initializes a new instance for the Agent Endpoint mode (Mode 3): invocation via the
+    /// per-agent endpoint URL. Parses the URL into its per-agent
+    /// <see cref="ProjectOpenAIClient"/> shape internally and forwards through the resulting
+    /// responses client.
+    /// </summary>
+    /// <param name="agentEndpoint">
+    /// The agent-specific endpoint URI. Must be of the shape
+    /// <c>https://&lt;host&gt;/.../projects/&lt;project&gt;/agents/&lt;agentName&gt;/endpoint/protocols/openai</c>.
+    /// </param>
+    /// <param name="credential">The authentication credential.</param>
+    /// <param name="clientOptions">Optional per-agent client options. <c>Endpoint</c> and <c>AgentName</c> are owned by this ctor and overridden with values derived from <paramref name="agentEndpoint"/>.</param>
+    internal FoundryChatClient(Uri agentEndpoint, AuthenticationTokenProvider credential, ProjectOpenAIClientOptions? clientOptions)
+        : this(BuildAgentEndpointInner(agentEndpoint, credential, clientOptions))
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance for the Agent Endpoint mode (Mode 3) by reusing an existing
+    /// <see cref="AIProjectClient"/>'s pipeline. Equivalent to the
+    /// <see cref="FoundryChatClient(Uri, AuthenticationTokenProvider, ProjectOpenAIClientOptions?)"/>
+    /// constructor but skips building a fresh per-agent pipeline: the project-level
+    /// <see cref="ProjectOpenAIClient"/> on <paramref name="aiProjectClient"/> is used directly.
+    /// </summary>
+    /// <param name="aiProjectClient">The project client already configured at the project root containing <paramref name="agentEndpoint"/>.</param>
+    /// <param name="agentEndpoint">The per-agent endpoint URI. Same shape constraints as the other agent-endpoint ctor.</param>
+    /// <param name="clientOptions">Optional per-agent client options applied to the per-agent <c>GetProjectResponsesClientForAgentEndpoint</c> call.</param>
+    internal FoundryChatClient(AIProjectClient aiProjectClient, Uri agentEndpoint, ProjectOpenAIClientOptions? clientOptions)
+        : this(BuildAgentEndpointInnerFromProjectClient(aiProjectClient, agentEndpoint, clientOptions))
+    {
+    }
+
+    private FoundryChatClient(AgentEndpointInner inner)
+        : base(inner.ChatClient)
+    {
+        this._aiProjectClient = inner.AIProjectClient;
+        this.AgentName = inner.AgentName;
+        this._metadata = new ChatClientMetadata("microsoft.foundry");
+        TryRegisterAgentFrameworkUserAgentPolicy(this.InnerClient);
+        TryRegisterServedModelPolicy(this.InnerClient);
+    }
+
+    /// <summary>
+    /// Gets the agent name associated with this chat client.
+    /// </summary>
+    /// <remarks>
+    /// <para>Set in two cases:</para>
+    /// <list type="bullet">
+    /// <item>
+    /// <description>
+    /// Prompt Agent mode (Mode 2): the value of <see cref="AgentReference.Name"/> supplied at
+    /// construction.
+    /// </description>
+    /// </item>
+    /// <item>
+    /// <description>
+    /// Agent Endpoint mode (Mode 3): the agent name segment parsed from the supplied agent
+    /// endpoint URI.
+    /// </description>
+    /// </item>
+    /// </list>
+    /// <para>
+    /// Returns <see langword="null"/> for the Responses Agent mode (Mode 1) where no agent name
+    /// exists.
+    /// </para>
+    /// </remarks>
+    internal string? AgentName { get; }
+
+    /// <inheritdoc/>
+    public override object? GetService(Type serviceType, object? serviceKey = null)
+    {
+        return (serviceKey is null && serviceType == typeof(ChatClientMetadata))
+            ? this._metadata
+            : (serviceKey is null && serviceType == typeof(AIProjectClient))
+            ? this._aiProjectClient
+            : (serviceKey is null && serviceType == typeof(AgentReference))
+            ? this._agentReference
+            : (serviceKey is null && serviceType == typeof(ProjectsAgentVersion))
+            ? this._agentVersion
+            : (serviceKey is null && serviceType == typeof(ProjectsAgentRecord))
+            ? this._agentRecord
+            : base.GetService(serviceType, serviceKey);
+    }
+
+    /// <inheritdoc/>
+    public override async Task<ChatResponse> GetResponseAsync(IEnumerable<ChatMessage> messages, ChatOptions? options = null, CancellationToken cancellationToken = default)
+    {
+        var effectiveOptions = this._agentReference is not null
+            ? this.GetAgentEnabledChatOptions(options)
+            : options;
+
+        var box = new StrongBox<string?>(null);
+        var previous = ServedModelScope.Current;
+        ServedModelScope.Current = box;
+
+        try
+        {
+            var response = await base.GetResponseAsync(messages, effectiveOptions, cancellationToken).ConfigureAwait(false);
+
+            if (box.Value is { } servedModel)
+            {
+                response.ModelId = servedModel;
+            }
+
+            return response;
+        }
+        finally
+        {
+            ServedModelScope.Current = previous;
+        }
+    }
+
+    /// <inheritdoc/>
+    public override async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(IEnumerable<ChatMessage> messages, ChatOptions? options = null, [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        var effectiveOptions = this._agentReference is not null
+            ? this.GetAgentEnabledChatOptions(options)
+            : options;
+
+        var box = new StrongBox<string?>(null);
+        var previous = ServedModelScope.Current;
+        ServedModelScope.Current = box;
+
+        try
+        {
+            await foreach (var chunk in base.GetStreamingResponseAsync(messages, effectiveOptions, cancellationToken).ConfigureAwait(false))
+            {
+                if (box.Value is { } servedModel)
+                {
+                    chunk.ModelId = servedModel;
+                }
+
+                yield return chunk;
+            }
+        }
+        finally
+        {
+            ServedModelScope.Current = previous;
+        }
+    }
+
+    #region File and vector-store helpers (mirrors Python's foundry_chat_client surface)
+
+    /// <summary>
+    /// Uploads a single file to the project for the supplied purpose. The upload is performed
+    /// against the project-level <see cref="AIProjectClient"/> reachable via
+    /// <see cref="GetService(Type, object?)"/>, so this method works uniformly across all three
+    /// FoundryChatClient construction modes.
+    /// </summary>
+    /// <param name="filePath">Absolute or relative path to the file to upload. The file must exist.</param>
+    /// <param name="purpose">The file upload purpose (e.g. <see cref="FileUploadPurpose.Assistants"/>).</param>
+    /// <param name="cancellationToken">A token that can cancel the upload.</param>
+    /// <returns>The created <see cref="OpenAIFile"/> as returned by the service.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="filePath"/> is <see langword="null"/>.</exception>
+    /// <exception cref="FileNotFoundException">The file at <paramref name="filePath"/> does not exist.</exception>
+    public async Task<OpenAIFile> UploadFileAsync(string filePath, FileUploadPurpose purpose, CancellationToken cancellationToken = default)
+    {
+        Throw.IfNull(filePath);
+        if (!File.Exists(filePath))
+        {
+            throw new FileNotFoundException($"File not found: '{filePath}'.", filePath);
+        }
+
+        var fileClient = this.GetOpenAIFileClient();
+        // Use the Stream overload to honor cancellation; the (string, purpose) overload has no
+        // CancellationToken parameter in the OpenAI SDK.
+        using var stream = File.OpenRead(filePath);
+        var result = await fileClient.UploadFileAsync(stream, Path.GetFileName(filePath), purpose, cancellationToken).ConfigureAwait(false);
+        return result.Value;
+    }
+
+    /// <summary>Deletes a file previously uploaded to the project.</summary>
+    /// <param name="fileId">The file id returned by <see cref="UploadFileAsync(string, FileUploadPurpose, CancellationToken)"/>.</param>
+    /// <param name="cancellationToken">A token that can cancel the delete.</param>
+    /// <returns>The deletion result.</returns>
+    /// <exception cref="ArgumentException"><paramref name="fileId"/> is <see langword="null"/> or whitespace.</exception>
+    public async Task<FileDeletionResult> DeleteFileAsync(string fileId, CancellationToken cancellationToken = default)
+    {
+        Throw.IfNullOrWhitespace(fileId);
+        var fileClient = this.GetOpenAIFileClient();
+        var result = await fileClient.DeleteFileAsync(fileId, cancellationToken).ConfigureAwait(false);
+        return result.Value;
+    }
+
+    /// <summary>
+    /// Uploads the supplied files, creates a vector store containing them, waits until the
+    /// store finishes ingesting its files (status leaves <see cref="VectorStoreStatus.InProgress"/>),
+    /// and returns the <see cref="VectorStore"/>. Mirrors Python's
+    /// <c>foundry_chat_client.create_vector_store(name, files, expires_after_days)</c>.
+    /// </summary>
+    /// <param name="name">The vector store name.</param>
+    /// <param name="filePaths">Paths to files to upload and attach to the store.</param>
+    /// <param name="expiresAfter">Optional last-active-at expiration window. When supplied, the vector store expires this many days after its last use.</param>
+    /// <param name="pollingTimeout">Optional upper bound on the wait for the vector store to leave <see cref="VectorStoreStatus.InProgress"/>. Defaults to 5 minutes when not supplied; pass <see cref="Timeout.InfiniteTimeSpan"/> to disable. Independent of <paramref name="cancellationToken"/>: cancellation always wins.</param>
+    /// <param name="cancellationToken">A token that can cancel the orchestration.</param>
+    /// <returns>The created and fully-ready <see cref="VectorStore"/>. The returned instance reflects the state observed after polling completes; it may be in <see cref="VectorStoreStatus.Completed"/> (typical), <see cref="VectorStoreStatus.Expired"/>, or any other terminal status returned by the service. Only <see cref="VectorStoreStatus.InProgress"/> is polled.</returns>
+    /// <remarks>
+    /// <para>
+    /// File-upload semantics are best-effort: when one of the per-file uploads throws, this method
+    /// makes a best-effort attempt to delete the files it has already uploaded so they do not
+    /// accumulate as orphaned resources on the project, then rethrows the original exception. The
+    /// cleanup itself does not throw — its failures are silently ignored because the caller is
+    /// already receiving a more meaningful exception from the original upload failure.
+    /// </para>
+    /// <para>
+    /// Cancellation aborts the polling loop with an <see cref="OperationCanceledException"/>; any
+    /// already-uploaded files and the partially-created vector store remain on the project and are
+    /// the caller's responsibility to clean up. The same applies when the polling timeout elapses
+    /// (a <see cref="TimeoutException"/> is thrown instead).
+    /// </para>
+    /// </remarks>
+    /// <exception cref="ArgumentException"><paramref name="name"/> is <see langword="null"/> or whitespace, or <paramref name="filePaths"/> is <see langword="null"/>.</exception>
+    /// <exception cref="TimeoutException">The vector store did not leave <see cref="VectorStoreStatus.InProgress"/> within <paramref name="pollingTimeout"/>.</exception>
+    public async Task<VectorStore> CreateVectorStoreAsync(string name, IEnumerable<string> filePaths, TimeSpan? expiresAfter = null, TimeSpan? pollingTimeout = null, CancellationToken cancellationToken = default)
+    {
+        Throw.IfNullOrWhitespace(name);
+        Throw.IfNull(filePaths);
+
+        var fileIds = new List<string>();
+        try
+        {
+            foreach (var path in filePaths)
+            {
+                cancellationToken.ThrowIfCancellationRequested();
+                var uploaded = await this.UploadFileAsync(path, FileUploadPurpose.Assistants, cancellationToken).ConfigureAwait(false);
+                fileIds.Add(uploaded.Id);
+            }
+        }
+        catch
+        {
+            // Q-B: best-effort cleanup of files already uploaded before the mid-loop failure so
+            // they do not accumulate as orphaned resources on the project. Swallow cleanup
+            // exceptions — the caller is already going to see the original upload exception, and
+            // there is nothing useful we can do with a secondary delete failure.
+            await this.BestEffortDeleteFilesAsync(fileIds).ConfigureAwait(false);
+            throw;
+        }
+
+        var options = new VectorStoreCreationOptions
+        {
+            Name = name,
+        };
+        foreach (var id in fileIds)
+        {
+            options.FileIds.Add(id);
+        }
+        if (expiresAfter is { } window)
+        {
+            options.ExpirationPolicy = new VectorStoreExpirationPolicy(VectorStoreExpirationAnchor.LastActiveAt, (int)Math.Ceiling(window.TotalDays));
+        }
+
+        var vectorStoreClient = this.GetVectorStoreClient();
+        var createResult = await vectorStoreClient.CreateVectorStoreAsync(options, cancellationToken).ConfigureAwait(false);
+        var created = createResult.Value;
+
+        // Q-A: poll until the vector store leaves the in-progress state. Without this the helper
+        // hands the caller a vector store whose file ingestion may still be running, defeating
+        // the purpose of the one-call wrapper.
+        return await WaitForVectorStoreReadyAsync(vectorStoreClient, created, pollingTimeout ?? s_defaultPollingTimeout, cancellationToken).ConfigureAwait(false);
+    }
+
+    private async Task BestEffortDeleteFilesAsync(IEnumerable<string> fileIds)
+    {
+        foreach (var id in fileIds)
+        {
+            try
+            {
+                // Pass CancellationToken.None: cleanup runs in the catch path; the caller's
+                // token may already be cancelled and we still want to do our best to free
+                // orphaned resources before propagating the original exception.
+                await this.DeleteFileAsync(id, CancellationToken.None).ConfigureAwait(false);
+            }
+            catch
+            {
+                // Silently ignore cleanup failures; see XML doc on CreateVectorStoreAsync.
+            }
+        }
+    }
+
+    /// <summary>Upper bound on <see cref="WaitForVectorStoreReadyAsync"/> when the caller does not supply one. Chosen to comfortably cover normal Foundry vector-store ingestion (seconds to a minute for modest file sets) while still surfacing a clear failure if the server is stuck.</summary>
+    private static readonly TimeSpan s_defaultPollingTimeout = TimeSpan.FromMinutes(5);
+
+    private static async Task<VectorStore> WaitForVectorStoreReadyAsync(VectorStoreClient client, VectorStore initial, TimeSpan timeout, CancellationToken cancellationToken)
+    {
+        if (initial.Status != VectorStoreStatus.InProgress)
+        {
+            return initial;
+        }
+
+        var stopwatch = System.Diagnostics.Stopwatch.StartNew();
+        var delay = TimeSpan.FromMilliseconds(250);
+        var maxDelay = TimeSpan.FromSeconds(2);
+        var current = initial;
+        while (current.Status == VectorStoreStatus.InProgress)
+        {
+            if (timeout != Timeout.InfiniteTimeSpan && stopwatch.Elapsed >= timeout)
+            {
+                throw new TimeoutException(
+                    $"Vector store '{current.Id}' did not leave the in-progress state within {timeout.TotalSeconds:0.##} seconds.");
+            }
+
+            await Task.Delay(delay, cancellationToken).ConfigureAwait(false);
+            var refreshed = await client.GetVectorStoreAsync(current.Id, cancellationToken).ConfigureAwait(false);
+            current = refreshed.Value;
+
+            if (delay < maxDelay)
+            {
+                var next = TimeSpan.FromMilliseconds(delay.TotalMilliseconds * 2);
+                delay = next < maxDelay ? next : maxDelay;
+            }
+        }
+
+        return current;
+    }
+
+    /// <summary>Deletes a vector store. The associated files (if any) are not deleted by this method; call <see cref="DeleteFileAsync(string, CancellationToken)"/> separately to clean them up.</summary>
+    /// <param name="vectorStoreId">The vector store id.</param>
+    /// <param name="cancellationToken">A token that can cancel the delete.</param>
+    /// <returns>The deletion result.</returns>
+    /// <exception cref="ArgumentException"><paramref name="vectorStoreId"/> is <see langword="null"/> or whitespace.</exception>
+    public async Task<VectorStoreDeletionResult> DeleteVectorStoreAsync(string vectorStoreId, CancellationToken cancellationToken = default)
+    {
+        Throw.IfNullOrWhitespace(vectorStoreId);
+        var vectorStoreClient = this.GetVectorStoreClient();
+        var result = await vectorStoreClient.DeleteVectorStoreAsync(vectorStoreId, cancellationToken).ConfigureAwait(false);
+        return result.Value;
+    }
+
+    private OpenAIFileClient GetOpenAIFileClient()
+    {
+        var projectClient = this._aiProjectClient
+            ?? throw new InvalidOperationException("This FoundryChatClient does not have an AIProjectClient available. File and vector-store helpers require an AIProjectClient.");
+        return projectClient.GetProjectOpenAIClient().GetOpenAIFileClient();
+    }
+
+    private VectorStoreClient GetVectorStoreClient()
+    {
+        var projectClient = this._aiProjectClient
+            ?? throw new InvalidOperationException("This FoundryChatClient does not have an AIProjectClient available. File and vector-store helpers require an AIProjectClient.");
+        return projectClient.GetProjectOpenAIClient().GetVectorStoreClient();
+    }
+
+    #endregion
+
+    /// <summary>
+    /// Parses an agent endpoint URI of shape
+    /// <c>https://&lt;host&gt;/.../projects/&lt;project&gt;/agents/&lt;agentName&gt;/endpoint/protocols/openai</c>
+    /// and returns the agent name and the derived project-root URI.
+    /// </summary>
+    /// <remarks>
+    /// Tolerates trailing slash, casing variants on <c>/agents/</c> and the suffix segment, and
+    /// strips query string and fragment. Throws <see cref="ArgumentException"/> for inputs that
+    /// do not match the expected shape.
+    /// </remarks>
+    /// <exception cref="ArgumentException">
+    /// The endpoint is missing the <c>/agents/</c> segment, has an empty agent name, or has a
+    /// suffix other than <c>/endpoint/protocols/openai</c>.
+    /// </exception>
+    internal static (string AgentName, Uri ProjectRoot) ParseAgentEndpoint(Uri agentEndpoint)
+    {
+        Throw.IfNull(agentEndpoint);
+
+        const string AgentsSegment = "/agents/";
+        const string ExpectedSuffix = "/endpoint/protocols/openai";
+
+        var path = agentEndpoint.AbsolutePath.TrimEnd('/');
+        var idx = path.IndexOf(AgentsSegment, StringComparison.OrdinalIgnoreCase);
+        if (idx < 0)
+        {
+            throw new ArgumentException(
+                $"Expected an agent endpoint of shape 'https://<host>/.../projects/<project>/agents/<agentName>/endpoint/protocols/openai' but got '{agentEndpoint}'. " +
+                "If you want to construct a FoundryAgent against a project endpoint, use the (Uri projectEndpoint, AuthenticationTokenProvider credential, string model, string instructions, ...) constructor instead.",
+                nameof(agentEndpoint));
+        }
+
+        var afterAgents = path.Substring(idx + AgentsSegment.Length);
+        var nextSlash = afterAgents.IndexOf('/');
+        if (nextSlash <= 0)
+        {
+            throw new ArgumentException(
+                $"Agent endpoint '{agentEndpoint}' is missing the '<agentName>{ExpectedSuffix}' suffix.",
+                nameof(agentEndpoint));
+        }
+
+        var agentName = afterAgents.Substring(0, nextSlash);
+        var suffix = afterAgents.Substring(nextSlash);
+        if (!string.Equals(suffix, ExpectedSuffix, StringComparison.OrdinalIgnoreCase))
+        {
+            throw new ArgumentException(
+                $"Agent endpoint '{agentEndpoint}' has an unexpected suffix '{suffix}'. Expected '{ExpectedSuffix}'.",
+                nameof(agentEndpoint));
+        }
+
+        var rootPath = path.Substring(0, idx);
+        var projectRoot = new UriBuilder(agentEndpoint)
+        {
+            Path = rootPath,
+            Query = string.Empty,
+            Fragment = string.Empty,
+        }.Uri;
+
+        return (agentName, projectRoot);
+    }
+
+    private ChatOptions GetAgentEnabledChatOptions(ChatOptions? options)
+    {
+        // Start with a clone of the base chat options defined for the agent, if any.
+        ChatOptions agentEnabledChatOptions = this._baseChatOptions?.Clone() ?? new();
+
+        // Ignore per-request all options that can't be overridden.
+        agentEnabledChatOptions.Instructions = null;
+        agentEnabledChatOptions.Tools = null;
+        agentEnabledChatOptions.Temperature = null;
+        agentEnabledChatOptions.TopP = null;
+        agentEnabledChatOptions.PresencePenalty = null;
+        agentEnabledChatOptions.ResponseFormat = null;
+
+        // Use the conversation from the request, or the one defined at the client level.
+        agentEnabledChatOptions.ConversationId = options?.ConversationId ?? this._baseChatOptions?.ConversationId;
+
+        // Preserve the original RawRepresentationFactory.
+        var originalFactory = options?.RawRepresentationFactory;
+
+        agentEnabledChatOptions.RawRepresentationFactory = (client) =>
+        {
+            if (originalFactory?.Invoke(this) is not CreateResponseOptions responseCreationOptions)
+            {
+                responseCreationOptions = new CreateResponseOptions();
+            }
+
+            responseCreationOptions.Agent = this._agentReference;
+#pragma warning disable SCME0001 // Type is for evaluation purposes only and is subject to change or removal in future updates.
+            responseCreationOptions.Patch.Remove("$.model"u8);
+#pragma warning restore SCME0001
+
+            return responseCreationOptions;
+        };
+
+        return agentEnabledChatOptions;
+    }
+
+    private static AgentReference CreateAgentReference(ProjectsAgentVersion agentVersion)
+    {
+        // If the version is null, empty, or whitespace, use "latest" as the default. This handles
+        // cases where hosted agents (like MCP agents) may not have a version assigned.
+        var version = string.IsNullOrWhiteSpace(agentVersion.Version) ? "latest" : agentVersion.Version;
+        return new AgentReference(agentVersion.Name, version);
+    }
+
+    private static AgentEndpointInner BuildAgentEndpointInner(
+        Uri agentEndpoint,
+        AuthenticationTokenProvider credential,
+        ProjectOpenAIClientOptions? clientOptions)
+    {
+        Throw.IfNull(agentEndpoint);
+        Throw.IfNull(credential);
+
+        var (agentName, projectRoot) = ParseAgentEndpoint(agentEndpoint);
+
+        var perAgentOptions = clientOptions ?? new ProjectOpenAIClientOptions();
+        perAgentOptions.Endpoint = agentEndpoint;
+        perAgentOptions.AgentName = agentName;
+
+        var authPolicy = new BearerTokenPolicy(credential, AzureAiResourceScope);
+        var perAgentClient = new ProjectOpenAIClient(authPolicy, perAgentOptions);
+
+        var chatClient = perAgentClient.GetProjectResponsesClient().AsIChatClient();
+
+        // Materialize a project-level AIProjectClient from the parsed project root so
+        // GetService<AIProjectClient>() returns non-null for all FoundryChatClient
+        // construction modes. Project-level helpers (file upload, vector store create/delete)
+        // depend on this. RBAC for those calls is at the project level; if the supplied
+        // credential lacks project-scope permissions, the SDK surfaces a clean 401/403 at
+        // call time. The four observable primitive ClientPipelineOptions properties are
+        // propagated from the caller's per-agent options bag so test-injected transports and
+        // explicit RetryPolicy / NetworkTimeout / UserAgentApplicationId reach the
+        // project-level pipeline. Pipeline policies added via AddPolicy on the caller bag are
+        // NOT propagated because ClientPipelineOptions does not publicly enumerate policies.
+        var aiProjectClientOptions = new AIProjectClientOptions();
+        if (clientOptions is not null)
+        {
+            if (clientOptions.RetryPolicy is not null)
+            {
+                aiProjectClientOptions.RetryPolicy = clientOptions.RetryPolicy;
+            }
+            if (clientOptions.NetworkTimeout is not null)
+            {
+                aiProjectClientOptions.NetworkTimeout = clientOptions.NetworkTimeout;
+            }
+            if (clientOptions.Transport is not null)
+            {
+                aiProjectClientOptions.Transport = clientOptions.Transport;
+            }
+            if (!string.IsNullOrEmpty(clientOptions.UserAgentApplicationId))
+            {
+                aiProjectClientOptions.UserAgentApplicationId = clientOptions.UserAgentApplicationId;
+            }
+        }
+        var aiProjectClient = new AIProjectClient(projectRoot, credential, aiProjectClientOptions);
+
+        return new AgentEndpointInner(chatClient, aiProjectClient, agentName);
+    }
+
+    private static AgentEndpointInner BuildAgentEndpointInnerFromProjectClient(
+        AIProjectClient aiProjectClient,
+        Uri agentEndpoint,
+        ProjectOpenAIClientOptions? clientOptions)
+    {
+        Throw.IfNull(aiProjectClient);
+        Throw.IfNull(agentEndpoint);
+
+        var (agentName, _) = ParseAgentEndpoint(agentEndpoint);
+
+        var perAgentOptions = clientOptions ?? new ProjectOpenAIClientOptions();
+        perAgentOptions.Endpoint = agentEndpoint;
+        perAgentOptions.AgentName = agentName;
+
+        var chatClient = aiProjectClient.GetProjectOpenAIClient()
+            .GetProjectResponsesClientForAgentEndpoint(agentName, options: perAgentOptions)
+            .AsIChatClient();
+
+        // Reuse the caller's AIProjectClient verbatim — no new pipeline is materialized.
+        return new AgentEndpointInner(chatClient, aiProjectClient, agentName);
+    }
+
+    /// <summary>Best-effort registration of <see cref="AgentFrameworkUserAgentPolicy"/> via the MEAI <see cref="OpenAIRequestPolicies"/> hook with at-most-once dedup per pipeline.</summary>
+    private static void TryRegisterAgentFrameworkUserAgentPolicy(IChatClient? innerClient)
+    {
+        if (innerClient?.GetService<OpenAIRequestPolicies>() is { } policies)
+        {
+            // OpenAIRequestPoliciesReflection.AddPolicyIfMissing performs a check-then-add against
+            // the private _entries collection on the OpenAIRequestPolicies instance, so the
+            // policy is registered at most once even when many FoundryChatClient instances share
+            // the same underlying chat client.
+            OpenAIRequestPoliciesReflection.AddPolicyIfMissing(
+                policies,
+                AgentFrameworkUserAgentPolicy.Instance,
+                PipelinePosition.PerCall);
+        }
+    }
+
+    /// <summary>
+    /// Best-effort registration of <see cref="ServedModelPolicy"/> via the MEAI
+    /// <see cref="OpenAIRequestPolicies"/> hook. The policy captures the
+    /// <c>x-ms-served-model</c> response header from Azure OpenAI and writes it into
+    /// <see cref="ServedModelScope"/> so the <see cref="GetResponseAsync"/> and
+    /// <see cref="GetStreamingResponseAsync"/> overrides can overwrite
+    /// <see cref="ChatResponse.ModelId"/> with the actual model snapshot.
+    /// </summary>
+    private static void TryRegisterServedModelPolicy(IChatClient? innerClient)
+    {
+        if (innerClient?.GetService<OpenAIRequestPolicies>() is { } policies)
+        {
+            OpenAIRequestPoliciesReflection.AddPolicyIfMissing(
+                policies,
+                ServedModelPolicy.Instance,
+                PipelinePosition.PerCall);
+        }
+    }
+
+    /// <summary>Default OAuth scope for the Azure AI resource. Matches the scope used by <c>Azure.AI.Extensions.OpenAI</c>'s internal authentication helper so the bearer token is accepted by the Foundry control plane.</summary>
+    private const string AzureAiResourceScope = "https://ai.azure.com/.default";
+
+    private readonly struct AgentEndpointInner
+    {
+        public AgentEndpointInner(IChatClient chatClient, AIProjectClient aiProjectClient, string agentName)
+        {
+            this.ChatClient = chatClient;
+            this.AIProjectClient = aiProjectClient;
+            this.AgentName = agentName;
+        }
+
+        public IChatClient ChatClient { get; }
+        public AIProjectClient AIProjectClient { get; }
+        public string AgentName { get; }
+    }
+}
@@ -0,0 +1,150 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+using System.Threading;
+using System.Threading.Tasks;
+using Azure.AI.Extensions.OpenAI;
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+using OpenAI.Responses;
+
+#pragma warning disable OPENAI001
+
+namespace Microsoft.Agents.AI.Foundry;
+
+/// <summary>
+/// Shared internal implementation behind the public <c>ToPromptAgentAsync</c> extension methods
+/// on <see cref="ChatClientAgent"/> and <see cref="FoundryAgent"/>. Converts a Foundry-backed
+/// agent into a <see cref="ProjectsAgentDefinition"/> ready to publish via
+/// <see cref="AgentAdministrationClient"/>.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Dispatch by <see cref="FoundryChatClient"/> construction mode (reachable via
+/// <see cref="IChatClient.GetService(Type, object?)"/>):
+/// </para>
+/// <list type="bullet">
+/// <item><description><b>Responses Agent (Mode 1)</b>: synthesize a <see cref="DeclarativeAgentDefinition"/> from the agent's <see cref="ChatOptions"/>.</description></item>
+/// <item><description><b>Prompt Agent (Mode 2, cached version)</b>: return the cached <see cref="ProjectsAgentVersion.Definition"/>.</description></item>
+/// <item><description><b>Prompt Agent (Mode 2, AgentReference-only)</b>: fetch the latest version from the service and return its definition.</description></item>
+/// <item><description><b>Agent Endpoint (Mode 3)</b>: throw — no local definition exists to convert.</description></item>
+/// </list>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
+internal static class FoundryPromptAgentConverter
+{
+    /// <summary>Performs the conversion for an agent whose chat client and chat options are supplied.</summary>
+    /// <param name="chatClient">The chat client extracted from the calling agent (must surface a <see cref="FoundryChatClient"/> via <see cref="IChatClient.GetService(Type, object?)"/>).</param>
+    /// <param name="chatOptions">The agent's chat options (model id, instructions, temperature, top-p, tools). Required for the Responses Agent mode; ignored for the Prompt Agent mode.</param>
+    /// <param name="cancellationToken">A token that can cancel a server-side fetch (Prompt Agent AgentReference path).</param>
+    /// <returns>A <see cref="ProjectsAgentDefinition"/> suitable for <c>AgentAdministrationClient.CreateAgentVersionAsync</c>.</returns>
+    /// <exception cref="InvalidOperationException">Thrown when the chat client is not Foundry-backed, the agent was constructed via the Agent Endpoint mode, no model id is set for the Responses Agent mode, or an unsupported <see cref="AITool"/> is encountered.</exception>
+    public static async Task<ProjectsAgentDefinition> ConvertAsync(IChatClient chatClient, ChatOptions? chatOptions, CancellationToken cancellationToken)
+    {
+        Throw.IfNull(chatClient);
+
+        var foundryChatClient = chatClient.GetService<FoundryChatClient>()
+            ?? throw new InvalidOperationException(
+                "ToPromptAgentAsync requires a FoundryChatClient-backed agent. " +
+                "The supplied agent's chat client does not expose a FoundryChatClient via GetService<FoundryChatClient>().");
+
+        // Prompt Agent (Mode 2) with a cached server-side version (constructed via ProjectsAgentVersion or ProjectsAgentRecord).
+        if (foundryChatClient.GetService<ProjectsAgentVersion>() is { } cachedVersion)
+        {
+            return cachedVersion.Definition;
+        }
+
+        // Prompt Agent (Mode 2) AgentReference-only: fetch the agent definition from the service.
+        // Honor a pinned AgentReference.Version when present (Q-C fix); fall back to the latest
+        // version only when the reference is unpinned ("", null, or "latest").
+        if (foundryChatClient.GetService<AgentReference>() is { } agentReference)
+        {
+            var aiProjectClient = foundryChatClient.GetService<AIProjectClient>()
+                ?? throw new InvalidOperationException(
+                    "Cannot fetch the agent version because the FoundryChatClient does not expose an AIProjectClient.");
+
+            if (!string.IsNullOrWhiteSpace(agentReference.Version)
+                && !string.Equals(agentReference.Version, "latest", StringComparison.OrdinalIgnoreCase))
+            {
+                var pinnedVersion = await aiProjectClient.AgentAdministrationClient
+                    .GetAgentVersionAsync(agentReference.Name, agentReference.Version, cancellationToken)
+                    .ConfigureAwait(false);
+                return pinnedVersion.Value.Definition;
+            }
+
+            var record = await aiProjectClient.AgentAdministrationClient
+                .GetAgentAsync(agentReference.Name, cancellationToken)
+                .ConfigureAwait(false);
+            return record.Value.GetLatestVersion().Definition;
+        }
+
+        // Agent Endpoint (Mode 3): AgentName is set (parsed from URL) but no AgentReference exists
+        // locally. The agent definition lives only on the server and is not retrievable through this
+        // chat client, so conversion is not supported here.
+        if (foundryChatClient.AgentName is not null)
+        {
+            throw new InvalidOperationException(
+                "ToPromptAgentAsync is not supported for agents constructed via the Agent Endpoint mode (Mode 3); " +
+                "no local definition exists to convert.");
+        }
+
+        // Responses Agent (Mode 1): synthesize from ChatOptions.
+        return SynthesizeFromChatOptions(chatOptions);
+    }
+
+    private static DeclarativeAgentDefinition SynthesizeFromChatOptions(ChatOptions? chatOptions)
+    {
+        if (chatOptions is null || string.IsNullOrWhiteSpace(chatOptions.ModelId))
+        {
+            throw new InvalidOperationException(
+                "ToPromptAgentAsync requires a model id on the agent's ChatOptions to synthesize a prompt agent definition.");
+        }
+
+        var definition = new DeclarativeAgentDefinition(chatOptions.ModelId!)
+        {
+            Instructions = chatOptions.Instructions,
+            Temperature = chatOptions.Temperature,
+            TopP = chatOptions.TopP,
+        };
+
+        if (chatOptions.Tools is { Count: > 0 } tools)
+        {
+            foreach (var tool in tools)
+            {
+                definition.Tools.Add(ConvertTool(tool));
+            }
+        }
+
+        return definition;
+    }
+
+    private static ResponseTool ConvertTool(AITool tool)
+    {
+        Throw.IfNull(tool);
+
+        if (tool is AIFunction function)
+        {
+            // strictModeEnabled is intentionally true to match the Python spec's
+            // default behavior. JsonSchema on AIFunction is a JsonElement; serialize via its
+            // string form so the payload matches what callers pass elsewhere in this codebase.
+            return ResponseTool.CreateFunctionTool(
+                function.Name,
+                BinaryData.FromString(function.JsonSchema.ToString() ?? "{}"),
+                strictModeEnabled: true,
+                function.Description);
+        }
+
+        if (tool.GetService(typeof(ResponseTool)) is ResponseTool responseTool)
+        {
+            return responseTool;
+        }
+
+        throw new InvalidOperationException(
+            $"Cannot convert AITool of type '{tool.GetType().Name}' to a ResponseTool. " +
+            "Only AIFunction and AITool instances that wrap a ResponseTool (such as those produced by FoundryAITool factories) are supported.");
+    }
+}
@@ -1,58 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using System.ClientModel.Primitives;
-using System.Collections.Generic;
-using System.Reflection;
-using System.Threading.Tasks;
-
-namespace Microsoft.Agents.AI;
-
-internal static class RequestOptionsExtensions
-{
-    /// <summary>Gets the singleton <see cref="PipelinePolicy"/> that adds a MEAI user-agent header.</summary>
-    internal static PipelinePolicy UserAgentPolicy => MeaiUserAgentPolicy.Instance;
-
-    /// <summary>Provides a pipeline policy that adds a "MEAI/x.y.z" user-agent header.</summary>
-    private sealed class MeaiUserAgentPolicy : PipelinePolicy
-    {
-        public static MeaiUserAgentPolicy Instance { get; } = new MeaiUserAgentPolicy();
-
-        private static readonly string s_userAgentValue = CreateUserAgentValue();
-
-        public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
-        {
-            AddUserAgentHeader(message);
-            ProcessNext(message, pipeline, currentIndex);
-        }
-
-        public override ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
-        {
-            AddUserAgentHeader(message);
-            return ProcessNextAsync(message, pipeline, currentIndex);
-        }
-
-        private static void AddUserAgentHeader(PipelineMessage message) =>
-            message.Request.Headers.Add("User-Agent", s_userAgentValue);
-
-        private static string CreateUserAgentValue()
-        {
-            const string Name = "MEAI";
-
-            if (typeof(MeaiUserAgentPolicy).Assembly.GetCustomAttribute<AssemblyInformationalVersionAttribute>()?.InformationalVersion is string version)
-            {
-                int pos = version.IndexOf('+');
-                if (pos >= 0)
-                {
-                    version = version.Substring(0, pos);
-                }
-
-                if (version.Length > 0)
-                {
-                    return $"{Name}/{version}";
-                }
-            }
-
-            return Name;
-        }
-    }
-}
@@ -0,0 +1,67 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ClientModel.Primitives;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+
+namespace Microsoft.Agents.AI.Foundry;
+
+/// <summary>
+/// Pipeline policy that captures the <c>x-ms-served-model</c> response header from Azure OpenAI
+/// and stores it in <see cref="ServedModelScope"/> for consumption by <see cref="FoundryChatClient"/>.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Azure OpenAI Responses API returns the deployment alias in <c>response.model</c> but the actual
+/// model snapshot (e.g. <c>gpt-5-nano-2025-08-07</c>) in the <c>x-ms-served-model</c> response header.
+/// This policy extracts the header after the HTTP roundtrip so the <see cref="FoundryChatClient"/>
+/// can overwrite <c>ChatResponse.ModelId</c> with the true model name.
+/// </para>
+/// <para>
+/// Registered once per <c>OpenAIRequestPolicies</c> instance via the MEAI 10.5.1 extension hook.
+/// When the header is absent (non-Azure endpoints), the scope is not set and the
+/// <see cref="FoundryChatClient"/> preserves the original model name.
+/// </para>
+/// </remarks>
+internal sealed class ServedModelPolicy : PipelinePolicy
+{
+    /// <summary>The Azure OpenAI response header that carries the actual served model name.</summary>
+    internal const string ServedModelHeader = "x-ms-served-model";
+
+    public static ServedModelPolicy Instance { get; } = new ServedModelPolicy();
+
+    private ServedModelPolicy()
+    {
+    }
+
+    public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+    {
+        ProcessNext(message, pipeline, currentIndex);
+        CaptureServedModel(message);
+    }
+
+    public override async ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+    {
+        await ProcessNextAsync(message, pipeline, currentIndex).ConfigureAwait(false);
+        CaptureServedModel(message);
+    }
+
+    private static void CaptureServedModel(PipelineMessage message)
+    {
+        if (message.Response is null)
+        {
+            return;
+        }
+
+        if (message.Response.Headers.TryGetValue(ServedModelHeader, out string? servedModel)
+            && !string.IsNullOrWhiteSpace(servedModel))
+        {
+            // Write into the box (reference-type mutation) so the value is visible to the
+            // FoundryChatClient that pushed the box before calling the inner client.
+            if (ServedModelScope.Current is { } box)
+            {
+                box.Value = servedModel.Trim();
+            }
+        }
+    }
+}
@@ -0,0 +1,35 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Runtime.CompilerServices;
+using System.Threading;
+
+namespace Microsoft.Agents.AI.Foundry;
+
+/// <summary>
+/// AsyncLocal carrier that bridges the <c>x-ms-served-model</c> response header value from the
+/// <see cref="ServedModelPolicy"/> running inside the SCM transport pipeline up to the
+/// <see cref="FoundryChatClient"/> decorator.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Because <see cref="AsyncLocal{T}"/> mutations inside a child <c>async</c> method do not propagate
+/// back to the caller (copy-on-write semantics), this scope uses <see cref="StrongBox{T}"/> as an
+/// indirection layer. The <see cref="FoundryChatClient"/> pushes a fresh box onto the scope
+/// before calling the inner client; the <see cref="ServedModelPolicy"/> writes into the box's
+/// <see cref="StrongBox{T}.Value"/> (a reference-type mutation visible to anyone holding the same box).
+/// After the inner call returns, the client reads the box's value.
+/// </para>
+/// </remarks>
+internal static class ServedModelScope
+{
+    private static readonly AsyncLocal<StrongBox<string?>?> s_current = new();
+
+    /// <summary>
+    /// Gets or sets the per-async-flow served model box.
+    /// </summary>
+    public static StrongBox<string?>? Current
+    {
+        get => s_current.Value;
+        set => s_current.Value = value;
+    }
+}
@@ -4,7 +4,11 @@ using System;
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
 using System.IO;
+using System.Linq;
 using Microsoft.Agents.AI.Compaction;
+#if NET
+using Microsoft.Agents.AI.Tools.Shell;
+#endif
 using Microsoft.Extensions.AI;
 using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
@@ -200,6 +204,14 @@ public sealed class HarnessAgent : DelegatingAIAgent
            result.Tools.Add(new HostedWebSearchTool());
        }

+#if NET
+        if (options?.ShellExecutor is ShellExecutor shellExecutor)
+        {
+            result.Tools ??= [];
+            result.Tools.Add(shellExecutor.AsAIFunction());
+        }
+#endif
+
        return result;
    }

@@ -249,6 +261,22 @@ public sealed class HarnessAgent : DelegatingAIAgent
            providers.Add(skillsProvider);
        }

+        if (options?.BackgroundAgents is IEnumerable<AIAgent> backgroundAgents)
+        {
+            var materializedAgents = backgroundAgents.ToList();
+            if (materializedAgents.Count > 0)
+            {
+                providers.Add(new BackgroundAgentsProvider(materializedAgents, options.BackgroundAgentsProviderOptions));
+            }
+        }
+
+#if NET
+        if (options?.ShellExecutor is ShellExecutor shellExecutor)
+        {
+            providers.Add(new ShellEnvironmentProvider(shellExecutor, options.ShellEnvironmentProviderOptions));
+        }
+#endif
+
        if (options?.AIContextProviders is IEnumerable<AIContextProvider> userProviders)
        {
            providers.AddRange(userProviders);
@@ -2,6 +2,9 @@

 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
+#if NET
+using Microsoft.Agents.AI.Tools.Shell;
+#endif
 using Microsoft.Extensions.AI;
 using Microsoft.Shared.DiagnosticIds;

@@ -218,4 +221,49 @@ public sealed class HarnessAgentOptions
    /// This property is ignored when <see cref="DisableOpenTelemetry"/> is <see langword="true"/>.
    /// </remarks>
    public string? OpenTelemetrySourceName { get; set; }
+
+    /// <summary>
+    /// Gets or sets the collection of background agents available for delegation via <see cref="BackgroundAgentsProvider"/>.
+    /// </summary>
+    /// <remarks>
+    /// When non-null and non-empty, a <see cref="BackgroundAgentsProvider"/> is automatically included in the
+    /// agent's context providers, enabling the agent to start, monitor, and retrieve results from background tasks.
+    /// When <see langword="null"/> or empty, no <see cref="BackgroundAgentsProvider"/> is configured.
+    /// Each agent in the collection must have a non-empty <see cref="AIAgent.Name"/> and names must be unique
+    /// (case-insensitive). If these requirements are not met, <see cref="BackgroundAgentsProvider"/> will throw
+    /// an <see cref="System.ArgumentException"/> during construction.
+    /// </remarks>
+    public IEnumerable<AIAgent>? BackgroundAgents { get; set; }
+
+    /// <summary>
+    /// Gets or sets optional configuration for the <see cref="BackgroundAgentsProvider"/>.
+    /// </summary>
+    /// <remarks>
+    /// Use this to customize instructions or agent list formatting for the background agents feature.
+    /// This property is ignored when <see cref="BackgroundAgents"/> is <see langword="null"/> or empty.
+    /// </remarks>
+    public BackgroundAgentsProviderOptions? BackgroundAgentsProviderOptions { get; set; }
+
+#if NET
+    /// <summary>
+    /// Gets or sets the shell executor used to enable shell tool and environment probing via <see cref="ShellEnvironmentProvider"/>.
+    /// </summary>
+    /// <remarks>
+    /// When non-null, a <see cref="ShellEnvironmentProvider"/> is automatically included in the agent's context
+    /// providers (injecting OS/shell/CWD information into the system prompt), and the executor's
+    /// <see cref="ShellExecutor.AsAIFunction"/> is registered as a callable tool.
+    /// When <see langword="null"/> (the default), no shell features are enabled.
+    /// </remarks>
+    public ShellExecutor? ShellExecutor { get; set; }
+
+    /// <summary>
+    /// Gets or sets optional configuration for the <see cref="ShellEnvironmentProvider"/>.
+    /// </summary>
+    /// <remarks>
+    /// Use this to customize which tools are probed, the probe timeout, shell family override,
+    /// or the instructions formatter.
+    /// This property is ignored when <see cref="ShellExecutor"/> is <see langword="null"/>.
+    /// </remarks>
+    public ShellEnvironmentProviderOptions? ShellEnvironmentProviderOptions { get; set; }
+#endif
 }
@@ -15,6 +15,10 @@
    <ProjectReference Include="..\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
  </ItemGroup>

+  <ItemGroup Condition="$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net8.0'))">
+    <ProjectReference Include="..\Microsoft.Agents.AI.Tools.Shell\Microsoft.Agents.AI.Tools.Shell.csproj" />
+  </ItemGroup>
+
  <PropertyGroup>
    <!-- NuGet Package Settings -->
    <Title>Microsoft Agent Framework Harness</Title>
@@ -0,0 +1,61 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.Diagnostics;
+using ModelContextProtocol.Client;
+using ModelContextProtocol.Protocol;
+
+namespace Microsoft.Agents.AI.Mcp;
+
+/// <summary>
+/// Extension methods on <see cref="McpClient"/> that expose MCP server tools to a Microsoft
+/// Agent Framework agent with optional long-running task (SEP-2663) handling.
+/// </summary>
+public static class McpClientTaskExtensions
+{
+    /// <summary>
+    /// Lists tools advertised by the connected MCP server and returns each as an
+    /// <see cref="AIFunction"/>. Tools that declare <see cref="ToolTaskSupport.Required"/>
+    /// are wrapped with task-aware behavior so an agent can transparently drive long-running
+    /// invocations. All other tools — including those that declare
+    /// <see cref="ToolTaskSupport.Optional"/> — are returned as-is, preserving inline
+    /// (synchronous) invocation semantics by default.
+    /// </summary>
+    /// <param name="client">The connected MCP client.</param>
+    /// <param name="options">
+    /// Options that control the task lifecycle for task-capable tools.
+    /// When <see langword="null"/>, defaults described on <see cref="McpTaskOptions"/> apply.
+    /// </param>
+    /// <param name="cancellationToken">Token used to cancel listing the server's tools.</param>
+    /// <returns>The tools, ready to pass to <c>AsAIAgent(tools: …)</c>.</returns>
+    public static async Task<IReadOnlyList<AIFunction>> ListAgentToolsWithTaskSupportAsync(
+        this McpClient client,
+        McpTaskOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        _ = Throw.IfNull(client);
+
+        McpTaskOptions effectiveOptions = options ?? new McpTaskOptions();
+
+        IList<McpClientTool> tools = await client.ListToolsAsync(cancellationToken: cancellationToken).ConfigureAwait(false);
+
+        AIFunction[] result = new AIFunction[tools.Count];
+        for (int i = 0; i < tools.Count; i++)
+        {
+            ToolTaskSupport? taskSupport = tools[i].ProtocolTool.Execution?.TaskSupport;
+            if (taskSupport is ToolTaskSupport.Required)
+            {
+                result[i] = new TaskAwareMcpClientAIFunction(client, tools[i], effectiveOptions);
+            }
+            else
+            {
+                result[i] = tools[i];
+            }
+        }
+
+        return result;
+    }
+}
@@ -0,0 +1,39 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+
+namespace Microsoft.Agents.AI.Mcp;
+
+/// <summary>
+/// Configures how an MCP client wrapper drives the
+/// <see href="https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks">MCP tasks</see>
+/// lifecycle when an underlying server tool returns a <c>CreateTaskResult</c>.
+/// </summary>
+/// <remarks>
+/// <para>
+/// All members of this type are subject to change. The MCP task surface is experimental
+/// and tracks the in-flight specification.
+/// </para>
+/// </remarks>
+public sealed class McpTaskOptions
+{
+    /// <summary>
+    /// Gets or sets the time-to-live the wrapper attaches to a newly created server-side task.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="null"/> the wrapper omits the <c>ttl</c> hint and lets the server
+    /// pick its own value. The server's chosen TTL is always authoritative.
+    /// </remarks>
+    public TimeSpan? DefaultTimeToLive { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the wrapper should send
+    /// <c>tasks/cancel</c> when the local <see cref="System.Threading.CancellationToken"/>
+    /// fires during a tool invocation.
+    /// </summary>
+    /// <remarks>
+    /// Defaults to <see langword="true"/>: a local cancellation means "the caller is giving up
+    /// on this tool invocation" and the server-side task has no further consumer.
+    /// </remarks>
+    public bool CancelRemoteTaskOnLocalCancellation { get; set; } = true;
+}
@@ -0,0 +1,37 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFrameworks>$(TargetFrameworksCore)</TargetFrameworks>
+    <RootNamespace>Microsoft.Agents.AI.Mcp</RootNamespace>
+    <VersionSuffix>alpha</VersionSuffix>
+    <NoWarn>$(NoWarn);MEAI001;MCPEXP001</NoWarn>
+  </PropertyGroup>
+
+  <Import Project="$(RepoRoot)/dotnet/nuget/nuget-package.props" />
+
+  <PropertyGroup>
+    <InjectSharedThrow>true</InjectSharedThrow>
+    <InjectTrimAttributesOnLegacy>true</InjectTrimAttributesOnLegacy>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <Title>Microsoft Agent Framework MCP</Title>
+    <Description>Provides Microsoft Agent Framework support for Model Context Protocol (MCP), including long-running task (SEP-2663) integration for MCP clients.</Description>
+  </PropertyGroup>
+
+  <!-- Disable package validation baseline until the first release -->
+  <PropertyGroup>
+    <PackageValidationBaselineVersion />
+    <EnablePackageValidation>false</EnablePackageValidation>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.AI" />
+    <PackageReference Include="ModelContextProtocol" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <InternalsVisibleTo Include="Microsoft.Agents.AI.Mcp.UnitTests" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,147 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Text.Json;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.Diagnostics;
+using ModelContextProtocol;
+using ModelContextProtocol.Client;
+using ModelContextProtocol.Protocol;
+
+namespace Microsoft.Agents.AI.Mcp;
+
+/// <summary>
+/// An <see cref="AIFunction"/> wrapper around an <see cref="McpClientTool"/> that drives the
+/// <see href="https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks">MCP long-running task</see>
+/// lifecycle (SEP-2663) on behalf of the agent's tool loop.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The wrapper invokes the tool with task augmentation via
+/// <see cref="McpClient.CallToolAsTaskAsync"/>, polls to completion via
+/// <see cref="McpClient.PollTaskUntilCompleteAsync"/>, and fetches the result via
+/// <see cref="McpClient.GetTaskResultAsync"/>. The result is returned to the caller as a
+/// <see cref="JsonElement"/> containing the serialized <see cref="CallToolResult"/> — the
+/// same wire shape produced by <see cref="McpClientTool"/>.<see cref="AIFunction.InvokeAsync(AIFunctionArguments, CancellationToken)"/>
+/// so that downstream <see cref="FunctionResultContent"/> serialization is byte-identical to
+/// a non-task-augmented MCP tool call. The agent's function-calling loop is unaware that a
+/// task was used.
+/// </para>
+/// <para>
+/// This wrapper is intended to be applied only to tools whose
+/// <see cref="ToolExecution.TaskSupport"/> is <see cref="ToolTaskSupport.Required"/>
+/// (selected by <see cref="McpClientTaskExtensions.ListAgentToolsWithTaskSupportAsync"/>).
+/// As a defensive fallback, if the server still rejects the task-augmented call with
+/// <see cref="McpErrorCode.MethodNotFound"/> (e.g. because tool-level capabilities changed
+/// between <c>tools/list</c> and invocation), the wrapper transparently falls back to a
+/// non-augmented call through the inner <see cref="McpClientTool"/>.
+/// </para>
+/// </remarks>
+internal sealed class TaskAwareMcpClientAIFunction : AIFunction
+{
+    private readonly McpClient _client;
+    private readonly McpClientTool _inner;
+    private readonly McpTaskOptions _options;
+
+    internal TaskAwareMcpClientAIFunction(McpClient client, McpClientTool inner, McpTaskOptions options)
+    {
+        _ = Throw.IfNull(client);
+        _ = Throw.IfNull(inner);
+        _ = Throw.IfNull(options);
+
+        this._client = client;
+        this._inner = inner;
+        this._options = options;
+    }
+
+    /// <inheritdoc />
+    public override string Name => this._inner.Name;
+
+    /// <inheritdoc />
+    public override string Description => this._inner.Description;
+
+    /// <inheritdoc />
+    public override JsonElement JsonSchema => this._inner.JsonSchema;
+
+    /// <inheritdoc />
+    public override JsonElement? ReturnJsonSchema => this._inner.ReturnJsonSchema;
+
+    /// <inheritdoc />
+    public override JsonSerializerOptions JsonSerializerOptions => this._inner.JsonSerializerOptions;
+
+    /// <inheritdoc />
+    protected override async ValueTask<object?> InvokeCoreAsync(
+        AIFunctionArguments arguments,
+        CancellationToken cancellationToken)
+    {
+        _ = Throw.IfNull(arguments);
+
+        McpTaskMetadata? metadata = null;
+        if (this._options.DefaultTimeToLive is TimeSpan ttl)
+        {
+            metadata = new McpTaskMetadata { TimeToLive = ttl };
+        }
+
+        McpTask task;
+        try
+        {
+            task = await this._client.CallToolAsTaskAsync(
+                this._inner.Name,
+                arguments,
+                taskMetadata: metadata,
+                progress: null,
+                options: null,
+                cancellationToken: cancellationToken).ConfigureAwait(false);
+        }
+        catch (McpProtocolException ex) when (ex.ErrorCode == McpErrorCode.MethodNotFound)
+        {
+            // Defensive fallback: the server's advertised TaskSupport indicated this tool
+            // could be invoked as a task, but the server now rejects task augmentation for it
+            // (e.g. capability changed between tools/list and invocation). Fall back to a
+            // non-augmented call through the inner McpClientTool.
+            return await this._inner.InvokeAsync(arguments, cancellationToken).ConfigureAwait(false);
+        }
+
+        return await this.PollAndRetrieveResultAsync(task.TaskId, cancellationToken).ConfigureAwait(false);
+    }
+
+    private async Task<JsonElement> PollAndRetrieveResultAsync(string taskId, CancellationToken cancellationToken)
+    {
+        try
+        {
+            McpTask terminal = await this._client.PollTaskUntilCompleteAsync(taskId, options: null, cancellationToken).ConfigureAwait(false);
+
+            return terminal.Status switch
+            {
+                McpTaskStatus.Completed => await this._client.GetTaskResultAsync(taskId, options: null, cancellationToken).ConfigureAwait(false),
+                McpTaskStatus.Cancelled => throw new OperationCanceledException(FormatTerminalStatusMessage(taskId, terminal)),
+                _ => throw new InvalidOperationException(FormatTerminalStatusMessage(taskId, terminal)),// Failed (or any future non-terminal-but-unhandled status that the poll loop returns).
+            };
+        }
+        catch (OperationCanceledException) when (this._options.CancelRemoteTaskOnLocalCancellation && cancellationToken.IsCancellationRequested)
+        {
+            await this.TryCancelTaskAsync(taskId).ConfigureAwait(false);
+            throw;
+        }
+    }
+
+    private static string FormatTerminalStatusMessage(string taskId, McpTask terminal)
+        => string.IsNullOrEmpty(terminal.StatusMessage)
+            ? $"MCP task '{taskId}' ended in terminal status '{terminal.Status}'."
+            : $"MCP task '{taskId}' ended in terminal status '{terminal.Status}': {terminal.StatusMessage}";
+
+    private async Task TryCancelTaskAsync(string taskId)
+    {
+        try
+        {
+            using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
+            _ = await this._client.CancelTaskAsync(taskId, options: null, cts.Token).ConfigureAwait(false);
+        }
+        catch
+        {
+            // Best-effort cancellation; do not mask the original cancellation reason.
+        }
+    }
+}
@@ -248,7 +248,7 @@ public sealed class DockerShellExecutor : ShellExecutor
    /// Build the AIFunction for this tool.
    /// </summary>
    /// <remarks>
-    /// When <paramref name="requireApproval"/> is <see langword="null"/>
+    /// When <paramref name="requireApproval"/> is <see langword="true"/>
    /// (the default), the returned function is wrapped in
    /// <see cref="ApprovalRequiredAIFunction"/>. The caller must
    /// explicitly pass <see langword="false"/> to opt out of approval
@@ -259,14 +259,12 @@ public sealed class DockerShellExecutor : ShellExecutor
    /// <param name="name">Function name surfaced to the model.</param>
    /// <param name="description">Function description for the model.</param>
    /// <param name="requireApproval">
-    /// <see langword="true"/> or <see langword="null"/> (the default)
-    /// wraps the function in <see cref="ApprovalRequiredAIFunction"/>;
+    /// <see langword="true"/> (the default) wraps the function in
+    /// <see cref="ApprovalRequiredAIFunction"/>;
    /// <see langword="false"/> opts out and returns the raw function.
    /// </param>
-    public AIFunction AsAIFunction(string name = "run_shell", string? description = null, bool? requireApproval = null)
+    public override AIFunction AsAIFunction(string name = "run_shell", string? description = null, bool requireApproval = true)
    {
-        var effectiveRequireApproval = requireApproval ?? true;
-
        description ??=
            "Execute a single shell command inside an isolated Docker container and return its " +
            "stdout, stderr, and exit code. The container has no network, no host filesystem access " +
@@ -292,7 +290,7 @@ public sealed class DockerShellExecutor : ShellExecutor
            },
            new AIFunctionFactoryOptions { Name = name, Description = description });

-        return effectiveRequireApproval ? new ApprovalRequiredAIFunction(fn) : fn;
+        return requireApproval ? new ApprovalRequiredAIFunction(fn) : fn;
    }

    /// <summary>
@@ -325,7 +325,7 @@ public sealed class LocalShellExecutor : ShellExecutor
    /// container where the tool itself is the boundary).
    /// </param>
    /// <returns>An <see cref="AIFunction"/> wrapping <see cref="RunAsync"/>.</returns>
-    public AIFunction AsAIFunction(string name = "run_shell", string? description = null, bool requireApproval = true)
+    public override AIFunction AsAIFunction(string name = "run_shell", string? description = null, bool requireApproval = true)
    {
        if (!requireApproval && !this._acknowledgeUnsafe)
        {
@@ -3,6 +3,7 @@
 using System;
 using System.Threading;
 using System.Threading.Tasks;
+using Microsoft.Extensions.AI;

 namespace Microsoft.Agents.AI.Tools.Shell;

@@ -65,6 +66,20 @@ public abstract class ShellExecutor : IAsyncDisposable
    /// <param name="cancellationToken">Cancellation token.</param>
    public abstract Task<ShellResult> RunAsync(string command, CancellationToken cancellationToken = default);

+    /// <summary>
+    /// Build an <see cref="AIFunction"/> bound to this executor, suitable for
+    /// registering with an agent as a callable tool.
+    /// </summary>
+    /// <param name="name">Function name visible to the model.</param>
+    /// <param name="description">Function description for the model.</param>
+    /// <param name="requireApproval">
+    /// When <see langword="true"/> (the default), wraps the function in
+    /// <see cref="ApprovalRequiredAIFunction"/> so every invocation requires
+    /// explicit user approval before executing.
+    /// </param>
+    /// <returns>An <see cref="AIFunction"/> wrapping <see cref="RunAsync"/>.</returns>
+    public abstract AIFunction AsAIFunction(string name = "run_shell", string? description = null, bool requireApproval = true);
+
    /// <inheritdoc />
    public abstract ValueTask DisposeAsync();
 }
@@ -22,9 +22,13 @@ internal static class AgentProviderExtensions
    {
        IAsyncEnumerable<AgentResponseUpdate> agentUpdates = agentProvider.InvokeAgentAsync(agentName, null, conversationId, inputMessages, inputArguments, cancellationToken);

-        // Enable "autoSend" behavior if this is the workflow conversation.
+        // Determine whether the target conversation is the workflow conversation
+        // (used below to decide whether to mirror messages into the workflow conversation
+        // when an agent runs against a different conversation). The caller's autoSend
+        // value is honored as-is — when the workflow.yaml specifies autoSend: false the
+        // raw agent output must not be streamed to the caller, even when the agent is
+        // running on the workflow conversation.
        bool isWorkflowConversation = context.IsWorkflowConversation(conversationId, out string? workflowConversationId);
-        autoSend |= isWorkflowConversation;

        // Process the agent response updates.
        List<AgentResponseUpdate> updates = [];
@@ -71,6 +71,13 @@ internal abstract class DeclarativeActionExecutor : Executor<ActionExecutorResul
    [SendsMessage(typeof(ActionExecutorResult))]
    public override async ValueTask HandleAsync(ActionExecutorResult message, IWorkflowContext context, CancellationToken cancellationToken = default)
    {
+        // Establish the Foundry ProductContext on the current async logical context before
+        // running any code that reads PropertyPath.VariableName / NamespaceAlias. ObjectModel
+        // resolves those lazily against AsyncLocal<ProductContext>; when the workflow is
+        // hosted (AsAIAgent + AddFoundryResponses) each HTTP request runs on a fresh logical
+        // context where the build-thread setting does not flow.
+        WorkflowDiagnostics.SetFoundryProduct();
+
        if (this.Model.Disabled)
        {
            Debug.WriteLine($"DISABLED {this.GetType().Name} [{this.Id}]");
@@ -192,13 +192,16 @@ internal sealed class InvokeAzureAgentExecutor(InvokeAzureAgent model, ResponseA

    private bool GetAutoSendValue()
    {
-        if (this.AgentOutput?.AutoSend is null)
+        // AzureAgentOutput.AutoSend is never null — it returns a literal-false default
+        // when the YAML omits the field. Use AutoSendIsDefaultValue to distinguish an
+        // explicit autoSend value from the implicit default, and treat the implicit
+        // default as autoSend = true (the historical behavior for actions that omit
+        // autoSend or have no output block at all).
+        if (this.AgentOutput is { AutoSendIsDefaultValue: false } output)
        {
-            return true;
+            return this.Evaluator.GetValue(output.AutoSend).Value;
        }

-        EvaluationResult<bool> autoSendResult = this.Evaluator.GetValue(this.AgentOutput.AutoSend);
-
-        return autoSendResult.Value;
+        return true;
    }
 }
@@ -1,5 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.

+using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Text.Json;
@@ -103,6 +104,24 @@ internal sealed class InvokeFunctionToolExecutor(
        FunctionResultContent? matchingResult = functionResults
            .FirstOrDefault(r => r.CallId == this.Id);

+        // When the caller approved an approval-required function call but didn't execute it
+        // locally (the hosted Foundry scenario, where mcp_approval_response is converted to a
+        // ToolApprovalResponseContent only), invoke the registered AIFunction here so that the
+        // declarative workflow can capture the result and continue (e.g. for downstream
+        // SendActivity/PropertyPath consumers like {Local.Result}).
+        if (matchingResult is null)
+        {
+            ToolApprovalResponseContent? approval = response.Messages
+                .SelectMany(m => m.Contents)
+                .OfType<ToolApprovalResponseContent>()
+                .FirstOrDefault(r => r.RequestId == this.Id);
+
+            if (approval is { Approved: true })
+            {
+                matchingResult = await this.InvokeRegisteredFunctionAsync(cancellationToken).ConfigureAwait(false);
+            }
+        }
+
        if (matchingResult is not null)
        {
            // Store the result in output variable
@@ -241,6 +260,48 @@ internal sealed class InvokeFunctionToolExecutor(
        return conversationIdValue.Length == 0 ? null : conversationIdValue;
    }

+    private async ValueTask<FunctionResultContent?> InvokeRegisteredFunctionAsync(CancellationToken cancellationToken)
+    {
+        string functionName = this.GetFunctionName();
+        AIFunction? function = agentProvider.Functions?.FirstOrDefault(
+            f => string.Equals(f.Name, functionName, StringComparison.Ordinal));
+
+        if (function is null)
+        {
+            return new FunctionResultContent(this.Id, result: null)
+            {
+                Exception = new InvalidOperationException(
+                    $"Function '{functionName}' is not registered with the agent provider."),
+            };
+        }
+
+        Dictionary<string, object?>? arguments = this.GetArguments();
+        AIFunctionArguments? functionArguments = arguments is null ? null : new AIFunctionArguments(arguments);
+
+        object? result;
+        try
+        {
+            result = await function.InvokeAsync(functionArguments, cancellationToken).ConfigureAwait(false);
+        }
+        catch (Exception ex) when (ex is not OperationCanceledException)
+        {
+            return new FunctionResultContent(this.Id, result: null) { Exception = ex };
+        }
+
+        // Match FunctionInvokingChatClient's serialization: pass strings through as-is and
+        // JSON-serialize anything else so structured results remain consumable by downstream
+        // PropertyPath consumers such as {Local.RefundResult}. Use AIJsonUtilities so the
+        // same trim/AOT-friendly serializer chain used elsewhere in the framework is applied.
+        string serialized = result switch
+        {
+            null => string.Empty,
+            string s => s,
+            _ => JsonSerializer.Serialize(result, AIJsonUtilities.DefaultOptions.GetTypeInfo(result.GetType())),
+        };
+
+        return new FunctionResultContent(this.Id, serialized);
+    }
+
    private bool GetRequireApproval()
    {
        if (this.Model.RequireApproval is null)
@@ -253,12 +314,16 @@ internal sealed class InvokeFunctionToolExecutor(

    private bool GetAutoSendValue()
    {
-        if (this.Model.Output?.AutoSend is null)
+        // InvokeToolOutput.AutoSend is never null — it returns a literal-false default
+        // when the YAML omits the field. Use AutoSendIsDefaultValue to distinguish an
+        // explicit autoSend value from the implicit default, and treat the implicit
+        // default as autoSend = true (the historical behavior).
+        if (this.Model.Output is { AutoSendIsDefaultValue: false } output)
        {
-            return true;
+            return this.Evaluator.GetValue(output.AutoSend).Value;
        }

-        return this.Evaluator.GetValue(this.Model.Output.AutoSend).Value;
+        return true;
    }

    private Dictionary<string, object?>? GetArguments()
@@ -311,12 +311,16 @@ internal sealed class InvokeMcpToolExecutor(

    private bool GetAutoSendValue()
    {
-        if (this.Model.Output?.AutoSend is null)
+        // InvokeToolOutput.AutoSend is never null — it returns a literal-false default
+        // when the YAML omits the field. Use AutoSendIsDefaultValue to distinguish an
+        // explicit autoSend value from the implicit default, and treat the implicit
+        // default as autoSend = true (the historical behavior).
+        if (this.Model.Output is { AutoSendIsDefaultValue: false } output)
        {
-            return true;
+            return this.Evaluator.GetValue(output.AutoSend).Value;
        }

-        return this.Evaluator.GetValue(this.Model.Output.AutoSend).Value;
+        return true;
    }

    private string? GetConnectionName()
@@ -21,12 +21,21 @@ internal sealed class SendActivityExecutor(SendActivity model, WorkflowFormulaSt

            await context.AddEventAsync(new MessageActivityEvent(activityText.Trim()), cancellationToken).ConfigureAwait(false);

+            ChatMessage message = new(ChatRole.Assistant, activityText);
+
+            // Emit an AgentResponseUpdateEvent so chat protocols (e.g. AsAIAgent) receive the
+            // activity text as streaming chat content. This event is yielded by WorkflowSession
+            // unconditionally, mirroring how AgentProviderExtensions surfaces autoSend agent
+            // updates — without it, SendActivity output is dropped whenever the host runs with
+            // includeWorkflowOutputsInResponse = false (the default).
+            AgentResponseUpdate update = new(ChatRole.Assistant, activityText) { AuthorName = this.Id };
+            await context.AddEventAsync(new AgentResponseUpdateEvent(this.Id, update), cancellationToken).ConfigureAwait(false);
+
            // Route through YieldOutputAsync so the activity participates in the workflow's
            // output-filter pipeline. The runner currently special-cases AgentResponse to
-            // produce an AgentResponseEvent identical to the one we'd build by hand, so this
-            // is behavior-preserving today and forward-compatible if filtering is ever
-            // applied to agent responses.
-            AgentResponse response = new([new ChatMessage(ChatRole.Assistant, activityText)]);
+            // produce an AgentResponseEvent identical to the one we'd build by hand, which
+            // is the gated summary surfaced only when includeWorkflowOutputsInResponse = true.
+            AgentResponse response = new([message]);
            await context.YieldOutputAsync(response, cancellationToken).ConfigureAwait(false);
        }

@@ -0,0 +1,229 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.IO;
+using System.Threading.Tasks;
+using AgentConformance.IntegrationTests.Support;
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry;
+using OpenAI.Files;
+using OpenAI.Responses;
+using OpenAI.VectorStores;
+using Shared.IntegrationTests;
+
+namespace Foundry.IntegrationTests;
+
+/// <summary>
+/// Integration tests for the file and vector-store forwarder extensions on
+/// <see cref="FoundryAgent"/> declared in <see cref="FoundryAgentExtensions"/>. End-to-end
+/// counterparts of the unit tests in
+/// <c>FoundryAgentExtensionsTests</c> that exercise the live Foundry project pipeline.
+/// </summary>
+/// <remarks>
+/// Mirrors <see cref="FoundryVersionedAgentCreateTests.CreateAgent_CreatesAgentWithVectorStoresAsync(string)"/>
+/// in shape (file upload → vector store creation → FileSearchTool answer → cleanup), but routes
+/// every helper call through the new <see cref="FoundryAgent"/> extensions instead of the raw
+/// <c>projectOpenAIClient.GetProjectFilesClient()</c> / <c>GetProjectVectorStoresClient()</c>
+/// path. Skipped by default for the same reasons as the existing vector-store IT (cost and
+/// runtime); flip Skip to run manually after seeding the right Foundry project.
+/// </remarks>
+public class FoundryAgentExtensionsTests
+{
+    private readonly AIProjectClient _client = new(
+        new Uri(TestConfiguration.GetRequiredValue(TestSettings.AzureAIProjectEndpoint)),
+        TestAzureCliCredentials.CreateAzureCliCredential());
+
+    [Fact(Skip = "For manual testing only")]
+    public async Task UploadFileAsync_ViaAgentExtension_UploadsToProjectAsync()
+    {
+        // Arrange — non-versioned Responses Agent (Mode 1) so we do not have to provision a server-side agent.
+        var agent = this._client.AsAIAgent(
+            model: TestConfiguration.GetRequiredValue(TestSettings.AzureAIModelDeploymentName),
+            instructions: "Be helpful.");
+        var foundryAgent = this.WrapAsFoundryAgent(agent);
+
+        var filePath = Path.GetTempFileName() + ".txt";
+        File.WriteAllText(filePath, "agent-extensions integration test payload");
+
+        OpenAIFile? uploaded = null;
+        try
+        {
+            // Act.
+            uploaded = await foundryAgent.UploadFileAsync(filePath, FileUploadPurpose.Assistants);
+
+            // Assert.
+            Assert.NotNull(uploaded);
+            Assert.False(string.IsNullOrEmpty(uploaded.Id));
+            Assert.Equal(Path.GetFileName(filePath), uploaded.Filename);
+        }
+        finally
+        {
+            if (uploaded is not null)
+            {
+                await foundryAgent.DeleteFileAsync(uploaded.Id);
+            }
+
+            File.Delete(filePath);
+        }
+    }
+
+    [Fact(Skip = "For manual testing only")]
+    public async Task DeleteFileAsync_ViaAgentExtension_RemovesUploadedFileAsync()
+    {
+        var agent = this._client.AsAIAgent(
+            model: TestConfiguration.GetRequiredValue(TestSettings.AzureAIModelDeploymentName),
+            instructions: "Be helpful.");
+        var foundryAgent = this.WrapAsFoundryAgent(agent);
+
+        var filePath = Path.GetTempFileName() + ".txt";
+        File.WriteAllText(filePath, "delete-me payload");
+
+        try
+        {
+            var uploaded = await foundryAgent.UploadFileAsync(filePath, FileUploadPurpose.Assistants);
+
+            // Act.
+            var result = await foundryAgent.DeleteFileAsync(uploaded.Id);
+
+            // Assert.
+            Assert.NotNull(result);
+            Assert.Equal(uploaded.Id, result.FileId);
+            Assert.True(result.Deleted);
+        }
+        finally
+        {
+            File.Delete(filePath);
+        }
+    }
+
+    [Fact(Skip = "For manual testing only")]
+    public async Task CreateVectorStoreAsync_ViaAgentExtension_BuildsStoreAndAnswersFileSearchQuestionAsync()
+    {
+        // Mirrors CreateAgent_CreatesAgentWithVectorStoresAsync but the upload-then-create-store
+        // sequence routes through the FoundryAgent.CreateVectorStoreAsync extension (single call
+        // that uploads, creates the store, and polls until ready). The resulting vector store id
+        // is then wired to a versioned agent's FileSearch tool and queried for a known value.
+        string AgentName = FoundryVersionedAgentFixture.GenerateUniqueAgentName("VectorStoreExtAgent");
+        const string AgentInstructions = """
+            You are a helpful agent that can help fetch data from files you know about.
+            Use the File Search Tool to look up codes for words.
+            Do not answer a question unless you can find the answer using the File Search Tool.
+            """;
+
+        // Non-versioned helper agent that owns the upload pipeline.
+        var helperAgent = this._client.AsAIAgent(
+            model: TestConfiguration.GetRequiredValue(TestSettings.AzureAIModelDeploymentName),
+            instructions: "Be helpful.");
+        var helperFoundryAgent = this.WrapAsFoundryAgent(helperAgent);
+
+        var searchFilePath = Path.GetTempFileName() + "wordcodelookup.txt";
+        File.WriteAllText(searchFilePath, "The word 'apple' uses the code 442345, while the word 'banana' uses the code 673457.");
+
+        VectorStore? vectorStore = null;
+        FoundryAgent? versionedAgent = null;
+        try
+        {
+            // Act — single agent-level helper call uploads, creates, and waits until ready.
+            vectorStore = await helperFoundryAgent.CreateVectorStoreAsync(
+                "WordCodeLookup_ExtensionVectorStore",
+                new[] { searchFilePath });
+
+            Assert.NotNull(vectorStore);
+            Assert.False(string.IsNullOrEmpty(vectorStore.Id));
+            Assert.NotEqual(VectorStoreStatus.InProgress, vectorStore.Status);
+
+            // Wire the store id into a versioned agent's FileSearch tool to prove it is actually usable.
+            var definition = new DeclarativeAgentDefinition(TestConfiguration.GetRequiredValue(TestSettings.AzureAIModelDeploymentName))
+            {
+                Instructions = AgentInstructions,
+                Tools = { ResponseTool.CreateFileSearchTool(vectorStoreIds: [vectorStore.Id]) },
+            };
+
+            var agentVersion = await this._client.AgentAdministrationClient.CreateAgentVersionAsync(
+                AgentName,
+                new ProjectsAgentVersionCreationOptions(definition));
+
+            versionedAgent = this._client.AsAIAgent(agentVersion);
+
+            // Assert.
+            var result = await versionedAgent.RunAsync("Can you give me the documented code for 'banana'?");
+            Assert.Contains("673457", result.ToString());
+        }
+        finally
+        {
+            if (versionedAgent is not null)
+            {
+                await this._client.AgentAdministrationClient.DeleteAgentAsync(versionedAgent.Name);
+            }
+
+            // Cleanup the vector store via the new extension too.
+            if (vectorStore is not null)
+            {
+                await helperFoundryAgent.DeleteVectorStoreAsync(vectorStore.Id);
+            }
+
+            File.Delete(searchFilePath);
+        }
+    }
+
+    [Fact(Skip = "For manual testing only")]
+    public async Task DeleteVectorStoreAsync_ViaAgentExtension_RemovesStoreAsync()
+    {
+        var agent = this._client.AsAIAgent(
+            model: TestConfiguration.GetRequiredValue(TestSettings.AzureAIModelDeploymentName),
+            instructions: "Be helpful.");
+        var foundryAgent = this.WrapAsFoundryAgent(agent);
+
+        var filePath = Path.GetTempFileName() + ".txt";
+        File.WriteAllText(filePath, "delete-store payload");
+
+        VectorStore? vectorStore = null;
+        try
+        {
+            vectorStore = await foundryAgent.CreateVectorStoreAsync(
+                "DeleteVectorStore_ExtensionTest",
+                new[] { filePath });
+
+            // Act.
+            var result = await foundryAgent.DeleteVectorStoreAsync(vectorStore.Id);
+
+            // Assert.
+            Assert.NotNull(result);
+            Assert.Equal(vectorStore.Id, result.VectorStoreId);
+            Assert.True(result.Deleted);
+            vectorStore = null;
+        }
+        finally
+        {
+            if (vectorStore is not null)
+            {
+                await foundryAgent.DeleteVectorStoreAsync(vectorStore.Id);
+            }
+
+            File.Delete(filePath);
+        }
+    }
+
+    /// <summary>
+    /// Resolves the underlying <see cref="FoundryAgent"/> from an <see cref="AIAgent"/> handle
+    /// returned by <c>AIProjectClient.AsAIAgent(model, instructions)</c>. The Mode 1 overload
+    /// returns a <see cref="ChatClientAgent"/>; the extension forwarders we test live on
+    /// <see cref="FoundryAgent"/>, so callers wanting them through this entry point need to
+    /// reach for the FoundryAgent constructor instead. This helper makes the test setup
+    /// consistent across the four IT scenarios.
+    /// </summary>
+    private FoundryAgent WrapAsFoundryAgent(AIAgent agent)
+    {
+        // The Mode 1 AsAIAgent overload returns ChatClientAgent rather than FoundryAgent; use
+        // the FoundryAgent projectEndpoint+model+instructions ctor to get the same underlying
+        // FoundryChatClient surfaced through a FoundryAgent typed handle.
+        _ = agent;
+        return new FoundryAgent(
+            projectEndpoint: new Uri(TestConfiguration.GetRequiredValue(TestSettings.AzureAIProjectEndpoint)),
+            credential: TestAzureCliCredentials.CreateAzureCliCredential(),
+            model: TestConfiguration.GetRequiredValue(TestSettings.AzureAIModelDeploymentName),
+            instructions: "Be helpful.");
+    }
+}
@@ -11,7 +11,7 @@ namespace Foundry.IntegrationTests;
 public class FoundryVersionedAgentStructuredOutputRunTests() : StructuredOutputRunTests<FoundryVersionedAgentStructuredOutputFixture<CityInfo>>(() => new FoundryVersionedAgentStructuredOutputFixture<CityInfo>())
 {
    private const string NotSupported = "Versioned Foundry agents do not support specifying structured output type at invocation time.";
-    private const string ResponseFormatNotSupported = "AzureAIProjectChatClient clears ResponseFormat for versioned agents; structured output must be defined in the server-side agent definition.";
+    private const string ResponseFormatNotSupported = "FoundryChatClient clears ResponseFormat for versioned agents; structured output must be defined in the server-side agent definition.";

    /// <summary>
    /// Verifies that response format provided at agent initialization is used when invoking RunAsync.
@@ -41,7 +41,7 @@ public class FoundryVersionedAgentStructuredOutputRunTests() : StructuredOutputR
    /// </summary>
    /// <remarks>
    /// Versioned Foundry agents do not support specifying the structured output type at invocation time yet.
-    /// The type T provided to RunAsync&lt;T&gt; is ignored by AzureAIProjectChatClient and is only used
+    /// The type T provided to RunAsync&lt;T&gt; is ignored by FoundryChatClient and is only used
    /// for deserializing the agent response by AgentResponse&lt;T&gt;.Result.
    /// </remarks>
    [RetryFact(Constants.RetryCount, Constants.RetryDelay, Skip = ResponseFormatNotSupported)]
@@ -0,0 +1,85 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Text.RegularExpressions;
+using System.Threading.Tasks;
+using AgentConformance.IntegrationTests.Support;
+using Azure.AI.Projects;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using Shared.IntegrationTests;
+
+namespace Foundry.IntegrationTests;
+
+/// <summary>
+/// Integration tests validating that the <c>x-ms-served-model</c> response header
+/// returned by the Azure OpenAI Responses API is surfaced on <see cref="ChatResponse.ModelId"/>.
+/// </summary>
+public class ResponsesAgentServedModelTests
+{
+    // Matches a dated served-model snapshot, e.g. "gpt-5-nano-2025-08-07".
+    private static readonly Regex s_snapshotRegex = new(@"-\d{4}-\d{2}-\d{2}$", RegexOptions.Compiled);
+
+    private static Uri Endpoint => new(TestConfiguration.GetRequiredValue(TestSettings.AzureAIProjectEndpoint));
+
+    private static string DeploymentName => TestConfiguration.GetRequiredValue(TestSettings.AzureAIModelDeploymentName);
+
+    private readonly AIProjectClient _client = new(Endpoint, TestAzureCliCredentials.CreateAzureCliCredential());
+
+    [Fact]
+    public async Task GetResponseAsync_ReturnsServedModelSnapshotOnModelIdAsync()
+    {
+        // Arrange
+        ChatClientAgent agent = this._client.AsAIAgent(
+            model: DeploymentName,
+            instructions: "You are a helpful assistant. Reply with a single short word.",
+            name: "ServedModelTest");
+
+        IChatClient chatClient = agent.ChatClient;
+
+        // Act
+        ChatResponse response = await chatClient.GetResponseAsync(
+            [new ChatMessage(ChatRole.User, "Say hi.")],
+            new ChatOptions { ModelId = DeploymentName });
+
+        // Assert
+        AssertServedModel(response.ModelId);
+    }
+
+    [Fact]
+    public async Task RunAsync_AgentResponseRawRepresentationCarriesServedModelAsync()
+    {
+        // Arrange
+        ChatClientAgent agent = this._client.AsAIAgent(
+            model: DeploymentName,
+            instructions: "You are a helpful assistant. Reply with a single short word.",
+            name: "ServedModelTestRun");
+
+        // Act
+        AgentResponse agentResponse = await agent.RunAsync("Say hi.");
+
+        // Assert
+        ChatResponse? chatResponse = agentResponse.RawRepresentation as ChatResponse;
+        Assert.NotNull(chatResponse);
+        AssertServedModel(chatResponse!.ModelId);
+    }
+
+    private static void AssertServedModel(string? modelId)
+    {
+        Assert.False(string.IsNullOrWhiteSpace(modelId), "ChatResponse.ModelId must be populated.");
+
+        // Primary invariant: the served-model value must look like a dated snapshot
+        // (e.g. "gpt-5-nano-2025-08-07"). This is what the x-ms-served-model header carries.
+        // Only when the configured deployment name itself already matches the snapshot pattern
+        // do we fall back to permitting equality with the deployment alias.
+        bool aliasIsSnapshot = s_snapshotRegex.IsMatch(DeploymentName);
+
+        if (aliasIsSnapshot)
+        {
+            return;
+        }
+
+        Assert.Matches(s_snapshotRegex, modelId!);
+        Assert.NotEqual(DeploymentName, modelId);
+    }
+}
@@ -83,6 +83,72 @@ public sealed class A2AAgentTests : IDisposable
        Assert.Null(agent.Description);
    }

+    [Fact]
+    public void Constructor_WithOptions_InitializesPropertiesCorrectly()
+    {
+        // Arrange
+        var options = new A2AAgentOptions
+        {
+            Id = "options-id",
+            Name = "options-name",
+            Description = "options-description"
+        };
+
+        // Act
+        var agent = new A2AAgent(this._a2aClient, options);
+
+        // Assert
+        Assert.Equal("options-id", agent.Id);
+        Assert.Equal("options-name", agent.Name);
+        Assert.Equal("options-description", agent.Description);
+    }
+
+    [Fact]
+    public void Constructor_WithOptions_IsolatesAgentFromOptionsMutation()
+    {
+        // Arrange
+        var options = new A2AAgentOptions
+        {
+            Id = "original-id",
+            Name = "Original Name",
+            Description = "Original Description"
+        };
+        var agent = new A2AAgent(this._a2aClient, options);
+
+        // Act - mutate options after agent construction
+        options.Id = "mutated-id";
+        options.Name = "Mutated Name";
+        options.Description = "Mutated Description";
+
+        // Assert - agent should retain original values
+        Assert.Equal("original-id", agent.Id);
+        Assert.Equal("Original Name", agent.Name);
+        Assert.Equal("Original Description", agent.Description);
+    }
+
+    [Fact]
+    public void Constructor_WithNullOptions_ThrowsArgumentNullException() =>
+        // Act & Assert
+        Assert.Throws<ArgumentNullException>(() => new A2AAgent(this._a2aClient, options: null!));
+
+    [Fact]
+    public void Constructor_WithEmptyOptions_UsesBaseProperties()
+    {
+        // Act
+        var agent = new A2AAgent(this._a2aClient, new A2AAgentOptions());
+
+        // Assert
+        Assert.NotNull(agent.Id);
+        Assert.NotEmpty(agent.Id);
+        Assert.Null(agent.Name);
+        Assert.Null(agent.Description);
+    }
+
+    [Fact]
+    public void Constructor_WithOptions_NullA2AClient_ThrowsArgumentNullException() =>
+        // Act & Assert
+        Assert.Throws<ArgumentNullException>(() => new A2AAgent(null!, new A2AAgentOptions()));
+
    [Fact]
    public async Task RunAsync_AllowsNonUserRoleMessagesAsync()
    {
@@ -1058,6 +1124,7 @@ public sealed class A2AAgentTests : IDisposable
        Assert.Equal(TaskId, update0.ResponseId);
        Assert.Equal(this._agent.Id, update0.AgentId);
        Assert.Null(update0.FinishReason);
+        Assert.Null(update0.MessageId);
        Assert.IsType<TaskStatusUpdateEvent>(update0.RawRepresentation);

        // Assert - session should be updated with context and task IDs
@@ -1066,6 +1133,50 @@ public sealed class A2AAgentTests : IDisposable
        Assert.Equal(TaskId, a2aSession.TaskId);
    }

+    [Fact]
+    public async Task RunStreamingAsync_WithTaskStatusUpdateEventAndMessageId_YieldsMessageIdAsync()
+    {
+        // Arrange
+        const string TaskId = "task-status-msg-123";
+        const string ContextId = "ctx-status-msg-456";
+        const string ExpectedMessageId = "msg-status-789";
+
+        this._handler.StreamingResponseToReturn = new StreamResponse
+        {
+            StatusUpdate = new TaskStatusUpdateEvent
+            {
+                TaskId = TaskId,
+                ContextId = ContextId,
+                Status = new()
+                {
+                    State = TaskState.Working,
+                    Message = new Message
+                    {
+                        MessageId = ExpectedMessageId,
+                        Parts = [Part.FromText("Processing your request...")]
+                    }
+                }
+            }
+        };
+
+        var session = await this._agent.CreateSessionAsync();
+
+        // Act
+        var updates = new List<AgentResponseUpdate>();
+        await foreach (var update in this._agent.RunStreamingAsync("Check task status", session))
+        {
+            updates.Add(update);
+        }
+
+        // Assert
+        Assert.Single(updates);
+
+        var update0 = updates[0];
+        Assert.Equal(ExpectedMessageId, update0.MessageId);
+        Assert.Equal(TaskId, update0.ResponseId);
+        Assert.IsType<TaskStatusUpdateEvent>(update0.RawRepresentation);
+    }
+
    [Fact]
    public async Task RunStreamingAsync_WithInputRequiredStatusUpdate_YieldsStatusContentsAsync()
    {
@@ -1084,6 +1195,7 @@ public sealed class A2AAgentTests : IDisposable
                    State = TaskState.InputRequired,
                    Message = new Message
                    {
+                        MessageId = "input-msg-789",
                        Parts = [Part.FromText("Where would you like to fly?")]
                    }
                }
@@ -1104,6 +1216,7 @@ public sealed class A2AAgentTests : IDisposable

        var update0 = updates[0];
        Assert.Equal(TaskId, update0.ResponseId);
+        Assert.Equal("input-msg-789", update0.MessageId);
        Assert.Null(update0.FinishReason);

        var textContent = Assert.Single(update0.Contents.OfType<TextContent>());
@@ -31,7 +31,7 @@ public sealed class A2AAgentCardExtensionsTests
    }

    [Fact]
-    public void GetAIAgent_ReturnsAIAgent()
+    public void AsAIAgent_ReturnsAIAgent()
    {
        // Act
        var agent = this._agentCard.AsAIAgent();
@@ -165,6 +165,81 @@ public sealed class A2AAgentCardExtensionsTests
        Assert.ThrowsAny<Exception>(() => card.AsAIAgent());
    }

+    [Fact]
+    public void AsAIAgent_WithAgentOptions_OverridesCardValues()
+    {
+        // Arrange
+        var card = new AgentCard
+        {
+            Name = "Card Agent",
+            Description = "Card description",
+            SupportedInterfaces = [new AgentInterface { Url = "http://test-endpoint/agent" }]
+        };
+
+        var agentOptions = new A2AAgentOptions
+        {
+            Id = "custom-id",
+            Name = "Custom Agent",
+            Description = "Custom description"
+        };
+
+        // Act
+        var agent = card.AsAIAgent(agentOptions);
+
+        // Assert
+        Assert.NotNull(agent);
+        Assert.IsType<A2AAgent>(agent);
+        Assert.Equal("custom-id", agent.Id);
+        Assert.Equal("Custom Agent", agent.Name);
+        Assert.Equal("Custom description", agent.Description);
+    }
+
+    [Fact]
+    public void AsAIAgent_WithAgentOptions_FallsBackToCardValues()
+    {
+        // Arrange
+        var card = new AgentCard
+        {
+            Name = "Card Agent",
+            Description = "Card description",
+            SupportedInterfaces = [new AgentInterface { Url = "http://test-endpoint/agent" }]
+        };
+
+        var agentOptions = new A2AAgentOptions
+        {
+            Id = "custom-id"
+        };
+
+        // Act
+        var agent = card.AsAIAgent(agentOptions);
+
+        // Assert
+        Assert.NotNull(agent);
+        Assert.Equal("custom-id", agent.Id);
+        Assert.Equal("Card Agent", agent.Name);
+        Assert.Equal("Card description", agent.Description);
+    }
+
+    [Fact]
+    public void AsAIAgent_WithEmptyAgentOptions_UsesCardValues()
+    {
+        // Arrange
+        var card = new AgentCard
+        {
+            Name = "Card Agent",
+            Description = "Card description",
+            SupportedInterfaces = [new AgentInterface { Url = "http://test-endpoint/agent" }]
+        };
+
+        // Act
+        var agent = card.AsAIAgent(new A2AAgentOptions());
+
+        // Assert
+        Assert.NotNull(agent);
+        Assert.Equal("Card Agent", agent.Name);
+        Assert.Equal("Card description", agent.Description);
+    }
+
    internal sealed class HttpMessageHandlerStub : HttpMessageHandler
    {
        public Queue ResponsesToReturn { get; } = new();
@@ -113,6 +113,61 @@ public sealed class A2ACardResolverExtensionsTests : IDisposable
        Assert.Equal(new Uri("http://jsonrpc/agent"), this._handler.CapturedUris[1]);
    }

+    [Fact]
+    public async Task GetAIAgentAsync_WithAgentOptions_OverridesCardValuesAsync()
+    {
+        // Arrange
+        this._handler.ResponsesToReturn.Enqueue(new AgentCard
+        {
+            Name = "Card Agent",
+            Description = "Card description",
+            SupportedInterfaces = [new AgentInterface { Url = "http://test-endpoint/agent" }]
+        });
+
+        var agentOptions = new A2AAgentOptions
+        {
+            Id = "custom-id",
+            Name = "Custom Agent",
+            Description = "Custom description"
+        };
+
+        // Act
+        var agent = await this._resolver.GetAIAgentAsync(agentOptions, httpClient: this._httpClient);
+
+        // Assert
+        Assert.NotNull(agent);
+        Assert.IsType<A2AAgent>(agent);
+        Assert.Equal("custom-id", agent.Id);
+        Assert.Equal("Custom Agent", agent.Name);
+        Assert.Equal("Custom description", agent.Description);
+    }
+
+    [Fact]
+    public async Task GetAIAgentAsync_WithAgentOptions_FallsBackToCardValuesAsync()
+    {
+        // Arrange
+        this._handler.ResponsesToReturn.Enqueue(new AgentCard
+        {
+            Name = "Card Agent",
+            Description = "Card description",
+            SupportedInterfaces = [new AgentInterface { Url = "http://test-endpoint/agent" }]
+        });
+
+        var agentOptions = new A2AAgentOptions
+        {
+            Id = "custom-id"
+        };
+
+        // Act
+        var agent = await this._resolver.GetAIAgentAsync(agentOptions, httpClient: this._httpClient);
+
+        // Assert
+        Assert.NotNull(agent);
+        Assert.Equal("custom-id", agent.Id);
+        Assert.Equal("Card Agent", agent.Name);
+        Assert.Equal("Card description", agent.Description);
+    }
+
    public void Dispose()
    {
        this._handler.Dispose();
@@ -11,7 +11,7 @@ namespace Microsoft.Agents.AI.A2A.UnitTests;
 public sealed class A2AClientExtensionsTests
 {
    [Fact]
-    public void GetAIAgent_WithAllParameters_ReturnsA2AAgentWithSpecifiedProperties()
+    public void AsAIAgent_WithAllParameters_ReturnsA2AAgentWithSpecifiedProperties()
    {
        // Arrange
        var a2aClient = new A2AClient(new Uri("http://test-endpoint"));
@@ -32,7 +32,7 @@ public sealed class A2AClientExtensionsTests
    }

    [Fact]
-    public void GetAIAgent_WithIA2AClient_ReturnsA2AAgentWithSpecifiedProperties()
+    public void AsAIAgent_WithIA2AClient_ReturnsA2AAgentWithSpecifiedProperties()
    {
        // Arrange - use IA2AClient reference type to verify the extension method works with the interface
        IA2AClient a2aClient = new A2AClient(new Uri("http://test-endpoint"));
@@ -53,7 +53,7 @@ public sealed class A2AClientExtensionsTests
    }

    [Fact]
-    public void GetAIAgent_WithIA2AClient_ExposesClientViaGetService()
+    public void AsAIAgent_WithIA2AClient_ExposesClientViaGetService()
    {
        // Arrange
        IA2AClient a2aClient = new A2AClient(new Uri("http://test-endpoint"));
@@ -66,4 +66,45 @@ public sealed class A2AClientExtensionsTests
        Assert.NotNull(service);
        Assert.Same(a2aClient, service);
    }
+
+    [Fact]
+    public void AsAIAgent_WithOptions_ReturnsA2AAgentWithSpecifiedProperties()
+    {
+        // Arrange
+        var a2aClient = new A2AClient(new Uri("http://test-endpoint"));
+        var options = new A2AAgentOptions
+        {
+            Id = "options-agent-id",
+            Name = "Options Agent",
+            Description = "Agent created with options"
+        };
+
+        // Act
+        var agent = a2aClient.AsAIAgent(options);
+
+        // Assert
+        Assert.NotNull(agent);
+        Assert.IsType<A2AAgent>(agent);
+        Assert.Equal("options-agent-id", agent.Id);
+        Assert.Equal("Options Agent", agent.Name);
+        Assert.Equal("Agent created with options", agent.Description);
+    }
+
+    [Fact]
+    public void AsAIAgent_WithEmptyOptions_ReturnsA2AAgentWithDefaultProperties()
+    {
+        // Arrange
+        var a2aClient = new A2AClient(new Uri("http://test-endpoint"));
+
+        // Act
+        var agent = a2aClient.AsAIAgent(new A2AAgentOptions());
+
+        // Assert
+        Assert.NotNull(agent);
+        Assert.IsType<A2AAgent>(agent);
+        Assert.NotNull(agent.Id);
+        Assert.NotEmpty(agent.Id);
+        Assert.Null(agent.Name);
+        Assert.Null(agent.Description);
+    }
 }
@@ -64,15 +64,29 @@ public sealed class HostedOutboundUserAgentTests : IAsyncDisposable
        var inboundBody = await inboundResponse.Content.ReadAsStringAsync();

        // Assert: at least one OUTBOUND request reached the fake transport, AND it carries the
-        // foundry-hosting/agent-framework-dotnet/{version} supplement on its User-Agent.
-        // (We don't care about the inbound response shape — only that the agent's call to MEAI
-        // triggered an outbound request whose UA reaches the sandbox boundary correctly.)
+        // combined hosted segment foundry-hosting/agent-framework-dotnet/{version} on its
+        // User-Agent. This matches Python's contract
+        // (foundry-hosting/agent-framework-python/{version}, see
+        // python/packages/core/agent_framework/_telemetry.py): a single combined segment when
+        // hosted, never two separate ones. The bare agent-framework-dotnet/{version} segment
+        // (from AgentFrameworkUserAgentPolicy in FoundryChatClient) must be upgraded in place
+        // by HostedAgentUserAgentPolicy — never appear duplicated.
        Assert.True(this._outboundHandler!.Requests.Count > 0,
            $"Expected at least one outbound request. Inbound status: {(int)inboundResponse.StatusCode}, body: {inboundBody}");
        var outbound = this._outboundHandler.Requests[0];
        Assert.StartsWith(TestEndpoint, outbound.Uri);
        Assert.Contains("MEAI/", outbound.UserAgent);
-        Assert.Contains("foundry-hosting/agent-framework-dotnet", outbound.UserAgent);
+        Assert.Contains("foundry-hosting/agent-framework-dotnet/", outbound.UserAgent);
+
+        // The bare agent-framework-dotnet/{v} segment must NOT appear separately when the
+        // combined form is present — Python emits a single combined value when the hosted
+        // prefix is registered, and .NET preserves that contract via the in-place upgrade in
+        // HostedAgentUserAgentPolicy.
+        var combinedIdx = outbound.UserAgent!.IndexOf("foundry-hosting/agent-framework-dotnet/", StringComparison.Ordinal);
+        var beforeCombined = outbound.UserAgent.Substring(0, combinedIdx);
+        var afterCombined = outbound.UserAgent.Substring(combinedIdx + "foundry-hosting/agent-framework-dotnet/".Length);
+        Assert.DoesNotContain("agent-framework-dotnet/", beforeCombined);
+        Assert.DoesNotContain("agent-framework-dotnet/", afterCombined);
    }

    private async Task StartHostedServerAsync()
@@ -197,6 +211,179 @@ public sealed class HostedOutboundUserAgentTests : IAsyncDisposable
        return array?.Length ?? -1;
    }

+    // -----------------------------------------------------------------------
+    // Direct unit tests for HostedAgentUserAgentPolicy's in-place upgrade behavior.
+    // These run the policy on a synthetic ClientPipeline (no hosting infrastructure)
+    // so the upgrade logic itself can be asserted in isolation.
+    // -----------------------------------------------------------------------
+
+    [Fact]
+    public async Task HostedAgentUserAgentPolicy_UpgradesBareAgentFrameworkSegment_InPlaceAsync()
+    {
+        // Arrange: an upstream per-call policy stamps the bare agent-framework-dotnet/{version}
+        // segment (matching what AgentFrameworkUserAgentPolicy would write in non-hosted code).
+        // Then HostedAgentUserAgentPolicy runs and must REPLACE that segment with the combined
+        // foundry-hosting/agent-framework-dotnet/{version} form, not append a duplicate.
+        using var handler = new InspectingHandler();
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+
+        var pipeline = ClientPipeline.Create(
+            new ClientPipelineOptions { Transport = new HttpClientPipelineTransport(httpClient) },
+            perCallPolicies: [new SetUserAgentPolicy("agent-framework-dotnet/9.9.9"), HostedAgentUserAgentPolicy.Instance],
+            perTryPolicies: default,
+            beforeTransportPolicies: default);
+
+        // Act
+        var message = pipeline.CreateMessage();
+        message.Request.Method = "POST";
+        message.Request.Uri = new Uri("https://example.test/anything");
+        await pipeline.SendAsync(message);
+
+        // Assert: combined form is present; bare form is gone (no duplicate agent-framework segment).
+        Assert.NotNull(handler.LastUserAgent);
+        Assert.Contains("foundry-hosting/agent-framework-dotnet/", handler.LastUserAgent);
+        var ua = handler.LastUserAgent!;
+        var firstAgentFramework = ua.IndexOf("agent-framework-dotnet/", StringComparison.Ordinal);
+        Assert.True(firstAgentFramework >= 0, "Expected agent-framework-dotnet segment.");
+        var secondAgentFramework = ua.IndexOf("agent-framework-dotnet/", firstAgentFramework + 1, StringComparison.Ordinal);
+        Assert.Equal(-1, secondAgentFramework);
+    }
+
+    [Fact]
+    public async Task HostedAgentUserAgentPolicy_AppendsCombined_WhenNoBareSegmentPresentAsync()
+    {
+        // Arrange: nothing upstream stamps the bare segment. Hosted policy should append the
+        // full combined segment to whatever User-Agent is on the wire.
+        using var handler = new InspectingHandler();
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+
+        var pipeline = ClientPipeline.Create(
+            new ClientPipelineOptions { Transport = new HttpClientPipelineTransport(httpClient) },
+            perCallPolicies: [HostedAgentUserAgentPolicy.Instance],
+            perTryPolicies: default,
+            beforeTransportPolicies: default);
+
+        // Act
+        var message = pipeline.CreateMessage();
+        message.Request.Method = "POST";
+        message.Request.Uri = new Uri("https://example.test/anything");
+        await pipeline.SendAsync(message);
+
+        // Assert
+        Assert.NotNull(handler.LastUserAgent);
+        Assert.Contains("foundry-hosting/agent-framework-dotnet/", handler.LastUserAgent);
+    }
+
+    [Fact]
+    public async Task HostedAgentUserAgentPolicy_IsIdempotent_WhenCombinedSegmentAlreadyPresentAsync()
+    {
+        // Arrange: upstream pre-populates the combined segment (simulating a retry or duplicate
+        // registration). Hosted policy must not re-append.
+        using var handler = new InspectingHandler();
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+
+        var pipeline = ClientPipeline.Create(
+            new ClientPipelineOptions { Transport = new HttpClientPipelineTransport(httpClient) },
+            perCallPolicies: [new SetUserAgentPolicy("foundry-hosting/agent-framework-dotnet/9.9.9"), HostedAgentUserAgentPolicy.Instance],
+            perTryPolicies: default,
+            beforeTransportPolicies: default);
+
+        // Act
+        var message = pipeline.CreateMessage();
+        message.Request.Method = "POST";
+        message.Request.Uri = new Uri("https://example.test/anything");
+        await pipeline.SendAsync(message);
+
+        // Assert: exactly one occurrence of "foundry-hosting/agent-framework-dotnet/" segment.
+        Assert.NotNull(handler.LastUserAgent);
+        var first = handler.LastUserAgent!.IndexOf("foundry-hosting/agent-framework-dotnet/", StringComparison.Ordinal);
+        Assert.True(first >= 0);
+        var second = handler.LastUserAgent.IndexOf("foundry-hosting/agent-framework-dotnet/", first + 1, StringComparison.Ordinal);
+        Assert.Equal(-1, second);
+    }
+
+    [Fact]
+    public async Task HostedAgentUserAgentPolicy_ReplacesDifferentVersionCombinedSegment_InPlaceAsync()
+    {
+        // Q-D regression: when the User-Agent already carries the COMBINED hosted form with a
+        // different version (e.g. an older registration or caller-supplied baseline), the policy
+        // must replace the entire combined span — not just the bare suffix — so we never emit
+        // the malformed `foundry-hosting/foundry-hosting/agent-framework-dotnet/...` shape.
+        using var handler = new InspectingHandler();
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+
+        var pipeline = ClientPipeline.Create(
+            new ClientPipelineOptions { Transport = new HttpClientPipelineTransport(httpClient) },
+            perCallPolicies: [new SetUserAgentPolicy("foundry-hosting/agent-framework-dotnet/0.0.1 MEAI/10.5.1"), HostedAgentUserAgentPolicy.Instance],
+            perTryPolicies: default,
+            beforeTransportPolicies: default);
+
+        // Act
+        var message = pipeline.CreateMessage();
+        message.Request.Method = "POST";
+        message.Request.Uri = new Uri("https://example.test/anything");
+        await pipeline.SendAsync(message);
+
+        // Assert: no doubled foundry-hosting/ prefix.
+        Assert.NotNull(handler.LastUserAgent);
+        Assert.DoesNotContain("foundry-hosting/foundry-hosting/", handler.LastUserAgent, StringComparison.Ordinal);
+
+        // The combined segment must appear exactly once, and the trailing MEAI segment must be
+        // preserved in place (i.e. the policy only rewrote the combined span, not anything after it).
+        var firstCombined = handler.LastUserAgent!.IndexOf("foundry-hosting/agent-framework-dotnet/", StringComparison.Ordinal);
+        Assert.True(firstCombined >= 0);
+        var secondCombined = handler.LastUserAgent.IndexOf("foundry-hosting/agent-framework-dotnet/", firstCombined + 1, StringComparison.Ordinal);
+        Assert.Equal(-1, secondCombined);
+        Assert.Contains(" MEAI/10.5.1", handler.LastUserAgent, StringComparison.Ordinal);
+
+        // And the version that survives must be the runtime supplement value's version, not 0.0.1.
+        Assert.DoesNotContain("foundry-hosting/agent-framework-dotnet/0.0.1", handler.LastUserAgent, StringComparison.Ordinal);
+    }
+
+    private sealed class InspectingHandler : HttpClientHandler
+    {
+        public string? LastUserAgent { get; private set; }
+
+        protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
+        {
+            this.LastUserAgent = request.Headers.TryGetValues("User-Agent", out var values)
+                ? string.Join(",", values)
+                : null;
+
+            return Task.FromResult(new HttpResponseMessage(HttpStatusCode.OK)
+            {
+                Content = new StringContent("{}", Encoding.UTF8, "application/json"),
+                RequestMessage = request,
+            });
+        }
+    }
+
+    private sealed class SetUserAgentPolicy : PipelinePolicy
+    {
+        private readonly string _value;
+        public SetUserAgentPolicy(string value) => this._value = value;
+
+        public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+        {
+            message.Request.Headers.Set("User-Agent", this._value);
+            ProcessNext(message, pipeline, currentIndex);
+        }
+
+        public override ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+        {
+            message.Request.Headers.Set("User-Agent", this._value);
+            return ProcessNextAsync(message, pipeline, currentIndex);
+        }
+    }
+
    private sealed class NoopHandler : HttpMessageHandler
    {
        protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
@@ -23,9 +23,9 @@ namespace Microsoft.Agents.AI.Foundry.UnitTests;

 #pragma warning disable CS0618
 /// <summary>
-/// Unit tests for the <see cref="AzureAIProjectChatClientExtensions"/> class.
+/// Unit tests for the <see cref="AIProjectClientExtensions"/> class.
 /// </summary>
-public sealed class AzureAIProjectChatClientExtensionsTests
+public sealed class AIProjectClientExtensionsTests
 {
    #region AsAIAgent(AIProjectClient, model, instructions) Tests

@@ -71,7 +71,11 @@ public sealed class AzureAIProjectChatClientExtensionsTests
        Assert.Equal("test-agent", agent.Name);
        Assert.Equal("A test agent", agent.Description);
        Assert.NotNull(agent.GetService<IChatClient>());
-        Assert.Null(agent.GetService<AIProjectClient>());
+        // After the FoundryChatClient consolidation the inner chat-client now exposes the
+        // AIProjectClient via GetService — Foundry callers can walk to the project client from
+        // the agent without holding their own reference. (Previously this path returned null
+        // because AsAIAgent(model, instructions) skipped the decorator entirely.)
+        Assert.NotNull(agent.GetService<AIProjectClient>());
    }

    /// <summary>
@@ -123,7 +127,10 @@ public sealed class AzureAIProjectChatClientExtensionsTests
        Assert.NotNull(agent);
        Assert.Equal("options-agent", agent.Name);
        Assert.Equal("Agent from options", agent.Description);
-        Assert.Null(agent.GetService<AIProjectClient>());
+        // After the FoundryChatClient consolidation the inner chat-client now exposes the
+        // AIProjectClient via GetService — see twin assertion in
+        // AsAIAgent_Rapi_WithModelAndInstructions_CreatesChatClientAgent for the rationale.
+        Assert.NotNull(agent.GetService<AIProjectClient>());
    }

    /// <summary>
@@ -185,6 +192,106 @@ public sealed class AzureAIProjectChatClientExtensionsTests
        Assert.True(userAgentFound, "MEAI user-agent header was not found in any request");
    }

+    /// <summary>
+    /// Verify that the non-versioned AsAIAgent overload now wraps with FoundryChatClient
+    /// (regression-prevention for the previously-untagged extension path).
+    /// </summary>
+    [Fact]
+    public void AsAIAgent_Rapi_WithModelAndInstructions_ExposesFoundryChatClientAndProviderName()
+    {
+        // Arrange
+        AIProjectClient client = this.CreateTestAgentClient();
+
+        // Act
+        ChatClientAgent agent = client.AsAIAgent("gpt-4o-mini", "You are helpful.");
+
+        // Assert: FoundryChatClient is internal-sealed and reachable via GetService<IChatClient>().
+        var chatClient = agent.GetService<IChatClient>();
+        Assert.NotNull(chatClient);
+
+        // Provider tag is "microsoft.foundry" (previously this path had no Foundry tag at all).
+        var metadata = chatClient!.GetService<ChatClientMetadata>();
+        Assert.NotNull(metadata);
+        Assert.Equal("microsoft.foundry", metadata!.ProviderName);
+        Assert.Equal("gpt-4o-mini", metadata.DefaultModelId);
+
+        // Reaching the FoundryChatClient by type (via InternalsVisibleTo).
+        Assert.NotNull(agent.GetService<FoundryChatClient>());
+    }
+
+    /// <summary>
+    /// Verify that the options-based non-versioned AsAIAgent overload now wraps with FoundryChatClient.
+    /// </summary>
+    [Fact]
+    public void AsAIAgent_Rapi_WithOptions_ExposesFoundryChatClientAndProviderName()
+    {
+        // Arrange
+        AIProjectClient client = this.CreateTestAgentClient();
+        ChatClientAgentOptions options = new()
+        {
+            Name = "options-agent",
+            ChatOptions = new ChatOptions { ModelId = "gpt-4o-mini", Instructions = "x" },
+        };
+
+        // Act
+        ChatClientAgent agent = client.AsAIAgent(options);
+
+        // Assert
+        var chatClient = agent.GetService<IChatClient>();
+        Assert.NotNull(chatClient);
+        var metadata = chatClient!.GetService<ChatClientMetadata>();
+        Assert.NotNull(metadata);
+        Assert.Equal("microsoft.foundry", metadata!.ProviderName);
+        Assert.NotNull(agent.GetService<FoundryChatClient>());
+    }
+
+    /// <summary>
+    /// Verify that the non-versioned AsAIAgent overload stamps the
+    /// agent-framework-dotnet/{version} segment on outbound requests via the new
+    /// AgentFrameworkUserAgentPolicy registered by FoundryChatClient.
+    /// </summary>
+    [Fact]
+    public async Task AsAIAgent_Rapi_WithModelAndInstructions_StampsAgentFrameworkUserAgentSegmentAsync()
+    {
+        bool afSeen = false;
+        using HttpHandlerAssert httpHandler = new(request =>
+        {
+            if (request.Headers.TryGetValues("User-Agent", out IEnumerable<string>? values))
+            {
+                foreach (string value in values)
+                {
+                    if (value.Contains("agent-framework-dotnet/"))
+                    {
+                        afSeen = true;
+                    }
+                }
+            }
+
+            return new HttpResponseMessage(HttpStatusCode.OK)
+            {
+                Content = new StringContent(TestDataUtil.GetOpenAIDefaultResponseJson(), Encoding.UTF8, "application/json")
+            };
+        });
+
+#pragma warning disable CA5399
+        using HttpClient httpClient = new(httpHandler);
+#pragma warning restore CA5399
+
+        AIProjectClient aiProjectClient = new(
+            new Uri("https://test.openai.azure.com/"),
+            new FakeAuthenticationTokenProvider(),
+            new() { Transport = new HttpClientPipelineTransport(httpClient) });
+
+        ChatClientAgent agent = aiProjectClient.AsAIAgent("gpt-4o-mini", "You are helpful.");
+
+        // Act
+        AgentSession session = await agent.CreateSessionAsync();
+        await agent.RunAsync("Hello", session);
+
+        // Assert
+        Assert.True(afSeen, "Expected agent-framework-dotnet/{version} segment on outbound requests from AsAIAgent(model, instructions).");
+    }
+
    #endregion

    #region AsAIAgent(AIProjectClient, ProjectsAgentRecord) Tests
@@ -0,0 +1,199 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.ClientModel.Primitives;
+using System.Collections.Generic;
+using System.Net;
+using System.Net.Http;
+using System.Reflection;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Microsoft.Agents.AI.Foundry.UnitTests;
+
+/// <summary>
+/// Verifies the framework-wide <see cref="AgentFrameworkUserAgentPolicy"/>. The policy stamps
+/// <c>agent-framework-dotnet/{version}</c> onto the outgoing <c>User-Agent</c> header of every
+/// request made through a Foundry chat client and is registered automatically by
+/// <c>FoundryChatClient</c> via the MEAI <c>OpenAIRequestPolicies</c> hook.
+/// </summary>
+public sealed class AgentFrameworkUserAgentPolicyTests
+{
+    [Fact]
+    public async Task AgentFrameworkUserAgentPolicy_AddsAgentFrameworkSegment_ToOutgoingRequestAsync()
+    {
+        // Arrange
+        using var handler = new RecordingHandler();
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+        var pipeline = ClientPipeline.Create(
+            new ClientPipelineOptions { Transport = new HttpClientPipelineTransport(httpClient) },
+            perCallPolicies: [AgentFrameworkUserAgentPolicy.Instance],
+            perTryPolicies: default,
+            beforeTransportPolicies: default);
+
+        // Act
+        var message = pipeline.CreateMessage();
+        message.Request.Method = "POST";
+        message.Request.Uri = new Uri("https://example.test/anything");
+        await pipeline.SendAsync(message);
+
+        // Assert
+        Assert.Equal(1, handler.Count);
+        Assert.NotNull(handler.LastUserAgent);
+        Assert.Contains("agent-framework-dotnet/", handler.LastUserAgent);
+    }
+
+    [Fact]
+    public async Task AgentFrameworkUserAgentPolicy_DoesNotStampMeaiSegmentAsync()
+    {
+        // Arrange: the AF policy must only contribute the agent-framework-dotnet segment.
+        // The MEAI/{version} segment is contributed by the MEAI-shipped policy at a different
+        // layer; this policy must not duplicate or replace it.
+        using var handler = new RecordingHandler();
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+        var pipeline = ClientPipeline.Create(
+            new ClientPipelineOptions { Transport = new HttpClientPipelineTransport(httpClient) },
+            perCallPolicies: [AgentFrameworkUserAgentPolicy.Instance],
+            perTryPolicies: default,
+            beforeTransportPolicies: default);
+
+        // Act
+        var message = pipeline.CreateMessage();
+        message.Request.Method = "POST";
+        message.Request.Uri = new Uri("https://example.test/anything");
+        await pipeline.SendAsync(message);
+
+        // Assert
+        Assert.NotNull(handler.LastUserAgent);
+        Assert.DoesNotContain("MEAI/", handler.LastUserAgent);
+        Assert.DoesNotContain("foundry-hosting/", handler.LastUserAgent);
+    }
+
+    [Fact]
+    public async Task AgentFrameworkUserAgentPolicy_PreservesExistingUserAgent_WhenAppendingAsync()
+    {
+        // Arrange: a per-call policy upstream that pre-populates the User-Agent header. The AF
+        // policy must read the existing value and append (not overwrite) the agent-framework
+        // segment so both stay reachable on the wire. (The exact separator the HTTP transport
+        // emits between multi-value User-Agent entries is comma per RFC 7230; this test does
+        // not assert on the separator character because that is a transport detail.)
+        using var handler = new RecordingHandler();
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+        var pipeline = ClientPipeline.Create(
+            new ClientPipelineOptions { Transport = new HttpClientPipelineTransport(httpClient) },
+            perCallPolicies: [new SeedUserAgentPolicy("existing-app/1.0"), AgentFrameworkUserAgentPolicy.Instance],
+            perTryPolicies: default,
+            beforeTransportPolicies: default);
+
+        // Act
+        var message = pipeline.CreateMessage();
+        message.Request.Method = "POST";
+        message.Request.Uri = new Uri("https://example.test/anything");
+        await pipeline.SendAsync(message);
+
+        // Assert: both segments survive to the wire.
+        Assert.NotNull(handler.LastUserAgent);
+        Assert.Contains("existing-app/1.0", handler.LastUserAgent);
+        Assert.Contains("agent-framework-dotnet/", handler.LastUserAgent);
+    }
+
+    [Fact]
+    public async Task AgentFrameworkUserAgentPolicy_IsIdempotent_DoesNotDoubleStampAsync()
+    {
+        // Arrange: register the same policy twice on the same pipeline. The second application
+        // must detect the segment is already present and not append it again. Guards against
+        // double-stamping on retries or duplicate registration.
+        using var handler = new RecordingHandler();
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+        var pipeline = ClientPipeline.Create(
+            new ClientPipelineOptions { Transport = new HttpClientPipelineTransport(httpClient) },
+            perCallPolicies: [AgentFrameworkUserAgentPolicy.Instance, AgentFrameworkUserAgentPolicy.Instance],
+            perTryPolicies: default,
+            beforeTransportPolicies: default);
+
+        // Act
+        var message = pipeline.CreateMessage();
+        message.Request.Method = "POST";
+        message.Request.Uri = new Uri("https://example.test/anything");
+        await pipeline.SendAsync(message);
+
+        // Assert: exactly one occurrence of "agent-framework-dotnet/".
+        Assert.NotNull(handler.LastUserAgent);
+        var ua = handler.LastUserAgent!;
+        var first = ua.IndexOf("agent-framework-dotnet/", StringComparison.Ordinal);
+        Assert.True(first >= 0, "Expected at least one agent-framework-dotnet segment.");
+        var second = ua.IndexOf("agent-framework-dotnet/", first + 1, StringComparison.Ordinal);
+        Assert.Equal(-1, second);
+    }
+
+    [Fact]
+    public void AgentFrameworkUserAgentPolicy_ExposesSingletonInstance()
+    {
+        // Two reads of the static property must return the same instance. The policy is stateless
+        // and shared; allocating a fresh instance per registration site would bloat memory and
+        // defeat the dedup logic in OpenAIRequestPoliciesReflection.AddPolicyIfMissing.
+        var first = AgentFrameworkUserAgentPolicy.Instance;
+        var second = AgentFrameworkUserAgentPolicy.Instance;
+        Assert.Same(first, second);
+    }
+
+    [Fact]
+    public void AgentFrameworkUserAgentPolicy_ValueIncludesAFFoundryAssemblyVersion_ReflectionGuard()
+    {
+        // The policy emits "agent-framework-dotnet/{Microsoft.Agents.AI.Foundry assembly InformationalVersion}".
+        // If the assembly metadata stops being readable, the policy falls back to "agent-framework-dotnet"
+        // without a version, which is a measurable telemetry regression.
+        var attr = typeof(AgentFrameworkUserAgentPolicy).Assembly
+            .GetCustomAttribute<AssemblyInformationalVersionAttribute>();
+        Assert.NotNull(attr);
+        Assert.False(string.IsNullOrEmpty(attr!.InformationalVersion));
+    }
+
+    private sealed class RecordingHandler : HttpClientHandler
+    {
+        public int Count { get; private set; }
+        public string? LastUserAgent { get; private set; }
+
+        protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
+        {
+            this.Count++;
+            this.LastUserAgent = request.Headers.TryGetValues("User-Agent", out var values)
+                ? string.Join(",", values)
+                : null;
+
+            var resp = new HttpResponseMessage(HttpStatusCode.OK)
+            {
+                Content = new StringContent("{}", Encoding.UTF8, "application/json"),
+                RequestMessage = request,
+            };
+            return Task.FromResult(resp);
+        }
+    }
+
+    private sealed class SeedUserAgentPolicy : PipelinePolicy
+    {
+        private readonly string _value;
+        public SeedUserAgentPolicy(string value) => this._value = value;
+
+        public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+        {
+            message.Request.Headers.Set("User-Agent", this._value);
+            ProcessNext(message, pipeline, currentIndex);
+        }
+
+        public override ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+        {
+            message.Request.Headers.Set("User-Agent", this._value);
+            return ProcessNextAsync(message, pipeline, currentIndex);
+        }
+    }
+}
@@ -1,209 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using System;
-using System.ClientModel.Primitives;
-using System.Net;
-using System.Net.Http;
-using System.Text;
-using System.Threading.Tasks;
-using Azure.AI.Extensions.OpenAI;
-using Azure.AI.Projects;
-
-namespace Microsoft.Agents.AI.Foundry.UnitTests;
-
-#pragma warning disable CS0618
-public class AzureAIProjectChatClientTests
-{
-    /// <summary>
-    /// Verify that after the first RunAsync, the session's ConversationId is set from the
-    /// response, and subsequent requests include that conversation ID automatically.
-    /// </summary>
-    [Fact]
-    public async Task ChatClient_UsesDefaultConversationIdAsync()
-    {
-        // Arrange
-        var responsesRequestCount = 0;
-        using var httpHandler = new HttpHandlerAssert(async (request) =>
-        {
-            if (request.Method == HttpMethod.Post && request.RequestUri!.PathAndQuery.Contains("/responses"))
-            {
-                responsesRequestCount++;
-
-                // Assert: On the second Responses API call, verify the conversation ID
-                // from the first response is automatically included in the request body.
-                if (responsesRequestCount == 2 && request.Content is not null)
-                {
-                    var requestBody = await request.Content.ReadAsStringAsync().ConfigureAwait(false);
-                    Assert.Contains("resp_0888a", requestBody);
-                }
-
-                return new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent(TestDataUtil.GetOpenAIDefaultResponseJson(), Encoding.UTF8, "application/json") };
-            }
-
-            return new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent(TestDataUtil.GetAgentResponseJson(), Encoding.UTF8, "application/json") };
-        });
-
-#pragma warning disable CA5399
-        using var httpClient = new HttpClient(httpHandler);
-#pragma warning restore CA5399
-
-        AIProjectClient projectClient = new(
-            new Uri("https://test.openai.azure.com/"),
-            new FakeAuthenticationTokenProvider(),
-            new AIProjectClientOptions() { Transport = new HttpClientPipelineTransport(httpClient) });
-
-        var agent = projectClient.AsAIAgent(new AgentReference("agent-name"));
-
-        // Act
-        var session = await agent.CreateSessionAsync();
-        await agent.RunAsync("Hello", session);
-        await agent.RunAsync("Follow up", session);
-
-        // Assert
-        Assert.Equal(2, responsesRequestCount);
-        var chatClientSession = Assert.IsType<ChatClientAgentSession>(session);
-        Assert.Equal("resp_0888a46cbf2b1ff3006914596e05d08195a77c3f5187b769a7", chatClientSession.ConversationId);
-    }
-
-    /// <summary>
-    /// Verify that when the chat client doesn't have a default "conv_" conversation id, the chat client still uses the conversation ID in HTTP requests.
-    /// </summary>
-    [Fact]
-    public async Task ChatClient_UsesPerRequestConversationId_WhenNoDefaultConversationIdIsProvidedAsync()
-    {
-        // Arrange
-        var requestTriggered = false;
-        using var httpHandler = new HttpHandlerAssert(async (request) =>
-        {
-            if (request.Method == HttpMethod.Post && request.RequestUri!.PathAndQuery.Contains("/responses"))
-            {
-                requestTriggered = true;
-
-                // Assert
-                if (request.Content is not null)
-                {
-                    var requestBody = await request.Content.ReadAsStringAsync().ConfigureAwait(false);
-                    Assert.Contains("conv_12345", requestBody);
-                }
-
-                return new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent(TestDataUtil.GetOpenAIDefaultResponseJson(), Encoding.UTF8, "application/json") };
-            }
-
-            return new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent(TestDataUtil.GetAgentResponseJson(), Encoding.UTF8, "application/json") };
-        });
-
-#pragma warning disable CA5399
-        using var httpClient = new HttpClient(httpHandler);
-#pragma warning restore CA5399
-
-        AIProjectClient projectClient = new(
-            new Uri("https://test.openai.azure.com/"),
-            new FakeAuthenticationTokenProvider(),
-            new AIProjectClientOptions() { Transport = new HttpClientPipelineTransport(httpClient) });
-
-        var agent = projectClient.AsAIAgent(new AgentReference("agent-name"));
-
-        // Act
-        var session = await agent.CreateSessionAsync();
-        await agent.RunAsync("Hello", session, options: new ChatClientAgentRunOptions() { ChatOptions = new() { ConversationId = "conv_12345" } });
-
-        Assert.True(requestTriggered);
-        var chatClientSession = Assert.IsType<ChatClientAgentSession>(session);
-        Assert.Equal("conv_12345", chatClientSession.ConversationId);
-    }
-
-    /// <summary>
-    /// Verify that even when the chat client has a default conversation id, the chat client will prioritize the per-request conversation id provided in HTTP requests.
-    /// </summary>
-    [Fact]
-    public async Task ChatClient_UsesPerRequestConversationId_EvenWhenDefaultConversationIdIsProvidedAsync()
-    {
-        // Arrange
-        var requestTriggered = false;
-        using var httpHandler = new HttpHandlerAssert(async (request) =>
-        {
-            if (request.Method == HttpMethod.Post && request.RequestUri!.PathAndQuery.Contains("/responses"))
-            {
-                requestTriggered = true;
-
-                // Assert
-                if (request.Content is not null)
-                {
-                    var requestBody = await request.Content.ReadAsStringAsync().ConfigureAwait(false);
-                    Assert.Contains("conv_12345", requestBody);
-                }
-
-                return new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent(TestDataUtil.GetOpenAIDefaultResponseJson(), Encoding.UTF8, "application/json") };
-            }
-
-            return new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent(TestDataUtil.GetAgentResponseJson(), Encoding.UTF8, "application/json") };
-        });
-
-#pragma warning disable CA5399
-        using var httpClient = new HttpClient(httpHandler);
-#pragma warning restore CA5399
-
-        AIProjectClient projectClient = new(
-            new Uri("https://test.openai.azure.com/"),
-            new FakeAuthenticationTokenProvider(),
-            new AIProjectClientOptions() { Transport = new HttpClientPipelineTransport(httpClient) });
-
-        var agent = projectClient.AsAIAgent(new AgentReference("agent-name"));
-
-        // Act
-        var session = await agent.CreateSessionAsync();
-        await agent.RunAsync("Hello", session, options: new ChatClientAgentRunOptions() { ChatOptions = new() { ConversationId = "conv_12345" } });
-
-        Assert.True(requestTriggered);
-        var chatClientSession = Assert.IsType<ChatClientAgentSession>(session);
-        Assert.Equal("conv_12345", chatClientSession.ConversationId);
-    }
-
-    /// <summary>
-    /// Verify that when the chat client is provided without a "conv_" prefixed conversation ID, the chat client uses the previous conversation ID in HTTP requests.
-    /// </summary>
-    [Fact]
-    public async Task ChatClient_UsesPreviousResponseId_WhenConversationIsNotPrefixedAsConvAsync()
-    {
-        // Arrange
-        var requestTriggered = false;
-        using var httpHandler = new HttpHandlerAssert(async (request) =>
-        {
-            if (request.Method == HttpMethod.Post && request.RequestUri!.PathAndQuery.Contains("/responses"))
-            {
-                requestTriggered = true;
-
-                // Assert
-                if (request.Content is not null)
-                {
-                    var requestBody = await request.Content.ReadAsStringAsync().ConfigureAwait(false);
-                    Assert.Contains("resp_0888a", requestBody);
-                }
-
-                return new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent(TestDataUtil.GetOpenAIDefaultResponseJson(), Encoding.UTF8, "application/json") };
-            }
-
-            return new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent(TestDataUtil.GetAgentResponseJson(), Encoding.UTF8, "application/json") };
-        });
-
-#pragma warning disable CA5399
-        using var httpClient = new HttpClient(httpHandler);
-#pragma warning restore CA5399
-
-        AIProjectClient projectClient = new(
-            new Uri("https://test.openai.azure.com/"),
-            new FakeAuthenticationTokenProvider(),
-            new AIProjectClientOptions() { Transport = new HttpClientPipelineTransport(httpClient) });
-
-        var agent = projectClient.AsAIAgent(new AgentReference("agent-name"));
-
-        // Act
-        var session = await agent.CreateSessionAsync();
-        await agent.RunAsync("Hello", session, options: new ChatClientAgentRunOptions() { ChatOptions = new() { ConversationId = "resp_0888a" } });
-
-        Assert.True(requestTriggered);
-        var chatClientSession = Assert.IsType<ChatClientAgentSession>(session);
-        Assert.Equal("resp_0888a46cbf2b1ff3006914596e05d08195a77c3f5187b769a7", chatClientSession.ConversationId);
-    }
-}
-#pragma warning restore CS0618
@@ -0,0 +1,200 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.ClientModel.Primitives;
+using System.Net;
+using System.Net.Http;
+using System.Text;
+using System.Threading.Tasks;
+using Azure.AI.Projects;
+using OpenAI.Files;
+
+#pragma warning disable OPENAI001, CS0618
+
+namespace Microsoft.Agents.AI.Foundry.UnitTests;
+
+/// <summary>
+/// Unit tests for the file and vector-store forwarder extensions on <see cref="FoundryAgent"/>
+/// declared in <see cref="FoundryAgentExtensions"/>. The forwarders are thin shims over the
+/// inner <see cref="FoundryChatClient"/>, so coverage focuses on (a) request shape (the agent
+/// path reaches the same wire as a direct chat-client call), (b) null/missing-FoundryChatClient
+/// handling, and (c) returns the same payload the chat client would.
+/// </summary>
+public sealed class FoundryAgentExtensionsTests
+{
+    private static readonly Uri s_testProjectEndpoint = new("https://test.openai.azure.com/");
+
+    [Fact]
+    public async Task UploadFileAsync_Forwards_ToInnerFoundryChatClient_Async()
+    {
+        // Arrange — agent built via the Responses Agent (Mode 1) projectEndpoint+model+instructions
+        // ctor wires a FoundryChatClient inside that the extension can resolve via GetService.
+        var sawPostToFiles = false;
+        using var handler = new HttpHandlerAssert(req =>
+        {
+            if (req.Method == HttpMethod.Post && req.RequestUri!.AbsolutePath.Contains("/files", StringComparison.Ordinal))
+            {
+                sawPostToFiles = true;
+                return new HttpResponseMessage(HttpStatusCode.OK)
+                {
+                    Content = new StringContent(FakeFileJson("file_via_agent"), Encoding.UTF8, "application/json"),
+                };
+            }
+            return new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent("{}", Encoding.UTF8, "application/json") };
+        });
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+
+        var agent = new FoundryAgent(
+            projectEndpoint: s_testProjectEndpoint,
+            credential: new FakeAuthenticationTokenProvider(),
+            model: "gpt-4o-mini",
+            instructions: "Be helpful.",
+            clientOptions: new AIProjectClientOptions { Transport = new HttpClientPipelineTransport(httpClient) });
+
+        var path = System.IO.Path.Combine(System.IO.Path.GetTempPath(), $"fae-{Guid.NewGuid():N}.txt");
+        System.IO.File.WriteAllText(path, "hello");
+
+        try
+        {
+            // Act — call the forwarder on the agent.
+            var result = await agent.UploadFileAsync(path, FileUploadPurpose.Assistants);
+
+            // Assert
+            Assert.True(sawPostToFiles, "POST to /files must reach the wire through the agent forwarder.");
+            Assert.Equal("file_via_agent", result.Id);
+        }
+        finally
+        {
+            System.IO.File.Delete(path);
+        }
+    }
+
+    [Fact]
+    public async Task DeleteFileAsync_Forwards_ToInnerFoundryChatClient_Async()
+    {
+        var sawDelete = false;
+        using var handler = new HttpHandlerAssert(req =>
+        {
+            if (req.Method == HttpMethod.Delete && req.RequestUri!.AbsolutePath.Contains("/files/", StringComparison.Ordinal))
+            {
+                sawDelete = true;
+                return new HttpResponseMessage(HttpStatusCode.OK)
+                {
+                    Content = new StringContent("{\"id\":\"file_abc\",\"object\":\"file\",\"deleted\":true}", Encoding.UTF8, "application/json"),
+                };
+            }
+            return new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent("{}", Encoding.UTF8, "application/json") };
+        });
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+
+        var agent = new FoundryAgent(
+            projectEndpoint: s_testProjectEndpoint,
+            credential: new FakeAuthenticationTokenProvider(),
+            model: "gpt-4o-mini",
+            instructions: "Be helpful.",
+            clientOptions: new AIProjectClientOptions { Transport = new HttpClientPipelineTransport(httpClient) });
+
+        var result = await agent.DeleteFileAsync("file_abc");
+
+        Assert.True(sawDelete);
+        Assert.NotNull(result);
+    }
+
+    [Fact]
+    public async Task CreateVectorStoreAsync_Forwards_ToInnerFoundryChatClient_Async()
+    {
+        var sawVectorStorePost = false;
+        using var handler = new HttpHandlerAssert(req =>
+        {
+            if (req.Method == HttpMethod.Post && req.RequestUri!.AbsolutePath.Contains("/vector_stores", StringComparison.Ordinal))
+            {
+                sawVectorStorePost = true;
+                return new HttpResponseMessage(HttpStatusCode.OK)
+                {
+                    Content = new StringContent(FakeVectorStoreJson("vs_via_agent", "kb"), Encoding.UTF8, "application/json"),
+                };
+            }
+            return new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent("{}", Encoding.UTF8, "application/json") };
+        });
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+
+        var agent = new FoundryAgent(
+            projectEndpoint: s_testProjectEndpoint,
+            credential: new FakeAuthenticationTokenProvider(),
+            model: "gpt-4o-mini",
+            instructions: "Be helpful.",
+            clientOptions: new AIProjectClientOptions { Transport = new HttpClientPipelineTransport(httpClient) });
+
+        var store = await agent.CreateVectorStoreAsync("kb", Array.Empty<string>());
+
+        Assert.True(sawVectorStorePost);
+        Assert.Equal("vs_via_agent", store.Id);
+    }
+
+    [Fact]
+    public async Task DeleteVectorStoreAsync_Forwards_ToInnerFoundryChatClient_Async()
+    {
+        var sawDelete = false;
+        using var handler = new HttpHandlerAssert(req =>
+        {
+            if (req.Method == HttpMethod.Delete && req.RequestUri!.AbsolutePath.Contains("/vector_stores/", StringComparison.Ordinal))
+            {
+                sawDelete = true;
+                return new HttpResponseMessage(HttpStatusCode.OK)
+                {
+                    Content = new StringContent("{\"id\":\"vs_abc\",\"object\":\"vector_store.deleted\",\"deleted\":true}", Encoding.UTF8, "application/json"),
+                };
+            }
+            return new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent("{}", Encoding.UTF8, "application/json") };
+        });
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+
+        var agent = new FoundryAgent(
+            projectEndpoint: s_testProjectEndpoint,
+            credential: new FakeAuthenticationTokenProvider(),
+            model: "gpt-4o-mini",
+            instructions: "Be helpful.",
+            clientOptions: new AIProjectClientOptions { Transport = new HttpClientPipelineTransport(httpClient) });
+
+        await agent.DeleteVectorStoreAsync("vs_abc");
+
+        Assert.True(sawDelete);
+    }
+
+    [Fact]
+    public async Task UploadFileAsync_NullAgent_ThrowsArgumentNullExceptionAsync()
+        => await Assert.ThrowsAsync<ArgumentNullException>(() =>
+            FoundryAgentExtensions.UploadFileAsync(null!, "x", FileUploadPurpose.Assistants));
+
+    [Fact]
+    public async Task DeleteFileAsync_NullAgent_ThrowsArgumentNullExceptionAsync()
+        => await Assert.ThrowsAsync<ArgumentNullException>(() =>
+            FoundryAgentExtensions.DeleteFileAsync(null!, "file_abc"));
+
+    [Fact]
+    public async Task CreateVectorStoreAsync_NullAgent_ThrowsArgumentNullExceptionAsync()
+        => await Assert.ThrowsAsync<ArgumentNullException>(() =>
+            FoundryAgentExtensions.CreateVectorStoreAsync(null!, "kb", Array.Empty<string>()));
+
+    [Fact]
+    public async Task DeleteVectorStoreAsync_NullAgent_ThrowsArgumentNullExceptionAsync()
+        => await Assert.ThrowsAsync<ArgumentNullException>(() =>
+            FoundryAgentExtensions.DeleteVectorStoreAsync(null!, "vs_abc"));
+
+    // ----- Helpers -----
+
+    private static string FakeFileJson(string id)
+        => $"{{\"id\":\"{id}\",\"object\":\"file\",\"bytes\":11,\"created_at\":1700000000,\"filename\":\"x.txt\",\"purpose\":\"assistants\",\"status\":\"processed\"}}";
+
+    private static string FakeVectorStoreJson(string id, string name)
+        => $"{{\"id\":\"{id}\",\"object\":\"vector_store\",\"created_at\":1700000000,\"name\":\"{name}\",\"usage_bytes\":0,\"file_counts\":{{\"in_progress\":0,\"completed\":0,\"failed\":0,\"cancelled\":0,\"total\":0}},\"status\":\"completed\",\"last_active_at\":1700000000}}";
+}
+#pragma warning restore CS0618
@@ -2,7 +2,6 @@

 using System;
 using System.ClientModel.Primitives;
-using System.Collections.Generic;
 using System.Net;
 using System.Net.Http;
 using System.Text;
@@ -352,18 +351,24 @@ public class FoundryAgentTests
    }

    [Fact]
-    public async Task Constructor_UserAgentHeaderAddedToRequestsAsync()
+    public async Task Constructor_AgentFrameworkUserAgentHeaderAddedToRequestsAsync()
    {
-        bool userAgentFound = false;
+        // After the FoundryChatClient consolidation, every outbound request from a
+        // FoundryAgent-built chat client carries the new agent-framework-dotnet/{version}
+        // segment (stamped by AgentFrameworkUserAgentPolicy registered via the MEAI
+        // OpenAIRequestPolicies hook). The local MEAI/{version} stamp was removed because
+        // MEAI 10.5.1 stamps that itself; this test only verifies the framework-wide segment
+        // that the Foundry package now guarantees.
+        bool agentFrameworkUserAgentFound = false;
        using HttpHandlerAssert httpHandler = new(request =>
        {
-            if (request.Headers.TryGetValues("User-Agent", out IEnumerable<string>? values))
+            if (request.Headers.TryGetValues("User-Agent", out System.Collections.Generic.IEnumerable<string>? values))
            {
                foreach (string value in values)
                {
-                    if (value.StartsWith("MEAI/", StringComparison.OrdinalIgnoreCase))
+                    if (value.Contains("agent-framework-dotnet/"))
                    {
-                        userAgentFound = true;
+                        agentFrameworkUserAgentFound = true;
                    }
                }
            }
@@ -396,7 +401,7 @@ public class FoundryAgentTests
        AgentSession session = await agent.CreateSessionAsync();
        await agent.RunAsync("Hello", session);

-        Assert.True(userAgentFound, "Expected MEAI user-agent header to be present in requests.");
+        Assert.True(agentFrameworkUserAgentFound, "Expected agent-framework-dotnet user-agent segment to be present on outbound requests.");
    }

    #endregion
@@ -434,6 +439,9 @@ public class FoundryAgentTests
    [Fact]
    public void AgentEndpointConstructor_GetServiceProjectOpenAIClient_ReturnsNull()
    {
+        // Behavior change: FoundryAgent no longer caches a ProjectOpenAIClient. Callers
+        // retrieve it from the AIProjectClient themselves
+        // (agent.GetService<AIProjectClient>()!.GetProjectOpenAIClient()).
        FoundryAgent agent = new(s_testAgentEndpoint, new FakeAuthenticationTokenProvider());

        Assert.Null(agent.GetService<ProjectOpenAIClient>());
@@ -442,6 +450,10 @@ public class FoundryAgentTests
    [Fact]
    public void AgentEndpointConstructor_GetServiceAIProjectClient_ReturnsNonNull()
    {
+        // Behavior change: after Plan #2's Agent Endpoint mode (Mode 3) AIProjectClient materialization, the
+        // agent-endpoint constructor now derives a project-level AIProjectClient from the
+        // parsed project root URL and surfaces it via GetService. Previously this returned
+        // null because no AIProjectClient was constructed for hosted-agent-endpoint agents.
        FoundryAgent agent = new(s_testAgentEndpoint, new FakeAuthenticationTokenProvider());

        Assert.NotNull(agent.GetService<AIProjectClient>());
@@ -450,6 +462,7 @@ public class FoundryAgentTests
    [Fact]
    public void ProjectEndpointConstructor_GetServiceProjectOpenAIClient_ReturnsNull()
    {
+        // See AgentEndpointConstructor_GetServiceProjectOpenAIClient_ReturnsNull for rationale.
        FoundryAgent agent = new(
            s_testEndpoint,
            new FakeAuthenticationTokenProvider(),
@@ -611,6 +624,57 @@ public class FoundryAgentTests
        Assert.True(meaiSeen, "Expected MEAI/x.y.z to appear in the User-Agent header on the agent-endpoint pipeline.");
    }

+    [Fact]
+    public void AgentEndpointConstructor_ExposesFoundryProviderName_OnChatClientMetadata()
+    {
+        // Behavior change: after the FoundryChatClient consolidation, the agent-endpoint path
+        // now wraps with FoundryChatClient in the Agent Endpoint mode (Mode 3) and stamps the microsoft.foundry provider
+        // name. Previously this path used a bare AsIChatClient() with no Foundry-specific
+        // decorator, so the provider name defaulted to whatever MEAI surfaces. This guards the
+        // new behavior.
+        FoundryAgent agent = new(s_testAgentEndpoint, new FakeAuthenticationTokenProvider());
+
+        var metadata = agent.GetService<ChatClientMetadata>();
+        Assert.NotNull(metadata);
+        Assert.Equal("microsoft.foundry", metadata!.ProviderName);
+    }
+
+    [Fact]
+    public async Task AgentEndpointConstructor_StampsAgentFrameworkUserAgentSegmentAsync()
+    {
+        // Behavior change: after the FoundryChatClient consolidation, every outbound request
+        // from the agent-endpoint constructor carries the agent-framework-dotnet/{version}
+        // segment via AgentFrameworkUserAgentPolicy. Previously this path had no
+        // agent-framework branding at all.
+        bool afSeen = false;
+        using HttpHandlerAssert handler = new(req =>
+        {
+            if (req.Headers.TryGetValues("User-Agent", out var values))
+            {
+                foreach (string v in values)
+                {
+                    if (v.Contains("agent-framework-dotnet/"))
+                    {
+                        afSeen = true;
+                    }
+                }
+            }
+            return new HttpResponseMessage(HttpStatusCode.OK)
+            {
+                Content = new StringContent(TestDataUtil.GetOpenAIDefaultResponseJson(), Encoding.UTF8, "application/json"),
+            };
+        });
+#pragma warning disable CA5399
+        using HttpClient http = new(handler);
+#pragma warning restore CA5399
+        ProjectOpenAIClientOptions opts = new() { Transport = new HttpClientPipelineTransport(http) };
+
+        FoundryAgent agent = new(s_testAgentEndpoint, new FakeAuthenticationTokenProvider(), clientOptions: opts);
+        await agent.RunAsync("Hello");
+
+        Assert.True(afSeen, "Expected agent-framework-dotnet/{version} segment on the agent-endpoint outbound User-Agent.");
+    }
+
    [Fact]
    public async Task AgentEndpointConstructor_PassesThroughCallerPolicyOnPerAgentPipelineAsync()
    {
@@ -666,82 +730,22 @@ public class FoundryAgentTests
    }

    [Fact]
-    public void AgentEndpointConstructor_PreservesUserAgentApplicationId()
+    public void AgentEndpointConstructor_PropagatesUserAgentApplicationId_ToProjectLevelClient()
    {
+        // The MEAI policy adds its own User-Agent header so we cannot reliably observe the OpenAI SDK's
+        // application-id stamp in the outbound request. Verify the value is propagated onto the
+        // caller's options bag and that the materialized AIProjectClient is reachable so
+        // downstream conversation/file/vector-store operations can pick the application id up.
        ProjectOpenAIClientOptions opts = new() { UserAgentApplicationId = "my-app-id" };

        FoundryAgent agent = new(s_testAgentEndpoint, new FakeAuthenticationTokenProvider(), clientOptions: opts);

+        AIProjectClient? aiProjectClient = agent.GetService<AIProjectClient>();
+        Assert.NotNull(aiProjectClient);
        // Caller's UserAgentApplicationId is preserved on the per-agent options bag verbatim.
-        Assert.NotNull(agent);
        Assert.Equal("my-app-id", opts.UserAgentApplicationId);
    }

-    [Fact]
-    public void CreateProjectClientOptions_NullCallerOptions_ReturnsNull()
-    {
-        Assert.Null(FoundryAgent.CreateProjectClientOptions(null));
-    }
-
-    [Fact]
-    public void CreateProjectClientOptions_CarriesPipelineSettingsAndUserAgent()
-    {
-        // Arrange
-        var transport = new FakePipelineTransport();
-        var retryPolicy = new FakeRetryPolicy();
-        var messageLoggingPolicy = new FakeMessageLoggingPolicy();
-        var clientLoggingOptions = new ClientLoggingOptions { EnableLogging = false };
-        var networkTimeout = TimeSpan.FromSeconds(42);
-
-        ProjectOpenAIClientOptions callerOptions = new()
-        {
-            UserAgentApplicationId = "my-app-id",
-            Transport = transport,
-            RetryPolicy = retryPolicy,
-            MessageLoggingPolicy = messageLoggingPolicy,
-            ClientLoggingOptions = clientLoggingOptions,
-            NetworkTimeout = networkTimeout,
-        };
-
-        // Act
-        AIProjectClientOptions? projectOptions = FoundryAgent.CreateProjectClientOptions(callerOptions);
-
-        // Assert: every settable pipeline behavior the caller configured is forwarded
-        // onto the project-level options bag, not silently dropped.
-        Assert.NotNull(projectOptions);
-        Assert.Equal("my-app-id", projectOptions!.UserAgentApplicationId);
-        Assert.Same(transport, projectOptions.Transport);
-        Assert.Same(retryPolicy, projectOptions.RetryPolicy);
-        Assert.Same(messageLoggingPolicy, projectOptions.MessageLoggingPolicy);
-        Assert.Same(clientLoggingOptions, projectOptions.ClientLoggingOptions);
-        Assert.Equal(networkTimeout, projectOptions.NetworkTimeout);
-    }
-
-    private sealed class FakeRetryPolicy : PipelinePolicy
-    {
-        public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
-            => ProcessNext(message, pipeline, currentIndex);
-
-        public override ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
-            => ProcessNextAsync(message, pipeline, currentIndex);
-    }
-
-    private sealed class FakeMessageLoggingPolicy : PipelinePolicy
-    {
-        public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
-            => ProcessNext(message, pipeline, currentIndex);
-
-        public override ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
-            => ProcessNextAsync(message, pipeline, currentIndex);
-    }
-
-    private sealed class FakePipelineTransport : PipelineTransport
-    {
-        protected override PipelineMessage CreateMessageCore() => throw new NotSupportedException();
-        protected override void ProcessCore(PipelineMessage message) => throw new NotSupportedException();
-        protected override ValueTask ProcessCoreAsync(PipelineMessage message) => throw new NotSupportedException();
-    }
-
    #endregion

    #region ParseAgentEndpoint tests
@@ -824,13 +828,13 @@ public class FoundryAgentTests
        private readonly string _value;
        public HeaderStampPolicy(string name, string value) { this._name = name; this._value = value; }

-        public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+        public override void Process(PipelineMessage message, System.Collections.Generic.IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
        {
            message.Request.Headers.Set(this._name, this._value);
            ProcessNext(message, pipeline, currentIndex);
        }

-        public override ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+        public override ValueTask ProcessAsync(PipelineMessage message, System.Collections.Generic.IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
        {
            message.Request.Headers.Set(this._name, this._value);
            return ProcessNextAsync(message, pipeline, currentIndex);
@@ -0,0 +1,616 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.ClientModel.Primitives;
+using System.Net;
+using System.Net.Http;
+using System.Reflection;
+using System.Text;
+using System.Threading.Tasks;
+using Azure.AI.Extensions.OpenAI;
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Microsoft.Extensions.AI;
+
+#pragma warning disable OPENAI001, CS0618
+
+namespace Microsoft.Agents.AI.Foundry.UnitTests;
+
+/// <summary>
+/// Unit tests for the internal <see cref="FoundryChatClient"/>. Covers the three construction
+/// modes (Responses Agent, Prompt Agent, Agent Endpoint), the GetService
+/// returns per mode, the metadata-tagging contract, the agent-framework user-agent registration,
+/// the Agent Endpoint mode (Mode 3) URL parsing happy and error paths, and end-to-end behavior through the public
+/// <c>AsAIAgent(AgentReference)</c> extension that constructs a FoundryChatClient internally.
+/// </summary>
+public sealed class FoundryChatClientTests
+{
+    #region the Responses Agent mode (Mode 1): Responses Agent (AIProjectClient + modelId)
+
+    [Fact]
+    public void Mode1_ResponsesAgent_StampsFoundryProviderName()
+    {
+        // Arrange
+        var projectClient = CreateProjectClient();
+
+        // Act
+        var chatClient = new FoundryChatClient(projectClient, "gpt-4o-mini");
+
+        // Assert
+        var metadata = chatClient.GetService<ChatClientMetadata>();
+        Assert.NotNull(metadata);
+        Assert.Equal("microsoft.foundry", metadata!.ProviderName);
+        Assert.Equal("gpt-4o-mini", metadata.DefaultModelId);
+    }
+
+    [Fact]
+    public void Mode1_ResponsesAgent_ExposesAIProjectClient_ViaGetService()
+    {
+        // Arrange
+        var projectClient = CreateProjectClient();
+
+        // Act
+        var chatClient = new FoundryChatClient(projectClient, "gpt-4o-mini");
+
+        // Assert
+        Assert.Same(projectClient, chatClient.GetService<AIProjectClient>());
+        // ProjectOpenAIClient is intentionally NOT exposed via GetService — callers retrieve
+        // it from the AIProjectClient themselves (aiProjectClient.GetProjectOpenAIClient()).
+        Assert.Null(chatClient.GetService<ProjectOpenAIClient>());
+    }
+
+    [Fact]
+    public void Mode1_ResponsesAgent_ReturnsNullForAgentSpecificServices()
+    {
+        // Arrange
+        var projectClient = CreateProjectClient();
+
+        // Act
+        var chatClient = new FoundryChatClient(projectClient, "gpt-4o-mini");
+
+        // Assert
+        Assert.Null(chatClient.GetService<AgentReference>());
+        Assert.Null(chatClient.GetService<ProjectsAgentVersion>());
+        Assert.Null(chatClient.GetService<ProjectsAgentRecord>());
+        // No agent name exists in the Responses Agent mode (Mode 1) — only the Prompt Agent mode (Mode 2) (from AgentReference.Name) and the Agent Endpoint mode (Mode 3)
+        // (parsed from URL) populate FoundryChatClient.AgentName.
+        Assert.Null(chatClient.AgentName);
+    }
+
+    [Fact]
+    public void Mode1_ResponsesAgent_ThrowsOnNullProjectClient()
+        => Assert.Throws<ArgumentNullException>(() => new FoundryChatClient(aiProjectClient: null!, "gpt-4o-mini"));
+
+    [Fact]
+    public void Mode1_ResponsesAgent_ThrowsOnEmptyModelId()
+        => Assert.Throws<ArgumentException>(() => new FoundryChatClient(CreateProjectClient(), modelId: ""));
+
+    #endregion
+
+    #region the Prompt Agent mode (Mode 2): Prompt Agent (direct unit tests)
+
+    [Fact]
+    public void Mode2_PromptAgent_StampsFoundryProviderNameAndDefaultModelId()
+    {
+        // Arrange
+        var projectClient = CreateProjectClient();
+        var agentRef = new AgentReference("agent-name", "1");
+
+        // Act
+        var chatClient = new FoundryChatClient(projectClient, agentRef, defaultModelId: "gpt-4o", baseChatOptions: null);
+
+        // Assert
+        var metadata = chatClient.GetService<ChatClientMetadata>();
+        Assert.NotNull(metadata);
+        Assert.Equal("microsoft.foundry", metadata!.ProviderName);
+        Assert.Equal("gpt-4o", metadata.DefaultModelId);
+    }
+
+    [Fact]
+    public void Mode2_PromptAgent_ExposesAgentReference_ViaGetService()
+    {
+        // Arrange
+        var projectClient = CreateProjectClient();
+        var agentRef = new AgentReference("agent-name", "1");
+
+        // Act
+        var chatClient = new FoundryChatClient(projectClient, agentRef, defaultModelId: null, baseChatOptions: null);
+
+        // Assert
+        Assert.Same(agentRef, chatClient.GetService<AgentReference>());
+        Assert.Same(projectClient, chatClient.GetService<AIProjectClient>());
+        // ProjectOpenAIClient is intentionally NOT exposed via GetService — see comment in
+        // Mode1_ResponsesAgent_ExposesAIProjectClient_ViaGetService.
+        Assert.Null(chatClient.GetService<ProjectOpenAIClient>());
+        // Version/Record were not provided via this ctor.
+        Assert.Null(chatClient.GetService<ProjectsAgentVersion>());
+        Assert.Null(chatClient.GetService<ProjectsAgentRecord>());
+    }
+
+    [Fact]
+    public void Mode2_PromptAgent_PopulatesAgentNameFromAgentReference()
+    {
+        // Arrange
+        var projectClient = CreateProjectClient();
+        var agentRef = new AgentReference("my-server-side-agent", "1");
+
+        // Act
+        var chatClient = new FoundryChatClient(projectClient, agentRef, defaultModelId: null, baseChatOptions: null);
+
+        // Assert: AgentName is general-purpose across the Prompt Agent (Mode 2) and Agent Endpoint (Mode 3) modes. In the Prompt Agent mode (Mode 2) it mirrors
+        // AgentReference.Name so callers have a uniform handle regardless of construction mode.
+        Assert.Equal("my-server-side-agent", chatClient.AgentName);
+    }
+
+    [Fact]
+    public void Mode2_PromptAgent_AllowsNullDefaultModelIdAndBaseChatOptions()
+    {
+        // Arrange
+        var projectClient = CreateProjectClient();
+        var agentRef = new AgentReference("agent-name", "1");
+
+        // Act + Assert: must not throw; defaultModelId and baseChatOptions are optional.
+        var chatClient = new FoundryChatClient(projectClient, agentRef, defaultModelId: null, baseChatOptions: null);
+        Assert.NotNull(chatClient);
+    }
+
+    [Fact]
+    public void Mode2_PromptAgent_ThrowsOnNullAgentReference()
+        => Assert.Throws<ArgumentNullException>(() =>
+            new FoundryChatClient(CreateProjectClient(), agentReference: null!, defaultModelId: null, baseChatOptions: null));
+
+    #endregion
+
+    #region the Prompt Agent mode (Mode 2): Prompt Agent end-to-end round-trip via AsAIAgent(AgentReference) extension
+
+    // The end-to-end tests below exercise the same FoundryChatClient mode-2 behaviors above,
+    // but through the public AsAIAgent(AgentReference) extension that constructs a FoundryChatClient
+    // internally. They focus on the conversation-id handling that only manifests through the
+    // ChatClientAgentSession surface, which requires a fully assembled agent rather than a bare
+    // chat client.
+
+    /// <summary>
+    /// Verify that after the first RunAsync, the session's ConversationId is set from the
+    /// response, and subsequent requests include that conversation ID automatically.
+    /// </summary>
+    [Fact]
+    public async Task EndToEnd_AgentReference_UsesDefaultConversationIdAsync()
+    {
+        // Arrange
+        var responsesRequestCount = 0;
+        using var httpHandler = new HttpHandlerAssert(async (request) =>
+        {
+            if (request.Method == HttpMethod.Post && request.RequestUri!.PathAndQuery.Contains("/responses"))
+            {
+                responsesRequestCount++;
+
+                // Assert: On the second Responses API call, verify the conversation ID
+                // from the first response is automatically included in the request body.
+                if (responsesRequestCount == 2 && request.Content is not null)
+                {
+                    var requestBody = await request.Content.ReadAsStringAsync().ConfigureAwait(false);
+                    Assert.Contains("resp_0888a", requestBody);
+                }
+
+                return new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent(TestDataUtil.GetOpenAIDefaultResponseJson(), Encoding.UTF8, "application/json") };
+            }
+
+            return new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent(TestDataUtil.GetAgentResponseJson(), Encoding.UTF8, "application/json") };
+        });
+
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(httpHandler);
+#pragma warning restore CA5399
+
+        AIProjectClient projectClient = new(
+            new Uri("https://test.openai.azure.com/"),
+            new FakeAuthenticationTokenProvider(),
+            new AIProjectClientOptions() { Transport = new HttpClientPipelineTransport(httpClient) });
+
+        var agent = projectClient.AsAIAgent(new AgentReference("agent-name"));
+
+        // Act
+        var session = await agent.CreateSessionAsync();
+        await agent.RunAsync("Hello", session);
+        await agent.RunAsync("Follow up", session);
+
+        // Assert
+        Assert.Equal(2, responsesRequestCount);
+        var chatClientSession = Assert.IsType<ChatClientAgentSession>(session);
+        Assert.Equal("resp_0888a46cbf2b1ff3006914596e05d08195a77c3f5187b769a7", chatClientSession.ConversationId);
+    }
+
+    /// <summary>
+    /// Verify that when the chat client doesn't have a default "conv_" conversation id, the chat client still uses the conversation ID in HTTP requests.
+    /// </summary>
+    [Fact]
+    public async Task EndToEnd_AgentReference_UsesPerRequestConversationId_WhenNoDefaultConversationIdIsProvidedAsync()
+    {
+        // Arrange
+        var requestTriggered = false;
+        using var httpHandler = new HttpHandlerAssert(async (request) =>
+        {
+            if (request.Method == HttpMethod.Post && request.RequestUri!.PathAndQuery.Contains("/responses"))
+            {
+                requestTriggered = true;
+
+                // Assert
+                if (request.Content is not null)
+                {
+                    var requestBody = await request.Content.ReadAsStringAsync().ConfigureAwait(false);
+                    Assert.Contains("conv_12345", requestBody);
+                }
+
+                return new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent(TestDataUtil.GetOpenAIDefaultResponseJson(), Encoding.UTF8, "application/json") };
+            }
+
+            return new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent(TestDataUtil.GetAgentResponseJson(), Encoding.UTF8, "application/json") };
+        });
+
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(httpHandler);
+#pragma warning restore CA5399
+
+        AIProjectClient projectClient = new(
+            new Uri("https://test.openai.azure.com/"),
+            new FakeAuthenticationTokenProvider(),
+            new AIProjectClientOptions() { Transport = new HttpClientPipelineTransport(httpClient) });
+
+        var agent = projectClient.AsAIAgent(new AgentReference("agent-name"));
+
+        // Act
+        var session = await agent.CreateSessionAsync();
+        await agent.RunAsync("Hello", session, options: new ChatClientAgentRunOptions() { ChatOptions = new() { ConversationId = "conv_12345" } });
+
+        Assert.True(requestTriggered);
+        var chatClientSession = Assert.IsType<ChatClientAgentSession>(session);
+        Assert.Equal("conv_12345", chatClientSession.ConversationId);
+    }
+
+    /// <summary>
+    /// Verify that even when the chat client has a default conversation id, the chat client will prioritize the per-request conversation id provided in HTTP requests.
+    /// </summary>
+    [Fact]
+    public async Task EndToEnd_AgentReference_UsesPerRequestConversationId_EvenWhenDefaultConversationIdIsProvidedAsync()
+    {
+        // Arrange
+        var requestTriggered = false;
+        using var httpHandler = new HttpHandlerAssert(async (request) =>
+        {
+            if (request.Method == HttpMethod.Post && request.RequestUri!.PathAndQuery.Contains("/responses"))
+            {
+                requestTriggered = true;
+
+                // Assert
+                if (request.Content is not null)
+                {
+                    var requestBody = await request.Content.ReadAsStringAsync().ConfigureAwait(false);
+                    Assert.Contains("conv_12345", requestBody);
+                }
+
+                return new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent(TestDataUtil.GetOpenAIDefaultResponseJson(), Encoding.UTF8, "application/json") };
+            }
+
+            return new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent(TestDataUtil.GetAgentResponseJson(), Encoding.UTF8, "application/json") };
+        });
+
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(httpHandler);
+#pragma warning restore CA5399
+
+        AIProjectClient projectClient = new(
+            new Uri("https://test.openai.azure.com/"),
+            new FakeAuthenticationTokenProvider(),
+            new AIProjectClientOptions() { Transport = new HttpClientPipelineTransport(httpClient) });
+
+        var agent = projectClient.AsAIAgent(new AgentReference("agent-name"));
+
+        // Act
+        var session = await agent.CreateSessionAsync();
+        await agent.RunAsync("Hello", session, options: new ChatClientAgentRunOptions() { ChatOptions = new() { ConversationId = "conv_12345" } });
+
+        Assert.True(requestTriggered);
+        var chatClientSession = Assert.IsType<ChatClientAgentSession>(session);
+        Assert.Equal("conv_12345", chatClientSession.ConversationId);
+    }
+
+    /// <summary>
+    /// Verify that when the chat client is provided without a "conv_" prefixed conversation ID, the chat client uses the previous conversation ID in HTTP requests.
+    /// </summary>
+    [Fact]
+    public async Task EndToEnd_AgentReference_UsesPreviousResponseId_WhenConversationIsNotPrefixedAsConvAsync()
+    {
+        // Arrange
+        var requestTriggered = false;
+        using var httpHandler = new HttpHandlerAssert(async (request) =>
+        {
+            if (request.Method == HttpMethod.Post && request.RequestUri!.PathAndQuery.Contains("/responses"))
+            {
+                requestTriggered = true;
+
+                // Assert
+                if (request.Content is not null)
+                {
+                    var requestBody = await request.Content.ReadAsStringAsync().ConfigureAwait(false);
+                    Assert.Contains("resp_0888a", requestBody);
+                }
+
+                return new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent(TestDataUtil.GetOpenAIDefaultResponseJson(), Encoding.UTF8, "application/json") };
+            }
+
+            return new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent(TestDataUtil.GetAgentResponseJson(), Encoding.UTF8, "application/json") };
+        });
+
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(httpHandler);
+#pragma warning restore CA5399
+
+        AIProjectClient projectClient = new(
+            new Uri("https://test.openai.azure.com/"),
+            new FakeAuthenticationTokenProvider(),
+            new AIProjectClientOptions() { Transport = new HttpClientPipelineTransport(httpClient) });
+
+        var agent = projectClient.AsAIAgent(new AgentReference("agent-name"));
+
+        // Act
+        var session = await agent.CreateSessionAsync();
+        await agent.RunAsync("Hello", session, options: new ChatClientAgentRunOptions() { ChatOptions = new() { ConversationId = "resp_0888a" } });
+
+        Assert.True(requestTriggered);
+        var chatClientSession = Assert.IsType<ChatClientAgentSession>(session);
+        Assert.Equal("resp_0888a46cbf2b1ff3006914596e05d08195a77c3f5187b769a7", chatClientSession.ConversationId);
+    }
+
+    #endregion
+
+    #region the Agent Endpoint mode (Mode 3): Agent Endpoint
+
+    [Fact]
+    public void Mode3_AgentEndpoint_ParsesAgentNameFromUrl()
+    {
+        // Arrange + Act
+        var chatClient = new FoundryChatClient(
+            agentEndpoint: new Uri("https://example.com/api/projects/myproj/agents/myagent/endpoint/protocols/openai"),
+            credential: new FakeAuthenticationTokenProvider(),
+            clientOptions: null);
+
+        // Assert
+        Assert.Equal("myagent", chatClient.AgentName);
+    }
+
+    [Fact]
+    public void Mode3_AgentEndpoint_StampsFoundryProviderName()
+    {
+        // Act
+        var chatClient = new FoundryChatClient(
+            agentEndpoint: new Uri("https://example.com/api/projects/myproj/agents/myagent/endpoint/protocols/openai"),
+            credential: new FakeAuthenticationTokenProvider(),
+            clientOptions: null);
+
+        // Assert
+        var metadata = chatClient.GetService<ChatClientMetadata>();
+        Assert.NotNull(metadata);
+        Assert.Equal("microsoft.foundry", metadata!.ProviderName);
+        // No model id is knowable from the URL alone.
+        Assert.Null(metadata.DefaultModelId);
+    }
+
+    [Fact]
+    public void Mode3_AgentEndpoint_ExposesProjectOpenAIClientAndAIProjectClient()
+    {
+        // Act
+        var chatClient = new FoundryChatClient(
+            agentEndpoint: new Uri("https://example.com/api/projects/myproj/agents/myagent/endpoint/protocols/openai"),
+            credential: new FakeAuthenticationTokenProvider(),
+            clientOptions: null);
+
+        // Assert
+        // ProjectOpenAIClient is intentionally NOT exposed via GetService — callers retrieve
+        // it from the AIProjectClient themselves (aiProjectClient.GetProjectOpenAIClient()).
+        Assert.Null(chatClient.GetService<ProjectOpenAIClient>());
+        // After the materialization change, the Agent Endpoint mode (Mode 3) also exposes a working AIProjectClient
+        // built from the parsed project root. This makes the helper surface symmetric across
+        // all three construction modes.
+        Assert.NotNull(chatClient.GetService<AIProjectClient>());
+        Assert.Null(chatClient.GetService<AgentReference>());
+        Assert.Null(chatClient.GetService<ProjectsAgentVersion>());
+        Assert.Null(chatClient.GetService<ProjectsAgentRecord>());
+    }
+
+    [Fact]
+    public void Mode3_AgentEndpoint_MaterializedAIProjectClient_TargetsParsedProjectRoot()
+    {
+        // The Agent Endpoint mode (Mode 3) ctor must derive the project root from the agent endpoint URL and
+        // construct the AIProjectClient against that root, NOT the agent endpoint itself.
+        var agentEndpoint = new Uri("https://example.com/api/projects/myproj/agents/myagent/endpoint/protocols/openai");
+        var chatClient = new FoundryChatClient(
+            agentEndpoint: agentEndpoint,
+            credential: new FakeAuthenticationTokenProvider(),
+            clientOptions: null);
+
+        var aiProjectClient = chatClient.GetService<AIProjectClient>();
+        Assert.NotNull(aiProjectClient);
+        // AIProjectClient does not expose its endpoint publicly, so we rely on reflection on
+        // the well-known private field. If the SDK field shape changes this guard fails loudly.
+        var field = typeof(AIProjectClient).GetField("_endpoint", BindingFlags.Instance | BindingFlags.NonPublic);
+        Assert.NotNull(field);
+        var actualEndpoint = (Uri)field!.GetValue(aiProjectClient!)!;
+        Assert.Equal("https://example.com/api/projects/myproj", actualEndpoint.AbsoluteUri.TrimEnd('/'));
+    }
+
+    [Fact]
+    public void Mode3_AgentEndpoint_MaterializedAIProjectClient_IsReusedAcrossGetServiceCalls()
+    {
+        // Repeated GetService<AIProjectClient>() calls must return the same instance — the
+        // materialized client is cached in the existing _aiProjectClient field, not built on
+        // demand each call.
+        var chatClient = new FoundryChatClient(
+            agentEndpoint: new Uri("https://example.com/api/projects/myproj/agents/myagent/endpoint/protocols/openai"),
+            credential: new FakeAuthenticationTokenProvider(),
+            clientOptions: null);
+
+        var first = chatClient.GetService<AIProjectClient>();
+        var second = chatClient.GetService<AIProjectClient>();
+        Assert.NotNull(first);
+        Assert.Same(first, second);
+    }
+
+    [Fact]
+    public void Mode1_ResponsesAgent_AIProjectClient_IsTheSuppliedInstance()
+    {
+        // Regression check: the Responses Agent mode (Mode 1) must continue to expose the AIProjectClient the caller
+        // supplied via the constructor, NOT a freshly-materialized one.
+        var supplied = CreateProjectClient();
+        var chatClient = new FoundryChatClient(supplied, "gpt-4o-mini");
+        Assert.Same(supplied, chatClient.GetService<AIProjectClient>());
+    }
+
+    [Fact]
+    public void Mode2_PromptAgent_AIProjectClient_IsTheSuppliedInstance()
+    {
+        // Regression check: the Prompt Agent mode (Mode 2) must continue to expose the AIProjectClient the caller
+        // supplied via the constructor.
+        var supplied = CreateProjectClient();
+        var agentRef = new AgentReference("agent-name", "1");
+        var chatClient = new FoundryChatClient(supplied, agentRef, defaultModelId: null, baseChatOptions: null);
+        Assert.Same(supplied, chatClient.GetService<AIProjectClient>());
+    }
+
+    [Fact]
+    public void Mode3_AgentEndpoint_ThrowsOnNullEndpoint()
+        => Assert.Throws<ArgumentNullException>(() =>
+            new FoundryChatClient(agentEndpoint: null!, credential: new FakeAuthenticationTokenProvider(), clientOptions: null));
+
+    [Fact]
+    public void Mode3_AgentEndpoint_ThrowsOnNullCredential()
+        => Assert.Throws<ArgumentNullException>(() =>
+            new FoundryChatClient(
+                agentEndpoint: new Uri("https://example.com/api/projects/myproj/agents/myagent/endpoint/protocols/openai"),
+                credential: null!,
+                clientOptions: null));
+
+    #endregion
+
+    #region ParseAgentEndpoint URL parsing
+
+    [Fact]
+    public void ParseAgentEndpoint_HappyPath_ReturnsAgentNameAndProjectRoot()
+    {
+        // Act
+        var (agentName, projectRoot) = FoundryChatClient.ParseAgentEndpoint(
+            new Uri("https://example.com/api/projects/myproj/agents/myagent/endpoint/protocols/openai"));
+
+        // Assert
+        Assert.Equal("myagent", agentName);
+        Assert.Equal("https://example.com/api/projects/myproj", projectRoot.AbsoluteUri.TrimEnd('/'));
+    }
+
+    [Fact]
+    public void ParseAgentEndpoint_TolerantOfTrailingSlash()
+    {
+        // Act
+        var (agentName, _) = FoundryChatClient.ParseAgentEndpoint(
+            new Uri("https://example.com/api/projects/myproj/agents/myagent/endpoint/protocols/openai/"));
+
+        // Assert
+        Assert.Equal("myagent", agentName);
+    }
+
+    [Fact]
+    public void ParseAgentEndpoint_TolerantOfCaseDifferencesOnAgentsSegment()
+    {
+        // Act
+        var (agentName, _) = FoundryChatClient.ParseAgentEndpoint(
+            new Uri("https://example.com/api/projects/myproj/AGENTS/myagent/endpoint/protocols/openai"));
+
+        // Assert
+        Assert.Equal("myagent", agentName);
+    }
+
+    [Fact]
+    public void ParseAgentEndpoint_StripsQueryAndFragment()
+    {
+        // Act
+        var (_, projectRoot) = FoundryChatClient.ParseAgentEndpoint(
+            new Uri("https://example.com/api/projects/myproj/agents/myagent/endpoint/protocols/openai?api-version=v1#frag"));
+
+        // Assert
+        Assert.Equal(string.Empty, projectRoot.Query);
+        Assert.Equal(string.Empty, projectRoot.Fragment);
+    }
+
+    [Fact]
+    public void ParseAgentEndpoint_ThrowsOnMissingAgentsSegment()
+        => Assert.Throws<ArgumentException>(() =>
+            FoundryChatClient.ParseAgentEndpoint(new Uri("https://example.com/api/projects/myproj/anyseg/myagent/endpoint/protocols/openai")));
+
+    [Fact]
+    public void ParseAgentEndpoint_ThrowsOnWrongSuffix()
+        => Assert.Throws<ArgumentException>(() =>
+            FoundryChatClient.ParseAgentEndpoint(new Uri("https://example.com/api/projects/myproj/agents/myagent/wrong/suffix")));
+
+    [Fact]
+    public void ParseAgentEndpoint_ThrowsOnNullUri()
+        => Assert.Throws<ArgumentNullException>(() => FoundryChatClient.ParseAgentEndpoint(null!));
+
+    #endregion
+
+    #region AgentFrameworkUserAgentPolicy + ServedModelPolicy registration + dedup
+
+    [Fact]
+    public void Register_AgentFrameworkUserAgentPolicy_OnUnderlyingOpenAIRequestPolicies()
+    {
+        // Arrange + Act: constructing a FoundryChatClient should register the
+        // AgentFrameworkUserAgentPolicy and ServedModelPolicy on the inner chat client's OpenAIRequestPolicies.
+        var chatClient = new FoundryChatClient(CreateProjectClient(), "gpt-4o-mini");
+
+        // Assert: the inner chat client (MEAI's OpenAIResponsesChatClient) exposes
+        // OpenAIRequestPolicies via GetService, and both policies are present in its entries.
+        var policies = chatClient.GetService<OpenAIRequestPolicies>();
+        Assert.NotNull(policies);
+        Assert.Equal(2, EntriesCount(policies!));
+    }
+
+    [Fact]
+    public void Register_AgentFrameworkUserAgentPolicy_IsDedupedAcrossMultipleClients_OnSharedInner()
+    {
+        // Arrange: construct via the ProjectsAgentVersion mode-2 variant, which chains via
+        // :this(...) into the AgentReference ctor. If the policy registration code were
+        // inadvertently called twice along the chain, we would see more than 2 entries.
+        var projectClient = CreateProjectClient();
+        var agentVersion = ModelReaderWriter.Read<ProjectsAgentVersion>(
+            BinaryData.FromString(TestDataUtil.GetAgentVersionResponseJson()))!;
+
+        // Act
+        var chatClient = new FoundryChatClient(projectClient, agentVersion, baseChatOptions: null);
+
+        // Assert: even though the version variant funnels through the AgentReference ctor
+        // via :this(...), each policy is registered exactly once on the inner pipeline.
+        var policies = chatClient.GetService<OpenAIRequestPolicies>();
+        Assert.NotNull(policies);
+        Assert.Equal(2, EntriesCount(policies!));
+        Assert.Same(agentVersion, chatClient.GetService<ProjectsAgentVersion>());
+        Assert.NotNull(chatClient.GetService<AgentReference>());
+    }
+
+    #endregion
+
+    #region Helpers
+
+    private static AIProjectClient CreateProjectClient()
+        => new(
+            new Uri("https://test.openai.azure.com/"),
+            new FakeAuthenticationTokenProvider(),
+            new AIProjectClientOptions { Transport = new HttpClientPipelineTransport(new HttpClient()) });
+
+    private static int EntriesCount(OpenAIRequestPolicies policies)
+    {
+        var field = typeof(OpenAIRequestPolicies).GetField("_entries", BindingFlags.Instance | BindingFlags.NonPublic);
+        Assert.NotNull(field);
+        var arr = (Array)field!.GetValue(policies)!;
+        return arr.Length;
+    }
+
+    #endregion
+}
+#pragma warning restore CS0618
@@ -0,0 +1,660 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.ClientModel.Primitives;
+using System.Collections.Generic;
+using System.IO;
+using System.Net;
+using System.Net.Http;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+using Azure.AI.Extensions.OpenAI;
+using Azure.AI.Projects;
+using OpenAI.Files;
+
+#pragma warning disable OPENAI001, CS0618
+
+namespace Microsoft.Agents.AI.Foundry.UnitTests;
+
+/// <summary>
+/// Unit tests for the file and vector-store helper methods on <see cref="FoundryChatClient"/>.
+/// Covers all four methods across the three FoundryChatClient construction modes plus argument
+/// validation, cancellation, and request-body shape on the wire.
+/// </summary>
+public sealed class FoundryChatClientVectorStoreTests
+{
+    // ----- Construction helpers shared by every test in this file -----
+
+    private static (FoundryChatClient ChatClient, RequestRecorder Recorder) CreateMode1(string modelId = "gpt-4o-mini", string? responseBody = null)
+    {
+        var recorder = new RequestRecorder(responseBody);
+#pragma warning disable CA5399
+        var httpClient = new HttpClient(recorder);
+#pragma warning restore CA5399
+        var projectClient = new AIProjectClient(
+            new Uri("https://test.openai.azure.com/"),
+            new FakeAuthenticationTokenProvider(),
+            new AIProjectClientOptions { Transport = new HttpClientPipelineTransport(httpClient) });
+        return (new FoundryChatClient(projectClient, modelId), recorder);
+    }
+
+    private static (FoundryChatClient ChatClient, RequestRecorder Recorder) CreateMode2(string? responseBody = null)
+    {
+        var recorder = new RequestRecorder(responseBody);
+#pragma warning disable CA5399
+        var httpClient = new HttpClient(recorder);
+#pragma warning restore CA5399
+        var projectClient = new AIProjectClient(
+            new Uri("https://test.openai.azure.com/"),
+            new FakeAuthenticationTokenProvider(),
+            new AIProjectClientOptions { Transport = new HttpClientPipelineTransport(httpClient) });
+        var agentRef = new AgentReference("agent-name", "1");
+        return (new FoundryChatClient(projectClient, agentRef, defaultModelId: "gpt-4o", baseChatOptions: null), recorder);
+    }
+
+    private static string MakeTempFile(string contents = "hello world")
+    {
+        var path = Path.Combine(Path.GetTempPath(), $"fcc-test-{Guid.NewGuid():N}.txt");
+        File.WriteAllText(path, contents);
+        return path;
+    }
+
+    // ----- UploadFileAsync -----
+
+    [Fact]
+    public async Task UploadFileAsync_Mode1_UploadsViaProjectOpenAIClientAsync()
+    {
+        var (chatClient, recorder) = CreateMode1(responseBody: FakeFileJson("file_abc"));
+        var path = MakeTempFile();
+        try
+        {
+            var result = await chatClient.UploadFileAsync(path, FileUploadPurpose.Assistants);
+
+            Assert.Equal("file_abc", result.Id);
+            Assert.NotEmpty(recorder.Requests);
+            Assert.EndsWith("/files", recorder.Requests[0].PathAndQuery.TrimEnd('/').Split('?')[0]);
+        }
+        finally { File.Delete(path); }
+    }
+
+    [Fact]
+    public async Task UploadFileAsync_Mode2_UploadsViaProjectOpenAIClientAsync()
+    {
+        var (chatClient, recorder) = CreateMode2(responseBody: FakeFileJson("file_xyz"));
+        var path = MakeTempFile();
+        try
+        {
+            var result = await chatClient.UploadFileAsync(path, FileUploadPurpose.Assistants);
+            Assert.Equal("file_xyz", result.Id);
+            Assert.Contains(recorder.Requests, r => r.PathAndQuery.Contains("/files"));
+        }
+        finally { File.Delete(path); }
+    }
+
+    [Fact]
+    public async Task UploadFileAsync_Mode3_UploadsViaMaterializedProjectClientAsync()
+    {
+        // Q-E: Mode 3 (Agent Endpoint) now honors caller-supplied transports via
+        // ProjectOpenAIClientOptions.Transport, so we can use a fake transport here instead of
+        // depending on DNS/network availability against example.com.
+        var sawUpload = false;
+        using var handler = new HttpHandlerAssert(req =>
+        {
+            if (req.Method == HttpMethod.Post && req.RequestUri!.AbsolutePath.Contains("/files", StringComparison.Ordinal))
+            {
+                sawUpload = true;
+                return MakeJsonResponse(FakeFileJson("file_mode3"));
+            }
+            return MakeJsonResponse("{}");
+        });
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+        var chatClient = new FoundryChatClient(
+            agentEndpoint: new Uri("https://example.com/api/projects/myproj/agents/myagent/endpoint/protocols/openai"),
+            credential: new FakeAuthenticationTokenProvider(),
+            clientOptions: new ProjectOpenAIClientOptions { Transport = new HttpClientPipelineTransport(httpClient) });
+
+        var path = MakeTempFile();
+        try
+        {
+            var result = await chatClient.UploadFileAsync(path, FileUploadPurpose.Assistants, CancellationToken.None);
+            Assert.True(sawUpload);
+            Assert.Equal("file_mode3", result.Id);
+        }
+        finally { File.Delete(path); }
+    }
+
+    [Fact]
+    public async Task UploadFileAsync_NullFilePath_ThrowsArgumentNullExceptionAsync()
+    {
+        var (chatClient, _) = CreateMode1();
+        await Assert.ThrowsAsync<ArgumentNullException>(() =>
+            chatClient.UploadFileAsync(null!, FileUploadPurpose.Assistants));
+    }
+
+    [Fact]
+    public async Task UploadFileAsync_FileNotFound_ThrowsFileNotFoundExceptionAsync()
+    {
+        var (chatClient, _) = CreateMode1();
+        var missing = Path.Combine(Path.GetTempPath(), $"does-not-exist-{Guid.NewGuid():N}.txt");
+        await Assert.ThrowsAsync<FileNotFoundException>(() =>
+            chatClient.UploadFileAsync(missing, FileUploadPurpose.Assistants));
+    }
+
+    [Fact]
+    public async Task UploadFileAsync_HonorsCancellationAsync()
+    {
+        // Cancellation propagation through the OpenAI SDK pipeline surfaces different exception
+        // types depending on the framework target (OperationCanceledException on net10.0,
+        // ObjectDisposedException at the transport layer on net472). Asserting on the exact
+        // exception class is brittle; assert only that the call throws when the token is
+        // pre-cancelled.
+        var (chatClient, _) = CreateMode1(responseBody: FakeFileJson("file_abc"));
+        var path = MakeTempFile();
+        try
+        {
+            using var cts = new CancellationTokenSource();
+            cts.Cancel();
+            await Assert.ThrowsAnyAsync<Exception>(() =>
+                chatClient.UploadFileAsync(path, FileUploadPurpose.Assistants, cts.Token));
+        }
+        finally { File.Delete(path); }
+    }
+
+    // ----- DeleteFileAsync -----
+
+    [Fact]
+    public async Task DeleteFileAsync_Mode1_CallsDeleteOnFileClientAsync()
+    {
+        var (chatClient, recorder) = CreateMode1(responseBody: FakeFileDeletedJson("file_abc"));
+        await chatClient.DeleteFileAsync("file_abc");
+        Assert.Contains(recorder.Requests, r => r.Method == "DELETE" && r.PathAndQuery.Contains("/files/file_abc"));
+    }
+
+    [Fact]
+    public async Task DeleteFileAsync_Mode2_CallsDeleteOnFileClientAsync()
+    {
+        var (chatClient, recorder) = CreateMode2(responseBody: FakeFileDeletedJson("file_xyz"));
+        await chatClient.DeleteFileAsync("file_xyz");
+        Assert.Contains(recorder.Requests, r => r.Method == "DELETE" && r.PathAndQuery.Contains("/files/file_xyz"));
+    }
+
+    [Fact]
+    public async Task DeleteFileAsync_NullId_ThrowsArgumentExceptionAsync()
+    {
+        var (chatClient, _) = CreateMode1();
+        await Assert.ThrowsAnyAsync<ArgumentException>(() => chatClient.DeleteFileAsync(null!));
+    }
+
+    [Fact]
+    public async Task DeleteFileAsync_EmptyId_ThrowsArgumentExceptionAsync()
+    {
+        var (chatClient, _) = CreateMode1();
+        await Assert.ThrowsAnyAsync<ArgumentException>(() => chatClient.DeleteFileAsync(""));
+    }
+
+    [Fact]
+    public async Task DeleteFileAsync_HonorsCancellationAsync()
+    {
+        // Verify the cancellation token reaches the HTTP pipeline by having the handler
+        // throw OperationCanceledException when the token is cancelled before the request.
+        // This is more robust than asserting on the exact exception the SDK surfaces, which
+        // depends on internal pipeline plumbing.
+        var observedToken = CancellationToken.None;
+        using var handler = new HttpHandlerAssert(async req =>
+        {
+            // We don't have direct access to the SDK's CancellationToken here; instead, sleep
+            // briefly to give the caller's pre-cancellation a chance to be picked up by the
+            // transport. If cancellation reached the pipeline, the await on this handler call
+            // would surface OperationCanceledException; if not, the response is returned.
+            await Task.Delay(50).ConfigureAwait(false);
+            return new HttpResponseMessage(HttpStatusCode.OK)
+            {
+                Content = new StringContent(FakeFileDeletedJson("file_abc"), Encoding.UTF8, "application/json"),
+            };
+        });
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+        var projectClient = new AIProjectClient(
+            new Uri("https://test.openai.azure.com/"),
+            new FakeAuthenticationTokenProvider(),
+            new AIProjectClientOptions { Transport = new HttpClientPipelineTransport(httpClient) });
+        var chatClient = new FoundryChatClient(projectClient, "gpt-4o-mini");
+
+        using var cts = new CancellationTokenSource();
+        cts.Cancel();
+        // Any throw is acceptable evidence that cancellation was honored. The SDK's exact
+        // exception surface for pre-cancelled tokens is an implementation detail of
+        // System.ClientModel's pipeline and may differ between versions.
+        await Assert.ThrowsAnyAsync<Exception>(() => chatClient.DeleteFileAsync("file_abc", cts.Token));
+    }
+
+    // ----- CreateVectorStoreAsync -----
+
+    [Fact]
+    public async Task CreateVectorStoreAsync_UploadsThenCreates_WithFileIds_ReturnsVectorStoreAsync()
+    {
+        // Each file POST returns a distinct file id; the recorder dispatches on URL to differentiate.
+        var fileCount = 0;
+        using var handler = new HttpHandlerAssert(async req =>
+        {
+            var body = req.Content is null ? "" : await req.Content.ReadAsStringAsync().ConfigureAwait(false);
+            if (req.RequestUri!.AbsolutePath.Contains("/files") && req.Method == HttpMethod.Post)
+            {
+                fileCount++;
+                return MakeJsonResponse(FakeFileJson($"file_{fileCount}"));
+            }
+            if (req.RequestUri.AbsolutePath.Contains("/vector_stores") && req.Method == HttpMethod.Post)
+            {
+                Assert.Contains("file_1", body);
+                Assert.Contains("file_2", body);
+                Assert.Contains("knowledge-base", body);
+                return MakeJsonResponse(FakeVectorStoreJson("vs_abc", name: "knowledge-base"));
+            }
+            return MakeJsonResponse("{}");
+        });
+
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+        var projectClient = new AIProjectClient(
+            new Uri("https://test.openai.azure.com/"),
+            new FakeAuthenticationTokenProvider(),
+            new AIProjectClientOptions { Transport = new HttpClientPipelineTransport(httpClient) });
+        var chatClient = new FoundryChatClient(projectClient, "gpt-4o-mini");
+
+        var pathA = MakeTempFile("alpha");
+        var pathB = MakeTempFile("beta");
+        try
+        {
+            var store = await chatClient.CreateVectorStoreAsync("knowledge-base", new[] { pathA, pathB });
+            Assert.Equal("vs_abc", store.Id);
+            Assert.Equal(2, fileCount);
+        }
+        finally { File.Delete(pathA); File.Delete(pathB); }
+    }
+
+    [Fact]
+    public async Task CreateVectorStoreAsync_WithExpiresAfter_SerializesLastActiveAtAnchorAsync()
+    {
+        string? vectorStoreBody = null;
+        using var handler = new HttpHandlerAssert(async req =>
+        {
+            if (req.RequestUri!.AbsolutePath.Contains("/vector_stores") && req.Method == HttpMethod.Post)
+            {
+                vectorStoreBody = req.Content is null ? "" : await req.Content.ReadAsStringAsync().ConfigureAwait(false);
+                return MakeJsonResponse(FakeVectorStoreJson("vs_abc", name: "x"));
+            }
+            return MakeJsonResponse("{}");
+        });
+
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+        var projectClient = new AIProjectClient(
+            new Uri("https://test.openai.azure.com/"),
+            new FakeAuthenticationTokenProvider(),
+            new AIProjectClientOptions { Transport = new HttpClientPipelineTransport(httpClient) });
+        var chatClient = new FoundryChatClient(projectClient, "gpt-4o-mini");
+
+        await chatClient.CreateVectorStoreAsync("x", Array.Empty<string>(), expiresAfter: TimeSpan.FromDays(7));
+
+        Assert.NotNull(vectorStoreBody);
+        Assert.Contains("\"expires_after\"", vectorStoreBody);
+        Assert.Contains("\"last_active_at\"", vectorStoreBody);
+        Assert.Contains("\"days\":7", vectorStoreBody);
+    }
+
+    [Fact]
+    public async Task CreateVectorStoreAsync_WithNullExpiresAfter_OmitsExpirationPolicyAsync()
+    {
+        string? vectorStoreBody = null;
+        using var handler = new HttpHandlerAssert(async req =>
+        {
+            if (req.RequestUri!.AbsolutePath.Contains("/vector_stores") && req.Method == HttpMethod.Post)
+            {
+                vectorStoreBody = req.Content is null ? "" : await req.Content.ReadAsStringAsync().ConfigureAwait(false);
+                return MakeJsonResponse(FakeVectorStoreJson("vs_abc", name: "x"));
+            }
+            return MakeJsonResponse("{}");
+        });
+
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+        var projectClient = new AIProjectClient(
+            new Uri("https://test.openai.azure.com/"),
+            new FakeAuthenticationTokenProvider(),
+            new AIProjectClientOptions { Transport = new HttpClientPipelineTransport(httpClient) });
+        var chatClient = new FoundryChatClient(projectClient, "gpt-4o-mini");
+
+        await chatClient.CreateVectorStoreAsync("x", Array.Empty<string>(), expiresAfter: null);
+
+        Assert.NotNull(vectorStoreBody);
+        Assert.DoesNotContain("\"expires_after\"", vectorStoreBody);
+    }
+
+    [Fact]
+    public async Task CreateVectorStoreAsync_EmptyFilesList_CreatesEmptyStoreAsync()
+    {
+        var (chatClient, _) = CreateMode1(responseBody: FakeVectorStoreJson("vs_empty", name: "x"));
+        var store = await chatClient.CreateVectorStoreAsync("x", Array.Empty<string>());
+        Assert.Equal("vs_empty", store.Id);
+    }
+
+    [Fact]
+    public async Task CreateVectorStoreAsync_NullName_ThrowsArgumentExceptionAsync()
+    {
+        var (chatClient, _) = CreateMode1();
+        await Assert.ThrowsAnyAsync<ArgumentException>(() =>
+            chatClient.CreateVectorStoreAsync(null!, Array.Empty<string>()));
+    }
+
+    [Fact]
+    public async Task CreateVectorStoreAsync_NullFilePaths_ThrowsArgumentNullExceptionAsync()
+    {
+        var (chatClient, _) = CreateMode1();
+        await Assert.ThrowsAsync<ArgumentNullException>(() =>
+            chatClient.CreateVectorStoreAsync("x", filePaths: null!));
+    }
+
+    [Fact]
+    public async Task CreateVectorStoreAsync_HonorsCancellationAsync()
+    {
+        // Same rationale as UploadFileAsync_HonorsCancellationAsync — assert only that any
+        // exception is thrown on a pre-cancelled token.
+        var (chatClient, _) = CreateMode1(responseBody: FakeVectorStoreJson("vs_x", "x"));
+        using var cts = new CancellationTokenSource();
+        cts.Cancel();
+        await Assert.ThrowsAnyAsync<Exception>(() =>
+            chatClient.CreateVectorStoreAsync("x", Array.Empty<string>(), expiresAfter: null, cancellationToken: cts.Token));
+    }
+
+    [Fact]
+    public async Task CreateVectorStoreAsync_PollsUntilStoreLeavesInProgress_Async()
+    {
+        // Q-A regression: when the create response returns status=in_progress, the helper must
+        // poll GET /vector_stores/{id} until status changes before returning. Otherwise the
+        // caller receives a half-built store.
+        var pollCount = 0;
+        using var handler = new HttpHandlerAssert(req =>
+        {
+            if (req.RequestUri!.AbsolutePath.Contains("/vector_stores") && req.Method == HttpMethod.Post)
+            {
+                // First response: status=in_progress.
+                return Task.FromResult(MakeJsonResponse(FakeVectorStoreJsonWithStatus("vs_abc", name: "x", status: "in_progress")));
+            }
+            if (req.RequestUri.AbsolutePath.Contains("/vector_stores/vs_abc") && req.Method == HttpMethod.Get)
+            {
+                pollCount++;
+                // Stay in_progress for two polls, then complete on the third.
+                var status = pollCount < 3 ? "in_progress" : "completed";
+                return Task.FromResult(MakeJsonResponse(FakeVectorStoreJsonWithStatus("vs_abc", name: "x", status: status)));
+            }
+            return Task.FromResult(MakeJsonResponse("{}"));
+        });
+
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+        var projectClient = new AIProjectClient(
+            new Uri("https://test.openai.azure.com/"),
+            new FakeAuthenticationTokenProvider(),
+            new AIProjectClientOptions { Transport = new HttpClientPipelineTransport(httpClient) });
+        var chatClient = new FoundryChatClient(projectClient, "gpt-4o-mini");
+
+        var store = await chatClient.CreateVectorStoreAsync("x", Array.Empty<string>());
+
+        Assert.NotEqual(OpenAI.VectorStores.VectorStoreStatus.InProgress, store.Status);
+        Assert.True(pollCount >= 3, $"Expected at least 3 GET polls before status leaves in_progress; saw {pollCount}.");
+    }
+
+    [Fact]
+    public async Task CreateVectorStoreAsync_PollingTimeout_ThrowsTimeoutExceptionAsync()
+    {
+        // Sergey #2: caller-supplied (or default) polling timeout must surface as TimeoutException
+        // when the vector store never leaves InProgress. Mock keeps the store stuck and we pass
+        // a tiny timeout; cancellation token stays unused so the only path that ends the loop
+        // is the timeout check.
+        using var handler = new HttpHandlerAssert(req =>
+        {
+            if (req.RequestUri!.AbsolutePath.Contains("/vector_stores", StringComparison.Ordinal))
+            {
+                return Task.FromResult(MakeJsonResponse(FakeVectorStoreJsonWithStatus("vs_stuck", name: "x", status: "in_progress")));
+            }
+            return Task.FromResult(MakeJsonResponse("{}"));
+        });
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+        var projectClient = new AIProjectClient(
+            new Uri("https://test.openai.azure.com/"),
+            new FakeAuthenticationTokenProvider(),
+            new AIProjectClientOptions { Transport = new HttpClientPipelineTransport(httpClient) });
+        var chatClient = new FoundryChatClient(projectClient, "gpt-4o-mini");
+
+        var ex = await Assert.ThrowsAsync<TimeoutException>(() =>
+            chatClient.CreateVectorStoreAsync("x", Array.Empty<string>(), expiresAfter: null, pollingTimeout: TimeSpan.FromMilliseconds(500)));
+        Assert.Contains("vs_stuck", ex.Message, StringComparison.Ordinal);
+        Assert.Contains("in-progress", ex.Message, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public async Task CreateVectorStoreAsync_MidUploadFailure_DeletesAlreadyUploadedFilesAsync()
+    {
+        // Q-B regression: when the upload loop throws partway through (e.g. file 3 of 5 is
+        // missing or the network fails), the helper must DELETE the already-uploaded files so
+        // they do not accumulate as orphaned resources. The exception must still propagate.
+        var uploadCount = 0;
+        var deleted = new List<string>();
+        using var handler = new HttpHandlerAssert(req =>
+        {
+            // DELETE first so we don't match the upload-collection /files path against this.
+            if (req.Method == HttpMethod.Delete)
+            {
+                var segments = req.RequestUri!.AbsolutePath.Split('/');
+                var fileId = segments[segments.Length - 1];
+                deleted.Add(fileId);
+                return MakeJsonResponse(FakeFileDeletedJson(fileId));
+            }
+            if (req.Method == HttpMethod.Post && req.RequestUri!.AbsolutePath.Contains("/files", StringComparison.Ordinal))
+            {
+                uploadCount++;
+                if (uploadCount == 3)
+                {
+                    // 400 is non-retriable; the SDK retry policy ignores it. 5xx would trigger
+                    // retries and confuse the assertion on upload count.
+                    return new HttpResponseMessage(HttpStatusCode.BadRequest)
+                    {
+                        Content = new StringContent("{\"error\":{\"code\":\"BadRequest\",\"message\":\"upload-failed-on-3\"}}", Encoding.UTF8, "application/json"),
+                    };
+                }
+                return MakeJsonResponse(FakeFileJson($"file_{uploadCount}"));
+            }
+            return MakeJsonResponse("{}");
+        });
+
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+        var projectClient = new AIProjectClient(
+            new Uri("https://test.openai.azure.com/"),
+            new FakeAuthenticationTokenProvider(),
+            new AIProjectClientOptions { Transport = new HttpClientPipelineTransport(httpClient) });
+        var chatClient = new FoundryChatClient(projectClient, "gpt-4o-mini");
+
+        var paths = new[] { MakeTempFile("a"), MakeTempFile("b"), MakeTempFile("c"), MakeTempFile("d"), MakeTempFile("e") };
+        try
+        {
+            await Assert.ThrowsAnyAsync<Exception>(() => chatClient.CreateVectorStoreAsync("knowledge-base", paths));
+
+            // Three upload attempts: two succeeded, the third threw.
+            Assert.Equal(3, uploadCount);
+            // The two successful uploads must have been deleted as part of best-effort cleanup.
+            Assert.Equal(2, deleted.Count);
+            Assert.Contains("file_1", deleted);
+            Assert.Contains("file_2", deleted);
+        }
+        finally
+        {
+            foreach (var p in paths)
+            {
+                File.Delete(p);
+            }
+        }
+    }
+
+    [Fact]
+    public async Task CreateVectorStoreAsync_MidUploadFailure_CleanupSwallowsDeleteErrorsAsync()
+    {
+        // Q-B follow-on: if a cleanup DELETE itself fails, the helper must still propagate the
+        // original upload exception — not the cleanup exception. The caller cares about the
+        // upload failure; cleanup is best-effort.
+        var uploadCount = 0;
+        using var handler = new HttpHandlerAssert(req =>
+        {
+            if (req.Method == HttpMethod.Delete)
+            {
+                return new HttpResponseMessage(HttpStatusCode.BadRequest)
+                {
+                    Content = new StringContent("{\"error\":{\"code\":\"DeleteFailed\",\"message\":\"cleanup-failed\"}}", Encoding.UTF8, "application/json"),
+                };
+            }
+            if (req.Method == HttpMethod.Post && req.RequestUri!.AbsolutePath.Contains("/files", StringComparison.Ordinal))
+            {
+                uploadCount++;
+                if (uploadCount == 2)
+                {
+                    return new HttpResponseMessage(HttpStatusCode.BadRequest)
+                    {
+                        Content = new StringContent("{\"error\":{\"code\":\"BadRequest\",\"message\":\"upload-failed\"}}", Encoding.UTF8, "application/json"),
+                    };
+                }
+                return MakeJsonResponse(FakeFileJson($"file_{uploadCount}"));
+            }
+            return MakeJsonResponse("{}");
+        });
+
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+        var projectClient = new AIProjectClient(
+            new Uri("https://test.openai.azure.com/"),
+            new FakeAuthenticationTokenProvider(),
+            new AIProjectClientOptions { Transport = new HttpClientPipelineTransport(httpClient) });
+        var chatClient = new FoundryChatClient(projectClient, "gpt-4o-mini");
+
+        var paths = new[] { MakeTempFile("a"), MakeTempFile("b") };
+        try
+        {
+            var ex = await Assert.ThrowsAnyAsync<Exception>(() => chatClient.CreateVectorStoreAsync("kb", paths));
+
+            // The original upload-failure message must surface, not the cleanup-failure message.
+            Assert.DoesNotContain("cleanup-failed", ex.Message ?? "", StringComparison.Ordinal);
+        }
+        finally
+        {
+            foreach (var p in paths)
+            {
+                File.Delete(p);
+            }
+        }
+    }
+
+    // ----- DeleteVectorStoreAsync -----
+
+    [Fact]
+    public async Task DeleteVectorStoreAsync_Mode1_CallsDeleteAsync()
+    {
+        var (chatClient, recorder) = CreateMode1(responseBody: FakeVectorStoreDeletedJson("vs_abc"));
+        await chatClient.DeleteVectorStoreAsync("vs_abc");
+        Assert.Contains(recorder.Requests, r => r.Method == "DELETE" && r.PathAndQuery.Contains("/vector_stores/vs_abc"));
+    }
+
+    [Fact]
+    public async Task DeleteVectorStoreAsync_Mode2_CallsDeleteAsync()
+    {
+        var (chatClient, recorder) = CreateMode2(responseBody: FakeVectorStoreDeletedJson("vs_xyz"));
+        await chatClient.DeleteVectorStoreAsync("vs_xyz");
+        Assert.Contains(recorder.Requests, r => r.Method == "DELETE" && r.PathAndQuery.Contains("/vector_stores/vs_xyz"));
+    }
+
+    [Fact]
+    public async Task DeleteVectorStoreAsync_NullId_ThrowsArgumentExceptionAsync()
+    {
+        var (chatClient, _) = CreateMode1();
+        await Assert.ThrowsAnyAsync<ArgumentException>(() => chatClient.DeleteVectorStoreAsync(null!));
+    }
+
+    [Fact]
+    public async Task DeleteVectorStoreAsync_HonorsCancellationAsync()
+    {
+        // Same approach as DeleteFileAsync_HonorsCancellationAsync — assert that the call
+        // throws when the token is pre-cancelled, without asserting on the exact exception
+        // surfaced by the SDK pipeline.
+        var (chatClient, _) = CreateMode1(responseBody: FakeVectorStoreDeletedJson("vs_abc"));
+        using var cts = new CancellationTokenSource();
+        cts.Cancel();
+        await Assert.ThrowsAnyAsync<Exception>(() => chatClient.DeleteVectorStoreAsync("vs_abc", cts.Token));
+    }
+
+    // ----- Fixtures and helpers -----
+
+    private static HttpResponseMessage MakeJsonResponse(string json)
+        => new(HttpStatusCode.OK)
+        {
+            Content = new StringContent(json, Encoding.UTF8, "application/json"),
+        };
+
+    private static string FakeFileJson(string id)
+        => $"{{\"id\":\"{id}\",\"object\":\"file\",\"bytes\":11,\"created_at\":1700000000,\"filename\":\"x.txt\",\"purpose\":\"assistants\",\"status\":\"processed\"}}";
+
+    private static string FakeFileDeletedJson(string id)
+        => $"{{\"id\":\"{id}\",\"object\":\"file\",\"deleted\":true}}";
+
+    private static string FakeVectorStoreJson(string id, string name)
+        => FakeVectorStoreJsonWithStatus(id, name, status: "completed");
+
+    private static string FakeVectorStoreJsonWithStatus(string id, string name, string status)
+        => $"{{\"id\":\"{id}\",\"object\":\"vector_store\",\"created_at\":1700000000,\"name\":\"{name}\",\"usage_bytes\":0,\"file_counts\":{{\"in_progress\":0,\"completed\":0,\"failed\":0,\"cancelled\":0,\"total\":0}},\"status\":\"{status}\",\"last_active_at\":1700000000}}";
+
+    private static string FakeVectorStoreDeletedJson(string id)
+        => $"{{\"id\":\"{id}\",\"object\":\"vector_store.deleted\",\"deleted\":true}}";
+
+    private sealed class RequestRecorder : HttpClientHandler
+    {
+        private readonly string _responseBody;
+        public List<RecordedRequest> Requests { get; } = [];
+
+        public RequestRecorder(string? responseBody)
+        {
+            this._responseBody = responseBody ?? "{}";
+        }
+
+        protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
+        {
+            this.Requests.Add(new RecordedRequest
+            {
+                Method = request.Method.Method,
+                PathAndQuery = request.RequestUri?.PathAndQuery ?? "",
+#if NET
+                Body = request.Content is null ? "" : await request.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false),
+#else
+                Body = request.Content is null ? "" : await request.Content.ReadAsStringAsync().ConfigureAwait(false),
+#endif
+            });
+            return MakeJsonResponse(this._responseBody);
+        }
+    }
+
+    private sealed class RecordedRequest
+    {
+        public string Method { get; set; } = "";
+        public string PathAndQuery { get; set; } = "";
+        public string Body { get; set; } = "";
+    }
+}
+#pragma warning restore CS0618
@@ -0,0 +1,433 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.ClientModel.Primitives;
+using System.Net;
+using System.Net.Http;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+using Azure.AI.Extensions.OpenAI;
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Microsoft.Extensions.AI;
+using OpenAI.Responses;
+
+#pragma warning disable OPENAI001, CS0618
+
+namespace Microsoft.Agents.AI.Foundry.UnitTests;
+
+/// <summary>
+/// Unit tests for the public <c>ToPromptAgentAsync</c> extension methods on
+/// <see cref="ChatClientAgent"/> and <see cref="FoundryAgent"/>. Both entry points dispatch
+/// to the same internal converter, so each behavior is asserted through both surfaces.
+/// </summary>
+public sealed class FoundryPromptAgentConverterTests
+{
+    // ----- Failure modes (assert through ChatClientAgent and FoundryAgent extensions) -----
+
+    [Fact]
+    public async Task ToPromptAgentAsync_ChatClientAgent_NonFoundryChatClient_ThrowsInvalidOperationExceptionAsync()
+    {
+        var agent = new ChatClientAgent(new NoOpChatClient());
+        var ex = await Assert.ThrowsAsync<InvalidOperationException>(() => agent.ToPromptAgentAsync());
+        Assert.Contains("FoundryChatClient", ex.Message);
+    }
+
+    [Fact]
+    public async Task ToPromptAgentAsync_FoundryAgent_FoundryChatClientInMode3_ThrowsInvalidOperationExceptionAsync()
+    {
+        var foundryAgent = new FoundryAgent(
+            agentEndpoint: new Uri("https://example.com/api/projects/myproj/agents/myagent/endpoint/protocols/openai"),
+            credential: new FakeAuthenticationTokenProvider());
+        var ex = await Assert.ThrowsAsync<InvalidOperationException>(() => foundryAgent.ToPromptAgentAsync());
+        Assert.Contains("Agent Endpoint mode (Mode 3)", ex.Message);
+    }
+
+    [Fact]
+    public async Task ToPromptAgentAsync_ChatClientAgent_Mode1_MissingModelId_ThrowsInvalidOperationExceptionAsync()
+    {
+        var projectClient = CreateProjectClient();
+        // Construct a FoundryChatClient via the Responses Agent mode (Mode 1) then wrap in a ChatClientAgent whose
+        // ChatOptions has no ModelId — synthesis must throw.
+        var fcc = new FoundryChatClient(projectClient, "gpt-4o-mini");
+        var agent = new ChatClientAgent(fcc, new ChatClientAgentOptions { ChatOptions = new ChatOptions() });
+        var ex = await Assert.ThrowsAsync<InvalidOperationException>(() => agent.ToPromptAgentAsync());
+        Assert.Contains("model id", ex.Message, StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Fact]
+    public async Task ToPromptAgentAsync_ChatClientAgent_Mode1_UnsupportedAITool_ThrowsInvalidOperationExceptionNamingTypeAsync()
+    {
+        var projectClient = CreateProjectClient();
+        var fcc = new FoundryChatClient(projectClient, "gpt-4o-mini");
+        var agent = new ChatClientAgent(fcc, new ChatClientAgentOptions
+        {
+            ChatOptions = new ChatOptions
+            {
+                ModelId = "gpt-4o-mini",
+                Tools = new System.Collections.Generic.List<AITool> { new UnsupportedTool() },
+            },
+        });
+        var ex = await Assert.ThrowsAsync<InvalidOperationException>(() => agent.ToPromptAgentAsync());
+        Assert.Contains(nameof(UnsupportedTool), ex.Message);
+    }
+
+    [Fact]
+    public async Task ToPromptAgentAsync_FoundryAgent_HonorsCancellationAsync()
+    {
+        // Cancellation should bubble up from the AgentReference fetch path. Construct a
+        // FoundryAgent via AsAIAgent(AgentReference) and pass a pre-cancelled token.
+        var (foundryAgent, _) = CreateMode2_PromptAgentOnly("agent-name");
+        using var cts = new CancellationTokenSource();
+        cts.Cancel();
+        await Assert.ThrowsAnyAsync<Exception>(() => foundryAgent.ToPromptAgentAsync(cts.Token));
+    }
+
+    // ----- the Responses Agent mode (Mode 1) (RAPI) synthesis paths -----
+
+    [Fact]
+    public async Task ToPromptAgentAsync_ChatClientAgent_Mode1_RoundTripsModelInstructionsTemperatureTopPAsync()
+    {
+        var projectClient = CreateProjectClient();
+        var fcc = new FoundryChatClient(projectClient, "gpt-4o-mini");
+        var agent = new ChatClientAgent(fcc, new ChatClientAgentOptions
+        {
+            ChatOptions = new ChatOptions
+            {
+                ModelId = "gpt-4o-mini",
+                Instructions = "Be helpful.",
+                Temperature = 0.5f,
+                TopP = 0.9f,
+            },
+        });
+
+        var def = await agent.ToPromptAgentAsync();
+        var declarative = Assert.IsType<DeclarativeAgentDefinition>(def);
+        Assert.Equal("gpt-4o-mini", declarative.Model);
+        Assert.Equal("Be helpful.", declarative.Instructions);
+        Assert.Equal(0.5f, declarative.Temperature);
+        Assert.Equal(0.9f, declarative.TopP);
+        Assert.Empty(declarative.Tools);
+    }
+
+    [Fact]
+    public async Task ToPromptAgentAsync_ChatClientAgent_Mode1_NoTools_ReturnsDefinitionWithEmptyToolsAsync()
+    {
+        var projectClient = CreateProjectClient();
+        var fcc = new FoundryChatClient(projectClient, "gpt-4o-mini");
+        var agent = new ChatClientAgent(fcc, new ChatClientAgentOptions
+        {
+            ChatOptions = new ChatOptions { ModelId = "gpt-4o-mini" },
+        });
+        var def = await agent.ToPromptAgentAsync();
+        var declarative = Assert.IsType<DeclarativeAgentDefinition>(def);
+        Assert.Empty(declarative.Tools);
+    }
+
+    [Fact]
+    public async Task ToPromptAgentAsync_ChatClientAgent_Mode1_AIFunctionTool_ConvertsToFunctionToolAsync()
+    {
+        var projectClient = CreateProjectClient();
+        var fcc = new FoundryChatClient(projectClient, "gpt-4o-mini");
+        var function = AIFunctionFactory.Create(() => "ok", "my_function", "A documented function.");
+        var agent = new ChatClientAgent(fcc, new ChatClientAgentOptions
+        {
+            ChatOptions = new ChatOptions
+            {
+                ModelId = "gpt-4o-mini",
+                Tools = new System.Collections.Generic.List<AITool> { function },
+            },
+        });
+
+        var def = await agent.ToPromptAgentAsync();
+        var declarative = Assert.IsType<DeclarativeAgentDefinition>(def);
+        var fnTool = Assert.Single(declarative.Tools);
+        var ft = Assert.IsType<FunctionTool>(fnTool);
+        Assert.Equal("my_function", ft.FunctionName);
+        Assert.Equal("A documented function.", ft.FunctionDescription);
+    }
+
+    [Fact]
+    public async Task ToPromptAgentAsync_ChatClientAgent_Mode1_FoundryAITool_UnwrapsUnderlyingResponseToolAsync()
+    {
+        var projectClient = CreateProjectClient();
+        var fcc = new FoundryChatClient(projectClient, "gpt-4o-mini");
+        var agent = new ChatClientAgent(fcc, new ChatClientAgentOptions
+        {
+            ChatOptions = new ChatOptions
+            {
+                ModelId = "gpt-4o-mini",
+                Tools = new System.Collections.Generic.List<AITool> { FoundryAITool.CreateWebSearchTool() },
+            },
+        });
+
+        var def = await agent.ToPromptAgentAsync();
+        var declarative = Assert.IsType<DeclarativeAgentDefinition>(def);
+        var tool = Assert.Single(declarative.Tools);
+        // The unwrapped instance must be the concrete WebSearchTool from the OpenAI SDK.
+        Assert.IsType<WebSearchTool>(tool);
+    }
+
+    [Fact]
+    public async Task ToPromptAgentAsync_ChatClientAgent_Mode1_MultipleToolsMixed_ConvertsAllInOrderAsync()
+    {
+        var projectClient = CreateProjectClient();
+        var fcc = new FoundryChatClient(projectClient, "gpt-4o-mini");
+        var function = AIFunctionFactory.Create(() => "ok", "fn", "");
+        var agent = new ChatClientAgent(fcc, new ChatClientAgentOptions
+        {
+            ChatOptions = new ChatOptions
+            {
+                ModelId = "gpt-4o-mini",
+                Tools = new System.Collections.Generic.List<AITool> { function, FoundryAITool.CreateWebSearchTool() },
+            },
+        });
+
+        var def = await agent.ToPromptAgentAsync();
+        var declarative = Assert.IsType<DeclarativeAgentDefinition>(def);
+        Assert.Equal(2, declarative.Tools.Count);
+        Assert.IsType<FunctionTool>(declarative.Tools[0]);
+        Assert.IsType<WebSearchTool>(declarative.Tools[1]);
+    }
+
+    [Fact]
+    public async Task ToPromptAgentAsync_FoundryAgent_Mode1_ResultIsDeclarativeAgentDefinitionAsync()
+    {
+        // FoundryAgent constructed via the projectEndpoint+model+instructions ctor (Responses Agent mode, the Responses Agent mode (Mode 1)).
+        var foundryAgent = new FoundryAgent(
+            projectEndpoint: new Uri("https://test.openai.azure.com/"),
+            credential: new FakeAuthenticationTokenProvider(),
+            model: "gpt-4o-mini",
+            instructions: "You are helpful.");
+
+        var def = await foundryAgent.ToPromptAgentAsync();
+        var declarative = Assert.IsType<DeclarativeAgentDefinition>(def);
+        Assert.Equal("gpt-4o-mini", declarative.Model);
+        Assert.Equal("You are helpful.", declarative.Instructions);
+    }
+
+    // ----- the Prompt Agent mode (Mode 2) paths -----
+
+    [Fact]
+    public async Task ToPromptAgentAsync_FoundryAgent_Mode2_AgentVersion_ReturnsCachedDefinitionAsync()
+    {
+        // Construct via ProjectsAgentVersion → the Definition reference must come back unchanged.
+        var version = ModelReaderWriter.Read<ProjectsAgentVersion>(BinaryData.FromString(TestDataUtil.GetAgentVersionResponseJson()))!;
+        var projectClient = CreateProjectClient();
+        var foundryAgent = projectClient.AsAIAgent(version);
+
+        var def = await foundryAgent.ToPromptAgentAsync();
+        Assert.Same(version.Definition, def);
+    }
+
+    [Fact]
+    public async Task ToPromptAgentAsync_FoundryAgent_Mode2_AgentRecord_ReturnsLatestVersionDefinitionAsync()
+    {
+        var record = ModelReaderWriter.Read<ProjectsAgentRecord>(BinaryData.FromString(TestDataUtil.GetAgentResponseJson()))!;
+        var projectClient = CreateProjectClient();
+        var foundryAgent = projectClient.AsAIAgent(record);
+
+        var def = await foundryAgent.ToPromptAgentAsync();
+        Assert.Same(record.GetLatestVersion().Definition, def);
+    }
+
+    [Fact]
+    public async Task ToPromptAgentAsync_FoundryAgent_Mode2_PromptAgentOnly_FetchesLatestVersionAsync()
+    {
+        // The handler returns a known agent JSON. The converter must hit GET /agents/{name}
+        // and return that record's latest version definition.
+        var fetched = false;
+        using var handler = new HttpHandlerAssert(req =>
+        {
+            if (req.Method == HttpMethod.Get && req.RequestUri!.AbsolutePath.Contains("/agents/agent-name"))
+            {
+                fetched = true;
+                return new HttpResponseMessage(HttpStatusCode.OK)
+                {
+                    Content = new StringContent(TestDataUtil.GetAgentResponseJson(agentName: "agent-name"), Encoding.UTF8, "application/json"),
+                };
+            }
+            return new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent("{}", Encoding.UTF8, "application/json") };
+        });
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+        var projectClient = new AIProjectClient(
+            new Uri("https://test.openai.azure.com/"),
+            new FakeAuthenticationTokenProvider(),
+            new AIProjectClientOptions { Transport = new HttpClientPipelineTransport(httpClient) });
+        var foundryAgent = projectClient.AsAIAgent(new AgentReference("agent-name"));
+
+        var def = await foundryAgent.ToPromptAgentAsync();
+        Assert.True(fetched);
+        Assert.NotNull(def);
+    }
+
+    [Fact]
+    public async Task ToPromptAgentAsync_FoundryAgent_Mode2_PromptAgentOnly_PinnedVersion_FetchesPinnedVersionAsync()
+    {
+        // Q-C regression: when AgentReference.Version is set, the converter must call
+        // GET /agents/{name}/versions/{version} and return that pinned version's definition,
+        // NOT GET /agents/{name} -> GetLatestVersion() which would silently substitute the
+        // server's latest. We probe both paths from the same handler and assert exactly one was hit.
+        var fetchedLatest = false;
+        var fetchedPinned = false;
+        using var handler = new HttpHandlerAssert(req =>
+        {
+            // Pinned-version path: …/agents/{name}/versions/{version}
+            if (req.Method == HttpMethod.Get && req.RequestUri!.AbsolutePath.Contains("/agents/agent-name/versions/2", StringComparison.Ordinal))
+            {
+                fetchedPinned = true;
+                var pinnedDef = new DeclarativeAgentDefinition("gpt-pinned") { Instructions = "Pinned-version instructions." };
+                return new HttpResponseMessage(HttpStatusCode.OK)
+                {
+                    Content = new StringContent(TestDataUtil.GetAgentVersionResponseJson(agentName: "agent-name", agentDefinition: pinnedDef), Encoding.UTF8, "application/json"),
+                };
+            }
+            // Latest-version path: …/agents/{name}
+            if (req.Method == HttpMethod.Get && req.RequestUri!.AbsolutePath.EndsWith("/agents/agent-name", StringComparison.Ordinal))
+            {
+                fetchedLatest = true;
+                var latestDef = new DeclarativeAgentDefinition("gpt-latest") { Instructions = "Latest-version instructions." };
+                return new HttpResponseMessage(HttpStatusCode.OK)
+                {
+                    Content = new StringContent(TestDataUtil.GetAgentResponseJson(agentName: "agent-name", agentDefinition: latestDef), Encoding.UTF8, "application/json"),
+                };
+            }
+            return new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent("{}", Encoding.UTF8, "application/json") };
+        });
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+        var projectClient = new AIProjectClient(
+            new Uri("https://test.openai.azure.com/"),
+            new FakeAuthenticationTokenProvider(),
+            new AIProjectClientOptions { Transport = new HttpClientPipelineTransport(httpClient) });
+        var foundryAgent = projectClient.AsAIAgent(new AgentReference("agent-name", "2"));
+
+        var def = await foundryAgent.ToPromptAgentAsync();
+
+        Assert.True(fetchedPinned, "Pinned-version endpoint (.../agents/agent-name/versions/2) must be called when AgentReference.Version is set.");
+        Assert.False(fetchedLatest, "Latest-version endpoint (.../agents/agent-name) must NOT be called when AgentReference.Version is set.");
+        var declarative = Assert.IsType<DeclarativeAgentDefinition>(def);
+        Assert.Equal("gpt-pinned", declarative.Model);
+        Assert.Equal("Pinned-version instructions.", declarative.Instructions);
+    }
+
+    [Fact]
+    public async Task ToPromptAgentAsync_FoundryAgent_Mode2_PromptAgentOnly_UnpinnedVersionKeyword_FetchesLatestAsync()
+    {
+        // Q-C boundary: AgentReference.Version == "latest" must fall back to the GET /agents/{name}
+        // path (the latest-version path), NOT GET /agents/{name}/versions/latest.
+        var fetchedLatest = false;
+        using var handler = new HttpHandlerAssert(req =>
+        {
+            if (req.Method == HttpMethod.Get && req.RequestUri!.AbsolutePath.EndsWith("/agents/agent-name", StringComparison.Ordinal))
+            {
+                fetchedLatest = true;
+                return new HttpResponseMessage(HttpStatusCode.OK)
+                {
+                    Content = new StringContent(TestDataUtil.GetAgentResponseJson(agentName: "agent-name"), Encoding.UTF8, "application/json"),
+                };
+            }
+            return new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent("{}", Encoding.UTF8, "application/json") };
+        });
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+        var projectClient = new AIProjectClient(
+            new Uri("https://test.openai.azure.com/"),
+            new FakeAuthenticationTokenProvider(),
+            new AIProjectClientOptions { Transport = new HttpClientPipelineTransport(httpClient) });
+        var foundryAgent = projectClient.AsAIAgent(new AgentReference("agent-name", "latest"));
+
+        var def = await foundryAgent.ToPromptAgentAsync();
+
+        Assert.True(fetchedLatest);
+        Assert.NotNull(def);
+    }
+
+    [Fact]
+    public async Task ToPromptAgentAsync_FoundryAgent_Mode2_PromptAgentOnly_ServerReturnsError_PropagatesExceptionAsync()
+    {
+        using var handler = new HttpHandlerAssert(req =>
+            new HttpResponseMessage(HttpStatusCode.NotFound) { Content = new StringContent("{\"error\":{\"code\":\"NotFound\"}}", Encoding.UTF8, "application/json") });
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+        var projectClient = new AIProjectClient(
+            new Uri("https://test.openai.azure.com/"),
+            new FakeAuthenticationTokenProvider(),
+            new AIProjectClientOptions { Transport = new HttpClientPipelineTransport(httpClient) });
+        var foundryAgent = projectClient.AsAIAgent(new AgentReference("missing-agent"));
+
+        await Assert.ThrowsAnyAsync<Exception>(() => foundryAgent.ToPromptAgentAsync());
+    }
+
+    // ----- Python-parity guard: both extensions produce equivalent definitions -----
+
+    [Fact]
+    public async Task BothExtensions_ProduceEquivalentDefinitions_ForEquivalentInputsAsync()
+    {
+        // Build two agents that are semantically equivalent: one as a plain ChatClientAgent
+        // via AsAIAgent(model, instructions), and one as a FoundryAgent via the projectEndpoint
+        // ctor. Both flow through the same converter; assert key fields match.
+        var projectClient = CreateProjectClient();
+        ChatClientAgent ccaAgent = projectClient.AsAIAgent("gpt-4o-mini", "Be helpful.");
+        var foundryAgent = new FoundryAgent(
+            projectEndpoint: new Uri("https://test.openai.azure.com/"),
+            credential: new FakeAuthenticationTokenProvider(),
+            model: "gpt-4o-mini",
+            instructions: "Be helpful.");
+
+        var ccaDef = await ccaAgent.ToPromptAgentAsync();
+        var faDef = await foundryAgent.ToPromptAgentAsync();
+
+        var a = Assert.IsType<DeclarativeAgentDefinition>(ccaDef);
+        var b = Assert.IsType<DeclarativeAgentDefinition>(faDef);
+        Assert.Equal(a.Model, b.Model);
+        Assert.Equal(a.Instructions, b.Instructions);
+        Assert.Equal(a.Tools.Count, b.Tools.Count);
+    }
+
+    // ----- Helpers -----
+
+    private static AIProjectClient CreateProjectClient()
+        => new(
+            new Uri("https://test.openai.azure.com/"),
+            new FakeAuthenticationTokenProvider(),
+            new AIProjectClientOptions { Transport = new HttpClientPipelineTransport(new HttpClient()) });
+
+    private static (FoundryAgent FoundryAgent, AIProjectClient ProjectClient) CreateMode2_PromptAgentOnly(string agentName)
+    {
+        var projectClient = CreateProjectClient();
+        var foundryAgent = projectClient.AsAIAgent(new AgentReference(agentName));
+        return (foundryAgent, projectClient);
+    }
+
+    private sealed class NoOpChatClient : IChatClient
+    {
+        public Task<ChatResponse> GetResponseAsync(System.Collections.Generic.IEnumerable<ChatMessage> messages, ChatOptions? options = null, CancellationToken cancellationToken = default)
+            => Task.FromResult(new ChatResponse());
+
+        public System.Collections.Generic.IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(System.Collections.Generic.IEnumerable<ChatMessage> messages, ChatOptions? options = null, CancellationToken cancellationToken = default)
+            => EmptyAsyncEnumerableAsync();
+
+        private static async System.Collections.Generic.IAsyncEnumerable<ChatResponseUpdate> EmptyAsyncEnumerableAsync()
+        {
+            await Task.CompletedTask.ConfigureAwait(false);
+            yield break;
+        }
+
+        public object? GetService(Type serviceType, object? serviceKey = null) => null;
+
+        public void Dispose() { }
+    }
+
+    private sealed class UnsupportedTool : AITool
+    {
+        public override string Name => "unsupported";
+    }
+}
+#pragma warning restore CS0618
@@ -0,0 +1,90 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.ClientModel;
+using System.ClientModel.Primitives;
+using System.Net;
+using System.Net.Http;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using OpenAI;
+using OpenAI.Responses;
+
+#pragma warning disable OPENAI001
+
+namespace Microsoft.Agents.AI.Foundry.UnitTests;
+
+/// <summary>
+/// One-shot verification (kept in tree to detect regressions) that MEAI 10.5.1 stamps its own
+/// <c>MEAI/{version}</c> User-Agent segment automatically when an <see cref="ResponsesClient"/>
+/// is wrapped via <c>AsIChatClient()</c>. If this test starts failing, the FoundryChatClient
+/// implementation must re-register the MEAI policy explicitly via OpenAIRequestPolicies because
+/// the local Foundry copy was deleted under the assumption that MEAI provides it built-in.
+/// </summary>
+public sealed class MeaiAutoUserAgentVerificationTests
+{
+    [Fact]
+    public async Task MeaiOpenAIResponsesClient_StampsMeaiSegmentAutomatically_WithoutLocalPolicyAsync()
+    {
+        // Arrange: bare OpenAI ResponseClient over a fake HTTP transport, wrapped via MEAI's
+        // AsIChatClient() with no custom OpenAIRequestPolicies registration. If MEAI auto-stamps
+        // its own MEAI/{version} segment, it will appear here.
+        using var handler = new RecordingHandler();
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(handler);
+#pragma warning restore CA5399
+
+        var options = new OpenAIClientOptions
+        {
+            Transport = new HttpClientPipelineTransport(httpClient),
+            Endpoint = new Uri("https://example.test/v1"),
+        };
+
+        var responseClient = new ResponsesClient(new ApiKeyCredential("test-key"), options);
+        var chatClient = responseClient.AsIChatClient("gpt-4o-mini");
+
+        // Act: send a request through MEAI's chat client. The fake transport will throw on
+        // response parsing, but we only care about the outbound headers, which are captured
+        // before the response is parsed.
+        try
+        {
+            await chatClient.GetResponseAsync("hi", cancellationToken: CancellationToken.None);
+        }
+        catch
+        {
+            // Expected: the fake response body is not parseable as a Responses API payload.
+        }
+
+        // Assert: at least one outbound request reached the transport, and its User-Agent
+        // contains either "MEAI/" (auto-stamped by MEAI) or no MEAI segment (verification
+        // signal — see test summary).
+        Assert.True(handler.Count > 0, "Expected at least one outbound request from MEAI wrapper.");
+        Assert.NotNull(handler.LastUserAgent);
+        // INTENT: assert that MEAI auto-stamps. If the assertion fails, see the FoundryChatClient
+        // implementation note about needing to register the MEAI policy explicitly.
+        Assert.Contains("MEAI/", handler.LastUserAgent);
+    }
+
+    private sealed class RecordingHandler : HttpClientHandler
+    {
+        public int Count { get; private set; }
+        public string? LastUserAgent { get; private set; }
+
+        protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
+        {
+            this.Count++;
+            this.LastUserAgent = request.Headers.TryGetValues("User-Agent", out var values)
+                ? string.Join(",", values)
+                : null;
+
+            var resp = new HttpResponseMessage(HttpStatusCode.OK)
+            {
+                Content = new StringContent("{}", Encoding.UTF8, "application/json"),
+                RequestMessage = request,
+            };
+            return Task.FromResult(resp);
+        }
+    }
+}
@@ -14,11 +14,14 @@
    <ProjectReference Include="..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
  </ItemGroup>

-  <!-- FoundryEval tests require net8.0+ (MEAI.Evaluation does not support legacy TFMs) -->
+  <!-- Tests requiring net8.0+ (MEAI.Evaluation and some SCM pipeline APIs do not support legacy TFMs) -->
  <ItemGroup Condition="!$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net8.0'))">
    <Compile Remove="FoundryEvalConverterTests.cs" />
    <Compile Remove="FoundryEvalsTests.cs" />
    <Compile Remove="ClientHeadersExtensionsTests.cs" />
+    <Compile Remove="ServedModelTestHelpers.cs" />
+    <Compile Remove="ServedModelScopeTests.cs" />
+    <Compile Remove="ServedModelPolicyTests.cs" />
  </ItemGroup>

  <ItemGroup>
--- a/Show More
+++ b/Show More