Get date suffix up to date with release date (#6690)

* replace the symlink index entries  with regular file entries

* Fixed broken links.

.github/ISSUE_TEMPLATE/dotnet-issue.yml

@@ -1,7 +1,7 @@
 name: .NET Bug Report
 description: Report a bug in the Agent Framework .NET SDK
 title: ".NET: [Bug]: "
-labels: ["bug", ".NET"]
+labels: [".NET"]
 type: bug
 body:
   - type: textarea

.github/ISSUE_TEMPLATE/python-issue.yml

@@ -1,7 +1,7 @@
 name: Python Bug Report
 description: Report a bug in the Agent Framework Python SDK
 title: "Python: [Bug]: "
-labels: ["bug", "Python"]
+labels: ["Python"]
 type: bug
 body:
   - type: textarea

.github/dependabot.yml

@@ -24,12 +24,14 @@ updates:
       - ".NET"
       - "dependencies"
 
-  # Maintain dependencies for python
+  # Maintain dependencies for python.
+  # TODO: Remove these Python Dependabot entries after we have confidence in the
+  # Python dependency-maintenance workflow.
   - package-ecosystem: "pip"
     directory: "python/"
     schedule:
       interval: "weekly"
-      day: "monday"
+      day: "thursday"
     labels:
       - "python"
       - "dependencies"
@@ -37,7 +39,7 @@ updates:
     directory: "python/"
     schedule:
       interval: "weekly"
-      day: "monday"
+      day: "thursday"
     labels:
       - "python"
       - "dependencies"

.github/workflows/issue-triage.yml

@@ -2,7 +2,7 @@ name: Issue Triage
 
 on:
   issues:
-    types: [opened, labeled]
+    types: [opened, typed]
 
 permissions:
   contents: read
@@ -12,9 +12,7 @@ permissions:
 concurrency:
   group: >-
     issue-triage-${{ github.repository }}-${{
-      ((github.event.action == 'opened' && contains(github.event.issue.labels.*.name, 'bug'))
-       || (github.event.action == 'labeled' && github.event.label.name == 'bug'))
-      && github.event.issue.number
+      github.event.issue.type.name == 'Bug' && github.event.issue.number
       || github.run_id
     }}
   cancel-in-progress: true
@@ -28,7 +26,7 @@ env:
 jobs:
   team_check:
     runs-on: ubuntu-latest
-    if: ${{ (github.event.action == 'opened' && contains(github.event.issue.labels.*.name, 'bug')) || (github.event.action == 'labeled' && github.event.label.name == 'bug') }}
+    if: ${{ github.event.issue.type.name == 'Bug' }}
     outputs:
       is_team_member: ${{ steps.check.outputs.is_team_member }}
       issue_number: ${{ steps.issue.outputs.issue_number }}

.github/workflows/label-issues.yml

@@ -90,9 +90,7 @@ jobs:
             // Check for issue type from issue form dropdown
             const issueTypeField = getFormFieldValue(body, 'Type of Issue')
             if (issueTypeField) {
-              if (issueTypeField === 'Bug') {
-                labels.push("bug")
-              } else if (issueTypeField === 'Feature Request') {
+              if (issueTypeField === 'Feature Request') {
                 labels.push("enhancement")
               } else if (issueTypeField === 'Question') {
                 labels.push("question")

.github/workflows/python-code-quality.yml

@@ -113,8 +113,8 @@ jobs:
       - name: Run markdown code lint
         run: uv run poe markdown-code-lint
 
-  mypy:
-    name: Mypy Checks
+  test-typing:
+    name: Test Typing Checks
     if: "!cancelled()"
     strategy:
       fail-fast: false
@@ -139,7 +139,5 @@ jobs:
           os: ${{ runner.os }}
         env:
           UV_CACHE_DIR: /tmp/.uv-cache
-      - name: Run Mypy
-        env:
-          GITHUB_BASE_REF: ${{ github.event.pull_request.base.ref || github.base_ref || 'main' }}
-        run: uv run python scripts/workspace_poe_tasks.py ci-mypy
+      - name: Run tests/samples type checkers (mypy, pyrefly, ty)
+        run: uv run python scripts/workspace_poe_tasks.py ci-test-typing

.github/workflows/python-dependency-maintenance.yml

@@ -0,0 +1,365 @@
+name: Python - Dependency Maintenance
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 4 * * 1"
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+concurrency:
+  group: python-dependency-maintenance
+  cancel-in-progress: false
+
+env:
+  UV_CACHE_DIR: /tmp/.uv-cache
+
+jobs:
+  dependency-maintenance:
+    name: Dependency Maintenance
+    runs-on: ubuntu-latest
+    env:
+      # Match the existing Python dependency maintenance workflows. Reevaluate if package
+      # installability starts differing across supported Python versions.
+      UV_PYTHON: "3.13"
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up python and install the project
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+        env:
+          UV_CACHE_DIR: /tmp/.uv-cache
+
+      - name: Set dependency release cutoff
+        run: |
+          cutoff="$(date -u -d '7 days ago' '+%Y-%m-%dT%H:%M:%SZ')"
+          echo "DEPENDENCY_RELEASE_CUTOFF=${cutoff}" >> "$GITHUB_ENV"
+          echo "Using dependency release cutoff: ${cutoff}"
+
+      - name: Repin dev dependency declarations
+        run: uv run poe upgrade-dev-dependency-pins
+        working-directory: ./python
+
+      - name: Refresh lockfile after dev pin updates
+        run: uv lock
+        working-directory: ./python
+
+      - name: Save dev dependency changes
+        run: |
+          DEV_PATCH="${RUNNER_TEMP}/python-dev-dependency-updates.patch"
+          git diff -- python/pyproject.toml "python/packages/*/pyproject.toml" python/uv.lock > "${DEV_PATCH}"
+          if [ -s "${DEV_PATCH}" ]; then
+            echo "has_dev_changes=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_dev_changes=false" >> "$GITHUB_OUTPUT"
+          fi
+          echo "patch=${DEV_PATCH}" >> "$GITHUB_OUTPUT"
+        id: dev_changes
+
+      - name: Run dependency bounds test scenarios
+        id: validate_bounds_test
+        continue-on-error: true
+        run: uv run poe validate-dependency-bounds-test --package "*"
+        working-directory: ./python
+
+      - name: Run dependency upper-bound validation
+        id: validate_ranges
+        if: steps.validate_bounds_test.outcome == 'success'
+        continue-on-error: true
+        run: uv run poe validate-dependency-bounds-project --mode upper --package "*"
+        working-directory: ./python
+
+      - name: Upload dependency validation reports
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: dependency-maintenance-results
+          path: |
+            python/scripts/dependencies/dependency-bounds-test-results.json
+            python/scripts/dependencies/dependency-range-results.json
+          if-no-files-found: warn
+
+      - name: Create issue for failed dependency bounds test
+        if: steps.validate_bounds_test.outcome != 'success'
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const fs = require("fs")
+            const reportPath = "python/scripts/dependencies/dependency-bounds-test-results.json"
+
+            const owner = context.repo.owner
+            const repo = context.repo.repo
+            const openIssues = await github.paginate(github.rest.issues.listForRepo, {
+              owner,
+              repo,
+              state: "open",
+              per_page: 100,
+            })
+            const openIssueTitles = new Set(
+              openIssues.filter((issue) => !issue.pull_request).map((issue) => issue.title)
+            )
+
+            const formatError = (message) => String(message || "No error output captured.").replace(/```/g, "'''")
+            const title = "Dependency bounds test failed"
+            if (openIssueTitles.has(title)) {
+              core.info(`Issue already exists: ${title}`)
+              return
+            }
+
+            const bodyLines = [
+              "Automated dependency bounds test mode failed before dependency upper-bound validation could run.",
+              "",
+              "The weekly dependency maintenance workflow kept only dev dependency updates for the generated PR, if any, and skipped dependency range updates for this run.",
+              "",
+            ]
+
+            if (fs.existsSync(reportPath)) {
+              const report = JSON.parse(fs.readFileSync(reportPath, "utf8"))
+              const failedScenarios = (report.scenarios ?? []).filter((scenario) => scenario.status === "failed")
+              for (const scenario of failedScenarios) {
+                bodyLines.push(`### ${scenario.name} scenario (${scenario.resolution})`)
+                const failedPackages = (scenario.packages ?? []).filter((pkg) => pkg.status === "failed")
+                for (const pkg of failedPackages.slice(0, 10)) {
+                  bodyLines.push(
+                    "",
+                    `- Package: \`${pkg.package_name}\``,
+                    `- Project path: \`${pkg.project_path}\``,
+                    "",
+                    "```",
+                    formatError(pkg.error).slice(0, 3500),
+                    "```"
+                  )
+                }
+                if (failedPackages.length > 10) {
+                  bodyLines.push("", `_Additional failed packages omitted: ${failedPackages.length - 10}_`)
+                }
+              }
+            } else {
+              bodyLines.push(`No dependency bounds test report was found at \`${reportPath}\`.`)
+            }
+
+            bodyLines.push("", `Workflow run: ${context.serverUrl}/${owner}/${repo}/actions/runs/${context.runId}`)
+
+            await github.rest.issues.create({
+              owner,
+              repo,
+              title,
+              body: bodyLines.join("\n"),
+            })
+            core.info(`Created issue: ${title}`)
+
+      - name: Create issues for failed dependency candidates
+        if: always()
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const fs = require("fs")
+            const reportPath = "python/scripts/dependencies/dependency-range-results.json"
+
+            if (!fs.existsSync(reportPath)) {
+              core.info(`No dependency range report found at ${reportPath}`)
+              return
+            }
+
+            const report = JSON.parse(fs.readFileSync(reportPath, "utf8"))
+            const dependencyFailures = []
+
+            for (const packageResult of report.packages ?? []) {
+              for (const dependency of packageResult.dependencies ?? []) {
+                const candidateVersions = new Set(dependency.candidate_versions ?? [])
+                const failedAttempts = (dependency.attempts ?? []).filter(
+                  (attempt) => attempt.status === "failed" && candidateVersions.has(attempt.trial_upper)
+                )
+                if (!failedAttempts.length) {
+                  continue
+                }
+
+                const failuresByVersion = new Map()
+                for (const attempt of failedAttempts) {
+                  const version = attempt.trial_upper || "unknown"
+                  if (!failuresByVersion.has(version)) {
+                    failuresByVersion.set(version, attempt.error || "No error output captured.")
+                  }
+                }
+
+                dependencyFailures.push({
+                  packageName: packageResult.package_name,
+                  projectPath: packageResult.project_path,
+                  dependencyName: dependency.name,
+                  originalRequirements: dependency.original_requirements ?? [],
+                  finalRequirements: dependency.final_requirements ?? [],
+                  failedVersions: [...failuresByVersion.entries()].map(([version, error]) => ({ version, error })),
+                })
+              }
+            }
+
+            if (!dependencyFailures.length) {
+              core.info("No failing dependency candidates found.")
+              return
+            }
+
+            const owner = context.repo.owner
+            const repo = context.repo.repo
+            const openIssues = await github.paginate(github.rest.issues.listForRepo, {
+              owner,
+              repo,
+              state: "open",
+              per_page: 100,
+            })
+            const openIssueTitles = new Set(
+              openIssues.filter((issue) => !issue.pull_request).map((issue) => issue.title)
+            )
+
+            const formatError = (message) => String(message || "No error output captured.").replace(/```/g, "'''")
+
+            for (const failure of dependencyFailures) {
+              const title = `Dependency validation failed: ${failure.dependencyName} (${failure.packageName})`
+              if (openIssueTitles.has(title)) {
+                core.info(`Issue already exists: ${title}`)
+                continue
+              }
+
+              const visibleFailures = failure.failedVersions.slice(0, 5)
+              const omittedCount = failure.failedVersions.length - visibleFailures.length
+              const failureDetails = visibleFailures
+                .map(
+                  (entry) =>
+                    `- \`${entry.version}\`\n\n\`\`\`\n${formatError(entry.error).slice(0, 3500)}\n\`\`\``
+                )
+                .join("\n\n")
+
+              const body = [
+                "Automated dependency range validation found candidate versions that failed checks.",
+                "",
+                `- Package: \`${failure.packageName}\``,
+                `- Project path: \`${failure.projectPath}\``,
+                `- Dependency: \`${failure.dependencyName}\``,
+                `- Original requirements: ${
+                  failure.originalRequirements.length
+                    ? failure.originalRequirements.map((value) => `\`${value}\``).join(", ")
+                    : "_none_"
+                }`,
+                `- Final requirements after run: ${
+                  failure.finalRequirements.length
+                    ? failure.finalRequirements.map((value) => `\`${value}\``).join(", ")
+                    : "_none_"
+                }`,
+                "",
+                "### Failed versions and errors",
+                failureDetails,
+                omittedCount > 0 ? `\n_Additional failed versions omitted: ${omittedCount}_` : "",
+                "",
+                `Workflow run: ${context.serverUrl}/${owner}/${repo}/actions/runs/${context.runId}`,
+              ].join("\n")
+
+              await github.rest.issues.create({
+                owner,
+                repo,
+                title,
+                body,
+              })
+              openIssueTitles.add(title)
+              core.info(`Created issue: ${title}`)
+            }
+
+      - name: Keep only dev updates when range validation fails
+        if: steps.validate_bounds_test.outcome != 'success' || steps.validate_ranges.outcome != 'success'
+        env:
+          DEV_PATCH: ${{ steps.dev_changes.outputs.patch }}
+          HAS_DEV_CHANGES: ${{ steps.dev_changes.outputs.has_dev_changes }}
+        run: |
+          git restore python/pyproject.toml python/packages/*/pyproject.toml python/uv.lock
+          if [ "${HAS_DEV_CHANGES}" = "true" ]; then
+            git apply "${DEV_PATCH}"
+          fi
+
+      - name: Refresh lockfile after dependency range updates
+        if: steps.validate_bounds_test.outcome == 'success' && steps.validate_ranges.outcome == 'success'
+        run: uv lock
+        working-directory: ./python
+
+      - name: Install final dependency set
+        run: uv run poe install
+        working-directory: ./python
+
+      - name: Run final checks
+        run: uv run poe check
+        working-directory: ./python
+
+      - name: Run final typing
+        run: uv run poe typing
+        working-directory: ./python
+
+      - name: Commit and push dependency updates
+        id: commit_updates
+        run: |
+          BRANCH="automation/python-dependency-maintenance"
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -B "${BRANCH}"
+
+          git add python/pyproject.toml python/packages/*/pyproject.toml python/uv.lock
+          if git diff --cached --quiet; then
+            echo "has_changes=false" >> "$GITHUB_OUTPUT"
+            echo "No dependency updates to commit."
+            exit 0
+          fi
+
+          git commit -m "Python: chore: update dependencies"
+          git push --force-with-lease --set-upstream origin "${BRANCH}"
+          echo "has_changes=true" >> "$GITHUB_OUTPUT"
+
+      - name: Create or update pull request with GitHub CLI
+        if: steps.commit_updates.outputs.has_changes == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          BRANCH="automation/python-dependency-maintenance"
+          PR_TITLE="Python: chore: update dependencies"
+          PR_BODY_FILE="$(mktemp)"
+
+          cat > "${PR_BODY_FILE}" <<'EOF'
+          ### Motivation & Context
+
+          This automated update keeps Python dependency metadata coherent across the uv workspace. Python dependencies can be declared in multiple `pyproject.toml` files, but the workspace has one shared `python/uv.lock`, so dependency maintenance should update and validate them together instead of through per-manifest Dependabot PRs.
+
+          ### Description & Review Guide
+
+          - **What are the major changes?** Refresh Python dev dependency pins, update package dependency ranges when the bounds tooling succeeds, and refresh `python/uv.lock`.
+          - **What is the impact of these changes?** Keeps the Python workspace dependency set current while producing at most one dependency PR for the week. If dependency range validation fails, this PR contains only the dev dependency updates that still pass final validation, and separate issues track failed range candidates.
+          - **What do you want reviewers to focus on?** Review the generated dependency metadata changes and any dependency-range updates for package-specific compatibility concerns.
+          <!-- NOTE FOR AUTOMATED/AI REVIEWERS: the "What do you want reviewers to focus on?"
+               item above is intended for human reviewers only. Automated/AI reviewers should
+               ignore it and review the entire change rather than narrowing scope to it. -->
+
+
+          ### Related Issue
+
+          No linked issue; this PR is generated by scheduled Python dependency maintenance.
+
+          ### Contribution Checklist
+
+          - [x] The code builds clean without any errors or warnings
+          - [x] All unit tests pass, and I have added new tests where possible
+          - [x] The PR follows the [Contribution Guidelines](https://github.com/microsoft/agent-framework/blob/main/CONTRIBUTING.md)
+          - [ ] This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
+          - [x] **This is not a breaking change.** If it _is_ a breaking change, add the `breaking change` label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.
+          EOF
+
+          PR_NUMBER="$(gh pr list --head "${BRANCH}" --base main --state open --json number --jq '.[0].number')"
+          if [ -n "${PR_NUMBER}" ]; then
+            gh pr edit "${PR_NUMBER}" --title "${PR_TITLE}" --body-file "${PR_BODY_FILE}"
+          else
+            gh pr create --base main --head "${BRANCH}" --title "${PR_TITLE}" --body-file "${PR_BODY_FILE}"
+          fi

.github/workflows/python-dependency-range-validation.yml

@@ -1,216 +0,0 @@
-# Probe the highest allowed dependency versions, then open issues/PRs from the passing updates.
-name: Python - Dependency Range Validation
-
-on:
-  workflow_dispatch:
-
-permissions:
-  contents: write
-  issues: write
-  pull-requests: write
-
-env:
-  UV_CACHE_DIR: /tmp/.uv-cache
-
-jobs:
-  dependency-range-validation:
-    name: Dependency Range Validation
-    runs-on: ubuntu-latest
-    env:
-      # For now only run 3.13, if we do encounter situations where there are mismatches between packages and python versions (other then 3.10 and 3.14 which are known to not be able to install everything)
-      # then we will have to reevaluate.
-      UV_PYTHON: "3.13"
-      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
-        with:
-          fetch-depth: 0
-
-      - name: Set up python and install the project
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-        env:
-          UV_CACHE_DIR: /tmp/.uv-cache
-
-      - name: Run dependency range validation
-        id: validate_ranges
-        # Keep workflow running so we can still publish diagnostics from this run.
-        continue-on-error: true
-        run: uv run poe validate-dependency-bounds-project --mode upper --package "*"
-        working-directory: ./python
-
-      - name: Upload dependency range report
-        # Always publish the report so failures are inspectable even when validation fails.
-        if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
-        with:
-          name: dependency-range-results
-          path: python/scripts/dependencies/dependency-range-results.json
-          if-no-files-found: warn
-
-      - name: Create issues for failed dependency candidates
-        # Always process the report so failed candidates create actionable tracking issues.
-        if: always()
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
-        with:
-          script: |
-            const fs = require("fs")
-            const reportPath = "python/scripts/dependencies/dependency-range-results.json"
-
-            if (!fs.existsSync(reportPath)) {
-              core.warning(`No dependency range report found at ${reportPath}`)
-              return
-            }
-
-            const report = JSON.parse(fs.readFileSync(reportPath, "utf8"))
-            const dependencyFailures = []
-
-            for (const packageResult of report.packages ?? []) {
-              for (const dependency of packageResult.dependencies ?? []) {
-                const candidateVersions = new Set(dependency.candidate_versions ?? [])
-                const failedAttempts = (dependency.attempts ?? []).filter(
-                  (attempt) => attempt.status === "failed" && candidateVersions.has(attempt.trial_upper)
-                )
-                if (!failedAttempts.length) {
-                  continue
-                }
-
-                const failuresByVersion = new Map()
-                for (const attempt of failedAttempts) {
-                  const version = attempt.trial_upper || "unknown"
-                  if (!failuresByVersion.has(version)) {
-                    failuresByVersion.set(version, attempt.error || "No error output captured.")
-                  }
-                }
-
-                dependencyFailures.push({
-                  packageName: packageResult.package_name,
-                  projectPath: packageResult.project_path,
-                  dependencyName: dependency.name,
-                  originalRequirements: dependency.original_requirements ?? [],
-                  finalRequirements: dependency.final_requirements ?? [],
-                  failedVersions: [...failuresByVersion.entries()].map(([version, error]) => ({ version, error })),
-                })
-              }
-            }
-
-            if (!dependencyFailures.length) {
-              core.info("No failing dependency candidates found.")
-              return
-            }
-
-            const owner = context.repo.owner
-            const repo = context.repo.repo
-            const openIssues = await github.paginate(github.rest.issues.listForRepo, {
-              owner,
-              repo,
-              state: "open",
-              per_page: 100,
-            })
-            const openIssueTitles = new Set(
-              openIssues.filter((issue) => !issue.pull_request).map((issue) => issue.title)
-            )
-
-            const formatError = (message) => String(message || "No error output captured.").replace(/```/g, "'''")
-
-            for (const failure of dependencyFailures) {
-              const title = `Dependency validation failed: ${failure.dependencyName} (${failure.packageName})`
-              if (openIssueTitles.has(title)) {
-                core.info(`Issue already exists: ${title}`)
-                continue
-              }
-
-              const visibleFailures = failure.failedVersions.slice(0, 5)
-              const omittedCount = failure.failedVersions.length - visibleFailures.length
-              const failureDetails = visibleFailures
-                .map(
-                  (entry) =>
-                    `- \`${entry.version}\`\n\n\`\`\`\n${formatError(entry.error).slice(0, 3500)}\n\`\`\``
-                )
-                .join("\n\n")
-
-              const body = [
-                "Automated dependency range validation found candidate versions that failed checks.",
-                "",
-                `- Package: \`${failure.packageName}\``,
-                `- Project path: \`${failure.projectPath}\``,
-                `- Dependency: \`${failure.dependencyName}\``,
-                `- Original requirements: ${
-                  failure.originalRequirements.length
-                    ? failure.originalRequirements.map((value) => `\`${value}\``).join(", ")
-                    : "_none_"
-                }`,
-                `- Final requirements after run: ${
-                  failure.finalRequirements.length
-                    ? failure.finalRequirements.map((value) => `\`${value}\``).join(", ")
-                    : "_none_"
-                }`,
-                "",
-                "### Failed versions and errors",
-                failureDetails,
-                omittedCount > 0 ? `\n_Additional failed versions omitted: ${omittedCount}_` : "",
-                "",
-                `Workflow run: ${context.serverUrl}/${owner}/${repo}/actions/runs/${context.runId}`,
-              ].join("\n")
-
-              await github.rest.issues.create({
-                owner,
-                repo,
-                title,
-                body,
-              })
-              openIssueTitles.add(title)
-              core.info(`Created issue: ${title}`)
-            }
-
-      - name: Refresh lockfile
-        # Only refresh lockfile after a clean validation to avoid committing known-bad ranges.
-        if: steps.validate_ranges.outcome == 'success'
-        run: uv lock --upgrade
-        working-directory: ./python
-
-      - name: Commit and push dependency updates
-        id: commit_updates
-        if: steps.validate_ranges.outcome == 'success'
-        run: |
-          BRANCH="automation/python-dependency-range-updates"
-
-          git config user.name "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git checkout -B "${BRANCH}"
-
-          git add python/packages/*/pyproject.toml python/uv.lock
-          if git diff --cached --quiet; then
-            echo "has_changes=false" >> "$GITHUB_OUTPUT"
-            echo "No dependency updates to commit."
-            exit 0
-          fi
-
-          git commit -m "chore: update dependency ranges"
-          git push --force-with-lease --set-upstream origin "${BRANCH}"
-          echo "has_changes=true" >> "$GITHUB_OUTPUT"
-
-      - name: Create or update pull request with GitHub CLI
-        # Only open/update PRs for validated updates to keep automation branches trustworthy.
-        if: steps.validate_ranges.outcome == 'success' && steps.commit_updates.outputs.has_changes == 'true'
-        run: |
-          BRANCH="automation/python-dependency-range-updates"
-          PR_TITLE="Python: chore: update dependency ranges"
-          PR_BODY_FILE="$(mktemp)"
-
-          cat > "${PR_BODY_FILE}" <<'EOF'
-          This PR was generated by the dependency range validation workflow.
-
-          - Ran `uv run poe validate-dependency-bounds-project --mode upper --package "*"`
-          - Updated package dependency bounds
-          - Refreshed `python/uv.lock` with `uv lock --upgrade`
-          EOF
-
-          PR_NUMBER="$(gh pr list --head "${BRANCH}" --base main --state open --json number --jq '.[0].number')"
-          if [ -n "${PR_NUMBER}" ]; then
-            gh pr edit "${PR_NUMBER}" --title "${PR_TITLE}" --body-file "${PR_BODY_FILE}"
-          else
-            gh pr create --base main --head "${BRANCH}" --title "${PR_TITLE}" --body-file "${PR_BODY_FILE}"
-          fi

.github/workflows/python-dev-dependency-upgrade.yml

@@ -1,91 +0,0 @@
-name: Python - Dev Dependency Upgrade
-
-on:
-  workflow_dispatch:
-
-permissions:
-  contents: write
-  pull-requests: write
-
-env:
-  UV_CACHE_DIR: /tmp/.uv-cache
-
-jobs:
-  upgrade-dev-dependencies:
-    name: Upgrade Dev Dependencies
-    runs-on: ubuntu-latest
-    env:
-      UV_PYTHON: "3.13"
-      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
-        with:
-          fetch-depth: 0
-
-      - name: Set up python and install the project
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-        env:
-          UV_CACHE_DIR: /tmp/.uv-cache
-
-      - name: Upgrade dev dependencies and validate workspace
-        run: uv run poe upgrade-dev-dependencies
-        working-directory: ./python
-
-      - name: Commit and push dev dependency updates
-        id: commit_updates
-        run: |
-          BRANCH="automation/python-dev-dependency-updates"
-
-          git config user.name "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git checkout -B "${BRANCH}"
-
-          git add python/pyproject.toml python/packages/*/pyproject.toml python/uv.lock
-          if git diff --cached --quiet; then
-            echo "has_changes=false" >> "$GITHUB_OUTPUT"
-            echo "No dev dependency updates to commit."
-            exit 0
-          fi
-
-          git commit -F- <<'EOF'
-          Python: chore: upgrade dev dependencies
-          EOF
-          git push --force-with-lease --set-upstream origin "${BRANCH}"
-          echo "has_changes=true" >> "$GITHUB_OUTPUT"
-
-      - name: Create or update pull request with GitHub CLI
-        if: steps.commit_updates.outputs.has_changes == 'true'
-        run: |
-          BRANCH="automation/python-dev-dependency-updates"
-          PR_TITLE="Python: chore: upgrade dev dependencies"
-          PR_BODY_FILE="$(mktemp)"
-
-          cat > "${PR_BODY_FILE}" <<'EOF'
-          ### Motivation and Context
-
-          This automated update refreshes Python dev dependency pins across the workspace and reruns the repo validation gates before opening a pull request.
-
-          ### Description
-
-          - Ran `uv run poe upgrade-dev-dependencies`
-          - Refreshed dev dependency pins in workspace `pyproject.toml` files
-          - Refreshed `python/uv.lock` with `uv lock --upgrade`
-          - Reinstalled from the frozen lockfile and reran `check`, `typing`, and `test`
-
-          ### Contribution Checklist
-
-          - [x] The code builds clean without any errors or warnings
-          - [x] The PR follows the [Contribution Guidelines](https://github.com/microsoft/agent-framework/blob/main/CONTRIBUTING.md)
-          - [x] All unit tests pass, and I have added new tests where possible
-          - [ ] **Is this a breaking change?** If yes, add "[BREAKING]" prefix to the title of the PR.
-          EOF
-
-          PR_NUMBER="$(gh pr list --head "${BRANCH}" --base main --state open --json number --jq '.[0].number')"
-          if [ -n "${PR_NUMBER}" ]; then
-            gh pr edit "${PR_NUMBER}" --title "${PR_TITLE}" --body-file "${PR_BODY_FILE}"
-          else
-            gh pr create --base main --head "${BRANCH}" --title "${PR_TITLE}" --body-file "${PR_BODY_FILE}"
-          fi

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

@@ -92,9 +92,6 @@ jobs:
       - name: Run lab type checking
         run: cd packages/lab && uv run poe pyright
 
-      - name: Run lab mypy
-        run: cd packages/lab && uv run poe mypy
-
       # Surface failing tests
       - name: Surface failing tests
         if: always()

.github/workflows/python-test-coverage-report.yml

@@ -30,21 +30,31 @@ jobs:
           merge-multiple: true
       - name: Display structure of downloaded files
         run: ls
-      - name: Read and set PR number
-        # Need to read the PR number from the file saved in the previous workflow
-        # because the workflow_run event does not have access to the PR number
-        # The PR number is needed to post the comment on the PR
+      - name: Read and validate PR number
+        # Keep the artifact handoff aligned with the workflow run that produced it.
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          RUN_HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
         run: |
           if [ ! -s pr_number ]; then
             echo "PR number file 'pr_number' is missing or empty"
             exit 1
           fi
-          PR_NUMBER=$(cat pr_number)
-          if ! [[ "$PR_NUMBER" =~ ^[0-9]+$ ]]; then
+
+          ARTIFACT_PR_NUMBER=$(cat pr_number)
+          if ! [[ "$ARTIFACT_PR_NUMBER" =~ ^[0-9]+$ ]]; then
             echo "::error::PR number file contains invalid content"
             exit 1
           fi
-          echo "PR_NUMBER=$PR_NUMBER" >> "$GITHUB_ENV"
+
+          PR_HEAD_SHA=$(gh pr view "$ARTIFACT_PR_NUMBER" --repo "$REPO" --json headRefOid --jq '.headRefOid')
+          if [ "$PR_HEAD_SHA" != "$RUN_HEAD_SHA" ]; then
+            echo "::error::PR head SHA does not match the triggering workflow run"
+            exit 1
+          fi
+
+          echo "PR_NUMBER=$ARTIFACT_PR_NUMBER" >> "$GITHUB_ENV"
       - name: Pytest coverage comment
         id: coverageComment
         uses: MishaKav/pytest-coverage-comment@26f986d2599c288bb62f623d29c2da98609e9cd4 # v1.6.0

docs/decisions/0027-hosting-channels.md

@@ -0,0 +1,144 @@
+---
+status: accepted
+contact: eavanvalkenburg
+date: 2026-06-11
+deciders: eavanvalkenburg
+---
+
+# Python minimal hosting core and pluggable channels
+
+## Context and Problem Statement
+
+Agent Framework has several protocol-specific hosting surfaces. App authors who want one agent or workflow on multiple protocols must compose servers, routes, middleware, session handling, and lifecycle code by hand.
+
+We will introduce a small Python hosting core that owns the common server shape and leaves protocol details inside channel packages. The first public contract must be intentionally narrow so Python can ship a base contract before adding identity linking, proactive delivery, or multicast behavior. Other language implementations may reuse the same conceptual boundary, but this ADR records the Python decision.
+
+## Decision Drivers
+
+- Keep the first host easy to explain: one app, one hostable target, one or more channels.
+- Reuse Agent Framework's existing agent, workflow, session, history, and checkpoint primitives.
+- Let channel packages own protocol parsing, protocol responses, authentication details, and native command surfaces.
+- Make session continuity explicit through a channel-supplied `ChannelSession(isolation_key=...)`.
+- Avoid approving cross-channel identity and delivery semantics before their safety model is reviewed.
+
+## Considered Options
+
+1. Keep only protocol-specific hosts.
+2. Ship a large hosting core with identity linking, authorization, background delivery, active-channel routing, and multicast in v1.
+3. Ship a minimal host/channel core now and track linking/multicast as follow-up work.
+
+### Keep only protocol-specific hosts
+
+- Good: no new abstraction or package surface.
+- Neutral: each protocol can continue evolving independently.
+- Bad: every multi-channel app still has to compose servers, lifecycle, and session handling by hand.
+
+### Ship the large cross-channel host in v1
+
+- Good: the richest cross-channel scenarios are available immediately.
+- Neutral: the host becomes the natural place to demonstrate identity and delivery policy.
+- Bad: v1 becomes a security-sensitive identity and delivery system before the safety model is reviewed.
+
+### Ship the minimal core now
+
+- Good: the host/channel boundary can be implemented, tested, and explained without solving linking and durable delivery at the same time.
+- Neutral: apps that need richer behavior must build it locally or wait for ADR-0028 follow-up work.
+- Bad: proactive delivery and multicast scenarios are deliberately absent from v1.
+
+## Decision Outcome
+
+Chosen option: **minimal host/channel core now, follow-up enhancements later**.
+
+`AgentFrameworkHost` owns:
+
+- one application object,
+- one hostable target (`SupportsAgentRun` agent-compatible object or a `Workflow`), and
+- one or more channels.
+
+Channels own:
+
+- contributed routes, middleware, commands, and lifecycle callbacks,
+- protocol-native request parsing into `ChannelRequest`,
+- protocol-native rendering of the originating response, and
+- any channel-specific authentication or signature validation.
+
+The host owns:
+
+- route/lifecycle aggregation,
+- invocation of the target,
+- `ChannelSession(isolation_key=...)` to `AgentSession` resolution and caching,
+- `reset_session(isolation_key=...)`,
+- host-level middleware, including Foundry isolation middleware only when the Foundry hosting environment flag is present,
+- invocation of per-channel hooks (`ChannelRunHook`, `ChannelResponseHook`, `ChannelStreamUpdateHook`), and
+- workflow checkpoint wiring through an explicit `checkpoint_location`.
+
+`ChannelIdentity`, when present, is request metadata only. In v1 it is not a linking, authorization, or delivery key.
+
+### Trust boundary for `isolation_key`
+
+The host treats `ChannelSession.isolation_key` as a session partition key, not as proof of identity. Channels or host middleware must authenticate and authorize any externally supplied value before passing it to the host. For example, a Responses caller must not be allowed to choose an arbitrary `previous_response_id` or header-derived key unless the platform or middleware has already established that the caller owns that conversation. The host deliberately does not infer that trust from the string itself.
+
+### Hook ownership
+
+Channels provide hook configuration and protocol-native context. The host invokes those hooks as part of the common invocation pipeline:
+
+- `ChannelRunHook` runs after channel parsing and before target invocation.
+- `ChannelResponseHook` runs after target invocation and before the originating channel serializes its response.
+- `ChannelStreamUpdateHook` is applied by the host while the channel consumes streamed updates because streaming serialization is protocol-specific.
+
+`ChannelStreamUpdateHook` is an update hook, not a final-response sanitizer. Channels that use it for redaction or filtering must also apply equivalent policy to any final response they render. Channels choose whether the response is streaming before run hooks execute.
+
+This keeps hook call conventions centralized while leaving protocol payload parsing and response formatting in channel packages.
+
+### State owned by v1
+
+`state_dir` is limited to host-owned local files for reset-session aliases and workflow checkpoint path derivation. It does not store linked identities, active-channel state, response-routing state, continuation records, durable runner queues, or delivery attempts. Those storage concerns belong to ADR-0028.
+
+## Non-goals for v1
+
+The following are deliberately **not** part of the v1 contract:
+
+- cross-channel identity linking (`IdentityLinker`, `local_identity_link`, or `agent-framework-hosting-entra`),
+- identity allowlists or authorization policy (`IdentityAllowlist`, `AuthPolicy`),
+- response routing beyond the originating channel (`ResponseTarget`, active channel, specific linked channel, `all_linked`),
+- push or payload codecs (`ChannelPush`, `ChannelPushCodec`),
+- background/continuation delivery,
+- durable task runners (`DurableTaskRunner`, `InProcessTaskRunner`),
+- retry/replay policy (`RetryPolicy`),
+- fan-out, multicast, or all-linked delivery,
+- confidentiality tiers and `LinkPolicy`, and
+- a host-level multi-agent router.
+
+These areas are follow-up enhancements covered by [ADR-0028](0028-hosting-linking-multicast-enhancements.md). They are not prerequisites for shipping or using the v1 host.
+
+## Consequences
+
+Positive:
+
+- The host/channel model can be implemented and tested without designing a security-sensitive identity graph.
+- Existing and new channel packages can share one Starlette app, middleware stack, lifecycle, and target invocation path.
+- Session continuity is explicit and debuggable: two channels share history only when they produce the same `isolation_key`.
+- Hook invocation is centralized in the host, so channels do not each invent the call convention.
+
+Negative:
+
+- Apps that need OAuth linking, allowlists, proactive messages, or multicast must continue to implement those behaviors outside the v1 host.
+- Some richer cross-channel scenarios from the original design move to a separate decision and validation cycle.
+- The host must document `isolation_key` trust clearly because it now provides the shared session boundary.
+
+## Validation Gates
+
+Before this ADR is accepted:
+
+- A sample can expose one target on multiple channels with one `AgentFrameworkHost` and no handwritten Starlette route composition.
+- Built-in channel tests prove that routes, commands, startup, and shutdown callbacks are contributed by channels and aggregated by the host.
+- Session tests prove that identical `ChannelSession.isolation_key` values resolve to the same cached `AgentSession`, and `reset_session` rotates that mapping.
+- Channel tests prove that each channel renders only its own originating response; there is no host-level push, multicast, or active-channel delivery path.
+- Workflow tests or samples use an explicit `checkpoint_location`.
+- Foundry isolation middleware is documented and covered by integration or contract tests, including the non-Foundry case where raw isolation headers are ignored.
+- The v1 API and packages do not expose the removed symbols or packages listed in [Non-goals for v1](#non-goals-for-v1).
+- The Python spec is updated to match this simplified contract and uses "public", "stable", or "released" terminology for Agent Framework APIs.
+
+## More Information
+
+- Follow-up linking and multicast ADR: [ADR-0028](0028-hosting-linking-multicast-enhancements.md)

docs/decisions/0028-hosting-linking-multicast-enhancements.md

@@ -0,0 +1,132 @@
+---
+status: proposed
+contact: eavanvalkenburg
+date: 2026-06-11
+deciders: eavanvalkenburg
+---
+
+# Hosting linking and multicast enhancements
+
+## Context and Problem Statement
+
+[ADR-0027](0027-hosting-channels.md) defines the minimal v1 hosting core: originating-channel responses, explicit `ChannelSession.isolation_key`, and no host-level identity linking, push, multicast, background delivery, or durable runners.
+
+This ADR tracks the richer cross-channel behaviors that were removed from v1. These enhancements are **follow-up work** and are **not prerequisites** for shipping, using, or stabilizing the v1 host/channel core.
+
+## Decision Drivers
+
+- Cross-channel continuity must not create accidental cross-user, cross-tenant, or cross-channel data leaks.
+- Non-originating delivery must be observable, idempotent, retryable, and supportable.
+- Protocol payloads must remain channel-native while still being safe to persist and replay.
+- App authors need opt-in policy controls, not hidden defaults.
+- The enhancement stack should layer on top of the v1 host without reshaping the minimal channel contract.
+
+## Enhancement Areas
+
+The follow-up design should cover these capabilities together because they share identity, storage, delivery, and replay concerns:
+
+- **Cross-channel identity linking** — a user can connect multiple `ChannelIdentity` values to one channel-neutral `isolation_key`.
+- **Authorization and allowlist policy** — channels or hosts can require verified identity, allow specific native identities or claims, and deny unknown callers.
+- **Non-originating response delivery** — a run can respond somewhere other than the request's originating protocol when explicitly configured.
+- **Active-channel routing** — delivery can target the most recently observed linked channel for an `isolation_key`.
+- **Multicast / all-linked delivery** — delivery can fan out to every linked channel or a selected set.
+- **Background runs and continuation tokens** — long-running requests can return immediately and complete later, with a polling/status fallback.
+- **Durable delivery runners** — delivery work can survive process restarts and support dead-letter handling.
+- **Retry and replay semantics** — delivery attempts are bounded, deduplicated, and safe to replay.
+- **Payload serialization** — channel-specific payloads can be persisted, redacted, versioned, and reconstructed without losing protocol fidelity.
+
+Candidate API names from the broader design (`IdentityLinker`, `IdentityAllowlist`, `AuthPolicy`, `ResponseTarget`, `ChannelPush`, `ChannelPushCodec`, `DurableTaskRunner`, `InProcessTaskRunner`, `RetryPolicy`, `LinkPolicy`) remain design vocabulary for this ADR. They are not approved v1 APIs.
+
+## Considered Options
+
+### Option A — Leave all behavior to applications
+
+Applications implement linking, authorization, push, retry, and serialization independently.
+
+- Good: the hosting core stays very small.
+- Neutral: advanced apps can still build what they need.
+- Bad: every app must solve the same security and delivery problems, likely inconsistently.
+
+### Option B — Add the full enhancement stack to v1
+
+The first host release includes linking, authorization, active channel, multicast, background runs, durable runners, and codecs.
+
+- Good: the original cross-channel experience is available immediately.
+- Neutral: samples can demonstrate rich end-to-end flows.
+- Bad: v1 becomes security-sensitive, storage-heavy, and harder to stabilize.
+
+### Option C — Layer opt-in enhancement packages after v1
+
+Ship the minimal host first, then add linking, authorization, and delivery packages behind explicit configuration.
+
+- Good: v1 remains simple while leaving room for a reviewed, supportable enhancement stack.
+- Neutral: apps that need advanced delivery wait for follow-up packages.
+- Bad: the first release does not satisfy proactive or all-linked scenarios.
+
+### Option D — Build only platform-specific integrations
+
+Implement linking and proactive delivery separately in Telegram, Activity Protocol, Discord, and future channels.
+
+- Good: each package can match its protocol exactly.
+- Neutral: some shared abstractions may emerge later.
+- Bad: cross-channel behavior becomes fragmented and hard to reason about.
+
+## Decision Outcome
+
+Proposed direction: **Option C — layered opt-in enhancement packages after v1**.
+
+The minimal host remains the foundation. Follow-up packages may add linking, authorization, delivery, and durable execution, but must be explicitly enabled and must pass the validation gates below before becoming part of the public contract.
+
+## Safety Requirements
+
+### Threat model
+
+The design must account for:
+
+- spoofed channel-native identities,
+- stolen or replayed link challenges,
+- cross-tenant or cross-confidentiality data leakage,
+- unsolicited proactive messages,
+- malicious payloads persisted for replay,
+- denial-of-service through fan-out or retry storms, and
+- privacy leakage through logs, metrics, or support tooling.
+
+Required mitigations include verified identity claims where available, signed and expiring link challenges, explicit user consent, per-channel capability checks, default-deny policy options, tenant partitioning, and uninformative denial messages on shared channels.
+
+### Idempotency and replay
+
+Exactly-once delivery is not a realistic guarantee. The design must provide:
+
+- stable run, continuation, and delivery-attempt identifiers,
+- channel-level idempotency keys where protocols support them,
+- bounded retry with jitter and explicit terminal states,
+- replay windows and expiration,
+- duplicate suppression for persisted attempts, and
+- clear semantics for "delivered", "accepted by platform", and "observed by user".
+
+### Storage
+
+Enhancement storage must stay distinct from v1 `AgentSession` history and workflow checkpoints unless an implementation deliberately backs them with the same physical store.
+
+Stored data should be schema-versioned, minimized, encrypted or otherwise protected as appropriate, and partitioned by tenant/project. Link records, continuation records, active-channel state, delivery attempts, dead letters, and serialized payloads need independent TTL and deletion policies.
+
+### Observability and support
+
+The design must include structured logs, traces, and metrics for link attempts, authorization decisions, delivery scheduling, retries, replay, and dead-letter outcomes. Logs must avoid message content and sensitive identity claims by default. Operators need a way to inspect, revoke, replay, or purge stuck records safely.
+
+## Validation Gates
+
+Before these enhancements are accepted:
+
+- A reviewed threat model covers identity linking, authorization, non-originating delivery, multicast, and replay.
+- Cross-channel linking tests prove a verified identity can link two channels and that unlink/deny paths do not leak information.
+- Authorization tests cover native-id allowlists, verified-claim allowlists, default-deny behavior, and misconfiguration failures.
+- Delivery tests cover originating-only, specific-channel, active-channel, selected-channel, and all-linked routing.
+- Background/continuation tests cover polling fallback, cancellation or expiration, process restart, retry, and dead-letter behavior.
+- Codec tests prove payloads are versioned, redacted where needed, backward compatible, and rejected safely when unknown.
+- Multicast tests prove fan-out is bounded, independently retried, and idempotent per destination.
+- Observability tests or manual validation prove support operators can correlate a request to delivery attempts without exposing sensitive content.
+
+## Relationship to ADR-0027
+
+ADR-0027 remains valid without any of these enhancements. This ADR extends the hosting model only after the safety, storage, and support requirements above are satisfied.

docs/decisions/0029-mcp-skill-templates-and-direct-references.md

@@ -0,0 +1,641 @@
+---
+status: proposed
+contact: sergeymenshykh
+date: 2026-06-23
+deciders: sergeymenshykh
+---
+
+# Skills Over MCP: Implementation Design Options
+
+This document explores design options for two SEP-2640 features. The decisions are not yet finalized.
+
+- **Part 1: MCP Resource Template Skills** - skills described by a URI template with variables that must be resolved before loading.
+- **Part 2: Direct Skill References** - reading `skill://` URIs referenced directly (e.g., in server instructions) without being listed in the index.
+
+## Part 1: MCP Resource Template Skills
+
+### Context and Problem Statement
+
+The `AgentMcpSkillsSource` currently only supports `skill-md` type entries from `skill://index.json` (support for `archive` type is planned). The SEP-2640 specification also defines `mcp-resource-template` entries: **parameterized skill namespaces** described by a URI template with variables (e.g., `{product}`) that resolve to concrete `SKILL.md` URIs. Rather than materializing every skill in the index, the template's variables must be resolved before a skill can be loaded.
+
+### Index Entry Format
+
+```json
+{
+  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
+  "skills": [
+    {
+      "name": "git-workflow",
+      "type": "skill-md",
+      "description": "Follow this team's Git conventions for branching and commits",
+      "url": "skill://git-workflow/SKILL.md"
+    },
+    {
+      "type": "mcp-resource-template",
+      "description": "Per-product documentation skill",
+      "url": "skill://docs/{product}/SKILL.md"
+    }
+  ]
+}
+```
+
+Key differences from `skill-md`:
+
+| Field | `skill-md` | `mcp-resource-template` |
+|-------|------------|-------------------------|
+| `name` | Required (the skill name) | **Omitted** (represents many skills) |
+| `type` | `"skill-md"` | `"mcp-resource-template"` |
+| `url` | Concrete URI to `SKILL.md` | URI template with variables |
+| `description` | Describes the skill | Describes the addressable skill space |
+
+### Use Cases
+
+Template skills address two scenarios where listing concrete skills is impractical:
+
+- **Large skill catalogs** - too many skills to enumerate every entry in the index.
+- **Dynamically generated skills** - skill content generated on the fly from parameters, so the set of valid skills is not known at index-creation time.
+
+### How Template Skills Are Consumed
+
+Per SEP-2640, the consumption flow relies on the MCP `completion/complete` method:
+
+1. **Server registers a resource template** - The MCP server registers the same `url` value (e.g., `skill://docs/{product}/SKILL.md`) as an MCP [resource template](https://modelcontextprotocol.io/specification/2025-11-25/server/resources#resource-templates), wiring template variables to the [completion API](https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/completion).
+
+2. **Host reads `skill://index.json`** - Discovers the template entry with `type: "mcp-resource-template"`.
+
+3. **Host surfaces template in UI** - Presents the template as an interactive discovery point where the user fills in variables.
+
+4. **Host calls `completion/complete`** - For each template variable (e.g., `{product}`), the host calls the MCP completion API to get possible values from the server:
+   ```json
+   {
+     "method": "completion/complete",
+     "params": {
+       "ref": {
+         "type": "ref/resource",
+         "uri": "skill://docs/{product}/SKILL.md"
+       },
+       "argument": {
+         "name": "product",
+         "value": ""
+       }
+     }
+   }
+   ```
+   The server responds with possible completions:
+   ```json
+   {
+     "completion": {
+       "values": ["widgets", "billing", "auth", "payments"],
+       "hasMore": false,
+       "total": 4
+     }
+   }
+   ```
+
+5. **User selects a value** - The user picks a value (e.g., `"billing"`) from the list.
+
+6. **Host resolves the URI** - The template `skill://docs/{product}/SKILL.md` becomes the concrete URI `skill://docs/billing/SKILL.md`.
+
+7. **Host reads the resolved skill** - Calls `resources/read` with the concrete URI and proceeds as with any `skill-md` skill.
+
+### Potential Implementation Options
+
+### Option 1: Callback on `AgentMcpSkillsSource` for Variable Value Selection
+
+Add a callback to `AgentMcpSkillsSource` (or its options) that is invoked for each `mcp-resource-template` entry to let the caller select variable values.
+
+**Flow:**
+
+1. `AgentMcpSkillsSource.GetSkillsAsync()` reads `skill://index.json`
+2. For each entry with `type: "mcp-resource-template"`:
+   - Parse the URI template to extract variable names (e.g., `{product}`)
+   - Call the MCP `completion/complete` API to get possible values for each variable
+   - Invoke the caller-provided callback with the variable name, description, and possible values
+   - The callback returns a selected value and a `bool` indicating whether to include the skill
+3. Resolve the URI template with the selected values
+4. Create an `AgentMcpSkill` from the resolved URI and add it to the skills list
+
+**API sketch:**
+
+```csharp
+public delegate Task<(string? SelectedValue, bool IncludeSkill)> McpTemplateVariableSelector(
+    string templateDescription,
+    string variableName,
+    IReadOnlyList<string> possibleValues,
+    CancellationToken cancellationToken);
+
+// Usage via builder:
+var provider = new AgentSkillsProviderBuilder()
+    .UseMcpSkills(mcpClient, options => {
+        options.TemplateVariableSelector = async (description, variable, values, ct) =>
+        {
+            // Present to user, return selection
+            var selected = PromptUser(variable, values);
+            return (selected, IncludeSkill: selected is not null);
+        };
+    })
+    .Build();
+```
+
+**Pros:**
+- Simple implementation
+- Easy to understand and use
+
+**Cons:**
+- Cannot be used in server-side scenarios where there is no interactive user at skill-discovery time
+- Does not integrate with the agent's conversational flow
+
+---
+
+### Option 2: Integrate into Agent Conversation via `ChatClientAgent` Decorator
+
+Model the template variable resolution as a request/response interaction within the agent's conversational loop.
+
+**Flow:**
+
+1. A `DelegatingAIAgent` decorator (e.g., `McpTemplateSkillResolutionAgent`) intercepts `RunAsync`/`RunStreamingAsync` calls and checks whether the inner agent has an `AgentSkillsProvider` with an `AgentMcpSkillsSource` containing unresolved template entries. The check is performed via `GetService<AgentMcpSkillsSource>()` on the `AgentSkillsProvider`, which delegates to a `GetService` method on the `AgentSkillsSource` base class.
+
+2. The decorator calls an internal member on `AgentMcpSkillsSource` to get the list of `mcp-resource-template` entries from the index. The `AgentMcpSkillsSource` needs to be extended with an internal member that exposes unresolved template entries separately from concrete skills.
+
+3. For each template entry, the decorator calls an internal member on `AgentMcpSkillsSource` to retrieve possible values for the template's variables via the MCP `completion/complete` API.
+
+4. For each variable needing resolution, the decorator returns an `McpResourceTemplateValueRequestContent` (inherits from MEAI's `InputRequestContent`) in the agent response - bypassing the call to the inner agent. The content carries the template description, variable name, and possible values.
+
+5. The user app receives the response, identifies the `McpResourceTemplateValueRequestContent` content type, and displays UI to the user showing the variable name and possible values, or forwards it further downstream if the user app is a service.
+
+6. The user selects a value, and the user app calls the agent again with a corresponding `McpResourceTemplateValueResponseContent` (inherits from MEAI's `InputResponseContent`) containing the selected value. The `RequestId` property (inherited from the base classes) correlates the response with the original request.
+
+7. The decorator identifies the response content and provides the resolved values to `AgentMcpSkillsSource` so it can use them when constructing concrete skills.
+
+8. Having resolved all template variables, the decorator calls `RunAsync`/`RunStreamingAsync` on the inner agent.
+
+9. The inner agent invokes the `AgentSkillsProvider`, which calls `AgentMcpSkillsSource.GetSkillsAsync()`. The source now has all resolved variable values and constructs concrete `AgentMcpSkill` instances from the resolved URIs, so it can provide the skill content if requested by the model.
+
+**API sketch:**
+
+```csharp
+// New content types inheriting from MEAI's InputRequestContent/InputResponseContent:
+public sealed class McpResourceTemplateValueRequestContent : InputRequestContent
+{
+    public string TemplateDescription { get; }
+    public string VariableName { get; }
+    public IReadOnlyList<string> PossibleValues { get; }
+    public string TemplateUrl { get; }
+}
+
+public sealed class McpResourceTemplateValueResponseContent : InputResponseContent
+{
+    public string SelectedValue { get; }
+    public string TemplateUrl { get; }
+}
+
+// Decorator usage:
+var provider = new AgentSkillsProviderBuilder()
+    .UseMcpSkills(mcpClient)
+    .Build();
+
+AIAgent agent = new ChatClientAgent(chatClient, new ChatClientAgentOptions
+{
+    AIContextProviders = [provider],
+});
+agent = new McpTemplateSkillResolutionAgent(agent);
+```
+
+**Pros:**
+- Works in server-side scenarios
+- Fits the existing `DelegatingAIAgent` decorator pattern
+- Can be composed with other decorators (tool approval, etc.)
+
+**Cons:**
+- Complex implementation
+- Requires user app awareness of the new content types
+- Users need to know that an additional decorator is required for handling MCP template skills, in addition to registering the MCP skills source
+- Resolved template variable values must be persisted across conversation turns so the decorator does not re-prompt on subsequent agent runs within the same session
+
+**Note:** This writeup is high-level and may miss details that could change the design. A POC would be needed to validate the approach.
+
+### Open Questions
+
+1. **Completion API limit** - The MCP completion API returns at most 100 values per request and provides no offset/cursor mechanism for enumeration. If a variable has more than 100 possible values, it's unclear how to retrieve the rest - the API only supports prefix-based filtering (typeahead), not bulk pagination.
+
+2. **Multi-variable templates** - A template like `skill://{org}/{product}/SKILL.md` has multiple variables. Should they be resolved sequentially (org first, then product - since product values may depend on org) or presented together?
+
+3. **Caching** - Should resolved template values be saved in the `AgentSession` so the user isn't re-prompted on every agent run? How should they be persisted between sessions?
+
+---
+
+## Part 2: Direct Skill References
+
+This part covers how to let the model read `skill://` URIs referenced directly (e.g., in an MCP server's `instructions`, in a resource, or in another skill's content) without being listed in `skill://index.json`.
+
+### How MCP Skills and Relative Links Work Today
+
+The `AgentMcpSkillsSource` discovers skills by reading the well-known `skill://index.json` resource from the MCP server:
+
+```json
+{
+  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
+  "skills": [
+    {
+      "name": "unit-converter",
+      "type": "skill-md",
+      "description": "Convert between common units.",
+      "url": "skill://unit-converter/SKILL.md"
+    },
+    {
+      "name": "currency-converter",
+      "type": "skill-md",
+      "description": "Convert between world currencies using live rates.",
+      "url": "skill://currency-converter/SKILL.md"
+    }
+  ]
+}
+```
+
+For each `skill-md` entry it creates an `AgentMcpSkill` instance - frontmatter (name/description) comes straight from the entry. The `AgentSkillsProvider` lists the discovered skills in the model's context (name + description):
+
+```xml
+<available_skills>
+  <skill>
+    <name>unit-converter</name>
+    <description>Convert between common units.</description>
+  </skill>
+  <skill>
+    <name>currency-converter</name>
+    <description>Convert between world currencies using live rates.</description>
+  </skill>
+</available_skills>
+```
+
+It also provides functions to the model so it can load a skill and access its resources:
+
+```csharp
+// Loads the full content of a specific skill.
+load_skill(string skillName)
+
+// Reads a resource associated with a skill (references, assets, dynamic data).
+read_skill_resource(string skillName, string resourceName)
+```
+
+The model calls `load_skill("unit-converter")` and receives the skill content:
+
+```markdown
+---
+name: unit-converter
+description: Convert between common units.
+---
+## Usage
+
+For the full conversion table, see references/units-table.md.
+```
+
+The skill body references `references/units-table.md` by relative path. The model calls `read_skill_resource("unit-converter", "references/units-table.md")` and receives the resource content:
+
+```markdown
+# Unit Conversion Table
+
+| From  | To   | Factor  |
+| miles | km   | 1.60934 |
+| kg    | lbs  | 2.20462 |
+```
+
+### Direct Reference Examples
+
+A `skill://` URI can appear in any of these locations:
+
+**Server instructions** - the MCP server advertises a skill the model should load:
+
+```text
+Follow our coding standards. Load skill://code-standards/SKILL.md for details.
+```
+
+**A skill body** - a skill's `SKILL.md` links to a sibling resource:
+
+```markdown
+---
+name: code-standards
+description: Coding standards and conventions.
+---
+## Naming
+
+Follow the naming rules in skill://code-standards/references/naming.md.
+```
+
+**A resource** - the linked resource holds the actual content:
+
+```markdown
+# Naming Rules
+
+- Use PascalCase for public members and type names.
+- Use camelCase for locals and parameters.
+- Prefix interfaces with `I` (e.g. `ISkillReader`).
+- Suffix async methods with `Async`.
+
+For examples, see skill://code-standards/references/naming-examples.md.
+```
+
+How can the model access content by direct reference?
+
+### Function for Reading Direct Skill References
+
+### Option 1: Extend existing `load_skill` and `read_skill_resource` functions
+
+```csharp
+// Added optional 'origin' and a direct skill:// URI is passed in 'skillName'.
+load_skill(string skillName, string? origin = null)
+
+// Added optional 'origin', made 'skillName' optional, and a direct skill:// URI is passed in 'resourceName'.
+read_skill_resource(string resourceName, string? skillName = null, string? origin = null)
+```
+
+The optional `origin` identifies the source/MCP server that should handle the direct URI.
+
+| Case | Call |
+|------|------|
+| Load skill | `load_skill("commit-guidelines")` |
+| Relative resource | `read_skill_resource("commit-guidelines", "examples/COMMIT_EXAMPLES.md")` |
+| `skill://` link (skill) | `load_skill(skillName: "skill://commit-guidelines/SKILL.md", origin: "DirectRefServer")` |
+| `skill://` link (resource) | `read_skill_resource(resourceName: "skill://commit-guidelines/examples/COMMIT_EXAMPLES.md", origin: "DirectRefServer")` |
+
+**Pros:**
+
+- No new functions added: existing tool surface stays at two functions.
+
+**Cons:**
+
+- Unreliable on some models (gpt-4o, gpt-4.1-mini): it often omits `origin` when it should not or calls the wrong function.
+- Optional parameters create silent ambiguity - the model can pass `origin` for non-MCP skills or omit it for `skill://` URIs.
+
+### Option 2 (Proposed): Add a dedicated `read_skill_uri` function alongside existing ones
+
+```csharp
+// Existing functions stay unchanged.
+load_skill(string skillName)
+read_skill_resource(string skillName, string resourceName)
+
+// New function added alongside: reads content by direct skill:// URI.
+read_skill_uri(string uri, string origin)
+```
+
+| Case | Call |
+|------|------|
+| Load skill | `load_skill("commit-guidelines")` |
+| Relative resource | `read_skill_resource("commit-guidelines", "examples/COMMIT_EXAMPLES.md")` |
+| `skill://` link (skill) | `read_skill_uri(uri: "skill://commit-guidelines/SKILL.md", origin:"DirectRefServer")` |
+| `skill://` link (resource) | `read_skill_uri(uri: "skill://commit-guidelines/examples/COMMIT_EXAMPLES.md", origin: "DirectRefServer")` |
+
+**Pros:**
+
+- Purely additive - no changes to existing functions needed; `read_skill_uri` can be deferred and added later when direct `skill://` reference support is needed.
+- Granular approval: each function can have its own approval gate (like the existing `ScriptApproval` for `run_skill_script`), making per-operation approval for skill loading, resource reading, and direct URI access straightforward to add.
+- Both `uri` and `origin` are required - no silent misuse through optional parameters.
+- Clean split: `load_skill`/`read_skill_resource` for named skills, `read_skill_uri` for `skill://` links - no parameter ambiguity.
+
+**Cons:**
+
+- Three read functions (`load_skill`, `read_skill_resource`, `read_skill_uri`), not counting `run_skill_script`: larger tool surface than a single-function design.
+
+### Option 3: Collapse `load_skill` and `read_skill_resource` into a single `read_resource` function
+
+```csharp
+// Single entrypoint for all skill content. 'uri' is required; 'origin' is optional.
+read_resource(string uri, string? origin = null)
+```
+
+- `uri` - what to read: a skill name, a relative resource path, or a `skill://` link.
+- `origin` - determines how `uri` is interpreted:
+  - **omitted** → load skill by name (`uri` is the skill name).
+  - **skill name** → read a relative resource (`uri` is the path within that skill).
+  - **server name** → read content by the `skill://` link (`uri` is handled by the source identified by the `[Origin: X]` marker).
+
+Dispatch is ordered: null `origin` routes to Case 1; if `origin` names a known skill, routes to Case 2; otherwise tries to find an `ISkillUriReader` whose `CanRead` returns true for `origin` (Case 3).
+
+| Case | Call |
+|------|------|
+| Load skill | `read_resource(uri: "commit-guidelines")` |
+| Relative resource | `read_resource(uri: "examples/COMMIT_EXAMPLES.md", origin: "commit-guidelines")` |
+| `skill://` link (skill) | `read_resource(uri: "skill://commit-guidelines/SKILL.md", origin: "DirectRefServer")` |
+| `skill://` link (resource) | `read_resource(uri: "skill://commit-guidelines/examples/COMMIT_EXAMPLES.md", origin: "DirectRefServer")` |
+
+**Pros:**
+
+- Minimal tool surface: one read function instead of two or three (not counting `run_skill_script`) reduces token usage and gives the model fewer choices.
+
+**Cons:**
+
+- No per-operation approval: all cases (skill loading, resource reading, direct URI access) share one function, so approval cannot be scoped to individual operations.
+- Unreliable on gpt-4.1-mini: omits `origin` when reading `skill://` links, passes skill name as `origin` when loading a plain skill (should be omitted), and hallucinates resource names (e.g. `API_SPECIFICATION.md`) that do not exist.
+
+
+---
+
+### Origin Marker
+
+A `skill://` URI does not carry an origin, but the model needs to provide one when reading it. The `origin` is what routes the read call to the source that can handle the URI - the provider uses it to pick the matching source. Since the URI itself carries no such hint, the MCP source injects an `[Origin: ...]` marker wherever a `skill://` URI appears, so the model can read it back and pass it as the `origin` argument.
+
+The marker is only added when the content actually contains `skill://` references. If a piece of content (server instructions, a skill body, or a resource) has no `skill://` URIs, there is nothing for the model to read back, so no marker is injected.
+
+Into **server instructions**, which may mention `skill://` URIs directly:
+
+```
+[Origin: code-standards-server]
+Follow our coding standards. Load skill://code-standards/SKILL.md for details.
+```
+
+Into **skill bodies**, since a `SKILL.md` may reference other `skill://` URIs (a resource file or a related skill):
+
+```
+[Origin: code-standards-server]
+# Code Standards
+
+For naming conventions, load skill://code-standards/references/naming.md.
+```
+
+Into **skill resources**, since a resource may itself reference further `skill://` URIs:
+
+```
+[Origin: code-standards-server]
+# Naming Rules
+
+- Use PascalCase for public members and type names.
+- Use camelCase for locals and parameters.
+
+For examples, see skill://code-standards/references/naming-examples.md.
+```
+
+---
+
+### Read-by-URI Capability: Interface vs Base Class Virtual Methods
+
+Now let's look at how an `AgentSkillsSource` can opt in to reading `skill://` URIs and signal that capability to the provider.
+
+### Option 1: New `ISkillUriReader` interface
+
+```csharp
+public interface ISkillUriReader
+{
+    // Returns true if this reader can handle the given skill:// URI from the given origin.
+    bool CanRead(string uri, string origin);
+
+    // Reads and returns the content for the given skill:// URI.
+    Task<object?> ReadByUriAsync(string uri, string origin, CancellationToken cancellationToken = default);
+}
+```
+
+Sources that support direct `skill://` URI reads - such as `AgentMcpSkillsSource` - implement this interface to opt in.
+
+The provider discovers readers via a service locator and dispatches to the first that can handle the URI:
+
+```csharp
+// Discover all registered readers.
+var readers = source.GetService<IEnumerable<ISkillUriReader>>();
+
+// Pick the first reader that can handle the URI.
+var reader = readers.FirstOrDefault(r => r.CanRead(uri, origin))
+    ?? throw new InvalidOperationException($"No reader can handle URI '{uri}' from origin '{origin}'.");
+
+// Delegate the read to it.
+return await reader.ReadByUriAsync(uri, origin, cancellationToken);
+```
+
+The provider may treat a source implementing `ISkillUriReader` as the signal to advertise `read_skill_uri`: if at least one registered source implements the interface, the function is exposed to the model; otherwise it is not.
+
+### Option 2 (Proposed): Virtual methods on `AgentSkillsSource` base class
+
+```csharp
+public abstract class AgentSkillsSource
+{
+    // New members for reading by URI.
+
+    // Whether this source can read by URI; drives whether read_skill_uri is advertised. Off by default.
+    public virtual bool SupportsReadByUri => false;
+
+    // Returns true if this source can handle the given skill:// URI from the given origin.
+    public virtual bool CanReadByUri(string uri, string origin) => false;
+
+    // Reads and returns the content for the given skill:// URI.
+    public virtual Task<object?> ReadByUriAsync(string uri, string origin, CancellationToken cancellationToken = default)
+        => Task.FromResult<object?>(null);
+
+    // Existing member.
+    public abstract Task<IList<AgentSkills>> GetSkillsAsync(CancellationToken cancellationToken = default);
+}
+```
+
+Sources opt in by overriding, and the provider calls them directly:
+
+```csharp
+// AgentMcpSkillsSource opts in by overriding the virtuals.
+public override bool SupportsReadByUri => true;
+
+// Handles the URI when its origin matches this source's MCP server.
+public override bool CanReadByUri(string uri, string origin)
+    => string.Equals(origin, this.Origin, StringComparison.OrdinalIgnoreCase);
+
+// Reads content by skill:// URI from the MCP server.
+public override Task<string?> ReadByUriAsync(string uri, string origin, CancellationToken cancellationToken)
+    => /* resolve uri via the MCP server identified by origin */;
+```
+
+All sources inherit the methods, so there is no type signal - `SupportsReadByUri` fills that role. The function is advertised when any registered source returns `true`.
+
+### Comparison
+
+| Aspect | Option 1: Interface | Option 2: Base class virtual methods |
+|--------|---------------------|--------------------------------------|
+| Discovery | Service locator | Direct call on source |
+| Advertising signal | Interface implementation | `SupportsReadByUri` flag |
+| Adding new members | Breaking change | Non-breaking |
+| Complexity | Higher | Lower |
+
+---
+
+### Include MCP Server Instructions Into Agent Instructions
+
+MCP server instructions may contain the `skill://` references the model needs, so we want to surface them in the agent's instructions. But they can also carry system prompts or behavioral directives irrelevant to the agent, polluting context - so inclusion is **opt-in** via the `IncludeServerInstructions` option:
+
+```csharp
+public sealed class AgentMcpSkillsSourceOptions
+{
+    // When true, the MCP server's instructions are injected into the agent instructions. Off by default.
+    public bool IncludeServerInstructions { get; set; }
+}
+
+builder.UseMcpSkills(mcpClient, options => options.IncludeServerInstructions = true);
+```
+
+When enabled, the instructions travel alongside the discovered skills on `AgentSkillsResult`:
+
+```csharp
+public class AgentSkillsResult
+{
+    // The skills discovered from the source.
+    public IList<AgentSkill> Skills { get; }
+
+    // The MCP server instructions, when IncludeServerInstructions is enabled; otherwise null.
+    public string? Instructions { get; }
+}
+```
+
+The `AgentSkillsProvider` then appends them to its own skill-usage guidance when building the agent's instructions:
+
+```csharp
+var result = await source.GetSkillsAsync(cancellationToken);
+
+var instructions = DefaultSkillsInstructionPrompt;
+if (!string.IsNullOrWhiteSpace(result.Instructions))
+{
+    // Combine the provider's skill-usage guidance with the server instructions.
+    instructions += Environment.NewLine + result.Instructions;
+}
+```
+
+### Enabling Direct Skill References
+
+Following direct `skill://` references is **disabled by default** and activated via an option. When enabled, the provider advertises the read function to the model, and the source injects the `[Origin: ...]` marker into all content provided by the MCP server that contains `skill://` references. When disabled, no function is advertised and no marker is injected.
+
+```csharp
+public sealed class AgentMcpSkillsSourceOptions
+{
+    public bool EnableDirectReferences { get; set; }
+}
+
+builder.UseMcpSkills(mcpClient, options => options.EnableDirectReferences = true);
+```
+
+## Decision Outcome
+
+### Template Variable Resolution: Callback vs Decorator (Part 1)
+
+**Postponed.** Deferring this decision until:
+
+- We have a concrete list of scenarios that require template variable resolution.
+- The skills-over-MCP spec is released (it is still a draft, so the design may change).
+- There is a strong signal of demand from users or the ecosystem.
+
+### Function for Reading Direct Skill References (Part 2)
+
+**Postponed.** Leaning toward **Option 2 - dedicated `read_skill_uri` function alongside existing ones** (purely additive, and each function can have its own approval gate for granular per-operation approval), but deferring the decision until:
+
+- The skills-over-MCP spec is released (it is still a draft, so the design may change).
+- There is a strong signal of demand from users or the ecosystem.
+
+### Read-by-URI Capability: Interface vs Base Class (Part 2)
+
+**Postponed.** Leaning toward **Option 2 - virtual methods on `AgentSkillsSource`** (non-breaking, lower complexity, and a natural fit with the existing base class hierarchy), but deferring the decision until:
+
+- The skills-over-MCP spec is released (it is still a draft, so the design may change).
+- There is a strong signal of demand from users or the ecosystem.
+
+The method naming (`SupportsReadByUri`, `CanReadByUri`, `ReadByUriAsync`) should also be abstracted a little more before adoption, so the same members can be reused when a similar direct-reference concept is needed for other skill types (e.g. file skills).
+
+## References
+
+- [SEP-2640: Skills Extension](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640) - Draft proposal
+- [SEP-2640 Implementation Guidelines: Model-Driven Resource Loading](https://github.com/modelcontextprotocol/experimental-ext-skills/blob/main/docs/sep-draft-skills-extension.md#hosts-model-driven-resource-loading)
+- [MCP Completion API](https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/completion) - Used for template variable resolution
+- [MCP Resource Templates](https://modelcontextprotocol.io/specification/2025-11-25/server/resources#resource-templates)
+- [Skills Over MCP Working Group](https://github.com/modelcontextprotocol/experimental-ext-skills)
+- [Open Question #4: Multi-server skill dependencies](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/39)
+- [Anthropic Agent Skills - Overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) - Prior art: single skill entrypoint + generic file reads
+- [Anthropic Agent Skills in the SDK](https://code.claude.com/docs/en/agent-sdk/skills) - The `Skill` tool exposed to the model

docs/specs/002-python-hosting-channels.md

@@ -0,0 +1,320 @@
+---
+status: proposed
+contact: eavanvalkenburg
+date: 2026-06-11
+deciders: eavanvalkenburg
+---
+
+# Python hosting core and pluggable channels
+
+## Scope
+
+This specification is the Python implementation plan for [ADR-0027](../decisions/0027-hosting-channels.md). It documents the simplified v1 host/channel contract only.
+
+The v1 contract is:
+
+- `AgentFrameworkHost` owns one Starlette app, one hostable target, and one or more channels.
+- A hostable target is either a `SupportsAgentRun`-compatible agent or a `Workflow`.
+- Channels contribute routes, middleware, commands, and lifecycle callbacks.
+- Channels parse protocol-native input into `ChannelRequest`.
+- Channels render their own originating response.
+- Session continuity is explicit: a channel supplies `ChannelSession(isolation_key=...)`, and the host resolves/caches an `AgentSession` for that key.
+- The host invokes `ChannelRunHook` and `ChannelResponseHook`; channels provide hook configuration and protocol context.
+
+The host does not link identities, route responses to other channels, run background continuations, or multicast in v1. Those enhancements are tracked in [ADR-0028](../decisions/0028-hosting-linking-multicast-enhancements.md).
+
+## Goals
+
+- Let an app expose one agent or workflow on multiple protocols without handwritten Starlette composition.
+- Keep protocol parsing and response formatting inside channel packages.
+- Provide one session-resolution path shared by all channels.
+- Keep the channel authoring surface small enough for new channels to implement.
+- Preserve full-fidelity agent and workflow results until a channel decides how to render them.
+
+## Non-goals for v1
+
+The following are removed from the v1 implementation pass:
+
+- `IdentityLinker`, `IdentityAllowlist`, `AuthPolicy`, and `LinkPolicy`
+- `ResponseTarget`, active-channel routing, `all_linked`, fan-out, and multicast
+- `ChannelPush` and `ChannelPushCodec`
+- `DurableTaskRunner`, `InProcessTaskRunner`, and `RetryPolicy`
+- continuation tokens and background delivery
+- confidentiality tiers
+- `agent-framework-hosting-entra`
+- `local_identity_link`
+
+These are follow-up design topics, not hidden requirements of the v1 host.
+
+## Packages
+
+| Package | Import surface | Contents |
+|---|---|---|
+| `agent-framework-hosting` | `agent_framework_hosting` | `AgentFrameworkHost`, channel protocols, key request/result types, hooks, `reset_session`, state-path helpers. |
+| `agent-framework-hosting-responses` | `agent_framework_hosting_responses` | `ResponsesChannel`. |
+| `agent-framework-hosting-invocations` | `agent_framework_hosting_invocations` | `InvocationsChannel`. |
+| `agent-framework-hosting-telegram` | `agent_framework_hosting_telegram` | `TelegramChannel` and Telegram command helpers. |
+| `agent-framework-hosting-activity-protocol` | `agent_framework_hosting_activity_protocol` | `ActivityProtocolChannel` for Activity Protocol over Azure Bot Service. |
+| `agent-framework-hosting-discord` | `agent_framework_hosting_discord` | `DiscordChannel` and Discord command/interaction helpers. |
+| `agent-framework-foundry-hosting` | `agent_framework.foundry_hosting` | Foundry isolation middleware and Foundry-backed hosting helpers usable with the v1 host. |
+
+Channel packages may depend on their native SDKs. The core hosting package should not depend on channel SDKs or on top-level legacy protocol hosts.
+
+## Key Types
+
+### `AgentFrameworkHost`
+
+The host constructor accepts:
+
+- `target`: one `SupportsAgentRun`-compatible object or one `Workflow`
+- `channels`: one or more `Channel` instances
+- optional Starlette middleware
+- optional `state_dir`
+- optional workflow `checkpoint_location`
+
+The host exposes:
+
+- `app`: the canonical Starlette ASGI application
+- `serve(...)`: a convenience wrapper for local serving
+- `reset_session(isolation_key: str)`: rotate the cached `AgentSession` for a host-tracked conversation
+
+`state_dir` is narrowed to v1 host-owned local files only:
+
+- session aliases (`isolation_key` to current `AgentSession` id), and
+- workflow checkpoint paths when the app chooses the host-provided file layout.
+
+It is not a store for identity links, continuations, active-channel state, delivery attempts, or multicast payloads.
+
+Externally supplied isolation keys are trusted only after the channel or host middleware has authenticated and authorized the caller. The host uses `isolation_key` as a partition key; the string itself is not proof of identity or ownership.
+
+### `Channel`
+
+A channel implements a small protocol:
+
+- declare a stable channel id/name,
+- contribute routes, middleware, commands, and lifecycle callbacks,
+- parse inbound protocol data into `ChannelRequest`,
+- call the host through `ChannelContext.run(...)` or `ChannelContext.run_stream(...)`, and
+- serialize the returned result to the originating protocol response.
+
+Channels own protocol authentication, signature validation, native command registration, and protocol-specific error bodies.
+
+### `ChannelContribution`
+
+`ChannelContribution` is the channel's host-facing contribution:
+
+- Starlette routes and optional middleware,
+- native command descriptors,
+- startup and shutdown callbacks, and
+- any channel-local metadata needed by the package.
+
+The host aggregates contributions but does not interpret protocol payloads.
+
+### `ChannelRequest`
+
+`ChannelRequest` is the host-neutral request envelope produced by a channel. It carries:
+
+- target input,
+- optional `ChannelSession`,
+- optional `ChannelIdentity`,
+- options and attributes produced by the channel, and
+- request metadata useful to hooks and context providers.
+
+The host may pass attributes through to context providers and middleware. Channels should treat attributes as a documented extension bag, not as a cross-channel delivery contract.
+
+### `ChannelSession`
+
+`ChannelSession(isolation_key=...)` is the only v1 session-continuity mechanism.
+
+When a request contains an isolation key:
+
+1. The host looks up or creates the cached `AgentSession` for that key.
+2. The target runs with that `AgentSession` when the target is an agent.
+3. `reset_session(isolation_key)` rotates the alias so the next request starts a new conversation.
+
+If two channels produce the same isolation key on the same host, they share the same cached session. If they produce different keys, they do not share session state.
+
+### `ChannelIdentity`
+
+`ChannelIdentity` is optional request metadata such as channel id, native user id, tenant id, claims, or display attributes.
+
+In v1, `ChannelIdentity` does not link channels, authorize callers, select delivery destinations, or imply that two identities should share an `AgentSession`. A channel that wants shared history must still produce the same `ChannelSession.isolation_key`.
+
+### Hooks
+
+Hooks are optional and channel-owned:
+
+- `ChannelRunHook`: runs after channel parsing and before host invocation; returns the `ChannelRequest` to execute.
+- `ChannelResponseHook`: runs after target completion and before the originating channel renders a one-shot response.
+- `ChannelStreamUpdateHook`: the host applies it to streamed updates before the originating channel serializes the stream.
+
+Common uses include adapting chat text into workflow inputs, enforcing deployment-specific options, flattening rich output for text-only protocols, or filtering streamed updates for a protocol. Stream update hooks are update-only; they do not automatically sanitize `get_final_response()` output. Channels choose their response transport from the parsed protocol request before invoking run hooks.
+
+### `HostedRunResult`
+
+`HostedRunResult[T]` wraps the target's full-fidelity result plus the resolved `AgentSession | None`.
+
+- Agent targets produce `HostedRunResult[AgentResponse]`.
+- Workflow targets produce `HostedRunResult[WorkflowRunResult]`.
+
+The host does not flatten, filter, or translate the result. Each channel decides how much of the result its protocol can carry.
+
+## Host Behavior
+
+1. `AgentFrameworkHost` builds one Starlette app and asks each channel for its contribution.
+2. A channel route receives a protocol-native request.
+3. The channel validates/parses the native payload and creates `ChannelRequest`.
+4. The channel passes the request, optional `ChannelRunHook`, and protocol-native context to the host.
+5. The host invokes `ChannelRunHook`, if configured, and receives the prepared request.
+6. The host resolves an `AgentSession` from `ChannelSession.isolation_key` when present.
+7. The host invokes the agent or workflow target.
+8. The host wraps the result in `HostedRunResult` or the streaming equivalent.
+9. The host invokes `ChannelResponseHook`, if configured, for non-streaming/final response shaping.
+10. The host applies stream update hooks while the channel consumes streams; the channel renders the originating protocol response.
+
+There is no host-level route from one channel's request to another channel's response in v1.
+
+## Workflow Checkpoints
+
+Workflow checkpointing is explicit. Apps either configure checkpoint storage on the workflow itself or pass a `checkpoint_location` to the host so the workflow dispatch path can use the intended file location.
+
+`state_dir` may provide a conventional location for workflow checkpoint files, but checkpointing is still opt-in and separate from agent session history. Checkpoints are workflow-runtime state, not channel state and not identity-link state.
+
+## Foundry Isolation Middleware
+
+V1 keeps Foundry isolation as middleware rather than as a channel-linking feature.
+
+The middleware is installed only when the Foundry hosting environment flag is present. In that environment it reads Foundry-provided isolation values at the trusted hosting boundary, exposes them as read-only request context for Foundry-aware history or memory providers, and rejects unsafe session resumes when the live isolation context does not match persisted session context. Outside Foundry, raw isolation headers are ignored unless an app supplies its own trusted middleware.
+
+This middleware does not create cross-channel identity links and does not authorize non-Foundry channels.
+
+## Current Channels
+
+### Responses
+
+`ResponsesChannel` exposes the OpenAI-compatible Responses API shape. It maps request body fields such as input, options, and conversation identifiers into `ChannelRequest`, and it renders Responses-compatible one-shot or streaming responses.
+
+Responses session continuity uses a channel-selected `isolation_key`, commonly derived from a response/conversation id, caller-provided session id, Foundry isolation context, or deployment-specific request metadata.
+
+### Invocations
+
+`InvocationsChannel` exposes an invocation endpoint for server-side callers and tools. It maps the request body into `ChannelRequest` and renders the invocation result on the same HTTP response.
+
+Invocations is useful for typed workflow inputs because a `ChannelRunHook` can translate the request body into the workflow's expected input type.
+
+### Telegram
+
+`TelegramChannel` supports webhook or polling transport, native command registration, and message rendering back to the originating Telegram chat.
+
+The channel chooses a default `isolation_key` from Telegram-native data such as chat id, user id, or a configured user/chat scope. A `/new` or equivalent command may call `reset_session` for that isolation key.
+
+### Activity Protocol
+
+`ActivityChannel` supports Activity Protocol requests, typically through Azure Bot Service for Teams, Web Chat, and other Bot Framework-fronted surfaces.
+
+The channel maps incoming `Activity` objects to `ChannelRequest` and renders a reply activity to the originating conversation. Proactive Activity delivery, active-channel routing, and all-linked fan-out are not v1 host semantics.
+
+### Discord
+
+`DiscordChannel` supports Discord messages, slash commands, and interactions as channel-native input.
+
+The channel maps Discord-native user, guild, channel, thread, and interaction data into `ChannelRequest` metadata and a configured `ChannelSession.isolation_key`. It renders the result to the originating Discord response path.
+
+## High-level Samples
+
+### One agent on Responses
+
+```python
+host = AgentFrameworkHost(
+    target=agent,
+    channels=[ResponsesChannel()],
+)
+
+app = host.app
+```
+
+### One agent on multiple channels
+
+```python
+host = AgentFrameworkHost(
+    target=agent,
+    channels=[
+        ResponsesChannel(),
+        InvocationsChannel(),
+        TelegramChannel(bot_token=os.environ["TELEGRAM_BOT_TOKEN"]),
+    ],
+)
+
+host.serve(host="localhost", port=8000)
+```
+
+The host owns one Starlette app. Each channel contributes its own routes and renders its own response.
+
+### Adapting a request before execution
+
+```python
+from dataclasses import replace
+
+
+def enforce_options(request: ChannelRequest) -> ChannelRequest:
+    options = dict(request.options or {})
+    options["temperature"] = 0
+    return replace(request, options=options)
+
+
+host = AgentFrameworkHost(
+    target=agent,
+    channels=[ResponsesChannel(run_hook=enforce_options)],
+)
+```
+
+### Workflow with explicit checkpoints
+
+```python
+host = AgentFrameworkHost(
+    target=workflow,
+    channels=[InvocationsChannel(run_hook=adapt_to_workflow_input)],
+    checkpoint_location=Path("./.af-hosting/workflow_checkpoints"),
+)
+```
+
+The hook adapts channel-native input to the workflow's typed input. Checkpoints use the explicit workflow checkpoint location, not identity-link or delivery storage.
+
+### Message channel reset command
+
+```python
+async def new_chat(context):
+    if context.request.session is not None:
+        await context.host.reset_session(context.request.session.isolation_key)
+        await context.reply("Started a new conversation.")
+```
+
+Telegram, Activity Protocol, and Discord can expose equivalent native commands when their protocols support them.
+
+## Follow-up Enhancements
+
+See [ADR-0028](../decisions/0028-hosting-linking-multicast-enhancements.md) for the deferred design covering:
+
+- cross-channel identity linking,
+- authorization and allowlists,
+- non-originating response delivery,
+- active-channel routing,
+- multicast and all-linked delivery,
+- background runs and continuation tokens,
+- durable delivery runners,
+- retry/replay semantics, and
+- payload serialization.
+
+Those enhancements must layer on top of this v1 contract without requiring v1 users to adopt them.
+
+## Validation Gates
+
+The Python implementation should be considered complete when:
+
+- a sample uses one `AgentFrameworkHost` with multiple channels and no manual Starlette route composition,
+- each current channel has contract tests for route contribution, lifecycle, request parsing, hooks, and originating response rendering,
+- session tests prove shared `isolation_key` values share an `AgentSession` and `reset_session` rotates it,
+- workflow tests or samples use explicit `checkpoint_location`,
+- Foundry isolation middleware is covered by integration or contract tests,
+- no v1 package exposes the removed linking, multicast, durable-runner, or continuation APIs, and
+- this spec and ADR-0027 remain aligned.

dotnet/.github/skills/pull-requests

@@ -1 +0,0 @@
-../../../.github/skills/pull-requests

dotnet/.github/skills/pull-requests/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: pull-requests
+description: >
+  Guidance for creating pull requests and handling PR review comments in the
+  Agent Framework repository. Use this when writing a PR description (filling out
+  the PR template) or when responding to and resolving review comments on an
+  existing PR.
+---
+
+# Pull Request Workflow
+
+This skill covers two tasks: (1) writing a high-quality PR description, and
+(2) handling review comments on an existing PR.
+
+## 1. Writing the PR description
+
+Always follow the repository PR template at
+[`.github/pull_request_template.md`](../../../../.github/pull_request_template.md). Keep its
+exact structure and headings. Fill every section:
+
+### `### Motivation & Context`
+Explain *why* the change is needed: the problem it solves and the scenario it
+contributes to. Describe the net change relative to `main` — this is implied, so
+do **not** spell out "vs main" explicitly.
+
+### `### Description & Review Guide`
+Describe the changes, the overall approach, and the design. Answer the three
+prompts:
+- **What are the major changes?**
+- **What is the impact of these changes?**
+- **What do you want reviewers to focus on?** — This item is for **human
+  reviewers only**. Automated/AI reviewers must ignore it and review the entire
+  change rather than narrowing scope to it.
+
+### `### Related Issue`
+Link the issue the PR fixes using a GitHub closing keyword (`Fixes #123` /
+`Closes #123`) so it closes automatically on merge. A PR with no linked issue may
+be closed regardless of how valid the change is. Before opening, confirm there is
+no other open PR for the same issue; if there is, explain how this PR differs.
+
+### `### Contribution Checklist`
+Check every item that applies. For the breaking-change item:
+- Leave **"This is not a breaking change."** checked for the common case.
+- If the change **is** breaking, add the `breaking change` label **or** put
+  `[BREAKING]` in the title prefix, before or after a language prefix such as
+  `Python:` or `.NET:` — workflows keep the label and the title prefix in sync
+  automatically (see `.github/workflows/label-title-prefix.yml` and
+  `.github/workflows/label-pr.yml`).
+
+### Do not
+- Do **not** add ad-hoc sections such as "Validation" or "Tests run"; CI/CD and
+  the checklist already cover validation status.
+- Do **not** remove or reorder the template's headings.
+
+### Creating the PR
+Open new PRs as **drafts** until they are ready for review. Example:
+
+```bash
+gh pr create --repo microsoft/agent-framework --base main \
+  --head <your-fork-owner>:<branch> --draft \
+  --title "<concise title>" --body "<body following the template>"
+```
+
+## 2. Handling review comments
+
+When a PR receives review comments, follow this sequence — **do not start editing
+code before the user has reviewed the plan**:
+
+1. **Review the comments.** Read every review comment and thread on the PR,
+   including inline code comments and general review summaries.
+2. **Make a plan.** Produce a concrete plan describing how each comment will be
+   addressed (or why it should not be, with reasoning).
+3. **Let the user review the plan.** Present the plan and wait for the user's
+   approval or adjustments before implementing anything.
+4. **Implement.** Make the agreed changes.
+5. **Reply to every comment.** Add a reply to **all** comments explaining how it
+   was addressed (or the agreed outcome) — leave none unanswered.
+6. **Resolve resolved threads.** Mark a review thread as resolved only when the
+   comment has actually been addressed.
+
+### Useful commands
+
+List review comments and threads:
+
+```bash
+# Inline review comments
+gh api repos/{owner}/{repo}/pulls/{pr}/comments
+
+# Review threads with resolution state (GraphQL)
+gh api graphql -f query='
+  query($owner:String!,$repo:String!,$pr:Int!){
+    repository(owner:$owner,name:$repo){
+      pullRequest(number:$pr){
+        reviewThreads(first:100){
+          nodes{ id isResolved comments(first:50){ nodes{ id body author{login} } } }
+        }
+      }
+    }
+  }' -F owner={owner} -F repo={repo} -F pr={pr}
+```
+
+Reply to an inline review comment:
+
+```bash
+gh api repos/{owner}/{repo}/pulls/{pr}/comments/{comment_id}/replies \
+  -f body="Addressed in <commit>: <explanation>"
+```
+
+Resolve a review thread (needs the thread node id from the GraphQL query above):
+
+```bash
+gh api graphql -f query='
+  mutation($threadId:ID!){
+    resolveReviewThread(input:{threadId:$threadId}){ thread{ isResolved } }
+  }' -F threadId={thread_id}
+```

dotnet/Directory.Packages.props

@@ -12,7 +12,7 @@
   <ItemGroup>
     <!-- Aspire.* -->
     <PackageVersion Include="Anthropic" Version="12.20.0" />
-    <PackageVersion Include="Anthropic.Foundry" Version="0.5.0" />
+    <PackageVersion Include="Anthropic.Foundry" Version="0.6.0" />
     <PackageVersion Include="Aspire.Hosting" Version="$(AspireAppHostSdkVersion)" />
     <PackageVersion Include="Aspire.Azure.AI.OpenAI" Version="13.0.0-preview.1.25560.3" />
     <PackageVersion Include="Aspire.Azure.AI.Inference" Version="13.1.0-preview.1.25616.3" />
@@ -27,10 +27,10 @@
     <PackageVersion Include="Azure.AI.AgentServer.Invocations" Version="1.0.0-beta.4" />
     <PackageVersion Include="Azure.AI.AgentServer.Responses" Version="1.0.0-beta.5" />
     <PackageVersion Include="Azure.Search.Documents" Version="12.0.0" />
-    <PackageVersion Include="Azure.AI.Projects" Version="2.1.0-beta.2" />
+    <PackageVersion Include="Azure.AI.Projects" Version="2.1.0-beta.3" />
     <PackageVersion Include="Azure.AI.Agents.Persistent" Version="1.2.0-beta.10" />
     <PackageVersion Include="Azure.AI.OpenAI" Version="2.9.0-beta.1" />
-    <PackageVersion Include="Azure.Core" Version="1.56.0" />
+    <PackageVersion Include="Azure.Core" Version="1.57.0" />
     <PackageVersion Include="Azure.Identity" Version="1.21.0" />
     <PackageVersion Include="DotNetEnv" Version="3.1.1" />
     <PackageVersion Include="Azure.Monitor.OpenTelemetry.Exporter" Version="1.5.0" />
@@ -45,7 +45,7 @@
     <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.8" />
     <PackageVersion Include="Microsoft.Bcl.HashCode" Version="6.0.0" />
     <PackageVersion Include="Microsoft.Bcl.Memory" Version="10.0.5" />
-    <PackageVersion Include="System.ClientModel" Version="1.12.0" />
+    <PackageVersion Include="System.ClientModel" Version="1.13.0" />
     <PackageVersion Include="System.CodeDom" Version="10.0.0" />
     <PackageVersion Include="System.Collections.Immutable" Version="10.0.1" />
     <PackageVersion Include="System.CommandLine" Version="2.0.0-rc.2.25502.107" />

dotnet/agent-framework-dotnet.slnx

@@ -120,6 +120,7 @@
   </Folder>
   <Folder Name="/Samples/02-agents/Harness/">
     <File Path="samples/02-agents/Harness/README.md" />
+    <Project Path="samples/02-agents/Harness/BuildYourOwnClaw/Claw_Step01_MeetYourClaw/Claw_Step01_MeetYourClaw.csproj" />
     <Project Path="samples/02-agents/Harness/ConsoleReactiveComponents/ConsoleReactiveComponents.csproj" />
     <Project Path="samples/02-agents/Harness/ConsoleReactiveFramework/ConsoleReactiveFramework.csproj" />
     <Project Path="samples/02-agents/Harness/Harness_Shared_Console/Harness_Shared_Console.csproj" />
@@ -217,6 +218,7 @@
   <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_PerRun_AuthHeaders/Agent_MCP_PerRun_AuthHeaders.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" />
@@ -331,6 +333,9 @@
   <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalTools/">
     <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalTools/HostedLocalTools.csproj" />
   </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalCodeAct/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalCodeAct/HostedLocalCodeAct.csproj" />
+  </Folder>
   <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-McpTools/">
     <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-McpTools/HostedMcpTools.csproj" />
   </Folder>
@@ -408,6 +413,7 @@
   <Folder Name="/Samples/05-end-to-end/Evaluation/">
     <Project Path="samples/05-end-to-end/Evaluation/Evaluation_ConversationSplits/Evaluation_ConversationSplits.csproj" />
     <Project Path="samples/05-end-to-end/Evaluation/Evaluation_FoundryQuality/Evaluation_FoundryQuality.csproj" />
+    <Project Path="samples/05-end-to-end/Evaluation/Evaluation_FoundryRubric/Evaluation_FoundryRubric.csproj" />
     <Project Path="samples/05-end-to-end/Evaluation/Evaluation_MixedProviders/Evaluation_MixedProviders.csproj" />
   </Folder>
   <Folder Name="/Samples/05-end-to-end/A2AClientServer/">
@@ -616,6 +622,7 @@
     <Project Path="src/Microsoft.Agents.AI.Hosting.AspNetCore/Microsoft.Agents.AI.Hosting.AspNetCore.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.LocalCodeAct/Microsoft.Agents.AI.LocalCodeAct.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" />
@@ -671,6 +678,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.LocalCodeAct.UnitTests/Microsoft.Agents.AI.LocalCodeAct.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" />

dotnet/eng/verify-samples/GetStartedSamples.cs

@@ -26,8 +26,8 @@ internal static class GetStartedSamples
         {
             Name = "01_hello_agent",
             ProjectPath = "samples/01-get-started/01_hello_agent",
-            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             ExpectedOutputDescription =
             [
                 "The output should contain a joke about a pirate.",
@@ -40,8 +40,8 @@ internal static class GetStartedSamples
         {
             Name = "02_add_tools",
             ProjectPath = "samples/01-get-started/02_add_tools",
-            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             MustContain = [],
             ExpectedOutputDescription =
             [
@@ -56,8 +56,8 @@ internal static class GetStartedSamples
         {
             Name = "03_multi_turn",
             ProjectPath = "samples/01-get-started/03_multi_turn",
-            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             ExpectedOutputDescription =
             [
                 "The output should contain a joke about a pirate.",
@@ -71,8 +71,8 @@ internal static class GetStartedSamples
         {
             Name = "04_memory",
             ProjectPath = "samples/01-get-started/04_memory",
-            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             MustContain =
             [
                 ">> Use session with blank memory",
@@ -97,8 +97,8 @@ internal static class GetStartedSamples
         {
             Name = "06_host_your_agent",
             ProjectPath = "samples/01-get-started/06_host_your_agent",
-            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             SkipReason = "Requires Azure Functions Core Tools runtime and starts a web server.",
         },
     ];

dotnet/nuget/nuget-package.props

@@ -1,14 +1,14 @@
 <Project>
   <PropertyGroup>
     <!-- Central version prefix - applies to all nuget packages. -->
-    <VersionPrefix>1.10.0</VersionPrefix>
+    <VersionPrefix>1.11.0</VersionPrefix>
     <RCNumber>1</RCNumber>
-    <DateSuffix>260610</DateSuffix>
+    <DateSuffix>260623</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.10.0</GitTag>
+    <GitTag>1.11.0</GitTag>
 
     <Configurations>Debug;Release;Publish</Configurations>
     <IsPackable>true</IsPackable>

dotnet/samples/01-get-started/01_hello_agent/01_hello_agent.csproj

@@ -9,13 +9,12 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Azure.AI.OpenAI" />
     <PackageReference Include="Azure.Identity" />
-    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+    <PackageReference Include="Microsoft.Extensions.AI.Abstractions" />
   </ItemGroup>
 
   <ItemGroup>
-    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
   </ItemGroup>
 
 </Project>

dotnet/samples/01-get-started/01_hello_agent/Program.cs

@@ -1,23 +1,19 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-// This sample shows how to create and use a simple AI agent with Azure OpenAI as the backend.
+// This sample shows how to create and use a simple AI agent with AIProjectClient as the backend.
 
-using Azure.AI.OpenAI;
+using Azure.AI.Projects;
 using Azure.Identity;
 using Microsoft.Agents.AI;
-using OpenAI.Chat;
 
-var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var model = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
 
 // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
 // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
 // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-AIAgent agent = new AzureOpenAIClient(
-    new Uri(endpoint),
-    new DefaultAzureCredential())
-    .GetChatClient(deploymentName)
-    .AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker");
+AIAgent agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
+    .AsAIAgent(model: model, instructions: "You are good at telling jokes.", name: "Joker");
 
 // Invoke the agent and output the text result.
 Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

dotnet/samples/01-get-started/02_add_tools/02_add_tools.csproj

@@ -9,13 +9,12 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Azure.AI.OpenAI" />
     <PackageReference Include="Azure.Identity" />
-    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+    <PackageReference Include="Microsoft.Extensions.AI.Abstractions" />
   </ItemGroup>
 
   <ItemGroup>
-    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
   </ItemGroup>
 
 </Project>

dotnet/samples/01-get-started/02_add_tools/Program.cs

@@ -1,31 +1,27 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-// This sample demonstrates how to use a ChatClientAgent with function tools.
-// It shows both non-streaming and streaming agent interactions using menu-related tools.
+// This sample demonstrates how to use an AIProjectClient agent with function tools.
+// It shows both non-streaming and streaming agent interactions using weather tools.
 
 using System.ComponentModel;
-using Azure.AI.OpenAI;
+using Azure.AI.Projects;
 using Azure.Identity;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
-using OpenAI.Chat;
 
-var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var model = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
 
 [Description("Get the weather for a given location.")]
 static string GetWeather([Description("The location to get the weather for.")] string location)
     => $"The weather in {location} is cloudy with a high of 15°C.";
 
-// Create the chat client and agent, and provide the function tool to the agent.
+// Create the agent and provide the function tool to the agent.
 // 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 are a helpful assistant", tools: [AIFunctionFactory.Create(GetWeather)]);
+AIAgent agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
+    .AsAIAgent(model: model, instructions: "You are a helpful assistant", tools: [AIFunctionFactory.Create(GetWeather)]);
 
 // Non-streaming agent interaction with function tools.
 Console.WriteLine(await agent.RunAsync("What is the weather like in Amsterdam?"));

dotnet/samples/01-get-started/03_multi_turn/03_multi_turn.csproj

@@ -9,13 +9,12 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Azure.AI.OpenAI" />
     <PackageReference Include="Azure.Identity" />
-    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+    <PackageReference Include="Microsoft.Extensions.AI.Abstractions" />
   </ItemGroup>
 
   <ItemGroup>
-    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
   </ItemGroup>
 
 </Project>

dotnet/samples/01-get-started/03_multi_turn/Program.cs

@@ -2,22 +2,18 @@
 
 // This sample shows how to create and use a simple AI agent with a multi-turn conversation.
 
-using Azure.AI.OpenAI;
+using Azure.AI.Projects;
 using Azure.Identity;
 using Microsoft.Agents.AI;
-using OpenAI.Chat;
 
-var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var model = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
 
 // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
 // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
 // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-AIAgent agent = new AzureOpenAIClient(
-    new Uri(endpoint),
-    new DefaultAzureCredential())
-    .GetChatClient(deploymentName)
-    .AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker");
+AIAgent agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
+    .AsAIAgent(model: model, instructions: "You are good at telling jokes.", name: "Joker");
 
 // Invoke the agent with a multi-turn conversation, where the context is preserved in the session object.
 AgentSession session = await agent.CreateSessionAsync();

dotnet/samples/01-get-started/04_memory/04_memory.csproj

@@ -9,13 +9,12 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Azure.AI.OpenAI" />
     <PackageReference Include="Azure.Identity" />
-    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+    <PackageReference Include="Microsoft.Extensions.AI.Abstractions" />
   </ItemGroup>
 
   <ItemGroup>
-    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
   </ItemGroup>
 
 </Project>

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

@@ -8,23 +8,26 @@
 
 using System.Text;
 using System.Text.Json;
-using Azure.AI.OpenAI;
+using Azure.AI.Projects;
 using Azure.Identity;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
-using OpenAI.Chat;
 using SampleApp;
 
-var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var model = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
 
 // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
 // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
 // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-ChatClient chatClient = new AzureOpenAIClient(
-    new Uri(endpoint),
-    new DefaultAzureCredential())
-    .GetChatClient(deploymentName);
+var projectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential());
+
+// Get the underlying IChatClient to use for the memory component.
+// The memory provider needs direct IChatClient access for structured extraction.
+IChatClient chatClient = projectClient
+    .AsAIAgent(new ChatClientAgentOptions { ChatOptions = new() { ModelId = model } })
+    .GetService<IChatClient>()
+    ?? throw new InvalidOperationException("Could not retrieve IChatClient from AIProjectClient agent.");
 
 // Create the agent and provide a factory to add our custom memory component to
 // all sessions created by the agent. Here each new memory component will have its own
@@ -36,7 +39,7 @@ ChatClient chatClient = new AzureOpenAIClient(
 AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions()
 {
     ChatOptions = new() { Instructions = "You are a friendly assistant. Always address the user by their name." },
-    AIContextProviders = [new UserInfoMemory(chatClient.AsIChatClient())]
+    AIContextProviders = [new UserInfoMemory(chatClient)]
 });
 
 // Create a new session for the conversation.

dotnet/samples/01-get-started/06_host_your_agent/06_host_your_agent.csproj

@@ -21,11 +21,10 @@
     <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" />
   </ItemGroup>
   <ItemGroup>
-    <PackageReference Include="Azure.AI.OpenAI" />
     <PackageReference Include="Azure.Identity" />
   </ItemGroup>
   <ItemGroup>
     <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Hosting.AzureFunctions\Microsoft.Agents.AI.Hosting.AzureFunctions.csproj" />
-    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
   </ItemGroup>
 </Project>

dotnet/samples/01-get-started/06_host_your_agent/Program.cs

@@ -4,36 +4,32 @@
 //
 // Prerequisites:
 //   - Azure Functions Core Tools
-//   - Azure OpenAI resource
+//   - Foundry project endpoint and credentials
 //
 // Environment variables:
-//   AZURE_OPENAI_ENDPOINT
-//   AZURE_OPENAI_DEPLOYMENT_NAME (defaults to "gpt-5.4-mini")
+//   FOUNDRY_PROJECT_ENDPOINT
+//   FOUNDRY_MODEL (defaults to "gpt-5.4-mini")
 //
 // Run with: func start
 // Then call: POST http://localhost:7071/api/agents/HostedAgent/run
 
-using Azure.AI.OpenAI;
+using Azure.AI.Projects;
 using Azure.Identity;
 using Microsoft.Agents.AI;
 using Microsoft.Agents.AI.Hosting.AzureFunctions;
 using Microsoft.Azure.Functions.Worker.Builder;
 using Microsoft.Extensions.Hosting;
-using OpenAI.Chat;
 
-var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
-    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var model = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
 
 // Set up an AI agent following the standard Microsoft Agent Framework pattern.
 // 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 are a helpful assistant hosted in Azure Functions.",
-        name: "HostedAgent");
+AIAgent agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
+    .AsAIAgent(model: model, instructions: "You are a helpful assistant hosted in Azure Functions.", name: "HostedAgent");
 
 // Configure the function app to host the AI agent.
 // This will automatically generate HTTP API endpoints for the agent.

dotnet/samples/02-agents/AgentProviders/foundry/Agent_Step22_MemorySearch/Program.cs

@@ -56,14 +56,13 @@ try
     // Inspect memory search results if available in raw response items.
     foreach (var message in response.Messages)
     {
-        if (message.RawRepresentation is MemorySearchToolCallResponseItem memorySearchResult)
+        if (message.RawRepresentation is MemorySearchToolCall memorySearchResult)
         {
             Console.WriteLine($"Memory Search Status: {memorySearchResult.Status}");
-            Console.WriteLine($"Memory Search Results Count: {memorySearchResult.Results.Count}");
+            Console.WriteLine($"Memory Search Results Count: {memorySearchResult.Memories.Count}");
 
-            foreach (var result in memorySearchResult.Results)
+            foreach (var memoryItem in memorySearchResult.Memories)
             {
-                var memoryItem = result.MemoryItem;
                 Console.WriteLine($"  - Memory ID: {memoryItem.MemoryId}");
                 Console.WriteLine($"    Scope: {memoryItem.Scope}");
                 Console.WriteLine($"    Content: {memoryItem.Content}");

dotnet/samples/02-agents/Evaluation/Evaluation_ExpectedOutputs/README.md

@@ -31,3 +31,4 @@ dotnet run --project .\Evaluation_ExpectedOutputs
 
 - [Evaluation_SimpleEval](../Evaluation_SimpleEval/) — Simplest evaluation with built-in and custom checks
 - [Evaluation_FoundryQuality](../../../05-end-to-end/Evaluation/Evaluation_FoundryQuality/) — Cloud-based quality evaluation with Foundry evaluators
+- [Evaluation_FoundryRubric](../../../05-end-to-end/Evaluation/Evaluation_FoundryRubric/) — Rubric (adaptive) evaluators with per-dimension scores

dotnet/samples/02-agents/Evaluation/Evaluation_Multimodal/README.md

@@ -26,4 +26,5 @@ dotnet run --project .\Evaluation_Multimodal
 
 - [Evaluation_SimpleEval](../Evaluation_SimpleEval/) — Simplest evaluation with built-in checks and `agent.EvaluateAsync()`
 - [Evaluation_FoundryQuality](../../../05-end-to-end/Evaluation/Evaluation_FoundryQuality/) — Cloud-based quality evaluation with Foundry evaluators
+- [Evaluation_FoundryRubric](../../../05-end-to-end/Evaluation/Evaluation_FoundryRubric/) — Rubric (adaptive) evaluators with per-dimension scores
 - [Evaluation_ConversationSplits](../../../05-end-to-end/Evaluation/Evaluation_ConversationSplits/) — Multi-turn conversation split strategies

dotnet/samples/02-agents/Harness/BuildYourOwnClaw/Claw_Step01_MeetYourClaw/Claw_Step01_MeetYourClaw.csproj

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

dotnet/samples/02-agents/Harness/BuildYourOwnClaw/Claw_Step01_MeetYourClaw/Program.cs

@@ -0,0 +1,111 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// "Meet your agent harness and claw" — Post 1 of the "Build your own claw with Microsoft Agent Framework" series.
+// See: https://devblogs.microsoft.com/agent-framework/meet-your-agent-harness-and-claw.
+//
+// This sample builds the foundation of a personal finance / investing assistant on top of a
+// HarnessAgent. The harness comes pre-configured with function invocation, per-service-call
+// history persistence, and planning (TodoProvider + AgentModeProvider), plus web search — so
+// all we add here is:
+//   1. Finance-focused instructions.
+//   2. A custom get_stock_price function tool.
+//
+// The agent can plan a multi-step request ("Review my watchlist and recommend some stocks to add"), create a todo list, switch
+// between plan and execute modes, search the web for market news, and call our stock-price tool.
+//
+// Special commands (handled by the shared HarnessConsole):
+//   /todos  — Display the current todo list without invoking the agent.
+//   /mode   — Get or set the current agent mode.
+//   /exit   — End the session.
+
+#pragma warning disable OPENAI001 // Suppress experimental API warnings for Responses API usage.
+#pragma warning disable MAAI001  // Suppress experimental API warnings for Agents AI experiments.
+
+using System.ClientModel.Primitives;
+using Azure.AI.Projects;
+using Azure.Identity;
+using ClawSample;
+using Harness.Shared.Console;
+using Harness.Shared.Console.OpenAI;
+using Harness.Shared.Console.ToolFormatters;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4";
+
+// <instructions>
+var instructions =
+    """
+    ## Personal Finance Assistant Instructions
+
+    You are a personal finance and investing assistant. You help the user understand their
+    watchlist and the markets. When asked about a stock, look up its current price with the
+    get_stock_price tool, and use web search for recent news, earnings, or analyst commentary.
+
+    ### Working style
+
+    - Always verify numbers with a tool rather than relying on memory. Stock prices change.
+    - Cite web sources inline when you use them.
+    - Keep the user's watchlist in a memory file called watchlist.md: read it when reviewing the
+      watchlist, and update it whenever the user adds or removes a ticker.
+
+    ### Important
+
+    You provide information and analysis only — you are not a licensed financial advisor and you
+    must not present your output as personalized investment advice. Remind the user to do their
+    own research before making decisions.
+    """;
+// </instructions>
+
+// <create_client>
+// Construct an IChatClient. Here we use a Microsoft Foundry project: the endpoint points at the
+// project, DefaultAzureCredential handles auth, and the deployment name selects the model.
+// The harness works with ANY IChatClient — see the AgentProviders samples for OpenAI, Azure
+// OpenAI, Anthropic, Google Gemini, Ollama, ONNX, and more.
+IChatClient chatClient =
+    new AIProjectClient(
+        new Uri(endpoint),
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+        new DefaultAzureCredential(),
+        new AIProjectClientOptions { RetryPolicy = new ClientRetryPolicy(3) })  // Enable retries to improve resiliency.
+    .GetProjectOpenAIClient()
+    .GetResponsesClient()
+    .AsIChatClient(deploymentName);
+// </create_client>
+
+// <create_agent>
+// Turn the chat client into a HarnessAgent. AsHarnessAgent pre-configures function invocation,
+// per-service-call chat history persistence, TodoProvider, AgentModeProvider, and web search.
+// We add finance instructions and our get_stock_price tool.
+AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
+{
+    ChatOptions = new ChatOptions
+    {
+        Instructions = instructions,
+        Tools = [StockTools.CreateGetStockPriceTool()],
+        Reasoning = new() { Effort = ReasoningEffort.Medium },
+    },
+});
+// </create_agent>
+
+// <run>
+// Run the interactive console session using the shared HarnessConsole helper.
+await HarnessConsole.RunAgentAsync(
+    agent,
+    userPrompt: "Ask about a stock or say 'Review my watchlist and recommend some stocks to add' to get started.",
+    new HarnessConsoleOptions
+    {
+        Observers = [
+            new OpenAIResponsesWebSearchDisplayObserver(),
+            new OpenAIResponsesErrorObserver(),
+            .. HarnessConsoleOptions.BuildObserversWithPlanning(
+                agent,
+                planModeName: "plan",
+                executionModeName: "execute",
+                toolFormatters: ToolCallFormatter.BuildDefaultToolFormatters())],
+        CommandHandlers = HarnessConsoleOptions.BuildDefaultCommandHandlers(agent),
+    });
+// </run>

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

@@ -0,0 +1,52 @@
+# Meet your claw (Post 1) — .NET
+
+The first runnable sample from the [**"Build your own agent harness and claw with Microsoft Agent Framework"** blog](https://devblogs.microsoft.com/agent-framework/build-your-own-claw-and-agent-harness-with-microsoft-agent-framework)
+series. It builds the foundation of a personal finance / investing assistant on top of a
+`HarnessAgent`.
+
+## What this sample demonstrates
+
+- **`AsHarnessAgent`** — turns an `IChatClient` into a batteries-included agent: function
+  invocation, per-service-call history persistence, planning
+  (`TodoProvider` + `AgentModeProvider`), and web search.
+- **A custom function tool** — `get_stock_price` (see `StockTools.cs`), exposing local data to the
+  agent. Prices are illustrative mock data, not real quotes.
+- **Web search** — provided automatically by the harness for market news and commentary.
+- **Planning & modes** — the agent breaks a multi-step request ("Review my watchlist and recommend some stocks to add") into a todo
+  list and switches between *plan* and *execute* modes.
+- **Shared harness console** — interactive streaming UI with `/todos`, `/mode`, and `/exit`
+  commands.
+
+## Prerequisites
+
+1. A Microsoft Foundry project with a deployed model (e.g. `gpt-5.4`).
+2. Azure CLI installed and authenticated (`az login`).
+
+## Environment variables
+
+```bash
+export FOUNDRY_PROJECT_ENDPOINT="https://your-project.services.ai.azure.com/api/projects/your-project"
+# Optional (defaults to gpt-5.4)
+export FOUNDRY_MODEL="gpt-5.4"
+```
+
+## Running
+
+```bash
+cd dotnet
+dotnet run --project samples/02-agents/Harness/BuildYourOwnClaw/Claw_Step01_MeetYourClaw
+```
+
+## What to expect
+
+The sample starts an interactive loop. Try these in order:
+
+1. `/mode execute` — switch out of the default plan mode; quick lookups don't need a plan.
+2. `What's the price of MSFT?` — the agent calls the `get_stock_price` tool.
+3. `Any recent news on NVDA?` — the agent uses web search.
+4. `Add MSFT, NVDA and SPY to my watch list` — saved to `watchlist.md` in the session's memory.
+5. `/mode plan` — switch back to plan mode for a bigger, multi-step task.
+6. `Review my watchlist and recommend some stocks to add` — the agent plans, then executes. Type
+   `/todos` to see the list and `/mode` to inspect the current mode.
+
+Output is colored by mode: **cyan** during planning, **green** during execution.

dotnet/samples/02-agents/Harness/BuildYourOwnClaw/Claw_Step01_MeetYourClaw/StockTools.cs

@@ -0,0 +1,61 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+using Microsoft.Extensions.AI;
+
+namespace ClawSample;
+
+/// <summary>
+/// A custom function tool that gives our "claw" access to (illustrative) stock prices.
+/// </summary>
+/// <remarks>
+/// The prices returned here are mock data for demonstration purposes only and are not real
+/// market quotes. In a real assistant you would call a market-data API instead.
+/// </remarks>
+internal static class StockTools
+{
+    // <stock_quote>
+    /// <summary>A delayed, illustrative stock quote.</summary>
+    public sealed record StockQuote(string Symbol, decimal Price, string Currency, DateTimeOffset AsOf);
+    // </stock_quote>
+
+    // A tiny in-memory price book so the sample runs without any external dependency.
+    private static readonly Dictionary<string, decimal> s_priceBook = new(StringComparer.OrdinalIgnoreCase)
+    {
+        ["MSFT"] = 462.97m,
+        ["AAPL"] = 229.35m,
+        ["GOOGL"] = 178.12m,
+        ["AMZN"] = 201.45m,
+        ["NVDA"] = 134.81m,
+    };
+
+    // <get_stock_price>
+    /// <summary>
+    /// Gets the latest (delayed, illustrative) stock price for a ticker symbol.
+    /// </summary>
+    /// <param name="symbol">The stock ticker symbol, e.g. <c>MSFT</c> or <c>AAPL</c>.</param>
+    [Description("Gets the latest (delayed, illustrative) stock price for a ticker symbol.")]
+    public static StockQuote GetStockPrice(
+        [Description("The stock ticker symbol, e.g. MSFT or AAPL.")] string symbol)
+    {
+        if (!s_priceBook.TryGetValue(symbol, out var price))
+        {
+            // Deterministic pseudo-price for unknown symbols so the sample stays self-contained.
+            // Derive a stable seed from the characters — string.GetHashCode() is randomized per
+            // process and Math.Abs(int.MinValue) throws, so neither is safe for repeatable output.
+            var seed = 0;
+            foreach (var ch in symbol.ToUpperInvariant())
+            {
+                seed = (seed * 31 + ch) % 1_000_000;
+            }
+
+            price = 50m + seed % 45000 / 100m;
+        }
+
+        return new StockQuote(symbol.ToUpperInvariant(), price, "USD", DateTimeOffset.UtcNow);
+    }
+    // </get_stock_price>
+
+    /// <summary>Creates the <see cref="AIFunction"/> wrapper used to expose the tool to the agent.</summary>
+    public static AIFunction CreateGetStockPriceTool() => AIFunctionFactory.Create(GetStockPrice, "get_stock_price");
+}

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

@@ -64,21 +64,15 @@ public sealed class HarnessAgentRunner : IDisposable
 
     /// <summary>
     /// Replaces the current session with the specified session. Used by the UX driver
-    /// when importing a serialized session. Acquires the input gate to ensure no
-    /// concurrent agent turn is reading the session.
+    /// when importing a serialized session. This method is always called from within
+    /// a command handler (which already holds the input gate), so no additional
+    /// synchronization is needed.
     /// </summary>
     /// <param name="newSession">The new session to use.</param>
-    internal async Task ReplaceSessionAsync(AgentSession newSession)
+    internal Task ReplaceSessionAsync(AgentSession newSession)
     {
-        await this._inputGate.WaitAsync().ConfigureAwait(false);
-        try
-        {
-            this._session = newSession;
-        }
-        finally
-        {
-            this._inputGate.Release();
-        }
+        this._session = newSession;
+        return Task.CompletedTask;
     }
 
     /// <inheritdoc/>

dotnet/samples/02-agents/Harness/Harness_Shared_Console/ToolFormatters/BackgroundAgentToolFormatter.cs

@@ -6,22 +6,22 @@ using Microsoft.Extensions.AI;
 namespace Harness.Shared.Console.ToolFormatters;
 
 /// <summary>
-/// Formats <c>BackgroundAgents_*</c> tool calls with human-readable details
+/// Formats <c>background_agents_*</c> tool calls with human-readable details
 /// for task start, continue, wait, and result retrieval operations.
 /// </summary>
 public sealed class BackgroundAgentToolFormatter : ToolCallFormatter
 {
     /// <inheritdoc/>
-    public override bool CanFormat(FunctionCallContent call) => call.Name.StartsWith("BackgroundAgents_", StringComparison.Ordinal);
+    public override bool CanFormat(FunctionCallContent call) => call.Name.StartsWith("background_agents_", StringComparison.Ordinal);
 
     /// <inheritdoc/>
     public override string? FormatDetail(FunctionCallContent call) => call.Name switch
     {
-        "BackgroundAgents_StartTask" => FormatStartBackgroundTask(call),
-        "BackgroundAgents_WaitForFirstCompletion" => FormatIdList(call, "taskIds", "Wait for"),
-        "BackgroundAgents_GetTaskResults" => FormatSingleId(call, "taskId"),
-        "BackgroundAgents_ContinueTask" => FormatContinueTask(call),
-        "BackgroundAgents_ClearCompletedTask" => FormatSingleId(call, "taskId"),
+        "background_agents_start_task" => FormatStartBackgroundTask(call),
+        "background_agents_wait_for_first_completion" => FormatIdList(call, "taskIds", "Wait for"),
+        "background_agents_get_task_results" => FormatSingleId(call, "taskId"),
+        "background_agents_continue_task" => FormatContinueTask(call),
+        "background_agents_clear_completed_task" => FormatSingleId(call, "taskId"),
         _ => null,
     };
 

dotnet/samples/02-agents/Harness/Harness_Shared_Console/ToolFormatters/FileMemoryToolFormatter.cs

@@ -5,21 +5,21 @@ using Microsoft.Extensions.AI;
 namespace Harness.Shared.Console.ToolFormatters;
 
 /// <summary>
-/// Formats <c>FileMemory_*</c> tool calls, showing file names and search patterns
+/// Formats <c>file_memory_*</c> tool calls, showing file names and search patterns
 /// with tree-view corners for save operations.
 /// </summary>
 public sealed class FileMemoryToolFormatter : ToolCallFormatter
 {
     /// <inheritdoc/>
-    public override bool CanFormat(FunctionCallContent call) => call.Name.StartsWith("FileMemory_", StringComparison.Ordinal);
+    public override bool CanFormat(FunctionCallContent call) => call.Name.StartsWith("file_memory_", StringComparison.Ordinal);
 
     /// <inheritdoc/>
     public override string? FormatDetail(FunctionCallContent call) => call.Name switch
     {
-        "FileMemory_SaveFile" => FormatSaveFile(call),
-        "FileMemory_ReadFile" => FormatStringArg(call, "fileName"),
-        "FileMemory_DeleteFile" => FormatStringArg(call, "fileName"),
-        "FileMemory_SearchFiles" => FormatSearchFiles(call),
+        "file_memory_save_file" => FormatSaveFile(call),
+        "file_memory_read_file" => FormatStringArg(call, "fileName"),
+        "file_memory_delete_file" => FormatStringArg(call, "fileName"),
+        "file_memory_search_files" => FormatSearchFiles(call),
         _ => null,
     };
 

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

@@ -89,6 +89,13 @@ AIAgent agent =
         OpenTelemetrySourceName = TracingSourceName,        // Use our custom source name so spans are captured by the TracerProvider above.
         FileMemoryStore = new FileSystemAgentFileStore(     // Configure the file memory provider to store files in a local folder called "agent-files".
             Path.Combine(AppContext.BaseDirectory, "agent-files")),
+        // The built in ModeProvider has two default modes: "plan" and "execute".
+        // Adding a loop evaluator so that in "execute" mode, the harness keeps re-invoking itself until every todo item is complete.
+        LoopEvaluators =
+        [
+            new TodoCompletionLoopEvaluator(new TodoCompletionLoopEvaluatorOptions { Modes = ["execute"] }),
+        ],
+        LoopAgentOptions = new LoopAgentOptions { MaxIterations = 10 }, // Safety cap on the number of autonomous passes per turn.
         ChatOptions = new ChatOptions
         {
             Instructions = instructions,

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

@@ -9,6 +9,7 @@ Key features showcased:
 - **Web Search** — the agent can search the web for current information via `ResponseTool.CreateWebSearchTool()`
 - **TodoProvider** — the agent creates and manages a todo list to track research questions
 - **AgentModeProvider** — the agent switches between "plan" mode (breaking down the topic) and "execute" mode (answering each research question)
+- **TodoCompletionLoopEvaluator** — in "execute" mode the agent loops automatically, re-invoking itself until every todo item is complete (capped by `LoopAgentOptions.MaxIterations`). The loop is scoped to "execute" mode, so "plan" mode stays interactive. The `HarnessAgent` wraps itself in a `LoopAgent` automatically whenever `LoopEvaluators` is supplied.
 - **Interactive conversation** — you can review the agent's plan, provide feedback, and approve before execution begins
 - **Streaming output** — responses are streamed token-by-token for a natural experience
 - **`/todos` command** — view the current todo list at any time without invoking the agent
@@ -47,7 +48,7 @@ The sample starts an interactive conversation loop. You can:
 1. **Enter a research topic** — the agent will analyze it and create a plan with todos
 2. **Review and adjust** — provide feedback on the plan, ask for changes, or approve it
 3. **Type `/todos`** — to see the current todo list at any time
-4. **Watch execution** — once approved, tell the agent to proceed and it will work through each todo
+4. **Watch execution** — once approved, the agent will switch to "execute" mode and process each todo autonomously until the whole plan is complete
 5. **Type `exit`** — to end the session
 
 The prompt and agent output are colored by the current mode: **cyan** during planning, **green** during execution.

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

@@ -56,9 +56,9 @@ AIAgent webSearchAgent =
         OpenTelemetrySourceName = TracingSourceName,
         DisableTodoProvider = true,
         DisableAgentModeProvider = true,
-        DisableFileMemory = true,   // If enabled, this would allow the agent to store memories as files in a directory associated with the current session
-        DisableFileAccess = true,   // If enabled, this would allow the agent to read/write files in a working directory
-        DisableToolApproval = true, // If enabled, this allows don't-ask-again approval functionality.
+        DisableFileMemory = true,       // If enabled, this would allow the agent to store memories as files in a directory associated with the current session
+        DisableFileAccess = true,       // If enabled, this would allow the agent to read/write files in a working directory
+        DisableToolAutoApproval = true, // If true, this disables the don't-ask-again approval functionality.
         ChatOptions = new ChatOptions
         {
             Instructions = "You are a web search assistant. When asked to find information, use the web search tool to look it up and return a concise, factual answer.",
@@ -106,9 +106,9 @@ AIAgent parentAgent =
         OpenTelemetrySourceName = TracingSourceName,
         DisableTodoProvider = true,
         DisableAgentModeProvider = true,
-        DisableFileMemory = true,   // If enabled, this would allow the agent to store memories as files in a directory associated with the current session
-        DisableFileAccess = true,   // If enabled, this would allow the agent to read/write files in a working directory
-        DisableToolApproval = true, // If enabled, this allows don't-ask-again approval functionality.
+        DisableFileMemory = true,       // If enabled, this would allow the agent to store memories as files in a directory associated with the current session
+        DisableFileAccess = true,       // If enabled, this would allow the agent to read/write files in a working directory
+        DisableToolAutoApproval = true, // If true, this disables the don't-ask-again approval functionality.
         DisableWebSearch = true,
         BackgroundAgents = [webSearchAgent],
         ChatOptions = new ChatOptions

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

@@ -9,16 +9,16 @@ A parent agent receives a list of stock tickers and uses a web-search background
 ### Architecture
 
 ```
-┌────────────────────────────────────────┐
-│     StockPriceResearcher               │
-│         (Parent Agent)                 │
-│                                        │
-│  BackgroundAgentsProvider              │
-│    ├─ BackgroundAgents_StartTask       │
-│    ├─ BackgroundAgents_WaitFor...      │
-│    ├─ BackgroundAgents_GetTaskResults  │
-│    └─ ...                              │
-└────────────┬───────────────────────────┘
+┌──────────────────────────────────────────────────┐
+│     StockPriceResearcher                         │
+│         (Parent Agent)                           │
+│                                                  │
+│  BackgroundAgentsProvider                        │
+│    ├─ background_agents_start_task               │
+│    ├─ background_agents_wait_for_first_completion│
+│    ├─ background_agents_get_task_results         │
+│    └─ ...                                        │
+└─────────────┬────────────────────────────────────┘
              │  delegates to
              ▼
 ┌─────────────────────────────────┐

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

@@ -79,6 +79,13 @@ AIAgent agent =
         Description = "A data analyst assistant that reads, analyzes, and processes data files.",
         OpenTelemetrySourceName = TracingSourceName,
         FileAccessStore = new FileSystemAgentFileStore(Path.Combine(AppContext.BaseDirectory, "working")),
+        ToolApprovalAgentOptions = new ToolApprovalAgentOptions()
+        {
+            // The HarnessAgent's FileAccessProvider requires approval for all file access operations.
+            // Add an auto-approval rule to skip prompts for specific operations (e.g., read-only access).
+            // You can also supply your own rule to implement custom approval logic.
+            AutoApprovalRules = [FileAccessProvider.ReadOnlyToolsAutoApprovalRule]
+        },
         DisableTodoProvider = true,
         DisableAgentModeProvider = true,
         DisableFileMemory = true,   // If enabled, this would allow the agent to store memories as files in a directory associated with the current session

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

@@ -116,7 +116,7 @@ async Task TodoLoopAsync()
         {
             var todoProvider = context.Agent.GetService<TodoProvider>()
                 ?? throw new InvalidOperationException("The agent did not expose a TodoProvider.");
-            var remaining = await todoProvider.GetRemainingTodosAsync(context.Session).ConfigureAwait(false);
+            var remaining = await todoProvider.GetRemainingTodosAsync(context.Session, cancellationToken).ConfigureAwait(false);
             return remaining.Count > 0
                 ? LoopEvaluation.Continue($"Not all todos are complete yet ({remaining.Count} remaining). Please complete the remaining todo items.")
                 : LoopEvaluation.Stop();

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

@@ -10,3 +10,11 @@ Samples demonstrating the [Harness AIContextProviders](../../../src/Microsoft.Ag
 | [Harness_Step02_Research_WithBackgroundAgents](./Harness_Step02_Research_WithBackgroundAgents/README.md) | Using BackgroundAgentsProvider to delegate stock price lookups to a web-search background agent concurrently |
 | [Harness_Step03_DataProcessing](./Harness_Step03_DataProcessing/README.md) | Using FileAccessProvider to give an agent access to CSV data files for reading, analysis, and output generation |
 | [Harness_Step05_Loop](./Harness_Step05_Loop/README.md) | Wrapping a HarnessAgent with the LoopAgent decorator to re-invoke it until a configured LoopEvaluator (completion marker, predicate, AI judge, or approval-aware loop) decides to stop |
+
+## Build your own claw blog series
+
+Samples accompanying the [*Build your own agent harness or claw with Microsoft Agent Framework*](https://devblogs.microsoft.com/agent-framework/build-your-own-claw-and-agent-harness-with-microsoft-agent-framework) blog series, which builds a personal finance assistant step by step.
+
+| Sample | Description |
+| --- | --- |
+| [Claw_Step01_MeetYourClaw](./BuildYourOwnClaw/Claw_Step01_MeetYourClaw/README.md) | Post 1 — a minimal HarnessAgent with a custom `get_stock_price` tool, web search, and planning |

dotnet/samples/02-agents/ModelContextProtocol/Agent_MCP_PerRun_AuthHeaders/Agent_MCP_PerRun_AuthHeaders.csproj

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

dotnet/samples/02-agents/ModelContextProtocol/Agent_MCP_PerRun_AuthHeaders/Program.cs

@@ -0,0 +1,136 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to attach per-run (refreshable) authentication headers to MCP requests.
+//
+// The agent connects to an MCP server with a custom HttpClient. A DelegatingHandler reads a token
+// for the current run from an AsyncLocal scope and stamps it on each outbound MCP request, so a
+// short-lived token (for example an OBO or cloud identity token that expires) can be refreshed on
+// every run without rebuilding the agent or the MCP connection.
+//
+// The agent backend is Microsoft Foundry via the Responses API (RAPI). The MCP server is the public
+// Microsoft Learn MCP server, which ignores the demonstration token; in production you point the
+// handler at your own protected MCP server and mint a real token per run.
+
+using System.Net.Http.Headers;
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using ModelContextProtocol.Client;
+
+var projectEndpoint = new Uri(Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set."));
+var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
+
+var serverEndpoint = new Uri("https://learn.microsoft.com/api/mcp");
+
+// Custom HttpClient for the MCP transport. The per-run handler attaches the bearer; the inner
+// handler disables cookies (no cross-context state), disables auto-redirect (so a redirect cannot
+// carry the bearer past the origin re-check), and checks certificate revocation.
+using var httpClient = new HttpClient(new PerRunAuthHeaderHandler(serverEndpoint)
+{
+    InnerHandler = new HttpClientHandler
+    {
+        UseCookies = false,
+        AllowAutoRedirect = false,
+        CheckCertificateRevocationList = true,
+    },
+});
+
+Console.WriteLine($"Connecting to MCP server at {serverEndpoint} ...");
+
+await using var mcpClient = await McpClient.CreateAsync(new HttpClientTransport(new()
+{
+    Endpoint = serverEndpoint,
+    Name = "Microsoft Learn MCP",
+    TransportMode = HttpTransportMode.StreamableHttp,
+}, httpClient));
+
+IList<McpClientTool> mcpTools = await mcpClient.ListToolsAsync();
+Console.WriteLine($"MCP tools available: {string.Join(", ", mcpTools.Select(t => t.Name))}");
+
+// Build the agent from Microsoft Foundry using the Responses API (RAPI).
+// 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 AIProjectClient(projectEndpoint, new DefaultAzureCredential())
+    .AsAIAgent(
+        model: deploymentName,
+        instructions: "You answer Microsoft documentation questions using the available tools.",
+        name: "DocsAgent",
+        tools: [.. mcpTools.Cast<AITool>()]);
+
+// Run the same agent twice under two different contexts. Each run gets a freshly minted token,
+// proving the auth header is per-run rather than bound when the agent or MCP connection was created.
+await RunForContextAsync(agent, "tenant-a", "How do I create an Azure storage account with az cli?");
+await RunForContextAsync(agent, "tenant-b", "What is Azure Functions?");
+
+static async Task RunForContextAsync(AIAgent agent, string label, string prompt)
+{
+    // Stand-in for a real per-run token (for example an OBO or cloud identity token).
+    // It carries no PII and is regenerated on every run. The label is non-secret and used for logging.
+    McpRunContext? previous = McpRunScope.Current;
+    McpRunScope.Current = new McpRunContext(label, $"{label}.{Guid.NewGuid():N}");
+    try
+    {
+        Console.WriteLine($"\n=== Run for '{label}' (fresh per-run token) ===");
+        Console.WriteLine(await agent.RunAsync(prompt));
+    }
+    finally
+    {
+        // Restore the prior scope (stack-like) so this is safe to call from within an outer scope.
+        McpRunScope.Current = previous;
+    }
+}
+
+/// <summary>
+/// Carries the context for the current run. <see cref="Label"/> is a non-secret identifier safe to
+/// log; <see cref="Token"/> is the secret that must never be logged or persisted.
+/// </summary>
+internal sealed record McpRunContext(string Label, string Token);
+
+/// <summary>
+/// Flows the current <see cref="McpRunContext"/> to the MCP <see cref="DelegatingHandler"/> without
+/// threading it through every call. Set it before a run and reset it afterwards.
+/// </summary>
+internal static class McpRunScope
+{
+    private static readonly AsyncLocal<McpRunContext?> s_current = new();
+
+    public static McpRunContext? Current
+    {
+        get => s_current.Value;
+        set => s_current.Value = value;
+    }
+}
+
+/// <summary>
+/// Attaches the current run's bearer token to outbound MCP requests. The token is read fresh on
+/// every request, so refreshing it between runs needs no agent or connection rebuild.
+/// </summary>
+/// <remarks>
+/// Security: the bearer is attached only over HTTPS and only when the request targets the configured
+/// MCP server origin, which prevents the credential from leaking over plaintext or to a redirect
+/// target on another origin. Only the non-secret label is logged, never the token.
+/// </remarks>
+internal sealed class PerRunAuthHeaderHandler(Uri serverEndpoint) : DelegatingHandler
+{
+    private readonly string _serverOrigin = serverEndpoint.GetLeftPart(UriPartial.Authority);
+
+    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
+    {
+        McpRunContext? context = McpRunScope.Current;
+        Uri? requestUri = request.RequestUri;
+
+        if (context is not null
+            && requestUri is not null
+            && requestUri.Scheme == Uri.UriSchemeHttps
+            && string.Equals(requestUri.GetLeftPart(UriPartial.Authority), this._serverOrigin, StringComparison.OrdinalIgnoreCase))
+        {
+            request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", context.Token);
+            Console.WriteLine($"[mcp-auth] attached bearer for '{context.Label}' -> {request.Method} {requestUri.AbsolutePath}");
+        }
+
+        return await base.SendAsync(request, cancellationToken).ConfigureAwait(false);
+    }
+}

dotnet/samples/02-agents/ModelContextProtocol/Agent_MCP_PerRun_AuthHeaders/README.md

@@ -0,0 +1,89 @@
+# Per-Run MCP Authentication Headers
+
+This sample shows how to attach per-run (refreshable) authentication headers to Model Context
+Protocol (MCP) requests using existing Agent Framework primitives. It addresses scenarios where the
+header value changes from one run to the next, for example a short-lived On-Behalf-Of (OBO) or cloud
+identity token that expires and must be refreshed.
+
+The agent backend is Microsoft Foundry accessed through the Responses API (RAPI). The MCP server is
+the public Microsoft Learn MCP server.
+
+## What this sample demonstrates
+
+- A custom `HttpClient` on the MCP transport whose `DelegatingHandler` stamps an `Authorization`
+  header on every outbound MCP request.
+- An `AsyncLocal` scope (`McpRunScope`) that carries the current run's context to the handler, set
+  immediately before each run and cleared in a `finally` block.
+- Running the same agent twice under two different contexts, each with a freshly minted token, so the
+  header is per-run rather than fixed when the agent or the MCP connection was created.
+
+Because the handler reads the token fresh on every request, an expiring token is refreshed simply by
+placing a new value in scope before the next run. No agent or connection rebuild is required.
+
+## How it works
+
+```text
+RunForContextAsync sets McpRunScope.Current
+        -> agent.RunAsync invokes an MCP tool
+                -> PerRunAuthHeaderHandler reads McpRunScope.Current
+                        -> stamps Authorization: Bearer <token> on the MCP request
+RunForContextAsync clears McpRunScope.Current in finally
+```
+
+The public Microsoft Learn MCP server is anonymous and ignores the demonstration token. In production
+you point the handler at your own protected MCP server and mint a real token per run.
+
+## Prerequisites
+
+- .NET 10 SDK or later
+- A Microsoft Foundry project endpoint and a model deployment
+- An authenticated Azure identity (for example, sign in with `az login`)
+
+Set the following environment variables:
+
+```powershell
+$env:FOUNDRY_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project"
+$env:FOUNDRY_MODEL="gpt-5.4-mini"
+```
+
+## Run the sample
+
+```powershell
+dotnet run
+```
+
+## Security considerations
+
+This sample is written to demonstrate the pattern safely. When you adapt it, keep these in place:
+
+- **Never log the token.** Only the non-secret label is printed. Avoid printing the token even in a
+  masked form.
+- **Attach the header over HTTPS only.** The handler skips the header when the request is not HTTPS,
+  so a credential is never sent over plaintext.
+- **Scope the header to the MCP server origin.** The handler attaches the header only when the
+  request targets the configured server origin (scheme, host, and port). Auto-redirect is also
+  disabled (`AllowAutoRedirect = false`) so a redirect cannot carry the token to another origin
+  below the handler before the origin check runs.
+- **Reset the scope after each run.** `McpRunScope.Current` is restored to its prior value in a
+  `finally` block so a token does not bleed into later, unrelated work and nesting stays safe.
+- **Disable cookies on the shared handler.** `UseCookies = false` avoids cross-context state on a
+  shared client, and `CheckCertificateRevocationList = true` validates the server certificate.
+- **Use non-identifying labels and tokens.** The labels and tokens here carry no personal data and are
+  regenerated per run.
+- **Do not persist secrets in serialized session state.** Agent session state is serializable, so keep
+  raw tokens in memory or mint them per run rather than storing them there.
+
+## Production notes
+
+- Replace the demonstration token with a real per-request exchange inside the handler, for example an
+  Azure `TokenCredential`, MSAL OBO flow, or a cloud identity token. Performing the exchange per
+  request lets expiry self-heal because each request obtains a current token.
+- The `AsyncLocal` scope isolates concurrent runs from each other, so parallel runs with different
+  tokens do not interfere.
+- As an alternative carrier, the token can be read from `AgentSession` state by an `AIContextProvider`
+  that copies it into the scope at the start of each invocation. Remember the serialized-state warning
+  above and avoid persisting the raw secret.
+- For MCP servers that implement standard OAuth, `HttpClientTransportOptions.OAuth` already handles the
+  authorization and refresh flow, so a custom handler is unnecessary.
+- This sample attaches the same header for every tool call in a run. Selecting different headers based
+  on the specific tool or its arguments is intentionally out of scope here.

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

@@ -21,6 +21,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|
+|[Agent with per-run MCP authentication headers](./Agent_MCP_PerRun_AuthHeaders/)|This sample demonstrates how to attach per-run, refreshable authentication headers to MCP requests using a custom HttpClient handler and an AsyncLocal scope. Uses Microsoft Foundry (`FOUNDRY_PROJECT_ENDPOINT` / `FOUNDRY_MODEL`) rather than the Azure OpenAI variables in the prerequisites above.|
 |[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.|
 

dotnet/samples/03-workflows/_StartHere/03_AgentWorkflowPatterns/Program.cs

@@ -27,7 +27,7 @@ public static class Program
         var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
         var client = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential()).GetChatClient(deploymentName).AsIChatClient();
 
-        Console.Write("Choose workflow type ('sequential', 'concurrent', 'handoffs', 'groupchat'): ");
+        Console.Write("Choose workflow type ('sequential', 'sequential-chain-only', 'concurrent', 'handoffs', 'groupchat'): ");
         switch (Console.ReadLine())
         {
             case "sequential":
@@ -36,6 +36,14 @@ public static class Program
                     [new(ChatRole.User, "Hello, world!")]);
                 break;
 
+            case "sequential-chain-only":
+                await RunWorkflowAsync(
+                    AgentWorkflowBuilder.BuildSequential(
+                        chainOnlyAgentResponses: true,
+                        from lang in (string[])["French", "Spanish", "English"] select GetTranslationAgent(lang, client)),
+                    [new(ChatRole.User, "Hello, world!")]);
+                break;
+
             case "concurrent":
                 await RunWorkflowAsync(
                     AgentWorkflowBuilder.BuildConcurrent(from lang in (string[])["French", "Spanish", "English"] select GetTranslationAgent(lang, client)),

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

@@ -20,7 +20,6 @@
 #pragma warning disable AAIP001 // ProjectAgentSkills is experimental
 
 using System.ClientModel;
-using System.IO.Compression;
 using Azure.AI.Projects;
 using Azure.AI.Projects.Agents;
 using Azure.Core;
@@ -121,8 +120,8 @@ app.Run();
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
-// Downloads each named skill from Foundry and extracts the ZIP archive into a
-// separate subdirectory under the target directory.
+// Downloads each named skill from Foundry into a separate subdirectory under the target directory.
+// GetSkillContentAsync downloads the skill package and unzips it into the destination directory.
 static async Task DownloadSkillsAsync(ProjectAgentSkills skillsClient, string[] skillNames, string targetDir)
 {
     if (Directory.Exists(targetDir))
@@ -135,56 +134,16 @@ static async Task DownloadSkillsAsync(ProjectAgentSkills skillsClient, string[]
     foreach (string name in skillNames)
     {
         Console.WriteLine($"Downloading skill '{name}' from Foundry...");
-        BinaryData zipData = await skillsClient.DownloadSkillAsync(name);
 
         string skillDir = Path.Combine(targetDir, name);
         Directory.CreateDirectory(skillDir);
 
-        using var zipStream = zipData.ToStream();
-        using var archive = new ZipArchive(zipStream, ZipArchiveMode.Read);
-        SafeExtractZip(archive, skillDir);
+        await skillsClient.GetSkillContentAsync(name, skillDir);
 
         if (!File.Exists(Path.Combine(skillDir, "SKILL.md")))
         {
             throw new InvalidOperationException(
-                $"Downloaded archive for '{name}' did not contain a SKILL.md at the root.");
-        }
-    }
-}
-
-// Extracts a ZIP archive into a destination directory, rejecting entries that would
-// escape the target path (zip-slip guard).
-static void SafeExtractZip(ZipArchive archive, string destinationDir)
-{
-    string destRoot = Path.GetFullPath(destinationDir);
-    string destRootWithSep = Path.EndsInDirectorySeparator(destRoot)
-        ? destRoot
-        : destRoot + Path.DirectorySeparatorChar;
-
-    // Use ordinal comparison on Unix (case-sensitive FS) and ordinal-ignore-case on Windows.
-    var comparison = OperatingSystem.IsWindows()
-        ? StringComparison.OrdinalIgnoreCase
-        : StringComparison.Ordinal;
-
-    foreach (ZipArchiveEntry entry in archive.Entries)
-    {
-        string entryPath = Path.GetFullPath(Path.Combine(destRoot, entry.FullName));
-        if (!entryPath.StartsWith(destRootWithSep, comparison)
-            && !string.Equals(entryPath, destRoot, comparison))
-        {
-            throw new InvalidOperationException(
-                $"Refusing to extract unsafe path '{entry.FullName}' outside of '{destRoot}'.");
-        }
-
-        if (string.IsNullOrEmpty(entry.Name))
-        {
-            // Directory entry — ensure it exists.
-            Directory.CreateDirectory(entryPath);
-        }
-        else
-        {
-            Directory.CreateDirectory(Path.GetDirectoryName(entryPath)!);
-            entry.ExtractToFile(entryPath, overwrite: true);
+                $"Downloaded skill '{name}' did not contain a SKILL.md at the root.");
         }
     }
 }
@@ -211,8 +170,8 @@ static async Task EnsureSkillsProvisionedAsync(ProjectAgentSkills skillsClient,
         catch (ClientResultException ex) when (ex.Status == 404)
         {
             Console.WriteLine($"Provisioning skill '{name}' from {skillPath}...");
-            AgentsSkill imported = await skillsClient.CreateSkillFromPackageAsync(skillPath);
-            Console.WriteLine($"  Imported skill '{imported.Name}' (id={imported.SkillId}, has_blob={imported.HasBlob}).");
+            AgentsSkill imported = (await skillsClient.CreateSkillVersionFromFilesAsync(name, skillPath)).Value;
+            Console.WriteLine($"  Imported skill '{imported.Name}' (id={imported.Id}, version={imported.LatestVersion}).");
         }
     }
 }

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

@@ -42,7 +42,7 @@ The agent is hosted using the [Agent Framework](https://github.com/microsoft/age
 
 ## Prerequisites
 
-- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- A Foundry project with a deployed model (e.g., `gpt-4o`)
 - Azure CLI logged in (`az login`)
 
 ### Required RBAC

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

@@ -7,7 +7,7 @@ This sample is the Azure AI Search counterpart to `Hosted-TextRag`. Where `Hoste
 ## Prerequisites
 
 - [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
-- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- A Foundry project with a deployed model (e.g., `gpt-4o`)
 - An Azure AI Search service ([create one](https://learn.microsoft.com/azure/search/search-create-service-portal))
 - **A pre-provisioned search index** with the schema and content described in the next section
 - Azure CLI logged in (`az login`)

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

@@ -5,7 +5,7 @@ A simple general-purpose AI assistant hosted as a Foundry Hosted Agent using the
 ## Prerequisites
 
 - [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
-- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- A Foundry project with a deployed model (e.g., `gpt-4o`)
 - Azure CLI logged in (`az login`)
 
 ## Configuration
@@ -16,7 +16,7 @@ Copy the template and fill in your project endpoint:
 cp .env.example .env
 ```
 
-Edit `.env` and set your Azure AI Foundry project endpoint:
+Edit `.env` and set your Foundry project endpoint:
 
 ```env
 FOUNDRY_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>

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

@@ -20,7 +20,7 @@
 // indirect prompt injection in an uploaded file.
 //
 // Required environment variables:
-//   FOUNDRY_PROJECT_ENDPOINT         - Azure AI Foundry project endpoint
+//   FOUNDRY_PROJECT_ENDPOINT         - Foundry project endpoint
 //   FOUNDRY_MODEL    - Model deployment name (default: gpt-4o)
 //
 // Optional:

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

@@ -43,7 +43,7 @@ The end-to-end alpha-SDK round trip (client uploads via `AgentSessionFiles.Uploa
 ## Prerequisites
 
 - [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
-- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- A Foundry project with a deployed model (e.g., `gpt-4o`)
 - Azure CLI logged in (`az login`)
 
 ## Configuration

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

@@ -7,7 +7,7 @@ This is the **Foundry hosting** pattern — the agent's behavior is configured i
 ## Prerequisites
 
 - [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
-- An Azure AI Foundry project with a **registered agent** (created via Foundry UI, CLI, or API)
+- A Foundry project with a **registered agent** (created via Foundry UI, CLI, or API)
 - Azure CLI logged in (`az login`)
 
 ## Configuration
@@ -18,7 +18,7 @@ Copy the template and fill in your project endpoint:
 cp .env.example .env
 ```
 
-Edit `.env` and set your Azure AI Foundry project endpoint:
+Edit `.env` and set your Foundry project endpoint:
 
 ```env
 FOUNDRY_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>

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

@@ -0,0 +1,6 @@
+FOUNDRY_PROJECT_ENDPOINT=<your-azure-ai-project-endpoint>
+ASPNETCORE_URLS=http://+:8088
+ASPNETCORE_ENVIRONMENT=Development
+FOUNDRY_MODEL=gpt-4o
+AZURE_BEARER_TOKEN=DefaultAzureCredential
+LOCAL_CODEACT_PYTHON=python3

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

@@ -0,0 +1,23 @@
+# Use the official .NET 10.0 ASP.NET runtime as a parent image
+FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
+WORKDIR /app
+
+# Install Python 3 so LocalCodeAct can spawn the embedded runner / validator.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends python3 \
+    && rm -rf /var/lib/apt/lists/*
+
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /src
+COPY . .
+RUN dotnet restore
+RUN dotnet publish -c Release -o /app/publish
+
+# Final stage
+FROM base AS final
+WORKDIR /app
+COPY --from=build /app/publish .
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+ENV LOCAL_CODEACT_PYTHON=python3
+ENTRYPOINT ["dotnet", "HostedLocalCodeAct.dll"]

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

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

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalCodeAct/HostedLocalCodeAct.csproj

@@ -0,0 +1,33 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <CentralPackageTransitivePinningEnabled>false</CentralPackageTransitivePinningEnabled>
+    <NoWarn>$(NoWarn);</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Projects" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="DotNetEnv" />
+  </ItemGroup>
+
+  <!-- For contributors: uses ProjectReference to build against local source -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry.Hosting\Microsoft.Agents.AI.Foundry.Hosting.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.LocalCodeAct\Microsoft.Agents.AI.LocalCodeAct.csproj" />
+    <ProjectReference Include="..\Hosted_Shared_Contributor_Setup\Hosted_Shared_Contributor_Setup.csproj" />
+  </ItemGroup>
+
+  <!-- For end-users: uncomment the PackageReference below and remove the ProjectReference above
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.Foundry" Version="1.6.1-preview.260514.1" />
+    <PackageReference Include="Microsoft.Agents.AI.Foundry.Hosting" Version="1.6.1-preview.260514.1" />
+    <PackageReference Include="Microsoft.Agents.AI.LocalCodeAct" Version="1.6.1-preview.260514.1" />
+  </ItemGroup>
+  -->
+
+</Project>

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

@@ -0,0 +1,120 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// Hosted Local CodeAct sample. Wires Microsoft.Agents.AI.LocalCodeAct into a
+// Foundry hosted agent. The model only sees a single `execute_code` tool;
+// `compute` and `fetch_data` are registered as sandbox-only host tools that
+// generated Python reaches via `await call_tool(...)`. This mirrors the Python
+// `foundry_hosted_agent.py` sample for the local-codeact package.
+//
+// SECURITY: LocalCodeAct executes LLM-generated Python in the agent process.
+// Only deploy this sample to an externally sandboxed environment such as a
+// Foundry hosted-agent container.
+
+using System.ComponentModel;
+using Azure.AI.Projects;
+using Azure.Core;
+using Azure.Identity;
+using DotNetEnv;
+using Hosted_Shared_Contributor_Setup;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry.Hosting;
+using Microsoft.Agents.AI.LocalCodeAct;
+using Microsoft.Extensions.AI;
+
+// Load .env file if present (for local development)
+Env.TraversePath().Load();
+
+string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-4o";
+string pythonExecutable = Environment.GetEnvironmentVariable("LOCAL_CODEACT_PYTHON")
+    ?? (OperatingSystem.IsWindows() ? "python.exe" : "python3");
+
+TokenCredential credential = new ChainedTokenCredential(
+    new DevTemporaryTokenCredential(),
+    new DefaultAzureCredential());
+
+// ── Sandbox-only tools (model never sees these directly) ─────────────────────
+
+[Description("Perform a math operation: add, subtract, multiply, or divide.")]
+static double Compute(
+    [Description("Operation: add, subtract, multiply, or divide.")] string operation,
+    [Description("First numeric operand.")] double a,
+    [Description("Second numeric operand.")] double b) => operation switch
+    {
+        "add" => a + b,
+        "subtract" => a - b,
+        "multiply" => a * b,
+        "divide" => b == 0 ? double.PositiveInfinity : a / b,
+        _ => throw new ArgumentException($"Unknown operation '{operation}'.", nameof(operation)),
+    };
+
+[Description("Fetch records from a named simulated table (users or products).")]
+static IReadOnlyList<IReadOnlyDictionary<string, object>> FetchData(
+    [Description("Name of the simulated table to query.")] string table)
+{
+    Dictionary<string, IReadOnlyList<IReadOnlyDictionary<string, object>>> data = new()
+    {
+        ["users"] =
+        [
+            new Dictionary<string, object> { ["id"] = 1, ["name"] = "Alice", ["role"] = "admin" },
+            new Dictionary<string, object> { ["id"] = 2, ["name"] = "Bob", ["role"] = "user" },
+            new Dictionary<string, object> { ["id"] = 3, ["name"] = "Charlie", ["role"] = "admin" },
+        ],
+        ["products"] =
+        [
+            new Dictionary<string, object> { ["id"] = 101, ["name"] = "Widget", ["price"] = 9.99 },
+            new Dictionary<string, object> { ["id"] = 102, ["name"] = "Gadget", ["price"] = 19.99 },
+        ],
+    };
+
+    return data.TryGetValue(table, out var rows) ? rows : [];
+}
+
+// ── LocalCodeAct provider with sandbox-only host tools ───────────────────────
+
+var codeActOptions = new LocalCodeActProviderOptions
+{
+    Tools =
+    [
+        AIFunctionFactory.Create(Compute, name: "compute"),
+        AIFunctionFactory.Create(FetchData, name: "fetch_data"),
+    ],
+    ExecutionLimits = new ProcessExecutionLimits { TimeoutSeconds = 5 },
+};
+
+var codeAct = new LocalCodeActProvider(pythonExecutable, codeActOptions);
+
+// ── Build the hosted agent ───────────────────────────────────────────────────
+
+AIAgent agent = new AIProjectClient(new Uri(endpoint), credential)
+    .AsAIAgent(new ChatClientAgentOptions
+    {
+        Name = Environment.GetEnvironmentVariable("AGENT_NAME") ?? "hosted-local-codeact",
+        Description = "Hosted CodeAct agent with sandbox-only compute and fetch_data tools.",
+        ChatOptions = new ChatOptions
+        {
+            ModelId = deploymentName,
+            Instructions =
+                """
+                You are a helpful assistant. Keep your answers brief. Prefer orchestrating your work
+                in a single `execute_code` block using `await call_tool(...)` over issuing many
+                direct tool calls. The sandbox exposes `compute` and `fetch_data` via `call_tool`.
+                """,
+        },
+        AIContextProviders = [codeAct],
+    });
+
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddFoundryResponses(agent);
+builder.Services.AddDevTemporaryLocalContributorSetup(); // Local Docker debugging only - must not be used in production.
+
+var app = builder.Build();
+app.MapFoundryResponses();
+
+// Contributor-only: in Development, also map the per-agent OpenAI route shape that live Foundry uses
+// so a local REPL client can target this server via AIProjectClient.AsAIAgent(Uri agentEndpoint).
+// Do not use this in production. Hosted Foundry agents only support the agent-endpoint path.
+app.MapDevTemporaryLocalAgentEndpoint();
+
+app.Run();

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

@@ -0,0 +1,159 @@
+# Hosted-LocalCodeAct
+
+A hosted agent that uses [`Microsoft.Agents.AI.LocalCodeAct`](../../../../../src/Microsoft.Agents.AI.LocalCodeAct/README.md)
+to give the model a single `execute_code` tool. Two sandbox-only host tools,
+`compute` and `fetch_data`, are registered on `LocalCodeActProvider` and are
+reachable from inside generated Python via `await call_tool(...)` — never as
+direct LLM tool calls.
+
+This mirrors the Python
+[`foundry_hosted_agent.py`](https://github.com/microsoft/agent-framework/blob/main/python/packages/local_codeact/samples/foundry_hosted_agent.py)
+sample for the `agent-framework-local-codeact` package.
+
+> **⚠️ Security:** LocalCodeAct executes LLM-generated Python in the agent
+> process. The package is not a sandbox — it relies on the Foundry hosted-agent
+> container (or another externally sandboxed environment) for process,
+> filesystem, and network isolation. Do not run this outside of a sandbox.
+
+## Prerequisites
+
+- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
+- Python 3 available on `PATH` (used by `LocalCodeActProvider` to execute the
+  embedded runner and validator). Override with the `LOCAL_CODEACT_PYTHON`
+  environment variable if you need a specific interpreter path.
+- A Foundry project with a deployed model (e.g., `gpt-4o`)
+- Azure CLI logged in (`az login`)
+
+## Configuration
+
+Copy the template and fill in your project endpoint:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` and set your Foundry project endpoint:
+
+```env
+FOUNDRY_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>
+ASPNETCORE_URLS=http://+:8088
+ASPNETCORE_ENVIRONMENT=Development
+FOUNDRY_MODEL=gpt-4o
+LOCAL_CODEACT_PYTHON=python3
+```
+
+> **Note:** `.env` is gitignored. The `.env.example` template is checked in as a reference.
+
+## Running directly (contributors)
+
+This project uses `ProjectReference` to build against the local Agent Framework
+source, including the `Microsoft.Agents.AI.LocalCodeAct` package.
+
+```bash
+cd dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalCodeAct
+AGENT_NAME=hosted-local-codeact dotnet run
+```
+
+The agent will start on `http://localhost:8088`.
+
+### Test it
+
+Using the Azure Developer CLI:
+
+```bash
+azd ai agent invoke --local "Fetch all users, find the admins, multiply 7 by 6, and print the users, admins, and the multiplication result. Use execute_code with await call_tool(...)."
+```
+
+Or with curl:
+
+```bash
+curl -X POST http://localhost:8088/responses \
+  -H "Content-Type: application/json" \
+  -d '{"input": "Fetch all users, find the admins, multiply 7 by 6, and print the users, admins, and the multiplication result. Use execute_code with await call_tool(...).", "model": "hosted-local-codeact"}'
+```
+
+## Running with Docker
+
+Since this project uses `ProjectReference`, use `Dockerfile.contributor` which
+takes a pre-published output. The image installs Python 3 so the embedded
+runner and validator scripts can execute.
+
+### 1. Publish for the container runtime (Linux Alpine)
+
+```bash
+dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+```
+
+### 2. Build the Docker image
+
+```bash
+docker build -f Dockerfile.contributor -t hosted-local-codeact .
+```
+
+### 3. Run the container
+
+Generate a bearer token on your host and pass it to the container:
+
+```bash
+# Generate token (expires in ~1 hour)
+export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
+
+# Run with token
+docker run --rm -p 8088:8088 \
+  -e AGENT_NAME=hosted-local-codeact \
+  -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN \
+  --env-file .env \
+  hosted-local-codeact
+```
+
+### 4. Test it
+
+```bash
+azd ai agent invoke --local "Fetch all users and print the admins."
+```
+
+## How CodeAct works here
+
+`LocalCodeActProvider` is registered as an `AIContextProvider`. On every run it
+injects:
+
+- A single `execute_code` tool that the model can call with a Python snippet.
+- CodeAct instructions that teach the model to use `await call_tool(...)` for
+  the provider-owned host tools, rather than asking for direct tool calls.
+
+The provider-owned host tools in this sample:
+
+| Tool | Description |
+|------|-------------|
+| `compute(operation, a, b)` | Math operation: `add`, `subtract`, `multiply`, `divide`. |
+| `fetch_data(table)` | Returns rows from a simulated `users` or `products` table. |
+
+`execute_code` runs the generated Python in a separate Python process governed
+by `ProcessExecutionLimits` (5 second timeout in this sample) and the
+default-on AST allow-list validator that rejects disallowed imports, builtins,
+and dynamic-eval constructs before execution.
+
+## Deploying to Foundry (azd spec)
+
+This sample includes an `azd` manifest (`agent.manifest.yaml`) and hosted agent
+spec (`agent.yaml`) for deployment to Foundry.
+
+Initialize an `azd` project from this sample's manifest:
+
+```bash
+mkdir hosted-local-codeact && cd hosted-local-codeact
+azd ai agent init -m https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalCodeAct/agent.manifest.yaml
+```
+
+Then deploy:
+
+```bash
+azd deploy
+```
+
+## NuGet package users
+
+If you are consuming the Agent Framework as a NuGet package (not building from
+source), use the standard `Dockerfile` instead of `Dockerfile.contributor`. See
+the commented section in `HostedLocalCodeAct.csproj` for the `PackageReference`
+alternative.

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

@@ -0,0 +1,30 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/AgentManifest.yaml
+name: hosted-local-codeact
+displayName: "Hosted Local CodeAct Agent"
+
+description: >
+  A hosted agent that uses the CodeAct pattern via
+  Microsoft.Agents.AI.LocalCodeAct. The model only sees an `execute_code`
+  tool and orchestrates `compute` and `fetch_data` sandbox-only host tools
+  via `await call_tool(...)` from inside generated Python.
+
+metadata:
+  tags:
+    - AI Agent Hosting
+    - Azure AI AgentServer
+    - Responses Protocol
+    - Local CodeAct
+    - Agent Framework
+
+template:
+  name: hosted-local-codeact
+  kind: hosted
+  protocols:
+    - protocol: responses
+      version: 1.0.0
+  resources:
+    cpu: "0.5"
+    memory: 1Gi
+parameters:
+  properties: []
+resources: []

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

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

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

@@ -7,7 +7,7 @@ The agent specializes in finding hotels in Seattle, with a `GetAvailableHotels`
 ## Prerequisites
 
 - [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
-- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- A Foundry project with a deployed model (e.g., `gpt-4o`)
 - Azure CLI logged in (`az login`)
 
 ## Configuration
@@ -18,7 +18,7 @@ Copy the template and fill in your project endpoint:
 cp .env.example .env
 ```
 
-Edit `.env` and set your Azure AI Foundry project endpoint:
+Edit `.env` and set your Foundry project endpoint:
 
 ```env
 FOUNDRY_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>

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

@@ -19,7 +19,7 @@ A hosted agent demonstrating **two layers of MCP (Model Context Protocol) tool i
 ## Prerequisites
 
 - [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
-- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- A Foundry project with a deployed model (e.g., `gpt-4o`)
 - Azure CLI logged in (`az login`)
 
 ## Configuration

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

@@ -17,7 +17,7 @@ This sample exists to demonstrate two things together:
 ## Prerequisites
 
 - [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
-- An Azure AI Foundry project with at least one chat model deployment and one embedding model deployment
+- A Foundry project with at least one chat model deployment and one embedding model deployment
 - Azure CLI logged in (`az login`)
 
 ## Configuration

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

@@ -27,7 +27,7 @@ Foundry injects `APPLICATIONINSIGHTS_CONNECTION_STRING` when the agent runs in t
 ## Prerequisites
 
 - [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
-- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- A Foundry project with a deployed model (e.g., `gpt-4o`)
 - Azure CLI logged in (`az login`)
 
 ## Configuration
@@ -36,7 +36,7 @@ Foundry injects `APPLICATIONINSIGHTS_CONNECTION_STRING` when the agent runs in t
 cp .env.example .env
 ```
 
-Edit `.env` and set your Azure AI Foundry project endpoint:
+Edit `.env` and set your Foundry project endpoint:
 
 ```env
 FOUNDRY_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>

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

@@ -7,7 +7,7 @@ This sample demonstrates how to add knowledge grounding to a hosted agent withou
 ## Prerequisites
 
 - [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
-- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- A Foundry project with a deployed model (e.g., `gpt-4o`)
 - Azure CLI logged in (`az login`)
 
 ## Configuration
@@ -18,7 +18,7 @@ Copy the template and fill in your project endpoint:
 cp .env.example .env
 ```
 
-Edit `.env` and set your Azure AI Foundry project endpoint:
+Edit `.env` and set your Foundry project endpoint:
 
 ```env
 FOUNDRY_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>

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

@@ -1,4 +1,4 @@
-# Azure AI Foundry project endpoint (auto-injected in hosted containers).
+# Foundry project endpoint (auto-injected in hosted containers).
 AZURE_AI_PROJECT_ENDPOINT=https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>
 
 # Model deployment name. Must exist in the Foundry project above.

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

@@ -11,7 +11,7 @@
 //
 // Required environment variables:
 //   AZURE_AI_PROJECT_ENDPOINT (local-dev) OR FOUNDRY_PROJECT_ENDPOINT (hosted runtime)
-//                                     - Azure AI Foundry project endpoint. The Foundry hosted
+//                                     - Foundry project endpoint. The Foundry hosted
 //                                       runtime auto-injects FOUNDRY_PROJECT_ENDPOINT; locally
 //                                       set AZURE_AI_PROJECT_ENDPOINT (the AF-repo convention).
 //   TOOLBOX_NAME                      - Name of the Foundry Toolbox to load

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

@@ -0,0 +1,16 @@
+# Foundry project endpoint (auto-injected in hosted containers).
+AZURE_AI_PROJECT_ENDPOINT=https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>
+
+# Model deployment name. Must exist in the Foundry project above.
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+
+# Name of the Foundry Toolbox you provisioned in the portal (see README.md).
+TOOLBOX_NAME=my-toolset
+
+# Agent name advertised over the wire. Must be unique if running side-by-side with
+# other Hosted-* samples (e.g. Hosted-Toolbox-AuthPaths), otherwise the REPL client
+# cannot disambiguate which agent to chat with.
+AGENT_NAME=hosted-toolbox-agent
+
+# Application Insights connection string (auto-injected in hosted containers; optional locally).
+# APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=...

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

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

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

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

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

@@ -7,20 +7,19 @@
 //
 // Required environment variables:
 //   FOUNDRY_PROJECT_ENDPOINT (hosted runtime) OR AZURE_AI_PROJECT_ENDPOINT (local-dev)
-//                                     - Azure AI Foundry project endpoint. The Foundry hosted
+//                                     - Foundry project endpoint. The Foundry hosted
 //                                       runtime auto-injects FOUNDRY_PROJECT_ENDPOINT; locally
 //                                       set AZURE_AI_PROJECT_ENDPOINT.
-//   FOUNDRY_MODEL                     - Model deployment name (default: gpt-4o)
 //
 // Optional:
-//   FOUNDRY_TOOLBOX_NAME              - Name of the toolbox to load (default: my-toolset)
-//   FOUNDRY_AGENT_TOOLSET_ENDPOINT    - Foundry Toolsets proxy base URL
-//                                       (injected automatically by Foundry platform at runtime)
-//   FOUNDRY_AGENT_NAME                - Client name reported to MCP server (auto-injected in hosted runtime)
-//   FOUNDRY_AGENT_VERSION             - Client version reported to MCP server (auto-injected in hosted runtime)
-//   FOUNDRY_AGENT_TOOLSET_FEATURES    - Additional Foundry-Features header flags (the mandatory
-//                                       Toolboxes=V1Preview flag is always sent; this env var
-//                                       appends additional flags if present).
+//   FOUNDRY_MODEL (or AZURE_AI_MODEL_DEPLOYMENT_NAME)
+//                                     - Model deployment name (default: gpt-4o)
+//   TOOLBOX_NAME                      - Name of the toolbox to load (default: my-toolset).
+//                                       NOTE: All FOUNDRY_* and AGENT_* env-var prefixes (other
+//                                       than the platform-injected ones above) are reserved by the
+//                                       Foundry container platform and rejected at agent-create.
+//                                       Use TOOLBOX_NAME, not FOUNDRY_TOOLBOX_NAME, for the
+//                                       sample-owned toolbox name so it survives deployment.
 //
 // The Foundry.Hosting package builds the toolbox proxy URL from FOUNDRY_PROJECT_ENDPOINT
 // per tools-integration-spec.md §2–§3.
@@ -43,8 +42,7 @@ string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
         "nor AZURE_AI_PROJECT_ENDPOINT (local-dev convention) is set.");
 string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL")
     ?? Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";
-string toolboxName = Environment.GetEnvironmentVariable("FOUNDRY_TOOLBOX_NAME")
-    ?? Environment.GetEnvironmentVariable("TOOLBOX_NAME") ?? "my-toolset";
+string toolboxName = Environment.GetEnvironmentVariable("TOOLBOX_NAME") ?? "my-toolset";
 
 // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
 // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid

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

@@ -1,27 +1,111 @@
 # Hosted-Toolbox
 
-A hosted Foundry agent that loads tools from a Foundry Toolbox via the AF Foundry hosting bridge.
+A hosted Foundry agent that loads tools from a single Foundry Toolbox via the AF Foundry hosting bridge.
 
-The agent declares one `FoundryAITool.CreateHostedMcpToolbox(name)` marker; `AddFoundryToolboxes(name)` registers a `FoundryToolboxService` that resolves the marker into the individual MCP tools the toolbox bundles, connecting to the Foundry Toolboxes MCP proxy at startup and discovering tools via `tools/list`.
+`AddFoundryToolboxes(name)` registers a `FoundryToolboxService` that connects to the Foundry Toolboxes MCP proxy at startup, discovers the toolbox's bundled tools via `tools/list`, and makes them available to the agent on every request. The agent code does nothing per request; the toolbox is baked in on the server.
+
+This is the minimal toolbox intro. For a richer walkthrough where a single toolbox bundles three MCP tools each authenticated differently, see [`Hosted-Toolbox-AuthPaths/`](../Hosted-Toolbox-AuthPaths/).
 
 ## Prerequisites
 
-- A Microsoft Foundry project with a Toolbox configured.
-- Azure CLI logged in (`az login`).
-- Set environment variables:
-  - `AZURE_AI_PROJECT_ENDPOINT` (local-dev) or `FOUNDRY_PROJECT_ENDPOINT` (auto-injected in hosted containers)
-  - `AZURE_AI_MODEL_DEPLOYMENT_NAME` (default `gpt-4o`)
-  - `TOOLBOX_NAME` (default `my-toolbox`)
+- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
+- A Foundry project with a deployed model (e.g., `gpt-4o`) and a Toolbox configured
+- Azure CLI logged in (`az login`)
+
+## Configuration
+
+Copy the template and fill in your values:
+
+```powershell
+Copy-Item .env.example .env
+```
+
+Edit `.env`:
+
+```env
+AZURE_AI_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+TOOLBOX_NAME=my-toolset
+```
+
+Configuration notes:
+
+- `AZURE_AI_PROJECT_ENDPOINT` (local-dev) or `FOUNDRY_PROJECT_ENDPOINT` (auto-injected in hosted containers).
+- `AZURE_AI_MODEL_DEPLOYMENT_NAME` (default `gpt-4o`).
+- `TOOLBOX_NAME` (default `my-toolset`). Use `TOOLBOX_NAME`, not `FOUNDRY_TOOLBOX_NAME`: all `FOUNDRY_*` env-var names are reserved by the Foundry platform and rejected at agent-create, so a `FOUNDRY_*`-named value would not survive deployment.
 
 The `Foundry.Hosting` package builds the toolbox proxy URL from `FOUNDRY_PROJECT_ENDPOINT` as `{FOUNDRY_PROJECT_ENDPOINT}/toolboxes/{TOOLBOX_NAME}/mcp?api-version=v1` per [`tools-integration-spec.md`](https://github.com/microsoft/AgentSchema/blob/main/specs/agents/hosted_agents/container-spec/docs/tools-integration-spec.md) §2–§3.
 
-## Run
+## Running directly (contributors)
 
 ```powershell
+cd dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox
 dotnet run --tl:off
 ```
 
+### Test it
+
+Using the Azure Developer CLI:
+
+```powershell
+azd ai agent invoke --local "What tools do you have available, and what can they do?"
+```
+
+## Running with Docker
+
+### 1. Publish for the container runtime
+
+```powershell
+dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+```
+
+### 2. Build and run
+
+```powershell
+docker build -f Dockerfile.contributor -t hosted-toolbox .
+
+$env:AZURE_BEARER_TOKEN = (az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
+
+docker run --rm -p 8088:8088 `
+  -e AGENT_NAME=hosted-toolbox-agent `
+  -e AZURE_BEARER_TOKEN=$env:AZURE_BEARER_TOKEN `
+  --env-file .env `
+  hosted-toolbox
+```
+
+## Deploying to Foundry (azd spec)
+
+This sample includes an `azd` manifest (`agent.manifest.yaml`) and hosted agent spec (`agent.yaml`) for deployment to Foundry.
+
+Initialize an `azd` project from this sample's manifest:
+
+```powershell
+mkdir hosted-toolbox; cd hosted-toolbox
+azd ai agent init -m https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox/agent.manifest.yaml
+```
+
+Then deploy:
+
+```powershell
+azd deploy
+```
+
+If you need to override defaults, set deployment-time environment variables in the `azd` environment before deploying:
+
+```powershell
+azd env set AZURE_AI_MODEL_DEPLOYMENT_NAME gpt-4o
+azd env set TOOLBOX_NAME my-toolset
+```
+
+For end-to-end hosted agent deployment guidance, see the [official deployment guide](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent).
+
+---
+
+## NuGet package users
+
+Use the standard `Dockerfile` instead of `Dockerfile.contributor`. See the commented section in `HostedToolbox.csproj` for the `PackageReference` alternative.
+
 ## Related samples
 
-- [`Hosted-Toolbox-AuthPaths/`](../Hosted-Toolbox-AuthPaths/) — extends this pattern with a three-tool toolbox demonstrating different MCP-tool authentication paths (key, Entra agent identity, inline `Authorization`), driven by the shared `Using-Samples/SimpleAgent/` REPL.
+- [`Hosted-Toolbox-AuthPaths/`](../Hosted-Toolbox-AuthPaths/) — same hosting bones as this sample, but the toolbox bundles three MCP tools each authenticated differently (key, Entra agent identity, inline `Authorization`), driven by the shared `Using-Samples/SimpleAgent/` REPL.
 - [`Hosted-McpTools/`](../Hosted-McpTools/) — contrasts client-side `McpClient` vs server-side `HostedMcpServerTool` for non-toolbox MCP servers.

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

@@ -0,0 +1,47 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/AgentManifest.yaml
+name: hosted-toolbox
+displayName: "Hosted Toolbox"
+
+description: >
+  A hosted agent that loads its tools from a single Foundry Toolbox via the
+  AF Foundry hosting bridge. AddFoundryToolboxes(name) connects to the Foundry
+  Toolboxes MCP proxy at startup and exposes the toolbox's bundled tools to the
+  agent on every request. The toolbox itself is provisioned out of band; see this
+  sample's README for the portal walkthrough.
+
+metadata:
+  tags:
+    - AI Agent Hosting
+    - Azure AI AgentServer
+    - Responses Protocol
+    - Agent Framework
+    - Foundry Toolbox
+    - MCP
+
+template:
+  name: hosted-toolbox
+  kind: hosted
+  protocols:
+    - protocol: responses
+      version: 1.0.0
+  resources:
+    cpu: "0.25"
+    memory: 0.5Gi
+  environment_variables:
+    - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
+      value: "{{AZURE_AI_MODEL_DEPLOYMENT_NAME}}"
+    - name: TOOLBOX_NAME
+      value: "{{TOOLBOX_NAME}}"
+parameters:
+  properties:
+    - name: TOOLBOX_NAME
+      type: string
+      default: "my-toolset"
+      description: "Name of the Foundry Toolbox to load at runtime."
+resources:
+  - kind: model
+    id: gpt-4o
+    name: AZURE_AI_MODEL_DEPLOYMENT_NAME
+  - kind: toolbox
+    name: "{{TOOLBOX_NAME}}"
+    tools: []

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

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

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

@@ -2,5 +2,5 @@ FOUNDRY_PROJECT_ENDPOINT=<your-azure-ai-project-endpoint>
 ASPNETCORE_URLS=http://+:8088
 ASPNETCORE_ENVIRONMENT=Development
 FOUNDRY_MODEL=gpt-5
-FOUNDRY_TOOLBOX_NAME=<your-toolbox-name>
+TOOLBOX_NAME=<your-toolbox-name>
 AZURE_BEARER_TOKEN=DefaultAzureCredential

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

@@ -7,9 +7,16 @@
 // AgentSkillsProviderBuilder.UseMcpSkills().
 //
 // Required environment variables:
-//   FOUNDRY_PROJECT_ENDPOINT         - Azure AI Foundry project endpoint
-//   FOUNDRY_TOOLBOX_NAME              - Name of the Foundry Toolbox to connect to
-//   FOUNDRY_MODEL    - Model deployment name (default: gpt-5)
+//   FOUNDRY_PROJECT_ENDPOINT         - Foundry project endpoint
+//   TOOLBOX_NAME                     - Name of the Foundry Toolbox to connect to
+//
+// Optional:
+//   FOUNDRY_MODEL                    - Model deployment name (default: gpt-5)
+//
+// NOTE: All FOUNDRY_* and AGENT_* env-var prefixes (other than the platform-injected ones
+// listed above) are reserved by the Foundry container platform and rejected at agent-create.
+// Use TOOLBOX_NAME, not FOUNDRY_TOOLBOX_NAME, for the sample-owned toolbox name so it
+// survives deployment.
 
 using System.Net.Http.Headers;
 using Azure.AI.Projects;
@@ -27,8 +34,8 @@ Env.TraversePath().Load();
 var projectEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
     ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
 var deployment = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5";
-var toolboxName = Environment.GetEnvironmentVariable("FOUNDRY_TOOLBOX_NAME")
-    ?? throw new InvalidOperationException("FOUNDRY_TOOLBOX_NAME is not set.");
+var toolboxName = Environment.GetEnvironmentVariable("TOOLBOX_NAME")
+    ?? throw new InvalidOperationException("TOOLBOX_NAME is not set.");
 
 // Build the Toolbox MCP URL from the project endpoint and toolbox name.
 var toolboxMcpServerUrl = $"{projectEndpoint.TrimEnd('/')}/toolboxes/{toolboxName}/mcp?api-version=v1";

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

@@ -13,7 +13,7 @@ This way the full skill body and resources are only loaded when the agent actual
 ## Prerequisites
 
 - [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
-- An Azure AI Foundry project with a deployed model (e.g., `gpt-5`)
+- A Foundry project with a deployed model (e.g., `gpt-5`)
 - A Foundry Toolbox already configured with skills provisioned
 - Azure CLI logged in (`az login`)
 
@@ -25,14 +25,14 @@ Copy the template and fill in your values:
 cp .env.example .env
 ```
 
-Edit `.env` and set your Azure AI Foundry project endpoint and toolbox name:
+Edit `.env` and set your Foundry project endpoint and toolbox name:
 
 ```env
 FOUNDRY_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>
 ASPNETCORE_URLS=http://+:8088
 ASPNETCORE_ENVIRONMENT=Development
 FOUNDRY_MODEL=gpt-5
-FOUNDRY_TOOLBOX_NAME=my-toolbox
+TOOLBOX_NAME=my-toolbox
 ```
 
 > **Note:** `.env` is gitignored. The `.env.example` template is checked in as a reference.

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

@@ -30,11 +30,11 @@ template:
   environment_variables:
     - name: FOUNDRY_MODEL
       value: "{{FOUNDRY_MODEL}}"
-    - name: FOUNDRY_TOOLBOX_NAME
-      value: "{{FOUNDRY_TOOLBOX_NAME}}"
+    - name: TOOLBOX_NAME
+      value: "{{TOOLBOX_NAME}}"
 parameters:
   properties:
-    - name: FOUNDRY_TOOLBOX_NAME
+    - name: TOOLBOX_NAME
       secret: false
       description: Name of the Foundry Toolbox to connect to for MCP skill discovery
 resources:

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

@@ -10,5 +10,5 @@ resources:
 environment_variables:
   - name: FOUNDRY_MODEL
     value: ${FOUNDRY_MODEL}
-  - name: FOUNDRY_TOOLBOX_NAME
-    value: ${FOUNDRY_TOOLBOX_NAME}
+  - name: TOOLBOX_NAME
+    value: ${TOOLBOX_NAME}

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

@@ -7,7 +7,7 @@ A hosted agent server demonstrating two patterns in a single app:
 
 Both agents are served over the Responses protocol. The server also exposes interactive web demos at `/tool-demo` and `/workflow-demo`.
 
-> Unlike the other samples in this folder, this one connects to an **Azure OpenAI** resource directly (not an Azure AI Foundry project endpoint).
+> Unlike the other samples in this folder, this one connects to an **Azure OpenAI** resource directly (not a Foundry project endpoint).
 
 ## Prerequisites
 

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

@@ -5,7 +5,7 @@ A hosted agent that demonstrates **multi-agent workflow orchestration**. Three t
 ## Prerequisites
 
 - [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
-- An Azure AI Foundry project with a deployed model (e.g., `hosted-workflow-simple`)
+- A Foundry project with a deployed model (e.g., `hosted-workflow-simple`)
 - Azure CLI logged in (`az login`)
 
 ## Configuration
@@ -16,7 +16,7 @@ Copy the template and fill in your project endpoint:
 cp .env.example .env
 ```
 
-Edit `.env` and set your Azure AI Foundry project endpoint:
+Edit `.env` and set your Foundry project endpoint:
 
 ```env
 FOUNDRY_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/README.md

@@ -0,0 +1,51 @@
+# Using-Samples — client REPLs for the hosted agents
+
+This folder holds small **client** console apps that connect to the **server** samples in the
+sibling `Hosted-*` folders. Each `Hosted-*` project is an agent you host (locally with
+`dotnet run` or deployed to Foundry); the projects here are the thing that *talks* to them.
+
+## Why these exist
+
+A hosted Foundry agent is an HTTP server, not a chat UI. It exposes only the per-agent OpenAI
+endpoint shape that the platform routes to:
+
+```
+{FOUNDRY_PROJECT_ENDPOINT}/agents/{AZURE_AI_AGENT_NAME}/endpoint/protocols/openai
+```
+
+There is no built-in console to poke it with. To actually exercise an agent — send a prompt,
+watch it call its tools, read the streamed answer — you need a client that builds a
+`FoundryAgent` against that endpoint and drives a conversation. That is all these REPLs do:
+
+1. Read `FOUNDRY_PROJECT_ENDPOINT` + `AZURE_AI_AGENT_NAME` from the environment.
+2. Derive the per-agent OpenAI endpoint URL.
+3. `AIProjectClient(...).AsAIAgent(agentEndpoint)` → `FoundryAgent`.
+4. Loop: read a line, `RunStreamingAsync`, print the streamed reply.
+
+The client is deliberately dumb. It knows nothing about tools, files, toolboxes, or auth — all
+of that is the hosted agent's concern on the server side. Swapping which agent you chat with is
+just a matter of changing `AZURE_AI_AGENT_NAME`.
+
+## Local HTTP dev
+
+When the target is a local `http://localhost:8088` dev server, the REPLs install a small
+`HttpSchemeRewritePolicy`: `AIProjectClient`/`BearerTokenPolicy` require HTTPS, so the client
+presents the endpoint as `https://` to satisfy the TLS check, then rewrites the scheme back to
+`http://` right before the request hits the wire. This is local-development only.
+
+## The clients
+
+| Client | What it targets | Notes |
+|---|---|---|
+| [`SimpleAgent/`](./SimpleAgent/) | Any hosted agent | Generic, agent-agnostic REPL. Point it at any `Hosted-*` server via `AZURE_AI_AGENT_NAME`. Used by `Hosted-Toolbox`, `Hosted-Toolbox-AuthPaths`, and `Hosted-McpTools`. |
+| [`SessionFilesClient/`](./SessionFilesClient/) | [`Hosted-Files`](../Hosted-Files/) | Same shape as `SimpleAgent`, framed around the bundled-files demo. |
+
+## Configuration (common to all clients)
+
+```env
+FOUNDRY_PROJECT_ENDPOINT=https://<host>/api/projects/<project>
+AZURE_AI_AGENT_NAME=<registered-server-side-agent-name>
+```
+
+Both are required. Authenticate with `az login` before running. See each client's own README for
+its end-to-end walkthrough.

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent/README.md

@@ -0,0 +1,63 @@
+# SimpleAgent
+
+A generic, agent-agnostic chat REPL for any hosted Foundry agent. Point it at a running
+`Hosted-*` agent via `AZURE_AI_AGENT_NAME`, and it builds a `FoundryAgent` against that agent's
+per-agent OpenAI endpoint and streams replies. This is the shared client that `Hosted-Toolbox`,
+`Hosted-Toolbox-AuthPaths`, and `Hosted-McpTools` reference for their end-to-end demos.
+
+It knows nothing about the agent's tools, toolboxes, files, or auth — those are entirely the
+server's concern. Changing which agent you chat with is just a different `AZURE_AI_AGENT_NAME`.
+See [`../README.md`](../README.md) for why these client REPLs exist at all.
+
+## Prerequisites
+
+- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
+- A running hosted agent (any `Hosted-*` sample, locally via `dotnet run` or deployed to Foundry)
+- Azure CLI logged in (`az login`)
+
+## Configuration
+
+```env
+FOUNDRY_PROJECT_ENDPOINT=https://<host>/api/projects/<project>
+AZURE_AI_AGENT_NAME=<registered-server-side-agent-name>
+```
+
+Both are required. `FOUNDRY_PROJECT_ENDPOINT` is the Foundry project endpoint URL and
+`AZURE_AI_AGENT_NAME` is the registered server-side agent name. The sample builds the per-agent
+OpenAI endpoint URL (`{FOUNDRY_PROJECT_ENDPOINT}/agents/{AZURE_AI_AGENT_NAME}/endpoint/protocols/openai`)
+from these.
+
+## Run
+
+Against a local Hosted-Toolbox agent listening on `http://localhost:8088`:
+
+```powershell
+cd dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent
+$env:FOUNDRY_PROJECT_ENDPOINT = "http://localhost:8088/api/projects/local"
+$env:AZURE_AI_AGENT_NAME = "hosted-toolbox-agent"
+dotnet run
+```
+
+When the project endpoint is `http://`, the client presents it as `https://` to satisfy the
+bearer-token TLS check, then rewrites the scheme back to `http://` right before transport
+(local-development only).
+
+## End-to-end demo
+
+With a hosted agent running:
+
+```text
+══════════════════════════════════════════════════════════
+Simple Agent Sample
+Connected to: https://localhost:8088/api/projects/local/agents/hosted-toolbox-agent/endpoint/protocols/openai
+Type a message or 'quit' to exit
+══════════════════════════════════════════════════════════
+
+You> What tools do you have available, and what can they do?
+Agent> I have the following tools from the toolbox: ...
+
+You> quit
+Goodbye!
+```
+
+The client only sent a chat prompt; the agent resolved its toolbox tools server-side and answered.

dotnet/samples/05-end-to-end/A2AClientServer/A2AServer/Program.cs

@@ -101,10 +101,15 @@ else
     throw new ArgumentException("Either A2AServer:ApiKey or A2AServer:ConnectionString & agentName must be provided");
 }
 
-// When running in production, make sure to use an SessionIsolationKeyProvider, e.g. ClaimsIdentity-based
-// if using Claims-based Identity for Authentication/Authorization
+// IMPORTANT: In production, register a SessionIsolationKeyProvider to isolate sessions by authenticated caller.
+// Without this, contextId alone is the session key — any caller who knows a contextId can access that session.
+// Example using claims-based identity:
 // builder.Services.UseClaimsBasedSessionIsolation(new() { ClaimType = ClaimTypes.NameIdentifier });
 
+// By default, NoopAgentSessionStore is used — sessions are not persisted across requests.
+// To enable multi-turn conversations, register a session store explicitly, e.g.:
+// builder.Services.AddKeyedSingleton<AgentSessionStore>(hostA2AAgent.Name, new InMemoryAgentSessionStore());
+
 builder.AddA2AServer(hostA2AAgent);
 
 var app = builder.Build();

dotnet/samples/05-end-to-end/AgentWebChat/AgentWebChat.AgentHost/Program.cs

@@ -28,10 +28,15 @@ builder.AddDevUI();
 builder.AddOpenAIChatCompletions();
 builder.AddOpenAIResponses();
 
-// When running in production, make sure to use an SessionIsolationKeyProvider, e.g. ClaimsIdentity-based
-// if using Claims-based Identity for Authentication/Authorization
+// IMPORTANT: In production, register a SessionIsolationKeyProvider to isolate sessions by authenticated caller.
+// Without this, contextId alone is the session key — any caller who knows a contextId can access that session.
+// Example using claims-based identity:
 // builder.Services.UseClaimsBasedSessionIsolation(new() { ClaimType = ClaimTypes.NameIdentifier });
 
+// By default, NoopAgentSessionStore is used — sessions are not persisted across requests.
+// To enable multi-turn conversations, register a session store explicitly, e.g.:
+// agentBuilder.WithInMemorySessionStore();
+
 var pirateAgentBuilder = builder.AddAIAgent(
     "pirate",
     instructions: "You are a pirate. Speak like a pirate",
@@ -152,8 +157,9 @@ builder.Services.AddKeyedSingleton<AIAgent>("my-di-matchingname-agent", (sp, nam
 pirateAgentBuilder.AddA2AServer();
 knightsKnavesAgentBuilder.AddA2AServer();
 
-// When running in production, make sure to use an SessionIsolationKeyProvider, e.g. ClaimsIdentity-based
-// if using Claims-based Identity for Authentication/Authorization
+// IMPORTANT: In production, register a SessionIsolationKeyProvider to isolate sessions by authenticated caller.
+// Without this, contextId alone is the session key — any caller who knows a contextId can access that session.
+// Example using claims-based identity:
 // builder.Services.UseClaimsBasedSessionIsolation(new() { ClaimType = ClaimTypes.NameIdentifier });
 
 var app = builder.Build();

dotnet/samples/05-end-to-end/Evaluation/Evaluation_FoundryRubric/Evaluation_FoundryRubric.csproj

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

dotnet/samples/05-end-to-end/Evaluation/Evaluation_FoundryRubric/Program.cs

@@ -0,0 +1,141 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample evaluates a pre-existing Azure AI Foundry agent against a rubric evaluator
+// that was authored in the Foundry portal.
+//
+// Rubric evaluators are LLM-as-judge evaluators with custom scoring dimensions you define
+// for your domain. agent-framework consumes pre-existing rubric evaluators — they are
+// authored in the Foundry portal (or via the dedicated SDK / REST surface) and referenced
+// here by name and version.
+//
+// Prerequisites:
+//   - An Azure AI Foundry project with a deployed model.
+//   - A registered Foundry agent in that project (the rubric was created against this agent).
+//   - A rubric evaluator already created in the Foundry portal.
+//   - .env (or environment) populated with the FOUNDRY_* variables below.
+//
+// IMPORTANT: FOUNDRY_PROJECT_ENDPOINT must be the project-scoped URL
+//   https://<resource>.services.ai.azure.com/api/projects/<project>
+// A bare Azure OpenAI endpoint silently fails eval submission with HTTP 500.
+
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry;
+using FoundryEvals = Microsoft.Agents.AI.Foundry.FoundryEvals;
+
+string projectEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+string model = Environment.GetEnvironmentVariable("FOUNDRY_MODEL")
+    ?? throw new InvalidOperationException("FOUNDRY_MODEL is not set.");
+string agentName = Environment.GetEnvironmentVariable("FOUNDRY_AGENT_NAME")
+    ?? throw new InvalidOperationException("FOUNDRY_AGENT_NAME is not set.");
+string? agentVersion = Environment.GetEnvironmentVariable("FOUNDRY_AGENT_VERSION");
+string rubricName = Environment.GetEnvironmentVariable("FOUNDRY_RUBRIC_NAME")
+    ?? throw new InvalidOperationException("FOUNDRY_RUBRIC_NAME is not set.");
+string? rubricVersion = Environment.GetEnvironmentVariable("FOUNDRY_RUBRIC_VERSION");
+
+// WARNING: DefaultAzureCredential is convenient for development but requires careful
+// consideration in production. Prefer ManagedIdentityCredential (or a specific credential)
+// to avoid latency, unintended credential probing, and fallback security risks.
+AIProjectClient projectClient = new(new Uri(projectEndpoint), new DefaultAzureCredential());
+
+// 1. Connect to the pre-existing Foundry agent the rubric was created against.
+FoundryAgent agent;
+if (agentVersion is null)
+{
+    ProjectsAgentRecord agentRecord = await projectClient.AgentAdministrationClient.GetAgentAsync(agentName);
+    agent = projectClient.AsAIAgent(agentRecord);
+}
+else
+{
+    ProjectsAgentVersion versionRecord = await projectClient.AgentAdministrationClient.GetAgentVersionAsync(agentName, agentVersion);
+    agent = projectClient.AsAIAgent(versionRecord);
+}
+
+// 2. Reference the pre-existing rubric evaluator by name + version.
+//    Always pin a version for reproducible CI runs; a versionless ref resolves to the
+//    current version at run time and emits a Trace.TraceWarning on each criterion build.
+GeneratedEvaluatorRef rubric = rubricVersion is null
+    ? GeneratedEvaluatorRef.Latest(rubricName)
+    : new GeneratedEvaluatorRef(rubricName, rubricVersion);
+
+// 3. Mix the rubric with built-in evaluators in a single FoundryEvals config.
+//    The implicit conversion lets you pass strings and refs interchangeably.
+FoundryEvals evals = new(
+    projectClient,
+    model,
+    rubric,
+    FoundryEvals.Relevance,
+    FoundryEvals.Coherence);
+
+// 4. Run two example queries against the agent and evaluate the outputs in one call.
+string[] queries =
+[
+    "What's the weather like in Seattle?",
+    "Should I bring an umbrella to London tomorrow?",
+];
+
+Console.WriteLine(new string('=', 60));
+Console.WriteLine($"Evaluating '{agent.Name}' with rubric '{rubricName}' (version {rubricVersion ?? "latest"})");
+Console.WriteLine(new string('=', 60));
+
+AgentEvaluationResults results = await agent.EvaluateAsync(queries, evals);
+
+Console.WriteLine($"Status: {results.Status}");
+Console.WriteLine($"Results: {results.Passed}/{results.Total} passed");
+if (results.ReportUrl is not null)
+{
+    Console.WriteLine($"Portal: {results.ReportUrl}");
+}
+
+Console.WriteLine(results.Passed == results.Total ? "[PASS] All passed" : $"[FAIL] {results.Failed} failed");
+
+// 5. Print per-dimension breakdown for each evaluated item — this is the unique value
+//    of a rubric evaluator over the built-in numeric ones.
+Console.WriteLine();
+Console.WriteLine(new string('=', 60));
+Console.WriteLine("Per-dimension scores");
+Console.WriteLine(new string('=', 60));
+
+if (results.DetailedItems is { Count: > 0 })
+{
+    for (int i = 0; i < results.DetailedItems.Count; i++)
+    {
+        EvalItemResult item = results.DetailedItems[i];
+        Console.WriteLine($"Item {i + 1}{(i < queries.Length ? $" — \"{queries[i]}\"" : string.Empty)}");
+
+        foreach (EvalScoreResult score in item.Scores)
+        {
+            Console.WriteLine($"  {score.Name}: {score.Score:F1}{(score.Passed is bool p ? (p ? " (pass)" : " (fail)") : string.Empty)}");
+            if (score.Dimensions is { Count: > 0 } dims)
+            {
+                foreach (RubricScore d in dims)
+                {
+                    string scoreStr = d.Score is int s ? s.ToString() : "n/a";
+                    Console.WriteLine($"    - {d.Id}: {scoreStr}  (weight={d.Weight}, applicable={d.Applicable})");
+                }
+            }
+        }
+
+        Console.WriteLine();
+    }
+}
+
+// 6. CI quality gate — fail the build if a critical dimension drops below threshold.
+//    Replace "general_quality" with whatever dimension id your rubric actually defines.
+Console.WriteLine(new string('=', 60));
+Console.WriteLine("Per-dimension quality gate");
+Console.WriteLine(new string('=', 60));
+
+try
+{
+    results.AssertDimensionScoreAtLeast("general_quality", minScore: 3.0, evaluator: rubricName, requireApplicable: true);
+    Console.WriteLine($"[PASS] {results.ProviderName}: general_quality >= 3 on every item");
+}
+catch (InvalidOperationException ex)
+{
+    Console.WriteLine($"[FAIL] {results.ProviderName}: dimension gate tripped: {ex.Message}");
+    System.Environment.ExitCode = 1;
+}

dotnet/samples/05-end-to-end/Evaluation/Evaluation_FoundryRubric/README.md

@@ -0,0 +1,55 @@
+# Evaluation — Foundry Rubric
+
+This sample evaluates a pre-existing Azure AI Foundry agent against a **rubric evaluator**
+authored in the Foundry portal. Rubric evaluators are LLM-as-judge evaluators with custom
+scoring dimensions you define for your domain; agent-framework references them by name and
+version, mixes them with built-in evaluators, and exposes per-dimension scores you can gate
+CI on.
+
+## What this sample demonstrates
+
+- Connecting to a pre-existing Foundry agent (`AgentAdministrationClient.GetAgentAsync`).
+- Referencing a pre-existing rubric evaluator via `GeneratedEvaluatorRef(name, version)`.
+- Mixing the rubric with built-in evaluators (`Relevance`, `Coherence`) in one
+  `FoundryEvals` run.
+- Reading per-dimension breakdowns from `EvalScoreResult.Dimensions`.
+- Gating CI on a per-dimension threshold via
+  `AgentEvaluationResults.AssertDimensionScoreAtLeast(...)`.
+
+## Prerequisites
+
+- .NET 10 SDK or later.
+- Azure CLI installed and authenticated (`az login`).
+- An Azure AI Foundry project with a deployed model.
+- A registered Foundry agent in that project (the agent the rubric was created against).
+- A rubric evaluator created in the Foundry portal. Creating rubrics through the portal
+  currently requires picking a Foundry agent as the generation context, so this
+  prerequisite is implied by having a rubric at all.
+
+> [!IMPORTANT]
+> `FOUNDRY_PROJECT_ENDPOINT` **must** be the project-scoped URL
+> `https://<resource>.services.ai.azure.com/api/projects/<project>`. A bare Azure OpenAI
+> endpoint silently fails eval submission with HTTP 500.
+
+> [!NOTE]
+> An **Eval Definition** (a saved bundle of testing_criteria with `"object": "eval"`) is
+> not the same as a **Rubric Evaluator** (a standalone evaluator with dimensions, weights,
+> and a version). `GeneratedEvaluatorRef` points at the latter.
+
+## Environment variables
+
+```powershell
+$env:FOUNDRY_PROJECT_ENDPOINT="https://your-resource.services.ai.azure.com/api/projects/your-project"
+$env:FOUNDRY_MODEL="gpt-4o-mini"
+$env:FOUNDRY_AGENT_NAME="your-agent-name"
+$env:FOUNDRY_AGENT_VERSION="1"                   # optional; omit for latest
+$env:FOUNDRY_RUBRIC_NAME="your-rubric-name"
+$env:FOUNDRY_RUBRIC_VERSION="1"                  # optional; omit for latest (CI: pin this)
+```
+
+## Run the sample
+
+```powershell
+cd dotnet/samples/05-end-to-end/Evaluation
+dotnet run --project .\Evaluation_FoundryRubric
+```

dotnet/samples/AGENTS.md

@@ -80,33 +80,35 @@ dotnet/samples/
 
 ## Default provider
 
-All canonical samples (01-get-started) use **Azure OpenAI** via `AzureOpenAIClient`
-with `DefaultAzureCredential`:
+All canonical samples (01-get-started) use **Microsoft Foundry** via `AIProjectClient.AsAIAgent()` with `DefaultAzureCredential`:
 
 ```csharp
-using Azure.AI.OpenAI;
+using Azure.AI.Projects;
 using Azure.Identity;
 using Microsoft.Agents.AI;
-using OpenAI.Chat;
 
-var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
-    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var model = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
 
 // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
 // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
 // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
-    .GetChatClient(deploymentName)
-    .AsAIAgent(instructions: "...", name: "...");
+AIAgent agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
+    .AsAIAgent(model: model, instructions: "...", name: "...");
 ```
 
 Environment variables:
-- `AZURE_OPENAI_ENDPOINT` — Your Azure OpenAI endpoint
-- `AZURE_OPENAI_DEPLOYMENT_NAME` — Model deployment name (defaults to `gpt-5.4-mini`)
+- `FOUNDRY_PROJECT_ENDPOINT` — Your Foundry project endpoint
+- `FOUNDRY_MODEL` — Model name (defaults to `gpt-5.4-mini`)
 
 For authentication, run `az login` before running samples.
 
+**Note:** Use `FoundryAgent` only when demonstrating Foundry-managed (prompt) agents specifically — see `02-agents/AgentsWithFoundry/`. For all other samples, use `AIProjectClient.AsAIAgent()`.
+
+**Note:** For samples demonstrating other providers (Azure OpenAI, OpenAI, Anthropic, etc.), see `02-agents/AgentProviders/`.
+
+
 ## Snippet tags for docs integration
 
 Samples embed named snippet regions for future `:::code` integration:
@@ -135,4 +137,3 @@ dotnet run
 - Azure Functions hosting uses `ConfigureDurableAgents(options => options.AddAIAgent(agent))`
 - Workflows use `WorkflowBuilder` with `Executor<TIn, TOut>` and edge connections
 
-

dotnet/src/Microsoft.Agents.AI.DurableTask/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## [Unreleased]
 
+- Bind MCP threadId to the current agent and guard cross-agent session dispatch ([#6531](https://github.com/microsoft/agent-framework/pull/6531))
 - Added support for durable workflows ([#4436](https://github.com/microsoft/agent-framework/pull/4436))
 
 ## v1.0.0-preview.260219.1

dotnet/src/Microsoft.Agents.AI.DurableTask/DurableAIAgentProxy.cs

@@ -79,6 +79,15 @@ internal class DurableAIAgentProxy(string name, IDurableAgentClient agentClient)
         RunRequest request = new([.. messages], responseFormat, enableToolCalls, enableToolNames);
         AgentSessionId sessionId = durableSession.SessionId;
 
+        // The session must belong to this agent.
+        if (!string.Equals(sessionId.Name, this.Name, StringComparison.OrdinalIgnoreCase))
+        {
+            throw new ArgumentException(
+                $"The provided session belongs to agent '{sessionId.Name}' but was passed to agent '{this.Name}'. " +
+                "Sessions cannot be reused across agents.",
+                paramName: nameof(session));
+        }
+
         AgentRunHandle agentRunHandle = await this._agentClient.RunAgentAsync(sessionId, request, cancellationToken);
 
         if (isFireAndForget)

dotnet/src/Microsoft.Agents.AI.Foundry.Hosting/OutputConverter.cs

@@ -3,6 +3,7 @@
 using System;
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
+using System.Linq;
 using System.Runtime.CompilerServices;
 using System.Security.Cryptography;
 using System.Text;
@@ -45,6 +46,7 @@ internal static class OutputConverter
         OutputItemMessageBuilder? currentMessageBuilder = null;
         TextContentBuilder? currentTextBuilder = null;
         StringBuilder? accumulatedText = null;
+        List<Annotation>? accumulatedAnnotations = null;
         string? previousMessageId = null;
         bool hasTerminalEvent = false;
         var executorItemIds = new Dictionary<string, string>();
@@ -60,7 +62,7 @@ internal static class OutputConverter
             if (update.RawRepresentation is WorkflowEvent workflowEvent && update.Contents.Count == 0)
             {
                 // Close any open message builder before emitting workflow items
-                foreach (var evt in CloseCurrentMessage(currentMessageBuilder, currentTextBuilder, accumulatedText))
+                foreach (var evt in CloseCurrentMessage(currentMessageBuilder, currentTextBuilder, accumulatedText, accumulatedAnnotations))
                 {
                     yield return evt;
                 }
@@ -68,6 +70,7 @@ internal static class OutputConverter
                 currentTextBuilder = null;
                 currentMessageBuilder = null;
                 accumulatedText = null;
+                accumulatedAnnotations = null;
                 previousMessageId = null;
 
                 foreach (var evt in EmitWorkflowEvent(stream, workflowEvent, executorItemIds))
@@ -86,7 +89,7 @@ internal static class OutputConverter
                     {
                         if (!IsSameMessage(update.MessageId, previousMessageId) && currentMessageBuilder is not null)
                         {
-                            foreach (var evt in CloseCurrentMessage(currentMessageBuilder, currentTextBuilder, accumulatedText))
+                            foreach (var evt in CloseCurrentMessage(currentMessageBuilder, currentTextBuilder, accumulatedText, accumulatedAnnotations))
                             {
                                 yield return evt;
                             }
@@ -94,6 +97,7 @@ internal static class OutputConverter
                             currentTextBuilder = null;
                             currentMessageBuilder = null;
                             accumulatedText = null;
+                            accumulatedAnnotations = null;
                         }
 
                         previousMessageId = update.MessageId;
@@ -115,6 +119,14 @@ internal static class OutputConverter
                             yield return currentTextBuilder!.EmitDelta(textContent.Text);
                         }
 
+                        if (textContent.Annotations is { Count: > 0 })
+                        {
+                            foreach (var sdkAnnotation in ConvertToSdkAnnotations(textContent.Annotations))
+                            {
+                                (accumulatedAnnotations ??= []).Add(sdkAnnotation);
+                            }
+                        }
+
                         break;
                     }
 
@@ -125,7 +137,7 @@ internal static class OutputConverter
                             break;
                         }
 
-                        foreach (var evt in CloseCurrentMessage(currentMessageBuilder, currentTextBuilder, accumulatedText))
+                        foreach (var evt in CloseCurrentMessage(currentMessageBuilder, currentTextBuilder, accumulatedText, accumulatedAnnotations))
                         {
                             yield return evt;
                         }
@@ -133,6 +145,7 @@ internal static class OutputConverter
                         currentTextBuilder = null;
                         currentMessageBuilder = null;
                         accumulatedText = null;
+                        accumulatedAnnotations = null;
                         previousMessageId = null;
 
                         var arguments = functionCall.Arguments is not null
@@ -149,7 +162,7 @@ internal static class OutputConverter
 
                     case TextReasoningContent reasoningContent:
                     {
-                        foreach (var evt in CloseCurrentMessage(currentMessageBuilder, currentTextBuilder, accumulatedText))
+                        foreach (var evt in CloseCurrentMessage(currentMessageBuilder, currentTextBuilder, accumulatedText, accumulatedAnnotations))
                         {
                             yield return evt;
                         }
@@ -157,6 +170,7 @@ internal static class OutputConverter
                         currentTextBuilder = null;
                         currentMessageBuilder = null;
                         accumulatedText = null;
+                        accumulatedAnnotations = null;
                         previousMessageId = null;
 
                         var reasoningBuilder = stream.AddOutputItemReasoningItem();
@@ -176,7 +190,7 @@ internal static class OutputConverter
 
                     case ToolApprovalRequestContent approvalRequest when approvalRequest.ToolCall is FunctionCallContent approvalFunctionCall:
                     {
-                        foreach (var evt in CloseCurrentMessage(currentMessageBuilder, currentTextBuilder, accumulatedText))
+                        foreach (var evt in CloseCurrentMessage(currentMessageBuilder, currentTextBuilder, accumulatedText, accumulatedAnnotations))
                         {
                             yield return evt;
                         }
@@ -184,6 +198,7 @@ internal static class OutputConverter
                         currentTextBuilder = null;
                         currentMessageBuilder = null;
                         accumulatedText = null;
+                        accumulatedAnnotations = null;
                         previousMessageId = null;
 
                         // The Responses API only standardizes the MCP-flavored approval primitive.
@@ -237,7 +252,7 @@ internal static class OutputConverter
 
                     case ErrorContent errorContent:
                     {
-                        foreach (var evt in CloseCurrentMessage(currentMessageBuilder, currentTextBuilder, accumulatedText))
+                        foreach (var evt in CloseCurrentMessage(currentMessageBuilder, currentTextBuilder, accumulatedText, accumulatedAnnotations))
                         {
                             yield return evt;
                         }
@@ -245,6 +260,7 @@ internal static class OutputConverter
                         currentTextBuilder = null;
                         currentMessageBuilder = null;
                         accumulatedText = null;
+                        accumulatedAnnotations = null;
                         previousMessageId = null;
                         hasTerminalEvent = true;
 
@@ -269,7 +285,7 @@ internal static class OutputConverter
                             break;
                         }
 
-                        foreach (var evt in CloseCurrentMessage(currentMessageBuilder, currentTextBuilder, accumulatedText))
+                        foreach (var evt in CloseCurrentMessage(currentMessageBuilder, currentTextBuilder, accumulatedText, accumulatedAnnotations))
                         {
                             yield return evt;
                         }
@@ -277,6 +293,7 @@ internal static class OutputConverter
                         currentTextBuilder = null;
                         currentMessageBuilder = null;
                         accumulatedText = null;
+                        accumulatedAnnotations = null;
                         previousMessageId = null;
 
                         var outputText = EncodeFunctionResultAsJsonStringPayload(functionResult.Result);
@@ -304,7 +321,7 @@ internal static class OutputConverter
         }
 
         // Close any remaining open message
-        foreach (var evt in CloseCurrentMessage(currentMessageBuilder, currentTextBuilder, accumulatedText))
+        foreach (var evt in CloseCurrentMessage(currentMessageBuilder, currentTextBuilder, accumulatedText, accumulatedAnnotations))
         {
             yield return evt;
         }
@@ -318,7 +335,8 @@ internal static class OutputConverter
     private static IEnumerable<ResponseStreamEvent> CloseCurrentMessage(
         OutputItemMessageBuilder? messageBuilder,
         TextContentBuilder? textBuilder,
-        StringBuilder? accumulatedText)
+        StringBuilder? accumulatedText,
+        List<Annotation>? annotations = null)
     {
         if (messageBuilder is null)
         {
@@ -329,6 +347,16 @@ internal static class OutputConverter
         {
             var finalText = accumulatedText?.ToString() ?? string.Empty;
             yield return textBuilder.EmitTextDone(finalText);
+
+            // Annotations must be emitted after EmitTextDone and before EmitDone.
+            if (annotations is not null)
+            {
+                foreach (var annotation in annotations)
+                {
+                    yield return textBuilder.EmitAnnotationAdded(annotation);
+                }
+            }
+
             yield return textBuilder.EmitDone();
         }
 
@@ -338,6 +366,41 @@ internal static class OutputConverter
     private static bool IsSameMessage(string? currentId, string? previousId) =>
         currentId is not { Length: > 0 } || previousId is not { Length: > 0 } || currentId == previousId;
 
+    /// <summary>
+    /// Converts MEAI <see cref="AIAnnotation"/> instances to Responses SDK <see cref="Annotation"/> objects.
+    /// Only <see cref="CitationAnnotation"/> with a URL and at least one <see cref="TextSpanAnnotatedRegion"/>
+    /// with explicit start/end indices is converted; all other shapes are skipped.
+    /// </summary>
+    private static IEnumerable<Annotation> ConvertToSdkAnnotations(IList<AIAnnotation> annotations)
+    {
+        foreach (var ann in annotations)
+        {
+            if (ann is not CitationAnnotation citation || citation.Url is null)
+            {
+                continue;
+            }
+
+            var regions = citation.AnnotatedRegions?
+                .OfType<TextSpanAnnotatedRegion>()
+                .Where(r => r.StartIndex is not null && r.EndIndex is not null)
+                .ToList();
+
+            if (regions is not { Count: > 0 })
+            {
+                continue;
+            }
+
+            foreach (var region in regions)
+            {
+                yield return new UrlCitationBody(
+                    citation.Url,
+                    region.StartIndex!.Value,
+                    region.EndIndex!.Value,
+                    citation.Title ?? string.Empty);
+            }
+        }
+    }
+
     private static ResponseUsage ConvertUsage(UsageDetails details, ResponseUsage? existing)
     {
         var inputTokens = details.InputTokenCount ?? 0;