Fix typing

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

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

@@ -331,6 +331,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 +411,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 +620,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 +676,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/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/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/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/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;

dotnet/src/Microsoft.Agents.AI.Foundry/Evaluation/FoundryEvalConverter.cs

@@ -148,19 +148,68 @@ internal static class FoundryEvalConverter
     /// <summary>
     /// Builds the <c>testing_criteria</c> array for <c>evals.create()</c>.
     /// </summary>
-    /// <param name="evaluators">Evaluator names (short or fully-qualified).</param>
+    /// <param name="evaluators">
+    /// Evaluator specs — built-in evaluator names (short or fully-qualified) and/or
+    /// <see cref="GeneratedEvaluatorRef"/> instances for pre-existing rubric evaluators.
+    /// </param>
     /// <param name="model">Model deployment name for the LLM judge.</param>
     /// <param name="includeDataMapping">
     /// Whether to include field-level data mapping (required for JSONL data source).
     /// </param>
+    /// <param name="includeToolDefinitions">
+    /// Whether the mapped data items include tool definitions. Used to add a
+    /// <c>tool_definitions</c> mapping entry for rubric evaluators (built-in evaluators
+    /// derive this from their own <see cref="ToolEvaluators"/> membership).
+    /// </param>
     internal static List<WireTestingCriterion> BuildTestingCriteria(
-        IEnumerable<string> evaluators,
+        IEnumerable<FoundryEvaluatorSpec> evaluators,
         string model,
-        bool includeDataMapping = false)
+        bool includeDataMapping = false,
+        bool includeToolDefinitions = false)
     {
         var criteria = new List<WireTestingCriterion>();
-        foreach (var name in evaluators)
+        foreach (var spec in evaluators)
         {
+            if (spec.IsRubric)
+            {
+                var @ref = spec.GeneratedRef!;
+                Dictionary<string, string>? refMapping = null;
+                if (includeDataMapping)
+                {
+                    // Rubric evaluators accept conversation arrays like agent evaluators,
+                    // plus tool_definitions when items are tool-aware.
+                    refMapping = new Dictionary<string, string>
+                    {
+                        ["query"] = "{{item.query_messages}}",
+                        ["response"] = "{{item.response_messages}}",
+                    };
+
+                    if (includeToolDefinitions)
+                    {
+                        refMapping["tool_definitions"] = "{{item.tool_definitions}}";
+                    }
+                }
+
+                criteria.Add(new WireTestingCriterion
+                {
+                    Name = @ref.DisplayName ?? @ref.Name,
+                    EvaluatorName = @ref.Name,
+                    EvaluatorVersion = @ref.Version,
+                    InitializationParameters = new WireInitParams { DeploymentName = model },
+                    DataMapping = refMapping,
+                });
+
+                if (@ref.Version is null)
+                {
+                    System.Diagnostics.Trace.TraceWarning(
+                        "GeneratedEvaluatorRef '{0}' has no pinned version; the eval run will resolve to whichever version is current at execution time. Pin the version for reproducible runs.",
+                        @ref.Name);
+                }
+
+                continue;
+            }
+
+            var name = spec.BuiltinName!;
             var qualified = ResolveEvaluator(name);
             var shortName = name.StartsWith("builtin.", StringComparison.Ordinal)
                 ? name.Substring("builtin.".Length)
@@ -248,8 +297,12 @@ internal static class FoundryEvalConverter
     /// Returns the subset of <paramref name="evaluators"/> that require a ground-truth
     /// (reference) value but cannot be evaluated because no item provided one.
     /// </summary>
+    /// <remarks>
+    /// Rubric references (<see cref="GeneratedEvaluatorRef"/>) are skipped — they are not
+    /// ground-truth–dependent on the wire.
+    /// </remarks>
     internal static List<string> FindMissingGroundTruthEvaluators(
-        IEnumerable<string> evaluators,
+        IEnumerable<FoundryEvaluatorSpec> evaluators,
         bool hasGroundTruth)
     {
         if (hasGroundTruth)
@@ -258,8 +311,14 @@ internal static class FoundryEvalConverter
         }
 
         var missing = new List<string>();
-        foreach (var name in evaluators)
+        foreach (var spec in evaluators)
         {
+            if (spec.IsRubric)
+            {
+                continue;
+            }
+
+            var name = spec.BuiltinName!;
             if (GroundTruthEvaluators.Contains(ResolveEvaluator(name)))
             {
                 missing.Add(name);

dotnet/src/Microsoft.Agents.AI.Foundry/Evaluation/FoundryEvalWireModels.cs

@@ -137,6 +137,9 @@ internal sealed class WireTestingCriterion
     [JsonPropertyName("evaluator_name")]
     public required string EvaluatorName { get; init; }
 
+    [JsonPropertyName("evaluator_version")]
+    public string? EvaluatorVersion { get; init; }
+
     [JsonPropertyName("initialization_parameters")]
     public required WireInitParams InitializationParameters { get; init; }
 

dotnet/src/Microsoft.Agents.AI.Foundry/Evaluation/FoundryEvals.cs

@@ -43,7 +43,7 @@ public sealed class FoundryEvals : IAgentEvaluator
 
     private readonly EvaluationClient _evaluationClient;
     private readonly string _model;
-    private readonly string[] _evaluatorNames;
+    private readonly FoundryEvaluatorSpec[] _evaluators;
     private readonly IConversationSplitter? _splitter;
     private readonly double _pollIntervalSeconds = 5.0;
     private readonly double _timeoutSeconds = 300.0;
@@ -58,17 +58,21 @@ public sealed class FoundryEvals : IAgentEvaluator
     /// <param name="projectClient">The Azure AI Foundry project client.</param>
     /// <param name="model">Model deployment name for the LLM judge evaluator.</param>
     /// <param name="evaluators">
-    /// Names of evaluators to use (e.g., <see cref="Relevance"/>, <see cref="Coherence"/>).
-    /// When empty, defaults to relevance and coherence.
+    /// Evaluator specs to use. Each entry can be a built-in evaluator name (string, for example
+    /// <see cref="Relevance"/>) or a <see cref="GeneratedEvaluatorRef"/> for a rubric evaluator
+    /// already registered in the Foundry project. When empty, defaults to relevance, coherence,
+    /// and task adherence.
     /// </param>
-    public FoundryEvals(AIProjectClient projectClient, string model, params string[] evaluators)
+    public FoundryEvals(AIProjectClient projectClient, string model, params FoundryEvaluatorSpec[] evaluators)
     {
         ArgumentNullException.ThrowIfNull(projectClient);
         ArgumentException.ThrowIfNullOrWhiteSpace(model);
+        ArgumentNullException.ThrowIfNull(evaluators);
+        EnsureAllSpecsValid(evaluators, nameof(evaluators));
 
         this._evaluationClient = projectClient.GetProjectOpenAIClient().GetEvaluationClient();
         this._model = model;
-        this._evaluatorNames = evaluators.Length > 0
+        this._evaluators = evaluators.Length > 0
             ? evaluators
             : [Relevance, Coherence, TaskAdherence];
     }
@@ -84,14 +88,14 @@ public sealed class FoundryEvals : IAgentEvaluator
     /// or a custom <see cref="IConversationSplitter"/> implementation.
     /// </param>
     /// <param name="evaluators">
-    /// Names of evaluators to use (e.g., <see cref="Relevance"/>, <see cref="Coherence"/>).
-    /// When empty, defaults to relevance and coherence.
+    /// Evaluator specs (built-in names and/or <see cref="GeneratedEvaluatorRef"/> instances).
+    /// When empty, defaults to relevance, coherence, and task adherence.
     /// </param>
     public FoundryEvals(
         AIProjectClient projectClient,
         string model,
         IConversationSplitter? splitter,
-        params string[] evaluators)
+        params FoundryEvaluatorSpec[] evaluators)
         : this(projectClient, model, evaluators)
     {
         this._splitter = splitter;
@@ -107,14 +111,16 @@ public sealed class FoundryEvals : IAgentEvaluator
     /// </param>
     /// <param name="pollIntervalSeconds">Seconds between status polls (default 5).</param>
     /// <param name="timeoutSeconds">Maximum seconds to wait for completion (default 300).</param>
-    /// <param name="evaluators">Evaluator names to use.</param>
+    /// <param name="evaluators">
+    /// Evaluator specs (built-in names and/or <see cref="GeneratedEvaluatorRef"/> instances).
+    /// </param>
     public FoundryEvals(
         AIProjectClient projectClient,
         string model,
         IConversationSplitter? splitter,
         double pollIntervalSeconds,
         double timeoutSeconds,
-        params string[] evaluators)
+        params FoundryEvaluatorSpec[] evaluators)
         : this(projectClient, model, splitter, evaluators)
     {
         ArgumentOutOfRangeException.ThrowIfLessThanOrEqual(pollIntervalSeconds, 0);
@@ -123,6 +129,81 @@ public sealed class FoundryEvals : IAgentEvaluator
         this._timeoutSeconds = timeoutSeconds;
     }
 
+    // -----------------------------------------------------------------------
+    // string[] constructor overloads (source-compat with older API that took
+    // `params string[] evaluators` before FoundryEvaluatorSpec was introduced).
+    // `params` is intentionally omitted to avoid overload ambiguity with the
+    // spec-based ctors at zero-args; individual string literals still resolve
+    // through `params FoundryEvaluatorSpec[]` via implicit conversion.
+    // -----------------------------------------------------------------------
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FoundryEvals"/> class using built-in evaluator
+    /// names. Preserves source compatibility for callers that pass a <see cref="string"/> array.
+    /// </summary>
+    /// <param name="projectClient">The Azure AI Foundry project client.</param>
+    /// <param name="model">Model deployment name for the LLM judge evaluator.</param>
+    /// <param name="evaluators">Built-in evaluator names (for example <see cref="Relevance"/>).</param>
+    public FoundryEvals(AIProjectClient projectClient, string model, string[] evaluators)
+        : this(projectClient, model, ToSpecs(evaluators))
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FoundryEvals"/> class with a splitter and
+    /// built-in evaluator names.
+    /// </summary>
+    /// <param name="projectClient">The Azure AI Foundry project client.</param>
+    /// <param name="model">Model deployment name for the LLM judge evaluator.</param>
+    /// <param name="splitter">Default conversation splitter for multi-turn conversations.</param>
+    /// <param name="evaluators">Built-in evaluator names.</param>
+    public FoundryEvals(
+        AIProjectClient projectClient,
+        string model,
+        IConversationSplitter? splitter,
+        string[] evaluators)
+        : this(projectClient, model, splitter, ToSpecs(evaluators))
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FoundryEvals"/> class with full configuration
+    /// and built-in evaluator names.
+    /// </summary>
+    /// <param name="projectClient">The Azure AI Foundry project client.</param>
+    /// <param name="model">Model deployment name for the LLM judge evaluator.</param>
+    /// <param name="splitter">Default conversation splitter for multi-turn conversations.</param>
+    /// <param name="pollIntervalSeconds">Seconds between status polls.</param>
+    /// <param name="timeoutSeconds">Maximum seconds to wait for completion.</param>
+    /// <param name="evaluators">Built-in evaluator names.</param>
+    public FoundryEvals(
+        AIProjectClient projectClient,
+        string model,
+        IConversationSplitter? splitter,
+        double pollIntervalSeconds,
+        double timeoutSeconds,
+        string[] evaluators)
+        : this(projectClient, model, splitter, pollIntervalSeconds, timeoutSeconds, ToSpecs(evaluators))
+    {
+    }
+
+    private static FoundryEvaluatorSpec[] ToSpecs(string[]? evaluators)
+    {
+        if (evaluators is null || evaluators.Length == 0)
+        {
+            return [];
+        }
+
+        var specs = new FoundryEvaluatorSpec[evaluators.Length];
+        for (int i = 0; i < evaluators.Length; i++)
+        {
+            specs[i] = evaluators[i]
+                ?? throw new ArgumentException($"Evaluator name at index {i} is null.", nameof(evaluators));
+        }
+
+        return specs;
+    }
+
     // -----------------------------------------------------------------------
     // IAgentEvaluator
     // -----------------------------------------------------------------------
@@ -149,10 +230,10 @@ public sealed class FoundryEvals : IAgentEvaluator
         bool allHaveGroundTruth = payloads.Count > 0 && payloads.All(p => p.GroundTruth is not null);
 
         // Filter out tool evaluators if no items have tools; auto-add ToolCallAccuracy if tools present
-        var evaluators = FilterToolEvaluators(this._evaluatorNames, hasTools);
-        if (hasTools && !evaluators.Any(e => FoundryEvalConverter.ToolEvaluators.Contains(FoundryEvalConverter.ResolveEvaluator(e))))
+        var evaluators = FilterToolEvaluators(this._evaluators, hasTools);
+        if (hasTools && !HasToolEvaluator(evaluators))
         {
-            evaluators = [.. evaluators, ToolCallAccuracy];
+            evaluators = [.. evaluators, (FoundryEvaluatorSpec)ToolCallAccuracy];
         }
 
         // Fail fast if a ground-truth evaluator (e.g. similarity) is requested but not
@@ -178,7 +259,7 @@ public sealed class FoundryEvals : IAgentEvaluator
                 ItemSchema = FoundryEvalConverter.BuildItemSchema(hasContext, hasTools, hasGroundTruth),
             },
             TestingCriteria = FoundryEvalConverter.BuildTestingCriteria(
-                evaluators, this._model, includeDataMapping: true),
+                evaluators, this._model, includeDataMapping: true, includeToolDefinitions: hasTools),
         };
 
         var createEvalJson = JsonSerializer.Serialize(createEvalPayload, s_jsonOptions);
@@ -270,6 +351,47 @@ public sealed class FoundryEvals : IAgentEvaluator
     // Static evaluation methods (traces and targets)
     // -----------------------------------------------------------------------
 
+    /// <summary>
+    /// Source-compat overload of <see cref="EvaluateTracesAsync(AIProjectClient, string, IEnumerable{string}, IEnumerable{string}, string, int, FoundryEvaluatorSpec[], string, double, double, CancellationToken)"/>
+    /// that accepts a <see cref="string"/> array of built-in evaluator names.
+    /// </summary>
+    /// <param name="projectClient">The Azure AI Foundry project client.</param>
+    /// <param name="model">Model deployment name for the LLM judge evaluator.</param>
+    /// <param name="responseIds">Evaluate specific Responses API response IDs.</param>
+    /// <param name="traceIds">Evaluate specific OTel trace IDs from App Insights.</param>
+    /// <param name="agentId">Filter traces by agent ID (used with <paramref name="lookbackHours"/>).</param>
+    /// <param name="lookbackHours">Hours of trace history to evaluate.</param>
+    /// <param name="evaluators">Built-in evaluator names. Each is wrapped via <see cref="FoundryEvaluatorSpec(string)"/>.</param>
+    /// <param name="evalName">Display name for the evaluation.</param>
+    /// <param name="pollIntervalSeconds">Seconds between status polls.</param>
+    /// <param name="timeoutSeconds">Maximum seconds to wait for completion.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Evaluation results with status, report URL, and per-item details.</returns>
+    public static Task<AgentEvaluationResults> EvaluateTracesAsync(
+        AIProjectClient projectClient,
+        string model,
+        IEnumerable<string>? responseIds,
+        IEnumerable<string>? traceIds,
+        string? agentId,
+        int lookbackHours,
+        string[]? evaluators = null,
+        string evalName = "Agent Framework Trace Eval",
+        double pollIntervalSeconds = 5.0,
+        double timeoutSeconds = 300.0,
+        CancellationToken cancellationToken = default)
+        => EvaluateTracesAsync(
+            projectClient,
+            model,
+            responseIds,
+            traceIds,
+            agentId,
+            lookbackHours,
+            ToSpecs(evaluators) is { Length: > 0 } specs ? specs : null,
+            evalName,
+            pollIntervalSeconds,
+            timeoutSeconds,
+            cancellationToken);
+
     /// <summary>
     /// Evaluates agent behavior from Responses API response IDs, OTel traces, or agent activity.
     /// </summary>
@@ -287,7 +409,11 @@ public sealed class FoundryEvals : IAgentEvaluator
     /// <param name="traceIds">Evaluate specific OTel trace IDs from App Insights.</param>
     /// <param name="agentId">Filter traces by agent ID (used with <paramref name="lookbackHours"/>).</param>
     /// <param name="lookbackHours">Hours of trace history to evaluate (default 24).</param>
-    /// <param name="evaluators">Evaluator names. Defaults to relevance, coherence, and task adherence.</param>
+    /// <param name="evaluators">
+    /// Evaluator specs. Each entry can be a built-in evaluator name (string) or a
+    /// <see cref="GeneratedEvaluatorRef"/> for a rubric evaluator. Defaults to relevance,
+    /// coherence, and task adherence.
+    /// </param>
     /// <param name="evalName">Display name for the evaluation.</param>
     /// <param name="pollIntervalSeconds">Seconds between status polls (default 5).</param>
     /// <param name="timeoutSeconds">Maximum seconds to wait for completion (default 300).</param>
@@ -300,7 +426,7 @@ public sealed class FoundryEvals : IAgentEvaluator
         IEnumerable<string>? traceIds = null,
         string? agentId = null,
         int lookbackHours = 24,
-        string[]? evaluators = null,
+        FoundryEvaluatorSpec[]? evaluators = null,
         string evalName = "Agent Framework Trace Eval",
         double pollIntervalSeconds = 5.0,
         double timeoutSeconds = 300.0,
@@ -320,9 +446,10 @@ public sealed class FoundryEvals : IAgentEvaluator
         }
 
         var evalClient = projectClient.GetProjectOpenAIClient().GetEvaluationClient();
-        var resolvedEvaluators = evaluators is { Length: > 0 }
+        FoundryEvaluatorSpec[] resolvedEvaluators = evaluators is { Length: > 0 }
             ? evaluators
             : [Relevance, Coherence, TaskAdherence];
+        EnsureAllSpecsValid(resolvedEvaluators, nameof(evaluators));
 
         // Create the evaluation definition with the appropriate data source scenario
         object dataSourceConfig;
@@ -429,6 +556,41 @@ public sealed class FoundryEvals : IAgentEvaluator
         };
     }
 
+    /// <summary>
+    /// Source-compat overload of <see cref="EvaluateFoundryTargetAsync(AIProjectClient, string, IDictionary{string, object}, IEnumerable{string}, FoundryEvaluatorSpec[], string, double, double, CancellationToken)"/>
+    /// that accepts a <see cref="string"/> array of built-in evaluator names.
+    /// </summary>
+    /// <param name="projectClient">The Azure AI Foundry project client.</param>
+    /// <param name="model">Model deployment name for the LLM judge evaluator.</param>
+    /// <param name="target">Target configuration (must include a "type" key).</param>
+    /// <param name="testQueries">Queries for Foundry to send to the target.</param>
+    /// <param name="evaluators">Built-in evaluator names. Each is wrapped via <see cref="FoundryEvaluatorSpec(string)"/>.</param>
+    /// <param name="evalName">Display name for the evaluation.</param>
+    /// <param name="pollIntervalSeconds">Seconds between status polls.</param>
+    /// <param name="timeoutSeconds">Maximum seconds to wait for completion.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Evaluation results with status, report URL, and per-item details.</returns>
+    public static Task<AgentEvaluationResults> EvaluateFoundryTargetAsync(
+        AIProjectClient projectClient,
+        string model,
+        IDictionary<string, object> target,
+        IEnumerable<string> testQueries,
+        string[]? evaluators = null,
+        string evalName = "Agent Framework Target Eval",
+        double pollIntervalSeconds = 5.0,
+        double timeoutSeconds = 300.0,
+        CancellationToken cancellationToken = default)
+        => EvaluateFoundryTargetAsync(
+            projectClient,
+            model,
+            target,
+            testQueries,
+            ToSpecs(evaluators) is { Length: > 0 } specs ? specs : null,
+            evalName,
+            pollIntervalSeconds,
+            timeoutSeconds,
+            cancellationToken);
+
     /// <summary>
     /// Evaluates a Foundry-registered agent or model deployment.
     /// </summary>
@@ -440,7 +602,10 @@ public sealed class FoundryEvals : IAgentEvaluator
     /// <param name="model">Model deployment name for the LLM judge evaluator.</param>
     /// <param name="target">Target configuration (must include a "type" key, e.g. "azure_ai_agent").</param>
     /// <param name="testQueries">Queries for Foundry to send to the target.</param>
-    /// <param name="evaluators">Evaluator names. Defaults to relevance, coherence, and task adherence.</param>
+    /// <param name="evaluators">
+    /// Evaluator specs (built-in names and/or <see cref="GeneratedEvaluatorRef"/> instances).
+    /// Defaults to relevance, coherence, and task adherence.
+    /// </param>
     /// <param name="evalName">Display name for the evaluation.</param>
     /// <param name="pollIntervalSeconds">Seconds between status polls (default 5).</param>
     /// <param name="timeoutSeconds">Maximum seconds to wait for completion (default 300).</param>
@@ -451,7 +616,7 @@ public sealed class FoundryEvals : IAgentEvaluator
         string model,
         IDictionary<string, object> target,
         IEnumerable<string> testQueries,
-        string[]? evaluators = null,
+        FoundryEvaluatorSpec[]? evaluators = null,
         string evalName = "Agent Framework Target Eval",
         double pollIntervalSeconds = 5.0,
         double timeoutSeconds = 300.0,
@@ -473,9 +638,10 @@ public sealed class FoundryEvals : IAgentEvaluator
         }
 
         var evalClient = projectClient.GetProjectOpenAIClient().GetEvaluationClient();
-        var resolvedEvaluators = evaluators is { Length: > 0 }
+        FoundryEvaluatorSpec[] resolvedEvaluators = evaluators is { Length: > 0 }
             ? evaluators
             : [Relevance, Coherence, TaskAdherence];
+        EnsureAllSpecsValid(resolvedEvaluators, nameof(evaluators));
 
         var createEvalPayload = new WireCreateEvalRequest
         {
@@ -831,7 +997,13 @@ public sealed class FoundryEvals : IAgentEvaluator
                     passed = pp.ValueKind == JsonValueKind.True;
                 }
 
-                scores.Add(new EvalScoreResult(name, score, passed));
+                IReadOnlyList<RubricScore>? dimensions = null;
+                if (r.TryGetProperty("sample", out var perResultSample))
+                {
+                    dimensions = ParseRubricScores(perResultSample);
+                }
+
+                scores.Add(new EvalScoreResult(name, score, passed) { Dimensions = dimensions });
             }
         }
 
@@ -917,20 +1089,202 @@ public sealed class FoundryEvals : IAgentEvaluator
         return result;
     }
 
-    internal static string[] FilterToolEvaluators(string[] evaluators, bool hasTools)
+    private static readonly string[] s_rubricDimensionKeys = ["dimension_scores", "rubric_scores"];
+
+    /// <summary>
+    /// Extracts the per-dimension <see cref="RubricScore"/> list from a result-level <c>sample</c>
+    /// payload, when present. Accepts several legacy/canonical shapes for forward compatibility
+    /// with provider SDK changes:
+    /// </summary>
+    /// <remarks>
+    /// <list type="bullet">
+    /// <item>
+    /// <description><c>sample.properties.dimension_scores</c> (canonical Foundry shape).</description>
+    /// </item>
+    /// <item>
+    /// <description><c>sample.properties.rubric_scores</c> (preview / legacy key).</description>
+    /// </item>
+    /// <item>
+    /// <description>Top-level <c>sample.dimension_scores</c> / <c>sample.rubric_scores</c> as a
+    /// defensive fallback.</description>
+    /// </item>
+    /// </list>
+    /// Returns <see langword="null"/> when no rubric scores are present (the evaluator was not
+    /// a rubric evaluator). Malformed entries (missing <c>id</c>, <c>weight</c>, or <c>applicable</c>)
+    /// are skipped without failing the whole list.
+    /// </remarks>
+    internal static List<RubricScore>? ParseRubricScores(JsonElement sample)
+    {
+        if (sample.ValueKind != JsonValueKind.Object)
+        {
+            return null;
+        }
+
+        // Prefer sample.properties.<key> then fall back to top-level sample.<key>.
+        if (sample.TryGetProperty("properties", out var properties)
+            && properties.ValueKind == JsonValueKind.Object)
+        {
+            foreach (var key in s_rubricDimensionKeys)
+            {
+                if (properties.TryGetProperty(key, out var raw))
+                {
+                    var parsed = ParseDimensionEntries(raw);
+                    if (parsed.Count > 0)
+                    {
+                        return parsed;
+                    }
+                }
+            }
+        }
+
+        foreach (var key in s_rubricDimensionKeys)
+        {
+            if (sample.TryGetProperty(key, out var raw))
+            {
+                var parsed = ParseDimensionEntries(raw);
+                if (parsed.Count > 0)
+                {
+                    return parsed;
+                }
+            }
+        }
+
+        return null;
+    }
+
+    private static List<RubricScore> ParseDimensionEntries(JsonElement raw)
+    {
+        var parsed = new List<RubricScore>();
+        if (raw.ValueKind != JsonValueKind.Array)
+        {
+            return parsed;
+        }
+
+        foreach (var entry in raw.EnumerateArray())
+        {
+            if (entry.ValueKind != JsonValueKind.Object)
+            {
+                continue;
+            }
+
+            if (!entry.TryGetProperty("id", out var idProp)
+                || !entry.TryGetProperty("weight", out var weightProp)
+                || !entry.TryGetProperty("applicable", out var applicableProp))
+            {
+                continue;
+            }
+
+            string? id = idProp.ValueKind switch
+            {
+                JsonValueKind.String => idProp.GetString(),
+                JsonValueKind.Number => idProp.GetRawText(),
+                _ => null,
+            };
+            if (string.IsNullOrEmpty(id))
+            {
+                continue;
+            }
+
+            if (weightProp.ValueKind != JsonValueKind.Number
+                || !weightProp.TryGetInt32(out var weight))
+            {
+                continue;
+            }
+
+            if (applicableProp.ValueKind is not (JsonValueKind.True or JsonValueKind.False))
+            {
+                continue;
+            }
+
+            int? score = null;
+            if (entry.TryGetProperty("score", out var scoreProp)
+                && scoreProp.ValueKind == JsonValueKind.Number)
+            {
+                if (scoreProp.TryGetInt32(out var intScore))
+                {
+                    score = intScore;
+                }
+                else if (scoreProp.TryGetDouble(out var doubleScore))
+                {
+                    score = (int)doubleScore;
+                }
+            }
+
+            string reason = entry.TryGetProperty("reason", out var reasonProp)
+                && reasonProp.ValueKind == JsonValueKind.String
+                ? reasonProp.GetString() ?? string.Empty
+                : string.Empty;
+
+            parsed.Add(new RubricScore(
+                Id: id!,
+                Score: score,
+                Applicable: applicableProp.ValueKind == JsonValueKind.True,
+                Weight: weight,
+                Reason: reason));
+        }
+
+        return parsed;
+    }
+
+    internal static FoundryEvaluatorSpec[] FilterToolEvaluators(FoundryEvaluatorSpec[] evaluators, bool hasTools)
     {
         if (hasTools)
         {
             return evaluators;
         }
 
-        var filtered = Array.FindAll(evaluators, e =>
-            !FoundryEvalConverter.ToolEvaluators.Contains(FoundryEvalConverter.ResolveEvaluator(e)));
+        var filtered = Array.FindAll(evaluators, spec =>
+        {
+            if (spec.IsRubric)
+            {
+                // Rubric refs are tool-aware but not tool-required; preserve them.
+                return true;
+            }
+
+            return !FoundryEvalConverter.ToolEvaluators.Contains(FoundryEvalConverter.ResolveEvaluator(spec.BuiltinName!));
+        });
 
         return filtered.Length > 0
             ? filtered
             : throw new ArgumentException(
                 "All configured evaluators require tool definitions, but no tool calls were found in the eval items. "
-                + $"Tool evaluators: {string.Join(", ", evaluators)}. Either add tool call content to your EvalItems or remove tool-type evaluators.");
+                + $"Tool evaluators: {string.Join(", ", evaluators.Select(e => e.ToString()))}. Either add tool call content to your EvalItems or remove tool-type evaluators.");
+    }
+
+    /// <summary>
+    /// Validates every spec in <paramref name="evaluators"/> — defensively guards against
+    /// <c>default(FoundryEvaluatorSpec)</c> values that would otherwise NRE deep in the
+    /// dispatch pipeline (e.g. on <c>spec.BuiltinName!</c>).
+    /// </summary>
+    internal static void EnsureAllSpecsValid(FoundryEvaluatorSpec[] evaluators, string paramName)
+    {
+        for (int i = 0; i < evaluators.Length; i++)
+        {
+            if (!evaluators[i].IsValid)
+            {
+                throw new ArgumentException(
+                    $"Invalid {nameof(FoundryEvaluatorSpec)} at index {i}: must be constructed with either a built-in " +
+                    $"evaluator name or a {nameof(GeneratedEvaluatorRef)}. The default struct value is not a valid spec.",
+                    paramName);
+            }
+        }
+    }
+
+    private static bool HasToolEvaluator(FoundryEvaluatorSpec[] evaluators)
+    {
+        foreach (var spec in evaluators)
+        {
+            if (spec.IsRubric)
+            {
+                continue;
+            }
+
+            if (FoundryEvalConverter.ToolEvaluators.Contains(FoundryEvalConverter.ResolveEvaluator(spec.BuiltinName!)))
+            {
+                return true;
+            }
+        }
+
+        return false;
     }
 }

dotnet/src/Microsoft.Agents.AI.Foundry/Evaluation/FoundryEvaluatorSpec.cs

@@ -0,0 +1,118 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+
+namespace Microsoft.Agents.AI.Foundry;
+
+/// <summary>
+/// Specifies a single evaluator for a <see cref="FoundryEvals"/> run — either a built-in
+/// Foundry evaluator (referenced by short or fully-qualified name) or a pre-existing rubric
+/// evaluator (referenced by <see cref="GeneratedEvaluatorRef"/>).
+/// </summary>
+/// <remarks>
+/// <para>
+/// Both <see cref="string"/> and <see cref="GeneratedEvaluatorRef"/> are implicitly convertible
+/// to <see cref="FoundryEvaluatorSpec"/>, so call sites can mix the two:
+/// </para>
+/// <code>
+/// var evals = new FoundryEvals(
+///     projectClient,
+///     "gpt-4o-mini",
+///     new GeneratedEvaluatorRef("policy-rubric", Version: "3"),
+///     FoundryEvals.Relevance,
+///     FoundryEvals.Coherence);
+/// </code>
+/// </remarks>
+public readonly struct FoundryEvaluatorSpec : IEquatable<FoundryEvaluatorSpec>
+{
+    private FoundryEvaluatorSpec(string? builtinName, GeneratedEvaluatorRef? generatedRef)
+    {
+        this.BuiltinName = builtinName;
+        this.GeneratedRef = generatedRef;
+    }
+
+    /// <summary>
+    /// Initializes a new <see cref="FoundryEvaluatorSpec"/> for a built-in evaluator by name
+    /// (for example <c>"relevance"</c> or <c>"builtin.relevance"</c>).
+    /// </summary>
+    /// <param name="builtinName">Built-in evaluator name.</param>
+    public FoundryEvaluatorSpec(string builtinName)
+        : this(builtinName ?? throw new ArgumentNullException(nameof(builtinName)), null)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new <see cref="FoundryEvaluatorSpec"/> for a generated rubric evaluator
+    /// previously registered with the provider.
+    /// </summary>
+    /// <param name="generatedRef">Reference to the rubric evaluator.</param>
+    public FoundryEvaluatorSpec(GeneratedEvaluatorRef generatedRef)
+        : this(null, generatedRef ?? throw new ArgumentNullException(nameof(generatedRef)))
+    {
+    }
+
+    /// <summary>Gets the built-in evaluator name, or <see langword="null"/> when this is a rubric reference.</summary>
+    public string? BuiltinName { get; }
+
+    /// <summary>Gets the rubric reference, or <see langword="null"/> when this is a built-in evaluator.</summary>
+    public GeneratedEvaluatorRef? GeneratedRef { get; }
+
+    /// <summary>Gets whether this spec references a built-in evaluator.</summary>
+    public bool IsBuiltin => this.BuiltinName is not null;
+
+    /// <summary>Gets whether this spec references a generated rubric evaluator.</summary>
+    public bool IsRubric => this.GeneratedRef is not null;
+
+    /// <summary>Gets whether this spec is valid (i.e. references either a built-in or a rubric).</summary>
+    /// <remarks>
+    /// Because <see cref="FoundryEvaluatorSpec"/> is a struct, <c>default(FoundryEvaluatorSpec)</c>
+    /// is a syntactically-valid but semantically-invalid value (both <see cref="BuiltinName"/> and
+    /// <see cref="GeneratedRef"/> are <see langword="null"/>). Call <see cref="EnsureValid"/> at
+    /// API boundaries to fail fast instead of NRE-ing later.
+    /// </remarks>
+    public bool IsValid => this.BuiltinName is not null || this.GeneratedRef is not null;
+
+    /// <summary>Validates that this spec references either a built-in evaluator or a rubric.</summary>
+    /// <param name="paramName">Parameter name used in the thrown <see cref="ArgumentException"/>.</param>
+    /// <exception cref="ArgumentException">Thrown when neither <see cref="BuiltinName"/> nor <see cref="GeneratedRef"/> is set.</exception>
+    public void EnsureValid(string? paramName = null)
+    {
+        if (!this.IsValid)
+        {
+            throw new ArgumentException(
+                $"Invalid {nameof(FoundryEvaluatorSpec)}: must be constructed with either a built-in evaluator name " +
+                $"or a {nameof(GeneratedEvaluatorRef)}. The default struct value is not a valid spec.",
+                paramName);
+        }
+    }
+
+    /// <summary>Implicit conversion from a built-in evaluator name.</summary>
+    public static implicit operator FoundryEvaluatorSpec(string builtinName) => new(builtinName);
+
+    /// <summary>Implicit conversion from a <see cref="GeneratedEvaluatorRef"/>.</summary>
+    public static implicit operator FoundryEvaluatorSpec(GeneratedEvaluatorRef generatedRef) => new(generatedRef);
+
+    /// <inheritdoc/>
+    public bool Equals(FoundryEvaluatorSpec other)
+        => this.BuiltinName == other.BuiltinName
+            && Equals(this.GeneratedRef, other.GeneratedRef);
+
+    /// <inheritdoc/>
+    public override bool Equals(object? obj) => obj is FoundryEvaluatorSpec other && this.Equals(other);
+
+    /// <inheritdoc/>
+    public override int GetHashCode()
+        => HashCode.Combine(this.BuiltinName, this.GeneratedRef);
+
+    /// <summary>Equality operator.</summary>
+    public static bool operator ==(FoundryEvaluatorSpec left, FoundryEvaluatorSpec right) => left.Equals(right);
+
+    /// <summary>Inequality operator.</summary>
+    public static bool operator !=(FoundryEvaluatorSpec left, FoundryEvaluatorSpec right) => !left.Equals(right);
+
+    /// <inheritdoc/>
+    public override string ToString()
+        => this.IsRubric
+            ? $"GeneratedEvaluatorRef({this.GeneratedRef!.Name}@{this.GeneratedRef.Version ?? "latest"})"
+            : this.BuiltinName ?? "<empty>";
+}

dotnet/src/Microsoft.Agents.AI.Harness/HarnessAgent.cs

@@ -57,8 +57,9 @@ namespace Microsoft.Agents.AI;
 /// <para>
 /// <strong>Agent decorators (each enabled by default, individually disableable):</strong>
 /// <list type="bullet">
-/// <item><description><see cref="ToolApprovalAgent"/> — "don't ask again" tool approval rules enabling safe unattended execution. Disable with <see cref="HarnessAgentOptions.DisableToolApproval"/>.</description></item>
+/// <item><description><see cref="ToolApprovalAgent"/> — "don't ask again" tool approval rules enabling safe unattended execution. Disable with <see cref="HarnessAgentOptions.DisableToolAutoApproval"/>.</description></item>
 /// <item><description><see cref="OpenTelemetryAgent"/> — OpenTelemetry instrumentation following semantic conventions for generative AI. Disable with <see cref="HarnessAgentOptions.DisableOpenTelemetry"/>.</description></item>
+/// <item><description><see cref="LoopAgent"/> — re-invokes the agent until the configured evaluators are satisfied. Applied as the outermost decorator (so each iteration is a complete agent run) and only when <see cref="HarnessAgentOptions.LoopEvaluators"/> supplies at least one evaluator; otherwise omitted.</description></item>
 /// </list>
 /// </para>
 /// <para>
@@ -142,7 +143,19 @@ public sealed class HarnessAgent : DelegatingAIAgent
 
         AIAgentBuilder builder = innerAgent.AsBuilder();
 
-        if (options?.DisableToolApproval is not true)
+        // Register the loop decorator first so it ends up outermost (AIAgentBuilder applies factories in reverse): the
+        // loop drives complete agent runs, each independently tool-approved and OpenTelemetry-traced. Only added when at
+        // least one evaluator is supplied; otherwise the agent behaves as a single-shot agent.
+        if (options?.LoopEvaluators is IEnumerable<LoopEvaluator> loopEvaluators)
+        {
+            List<LoopEvaluator> evaluatorList = loopEvaluators.ToList();
+            if (evaluatorList.Count > 0)
+            {
+                builder.Use((inner, _) => new LoopAgent(inner, evaluatorList, options.LoopAgentOptions, loggerFactory));
+            }
+        }
+
+        if (options?.DisableToolAutoApproval is not true)
         {
             builder.UseToolApproval(options?.ToolApprovalAgentOptions);
         }

dotnet/src/Microsoft.Agents.AI.Harness/HarnessAgentOptions.cs

@@ -146,6 +146,33 @@ public sealed class HarnessAgentOptions
     /// </remarks>
     public IEnumerable<AIContextProvider>? AIContextProviders { get; set; }
 
+    /// <summary>
+    /// Gets or sets the ordered collection of <see cref="LoopEvaluator"/> instances that, when supplied, cause the
+    /// <see cref="HarnessAgent"/> to be wrapped in a <see cref="LoopAgent"/> decorator.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// When this collection is non-<see langword="null"/> and contains at least one evaluator, the harness agent is
+    /// wrapped in a <see cref="LoopAgent"/> that re-invokes the agent until the evaluators are satisfied. The loop is
+    /// applied as the outermost decorator, so each iteration is a complete agent run (including tool approval and
+    /// OpenTelemetry instrumentation).
+    /// </para>
+    /// <para>
+    /// When <see langword="null"/> or empty (the default), no <see cref="LoopAgent"/> is added and the agent behaves
+    /// as a single-shot agent.
+    /// </para>
+    /// </remarks>
+    public IEnumerable<LoopEvaluator>? LoopEvaluators { get; set; }
+
+    /// <summary>
+    /// Gets or sets optional configuration for the <see cref="LoopAgent"/> created from <see cref="LoopEvaluators"/>.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="null"/>, the <see cref="LoopAgent"/> uses its default settings. This property is ignored
+    /// when <see cref="LoopEvaluators"/> is <see langword="null"/> or empty.
+    /// </remarks>
+    public LoopAgentOptions? LoopAgentOptions { get; set; }
+
     /// <summary>
     /// Gets or sets the maximum number of function-invocation loop iterations per request.
     /// </summary>
@@ -156,20 +183,22 @@ public sealed class HarnessAgentOptions
     public int? MaximumIterationsPerRequest { get; set; }
 
     /// <summary>
-    /// Gets or sets a value indicating whether the <see cref="ToolApprovalAgent"/> wrapper is disabled.
+    /// Gets or sets a value indicating whether the <see cref="ToolApprovalAgent"/> auto-approval middleware is disabled.
     /// </summary>
     /// <remarks>
-    /// When <see langword="false"/> (the default), the agent is wrapped with tool approval middleware
-    /// that supports "don't ask again" auto-approval rules.
+    /// This disables the tool auto-approval functionality only, keeping the tool approval flow requiring approval (for example,
+    /// <see cref="ApprovalRequiredAIFunction"/> tools). This setting controls whether the agent is wrapped with the
+    /// <see cref="ToolApprovalAgent"/> middleware that supports "don't ask again" and auto-approval rules.
+    /// When <see langword="false"/> (the default), the middleware is added.
     /// </remarks>
-    public bool DisableToolApproval { get; set; }
+    public bool DisableToolAutoApproval { get; set; }
 
     /// <summary>
     /// Gets or sets the options for the <see cref="ToolApprovalAgent"/> middleware.
     /// </summary>
     /// <remarks>
     /// When <see langword="null"/>, the <see cref="ToolApprovalAgent"/> uses default settings.
-    /// This property has no effect when <see cref="DisableToolApproval"/> is <see langword="true"/>.
+    /// This property has no effect when <see cref="DisableToolAutoApproval"/> is <see langword="true"/>.
     /// </remarks>
     public ToolApprovalAgentOptions? ToolApprovalAgentOptions { get; set; }
 

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/BuiltInFunctions.cs

@@ -20,6 +20,8 @@ internal static class BuiltInFunctions
 {
     internal const string HttpPrefix = "http-";
     internal const string McpToolPrefix = "mcptool-";
+    internal const string StatusFunctionSuffix = "-status";
+    internal const string RespondFunctionSuffix = "-respond";
 
     private const string WaitForResponseHeaderName = "x-ms-wait-for-response";
 
@@ -90,7 +92,7 @@ internal static class BuiltInFunctions
         }
 
         OrchestrationMetadata? metadata = await client.GetInstanceAsync(runId, getInputsAndOutputs: true);
-        if (metadata is null)
+        if (metadata is null || !IsOrchestrationOwnedByWorkflow(metadata.Name, context.FunctionDefinition.Name, StatusFunctionSuffix))
         {
             return await CreateErrorResponseAsync(req, context, HttpStatusCode.NotFound, $"Workflow run '{runId}' not found.");
         }
@@ -146,7 +148,7 @@ internal static class BuiltInFunctions
 
         // Verify the orchestration exists and is in a valid state
         OrchestrationMetadata? metadata = await client.GetInstanceAsync(runId, getInputsAndOutputs: true);
-        if (metadata is null)
+        if (metadata is null || !IsOrchestrationOwnedByWorkflow(metadata.Name, context.FunctionDefinition.Name, RespondFunctionSuffix))
         {
             return await CreateErrorResponseAsync(req, context, HttpStatusCode.NotFound, $"Workflow run '{runId}' not found.");
         }
@@ -363,9 +365,10 @@ internal static class BuiltInFunctions
 
         string agentName = context.Name;
 
-        // Derive session id: try to parse provided threadId, otherwise create a new one.
+        // Bind the caller-supplied threadId as a session key under the current agent name,
+        // mirroring the behavior of RunAgentHttpAsync.
         AgentSessionId sessionId = context.Arguments.TryGetValue("threadId", out object? threadObj) && threadObj is string threadId && !string.IsNullOrWhiteSpace(threadId)
-            ? AgentSessionId.Parse(threadId)
+            ? new AgentSessionId(agentName, threadId)
             : new AgentSessionId(agentName, functionContext.InvocationId);
 
         AIAgent agentProxy = client.AsDurableAgentProxy(functionContext, agentName);
@@ -654,6 +657,39 @@ internal static class BuiltInFunctions
         return functionName[HttpPrefix.Length..];
     }
 
+    /// <summary>
+    /// Extracts the workflow name from the function definition name by stripping the
+    /// <see cref="HttpPrefix"/> and the given suffix (e.g., "-status" or "-respond").
+    /// </summary>
+    internal static string GetWorkflowName(string functionName, string suffix)
+    {
+        if (!functionName.StartsWith(HttpPrefix, StringComparison.Ordinal) ||
+            !functionName.EndsWith(suffix, StringComparison.Ordinal))
+        {
+            throw new InvalidOperationException(
+                $"Built-in HTTP trigger function name '{functionName}' does not match the expected pattern '{HttpPrefix}<workflowName>{suffix}'.");
+        }
+
+        return functionName[HttpPrefix.Length..^suffix.Length];
+    }
+
+    /// <summary>
+    /// Returns true if the orchestration name matches the expected orchestration for the
+    /// workflow derived from the given function name and suffix.
+    /// </summary>
+    internal static bool IsOrchestrationOwnedByWorkflow(string orchestrationName, string functionName, string suffix)
+    {
+        if (!functionName.StartsWith(HttpPrefix, StringComparison.Ordinal) ||
+            !functionName.EndsWith(suffix, StringComparison.Ordinal))
+        {
+            return false;
+        }
+
+        string workflowName = GetWorkflowName(functionName, suffix);
+        string expectedOrchestrationName = WorkflowNamingHelper.ToOrchestrationFunctionName(workflowName);
+        return string.Equals(orchestrationName, expectedOrchestrationName, StringComparison.OrdinalIgnoreCase);
+    }
+
     /// <summary>
     /// Represents a request to run an agent.
     /// </summary>

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+- Scope workflow status/respond endpoints to the route workflow name ([#6608](https://github.com/microsoft/agent-framework/pull/6608))
+- Bind MCP threadId to the current agent and guard cross-agent session dispatch ([#6531](https://github.com/microsoft/agent-framework/pull/6531))
 - Support returning workflow results from HTTP trigger endpoint ([#5321](https://github.com/microsoft/agent-framework/pull/5321))
 - Added MCP tool trigger support for durable workflows ([#4768](https://github.com/microsoft/agent-framework/pull/4768))
 - Added Azure Functions hosting support for durable workflows ([#4436](https://github.com/microsoft/agent-framework/pull/4436))

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/Workflows/DurableWorkflowsFunctionMetadataTransformer.cs

@@ -89,7 +89,7 @@ internal sealed class DurableWorkflowsFunctionMetadataTransformer : IFunctionMet
             // Register a status endpoint if opted in via AddWorkflow(exposeStatusEndpoint: true).
             if (this._options.IsStatusEndpointEnabled(workflow.Key))
             {
-                string statusFunctionName = $"{BuiltInFunctions.HttpPrefix}{workflow.Key}-status";
+                string statusFunctionName = $"{BuiltInFunctions.HttpPrefix}{workflow.Key}{BuiltInFunctions.StatusFunctionSuffix}";
                 if (registeredFunctions.Add(statusFunctionName))
                 {
                     this._logger.LogRegisteringWorkflowTrigger(workflow.Key, statusFunctionName, "http-status");
@@ -105,7 +105,7 @@ internal sealed class DurableWorkflowsFunctionMetadataTransformer : IFunctionMet
             bool hasRequestPorts = workflow.Value.ReflectExecutors().Values.Any(b => b is RequestPortBinding);
             if (hasRequestPorts)
             {
-                string respondFunctionName = $"{BuiltInFunctions.HttpPrefix}{workflow.Key}-respond";
+                string respondFunctionName = $"{BuiltInFunctions.HttpPrefix}{workflow.Key}{BuiltInFunctions.RespondFunctionSuffix}";
                 if (registeredFunctions.Add(respondFunctionName))
                 {
                     this._logger.LogRegisteringWorkflowTrigger(workflow.Key, respondFunctionName, "http-respond");

dotnet/src/Microsoft.Agents.AI.LocalCodeAct/CodeValidationException.cs

@@ -0,0 +1,29 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+
+namespace Microsoft.Agents.AI.LocalCodeAct;
+
+/// <summary>
+/// Exception thrown when AST validation of generated Python code fails.
+/// </summary>
+public sealed class CodeValidationException : Exception
+{
+    /// <summary>Initializes a new instance of the <see cref="CodeValidationException"/> class.</summary>
+    public CodeValidationException()
+    {
+    }
+
+    /// <summary>Initializes a new instance of the <see cref="CodeValidationException"/> class.</summary>
+    /// <param name="message">Validation error message.</param>
+    public CodeValidationException(string message) : base(message)
+    {
+    }
+
+    /// <summary>Initializes a new instance of the <see cref="CodeValidationException"/> class.</summary>
+    /// <param name="message">Validation error message.</param>
+    /// <param name="innerException">Underlying exception.</param>
+    public CodeValidationException(string message, Exception innerException) : base(message, innerException)
+    {
+    }
+}

dotnet/src/Microsoft.Agents.AI.LocalCodeAct/FileMount.cs

@@ -0,0 +1,64 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI.LocalCodeAct;
+
+/// <summary>
+/// File mount access mode.
+/// </summary>
+public enum FileMountMode
+{
+    /// <summary>Read-only access. Files are not scanned for capture after execution.</summary>
+    ReadOnly,
+
+    /// <summary>Read-write access. New or modified files are captured after execution.</summary>
+    ReadWrite,
+}
+
+/// <summary>
+/// Represents a host directory exposed to locally executed code.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Unlike a true sandbox, mounts in this package expose <see cref="HostPath"/>
+/// directly to the subprocess. The <see cref="MountPath"/> is metadata used to
+/// describe the mount to the model in the function description and to label
+/// captured files. Real isolation must come from the surrounding sandbox
+/// (container, VM, Foundry hosted agent, etc.).
+/// </para>
+/// </remarks>
+public sealed class FileMount
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FileMount"/> class.
+    /// </summary>
+    /// <param name="hostPath">Path on the host filesystem to expose to the subprocess. Must exist.</param>
+    /// <param name="mountPath">
+    /// Logical path used to describe the mount to the model (for example <c>"/input/data.csv"</c>).
+    /// </param>
+    /// <param name="mode">Access mode for the mount. Defaults to <see cref="FileMountMode.ReadWrite"/>.</param>
+    /// <param name="writeBytesLimit">
+    /// Optional per-mount write capture limit (in bytes). When <see langword="null"/>, the global
+    /// <see cref="ProcessExecutionLimits.MaxCapturedFileBytes"/> applies.
+    /// </param>
+    public FileMount(string hostPath, string mountPath, FileMountMode mode = FileMountMode.ReadWrite, long? writeBytesLimit = null)
+    {
+        this.HostPath = Throw.IfNullOrWhitespace(hostPath);
+        this.MountPath = Throw.IfNullOrWhitespace(mountPath);
+        this.Mode = mode;
+        this.WriteBytesLimit = writeBytesLimit;
+    }
+
+    /// <summary>Gets the host filesystem path exposed to the subprocess.</summary>
+    public string HostPath { get; }
+
+    /// <summary>Gets the logical mount path used to describe the mount to the model.</summary>
+    public string MountPath { get; }
+
+    /// <summary>Gets the access mode for the mount.</summary>
+    public FileMountMode Mode { get; }
+
+    /// <summary>Gets the optional per-mount write capture limit (in bytes).</summary>
+    public long? WriteBytesLimit { get; }
+}

dotnet/src/Microsoft.Agents.AI.LocalCodeAct/Internal/CodeExecutor.cs

@@ -0,0 +1,107 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.LocalCodeAct.Internal;
+
+/// <summary>
+/// Coordinates a single execution: optional validation, snapshot of writable mounts,
+/// running the subprocess, capturing written files, and assembling the final content list.
+/// </summary>
+internal sealed class CodeExecutor
+{
+    private readonly string _pythonExecutable;
+    private readonly string _runnerScript;
+    private readonly CodeValidator? _validator;
+    private readonly ProcessExecutionLimits _limits;
+    private readonly IReadOnlyDictionary<string, string>? _environment;
+    private readonly string? _workingDirectory;
+
+    public CodeExecutor(
+        string pythonExecutable,
+        string runnerScript,
+        CodeValidator? validator,
+        ProcessExecutionLimits limits,
+        IReadOnlyDictionary<string, string>? environment,
+        string? workingDirectory)
+    {
+        this._pythonExecutable = pythonExecutable;
+        this._runnerScript = runnerScript;
+        this._validator = validator;
+        this._limits = limits;
+        this._environment = environment;
+        this._workingDirectory = workingDirectory;
+    }
+
+    /// <summary>Immutable snapshot of provider state captured at the start of an invocation.</summary>
+    public sealed class RunSnapshot
+    {
+        public RunSnapshot(IReadOnlyList<AIFunction> tools, IReadOnlyList<FileMount> fileMounts)
+        {
+            this.Tools = tools;
+            this.FileMounts = fileMounts;
+        }
+
+        public IReadOnlyList<AIFunction> Tools { get; }
+
+        public IReadOnlyList<FileMount> FileMounts { get; }
+    }
+
+    public async Task<List<AIContent>> ExecuteAsync(RunSnapshot snapshot, string code, CancellationToken cancellationToken)
+    {
+        if (this._validator is not null)
+        {
+            await this._validator.ValidateAsync(code, cancellationToken).ConfigureAwait(false);
+        }
+
+        var preState = FileMountHelper.SnapshotWritableMounts(snapshot.FileMounts);
+
+        var bridge = new ProcessBridge(
+            this._pythonExecutable,
+            this._runnerScript,
+            snapshot.Tools,
+            this._limits,
+            this._environment,
+            this._workingDirectory);
+
+        var result = await bridge.RunAsync(code, cancellationToken).ConfigureAwait(false);
+
+        var captured = FileMountHelper.CaptureWrittenFiles(snapshot.FileMounts, preState, this._limits);
+
+        return BuildContents(result, captured);
+    }
+
+    private static List<AIContent> BuildContents(ProcessBridge.ExecutionResult result, List<AIContent> capturedFiles)
+    {
+        var contents = new List<AIContent>();
+
+        if (!string.IsNullOrEmpty(result.Stdout))
+        {
+            var stdoutText = result.StdoutTruncated ? result.Stdout + "\n[stdout truncated]" : result.Stdout;
+            contents.Add(new TextContent(stdoutText));
+        }
+
+        if (!string.IsNullOrEmpty(result.Stderr))
+        {
+            var stderrText = result.StderrTruncated ? result.Stderr + "\n[stderr truncated]" : result.Stderr;
+            contents.Add(new TextContent("stderr:\n" + stderrText));
+        }
+
+        if (result.OutputPresent && result.Output.HasValue)
+        {
+            contents.Add(new TextContent("result:\n" + result.Output.Value.GetRawText()));
+        }
+
+        contents.AddRange(capturedFiles);
+
+        if (contents.Count == 0)
+        {
+            contents.Add(new TextContent("Code executed successfully without output."));
+        }
+
+        return contents;
+    }
+}

dotnet/src/Microsoft.Agents.AI.LocalCodeAct/Internal/CodeValidator.cs

@@ -0,0 +1,178 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Linq;
+using System.Text;
+using System.Text.Json;
+using System.Text.Json.Nodes;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Microsoft.Agents.AI.LocalCodeAct.Internal;
+
+/// <summary>
+/// Runs the embedded Python AST validator in a child process with a strict timeout.
+/// </summary>
+internal sealed class CodeValidator
+{
+    private readonly string _pythonExecutable;
+    private readonly string _validatorScript;
+    private readonly TimeSpan _timeout;
+    private readonly IReadOnlyList<string>? _allowedImports;
+    private readonly IReadOnlyList<string>? _blockedImports;
+    private readonly IReadOnlyList<string>? _allowedBuiltins;
+    private readonly IReadOnlyList<string>? _blockedBuiltins;
+
+    public CodeValidator(
+        string pythonExecutable,
+        string validatorScript,
+        TimeSpan timeout,
+        IReadOnlyList<string>? allowedImports,
+        IReadOnlyList<string>? blockedImports,
+        IReadOnlyList<string>? allowedBuiltins,
+        IReadOnlyList<string>? blockedBuiltins)
+    {
+        this._pythonExecutable = pythonExecutable;
+        this._validatorScript = validatorScript;
+        this._timeout = timeout;
+        this._allowedImports = allowedImports;
+        this._blockedImports = blockedImports;
+        this._allowedBuiltins = allowedBuiltins;
+        this._blockedBuiltins = blockedBuiltins;
+    }
+
+    /// <summary>Validates Python source code against the configured allow-lists.</summary>
+    /// <exception cref="CodeValidationException">Thrown when validation fails.</exception>
+    public async Task ValidateAsync(string code, CancellationToken cancellationToken)
+    {
+        var request = new JsonObject
+        {
+            ["code"] = code,
+        };
+
+        AddList(request, "allowed_imports", this._allowedImports);
+        AddList(request, "blocked_imports", this._blockedImports);
+        AddList(request, "allowed_builtins", this._allowedBuiltins);
+        AddList(request, "blocked_builtins", this._blockedBuiltins);
+
+        var requestJson = request.ToJsonString();
+
+        var startInfo = new ProcessStartInfo
+        {
+            FileName = this._pythonExecutable,
+            UseShellExecute = false,
+            RedirectStandardInput = true,
+            RedirectStandardOutput = true,
+            RedirectStandardError = true,
+            CreateNoWindow = true,
+        };
+        startInfo.ArgumentList.Add("-I");
+        startInfo.ArgumentList.Add(this._validatorScript);
+
+        using var process = Process.Start(startInfo)
+            ?? throw new InvalidOperationException("Failed to start Python validator process.");
+
+        using var timeoutCts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+        timeoutCts.CancelAfter(this._timeout);
+
+        try
+        {
+            await process.StandardInput.WriteLineAsync(requestJson.AsMemory(), timeoutCts.Token).ConfigureAwait(false);
+            await process.StandardInput.FlushAsync(timeoutCts.Token).ConfigureAwait(false);
+            process.StandardInput.Close();
+
+            var stdoutTask = process.StandardOutput.ReadToEndAsync(timeoutCts.Token);
+            var stderrTask = process.StandardError.ReadToEndAsync(timeoutCts.Token);
+
+            await process.WaitForExitAsync(timeoutCts.Token).ConfigureAwait(false);
+
+            var stdout = await stdoutTask.ConfigureAwait(false);
+            var stderr = await stderrTask.ConfigureAwait(false);
+
+            if (process.ExitCode == 0)
+            {
+                return;
+            }
+
+            throw new CodeValidationException(ExtractError(stdout, stderr));
+        }
+        catch (OperationCanceledException) when (timeoutCts.IsCancellationRequested && !cancellationToken.IsCancellationRequested)
+        {
+            TryKill(process);
+            throw new CodeValidationException($"Code validation exceeded {this._timeout.TotalSeconds:F0} seconds.");
+        }
+        catch
+        {
+            TryKill(process);
+            throw;
+        }
+    }
+
+    private static string ExtractError(string output, string errorOutput)
+    {
+        if (string.IsNullOrWhiteSpace(output))
+        {
+            return string.IsNullOrWhiteSpace(errorOutput) ? "Code validation failed." : errorOutput;
+        }
+
+        try
+        {
+            using var doc = JsonDocument.Parse(output);
+            if (doc.RootElement.TryGetProperty("errors", out var errors) && errors.ValueKind == JsonValueKind.Array)
+            {
+                var sb = new StringBuilder();
+                foreach (var err in errors.EnumerateArray())
+                {
+                    if (sb.Length > 0)
+                    {
+                        sb.Append("; ");
+                    }
+
+                    sb.Append(err.ValueKind == JsonValueKind.String ? err.GetString() : err.ToString());
+                }
+
+                return sb.Length > 0 ? sb.ToString() : output;
+            }
+
+            if (doc.RootElement.TryGetProperty("message", out var message) && message.ValueKind == JsonValueKind.String)
+            {
+                return message.GetString() ?? output;
+            }
+        }
+        catch (JsonException)
+        {
+            // fall through
+        }
+
+        return output;
+    }
+
+    private static void TryKill(Process process)
+    {
+        try
+        {
+            if (!process.HasExited)
+            {
+                process.Kill(entireProcessTree: true);
+            }
+        }
+        catch
+        {
+#pragma warning disable CA1031 // Do not catch general exception types
+            // best-effort cleanup
+#pragma warning restore CA1031
+        }
+    }
+
+    private static void AddList(JsonObject obj, string key, IReadOnlyList<string>? values)
+    {
+        if (values is null)
+        {
+            return;
+        }
+
+        obj[key] = new JsonArray(values.Select(v => (JsonNode?)JsonValue.Create(v)).ToArray());
+    }
+}

dotnet/src/Microsoft.Agents.AI.LocalCodeAct/Internal/EmbeddedScripts.cs

@@ -0,0 +1,60 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.IO;
+
+namespace Microsoft.Agents.AI.LocalCodeAct.Internal;
+
+/// <summary>
+/// Extracts the embedded Python <c>runner.py</c> and <c>validator.py</c> scripts to a temporary
+/// directory and caches their paths for the lifetime of the process.
+/// </summary>
+internal static class EmbeddedScripts
+{
+    private static readonly object s_syncRoot = new();
+    private static string? s_runnerPath;
+    private static string? s_validatorPath;
+
+    /// <summary>Returns the path to the embedded <c>runner.py</c>, extracting it on first access.</summary>
+    public static string GetRunnerScriptPath() => GetOrExtract("runner.py", ref s_runnerPath);
+
+    /// <summary>Returns the path to the embedded <c>validator.py</c>, extracting it on first access.</summary>
+    public static string GetValidatorScriptPath() => GetOrExtract("validator.py", ref s_validatorPath);
+
+    private static string GetOrExtract(string fileName, ref string? cached)
+    {
+        if (cached is not null && File.Exists(cached))
+        {
+            return cached;
+        }
+
+        lock (s_syncRoot)
+        {
+            if (cached is not null && File.Exists(cached))
+            {
+                return cached;
+            }
+
+            var path = Extract(fileName);
+            cached = path;
+            return path;
+        }
+    }
+
+    private static string Extract(string fileName)
+    {
+        var assembly = typeof(EmbeddedScripts).Assembly;
+        var resourceName = $"Microsoft.Agents.AI.LocalCodeAct.Resources.{fileName}";
+
+        using var stream = assembly.GetManifestResourceStream(resourceName)
+            ?? throw new InvalidOperationException($"Embedded resource '{resourceName}' not found.");
+
+        var dir = Path.Combine(Path.GetTempPath(), "agentframework-localcodeact-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(dir);
+        var path = Path.Combine(dir, fileName);
+
+        using var fileStream = File.Create(path);
+        stream.CopyTo(fileStream);
+        return path;
+    }
+}

dotnet/src/Microsoft.Agents.AI.LocalCodeAct/Internal/ExecuteCodeFunction.cs

@@ -0,0 +1,51 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.ComponentModel;
+using System.Text.Json;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.LocalCodeAct.Internal;
+
+/// <summary>
+/// Run-scoped <see cref="AIFunction"/> that exposes <c>execute_code</c> to the model.
+/// </summary>
+internal sealed class ExecuteCodeFunction : AIFunction
+{
+    private const string ExecuteCodeName = "execute_code";
+
+    private readonly CodeExecutor _executor;
+    private readonly CodeExecutor.RunSnapshot _snapshot;
+    private readonly AIFunction _inner;
+
+    public ExecuteCodeFunction(CodeExecutor executor, CodeExecutor.RunSnapshot snapshot, string description)
+    {
+        this._executor = executor;
+        this._snapshot = snapshot;
+        this._inner = AIFunctionFactory.Create(
+            this.ExecuteCodeAsync,
+            new AIFunctionFactoryOptions
+            {
+                Name = ExecuteCodeName,
+                Description = description,
+            });
+    }
+
+    public override string Name => this._inner.Name;
+
+    public override string Description => this._inner.Description;
+
+    public override JsonElement JsonSchema => this._inner.JsonSchema;
+
+    protected override ValueTask<object?> InvokeCoreAsync(AIFunctionArguments arguments, CancellationToken cancellationToken) =>
+        this._inner.InvokeAsync(arguments, cancellationToken);
+
+    private async ValueTask<object?> ExecuteCodeAsync(
+        [Description("Python source code to execute locally in the agent environment.")] string code,
+        CancellationToken cancellationToken)
+        => string.IsNullOrWhiteSpace(code)
+            ? throw new ArgumentException("Parameter 'code' must not be empty.", nameof(code))
+            : await this._executor.ExecuteAsync(this._snapshot, code, cancellationToken).ConfigureAwait(false);
+}

dotnet/src/Microsoft.Agents.AI.LocalCodeAct/Internal/FileMountHelper.cs

@@ -0,0 +1,270 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.LocalCodeAct.Internal;
+
+/// <summary>
+/// Filesystem helpers for read-write mount snapshotting and capture.
+/// </summary>
+internal static class FileMountHelper
+{
+    /// <summary>Normalizes and validates a mount path (must be a clean absolute POSIX-style path).</summary>
+    public static string NormalizeMountPath(string mountPath)
+    {
+        if (string.IsNullOrWhiteSpace(mountPath))
+        {
+            throw new ArgumentException("Mount path must not be empty.", nameof(mountPath));
+        }
+
+        var raw = mountPath.Trim().Replace('\\', '/');
+        var parts = raw.Split('/', StringSplitOptions.RemoveEmptyEntries)
+            .Where(p => p != ".")
+            .ToList();
+
+        if (parts.Any(p => p == ".."))
+        {
+            throw new ArgumentException("Mount path must not contain '..' segments.", nameof(mountPath));
+        }
+
+        if (parts.Count == 0)
+        {
+            throw new ArgumentException("Mount path must point to a concrete absolute path.", nameof(mountPath));
+        }
+
+        return "/" + string.Join("/", parts);
+    }
+
+    /// <summary>
+    /// Validates a FileMount and returns a normalized copy (resolved host path, normalized mount path).
+    /// </summary>
+    public static FileMount Normalize(FileMount mount)
+    {
+        if (mount is null)
+        {
+            throw new ArgumentNullException(nameof(mount));
+        }
+
+        if (string.IsNullOrWhiteSpace(mount.HostPath))
+        {
+            throw new ArgumentException("HostPath must not be empty.", nameof(mount));
+        }
+
+        var fullHost = Path.GetFullPath(mount.HostPath);
+        if (!Directory.Exists(fullHost) && !File.Exists(fullHost))
+        {
+            throw new DirectoryNotFoundException($"FileMount host path '{mount.HostPath}' does not exist.");
+        }
+
+        if (mount.WriteBytesLimit.HasValue && mount.WriteBytesLimit.Value < 0)
+        {
+            throw new ArgumentException("WriteBytesLimit must be non-negative when set.", nameof(mount));
+        }
+
+        return new FileMount(fullHost, NormalizeMountPath(mount.MountPath), mount.Mode, mount.WriteBytesLimit);
+    }
+
+    /// <summary>Snapshot of (size, last-write-time ticks) per relative path under a writable mount.</summary>
+    public sealed class MountSnapshot
+    {
+        public MountSnapshot(IReadOnlyDictionary<string, (long Size, long Ticks)> files)
+        {
+            this.Files = files;
+        }
+
+        public IReadOnlyDictionary<string, (long Size, long Ticks)> Files { get; }
+    }
+
+    /// <summary>Captures the current file inventory of read-write mounts before execution.</summary>
+    public static Dictionary<string, MountSnapshot> SnapshotWritableMounts(IReadOnlyList<FileMount> mounts)
+    {
+        var snapshot = new Dictionary<string, MountSnapshot>(StringComparer.Ordinal);
+
+        foreach (var mount in mounts)
+        {
+            if (mount.Mode != FileMountMode.ReadWrite)
+            {
+                continue;
+            }
+
+            var root = new DirectoryInfo(mount.HostPath);
+            if (!root.Exists)
+            {
+                snapshot[mount.MountPath] = new MountSnapshot(new Dictionary<string, (long, long)>());
+                continue;
+            }
+
+            var files = new Dictionary<string, (long Size, long Ticks)>(StringComparer.Ordinal);
+            foreach (var file in EnumerateRealFiles(root))
+            {
+                var rel = MakeRelative(root.FullName, file.FullName);
+                files[rel] = (file.Length, file.LastWriteTimeUtc.Ticks);
+            }
+
+            snapshot[mount.MountPath] = new MountSnapshot(files);
+        }
+
+        return snapshot;
+    }
+
+    /// <summary>Captures files that were created or modified in read-write mounts since the snapshot was taken.</summary>
+    public static List<AIContent> CaptureWrittenFiles(
+        IReadOnlyList<FileMount> mounts,
+        IReadOnlyDictionary<string, MountSnapshot> preState,
+        ProcessExecutionLimits limits)
+    {
+        var captured = new List<AIContent>();
+        long totalBytes = 0;
+
+        foreach (var mount in mounts)
+        {
+            if (mount.Mode != FileMountMode.ReadWrite)
+            {
+                continue;
+            }
+
+            var root = new DirectoryInfo(mount.HostPath);
+            if (!root.Exists)
+            {
+                continue;
+            }
+
+            preState.TryGetValue(mount.MountPath, out var before);
+            var beforeFiles = before?.Files ?? new Dictionary<string, (long, long)>();
+            long mountBytes = 0;
+            var perMountLimit = mount.WriteBytesLimit ?? limits.MaxCapturedFileBytes;
+
+            foreach (var file in EnumerateRealFiles(root).OrderBy(f => f.FullName, StringComparer.Ordinal))
+            {
+                var rel = MakeRelative(root.FullName, file.FullName);
+                var current = (file.Length, file.LastWriteTimeUtc.Ticks);
+
+                if (beforeFiles.TryGetValue(rel, out var previous) && previous == current)
+                {
+                    continue;
+                }
+
+                var sandboxPath = mount.MountPath.TrimEnd('/') + "/" + rel;
+
+                if (file.Length > limits.MaxCapturedFileBytes)
+                {
+                    captured.Add(new TextContent($"[file {sandboxPath} omitted: exceeds per-file capture limit]"));
+                    continue;
+                }
+
+                if (mountBytes + file.Length > perMountLimit)
+                {
+                    captured.Add(new TextContent($"[file {sandboxPath} omitted: per-mount capture limit reached]"));
+                    continue;
+                }
+
+                if (totalBytes + file.Length > limits.MaxTotalCapturedFileBytes)
+                {
+                    captured.Add(new TextContent($"[file {sandboxPath} omitted: total capture limit reached]"));
+                    continue;
+                }
+
+                byte[] data;
+                try
+                {
+                    data = File.ReadAllBytes(file.FullName);
+                }
+                catch (IOException)
+                {
+                    continue;
+                }
+                catch (UnauthorizedAccessException)
+                {
+                    continue;
+                }
+
+                captured.Add(new DataContent(data, GuessMediaType(file.Name))
+                {
+                    AdditionalProperties = new AdditionalPropertiesDictionary
+                    {
+                        ["path"] = sandboxPath,
+                    },
+                });
+
+                mountBytes += file.Length;
+                totalBytes += file.Length;
+            }
+        }
+
+        return captured;
+    }
+
+    private static string MakeRelative(string root, string full)
+    {
+        var rel = Path.GetRelativePath(root, full);
+        return rel.Replace(Path.DirectorySeparatorChar, '/');
+    }
+
+    private static IEnumerable<FileInfo> EnumerateRealFiles(DirectoryInfo root)
+    {
+        var stack = new Stack<DirectoryInfo>();
+        stack.Push(root);
+
+        while (stack.Count > 0)
+        {
+            var current = stack.Pop();
+            FileSystemInfo[] entries;
+            try
+            {
+                entries = current.GetFileSystemInfos();
+            }
+            catch (IOException)
+            {
+                continue;
+            }
+
+            foreach (var entry in entries)
+            {
+                if (entry.Attributes.HasFlag(FileAttributes.ReparsePoint))
+                {
+                    continue;
+                }
+
+                if (entry is DirectoryInfo dir)
+                {
+                    stack.Push(dir);
+                }
+                else if (entry is FileInfo file)
+                {
+                    yield return file;
+                }
+            }
+        }
+    }
+
+    private static string GuessMediaType(string fileName)
+    {
+#pragma warning disable CA1308 // Normalize strings to uppercase - file extensions are conventionally lowercase
+        var extension = Path.GetExtension(fileName).ToLowerInvariant();
+#pragma warning restore CA1308
+        return extension switch
+        {
+            ".txt" => "text/plain",
+            ".json" => "application/json",
+            ".xml" => "application/xml",
+            ".html" => "text/html",
+            ".css" => "text/css",
+            ".js" => "application/javascript",
+            ".png" => "image/png",
+            ".jpg" or ".jpeg" => "image/jpeg",
+            ".gif" => "image/gif",
+            ".svg" => "image/svg+xml",
+            ".pdf" => "application/pdf",
+            ".zip" => "application/zip",
+            ".csv" => "text/csv",
+            ".md" => "text/markdown",
+            ".py" => "text/x-python",
+            ".cs" => "text/x-csharp",
+            _ => "application/octet-stream",
+        };
+    }
+}