Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

.devcontainer/devcontainer.json

@@ -1,15 +1,19 @@
 {
   "name": "Python 3",
-  "image": "mcr.microsoft.com/devcontainers/python:3.13-bullseye",
+  "image": "mcr.microsoft.com/devcontainers/python:3.14-bookworm",
   "features": {
     "ghcr.io/va-h/devcontainers-features/uv:1": {},
-    "ghcr.io/devcontainers/features/azure-cli:1.2.8": {}
+    "ghcr.io/devcontainers/features/docker-in-docker:3": {},
+    "ghcr.io/devcontainers/features/azure-cli:1.2.9": {},
+    "ghcr.io/devcontainers/features/copilot-cli:1": {}
   },
   "postCreateCommand": "bash ./devsetup.sh",
   "workspaceFolder": "/workspaces/agent-framework/python/",
   "customizations": {
     "vscode": {
       "extensions": [
+        "GitHub.copilot",
+        "GitHub.vscode-github-actions",
         "ms-python.python",
         "ms-windows-ai-studio.windows-ai-studio",
         "littlefoxteam.vscode-python-test-adapter"

.github/.linkspector.yml

@@ -8,7 +8,7 @@ ignorePatterns:
   - pattern: "./blob"
   - pattern: "./issues"
   - pattern: "./discussions"
-  - pattern: "./pulls"
+  - pattern: "./pull"
   - pattern: "https:\/\/platform.openai.com"
   - pattern: "http:\/\/localhost"
   - pattern: "http:\/\/127.0.0.1"
@@ -20,7 +20,10 @@ ignorePatterns:
   - pattern: "https://your-resource.openai.azure.com/"
   - pattern: "http://host.docker.internal"
   - pattern: "https://openai.github.io/openai-agents-js/openai/agents/classes/"
-  - pattern: "https:\/\/dotnet.microsoft.com\/download"
+  # dotnet.microsoft.com bot-blocks CI link checkers with intermittent 403s on any
+  # path (including localized variants like /en-us/download/...), so ignore the
+  # whole domain rather than just /download.
+  - pattern: "https:\/\/dotnet.microsoft.com"
   - pattern: "https://github.com/Rel1cx/eslint-react"
 # excludedDirs:
   # Folders which include links to localhost, since it's not ignored with regular expressions

.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/actions/free-runner-disk-space/action.yml

@@ -0,0 +1,64 @@
+name: Free runner disk space
+description: |
+  Reclaims disk space on GitHub-hosted Ubuntu runners by removing
+  pre-installed toolchains we do not use (Android SDK, GHC/Haskell,
+  CodeQL bundle), Docker images, and swap. Also relocates the
+  NuGet package cache to /mnt (which has ~75 GB free vs ~14 GB
+  on /). No-op on non-Linux runners.
+
+runs:
+  using: composite
+  steps:
+    - name: Free disk space (Linux only)
+      if: runner.os == 'Linux'
+      shell: bash
+      run: |
+        set -euo pipefail
+        echo "::group::Disk usage before cleanup"
+        df -h /
+        echo "::endgroup::"
+
+        # Remove pre-installed toolchains we never use on this repo's
+        # dotnet/python jobs. These reclaim ~25-30 GB on ubuntu-latest.
+        sudo rm -rf \
+          /usr/local/lib/android \
+          /usr/share/dotnet/sdk/NuGetFallbackFolder \
+          /opt/ghc \
+          /usr/local/.ghcup \
+          /opt/hostedtoolcache/CodeQL \
+          /opt/hostedtoolcache/PyPy \
+          /opt/hostedtoolcache/Ruby \
+          /opt/hostedtoolcache/go \
+          /usr/local/share/boost \
+          /usr/local/share/powershell \
+          /usr/local/share/chromium \
+          /usr/local/share/vcpkg \
+          /usr/local/lib/heroku \
+          "${AGENT_TOOLSDIRECTORY:-/opt/hostedtoolcache}/PyPy" \
+          "${AGENT_TOOLSDIRECTORY:-/opt/hostedtoolcache}/Ruby" \
+          "${AGENT_TOOLSDIRECTORY:-/opt/hostedtoolcache}/go" || true
+
+        # Drop docker images shipped on the runner; jobs that need
+        # docker pull what they need fresh.
+        if command -v docker >/dev/null 2>&1; then
+          sudo docker image prune --all --force >/dev/null 2>&1 || true
+        fi
+
+        # Disable swap to free its backing file.
+        sudo swapoff -a || true
+        sudo rm -f /mnt/swapfile /swapfile || true
+
+        echo "::group::Disk usage after cleanup"
+        df -h /
+        echo "::endgroup::"
+
+    - name: Relocate NuGet package cache to /mnt (Linux only)
+      if: runner.os == 'Linux'
+      shell: bash
+      run: |
+        set -euo pipefail
+        sudo mkdir -p /mnt/nuget
+        sudo chown -R "$USER":"$USER" /mnt/nuget
+        echo "NUGET_PACKAGES=/mnt/nuget" >> "$GITHUB_ENV"
+        echo "Relocated NuGet package cache to /mnt/nuget"
+        df -h /mnt || true

.github/actions/python-setup/action.yml

@@ -17,7 +17,7 @@ runs:
     using: "composite"
     steps:
       - name: Set up uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
         with:
             version-file: "python/pyproject.toml"
             enable-cache: true
@@ -32,7 +32,13 @@ runs:
               if grep -q "name = \"$pkg\"" "$f"; then
                 pkg_dir=$(dirname "$f" | sed 's|python/||')
                 echo "Excluding workspace package: $pkg ($pkg_dir)"
-                sed -i.bak '/\[tool\.uv\.workspace\]/a\exclude = ["'"$pkg_dir"'"]' python/pyproject.toml
+                if awk '/^\[tool\.uv\.workspace\]/{f=1;next} /^\[/{f=0} f && /^exclude = \[/{found=1} END{exit !found}' python/pyproject.toml; then
+                  if ! awk '/^\[tool\.uv\.workspace\]/{f=1;next} /^\[/{f=0} f && /^exclude = \[/ && index($0, "\"'"$pkg_dir"'\"")' python/pyproject.toml | grep -q .; then
+                    sed -i.bak '/\[tool\.uv\.workspace\]/,/^\[/ { /^exclude = \[/ s|\]|, "'"$pkg_dir"'"]| }' python/pyproject.toml
+                  fi
+                else
+                  sed -i.bak '/\[tool\.uv\.workspace\]/a\exclude = ["'"$pkg_dir"'"]' python/pyproject.toml
+                fi
                 sed -i.bak '/'"$pkg"' = { workspace = true }/d' python/pyproject.toml
               fi
             done
@@ -40,4 +46,4 @@ runs:
       - name: Install the project
         shell: bash
         run: |
-          cd python && uv sync --all-packages --all-extras --dev -U --prerelease=if-necessary-or-explicit
+          cd python && uv sync --all-packages --all-extras --dev --prerelease=if-necessary-or-explicit

.github/actions/sample-validation-setup/action.yml

@@ -24,7 +24,7 @@ runs:
   using: "composite"
   steps:
     - name: Set up Node.js environment
-      uses: actions/setup-node@v6
+      uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
       with:
         node-version: 22
 
@@ -37,7 +37,7 @@ runs:
       run: copilot --version && copilot -p "What can you do in one sentence?"
 
     - name: Azure CLI Login
-      uses: azure/login@v2
+      uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
       with:
         client-id: ${{ inputs.azure-client-id }}
         tenant-id: ${{ inputs.azure-tenant-id }}

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

.github/pull_request_template.md

@@ -1,23 +1,43 @@
-### Motivation and Context
+### Motivation & Context
 
 <!-- Thank you for your contribution to the Agent Framework repo!
 Please help reviewers and future users, providing the following information:
   1. Why is this change required?
   2. What problem does it solve?
   3. What scenario does it contribute to?
-  4. If it fixes an open issue, please link to the issue here.
+  4. If it fixes an open issue, please link to the issue below.
 -->
 
-### Description
+### Description & Review Guide
 
 <!-- Describe your changes, the overall approach, the underlying design.
+     Highlight what you want the reviewers to focus on.
      These notes will help understanding how your code works. Thanks! -->
 
+- **What are the major changes?**
+- **What is the impact of these changes?**
+- **What do you want reviewers to focus on?**
+<!-- 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
+
+<!-- Which issue does this PR fix? Link it using a GitHub closing keyword so it is
+     closed automatically when this PR is merged, e.g. "Fixes #123" or "Closes #123".
+     PRs that are not linked to an issue may be closed, no matter how valid the change is.
+     Also check whether an open PR already exists for this issue; if so,
+     explain how this PR is different. -->
+
+Fixes #
+
 ### Contribution Checklist
 
 <!-- Before submitting this PR, please make sure: -->
 
 - [ ] The code builds clean without any errors or warnings
-- [ ] The PR follows the [Contribution Guidelines](https://github.com/microsoft/agent-framework/blob/main/CONTRIBUTING.md)
 - [ ] 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.
+- [ ] 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.

.github/scripts/pr_limit_moderation.js

@@ -0,0 +1,181 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+function getPullRequest(context) {
+  const pullRequest = context.payload.pull_request;
+  if (!pullRequest?.number || !pullRequest.user?.login) {
+    throw new Error('This script must be run from a pull_request_target event.');
+  }
+
+  return {
+    author: pullRequest.user.login,
+    authorType: pullRequest.user.type,
+    labels: pullRequest.labels?.map((label) => label.name).filter(Boolean) ?? [],
+    number: pullRequest.number,
+  };
+}
+
+async function ensureLabel({ github, owner, repo, labelName }) {
+  try {
+    await github.rest.issues.getLabel({
+      owner,
+      repo,
+      name: labelName,
+    });
+  } catch (error) {
+    if (error.status !== 404) {
+      throw error;
+    }
+
+    try {
+      await github.rest.issues.createLabel({
+        owner,
+        repo,
+        name: labelName,
+        color: 'd93f0b',
+        description: 'Community author has exceeded the open pull request limit.',
+      });
+    } catch (createError) {
+      if (createError.status !== 422) {
+        throw createError;
+      }
+    }
+  }
+}
+
+function hasLabel(labels, labelName) {
+  if (!labelName) {
+    return false;
+  }
+
+  return labels.some((label) => label.toLowerCase() === labelName.toLowerCase());
+}
+
+function isDependabotAuthor({ author, authorType }) {
+  return authorType === 'Bot' && author.toLowerCase() === 'dependabot[bot]';
+}
+
+function buildLimitMessage({ author, exemptLabelName, maxOpenPrs, openPrCount }) {
+  return [
+    `Thank you for your contribution, @${author}.`,
+    '',
+    `To keep the review queue manageable, we currently limit community contributors to ${maxOpenPrs} `
+      + `open pull requests at a time. This PR would put you at ${openPrCount} open pull requests, `
+      + 'so we are closing it automatically.',
+    '',
+    'Please focus on getting your existing PRs reviewed, merged, or closed before opening another one. '
+      + `If a maintainer asked you to open this PR, they can apply the \`${exemptLabelName}\` label and reopen it.`,
+  ].join('\n');
+}
+
+async function getOpenPrCount({ github, owner, repo, author, pullRequestNumber }) {
+  const openPullRequests = await github.paginate(github.rest.pulls.list, {
+    owner,
+    repo,
+    state: 'open',
+    per_page: 100,
+  });
+
+  const authorOpenPullRequestNumbers = openPullRequests
+    .filter((pullRequest) => pullRequest.user?.login === author)
+    .map((pullRequest) => pullRequest.number);
+  const currentPrIsOpen = authorOpenPullRequestNumbers.includes(pullRequestNumber);
+  const existingOpenPrCount = currentPrIsOpen
+    ? authorOpenPullRequestNumbers.length - 1
+    : authorOpenPullRequestNumbers.length;
+
+  return existingOpenPrCount + 1;
+}
+
+async function enforcePrLimit({ github, context, core, exemptLabelName, maxOpenPrs, labelName }) {
+  const { owner, repo } = context.repo;
+  const { author, authorType, labels, number } = getPullRequest(context);
+
+  if (isDependabotAuthor({ author, authorType })) {
+    core.info(`Author ${author} is Dependabot; skipping open PR limit enforcement.`);
+    return {
+      author,
+      closed: false,
+      dependabotExempt: true,
+      openPrCount: null,
+    };
+  }
+
+  if (hasLabel(labels, exemptLabelName)) {
+    core.info(`PR #${number} has the ${exemptLabelName} label; skipping open PR limit enforcement.`);
+    return {
+      author,
+      closed: false,
+      exempt: true,
+      openPrCount: null,
+    };
+  }
+
+  const openPrCount = await getOpenPrCount({
+    github,
+    owner,
+    repo,
+    author,
+    pullRequestNumber: number,
+  });
+
+  if (openPrCount <= maxOpenPrs) {
+    core.info(
+      `${author} has ${openPrCount} open pull request(s), which is within the limit of ${maxOpenPrs}.`,
+    );
+    return {
+      author,
+      closed: false,
+      openPrCount,
+    };
+  }
+
+  await ensureLabel({
+    github,
+    owner,
+    repo,
+    labelName,
+  });
+
+  await github.rest.issues.addLabels({
+    owner,
+    repo,
+    issue_number: number,
+    labels: [labelName],
+  });
+
+  await github.rest.issues.createComment({
+    owner,
+    repo,
+    issue_number: number,
+    body: buildLimitMessage({
+      author,
+      exemptLabelName,
+      maxOpenPrs,
+      openPrCount,
+    }),
+  });
+
+  await github.rest.pulls.update({
+    owner,
+    repo,
+    pull_number: number,
+    state: 'closed',
+  });
+
+  core.info(
+    `${author} has ${openPrCount} open pull request(s), which exceeds the limit of ${maxOpenPrs}. `
+      + `Closed PR #${number}.`,
+  );
+
+  return {
+    author,
+    closed: true,
+    openPrCount,
+  };
+}
+
+module.exports = {
+  buildLimitMessage,
+  enforcePrLimit,
+  getOpenPrCount,
+};

.github/scripts/title_prefix.js

@@ -0,0 +1,253 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+const BREAKING_CHANGE_LABEL = 'breaking change';
+const BREAKING_PREFIX = '[BREAKING]';
+
+const DEFAULT_PREFIX_LABELS = Object.freeze({
+  python: 'Python',
+  '.NET': '.NET',
+});
+
+const DEFAULT_BRACKET_PREFIX_LABELS = Object.freeze({
+  [BREAKING_CHANGE_LABEL]: BREAKING_PREFIX,
+});
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function getMatchingValueByKey(valuesByKey, keyToFind) {
+  const matchingKey = Object.keys(valuesByKey).find((key) => key.toLowerCase() === keyToFind.toLowerCase());
+  return matchingKey === undefined ? null : valuesByKey[matchingKey];
+}
+
+function getPrefixPattern(prefixes) {
+  return prefixes.map(escapeRegExp).join('|');
+}
+
+function canonicalizePrefix(prefix, prefixes) {
+  return prefixes.find((knownPrefix) => knownPrefix.toLowerCase() === prefix.toLowerCase()) ?? prefix;
+}
+
+function normalizeLeadingBracketPrefix(title, bracketPrefixes) {
+  const bracketPattern = getPrefixPattern(bracketPrefixes);
+  if (!bracketPattern) {
+    return title;
+  }
+
+  const leadingBracketPrefix = new RegExp(`^(${bracketPattern})(?=\\s|$)`, 'i');
+  return title.replace(
+    leadingBracketPrefix,
+    (bracketPrefix) => canonicalizePrefix(bracketPrefix, bracketPrefixes),
+  );
+}
+
+function parseLeadingTitlePrefix(title, titlePrefixes) {
+  const titlePrefixPattern = getPrefixPattern(titlePrefixes);
+  if (!titlePrefixPattern) {
+    return null;
+  }
+
+  const match = title.match(new RegExp(`^(${titlePrefixPattern}):\\s*`, 'i'));
+  if (!match) {
+    return null;
+  }
+
+  return {
+    prefix: canonicalizePrefix(match[1], titlePrefixes),
+    rest: title.slice(match[0].length).trimStart(),
+  };
+}
+
+function removeBracketPrefixToken(title, bracketPrefix) {
+  const bracketPrefixPattern = escapeRegExp(bracketPrefix);
+  return title
+    .replace(new RegExp(`(^|\\s+)${bracketPrefixPattern}(?=\\s|$)`, 'ig'), '$1')
+    .replace(/\s{2,}/g, ' ')
+    .trim();
+}
+
+function addTitlePrefix(title, prefix, bracketPrefixes = Object.values(DEFAULT_BRACKET_PREFIX_LABELS)) {
+  const bracketPattern = getPrefixPattern(bracketPrefixes);
+  const prefixPattern = escapeRegExp(prefix);
+
+  if (bracketPattern) {
+    const bracketThenTitlePrefix = new RegExp(`^(${bracketPattern})(\\s+)(${prefixPattern})(?=:)`, 'i');
+    if (bracketThenTitlePrefix.test(title)) {
+      return title.replace(
+        bracketThenTitlePrefix,
+        (match, bracketPrefix, spacing) => `${canonicalizePrefix(bracketPrefix, bracketPrefixes)}${spacing}${prefix}`,
+      );
+    }
+
+    title = normalizeLeadingBracketPrefix(title, bracketPrefixes);
+  }
+
+  if (!title.startsWith(`${prefix}: `)) {
+    const existingTitlePrefix = new RegExp(`^${prefixPattern}:\\s*`, 'i');
+    if (existingTitlePrefix.test(title)) {
+      return title.replace(existingTitlePrefix, `${prefix}: `);
+    }
+
+    return `${prefix}: ${title}`;
+  }
+
+  return title;
+}
+
+function hasBracketPrefix(title, bracketPrefix, titlePrefixes = Object.values(DEFAULT_PREFIX_LABELS)) {
+  const bracketPrefixPattern = escapeRegExp(bracketPrefix);
+  const leadingBracketPrefix = new RegExp(`^${bracketPrefixPattern}(?=\\s|$)`, 'i');
+  if (leadingBracketPrefix.test(title)) {
+    return true;
+  }
+
+  const leadingTitlePrefix = parseLeadingTitlePrefix(title, titlePrefixes);
+  if (!leadingTitlePrefix) {
+    return false;
+  }
+
+  return leadingBracketPrefix.test(leadingTitlePrefix.rest);
+}
+
+function addBracketPrefix(title, bracketPrefix, titlePrefixes = Object.values(DEFAULT_PREFIX_LABELS)) {
+  const bracketPrefixPattern = escapeRegExp(bracketPrefix);
+  const leadingBracketPrefix = new RegExp(`^${bracketPrefixPattern}(?=\\s|$)`, 'i');
+  if (leadingBracketPrefix.test(title)) {
+    return title.replace(leadingBracketPrefix, bracketPrefix);
+  }
+
+  const leadingTitlePrefix = parseLeadingTitlePrefix(title, titlePrefixes);
+  if (leadingTitlePrefix) {
+    if (leadingBracketPrefix.test(leadingTitlePrefix.rest)) {
+      const normalizedRest = leadingTitlePrefix.rest.replace(leadingBracketPrefix, bracketPrefix);
+      return `${leadingTitlePrefix.prefix}: ${normalizedRest}`;
+    }
+
+    const titleWithoutBracketPrefix = removeBracketPrefixToken(leadingTitlePrefix.rest, bracketPrefix);
+    return `${leadingTitlePrefix.prefix}: ${bracketPrefix}`
+      + (titleWithoutBracketPrefix ? ` ${titleWithoutBracketPrefix}` : '');
+  }
+
+  const titleWithoutBracketPrefix = removeBracketPrefixToken(title, bracketPrefix);
+  return `${bracketPrefix}${titleWithoutBracketPrefix ? ` ${titleWithoutBracketPrefix}` : ''}`;
+}
+
+function hasLabel(labels, labelName) {
+  return labels.some((label) => label.toLowerCase() === labelName.toLowerCase());
+}
+
+function getCurrentTitle(context) {
+  switch (context.eventName) {
+    case 'issues':
+      return context.payload.issue.title;
+    case 'pull_request_target':
+      return context.payload.pull_request.title;
+    default:
+      throw new Error(`Unrecognized eventName: ${context.eventName}`);
+  }
+}
+
+async function updateTitleForAddedLabel({
+  github,
+  context,
+  core,
+  prefixLabels = DEFAULT_PREFIX_LABELS,
+  bracketPrefixLabels = DEFAULT_BRACKET_PREFIX_LABELS,
+}) {
+  const labelAdded = context.payload.label?.name;
+  if (!labelAdded) {
+    throw new Error('This script must be run from a labeled event.');
+  }
+
+  const currentTitle = getCurrentTitle(context);
+  let newTitle = null;
+
+  const titlePrefix = getMatchingValueByKey(prefixLabels, labelAdded);
+  if (titlePrefix !== null) {
+    newTitle = addTitlePrefix(currentTitle, titlePrefix, Object.values(bracketPrefixLabels));
+  }
+
+  const bracketPrefix = getMatchingValueByKey(bracketPrefixLabels, labelAdded);
+  if (bracketPrefix !== null) {
+    newTitle = addBracketPrefix(currentTitle, bracketPrefix, Object.values(prefixLabels));
+  }
+
+  if (newTitle === null) {
+    core.info(`No title prefix configured for label "${labelAdded}".`);
+    return { updated: false, newTitle: currentTitle };
+  }
+
+  if (newTitle === currentTitle) {
+    core.info(`Title already includes the prefix for label "${labelAdded}".`);
+    return { updated: false, newTitle };
+  }
+
+  switch (context.eventName) {
+    case 'issues':
+      await github.rest.issues.update({
+        issue_number: context.issue.number,
+        owner: context.repo.owner,
+        repo: context.repo.repo,
+        title: newTitle,
+      });
+      break;
+
+    case 'pull_request_target':
+      await github.rest.pulls.update({
+        pull_number: context.issue.number,
+        owner: context.repo.owner,
+        repo: context.repo.repo,
+        title: newTitle,
+      });
+      break;
+
+    default:
+      throw new Error(`Unrecognized eventName: ${context.eventName}`);
+  }
+
+  return { updated: true, newTitle };
+}
+
+async function syncBreakingChangeLabelFromTitle({
+  github,
+  context,
+  core,
+  labelName = BREAKING_CHANGE_LABEL,
+  bracketPrefix = BREAKING_PREFIX,
+  titlePrefixes = Object.values(DEFAULT_PREFIX_LABELS),
+}) {
+  const pullRequest = context.payload.pull_request;
+  if (!pullRequest) {
+    throw new Error('This script must be run from a pull_request_target event.');
+  }
+
+  const title = pullRequest.title || '';
+  if (!hasBracketPrefix(title, bracketPrefix, titlePrefixes)) {
+    core.info(`Title does not include ${bracketPrefix} in the title prefix.`);
+    return { added: false };
+  }
+
+  const labels = pullRequest.labels?.map((label) => label.name).filter(Boolean) ?? [];
+  if (hasLabel(labels, labelName)) {
+    core.info(`PR already has the "${labelName}" label.`);
+    return { added: false };
+  }
+
+  await github.rest.issues.addLabels({
+    issue_number: context.issue.number,
+    owner: context.repo.owner,
+    repo: context.repo.repo,
+    labels: [labelName],
+  });
+
+  return { added: true };
+}
+
+module.exports = {
+  addBracketPrefix,
+  addTitlePrefix,
+  hasBracketPrefix,
+  syncBreakingChangeLabelFromTitle,
+  updateTitleForAddedLabel,
+};

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

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

.github/tests/test_pr_limit_moderation.js

@@ -0,0 +1,341 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+/**
+ * Tests for pr_limit_moderation.js.
+ *
+ * Run with: node --test .github/tests/test_pr_limit_moderation.js
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+
+const { enforcePrLimit } = require('../scripts/pr_limit_moderation.js');
+
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createContext({ author = 'community-user', authorType = 'User', labels = [], number = 123 } = {}) {
+  return {
+    repo: {
+      owner: 'microsoft',
+      repo: 'agent-framework',
+    },
+    payload: {
+      pull_request: {
+        number,
+        labels: labels.map((name) => ({ name })),
+        user: {
+          login: author,
+          type: authorType,
+        },
+      },
+    },
+  };
+}
+
+function createCore() {
+  const messages = [];
+  return {
+    messages,
+    info(message) {
+      messages.push(message);
+    },
+  };
+}
+
+function createGithub({
+  itemNumbers,
+  labelExists = true,
+  pullRequests = createPullRequestPage({ numbers: itemNumbers }),
+}) {
+  const calls = [];
+
+  return {
+    calls,
+    async paginate(method, params) {
+      calls.push({ api: 'paginate', method, params });
+      return pullRequests;
+    },
+    rest: {
+      issues: {
+        async getLabel(params) {
+          calls.push({ api: 'issues.getLabel', params });
+          if (!labelExists) {
+            const error = new Error('Not Found');
+            error.status = 404;
+            throw error;
+          }
+          return { data: { name: params.name } };
+        },
+        async createLabel(params) {
+          calls.push({ api: 'issues.createLabel', params });
+          return { data: { name: params.name } };
+        },
+        async addLabels(params) {
+          calls.push({ api: 'issues.addLabels', params });
+          return { data: [] };
+        },
+        async createComment(params) {
+          calls.push({ api: 'issues.createComment', params });
+          return { data: { id: 1 } };
+        },
+      },
+      pulls: {
+        async list(params) {
+          calls.push({ api: 'pulls.list', params });
+          return { data: pullRequests };
+        },
+        async update(params) {
+          calls.push({ api: 'pulls.update', params });
+          return { data: { state: params.state } };
+        },
+      },
+    },
+  };
+}
+
+function createPullRequestPage({ author = 'community-user', numbers }) {
+  return numbers.map((number) => ({
+    number,
+    user: {
+      login: author,
+    },
+  }));
+}
+
+
+// ---------------------------------------------------------------------------
+// PR limit enforcement
+// ---------------------------------------------------------------------------
+
+describe('PR limit enforcement', () => {
+  it('does not close the PR when the author is at the open PR limit', async () => {
+    const github = createGithub({
+      itemNumbers: [1, 2, 3, 4, 5, 6, 7, 8, 9, 123],
+    });
+
+    const result = await enforcePrLimit({
+      github,
+      context: createContext(),
+      core: createCore(),
+      exemptLabelName: 'pr-limit-exempt',
+      maxOpenPrs: 10,
+      labelName: 'too-many-prs',
+    });
+
+    assert.equal(result.closed, false);
+    assert.equal(result.openPrCount, 10);
+    assert.deepEqual(
+      github.calls.map((call) => call.api),
+      ['paginate'],
+    );
+  });
+
+  it('counts the new PR when the pull list includes it', async () => {
+    const github = createGithub({
+      itemNumbers: [123, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+    });
+
+    const result = await enforcePrLimit({
+      github,
+      context: createContext(),
+      core: createCore(),
+      exemptLabelName: 'pr-limit-exempt',
+      maxOpenPrs: 10,
+      labelName: 'too-many-prs',
+    });
+
+    assert.equal(result.closed, true);
+    assert.equal(result.openPrCount, 11);
+    assert.deepEqual(
+      github.calls.map((call) => call.api),
+      [
+        'paginate',
+        'issues.getLabel',
+        'issues.addLabels',
+        'issues.createComment',
+        'pulls.update',
+      ],
+    );
+  });
+
+  it('counts the current PR on top of existing open PRs', async () => {
+    const github = createGithub({
+      itemNumbers: [123, ...Array.from({ length: 24 }, (_, index) => index + 1)],
+      pullRequests: createPullRequestPage({
+        numbers: [123, ...Array.from({ length: 25 }, (_, index) => index + 1)],
+      }),
+    });
+
+    const result = await enforcePrLimit({
+      github,
+      context: createContext(),
+      core: createCore(),
+      exemptLabelName: 'pr-limit-exempt',
+      maxOpenPrs: 10,
+      labelName: 'too-many-prs',
+    });
+
+    assert.equal(result.closed, true);
+    assert.equal(result.openPrCount, 26);
+    const comment = github.calls.find((call) => call.api === 'issues.createComment').params.body;
+    assert.match(comment, /This PR would put you at 26 open pull requests/);
+  });
+
+  it('creates the label when it does not already exist', async () => {
+    const github = createGithub({
+      itemNumbers: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 123],
+      labelExists: false,
+    });
+
+    const result = await enforcePrLimit({
+      github,
+      context: createContext(),
+      core: createCore(),
+      exemptLabelName: 'pr-limit-exempt',
+      maxOpenPrs: 10,
+      labelName: 'too-many-prs',
+    });
+
+    assert.equal(result.closed, true);
+    assert.deepEqual(
+      github.calls.map((call) => call.api),
+      [
+        'paginate',
+        'issues.getLabel',
+        'issues.createLabel',
+        'issues.addLabels',
+        'issues.createComment',
+        'pulls.update',
+      ],
+    );
+    assert.equal(
+      github.calls.find((call) => call.api === 'issues.createLabel').params.name,
+      'too-many-prs',
+    );
+  });
+
+  it('tolerates a 422 race when creating the label', async () => {
+    const github = createGithub({
+      itemNumbers: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 123],
+      labelExists: false,
+    });
+    github.rest.issues.createLabel = async (params) => {
+      github.calls.push({ api: 'issues.createLabel', params });
+      const error = new Error('Validation Failed');
+      error.status = 422;
+      throw error;
+    };
+
+    const result = await enforcePrLimit({
+      github,
+      context: createContext(),
+      core: createCore(),
+      exemptLabelName: 'pr-limit-exempt',
+      maxOpenPrs: 10,
+      labelName: 'too-many-prs',
+    });
+
+    assert.equal(result.closed, true);
+    assert.deepEqual(
+      github.calls.map((call) => call.api),
+      [
+        'paginate',
+        'issues.getLabel',
+        'issues.createLabel',
+        'issues.addLabels',
+        'issues.createComment',
+        'pulls.update',
+      ],
+    );
+  });
+
+  it('uses a diplomatic close message with the configured limit', async () => {
+    const github = createGithub({
+      itemNumbers: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 123],
+      pullRequests: createPullRequestPage({
+        author: 'octo-contributor',
+        numbers: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 123],
+      }),
+    });
+
+    await enforcePrLimit({
+      github,
+      context: createContext({ author: 'octo-contributor' }),
+      core: createCore(),
+      exemptLabelName: 'pr-limit-exempt',
+      maxOpenPrs: 10,
+      labelName: 'too-many-prs',
+    });
+
+    const comment = github.calls.find((call) => call.api === 'issues.createComment').params.body;
+    assert.match(comment, /Thank you for your contribution/);
+    assert.match(comment, /limit community contributors to 10 open pull requests/);
+    assert.match(comment, /@octo-contributor/);
+    assert.match(comment, /`pr-limit-exempt` label and reopen/);
+  });
+
+  it('does not close an exempt PR when it is reopened', async () => {
+    const github = createGithub({
+      itemNumbers: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 123],
+    });
+
+    const result = await enforcePrLimit({
+      github,
+      context: createContext({ labels: ['PR-LIMIT-EXEMPT'] }),
+      core: createCore(),
+      exemptLabelName: 'pr-limit-exempt',
+      maxOpenPrs: 10,
+      labelName: 'too-many-prs',
+    });
+
+    assert.equal(result.closed, false);
+    assert.equal(result.exempt, true);
+    assert.equal(result.openPrCount, null);
+    assert.deepEqual(github.calls, []);
+  });
+
+  it('does not close Dependabot PRs', async () => {
+    const github = createGithub({
+      itemNumbers: [123, ...Array.from({ length: 25 }, (_, index) => index + 1)],
+      pullRequests: createPullRequestPage({
+        author: 'dependabot[bot]',
+        numbers: [123, ...Array.from({ length: 25 }, (_, index) => index + 1)],
+      }),
+    });
+
+    const result = await enforcePrLimit({
+      github,
+      context: createContext({ author: 'dependabot[bot]', authorType: 'Bot' }),
+      core: createCore(),
+      exemptLabelName: 'pr-limit-exempt',
+      maxOpenPrs: 10,
+      labelName: 'too-many-prs',
+    });
+
+    assert.equal(result.closed, false);
+    assert.equal(result.dependabotExempt, true);
+    assert.equal(result.openPrCount, null);
+    assert.deepEqual(github.calls, []);
+  });
+
+  it('counts the current PR when the author has more than one page of open PRs', async () => {
+    const github = createGithub({
+      itemNumbers: [123, ...Array.from({ length: 100 }, (_, index) => index + 1)],
+    });
+
+    const result = await enforcePrLimit({
+      github,
+      context: createContext({ number: 123 }),
+      core: createCore(),
+      exemptLabelName: 'pr-limit-exempt',
+      maxOpenPrs: 10,
+      labelName: 'too-many-prs',
+    });
+
+    assert.equal(result.closed, true);
+    assert.equal(result.openPrCount, 101);
+  });
+});

.github/workflows/codeql-analysis.yml

@@ -32,13 +32,13 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           persist-credentials: false
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v4
+        uses: github/codeql-action/init@9e0d7b8d25671d64c341c19c0152d693099fb5ba # v4
         with:
           languages: ${{ matrix.language }}
           # If you wish to specify custom queries, you can do so here or in a config file.
@@ -51,7 +51,7 @@ jobs:
       # Autobuild attempts to build any compiled languages  (C/C++, C#, Go, or Java).
       # If this step fails, then you should remove it and run the build manually (see below)
       - name: Autobuild
-        uses: github/codeql-action/autobuild@v4
+        uses: github/codeql-action/autobuild@9e0d7b8d25671d64c341c19c0152d693099fb5ba # v4
 
       # ℹ️ Command-line programs to run using the OS shell.
       # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
@@ -64,6 +64,6 @@ jobs:
       #     ./location_of_script_within_repo/buildscript.sh
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v4
+        uses: github/codeql-action/analyze@9e0d7b8d25671d64c341c19c0152d693099fb5ba # v4
         with:
           category: "/language:${{matrix.language}}"

.github/workflows/devflow-pr-review.yml

@@ -66,7 +66,7 @@ jobs:
 
       - name: Check PR author team membership
         id: check
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
         env:
           TEAM_NAME: ${{ secrets.DEVELOPER_TEAM }}
           PR_NUMBER: ${{ steps.pr.outputs.pr_number }}
@@ -116,7 +116,7 @@ jobs:
     steps:
       # Safe checkout: base repo only, not the untrusted PR head.
       - name: Checkout target repo base
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ github.event_name == 'pull_request_target' && github.event.pull_request.base.sha || github.sha }}
           fetch-depth: 0
@@ -125,7 +125,7 @@ jobs:
 
       # Private DevFlow checkout: the PAT/token grants access to this repo's code.
       - name: Checkout DevFlow
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           repository: ${{ env.DEVFLOW_REPOSITORY }}
           ref: ${{ env.DEVFLOW_REF }}
@@ -135,12 +135,12 @@ jobs:
           path: devflow
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
           python-version: "3.13"
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
         with:
           version: "0.11.x"
           enable-cache: true

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

@@ -38,9 +38,11 @@ jobs:
       dotnetChanges: ${{ steps.filter.outputs.dotnet }}
       cosmosDbChanges: ${{ steps.filter.outputs.cosmosdb }}
       foundryHostingChanges: ${{ steps.filter.outputs.foundryHosting }}
+      functionsChanged: ${{ steps.filter.outputs.functions }}
+      coreChanged: ${{ steps.filter.outputs.core }}
     steps:
-      - uses: actions/checkout@v6
-      - uses: dorny/paths-filter@v3
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: dorny/paths-filter@d1c1ffe0248fe513906c8e24db8ea791d46f8590 # v3
         id: filter
         with:
           filters: |
@@ -60,9 +62,28 @@ jobs:
               - 'dotnet/src/Microsoft.Agents.AI.Workflows/**'
               - 'dotnet/tests/Foundry.Hosting.IntegrationTests/**'
               - 'dotnet/tests/Foundry.Hosting.IntegrationTests.TestContainer/**'
+              - 'dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/**'
               - 'dotnet/Directory.Packages.props'
               - 'dotnet/tests/Foundry.Hosting.IntegrationTests/scripts/it-build-image.ps1'
               - '.github/workflows/dotnet-build-and-test.yml'
+            functions:
+              - 'dotnet/src/Microsoft.Agents.AI.DurableTask/**'
+              - 'dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/**'
+              - 'dotnet/tests/Microsoft.Agents.AI.DurableTask.IntegrationTests/**'
+              - 'dotnet/tests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests/**'
+              - '.github/actions/azure-functions-integration-setup/**'
+              - '.github/workflows/dotnet-build-and-test.yml'
+            core:
+              - 'dotnet/src/Microsoft.Agents.AI/**'
+              - 'dotnet/src/Microsoft.Agents.AI.Abstractions/**'
+              - 'dotnet/src/Microsoft.Agents.AI.OpenAI/**'
+              - 'dotnet/src/Microsoft.Agents.AI.Workflows/**'
+              - 'dotnet/src/Microsoft.Agents.AI.Workflows.Generators/**'
+              - 'dotnet/eng/scripts/New-FilteredSolution.ps1'
+              - 'dotnet/tests/Directory.Build.props'
+              - 'dotnet/Directory.Packages.props'
+              - 'dotnet/global.json'
+              - '.github/workflows/dotnet-build-and-test.yml'
       # run only if 'dotnet' files were changed
       - name: dotnet tests
         if: steps.filter.outputs.dotnet == 'true'
@@ -90,7 +111,7 @@ jobs:
 
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
             persist-credentials: false
             sparse-checkout: |
@@ -100,8 +121,11 @@ jobs:
               python
               declarative-agents
 
+      - name: Free runner disk space
+        uses: ./.github/actions/free-runner-disk-space
+
       - name: Setup dotnet
-        uses: actions/setup-dotnet@v5.2.0
+        uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7 # v5.2.0
         with:
           global-json-file: ${{ github.workspace }}/dotnet/global.json
       - name: Build dotnet solutions
@@ -160,7 +184,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     environment: ${{ matrix.environment }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
             persist-credentials: false
             sparse-checkout: |
@@ -170,6 +194,9 @@ jobs:
               python
               declarative-agents
 
+      - name: Free runner disk space
+        uses: ./.github/actions/free-runner-disk-space
+
       # Start Cosmos DB Emulator for all integration tests and only for unit tests when CosmosDB changes happened)
       - name: Start Azure Cosmos DB Emulator
         if: ${{ runner.os == 'Windows' && (needs.paths-filter.outputs.cosmosDbChanges == 'true' || (github.event_name != 'pull_request' && matrix.integration-tests)) }}
@@ -181,7 +208,7 @@ jobs:
           echo "COSMOSDB_EMULATOR_AVAILABLE=true" >> $env:GITHUB_ENV
 
       - name: Setup dotnet
-        uses: actions/setup-dotnet@v5.2.0
+        uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7 # v5.2.0
         with:
           global-json-file: ${{ github.workspace }}/dotnet/global.json
 
@@ -210,10 +237,11 @@ jobs:
             Verbose         = $true
           }
           ./dotnet/eng/scripts/New-FilteredSolution.ps1 @commonArgs `
-            -TestProjectNameFilter "*UnitTests*" `
+            -TestProjectNameIncludeFilter "*UnitTests*" `
             -OutputPath dotnet/filtered-unit.slnx
           ./dotnet/eng/scripts/New-FilteredSolution.ps1 @commonArgs `
-            -TestProjectNameFilter "*IntegrationTests*" `
+            -TestProjectNameIncludeFilter "*IntegrationTests*" `
+            -TestProjectNameExcludeFilter "*DurableTask.IntegrationTests*","*AzureFunctions.IntegrationTests*" `
             -OutputPath dotnet/filtered-integration.slnx
 
       - name: Run Unit Tests
@@ -249,20 +277,12 @@ jobs:
 
       - name: Azure CLI Login
         if: github.event_name != 'pull_request' && matrix.integration-tests
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
         with:
           client-id: ${{ secrets.AZURE_CLIENT_ID }}
           tenant-id: ${{ secrets.AZURE_TENANT_ID }}
           subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
 
-        # This setup action is required for both Durable Task and Azure Functions integration tests.
-        # We only run it on Ubuntu since the Durable Task and Azure Functions features are not available
-        # on .NET Framework (net472) which is what we use the Windows runner for.
-      - name: Set up Durable Task and Azure Functions Integration Test Emulators
-        if: github.event_name != 'pull_request' && matrix.integration-tests && matrix.os == 'ubuntu-latest'
-        uses: ./.github/actions/azure-functions-integration-setup
-        id: azure-functions-setup
-
       - name: Run Integration Tests
         shell: pwsh
         working-directory: dotnet
@@ -297,14 +317,15 @@ jobs:
           AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZURE_AI_MODEL_DEPLOYMENT_NAME }}
           AZURE_AI_BING_CONNECTION_ID: ${{ vars.AZURE_AI_BING_CONNECTION_ID }}
           # Anthropic Models
-          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-          ANTHROPIC_CHAT_MODEL_NAME: ${{ vars.ANTHROPIC_CHAT_MODEL_NAME }}
-          ANTHROPIC_REASONING_MODEL_NAME: ${{ vars.ANTHROPIC_REASONING_MODEL_NAME }}
+          # Disable Anthropic tests by not providing environment vars until 404 failure is resolved
+          # ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          # ANTHROPIC_CHAT_MODEL_NAME: ${{ vars.ANTHROPIC_CHAT_MODEL_NAME }}
+          # ANTHROPIC_REASONING_MODEL_NAME: ${{ vars.ANTHROPIC_REASONING_MODEL_NAME }}
 
       # Generate test reports and check coverage
       - name: Generate test reports
         if: matrix.targetFramework == env.COVERAGE_FRAMEWORK
-        uses: danielpalme/ReportGenerator-GitHub-Action@5.5.3
+        uses: danielpalme/ReportGenerator-GitHub-Action@2a82782178b2816d9d6960a7345fdd164791b323 # 5.5.3
         with:
           reports: "./TestResults/Coverage/**/*.cobertura.xml"
           targetdir: "./TestResults/Reports"
@@ -312,7 +333,7 @@ jobs:
 
       - name: Upload coverage report artifact
         if: matrix.targetFramework == env.COVERAGE_FRAMEWORK
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: CoverageReport-${{ matrix.os }}-${{ matrix.targetFramework }}-${{ matrix.configuration }} # Artifact name
           path: ./TestResults/Reports # Directory containing files to upload
@@ -324,7 +345,7 @@ jobs:
 
       - name: Upload integration test results
         if: always() && github.event_name != 'pull_request' && matrix.integration-tests
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: dotnet-test-results-${{ matrix.targetFramework }}-${{ matrix.os }}
           path: IntegrationTestResults/**/*.junit
@@ -340,10 +361,9 @@ jobs:
     runs-on: ubuntu-latest
     environment: integration
     env:
-      targetFramework: net10.0
       configuration: Release
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           persist-credentials: false
           sparse-checkout: |
@@ -352,39 +372,26 @@ jobs:
             dotnet
             python
 
+      - name: Free runner disk space
+        uses: ./.github/actions/free-runner-disk-space
+
       - name: Setup dotnet
-        uses: actions/setup-dotnet@v5.2.0
+        uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7 # v5.2.0
         with:
           global-json-file: ${{ github.workspace }}/dotnet/global.json
 
-      - name: Generate test solution (no samples)
-        shell: pwsh
-        run: |
-          ./dotnet/eng/scripts/New-FilteredSolution.ps1 `
-            -Solution dotnet/agent-framework-dotnet.slnx `
-            -TargetFramework $env:targetFramework `
-            -Configuration $env:configuration `
-            -ExcludeSamples `
-            -OutputPath dotnet/filtered.slnx `
-            -Verbose
-
-      - name: Generate Foundry hosted IT filtered solution
-        shell: pwsh
-        run: |
-          ./dotnet/eng/scripts/New-FilteredSolution.ps1 `
-            -Solution dotnet/filtered.slnx `
-            -TargetFramework $env:targetFramework `
-            -Configuration $env:configuration `
-            -TestProjectNameFilter "Foundry.Hosting.IntegrationTests*" `
-            -OutputPath dotnet/filtered-foundry-hosted.slnx `
-            -Verbose
-
+      # Build the test csproj directly instead of a filtered slnx + -f override.
+      # The test project pins TargetFrameworks=net10.0 and its ProjectReference closure
+      # gives MSBuild a single-rooted graph, so each multi-targeted dependency is invoked
+      # exactly once for net10.0. This avoids the MSB3026/MSB3491/MSB4018/MSB3883 file-lock
+      # collisions caused by parallel inner-builds racing on shared bin/obj output paths
+      # under the previous slnx + global TFM override approach.
       - name: Build Foundry hosted IT (and its deps)
         shell: bash
-        run: dotnet build dotnet/filtered-foundry-hosted.slnx -c "$configuration" -f "$targetFramework" --warnaserror
+        run: dotnet build dotnet/tests/Foundry.Hosting.IntegrationTests/Foundry.Hosting.IntegrationTests.csproj -c "$configuration" --warnaserror
 
       - name: Azure CLI Login
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
         with:
           client-id: ${{ secrets.AZURE_CLIENT_ID }}
           tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -394,13 +401,12 @@ jobs:
       # are picked up; the image tag is content-hashed across the test container source AND its
       # framework project references, so identical content is a no-op push.
       #
-      # `-UsePrebuiltProjectReferences` opts into the no-rebuild fast path: publish skips
-      # rebuilding ProjectReferences and consumes the DLLs the prior "Build Foundry hosted IT
-      # (and its deps)" step already produced. This avoids MSB3026 ("file is being used by
-      # another process") collisions caused by the previous build's shared-compilation server
-      # still holding file handles to those DLLs. Safe in CI because the prebuild step ran in
-      # the same job against the same source. Do not remove the prebuild step (the subsequent
-      # `dotnet test --no-build` step depends on it too).
+      # The script always passes --no-dependencies to dotnet publish so publish never re-touches
+      # the framework lib DLLs the prior "Build Foundry hosted IT (and its deps)" step produced.
+      # This structurally eliminates the MSB3026 collision that VBCSCompiler from the prebuild
+      # would otherwise cause by holding file handles to those DLLs. Do not remove the prebuild
+      # step: the subsequent `dotnet test --no-build` step and the publish's ProjectReference
+      # resolution both depend on the prebuilt outputs being present.
       - name: Build and push Foundry Hosted Agents test container
         id: build-foundry-hosted-image
         shell: pwsh
@@ -410,14 +416,13 @@ jobs:
           if ([string]::IsNullOrWhiteSpace($registry)) {
             throw "IT_HOSTED_AGENT_REGISTRY not set in the integration environment."
           }
-          & "${{ github.workspace }}/dotnet/tests/Foundry.Hosting.IntegrationTests/scripts/it-build-image.ps1" -Registry $registry -UsePrebuiltProjectReferences | Tee-Object -FilePath $env:GITHUB_ENV -Append
+          & "${{ github.workspace }}/dotnet/tests/Foundry.Hosting.IntegrationTests/scripts/it-build-image.ps1" -Registry $registry | Tee-Object -FilePath $env:GITHUB_ENV -Append
 
       - name: Run Foundry Hosted Agents Integration Tests
         shell: pwsh
         working-directory: dotnet
         run: |
-          dotnet test --solution ./filtered-foundry-hosted.slnx `
-            -f $env:targetFramework `
+          dotnet test --project tests/Foundry.Hosting.IntegrationTests/Foundry.Hosting.IntegrationTests.csproj `
             -c $env:configuration `
             --no-build -v Normal `
             --report-xunit-trx `
@@ -426,13 +431,121 @@ jobs:
         env:
           AZURE_AI_PROJECT_ENDPOINT: ${{ vars.IT_HOSTED_AGENT_PROJECT_ENDPOINT }}
           AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.IT_HOSTED_AGENT_MODEL_DEPLOYMENT_NAME }}
+          # Azure AI Search (for the azure-search-rag scenario). Reuses the integration
+          # environment secrets shared with python-sample-validation.yml. The index is
+          # provisioned out of band; see dotnet/tests/Foundry.Hosting.IntegrationTests/README.md
+          # for the required schema and seed content.
+          AZURE_SEARCH_ENDPOINT: ${{ secrets.AZURE_SEARCH_ENDPOINT }}
+          AZURE_SEARCH_INDEX_NAME: ${{ secrets.AZURE_SEARCH_INDEX_NAME }}
           # IT_HOSTED_AGENT_IMAGE was exported into $GITHUB_ENV by the previous step.
 
+  # DurableTask and AzureFunctions integration tests (ubuntu/net10.0 only).
+  # Split from main dotnet-test job for path-based filtering and parallelism.
+  dotnet-test-functions:
+    needs: [paths-filter]
+    if: >
+      github.event_name != 'pull_request' &&
+      (needs.paths-filter.outputs.functionsChanged == 'true' ||
+       needs.paths-filter.outputs.coreChanged == 'true' ||
+       github.event_name == 'schedule' ||
+       github.event_name == 'workflow_dispatch')
+    runs-on: ubuntu-latest
+    environment: integration
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          persist-credentials: false
+          sparse-checkout: |
+            .
+            .github
+            dotnet
+            python
+            declarative-agents
+
+      - name: Free runner disk space
+        uses: ./.github/actions/free-runner-disk-space
+
+      - name: Setup dotnet
+        uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7 # v5.2.0
+        with:
+          global-json-file: ${{ github.workspace }}/dotnet/global.json
+
+      - name: Build functions integration test projects
+        shell: bash
+        working-directory: dotnet
+        run: |
+          dotnet build ./tests/Microsoft.Agents.AI.DurableTask.IntegrationTests -c Release -f net10.0 --warnaserror
+          dotnet build ./tests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests -c Release -f net10.0 --warnaserror
+
+      - name: Azure CLI Login
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
+        with:
+          client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+
+      - name: Set up Durable Task and Azure Functions Integration Test Emulators
+        uses: ./.github/actions/azure-functions-integration-setup
+        id: azure-functions-setup
+
+      - name: Run Functions Integration Tests
+        shell: pwsh
+        working-directory: dotnet
+        run: |
+          # Run DurableTask integration tests
+          dotnet test `
+            --project ./tests/Microsoft.Agents.AI.DurableTask.IntegrationTests `
+            -f net10.0 `
+            -c Release `
+            --no-build -v Normal `
+            --report-xunit-trx `
+            --report-junit `
+            --results-directory ../IntegrationTestResults/ `
+            --ignore-exit-code 8 `
+            --filter-not-trait "Category=IntegrationDisabled" `
+            --parallel-algorithm aggressive `
+            --max-threads 2.0x
+
+          # Run AzureFunctions integration tests
+          dotnet test `
+            --project ./tests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests `
+            -f net10.0 `
+            -c Release `
+            --no-build -v Normal `
+            --report-xunit-trx `
+            --report-junit `
+            --results-directory ../IntegrationTestResults/ `
+            --ignore-exit-code 8 `
+            --filter-not-trait "Category=IntegrationDisabled" `
+            --parallel-algorithm aggressive `
+            --max-threads 2.0x
+        env:
+          # OpenAI Models
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          OPENAI_CHAT_MODEL_NAME: ${{ vars.OPENAI_CHAT_MODEL_NAME }}
+          OPENAI_REASONING_MODEL_NAME: ${{ vars.OPENAI_REASONING_MODEL_NAME }}
+          # Azure OpenAI Models
+          AZURE_OPENAI_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_DEPLOYMENT_NAME }}
+          AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_DEPLOYMENT_NAME }}
+          AZURE_OPENAI_ENDPOINT: ${{ vars.AZURE_OPENAI_ENDPOINT }}
+          # Azure AI Foundry
+          AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
+          AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZURE_AI_MODEL_DEPLOYMENT_NAME }}
+          AZURE_AI_BING_CONNECTION_ID: ${{ vars.AZURE_AI_BING_CONNECTION_ID }}
+
+      - name: Upload functions test results
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: dotnet-test-results-functions-net10.0-ubuntu-latest
+          path: IntegrationTestResults/**/*.junit
+          if-no-files-found: ignore
+
   # This final job is required to satisfy the merge queue. It must only run (or succeed) if no tests failed
   dotnet-build-and-test-check:
     if: always()
     runs-on: ubuntu-latest
-    needs: [dotnet-build, dotnet-test, dotnet-foundry-hosted-it]
+    needs: [dotnet-build, dotnet-test, dotnet-foundry-hosted-it, dotnet-test-functions]
     steps:
       - name: Get Date
         shell: bash
@@ -460,14 +573,14 @@ jobs:
       - name: Fail workflow if tests failed
         id: check_tests_failed
         if: contains(join(needs.*.result, ','), 'failure')
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
         with:
           script: core.setFailed('Integration Tests Failed!')
 
       - name: Fail workflow if tests cancelled
         id: check_tests_cancelled
         if: contains(join(needs.*.result, ','), 'cancelled')
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
         with:
           script: core.setFailed('Integration Tests Cancelled!')
 
@@ -479,13 +592,13 @@ jobs:
       github.event_name != 'pull_request' &&
       (contains(join(needs.*.result, ','), 'success') ||
        contains(join(needs.*.result, ','), 'failure'))
-    needs: [dotnet-test]
+    needs: [dotnet-test, dotnet-test-functions]
     runs-on: ubuntu-latest
     defaults:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           persist-credentials: false
           sparse-checkout: |
@@ -497,12 +610,12 @@ jobs:
           python-version: "3.13"
           os: ${{ runner.os }}
       - name: Download all test results from current run
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
         with:
           pattern: dotnet-test-results-*
           path: dotnet-test-results/
       - name: Restore report history cache
-        uses: actions/cache/restore@v4
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
           path: python/dotnet-integration-report-history.json
           key: dotnet-integration-report-history-${{ github.run_id }}
@@ -519,13 +632,13 @@ jobs:
         run: cat dotnet-integration-test-report.md >> $GITHUB_STEP_SUMMARY
       - name: Save report history cache
         if: always()
-        uses: actions/cache/save@v4
+        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
           path: python/dotnet-integration-report-history.json
           key: dotnet-integration-report-history-${{ github.run_id }}
       - name: Upload trend report
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: dotnet-integration-test-report
           path: |

.github/workflows/dotnet-format.yml

@@ -30,7 +30,7 @@ jobs:
 
     steps:
       - name: Check out code
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -42,7 +42,7 @@ jobs:
       - name: Get changed files
         id: changed-files
         if: github.event_name == 'pull_request'
-        uses: jitterbit/get-changed-files@v1
+        uses: jitterbit/get-changed-files@b17fbb00bdc0c0f63fcf166580804b4d2cdc2a42 # v1
         continue-on-error: true
 
       - name: No C# files changed
@@ -54,11 +54,14 @@ jobs:
       - name: Find csproj files
         id: find-csproj
         if: github.event_name != 'pull_request' || steps.changed-files.outputs.added_modified != '' || steps.changed-files.outcome == 'failure'
+        env:
+          ADDED_MODIFIED: ${{ steps.changed-files.outputs.added_modified }}
         run: |
           csproj_files=()
           exclude_files=("Experimental.Orchestration.Flow.csproj" "Experimental.Orchestration.Flow.UnitTests.csproj" "Experimental.Orchestration.Flow.IntegrationTests.csproj")
+          set -f
           if [[ ${{ steps.changed-files.outcome }} == 'success' ]]; then
-            for file in ${{ steps.changed-files.outputs.added_modified }}; do
+            for file in $ADDED_MODIFIED; do
               echo "$file was changed"
               dir="./$file"
               while [[ $dir != "." && $dir != "/" && $dir != $GITHUB_WORKSPACE ]]; do
@@ -80,6 +83,7 @@ jobs:
           csproj_files=($(printf "%s\n" "${csproj_files[@]}" | sort -u))
           echo "Found ${#csproj_files[@]} unique csproj/slnx files: ${csproj_files[*]}"
           echo "csproj_files=${csproj_files[*]}" >> $GITHUB_OUTPUT
+          set +f
 
       - name: Pull container dotnet/sdk:${{ matrix.dotnet }}
         if: steps.find-csproj.outputs.csproj_files != ''
@@ -88,8 +92,11 @@ jobs:
       # This step will run dotnet format on each of the unique csproj files and fail if any changes are made
       - name: Run dotnet format
         if: steps.find-csproj.outputs.csproj_files != ''
+        env:
+          CSPROJ_FILES: ${{ steps.find-csproj.outputs.csproj_files }}
         run: |
-          for csproj in ${{ steps.find-csproj.outputs.csproj_files }}; do
+          set -f
+          for csproj in $CSPROJ_FILES; do
             echo "Running dotnet format on $csproj"
-            docker run --rm -v $(pwd):/app -w /app mcr.microsoft.com/dotnet/sdk:${{ matrix.dotnet }} /bin/sh -c "dotnet format $csproj --verify-no-changes --verbosity diagnostic"
+            docker run --rm -v "$(pwd):/app" -w /app mcr.microsoft.com/dotnet/sdk:${{ matrix.dotnet }} dotnet format "$csproj" --verify-no-changes --verbosity diagnostic
           done

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

@@ -29,7 +29,7 @@ jobs:
     environment: integration
     timeout-minutes: 60
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ inputs.checkout-ref }}
           persist-credentials: false
@@ -50,7 +50,7 @@ jobs:
           echo "COSMOS_EMULATOR_AVAILABLE=true" >> $env:GITHUB_ENV
 
       - name: Setup dotnet
-        uses: actions/setup-dotnet@v5.2.0
+        uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7 # v5.2.0
         with:
           global-json-file: ${{ github.workspace }}/dotnet/global.json
 
@@ -63,7 +63,7 @@ jobs:
           done
 
       - name: Azure CLI Login
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
         with:
           client-id: ${{ secrets.AZURE_CLIENT_ID }}
           tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -88,6 +88,7 @@ jobs:
         env:
           COSMOSDB_ENDPOINT: https://localhost:8081
           COSMOSDB_KEY: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
+          COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
           OpenAI__ApiKey: ${{ secrets.OPENAI__APIKEY }}
           OpenAI__ChatModelId: ${{ vars.OPENAI__CHATMODELID }}
           OpenAI__ChatReasoningModelId: ${{ vars.OPENAI__CHATREASONINGMODELID }}

.github/workflows/dotnet-verify-samples.yml

@@ -41,7 +41,7 @@ jobs:
     environment: 'integration'
     timeout-minutes: 90
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           persist-credentials: false
           sparse-checkout: |
@@ -52,13 +52,13 @@ jobs:
             declarative-agents
 
       - name: Setup dotnet
-        uses: actions/setup-dotnet@v5.2.0
+        uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7 # v5.2.0
         with:
           global-json-file: ${{ github.workspace }}/dotnet/global.json
 
       - name: Azure CLI Login
         if: github.event_name != 'pull_request'
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
         with:
           client-id: ${{ secrets.AZURE_CLIENT_ID }}
           tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -109,6 +109,9 @@ jobs:
           AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
           AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZURE_AI_MODEL_DEPLOYMENT_NAME }}
           AZURE_AI_BING_CONNECTION_ID: ${{ vars.AZURE_AI_BING_CONNECTION_ID }}
+          # Foundry
+          FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
+          FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL }}
 
       - name: Write Job Summary
         if: always()
@@ -123,7 +126,7 @@ jobs:
 
       - name: Upload results
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: verify-samples-results
           path: |

.github/workflows/issue-triage.yml

@@ -1,12 +1,8 @@
 name: Issue Triage
 
 on:
-  workflow_dispatch:
-    inputs:
-      issue_number:
-        description: Issue number to triage
-        required: true
-        type: string
+  issues:
+    types: [opened, typed]
 
 permissions:
   contents: read
@@ -14,7 +10,11 @@ permissions:
   id-token: write
 
 concurrency:
-  group: issue-triage-${{ github.repository }}-${{ github.event.issue.number || inputs.issue_number || github.run_id }}
+  group: >-
+    issue-triage-${{ github.repository }}-${{
+      github.event.issue.type.name == 'Bug' && github.event.issue.number
+      || github.run_id
+    }}
   cancel-in-progress: true
 
 env:
@@ -26,6 +26,7 @@ env:
 jobs:
   team_check:
     runs-on: ubuntu-latest
+    if: ${{ github.event.issue.type.name == 'Bug' }}
     outputs:
       is_team_member: ${{ steps.check.outputs.is_team_member }}
       issue_number: ${{ steps.issue.outputs.issue_number }}
@@ -36,18 +37,13 @@ jobs:
         shell: bash
         env:
           ISSUE_NUMBER_EVENT: ${{ github.event.issue.number }}
-          ISSUE_NUMBER_INPUT: ${{ inputs.issue_number }}
         run: |
           set -euo pipefail
 
-          if [[ "${GITHUB_EVENT_NAME}" == "issues" ]]; then
-            issue_number="${ISSUE_NUMBER_EVENT}"
-          else
-            issue_number="${ISSUE_NUMBER_INPUT}"
-          fi
+          issue_number="${ISSUE_NUMBER_EVENT}"
 
           if [[ ! "$issue_number" =~ ^[1-9][0-9]*$ ]]; then
-            echo "Could not determine issue number; for workflow_dispatch runs, the 'issue_number' input is required." >&2
+            echo "Could not determine issue number from event payload." >&2
             exit 1
           fi
 
@@ -55,7 +51,7 @@ jobs:
           echo "repo=${GITHUB_REPOSITORY}" >> "$GITHUB_OUTPUT"
 
       - name: Checkout scripts
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           sparse-checkout: .github/scripts
           fetch-depth: 1
@@ -63,7 +59,7 @@ jobs:
 
       - name: Check issue author team membership
         id: check
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
         env:
           TEAM_NAME: ${{ secrets.DEVELOPER_TEAM }}
           ISSUE_NUMBER: ${{ steps.issue.outputs.issue_number }}
@@ -95,7 +91,7 @@ jobs:
     steps:
       # Safe checkout: base repo only.
       - name: Checkout target repo base
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -103,7 +99,7 @@ jobs:
 
       # Private DevFlow (maf-dashboard) checkout.
       - name: Checkout DevFlow
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           repository: ${{ env.DEVFLOW_REPOSITORY }}
           ref: ${{ env.DEVFLOW_REF }}
@@ -113,12 +109,12 @@ jobs:
           path: devflow
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
           python-version: "3.13"
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
         with:
           version: "0.11.x"
           enable-cache: true
@@ -128,7 +124,7 @@ jobs:
         run: uv sync --frozen
 
       - name: Azure CLI Login
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
         with:
           client-id: ${{ secrets.AZURE_CLIENT_ID }}
           tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -139,6 +135,7 @@ jobs:
         working-directory: ${{ env.DEVFLOW_PATH }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DEVFLOW_TOKEN: ${{ secrets.DEVFLOW_TOKEN }}
           SK_REPO_PATH: ${{ env.TARGET_REPO_PATH }}
           AGENT_REPO_PATH: ${{ env.TARGET_REPO_PATH }}
           ISSUE_REPO: ${{ needs.team_check.outputs.repo }}
@@ -151,21 +148,22 @@ jobs:
             --apply-labels
 
       - name: Stop after spam gate
-        if: ${{ steps.spam.outputs.decision != 'allow' }}
+        if: ${{ steps.spam.outputs.allow_triage != 'true' }}
         shell: bash
-        env:
-          SPAM_DECISION: ${{ steps.spam.outputs.decision }}
         run: |
-          echo "Stopping: spam gate decided: ${SPAM_DECISION}"
+          echo "Stopping: issue triage preflight did not allow automation."
           exit 1
 
       - name: Reproduce reported issue
-        if: ${{ steps.spam.outputs.decision == 'allow' }}
+        if: ${{ steps.spam.outputs.allow_triage == 'true' }}
         id: repro
         working-directory: ${{ env.DEVFLOW_PATH }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           GH_COPILOT_TOKEN: ${{ secrets.GH_COPILOT_TOKEN }}
+          # Not seen by the agent prompt; used only to push a paper-trail
+          # branch back to maf-dashboard at run end.
+          DEVFLOW_TOKEN: ${{ secrets.DEVFLOW_TOKEN }}
           SK_REPO_PATH: ${{ env.TARGET_REPO_PATH }}
           AGENT_REPO_PATH: ${{ env.TARGET_REPO_PATH }}
           ISSUE_REPO: ${{ needs.team_check.outputs.repo }}

.github/workflows/label-issues.yml

@@ -13,7 +13,7 @@ jobs:
     permissions:
       issues: write
     steps:
-      - uses: actions/github-script@v8
+      - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
         with:
           github-token: ${{ secrets.GH_ACTIONS_PR_WRITE }}
           script: |
@@ -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/label-pr.yml

@@ -6,16 +6,34 @@
 # https://github.com/actions/labeler
 
 name: Label pull request
-on: [pull_request_target]
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened, edited]
 
 jobs:
   add_label:
     runs-on: ubuntu-latest
     permissions:
       contents: read
+      issues: write
       pull-requests: write
 
     steps:
-      - uses: actions/labeler@v6
+      - uses: actions/labeler@f27b608878404679385c85cfa523b85ccb86e213 # v6
         with:
           repo-token: "${{ secrets.GH_ACTIONS_PR_WRITE }}"
+
+      - name: Checkout scripts
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          sparse-checkout: .github/scripts
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: "PR: add breaking change label from title"
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
+        with:
+          github-token: ${{ secrets.GH_ACTIONS_PR_WRITE }}
+          script: |
+            const { syncBreakingChangeLabelFromTitle } = require('./.github/scripts/title_prefix.js');
+            await syncBreakingChangeLabelFromTitle({ github, context, core });

.github/workflows/label-title-prefix.yml

@@ -15,58 +15,17 @@ jobs:
       pull-requests: write
 
     steps:
-      - uses: actions/github-script@v8
+      - name: Checkout scripts
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          sparse-checkout: .github/scripts
+          fetch-depth: 1
+          persist-credentials: false
+
+      - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
         name: "Issue/PR: update title"
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
-            let prefixLabels = {
-              "python": "Python",
-              ".NET": ".NET"
-            };
-
-            function addTitlePrefix(title, prefix)
-            {
-              // Update the title based on the label and prefix
-              // Check if the title starts with the prefix (case-sensitive)
-              if (!title.startsWith(prefix + ": ")) {
-                // If not, check if the first word is the label (case-insensitive)
-                if (title.match(new RegExp(`^${prefix}`, 'i'))) {
-                  // If yes, replace it with the prefix (case-sensitive)
-                  title = title.replace(new RegExp(`^${prefix}`, 'i'), prefix);
-                } else {
-                  // If not, prepend the prefix to the title
-                  title = prefix + ": " + title;
-                }
-              }
-
-              return title;
-            }
-
-            labelAdded = context.payload.label.name
-
-            // Check if the issue or PR has the label
-            if (labelAdded in prefixLabels) {
-              let prefix = prefixLabels[labelAdded];
-              switch(context.eventName) {
-                case 'issues':
-                  github.rest.issues.update({
-                    issue_number: context.issue.number,
-                    owner: context.repo.owner,
-                    repo: context.repo.repo,
-                    title: addTitlePrefix(context.payload.issue.title, prefix)
-                  });
-                  break
-
-                case 'pull_request_target':
-                  github.rest.pulls.update({
-                    pull_number: context.issue.number,
-                    owner: context.repo.owner,
-                    repo: context.repo.repo,
-                    title: addTitlePrefix(context.payload.pull_request.title, prefix)
-                  });
-                  break
-                default:
-                  core.setFailed('Unrecognited eventName: ' + context.eventName);
-              }
-            }
+            const { updateTitleForAddedLabel } = require('./.github/scripts/title_prefix.js');
+            await updateTitleForAddedLabel({ github, context, core });

.github/workflows/limit-community-prs.yml

@@ -0,0 +1,83 @@
+name: Limit community pull requests
+
+on:
+  pull_request_target:
+    types: [opened, reopened]
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+concurrency:
+  group: pr-limit-${{ github.repository }}-${{ github.event.pull_request.user.login }}
+  cancel-in-progress: false
+
+env:
+  MAX_OPEN_PULL_REQUESTS: '10'
+  PR_LIMIT_EXEMPT_LABEL: pr-limit-exempt
+  TOO_MANY_PRS_LABEL: too-many-prs
+
+jobs:
+  team_check:
+    runs-on: ubuntu-latest
+    outputs:
+      is_team_member: ${{ steps.check.outputs.is_team_member }}
+    steps:
+      - name: Checkout scripts
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          sparse-checkout: .github/scripts
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: Check PR author team membership
+        id: check
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
+        env:
+          TEAM_NAME: ${{ secrets.DEVELOPER_TEAM }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        with:
+          github-token: ${{ secrets.GH_ACTIONS_PR_WRITE }}
+          script: |
+            const checkTeamMembership = require('./.github/scripts/check_team_membership.js');
+            const { author, isTeamMember } = await checkTeamMembership({
+              github,
+              context,
+              core,
+              teamSlug: process.env.TEAM_NAME,
+              issueNumber: process.env.PR_NUMBER,
+            });
+            core.setOutput('is_team_member', isTeamMember ? 'true' : 'false');
+            if (isTeamMember) {
+              core.info(`Author ${author} is a team member; skipping open PR limit.`);
+            } else {
+              core.info(`Author ${author} is not a team member; checking open PR limit.`);
+            }
+
+  limit_open_prs:
+    runs-on: ubuntu-latest
+    needs: team_check
+    if: ${{ needs.team_check.outputs.is_team_member == 'false' }}
+    steps:
+      - name: Checkout scripts
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          sparse-checkout: .github/scripts
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: Enforce open PR limit
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
+        with:
+          github-token: ${{ secrets.GH_ACTIONS_PR_WRITE }}
+          script: |
+            const { enforcePrLimit } = require('./.github/scripts/pr_limit_moderation.js');
+            await enforcePrLimit({
+              github,
+              context,
+              core,
+              exemptLabelName: process.env.PR_LIMIT_EXEMPT_LABEL,
+              maxOpenPrs: Number.parseInt(process.env.MAX_OPEN_PULL_REQUESTS, 10),
+              labelName: process.env.TOO_MANY_PRS_LABEL,
+            });

.github/workflows/markdown-link-check.yml

@@ -19,13 +19,21 @@ jobs:
     runs-on: ubuntu-22.04
     # check out the latest version of the code
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           persist-credentials: false
 
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install Chrome for Puppeteer
+        run: npx puppeteer browsers install chrome
+
       # Checks the status of hyperlinks in all files
       - name: Run linkspector
-        uses: umbrelladocs/action-linkspector@v1
+        uses: umbrelladocs/action-linkspector@963b6264d7de32c904942a70b488d3407453049e # v1
         with:
           reporter: local
           filter_mode: nofilter

.github/workflows/merge-gatekeeper.yml

@@ -2,7 +2,7 @@ name: Merge Gatekeeper
 
 on:
   pull_request:
-    branches: [ "main", "feature*" ]
+    branches: ["main", "feature*"]
   merge_group:
     branches: ["main"]
 
@@ -13,23 +13,105 @@ concurrency:
 jobs:
   merge-gatekeeper:
     runs-on: ubuntu-latest
-    # Restrict permissions of the GITHUB_TOKEN.
-    # Docs: https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs
     permissions:
       checks: read
       statuses: read
     steps:
-      - name: Run Merge Gatekeeper
-        # NOTE: v1 is updated to reflect the latest v1.x.y. Please use any tag/branch that suits your needs:
-        #       https://github.com/upsidr/merge-gatekeeper/tags
-        #       https://github.com/upsidr/merge-gatekeeper/branches
-        uses: upsidr/merge-gatekeeper@v1
+      - name: Wait for required checks
         if: github.event_name == 'pull_request'
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-          timeout: 3600
-          interval: 30
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
+        env:
+          TIMEOUT_SECONDS: "3600"
+          INTERVAL_SECONDS: "30"
+          SELF_JOB_NAME: ${{ github.job }}
           # "Cleanup artifacts", "Agent", "Prepare", and "Upload results" are check runs
           # created by an org-level GitHub App (MSDO), not by any workflow in this repo.
           # They are outside our control and their transient failures should not block merges.
-          ignored: CodeQL,CodeQL analysis (csharp),Cleanup artifacts,Agent,Prepare,Upload results
+          IGNORED_NAMES: "CodeQL,CodeQL analysis (csharp),Cleanup artifacts,Agent,Prepare,Upload results,review"
+        with:
+          script: |
+            const timeoutSeconds = Number(process.env.TIMEOUT_SECONDS);
+            const intervalSeconds = Number(process.env.INTERVAL_SECONDS);
+            const selfName = process.env.SELF_JOB_NAME;
+            const ignored = new Set(
+              process.env.IGNORED_NAMES.split(',').map((s) => s.trim()).filter(Boolean),
+            );
+
+            const sha = context.payload.pull_request.head.sha;
+            const { owner, repo } = context.repo;
+
+            const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+            // Mirrors upsidr/merge-gatekeeper: merge combined-statuses and check-runs
+            // for the PR head SHA, with combined-statuses winning on name collision.
+            async function collectChecks() {
+              const merged = new Map();
+
+              const combined = await github.rest.repos.getCombinedStatusForRef({
+                owner, repo, ref: sha, per_page: 100,
+              });
+              for (const s of combined.data.statuses ?? []) {
+                if (!merged.has(s.context)) {
+                  // Combined-status states: success | pending | error | failure
+                  merged.set(s.context, { name: s.context, state: s.state });
+                }
+              }
+
+              const runs = await github.paginate(github.rest.checks.listForRef, {
+                owner, repo, ref: sha, per_page: 100,
+              });
+              for (const r of runs) {
+                if (merged.has(r.name)) continue;
+                let state;
+                if (r.status !== 'completed') {
+                  state = 'pending';
+                } else if (r.conclusion === 'skipped') {
+                  continue; // Skipped runs are dropped, matching the original action.
+                } else if (r.conclusion === 'success' || r.conclusion === 'neutral') {
+                  state = 'success';
+                } else {
+                  // cancelled | timed_out | action_required | stale | failure
+                  state = 'error';
+                }
+                merged.set(r.name, { name: r.name, state });
+              }
+
+              return [...merged.values()];
+            }
+
+            function evaluate(entries) {
+              const failed = [];
+              const pending = [];
+              const succeeded = [];
+              for (const e of entries) {
+                if (e.name === selfName || ignored.has(e.name)) continue;
+                if (e.state === 'success') succeeded.push(e.name);
+                else if (e.state === 'error' || e.state === 'failure') failed.push(e.name);
+                else pending.push(e.name);
+              }
+              return { failed, pending, succeeded };
+            }
+
+            const deadline = Date.now() + timeoutSeconds * 1000;
+            for (;;) {
+              const entries = await collectChecks();
+              const { failed, pending, succeeded } = evaluate(entries);
+
+              core.info(
+                `succeeded=${succeeded.length} pending=${pending.length} failed=${failed.length}`,
+              );
+              if (failed.length) {
+                core.setFailed(`Failing checks: ${failed.join(', ')}`);
+                return;
+              }
+              if (pending.length === 0) {
+                core.info(`All required checks passed: ${succeeded.join(', ') || '(none)'}`);
+                return;
+              }
+              if (Date.now() > deadline) {
+                core.setFailed(`Timed out waiting for: ${pending.join(', ')}`);
+                return;
+              }
+              core.info(`Waiting on (${pending.length}): ${pending.slice(0, 10).join(', ')}${pending.length > 10 ? ', …' : ''}`);
+              await sleep(intervalSeconds * 1000);
+            }

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

@@ -6,6 +6,10 @@ on:
     branches: ["main"]
     paths:
       - "python/**"
+      - "!python/AGENTS.md"
+      - "!python/**/AGENTS.md"
+      - "!python/.github/skills/*"
+      - "!python/.github/skills/**"
 
 env:
   # Configure a constant location for the uv cache
@@ -27,7 +31,7 @@ jobs:
     env:
       UV_PYTHON: ${{ matrix.python-version }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           fetch-depth: 0
       - name: Set up python and install the project
@@ -38,11 +42,11 @@ jobs:
           os: ${{ runner.os }}
         env:
           UV_CACHE_DIR: /tmp/.uv-cache
-      - uses: actions/cache@v5
+      - uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
         with:
           path: ~/.cache/prek
           key: prek|${{ matrix.python-version }}|${{ hashFiles('python/.pre-commit-config.yaml') }}
-      - uses: j178/prek-action@v1
+      - uses: j178/prek-action@0bb87d7f00b0c99306c8bcb8b8beba1eb581c037 # v1
         name: Run Pre-commit Hooks (excluding poe-check)
         env:
           SKIP: poe-check
@@ -64,7 +68,7 @@ jobs:
     env:
       UV_PYTHON: ${{ matrix.python-version }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           fetch-depth: 0
       - name: Set up python and install the project
@@ -93,7 +97,7 @@ jobs:
     env:
       UV_PYTHON: ${{ matrix.python-version }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           fetch-depth: 0
       - name: Set up python and install the project
@@ -109,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
@@ -124,7 +128,7 @@ jobs:
     env:
       UV_PYTHON: ${{ matrix.python-version }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           fetch-depth: 0
       - name: Set up python and install the project
@@ -135,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,431 @@
+name: Python - Dependency Maintenance
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 4 * * 1"
+
+permissions:
+  contents: write
+  issues: 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 dependency maintenance tracking issue
+        if: steps.commit_updates.outputs.has_changes == 'true'
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const branch = "automation/python-dependency-maintenance"
+            const prTitle = "Python: chore: update dependencies"
+            const issueTitle = "Python dependency maintenance PR needed"
+            const owner = context.repo.owner
+            const repo = context.repo.repo
+
+            const branchRef = await github.rest.git.getRef({
+              owner,
+              repo,
+              ref: `heads/${branch}`,
+            })
+            const branchSha = branchRef.data.object.sha
+            const runUrl = `${context.serverUrl}/${owner}/${repo}/actions/runs/${context.runId}`
+            const compareUrl = `${context.serverUrl}/${owner}/${repo}/compare/main...${branch}`
+
+            const prBody = [
+              "### 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.',
+            ].join("\n")
+
+            const prBodyFence = "```"
+            const command = [
+              "PR_BODY_FILE=\"$(mktemp)\"",
+              `cat > "$PR_BODY_FILE" <<'EOF'`,
+              prBody,
+              "EOF",
+              "gh pr create --repo microsoft/agent-framework --base main \\",
+              `  --head ${owner}:${branch} \\`,
+              `  --title "${prTitle}" \\`,
+              "  --body-file \"$PR_BODY_FILE\"",
+            ].join("\n")
+
+            const issueBody = [
+              "The Python dependency maintenance workflow generated and validated dependency updates, then pushed them to the automation branch.",
+              "",
+              `- Branch: \`${branch}\``,
+              `- Commit: \`${branchSha}\``,
+              `- Compare: ${compareUrl}`,
+              `- Workflow run: ${runUrl}`,
+              "",
+              "GitHub Actions is not permitted to create pull requests in this repository, so a maintainer needs to create the PR manually.",
+              "",
+              "### Create the PR",
+              "",
+              "```bash",
+              command,
+              "```",
+              "",
+              "### Generated PR body",
+              "",
+              prBodyFence,
+              prBody,
+              prBodyFence,
+            ].join("\n")
+
+            const openIssues = await github.paginate(github.rest.issues.listForRepo, {
+              owner,
+              repo,
+              state: "open",
+              per_page: 100,
+            })
+            const existingIssue = openIssues.find((issue) => !issue.pull_request && issue.title === issueTitle)
+
+            if (existingIssue) {
+              await github.rest.issues.update({
+                owner,
+                repo,
+                issue_number: existingIssue.number,
+                title: issueTitle,
+                body: issueBody,
+              })
+              core.info(`Updated issue #${existingIssue.number}: ${issueTitle}`)
+            } else {
+              const createdIssue = await github.rest.issues.create({
+                owner,
+                repo,
+                title: issueTitle,
+                body: issueBody,
+              })
+              core.info(`Created issue #${createdIssue.data.number}: ${issueTitle}`)
+            }

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

@@ -24,9 +24,9 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       - name: Set up uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
         with:
           version-file: "python/pyproject.toml"
           enable-cache: true

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

@@ -36,7 +36,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ inputs.checkout-ref }}
           persist-credentials: false
@@ -69,7 +69,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ inputs.checkout-ref }}
           persist-credentials: false
@@ -90,7 +90,7 @@ jobs:
           --junitxml=pytest.xml
       - name: Upload test results
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: test-results-openai
           path: ./python/pytest.xml
@@ -112,7 +112,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ inputs.checkout-ref }}
           persist-credentials: false
@@ -123,7 +123,7 @@ jobs:
           python-version: ${{ env.UV_PYTHON }}
           os: ${{ runner.os }}
       - name: Azure CLI Login
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
         with:
           client-id: ${{ secrets.AZURE_CLIENT_ID }}
           tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -141,7 +141,7 @@ jobs:
           --junitxml=pytest.xml
       - name: Upload test results
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: test-results-azure-openai
           path: ./python/pytest.xml
@@ -163,7 +163,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ inputs.checkout-ref }}
           persist-credentials: false
@@ -177,7 +177,7 @@ jobs:
         run: curl -fsSL https://ollama.com/install.sh | sh
         working-directory: .
       - name: Cache Ollama models
-        uses: actions/cache@v4
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
           path: ~/.ollama/models
           key: ollama-models-qwen2.5-1.5b-nomic-embed-text-v1
@@ -231,7 +231,7 @@ jobs:
           --junitxml=pytest.xml
       - name: Upload test results
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: test-results-misc
           path: ./python/pytest.xml
@@ -283,7 +283,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ inputs.checkout-ref }}
           persist-credentials: false
@@ -294,7 +294,7 @@ jobs:
           python-version: ${{ env.UV_PYTHON }}
           os: ${{ runner.os }}
       - name: Azure CLI Login
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
         with:
           client-id: ${{ secrets.AZURE_CLIENT_ID }}
           tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -315,7 +315,7 @@ jobs:
           --junitxml=pytest.xml
       - name: Upload test results
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: test-results-functions
           path: ./python/pytest.xml
@@ -341,7 +341,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ inputs.checkout-ref }}
           persist-credentials: false
@@ -352,7 +352,7 @@ jobs:
           python-version: ${{ env.UV_PYTHON }}
           os: ${{ runner.os }}
       - name: Azure CLI Login
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
         with:
           client-id: ${{ secrets.AZURE_CLIENT_ID }}
           tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -369,7 +369,7 @@ jobs:
           --junitxml=pytest.xml
       - name: Upload test results
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: test-results-foundry
           path: ./python/pytest.xml
@@ -388,7 +388,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ inputs.checkout-ref }}
           persist-credentials: false
@@ -399,7 +399,7 @@ jobs:
           python-version: ${{ env.UV_PYTHON }}
           os: ${{ runner.os }}
       - name: Azure CLI Login
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
         with:
           client-id: ${{ secrets.AZURE_CLIENT_ID }}
           tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -416,7 +416,7 @@ jobs:
           --junitxml=pytest.xml
       - name: Upload test results
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: test-results-foundry-hosting
           path: ./python/pytest.xml
@@ -443,7 +443,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ inputs.checkout-ref }}
           persist-credentials: false
@@ -468,12 +468,51 @@ jobs:
         run: uv run --directory packages/azure-cosmos poe integration-tests -n logical --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5 --junitxml=${{ github.workspace }}/python/pytest.xml
       - name: Upload test results
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: test-results-cosmos
           path: ./python/pytest.xml
           if-no-files-found: ignore
 
+  # GitHub Copilot integration tests
+  python-tests-github-copilot:
+    name: Python Integration Tests - GitHub Copilot
+    runs-on: ubuntu-latest
+    environment: integration
+    timeout-minutes: 60
+    env:
+      COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+      GITHUB_COPILOT_TIMEOUT: "120"
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
+          persist-credentials: false
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Test with pytest (GitHub Copilot integration)
+        run: >
+          uv run pytest --import-mode=importlib
+          packages/github_copilot/tests
+          -m integration
+          --timeout=120 --session-timeout=900 --timeout_method thread
+          --retries 2 --retry-delay 5
+          --junitxml=pytest.xml
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: test-results-github-copilot
+          path: ./python/pytest.xml
+          if-no-files-found: ignore
+
   # Integration test trend report (aggregates per-job JUnit XML results)
   python-integration-test-report:
     name: Integration Test Report
@@ -490,13 +529,14 @@ jobs:
         python-tests-foundry,
         python-tests-foundry-hosting,
         python-tests-cosmos,
+        python-tests-github-copilot,
       ]
     runs-on: ubuntu-latest
     defaults:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ inputs.checkout-ref }}
           persist-credentials: false
@@ -506,12 +546,12 @@ jobs:
           python-version: ${{ env.UV_PYTHON }}
           os: ${{ runner.os }}
       - name: Download all test results from current run
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
         with:
           pattern: test-results-*
           path: test-results/
       - name: Restore report history cache
-        uses: actions/cache/restore@v4
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
           path: python/integration-report-history.json
           key: integration-report-history-integration-${{ github.run_id }}
@@ -528,13 +568,13 @@ jobs:
         run: cat integration-test-report.md >> $GITHUB_STEP_SUMMARY
       - name: Save report history cache
         if: always()
-        uses: actions/cache/save@v4
+        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
           path: python/integration-report-history.json
           key: integration-report-history-integration-${{ github.run_id }}
       - name: Upload unified trend report
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: integration-test-report
           path: |
@@ -553,17 +593,18 @@ jobs:
         python-tests-functions,
         python-tests-foundry,
         python-tests-foundry-hosting,
-        python-tests-cosmos
+        python-tests-cosmos,
+        python-tests-github-copilot
       ]
     steps:
       - name: Fail workflow if tests failed
         if: contains(join(needs.*.result, ','), 'failure')
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
         with:
           script: core.setFailed('Integration Tests Failed!')
 
       - name: Fail workflow if tests cancelled
         if: contains(join(needs.*.result, ','), 'cancelled')
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
         with:
           script: core.setFailed('Integration Tests Cancelled!')

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

@@ -24,13 +24,17 @@ jobs:
     outputs:
       pythonChanges: ${{ steps.filter.outputs.python}}
     steps:
-      - uses: actions/checkout@v6
-      - uses: dorny/paths-filter@v3
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: dorny/paths-filter@d1c1ffe0248fe513906c8e24db8ea791d46f8590 # v3
         id: filter
         with:
           filters: |
             python:
               - 'python/**'
+              - '!python/AGENTS.md'
+              - '!python/**/AGENTS.md'
+              - '!python/.github/skills/*'
+              - '!python/.github/skills/**'
       # run only if 'python' files were changed
       - name: python tests
         if: steps.filter.outputs.python == 'true'
@@ -59,7 +63,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
       - name: Set up python and install the project
         id: python-setup
@@ -88,13 +92,10 @@ 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()
-        uses: pmeier/pytest-results-action@v0.7.2
+        uses: pmeier/pytest-results-action@20b595761ba9bf89e115e875f8bc863f913bc8ad # v0.7.2
         with:
           path: ./python/packages/lab/**.xml
           summary: true

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

@@ -40,9 +40,10 @@ jobs:
       foundryChanged: ${{ steps.filter.outputs.foundry }}
       foundryHostingChanged: ${{ steps.filter.outputs.foundry_hosting }}
       cosmosChanged: ${{ steps.filter.outputs.cosmos }}
+      githubCopilotChanged: ${{ steps.filter.outputs.github_copilot }}
     steps:
-      - uses: actions/checkout@v6
-      - uses: dorny/paths-filter@v3
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: dorny/paths-filter@d1c1ffe0248fe513906c8e24db8ea791d46f8590 # v3
         id: filter
         with:
           filters: |
@@ -85,6 +86,8 @@ jobs:
               - 'python/packages/foundry_hosting/**'
             cosmos:
               - 'python/packages/azure-cosmos/**'
+            github_copilot:
+              - 'python/packages/github_copilot/**'
       # run only if 'python' files were changed
       - name: python tests
         if: steps.filter.outputs.python == 'true'
@@ -106,7 +109,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       - name: Set up python and install the project
         id: python-setup
         uses: ./.github/actions/python-setup
@@ -123,7 +126,7 @@ jobs:
         working-directory: ./python
       - name: Surface failing tests
         if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
+        uses: pmeier/pytest-results-action@20b595761ba9bf89e115e875f8bc863f913bc8ad # v0.7.2
         with:
           path: ./python/pytest.xml
           summary: true
@@ -153,7 +156,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       - name: Set up python and install the project
         id: python-setup
         uses: ./.github/actions/python-setup
@@ -177,7 +180,7 @@ jobs:
         working-directory: ./python
       - name: Surface failing tests
         if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
+        uses: pmeier/pytest-results-action@20b595761ba9bf89e115e875f8bc863f913bc8ad # v0.7.2
         with:
           path: ./python/pytest.xml
           summary: true
@@ -186,7 +189,7 @@ jobs:
           title: OpenAI integration test results
       - name: Upload test results
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: test-results-openai
           path: ./python/pytest.xml
@@ -214,7 +217,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       - name: Set up python and install the project
         id: python-setup
         uses: ./.github/actions/python-setup
@@ -223,7 +226,7 @@ jobs:
           os: ${{ runner.os }}
       - name: Azure CLI Login
         if: github.event_name != 'pull_request'
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
         with:
           client-id: ${{ secrets.AZURE_CLIENT_ID }}
           tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -247,7 +250,7 @@ jobs:
         working-directory: ./python
       - name: Surface failing tests
         if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
+        uses: pmeier/pytest-results-action@20b595761ba9bf89e115e875f8bc863f913bc8ad # v0.7.2
         with:
           path: ./python/pytest.xml
           summary: true
@@ -256,7 +259,7 @@ jobs:
           title: Azure OpenAI integration test results
       - name: Upload test results
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: test-results-azure-openai
           path: ./python/pytest.xml
@@ -284,7 +287,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       - name: Set up python and install the project
         id: python-setup
         uses: ./.github/actions/python-setup
@@ -295,7 +298,7 @@ jobs:
         run: curl -fsSL https://ollama.com/install.sh | sh
         working-directory: .
       - name: Cache Ollama models
-        uses: actions/cache@v4
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
           path: ~/.ollama/models
           key: ollama-models-qwen2.5-1.5b-nomic-embed-text-v1
@@ -370,7 +373,7 @@ jobs:
           kill -KILL -- "-$server_pid" 2>/dev/null || kill -KILL "$server_pid" 2>/dev/null || true
       - name: Surface failing tests
         if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
+        uses: pmeier/pytest-results-action@20b595761ba9bf89e115e875f8bc863f913bc8ad # v0.7.2
         with:
           path: ./python/pytest.xml
           summary: true
@@ -379,7 +382,7 @@ jobs:
           title: Misc integration test results
       - name: Upload test results
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: test-results-misc
           path: ./python/pytest.xml
@@ -417,7 +420,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       - name: Set up python and install the project
         id: python-setup
         uses: ./.github/actions/python-setup
@@ -426,7 +429,7 @@ jobs:
           os: ${{ runner.os }}
       - name: Azure CLI Login
         if: github.event_name != 'pull_request'
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
         with:
           client-id: ${{ secrets.AZURE_CLIENT_ID }}
           tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -448,7 +451,7 @@ jobs:
         working-directory: ./python
       - name: Surface failing tests
         if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
+        uses: pmeier/pytest-results-action@20b595761ba9bf89e115e875f8bc863f913bc8ad # v0.7.2
         with:
           path: ./python/pytest.xml
           summary: true
@@ -457,7 +460,7 @@ jobs:
           title: Functions integration test results
       - name: Upload test results
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: test-results-functions
           path: ./python/pytest.xml
@@ -488,7 +491,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       - name: Set up python and install the project
         id: python-setup
         uses: ./.github/actions/python-setup
@@ -497,7 +500,7 @@ jobs:
           os: ${{ runner.os }}
       - name: Azure CLI Login
         if: github.event_name != 'pull_request'
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
         with:
           client-id: ${{ secrets.AZURE_CLIENT_ID }}
           tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -515,7 +518,7 @@ jobs:
         working-directory: ./python
       - name: Surface failing tests
         if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
+        uses: pmeier/pytest-results-action@20b595761ba9bf89e115e875f8bc863f913bc8ad # v0.7.2
         with:
           path: ./python/pytest.xml
           summary: true
@@ -524,7 +527,7 @@ jobs:
           title: Test results
       - name: Upload test results
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: test-results-foundry
           path: ./python/pytest.xml
@@ -549,7 +552,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       - name: Set up python and install the project
         id: python-setup
         uses: ./.github/actions/python-setup
@@ -558,7 +561,7 @@ jobs:
           os: ${{ runner.os }}
       - name: Azure CLI Login
         if: github.event_name != 'pull_request'
-        uses: azure/login@v2
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2
         with:
           client-id: ${{ secrets.AZURE_CLIENT_ID }}
           tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -576,7 +579,7 @@ jobs:
         working-directory: ./python
       - name: Surface failing tests
         if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
+        uses: pmeier/pytest-results-action@20b595761ba9bf89e115e875f8bc863f913bc8ad # v0.7.2
         with:
           path: ./python/pytest.xml
           summary: true
@@ -585,7 +588,7 @@ jobs:
           title: Foundry Hosting integration test results
       - name: Upload test results
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: test-results-foundry-hosting
           path: ./python/pytest.xml
@@ -620,7 +623,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       - name: Set up python and install the project
         id: python-setup
         uses: ./.github/actions/python-setup
@@ -643,7 +646,7 @@ jobs:
         working-directory: ./python
       - name: Surface failing tests
         if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
+        uses: pmeier/pytest-results-action@20b595761ba9bf89e115e875f8bc863f913bc8ad # v0.7.2
         with:
           path: ./python/pytest.xml
           summary: true
@@ -652,12 +655,64 @@ jobs:
           title: Cosmos integration test results
       - name: Upload test results
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: test-results-cosmos
           path: ./python/pytest.xml
           if-no-files-found: ignore
 
+  # GitHub Copilot integration tests
+  python-tests-github-copilot:
+    name: Python Tests - GitHub Copilot Integration
+    needs: paths-filter
+    if: >
+      github.event_name != 'pull_request' &&
+      needs.paths-filter.outputs.pythonChanges == 'true' &&
+      (github.event_name != 'merge_group' ||
+       needs.paths-filter.outputs.githubCopilotChanged == 'true' ||
+       needs.paths-filter.outputs.coreChanged == 'true')
+    runs-on: ubuntu-latest
+    environment: integration
+    timeout-minutes: 60
+    env:
+      COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+      GITHUB_COPILOT_TIMEOUT: "120"
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Test with pytest (GitHub Copilot integration)
+        run: >
+          uv run pytest --import-mode=importlib
+          packages/github_copilot/tests
+          -m integration
+          --timeout=120 --session-timeout=900 --timeout_method thread
+          --retries 2 --retry-delay 5
+          --junitxml=pytest.xml
+      - name: Surface failing tests
+        if: always()
+        uses: pmeier/pytest-results-action@20b595761ba9bf89e115e875f8bc863f913bc8ad # v0.7.2
+        with:
+          path: ./python/pytest.xml
+          summary: true
+          display-options: fEX
+          fail-on-empty: false
+          title: GitHub Copilot integration test results
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: test-results-github-copilot
+          path: ./python/pytest.xml
+          if-no-files-found: ignore
+
   # Integration test trend report (aggregates per-job JUnit XML results)
   python-integration-test-report:
     name: Integration Test Report
@@ -674,25 +729,26 @@ jobs:
         python-tests-foundry,
         python-tests-foundry-hosting,
         python-tests-cosmos,
+        python-tests-github-copilot,
       ]
     runs-on: ubuntu-latest
     defaults:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       - name: Set up python and install the project
         uses: ./.github/actions/python-setup
         with:
           python-version: ${{ env.UV_PYTHON }}
           os: ${{ runner.os }}
       - name: Download all test results from current run
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
         with:
           pattern: test-results-*
           path: test-results/
       - name: Restore report history cache
-        uses: actions/cache/restore@v4
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
           path: python/integration-report-history.json
           key: integration-report-history-merge-${{ github.run_id }}
@@ -709,13 +765,13 @@ jobs:
         run: cat integration-test-report.md >> $GITHUB_STEP_SUMMARY
       - name: Save report history cache
         if: always()
-        uses: actions/cache/save@v4
+        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
           path: python/integration-report-history.json
           key: integration-report-history-merge-${{ github.run_id }}
       - name: Upload unified trend report
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: integration-test-report
           path: |
@@ -735,18 +791,19 @@ jobs:
         python-tests-foundry,
         python-tests-foundry-hosting,
         python-tests-cosmos,
+        python-tests-github-copilot,
       ]
     steps:
       - name: Fail workflow if tests failed
         id: check_tests_failed
         if: contains(join(needs.*.result, ','), 'failure')
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
         with:
           script: core.setFailed('Integration Tests Failed!')
 
       - name: Fail workflow if tests cancelled
         id: check_tests_cancelled
         if: contains(join(needs.*.result, ','), 'cancelled')
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
         with:
           script: core.setFailed('Integration Tests Cancelled!')

.github/workflows/python-release.yml

@@ -23,7 +23,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       - name: Set up python and install the project
         id: python-setup
         uses: ./.github/actions/python-setup
@@ -56,7 +56,7 @@ jobs:
       - name: Build the package
         run: uv run poe --directory packages/${{ env.PACKAGE }} build
       - name: Release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2
         with:
           files: |
             python/dist/*

.github/workflows/python-sample-validation.yml

@@ -29,7 +29,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
       - name: Setup environment
         uses: ./.github/actions/sample-validation-setup
@@ -49,7 +49,7 @@ jobs:
           cd scripts && uv run python -m sample_validation --subdir 01-get-started --save-report --report-name 01-get-started
 
       - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         if: always()
         with:
           name: validation-report-01-get-started
@@ -82,7 +82,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
       - name: Setup environment
         uses: ./.github/actions/sample-validation-setup
@@ -111,7 +111,7 @@ jobs:
           cd scripts && uv run python -m sample_validation --subdir 02-agents --exclude providers --save-report --report-name 02-agents
 
       - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         if: always()
         with:
           name: validation-report-02-agents
@@ -130,7 +130,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
       - name: Setup environment
         uses: ./.github/actions/sample-validation-setup
@@ -152,7 +152,7 @@ jobs:
           cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/openai --save-report --report-name 02-agents-openai
 
       - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         if: always()
         with:
           name: validation-report-02-agents-openai
@@ -170,7 +170,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
       - name: Setup environment
         uses: ./.github/actions/sample-validation-setup
@@ -191,7 +191,7 @@ jobs:
           cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/azure --save-report --report-name 02-agents-azure
 
       - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         if: always()
         with:
           name: validation-report-02-agents-azure
@@ -208,7 +208,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
       - name: Setup environment
         uses: ./.github/actions/sample-validation-setup
@@ -228,7 +228,7 @@ jobs:
           cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/anthropic --save-report --report-name 02-agents-anthropic
 
       - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         if: always()
         with:
           name: validation-report-02-agents-anthropic
@@ -242,7 +242,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
       - name: Setup environment
         uses: ./.github/actions/sample-validation-setup
@@ -257,7 +257,7 @@ jobs:
           cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/github_copilot --save-report --report-name 02-agents-github-copilot
 
       - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         if: always()
         with:
           name: validation-report-02-agents-github-copilot
@@ -274,7 +274,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
       - name: Setup environment
         uses: ./.github/actions/sample-validation-setup
@@ -289,7 +289,7 @@ jobs:
           cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/amazon --save-report --report-name 02-agents-amazon
 
       - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         if: always()
         with:
           name: validation-report-02-agents-amazon
@@ -306,7 +306,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
       - name: Setup environment
         uses: ./.github/actions/sample-validation-setup
@@ -321,7 +321,7 @@ jobs:
           cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/ollama --save-report --report-name 02-agents-ollama
 
       - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         if: always()
         with:
           name: validation-report-02-agents-ollama
@@ -341,7 +341,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
       - name: Setup environment
         uses: ./.github/actions/sample-validation-setup
@@ -363,7 +363,7 @@ jobs:
           cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/foundry --save-report --report-name 02-agents-foundry
 
       - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         if: always()
         with:
           name: validation-report-02-agents-foundry
@@ -383,7 +383,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
       - name: Setup environment
         uses: ./.github/actions/sample-validation-setup
@@ -405,7 +405,7 @@ jobs:
           cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/copilotstudio --save-report --report-name 02-agents-copilotstudio
 
       - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         if: always()
         with:
           name: validation-report-02-agents-copilotstudio
@@ -419,7 +419,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
       - name: Setup environment
         uses: ./.github/actions/sample-validation-setup
@@ -434,7 +434,7 @@ jobs:
           cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/custom --save-report --report-name 02-agents-custom
 
       - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         if: always()
         with:
           name: validation-report-02-agents-custom
@@ -451,7 +451,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
       - name: Setup environment
         uses: ./.github/actions/sample-validation-setup
@@ -471,7 +471,7 @@ jobs:
           cd scripts && uv run python -m sample_validation --subdir 03-workflows --save-report --report-name 03-workflows
 
       - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         if: always()
         with:
           name: validation-report-03-workflows
@@ -491,7 +491,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
       - name: Setup environment
         uses: ./.github/actions/sample-validation-setup
@@ -506,7 +506,7 @@ jobs:
           cd scripts && uv run python -m sample_validation --subdir 04-hosting --save-report --report-name 04-hosting
 
       - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         if: always()
         with:
           name: validation-report-04-hosting
@@ -534,7 +534,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
       - name: Setup environment
         uses: ./.github/actions/sample-validation-setup
@@ -549,7 +549,7 @@ jobs:
           cd scripts && uv run python -m sample_validation --subdir 05-end-to-end --save-report --report-name 05-end-to-end
 
       - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         if: always()
         with:
           name: validation-report-05-end-to-end
@@ -574,7 +574,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
       - name: Setup environment
         uses: ./.github/actions/sample-validation-setup
@@ -599,7 +599,7 @@ jobs:
           cd scripts && uv run python -m sample_validation --subdir autogen-migration --save-report --report-name autogen-migration
 
       - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         if: always()
         with:
           name: validation-report-autogen-migration
@@ -633,7 +633,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
       - name: Setup environment
         uses: ./.github/actions/sample-validation-setup
@@ -662,7 +662,7 @@ jobs:
           cd scripts && uv run python -m sample_validation --subdir semantic-kernel-migration --save-report --report-name semantic-kernel-migration
 
       - name: Upload validation report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         if: always()
         with:
           name: validation-report-semantic-kernel-migration
@@ -690,10 +690,10 @@ jobs:
       - validate-autogen-migration
       - validate-semantic-kernel-migration
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
       - name: Download all validation reports
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7
         with:
           pattern: validation-report-*
           path: reports/
@@ -701,7 +701,7 @@ jobs:
 
       - name: Restore validation history
         id: cache-restore
-        uses: actions/cache/restore@v4
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
           path: validation-history/
           key: validation-history-${{ github.run_id }}
@@ -719,13 +719,13 @@ jobs:
         run: cat trend-report.md >> "$GITHUB_STEP_SUMMARY"
 
       - name: Save validation history
-        uses: actions/cache/save@v4
+        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
           path: validation-history/
           key: validation-history-${{ github.run_id }}
 
       - name: Upload trend report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         if: always()
         with:
           name: validation-trend-report

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

@@ -8,6 +8,7 @@ on:
 
 permissions:
   contents: read
+  actions: read
   pull-requests: write
 
 jobs:
@@ -19,36 +20,46 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       - name: Download coverage report
-        uses: actions/download-artifact@v8
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
         with:
-          github-token: ${{ secrets.GH_ACTIONS_PR_WRITE }}
+          github-token: ${{ github.token }}
           run-id: ${{ github.event.workflow_run.id }}
           path: ./python
           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=$(head -1 pr_number | tr -dc '0-9')
-          if [ -z "$PR_NUMBER" ]; then
-            echo "PR number file 'pr_number' does not contain a valid PR number"
+
+          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@v1.6.0
+        uses: MishaKav/pytest-coverage-comment@26f986d2599c288bb62f623d29c2da98609e9cd4 # v1.6.0
         with:
-          github-token: ${{ secrets.GH_ACTIONS_PR_WRITE }}
+          github-token: ${{ github.token }}
           issue-number: ${{ env.PR_NUMBER }}
           pytest-xml-coverage-path: python/python-coverage.xml
           title: "Python Test Coverage Report"

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

@@ -22,7 +22,7 @@ jobs:
     env:
       UV_PYTHON: "3.11"
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       # Save the PR number to a file since the workflow_run event
       # in the coverage report workflow does not have access to it
       - name: Save PR number
@@ -42,7 +42,7 @@ jobs:
       - name: Check coverage threshold
         run: python ${{ github.workspace }}/.github/workflows/python-check-coverage.py python-coverage.xml ${{ env.COVERAGE_THRESHOLD }}
       - name: Upload coverage report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           path: |
             python/python-coverage.xml

.github/workflows/python-tests.yml

@@ -5,6 +5,10 @@ on:
     branches: ["main", "feature*"]
     paths:
       - "python/**"
+      - "!python/AGENTS.md"
+      - "!python/**/AGENTS.md"
+      - "!python/.github/skills/*"
+      - "!python/.github/skills/**"
 env:
   # Configure a constant location for the uv cache
   UV_CACHE_DIR: /tmp/.uv-cache
@@ -27,7 +31,7 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       - name: Set up python and install the project
         id: python-setup
         uses: ./.github/actions/python-setup
@@ -46,7 +50,7 @@ jobs:
       # Surface failing tests
       - name: Surface failing tests
         if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
+        uses: pmeier/pytest-results-action@20b595761ba9bf89e115e875f8bc863f913bc8ad # v0.7.2
         with:
           path: ./python/pytest.xml
           summary: true

.github/workflows/stale-issue-pr-ping.yml

@@ -31,9 +31,9 @@ jobs:
       issues: write
       pull-requests: write
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
           python-version: '3.13'
 

.gitignore

@@ -206,6 +206,7 @@ temp*/
 .temp/
 
 # AI
+**/.checkpoints/
 .claude/
 .omc/
 .omx/
@@ -213,6 +214,7 @@ WARP.md
 **/memory-bank/
 **/projectBrief.md
 **/tmpclaude*
+.kiro/
 # Dependency-bound validation reports
 python/scripts/dependency-*-results.json
 python/scripts/dependencies/dependency-*-results.json
@@ -246,3 +248,6 @@ dotnet/filtered-*.slnx
 # Local tool state
 .omc/
 .omx/
+
+**/issues/
+.test_*

README.md

@@ -6,7 +6,7 @@
 [![MS Learn Documentation](https://img.shields.io/badge/MS%20Learn-Documentation-blue)](https://learn.microsoft.com/en-us/agent-framework/)
 [![PyPI](https://img.shields.io/pypi/v/agent-framework)](https://pypi.org/project/agent-framework/)
 [![NuGet](https://img.shields.io/nuget/v/Microsoft.Agents.AI)](https://www.nuget.org/profiles/MicrosoftAgentFramework/)
-[![GitHub stars](https://img.shields.io/github/stars/microsoft/agent-framework?style=social)](https://github.com/microsoft/agent-framework/stargazers)
+[![GitHub stars](https://img.shields.io/github/stars/microsoft/agent-framework?style=social)](https://github.com/microsoft/agent-framework)
 
 
 Microsoft Agent Framework (MAF) is an open, multi-language framework for building **production-grade AI agents and multi-agent workflows** in **.NET and Python**.

SUPPORT.md

@@ -1,17 +1,17 @@
-# Support
-
-## How to file issues and get help  
-
-This project uses GitHub Issues to track bugs and feature requests. Please search the existing 
-issues before filing new issues to avoid duplicates.  For new issues, file your bug or 
-feature request as a new Issue.
-
-For help and questions about using this project, please create a GitHub issue.
-
-AI Support team will support Microsoft Agent Framework issues for customers under a **Unified support agreement when the issue arises from usage of Azure AI services** (Foundry Models, Foundry Agents etc.) in conjunction with the SDK. Conversely, if customer has any other / non unified support agreement and/or Agent Framework SDK is used in a way **not involving an Azure service**, it is treated as a purely open-source tool – Microsoft’s support organization will not handle it, and users should use GitHub or forums for assistance
-
-For Copilot Studio SDK implementation issues, customers should use GitHub Issues for assistance, as outlined above. Conversely, for prerequisites managed within the Copilot Studio portal, customers can rely on the standard Microsoft Copilot Studio support channels.
-
-## Microsoft Support Policy  
-
-Support for this **PROJECT or PRODUCT** is limited to the resources listed above.
+# Support
+
+## How to file issues and get help  
+
+This project uses GitHub Issues to track bugs and feature requests. Please search the existing 
+issues before filing new issues to avoid duplicates.  For new issues, file your bug or 
+feature request as a new Issue.
+
+For help and questions about using this project, please create a GitHub issue.
+
+AI Support team will support Microsoft Agent Framework issues for customers under a **Unified support agreement when the issue arises from usage of Azure AI services** (Foundry Models, Foundry Agents etc.) in conjunction with the SDK. Conversely, if customer has any other / non unified support agreement and/or Agent Framework SDK is used in a way **not involving an Azure service**, it is treated as a purely open-source tool – Microsoft’s support organization will not handle it, and users should use GitHub or forums for assistance
+
+For Copilot Studio SDK implementation issues, customers should use GitHub Issues for assistance, as outlined above. Conversely, for prerequisites managed within the Copilot Studio portal, customers can rely on the standard Microsoft Copilot Studio support channels.
+
+## Microsoft Support Policy  
+
+Support for this **PROJECT or PRODUCT** is limited to the resources listed above.

declarative-agents/workflow-samples/MathChat.yaml

@@ -11,7 +11,7 @@ trigger:
   kind: OnConversationStart
   id: workflow_demo
   actions:
-
+ 
     - kind: InvokeAzureAgent
       id: question_student
       conversationId: =System.ConversationId

docs/assets/SVG/Microsoft Foundry Agent Framework - Color.svg

@@ -0,0 +1,55 @@
+<svg width="256" height="256" viewBox="0 0 256 256" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="256" height="256" transform="matrix(-1 0 0 1 256 0)" fill="white"/>
+<path d="M163.006 36.0262C155.129 31.4785 145.424 31.4759 137.533 36.0284L104.002 55.3877C107.838 53.2763 112.07 52.2274 116.296 52.2248C120.633 52.2231 124.976 53.3247 128.871 55.5411L174.091 81.6479C175.11 82.2362 175.738 83.3236 175.738 84.5004V151.263C175.738 152.716 177.313 153.621 178.568 152.895L196.967 142.28C204.845 137.732 209.704 129.326 209.704 120.221V77.7299C209.704 68.6342 204.855 60.227 196.967 55.6697L190.983 52.2141C190.65 52.0008 190.313 51.7921 189.969 51.5933L163.006 36.0262Z" fill="url(#paint0_linear_481_4810)"/>
+<path d="M163.006 36.0262C155.129 31.4785 145.424 31.4759 137.533 36.0284L104.002 55.3877C107.838 53.2763 112.07 52.2274 116.296 52.2248C120.633 52.2231 124.976 53.3247 128.871 55.5411L174.091 81.6479C175.11 82.2362 175.738 83.3236 175.738 84.5004V151.263C175.738 152.716 177.313 153.621 178.568 152.895L196.967 142.28C204.845 137.732 209.704 129.326 209.704 120.221V77.7299C209.704 68.6342 204.855 60.227 196.967 55.6697L190.983 52.2141C190.65 52.0008 190.313 51.7921 189.969 51.5933L163.006 36.0262Z" fill="url(#paint1_linear_481_4810)"/>
+<path d="M103.548 55.6397L103.557 55.6451L104.002 55.3877C103.851 55.471 103.698 55.5531 103.548 55.6397Z" fill="url(#paint2_linear_481_4810)"/>
+<path d="M103.548 55.6397L103.557 55.6451L104.002 55.3877C103.851 55.471 103.698 55.5531 103.548 55.6397Z" fill="url(#paint3_linear_481_4810)"/>
+<path d="M116.308 52.2209C111.903 52.2271 107.507 53.3498 103.561 55.6366C95.6702 60.1891 90.8239 68.6019 90.8231 77.6986L90.8223 167.846C90.8222 169.786 92.871 171.041 94.599 170.16L103.523 165.611C116.573 158.959 124.788 145.549 124.788 130.902V62.9894C124.778 58.6476 129.49 55.9209 133.25 58.0698L128.879 55.5453C124.976 53.3242 120.645 52.2192 116.308 52.2209Z" fill="url(#paint4_linear_481_4810)"/>
+<path d="M95.3068 221.682C103.184 226.23 112.889 226.232 120.78 221.68L154.311 202.32C150.475 204.432 146.243 205.481 142.018 205.483C137.68 205.485 133.337 204.383 129.442 202.167L84.2226 176.06C83.2035 175.472 82.5757 174.384 82.5757 173.208L82.5757 106.445C82.5757 104.992 81 104.087 79.7451 104.813L61.3465 115.428C53.4682 119.976 48.6091 128.382 48.6089 137.487L48.6089 179.978C48.6089 189.074 53.4585 197.481 61.3465 202.038L67.3303 205.494C67.6629 205.707 68.0002 205.916 68.3446 206.115L95.3068 221.682Z" fill="url(#paint5_linear_481_4810)"/>
+<path d="M95.3068 221.682C103.184 226.23 112.889 226.232 120.78 221.68L154.311 202.32C150.475 204.432 146.243 205.481 142.018 205.483C137.68 205.485 133.337 204.383 129.442 202.167L84.2226 176.06C83.2035 175.472 82.5757 174.384 82.5757 173.208L82.5757 106.445C82.5757 104.992 81 104.087 79.7451 104.813L61.3465 115.428C53.4682 119.976 48.6091 128.382 48.6089 137.487L48.6089 179.978C48.6089 189.074 53.4585 197.481 61.3465 202.038L67.3303 205.494C67.6629 205.707 68.0002 205.916 68.3446 206.115L95.3068 221.682Z" fill="url(#paint6_linear_481_4810)"/>
+<path d="M154.765 202.068L154.756 202.063L154.311 202.32C154.463 202.237 154.615 202.155 154.765 202.068Z" fill="url(#paint7_linear_481_4810)"/>
+<path d="M154.765 202.068L154.756 202.063L154.311 202.32C154.463 202.237 154.615 202.155 154.765 202.068Z" fill="url(#paint8_linear_481_4810)"/>
+<path d="M142.003 205.487C146.408 205.481 150.805 204.358 154.751 202.071C162.641 197.519 167.488 189.106 167.488 180.009L167.489 89.8618C167.489 87.9222 165.44 86.667 163.712 87.5479L154.788 92.0972C141.739 98.7494 133.523 112.159 133.523 126.806L133.523 194.719C133.533 199.06 128.821 201.787 125.061 199.638L129.432 202.163C133.336 204.384 137.666 205.489 142.003 205.487Z" fill="url(#paint9_linear_481_4810)"/>
+<defs>
+<linearGradient id="paint0_linear_481_4810" x1="207.413" y1="61.882" x2="148.999" y2="163.067" gradientUnits="userSpaceOnUse">
+<stop stop-color="#9189F7"/>
+<stop offset="1" stop-color="#4135E9"/>
+</linearGradient>
+<linearGradient id="paint1_linear_481_4810" x1="188.235" y1="204.189" x2="264.21" y2="152.592" gradientUnits="userSpaceOnUse">
+<stop stop-color="#4F42FD"/>
+<stop offset="1" stop-color="#7274FF"/>
+</linearGradient>
+<linearGradient id="paint2_linear_481_4810" x1="207.413" y1="61.882" x2="148.999" y2="163.067" gradientUnits="userSpaceOnUse">
+<stop stop-color="#9189F7"/>
+<stop offset="1" stop-color="#4135E9"/>
+</linearGradient>
+<linearGradient id="paint3_linear_481_4810" x1="188.235" y1="204.189" x2="264.21" y2="152.592" gradientUnits="userSpaceOnUse">
+<stop stop-color="#4F42FD"/>
+<stop offset="1" stop-color="#7274FF"/>
+</linearGradient>
+<linearGradient id="paint4_linear_481_4810" x1="93.1761" y1="128.826" x2="66.2399" y2="104.746" gradientUnits="userSpaceOnUse">
+<stop offset="0.25" stop-color="#4F42FD"/>
+<stop offset="1" stop-color="#2C08AC"/>
+</linearGradient>
+<linearGradient id="paint5_linear_481_4810" x1="50.9004" y1="195.826" x2="109.315" y2="94.6412" gradientUnits="userSpaceOnUse">
+<stop stop-color="#9189F7"/>
+<stop offset="1" stop-color="#4135E9"/>
+</linearGradient>
+<linearGradient id="paint6_linear_481_4810" x1="70.0787" y1="53.5188" x2="-5.89657" y2="105.116" gradientUnits="userSpaceOnUse">
+<stop stop-color="#4F42FD"/>
+<stop offset="1" stop-color="#7274FF"/>
+</linearGradient>
+<linearGradient id="paint7_linear_481_4810" x1="50.9004" y1="195.826" x2="109.315" y2="94.6412" gradientUnits="userSpaceOnUse">
+<stop stop-color="#9189F7"/>
+<stop offset="1" stop-color="#4135E9"/>
+</linearGradient>
+<linearGradient id="paint8_linear_481_4810" x1="70.0787" y1="53.5188" x2="-5.89657" y2="105.116" gradientUnits="userSpaceOnUse">
+<stop stop-color="#4F42FD"/>
+<stop offset="1" stop-color="#7274FF"/>
+</linearGradient>
+<linearGradient id="paint9_linear_481_4810" x1="165.135" y1="128.882" x2="192.072" y2="152.962" gradientUnits="userSpaceOnUse">
+<stop offset="0.25" stop-color="#4F42FD"/>
+<stop offset="1" stop-color="#2C08AC"/>
+</linearGradient>
+</defs>
+</svg>

docs/assets/SVG/Microsoft Foundry Agent Framework - Fill (Black).svg

@@ -0,0 +1,5 @@
+<svg width="256" height="256" viewBox="0 0 256 256" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="256" height="256" transform="matrix(-1 0 0 1 256 0)" fill="white"/>
+<path d="M167.489 89.8618C167.489 87.9224 165.441 86.667 163.713 87.5473L154.788 92.0971C141.739 98.7493 133.523 112.159 133.523 126.806V194.718C133.533 199.053 128.837 201.777 125.08 199.647L84.2227 176.06C83.2036 175.472 82.5762 174.384 82.5762 173.207V106.445C82.5759 104.992 80.9999 104.087 79.7451 104.813L61.3467 115.428C53.4685 119.976 48.6096 128.382 48.6094 137.487V179.978C48.6094 189.074 53.4588 197.481 61.3467 202.039L67.3301 205.494C67.6627 205.707 68.0004 205.916 68.3447 206.115L95.3066 221.682C103.184 226.23 112.889 226.232 120.779 221.679L154.312 202.32C154.271 202.342 154.23 202.362 154.189 202.384C154.283 202.333 154.375 202.281 154.468 202.229L154.312 202.32C154.463 202.237 154.615 202.154 154.765 202.068L154.762 202.065C162.646 197.511 167.487 189.102 167.488 180.009L167.489 89.8618Z" fill="black"/>
+<path d="M163.007 36.0259C155.13 31.4781 145.424 31.4763 137.533 36.0288L104.002 55.3882C104.029 55.3732 104.057 55.359 104.084 55.3442C104.02 55.3794 103.956 55.4159 103.893 55.4516L104.002 55.3882C103.851 55.4714 103.699 55.5536 103.549 55.6401L103.552 55.6411C95.6664 60.1948 90.8241 68.6053 90.8232 77.6987L90.8223 167.846C90.8223 169.786 92.8707 171.04 94.5986 170.16L103.523 165.611C116.573 158.959 124.788 145.549 124.788 130.902V62.9897C124.778 58.6479 129.49 55.9211 133.25 58.0698L174.091 81.6479C175.11 82.2363 175.737 83.3238 175.737 84.5005V151.263C175.738 152.716 177.314 153.621 178.568 152.895L196.967 142.28C204.845 137.732 209.704 129.326 209.704 120.221V77.73C209.704 68.6343 204.855 60.2267 196.967 55.6694L190.982 52.2143C190.65 52.0011 190.313 51.792 189.969 51.5932L163.007 36.0259Z" fill="black"/>
+</svg>

docs/assets/SVG/Microsoft Foundry Agent Framework - Fill (White).svg

@@ -0,0 +1,5 @@
+<svg width="256" height="256" viewBox="0 0 256 256" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="256" height="256" transform="matrix(-1 0 0 1 256 0)" fill="black"/>
+<path d="M167.489 89.8618C167.489 87.9224 165.441 86.667 163.713 87.5473L154.788 92.0971C141.739 98.7493 133.523 112.159 133.523 126.806V194.718C133.533 199.053 128.837 201.777 125.08 199.647L84.2227 176.06C83.2036 175.472 82.5762 174.384 82.5762 173.207V106.445C82.5759 104.992 80.9999 104.087 79.7451 104.813L61.3467 115.428C53.4685 119.976 48.6096 128.382 48.6094 137.487V179.978C48.6094 189.074 53.4588 197.481 61.3467 202.039L67.3301 205.494C67.6627 205.707 68.0004 205.916 68.3447 206.115L95.3066 221.682C103.184 226.23 112.889 226.232 120.779 221.679L154.312 202.32C154.271 202.342 154.23 202.362 154.189 202.384C154.283 202.333 154.375 202.281 154.468 202.229L154.312 202.32C154.463 202.237 154.615 202.154 154.765 202.068L154.762 202.065C162.646 197.511 167.487 189.102 167.488 180.009L167.489 89.8618Z" fill="white"/>
+<path d="M163.007 36.0259C155.13 31.4781 145.424 31.4763 137.533 36.0288L104.002 55.3882C104.029 55.3732 104.057 55.359 104.084 55.3442C104.02 55.3794 103.956 55.4159 103.893 55.4516L104.002 55.3882C103.851 55.4714 103.699 55.5536 103.549 55.6401L103.552 55.6411C95.6664 60.1948 90.8241 68.6053 90.8232 77.6987L90.8223 167.846C90.8223 169.786 92.8707 171.04 94.5986 170.16L103.523 165.611C116.573 158.959 124.788 145.549 124.788 130.902V62.9897C124.778 58.6479 129.49 55.9211 133.25 58.0698L174.091 81.6479C175.11 82.2363 175.737 83.3238 175.737 84.5005V151.263C175.738 152.716 177.314 153.621 178.568 152.895L196.967 142.28C204.845 137.732 209.704 129.326 209.704 120.221V77.73C209.704 68.6343 204.855 60.2267 196.967 55.6694L190.982 52.2143C190.65 52.0011 190.313 51.792 189.969 51.5932L163.007 36.0259Z" fill="white"/>
+</svg>

docs/assets/SVG/Microsoft Foundry Agent Framework - Stroke (Black).svg

@@ -0,0 +1,4 @@
+<svg width="256" height="256" viewBox="0 0 256 256" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="256" height="256" transform="matrix(-1 0 0 1 256 0)" fill="white"/>
+<path d="M48.6094 179.978V137.487C48.6096 128.382 53.4685 119.976 61.3467 115.428L79.7451 104.813C80.9999 104.087 82.5759 104.992 82.5762 106.445V173.207C82.5762 174.384 83.2036 175.472 84.2227 176.06L125.08 199.647C128.837 201.777 133.533 199.053 133.523 194.718V126.806C133.523 112.388 141.484 99.1684 154.18 92.4135L154.788 92.0971L163.713 87.5473C165.441 86.667 167.489 87.9224 167.489 89.8618L167.488 180.009L167.474 180.86C167.181 189.624 162.399 197.653 154.762 202.065L154.765 202.068C154.615 202.154 154.463 202.237 154.312 202.32L154.468 202.229C154.375 202.281 154.283 202.333 154.189 202.384C154.23 202.362 154.271 202.342 154.312 202.32L120.779 221.679L120.034 222.092C112.534 226.093 103.539 226.092 96.0508 222.095L95.3066 221.682L68.3447 206.115C68.0004 205.916 67.6627 205.707 67.3301 205.494L61.3467 202.039C53.7053 197.624 48.9149 189.595 48.623 180.829L48.6094 179.978ZM175.737 84.5005C175.737 83.3974 175.186 82.3728 174.277 81.7641L174.091 81.6479L133.25 58.0698C129.49 55.9211 124.778 58.6479 124.788 62.9897V130.902L124.782 131.587C124.53 145.966 116.369 159.063 103.523 165.611L94.5986 170.16L94.4355 170.236C92.799 170.938 90.9459 169.803 90.8281 168.026L90.8223 167.846L90.8232 77.6987C90.8241 68.6053 95.6664 60.1948 103.552 55.6411L103.549 55.6401C103.699 55.5536 103.851 55.4714 104.002 55.3882L103.893 55.4516C103.956 55.4159 104.02 55.3794 104.084 55.3442C104.057 55.359 104.029 55.3732 104.002 55.3882L137.533 36.0288C145.424 31.4763 155.13 31.4781 163.007 36.0259L189.969 51.5932C190.313 51.792 190.65 52.0011 190.982 52.2143L196.967 55.6694C204.855 60.2267 209.704 68.6343 209.704 77.73V120.221L209.689 121.073C209.397 129.848 204.599 137.874 196.967 142.28L178.568 152.895C177.314 153.621 175.738 152.716 175.737 151.263V84.5005ZM176.814 149.866L176.819 149.864L176.832 149.856C176.826 149.859 176.82 149.862 176.814 149.866ZM137.023 194.71L137.019 195.038C136.802 201.878 129.341 206.087 123.354 202.692L123.33 202.678L82.4727 179.091C80.3698 177.877 79.0762 175.634 79.0762 173.207V109.239L63.0957 118.458C56.5124 122.259 52.3745 129.183 52.1221 136.752L52.1094 137.487V179.978C52.1094 187.823 56.2909 195.075 63.0957 199.007H63.0967L69.0801 202.462L69.1504 202.503L69.2188 202.547C69.5212 202.741 69.8111 202.92 70.0947 203.083L97.0566 218.651L97.6982 219.007C104.372 222.569 112.434 222.453 119.029 218.648L152.514 199.316L152.512 199.312C152.581 199.274 152.65 199.236 152.752 199.178L152.753 199.181C152.775 199.169 152.796 199.158 152.815 199.147L153.011 199.035C159.81 195.107 163.987 187.854 163.988 180.009V91.3344L156.378 95.2153C144.501 101.27 137.023 113.475 137.023 126.806V194.71ZM94.3223 166.372L101.934 162.493C113.811 156.438 121.288 144.233 121.288 130.902V62.9897C121.278 55.9521 128.901 51.5532 134.986 55.0307L135 55.0385L175.841 78.6167L176.036 78.7339C178.023 79.9714 179.237 82.15 179.237 84.5005V148.468L195.217 139.249C202.013 135.326 206.204 128.075 206.204 120.221V77.73C206.204 69.8848 202.022 62.6318 195.217 58.6997L189.232 55.2456L189.162 55.2046L189.094 55.1606C188.788 54.9649 188.5 54.787 188.219 54.6245L161.257 39.0571C154.463 35.135 146.091 35.1311 139.282 39.0591L139.283 39.06L105.765 58.4106L105.767 58.4135C105.713 58.443 105.723 58.4383 105.602 58.5063L105.6 58.5034C105.535 58.5391 105.481 58.5691 105.433 58.5962L105.302 58.6723C98.5016 62.5995 94.324 69.8532 94.3232 77.6987L94.3223 166.372Z" fill="black"/>
+</svg>

docs/assets/SVG/Microsoft Foundry Agent Framework - Stroke (White).svg

@@ -0,0 +1,4 @@
+<svg width="256" height="256" viewBox="0 0 256 256" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="256" height="256" transform="matrix(-1 0 0 1 256 0)" fill="black"/>
+<path d="M48.6094 179.978V137.487C48.6096 128.382 53.4685 119.976 61.3467 115.428L79.7451 104.813C80.9999 104.087 82.5759 104.992 82.5762 106.445V173.207C82.5762 174.384 83.2036 175.472 84.2227 176.06L125.08 199.647C128.837 201.777 133.533 199.053 133.523 194.718V126.806C133.523 112.388 141.484 99.1684 154.18 92.4135L154.788 92.0971L163.713 87.5473C165.441 86.667 167.489 87.9224 167.489 89.8618L167.488 180.009L167.474 180.86C167.181 189.624 162.399 197.653 154.762 202.065L154.765 202.068C154.615 202.154 154.463 202.237 154.312 202.32L154.468 202.229C154.375 202.281 154.283 202.333 154.189 202.384C154.23 202.362 154.271 202.342 154.312 202.32L120.779 221.679L120.034 222.092C112.534 226.093 103.539 226.092 96.0508 222.095L95.3066 221.682L68.3447 206.115C68.0004 205.916 67.6627 205.707 67.3301 205.494L61.3467 202.039C53.7053 197.624 48.9149 189.595 48.623 180.829L48.6094 179.978ZM175.737 84.5005C175.737 83.3974 175.186 82.3728 174.277 81.7641L174.091 81.6479L133.25 58.0698C129.49 55.9211 124.778 58.6479 124.788 62.9897V130.902L124.782 131.587C124.53 145.966 116.369 159.063 103.523 165.611L94.5986 170.16L94.4355 170.236C92.799 170.938 90.9459 169.803 90.8281 168.026L90.8223 167.846L90.8232 77.6987C90.8241 68.6053 95.6664 60.1948 103.552 55.6411L103.549 55.6401C103.699 55.5536 103.851 55.4714 104.002 55.3882L103.893 55.4516C103.956 55.4159 104.02 55.3794 104.084 55.3442C104.057 55.359 104.029 55.3732 104.002 55.3882L137.533 36.0288C145.424 31.4763 155.13 31.4781 163.007 36.0259L189.969 51.5932C190.313 51.792 190.65 52.0011 190.982 52.2143L196.967 55.6694C204.855 60.2267 209.704 68.6343 209.704 77.73V120.221L209.689 121.073C209.397 129.848 204.599 137.874 196.967 142.28L178.568 152.895C177.314 153.621 175.738 152.716 175.737 151.263V84.5005ZM176.814 149.866L176.819 149.864L176.832 149.856C176.826 149.859 176.82 149.862 176.814 149.866ZM137.023 194.71L137.019 195.038C136.802 201.878 129.341 206.087 123.354 202.692L123.33 202.678L82.4727 179.091C80.3698 177.877 79.0762 175.634 79.0762 173.207V109.239L63.0957 118.458C56.5124 122.259 52.3745 129.183 52.1221 136.752L52.1094 137.487V179.978C52.1094 187.823 56.2909 195.075 63.0957 199.007H63.0967L69.0801 202.462L69.1504 202.503L69.2188 202.547C69.5212 202.741 69.8111 202.92 70.0947 203.083L97.0566 218.651L97.6982 219.007C104.372 222.569 112.434 222.453 119.029 218.648L152.514 199.316L152.512 199.312C152.581 199.274 152.65 199.236 152.752 199.178L152.753 199.181C152.775 199.169 152.796 199.158 152.815 199.147L153.011 199.035C159.81 195.107 163.987 187.854 163.988 180.009V91.3344L156.378 95.2153C144.501 101.27 137.023 113.475 137.023 126.806V194.71ZM94.3223 166.372L101.934 162.493C113.811 156.438 121.288 144.233 121.288 130.902V62.9897C121.278 55.9521 128.901 51.5532 134.986 55.0307L135 55.0385L175.841 78.6167L176.036 78.7339C178.023 79.9714 179.237 82.15 179.237 84.5005V148.468L195.217 139.249C202.013 135.326 206.204 128.075 206.204 120.221V77.73C206.204 69.8848 202.022 62.6318 195.217 58.6997L189.232 55.2456L189.162 55.2046L189.094 55.1606C188.788 54.9649 188.5 54.787 188.219 54.6245L161.257 39.0571C154.463 35.135 146.091 35.1311 139.282 39.0591L139.283 39.06L105.765 58.4106L105.767 58.4135C105.713 58.443 105.723 58.4383 105.602 58.5063L105.6 58.5034C105.535 58.5391 105.481 58.5691 105.433 58.5962L105.302 58.6723C98.5016 62.5995 94.324 69.8532 94.3232 77.6987L94.3223 166.372Z" fill="white"/>
+</svg>

docs/decisions/0007-agent-filtering-middleware.md

@@ -1125,7 +1125,7 @@ Naming (Python): N/A (Composable Components)
 Supports: N  
 Observation: No explicit middleware/filters; modularity allows composable units but no dedicated interception hooks or callbacks for custom reading/modification mid-execution.
 
-For more details, see the official documentation: [Atomic Agents Docs](https://brainblend-ai.github.io/atomic-agents/). No specific code examples available for interception.
+No specific code examples available for interception.
 
 #### Smolagents (Hugging Face)
 

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

@@ -43,6 +43,11 @@ FIDES (Flow Integrity Deterministic Enforcement System) is a label-based securit
 3. **Variable Indirection** — `ContentVariableStore` and `VariableReferenceContent` for physical isolation of untrusted content from the LLM context.
 4. **Quarantined Execution** — `quarantined_llm` and `inspect_variable` tools for isolated processing of untrusted data with audit logging.
 
+In addition, remote MCP integrations are secured through two mechanisms:
+
+- **Hint-based tool auto-labeling**: MCP `ToolAnnotations` (`readOnlyHint`, `openWorldHint`, etc.) are mapped to FIDES tool properties (`source_integrity`, `accepts_untrusted`, `max_allowed_confidentiality`).
+- **Server `_meta.ifc` result labels**: MCP result metadata is parsed into per-item `security_label` values, so provider-supplied IFC labels are enforced by middleware.
+
 ### Consequences
 
 - Good, because it provides deterministic security guarantees about what untrusted content can influence.
@@ -117,6 +122,13 @@ Monitor agent behavior and block suspicious actions post-facto.
 - Uses existing `FunctionMiddleware` base class.
 - Attaches labels via `additional_properties` (no schema changes).
 - Leverages `SerializationMixin` for label persistence.
+- Integrates MCP hint/result metadata through `additional_properties` keys (`max_allowed_confidentiality`, `source_integrity`, `__mcp_result_meta__`) without transport-specific policy code in core middleware.
+
+### MCP-Specific Security Notes
+
+- `SecureMCPToolProxy` applies `apply_mcp_security_labels(...)` automatically when connecting an MCP tool or URL.
+- For servers like the GitHub MCP server (with `X-MCP-Features: ifc_labels`), `_meta.ifc` labels are considered authoritative for per-result label assignment.
+- Tools that are not explicitly `readOnlyHint=True` are treated as potential sinks and default to `max_allowed_confidentiality=PUBLIC` to prevent exfiltration.
 
 
 ### Backwards Compatibility

docs/decisions/0026-hosted-session-identity-context.md

@@ -0,0 +1,86 @@
+---
+status: superseded by [ADR-0030](0030-hosted-platform-context-agentserver-2.0.md)
+contact: rogerbarreto
+date: 2026-06-29
+deciders: rogerbarreto
+consulted: []
+informed: []
+---
+
+# Hosted session identity context for Foundry Hosting
+
+> **Superseded by [ADR-0030](0030-hosted-platform-context-agentserver-2.0.md).** `Azure.AI.AgentServer.*` 2.0.0 (responses protocol `2.0.0`) replaced `ResponseContext.Isolation` (`UserIsolationKey` / `ChatIsolationKey`, headers `x-agent-user-isolation-key` / `x-agent-chat-isolation-key`) with `ResponseContext.PlatformContext` (`UserIdKey` / `CallId`, headers `x-agent-user-id` / `x-agent-foundry-call-id`). The chat isolation key was removed and `HostedSessionContext` is now user-only. This ADR is retained as the historical record of the original design.
+
+## Context and Problem Statement
+
+Server-hosted Foundry agents need a way to scope per-user state (most notably `FoundryMemoryProvider` memories) by the end user that initiated the request. The Foundry platform already injects `x-agent-user-isolation-key` and `x-agent-chat-isolation-key` headers on every Responses request, but the agent-framework hosting layer did not surface those values to `AIContextProvider` instances. The provider's `stateInitializer` only received an `AgentSession?` with no identity attached, so per-user scoping was impossible without out-of-band plumbing.
+
+## Decision Drivers
+
+- Memory and any future user-private context must be partitioned per end user without per-sample boilerplate.
+- The identity must be **read-only** from the perspective of `AIContextProvider`s, so a buggy or hostile provider cannot escalate or leak across users.
+- The persisted session must validate against the live request on every resume to defend against session-id leak and in-process tampering.
+- The change must work for every existing hosted-agent type (`ChatClientAgent`, `FoundryAgent`, future ones) without per-type refactoring of cast-heavy code paths in `Microsoft.Agents.AI`.
+- Local Docker debugging must remain possible when the platform headers are absent.
+
+## Considered Options
+
+1. **`HostedSessionContext` stored in `AgentSessionStateBag`, exposed via a public read accessor and an `internal` setter.** Hosting writes once on session creation and validates on every resume.
+2. **Specialised `HostedAgentSession : AgentSession` wrapper** that carries `UserId`/`ChatId` properties, with `GetService<ChatClientAgentSession>()` as the unwrap escape hatch.
+3. **New property on `AgentSession` base class** (`HostedSessionContext? HostedContext { get; internal set; }`).
+4. **AsyncLocal middleware** that reads the headers and stuffs them into a per-request `AsyncLocal<HostedSessionContext>` consumed by the provider.
+
+For the source of identity:
+- A. The platform-injected `IsolationContext` exposed by `ResponseContext.Isolation` (typed `UserIsolationKey`/`ChatIsolationKey`).
+- B. The OpenAI Responses spec's top-level `request.User` field.
+- C. A custom HTTP header `x-client-user`.
+
+## Decision Outcome
+
+**Option 1** was chosen for the storage shape, sourced from **Option A** (`ResponseContext.Isolation`).
+
+Rationale:
+
+- **Wrapper rejected (Option 2).** `ChatClientAgentSession` is `sealed` and `ChatClientAgent` rejects any other session type via direct `is not ChatClientAgentSession` checks at multiple call sites. Wrapping would force non-trivial refactors across `Microsoft.Agents.AI` and a corresponding repeat for every other agent type.
+- **Base-class property rejected (Option 3).** Leaks "hosted" semantics into the universal `AgentSession` abstraction used by Durable, A2A, and CopilotStudio agents that have no notion of a hosted user.
+- **AsyncLocal rejected (Option 4).** Surfaces the concept only locally, requires every consumer to re-implement the bridge, and cannot be enforced as read-only.
+- **`request.User` rejected (Option B).** Set by the caller, not the platform. Forging it client-side trivially defeats per-user partitioning.
+- **`x-client-user` rejected (Option C).** Non-standard, requires custom HTTP plumbing, and duplicates the platform-provided isolation contract.
+
+Implementation summary in `Microsoft.Agents.AI.Foundry.Hosting`:
+
+| Type | Visibility | Purpose |
+|---|---|---|
+| `HostedSessionContext` | public sealed | Captures `UserId` and `ChatId` (both required, non-whitespace). |
+| `HostedSessionContextExtensions.GetHostedContext` | public | Read accessor for `AIContextProvider`s. |
+| `HostedSessionContextExtensions.SetHostedContext` | internal | Writer reserved for the hosting assembly. Backed by `AgentSessionStateBag` under a well-known key for serialisation. |
+| `HostedSessionIsolationKeyProvider` (abstract) | public | DI-resolvable factory. Async signature: `ValueTask<HostedSessionContext?> GetKeysAsync(ResponseContext, CreateResponse, CancellationToken)`. |
+| `PlatformHostedSessionIsolationKeyProvider` | internal sealed | Default implementation. Maps `context.Isolation.UserIsolationKey` and `context.Isolation.ChatIsolationKey`. Returns `null` when either is absent. |
+
+Behaviour added to `AgentFrameworkResponseHandler.CreateAsync`:
+
+1. Resolve `HostedSessionIsolationKeyProvider` from DI; fall back to `PlatformHostedSessionIsolationKeyProvider`.
+2. Call `GetKeysAsync(context, request, cancellationToken)`. A `null` result throws `InvalidOperationException` (becomes 500). A null/whitespace `UserId` or `ChatId` is rejected by `HostedSessionContext`'s constructor.
+3. Branch on the **session's existing context**, not on whether a `conversation_id` was supplied:
+   - **No session (`session is null`):** nothing to stamp; skip.
+   - **Session present but un-stamped (`GetHostedContext() is null`):** treat as fresh. This covers both newly-created sessions and pre-existing sessions whose `conversation_id` was provisioned externally (e.g. via `conversations.CreateProjectConversationAsync()`) before the first hosted-agent request. Stamp the resolved identity now.
+   - **Session present with stamped context:** strict resume. The persisted `UserId` and `ChatId` must equal the resolved values exactly. Mismatch throws `ResponsesApiException` with status 403 and body `Hosted session identity context mismatch`.
+
+## Consequences
+
+Positive:
+
+- Per-user memory partitioning works out of the box for any agent that consumes a `Microsoft.Agents.AI.Foundry.FoundryMemoryProvider` configured to read `session.GetHostedContext().UserId`.
+- Cross-user session-id leak and in-process tampering of the persisted identity both surface as a 403 with a deliberately uninformative body.
+- The identity is opaque to the framework, matching the platform's semantics. The framework never inspects user identity; the `IsolationContext` keys are pre-partitioned per agent.
+
+Negative:
+
+- Every existing hosted sample fails locally without a `HostedSessionIsolationKeyProvider` registered, because the platform headers are absent outside the platform. Mitigated by shipping `Hosted_Shared_Contributor_Setup` with `DevTemporaryLocalSessionIsolationKeyProvider` and `AddDevTemporaryLocalContributorSetup`, and migrating all 9 existing responses samples.
+- An attacker who can plant an un-stamped session under a victim's `conversation_id` *before* the victim's first hosted-agent request would be stamped with the attacker's identity on that first request. This is not a regression vs. behaviour without this contract, and is mitigated in practice because the `conversation_id` namespace is allocated by the platform per project. Once a session is stamped, the strict equality check fully defends the resume path.
+
+## Out of scope
+
+- Per-request `User` field on `CreateResponse` is intentionally not consumed; only the platform `IsolationContext` headers carry trustworthy identity.
+- Generic (non-Foundry) hosting layers can re-define an equivalent type if needed; nothing in this ADR is moved into `Microsoft.Agents.AI.Hosting` because `Microsoft.Agents.AI.Foundry.Hosting` does not depend on it.
+- HMAC tamper signatures over the persisted context are not implemented; comparison against `ResponseContext.Isolation` on every request is sufficient because the platform sets those headers at the trust boundary.

docs/decisions/0027-hosting-channels.md

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

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

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

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

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

docs/decisions/0029-python-agent-session-identity.md

@@ -0,0 +1,356 @@
+---
+status: accepted
+contact: eavanvalkenburg
+date: 2026-06-19
+deciders: eavanvalkenburg, moonbox3, TaoChenOSU, chetantoshnival
+consulted: westey-m
+informed:
+---
+
+# Python identity lifetimes for sessions, tasks, and continuation
+
+## Context and Problem Statement
+
+Python `AgentSession` currently carries a local `session_id`, an optional opaque service continuation
+`service_session_id`, and provider state. `service_session_id` is any service-owned value that lets that service continue
+a conversation, session, or thread; chat clients happen to map it through the abstract `conversation_id` ChatOption, but
+other agent types can use it differently. It is not a generic correlation field, and generic correlation should not
+require parsing or understanding that opaque service-owned value.
+
+The related issues mix values with different lifetimes:
+
+- **Session / conversation identity**: values that group a multi-turn interaction. Examples: A2A `context_id`, OpenAI
+  Responses `conversation` (`conv_*`) or response-chain continuation (`previous_response_id`).
+- **Task identity**: values that identify a protocol task and may affect future protocol calls. Example: A2A `task_id`.
+- **Message / response identity**: values that identify an output message or response. Examples: A2A `message_id` /
+  `artifact_id`, OpenAI Responses response id (`resp_*`).
+- **Continuation token**: a framework resume payload for in-progress work. It may contain the same underlying value as a
+  protocol id, such as A2A `task_id`, but it only exists when there is an unfinished operation to resume.
+
+These values should not automatically live in the same object just because they all help "continue" something. A value
+belongs in `AgentSession` only when it is needed to continue future calls across turns. A value that identifies one
+result belongs on the response or message. A value that resumes in-progress work belongs in a `ContinuationToken`.
+
+An `AgentSession` created for one agent is not expected to be guaranteed to work against another agent. When a session is
+used with an incompatible agent, protocol, or service, the framework should still help users understand what is wrong as
+early as possible, preferably before calling out to the remote service.
+
+For #4673, native conversation identity propagation should be based on `AgentSession` where the value is durable session
+state. For #4893, A2A `context_id` and `task_id` need a coherent Agent Framework mapping.
+
+AG-UI is out of scope for the decision. Its `thread_id` already maps to `AgentSession.session_id` in the normal wrapper
+path, and `run_id` is wrapper-owned event correlation. If AG-UI run correlation needs framework telemetry integration
+later, that should be handled as a run-context/telemetry design, not as session identity.
+
+### Concrete gap example
+
+At the protocol level, the durable continuation payload shapes are different:
+
+```json
+// A2A: future calls may need multiple durable protocol fields
+{
+  "context_id": "ctx_123",
+  "task_id": "task_789",
+  "task_state": "input_required"
+}
+```
+
+```json
+// OpenAI Responses: future calls usually need one continuation value
+{
+  "previous_response_id": "resp_abc123"
+}
+```
+
+The gap is that A2A continuation state is multi-field while OpenAI continuation is
+typically single-field.
+
+## Current implementation notes
+
+- A2A currently has `A2AAgentSession`, but `A2AAgent.create_session(...)` does not automatically return it.
+- A2A currently mirrors `context_id` into `service_session_id`; that is current behavior, not necessarily the target
+  abstraction.
+- A2A `task_id` is not just cosmetic correlation. It is used for `task_id` when a task is `INPUT_REQUIRED`, for
+  `reference_task_ids` when refining a previous task, and inside `A2AContinuationToken` for in-progress tasks.
+- `RawAgent._prepare_run_context(...)` currently forwards `active_session.service_session_id` as chat `conversation_id`,
+  so any non-string or formatted value affects existing chat-client paths.
+- `OpenAIChatClient` maps chat options `conversation_id` to the Responses API as `previous_response_id` for `resp_*`,
+  `conversation` for `conv_*`, and defaults unrecognized strings to `previous_response_id`. When `store` is not `False`,
+  it returns `response.conversation.id` when available, otherwise `response.id`, as the next service continuation value.
+- For Responses API, the response id (`resp_*`) is also the response/message identity surfaced as
+  `ChatResponse.response_id`; when used for continuation on the next request, it becomes the `previous_response_id`
+  value.
+- Python A2A has not been released as stable yet, so its session factory or session shape can still be adjusted before
+  release.
+
+## Decision Drivers
+
+- Preserve `AgentSession.session_id` as the local/client conversation identity.
+- Preserve `AgentSession.service_session_id` as an opaque service-owned continuation handle.
+- Keep `AgentSession` for durable state needed across turns, not per-run bookkeeping.
+- Store values needed by future calls in durable session state; keep values that only resume in-progress work in
+  `ContinuationToken`.
+- Fix the current confusion where session, task, response, and continuation values can be treated as interchangeable
+  because they all participate in "continuing" something.
+- Make the implementation following this ADR preserve the lifetime split clearly: future-call state, in-progress resume
+  tokens, response/message ids, and protocol event correlation must not be silently mixed.
+- Expose durable continuation state in a typed way when future calls depend on it.
+- Let telemetry correlate runs without parsing opaque service continuation handles.
+- Reuse existing run/context surfaces before introducing a new identity abstraction.
+- Keep MCP and other remote tool boundaries safe: framework identity must not be forwarded to remote tools unless an
+  existing explicit opt-in mechanism says so.
+- Keep existing `AgentSession.to_dict()` / `from_dict()` migration and compatibility straightforward.
+- Stay close to .NET where there is already behavior to match, especially A2A's `ContextId`, `TaskId`, and `TaskState`.
+- Detect incompatible session identity shapes as early as practical, preferably before a remote service call.
+
+## Non-goals
+
+- Do not design a provider-agnostic conversation creation API here. That is tracked separately in #6622.
+- Do not make `service_session_id` a generic telemetry or run-correlation field.
+- Do not introduce a new identity object if existing run/context objects can carry the selected per-run correlation value.
+- Do not make a session from one agent guaranteed to work against another agent.
+- Do not optimize the public `agent.run(...)` API for protocol-wrapper internals.
+
+## Remaining question: durable shape for additional continuation state
+
+- Option A: Use protocol-specific `AgentSession` subclasses.
+- Option B: Extend `service_session_id` with richer service-owned values.
+- Option C: Add a dedicated dict for additional session details.
+- Option D: Store additional durable state inside `AgentSession.state`.
+
+### Option A: Use protocol-specific `AgentSession` subclasses
+
+Each protocol or agent type that needs additional durable state keeps a specialized `AgentSession` subclass. For A2A,
+that means keeping `A2AAgentSession` for A2A-specific durable state and changing `A2AAgent.create_session(...)` to return
+that type.
+
+Example:
+
+```python
+# First call returns a task that future A2A messages may need to reference.
+session = await a2a_agent.create_session()
+
+response = await a2a_agent.run(
+    message,
+    session=session,
+)
+
+# A2AAgent updates durable A2A protocol state from the returned task/status payload.
+# The user does not set these manually.
+assert isinstance(session, A2AAgentSession)
+assert session.task_id is not None
+assert session.task_state is not None
+
+# Later call reuses the durable A2A session state. A2AAgent decides whether to send task_id
+# for INPUT_REQUIRED or reference_task_ids for task refinement.
+next_response = await a2a_agent.run(
+    next_message,
+    session=session,
+)
+```
+
+- Good, because protocol-specific state stays in a protocol-specific type.
+- Good, because it aligns with .NET A2A's `A2AAgentSession` shape.
+- Good, because Python A2A can still make this pre-release session factory adjustment.
+- Good, because `task_state` does not get promoted to a base `AgentSession` concept.
+- Bad, because generic consumers cannot read protocol-specific state without knowing about the subclass or a helper API.
+- Bad, because it depends on each subclass consistently setting shared session fields such as `service_session_id` where
+  those are part of the shared abstraction.
+
+### Option B: Extend `service_session_id` with richer service-owned values
+
+Keep the common `service_session_id` case as a plain string. When an agent/service needs more than one service-owned
+continuation value, allow `service_session_id` to be a typed structured value, such as a `TypedDict`. The main session ID
+used for `gen_ai.conversation.id` should still be extracted by the owning agent, not inferred by generic telemetry code.
+
+Examples:
+
+```python
+simple_session = AgentSession(
+    service_session_id="resp_123",
+)
+
+structured_session = AgentSession(
+    service_session_id=A2AServiceSessionId(
+        context_id="ctx_123",
+        task_id="task_789",
+        task_state=TaskState.TASK_STATE_WORKING,
+    ),
+)
+```
+
+- Good, because the common case remains a plain string and stays simple.
+- Good, because richer service-owned continuation state stays under the existing continuation property.
+- Good, because a structured value can make framework-side validation possible before a value is sent back to a service.
+- Good, because A2A can keep `context_id`, `task_id`, and `task_state` together as the service/protocol-owned continuation
+  value without adding A2A fields to base `AgentSession`.
+- Neutral, because telemetry needs an agent-owned extractor to pick the `gen_ai.conversation.id` value from either a
+  string or structured `service_session_id`.
+- Neutral, because Python A2A would need a pre-release adjustment to stop relying on `A2AAgentSession` for these fields.
+- Bad, because changing the `service_session_id` type is a compatibility risk for users, providers, serialization, and
+  tests.
+- Bad, because every path that sends `service_session_id` back to a service must consistently extract/adapt the
+  service-owned continuation component.
+
+### Option C: Add a dedicated dict for additional session details
+
+Keep `service_session_id` as the primary opaque service-owned continuation handle, and add a separate dictionary for
+additional durable protocol/service values that need to travel with the session.
+
+Example:
+
+```python
+session = AgentSession(
+    service_session_id="ctx_123",
+    session_details={
+        "task_id": "task_456",
+        "task_state": TaskState.TASK_STATE_WORKING,
+    },
+)
+```
+
+- Good, because the main service continuation handle stays a plain `service_session_id` string.
+- Good, because extra state has an explicit home and does not overload `service_session_id`.
+- Good, because generic consumers can look in one documented place for additional session-scoped values.
+- Neutral, because helper APIs can hide the raw dictionary access.
+- Bad, because this still introduces string-keyed state unless the dict values are wrapped by typed helpers.
+- Bad, because it adds another public session field that needs serialization, naming, and compatibility rules.
+- Bad, because generic consumers still need to understand the shape or use helpers for the selected agent/session type.
+
+### Option D: Store additional durable state inside `AgentSession.state`
+
+Keep base `AgentSession` unchanged and store additional durable continuation/protocol state under namespaced keys in
+`session.state`.
+
+Example:
+
+```python
+session = AgentSession(session_id="ctx_123")
+
+session.state["a2a"] = {
+    "task_id": "task_456",
+    "task_state": TaskState.TASK_STATE_WORKING,
+}
+```
+
+- Good, because it avoids new public fields and avoids a subclass requirement.
+- Good, because `AgentSession.state` already exists for provider/session state.
+- Neutral, because helper APIs can hide the raw dictionary access.
+- Bad, because stringly typed state is easier to corrupt and harder to validate.
+- Bad, because generic consumers need helper APIs anyway; directly reading nested dictionaries is not a good abstraction.
+- Bad, because users may accidentally overwrite or persist invalid protocol state.
+
+## Decision
+
+Chosen decision criteria for the future: **split identity by lifecycle**.
+
+When a protocol emits an id/token, place it by answering "what lifecycle does this value serve?":
+
+- **Future-call continuation state** -> durable session state. Examples: A2A `context_id` + `task_id` + `task_state`;
+  OpenAI Responses `previous_response_id`/`conversation`.
+- **Single-result identity** -> response/message object only. Examples: OpenAI `resp_*`, A2A `message_id`,
+  A2A `artifact_id`.
+- **Resume unfinished work** -> `ContinuationToken` only. Example: a token carrying in-progress task resume data.
+- **Run-start-only request fields** -> run method arguments/options, not durable session state. Example: A2A
+  `reference_task_ids` for a specific follow-up/refinement request.
+- **Per-run correlation/telemetry** -> protocol wrapper or run context, not `AgentSession`. Example: wrapper-managed
+  `run_id` used only for tracing/events.
+
+Durable-state option decision: **Option B: Extend `service_session_id` with richer service-owned values**.
+This does **not** add a new top-level identity abstraction; it keeps continuation identity under
+`service_session_id` and keeps run correlation in existing run/telemetry context.
+The immediate implementation gap is mainly in A2A mapping clarity, but the lifecycle split applies
+consistently across providers.
+
+To support telemetry, `BaseAgent` should expose a method that accepts an `AgentSession | None` and returns the value to
+use for `gen_ai.conversation.id`. The default implementation should return `session.service_session_id` when it is a
+string. Agents that use a structured `service_session_id`, such as `A2AAgent`, should override that method and return the
+appropriate primary session/context value.
+
+## Appendix: A2A `task_id` and `reference_task_ids` implementation check
+
+The A2A protocol distinguishes a message's `task_id` from `reference_task_ids`:
+
+- `task_id` associates the message with a specific task.
+- `reference_task_ids` provides additional task context, for example when a new task refines or follows up on the result
+  of a previous task.
+
+The protocol does not appear to prescribe that `task_id` and `reference_task_ids` are mutually exclusive. If both are
+present, the natural reading is that the message is associated with one task while also referencing other tasks for
+context. The serving agent decides how to interpret that context.
+
+The Python implementation should check and likely adjust the current behavior:
+
+- `task_id` should be updated by the current run when the remote A2A service returns a task/status payload.
+- `task_id` should remain durable A2A session state when needed for future calls, for example when a task is
+  `INPUT_REQUIRED`.
+- `reference_task_ids` should be a run parameter / caller intent for the current request, not implicit durable session
+  continuation state.
+- A follow-up/refinement request should pass explicit `reference_task_ids` when it wants to reference previous tasks.
+- If both session `task_id` and run `reference_task_ids` are present, the wrapper should preserve the protocol
+  distinction rather than treating one as a replacement for the other.
+- If no `reference_task_ids` are supplied, the wrapper should not automatically infer them from the last session task
+  unless we deliberately keep that convenience for compatibility.
+
+## Appendix: implementation notes for Option B
+
+The exact names are implementation details, but the shape should be:
+
+```python
+class A2AServiceSessionId(TypedDict):
+    context_id: str
+    task_id: str | None
+    task_state: TaskState | None
+
+
+class AgentSession:
+    def __init__(
+        self,
+        *,
+        session_id: str | None = None,
+        service_session_id: str | ServiceSessionId | None = None,
+    ) -> None:
+        ...
+
+
+class BaseAgent:
+    def _get_otel_conversation_id(self, session: AgentSession | None) -> str | None:
+        service_session_id = session.service_session_id if session else None
+        return service_session_id if isinstance(service_session_id, str) else None
+
+
+class A2AAgent(BaseAgent):
+    def _get_otel_conversation_id(self, session: AgentSession | None) -> str | None:
+        service_session_id = session.service_session_id if session else None
+        if isinstance(service_session_id, Mapping):
+            return service_session_id.get("context_id")
+        return service_session_id if isinstance(service_session_id, str) else None
+
+
+class AgentTelemetryLayer:
+    def _trace_agent_invocation(...):
+        attributes = _get_span_attributes(
+            ...,
+            thread_id=self._get_otel_conversation_id(session),
+            ...,
+        )
+```
+
+This keeps the OpenTelemetry extraction decision with the agent that owns the service continuation shape. Generic OTel
+code should not parse structured `service_session_id` values directly.
+
+`AgentSession` must also be updated so `service_session_id` can store either the current string value or a structured
+service-owned value. Serialization must preserve both shapes, and existing serialized sessions with string
+`service_session_id` must continue to round-trip unchanged.
+
+## More Information
+
+Related work and issues:
+
+- #4673: native conversation ID propagation.
+- #4893: align A2A protocol concepts with Agent Framework session/continuation concepts.
+- #2931: Foundry-specific conversation creation helper, split into a separate Python PR.
+- #6622: broader provider-agnostic conversation creation API discussion requiring .NET sync.
+- [ADR-0015](0015-agent-run-context.md): AgentRunContext for Agent Run.
+- [ADR-0018](0018-agentthread-serialization.md): AgentSession serialization.
+- [ADR-0026](0026-hosted-session-identity-context.md): hosted session identity context.

docs/decisions/0030-hosted-platform-context-agentserver-2.0.md

@@ -0,0 +1,84 @@
+---
+status: accepted
+contact: rogerbarreto
+date: 2026-06-29
+deciders: rogerbarreto
+consulted: []
+informed: []
+---
+
+# Hosted platform context (user id + call id) for Foundry Hosting on AgentServer 2.0
+
+Supersedes [ADR-0026](0026-hosted-session-identity-context.md).
+
+## Context and Problem Statement
+
+[ADR-0026](0026-hosted-session-identity-context.md) sourced the hosted-agent end-user identity from `ResponseContext.Isolation` (an `IsolationContext` typed `UserIsolationKey` / `ChatIsolationKey`), injected by the platform as the `x-agent-user-isolation-key` and `x-agent-chat-isolation-key` headers.
+
+`Azure.AI.AgentServer.*` 2.0.0 (responses protocol `2.0.0`) removes that surface. `ResponseContext.Isolation` is gone; the platform now exposes `ResponseContext.PlatformContext` (a `PlatformContext` typed `UserIdKey` and `CallId`), populated from the `x-agent-user-id` and `x-agent-foundry-call-id` headers. The chat isolation key no longer exists, and a new per-request **call id** is introduced that first-party Foundry services (the toolbox proxy in particular) require on outbound calls to resolve the server-side-stored caller context. The hosting layer in `Microsoft.Agents.AI.Foundry.Hosting` had to migrate to this contract without changing the public shape that samples and providers depend on.
+
+## Decision Drivers
+
+- Track the breaking `Azure.AI.AgentServer.*` 2.0.0 surface (`PlatformContext` replacing `Isolation`) while keeping the same per-user partitioning guarantees from ADR-0026.
+- Keep the change **internal**: existing hosted samples and `AIContextProvider`s must not need code changes. `session.GetHostedContext().UserId`, `HostedSessionIsolationKeyProvider`, and `AddFoundryResponses` stay source-compatible.
+- Forward the new per-request call id verbatim on outbound calls to Foundry first-party services so per-user toolbox OAuth consent and other server-side caller-context lookups keep working.
+- Remain resilient on protocol `1.0.0`: when only the legacy headers are present, `UserIdKey` still resolves and `CallId` is simply absent.
+- Preserve the strict-resume tamper defense from ADR-0026 with identity now reduced to user only.
+
+## Considered Options
+
+For the identity source:
+
+1. **Map `ResponseContext.PlatformContext.UserIdKey`** into the existing `HostedSessionContext` (user only), keeping ADR-0026's storage shape and read accessor.
+2. Keep a `ChatId` slot on `HostedSessionContext` for backward source-compatibility, populated from `CallId` or left null.
+
+For the call id propagation:
+
+A. **A request-scoped ambient (`HostedCallContext`, an `AsyncLocal<string?>`)** set by the handler and re-applied before each egress point, read by the outbound delegating handler.
+B. Thread the call id through every method signature down to the toolbox bearer handler.
+
+For session keying (previously implied by the conversation/chat pairing):
+
+I. **`HostedConversationKey`** resolving a stable partition from `conversation_id ?? partition(previous_response_id) ?? partition(responseId)`.
+II. Continue keying on the container session id (`FOUNDRY_AGENT_SESSION_ID`).
+
+## Decision Outcome
+
+Chosen: **Option 1** for identity, **Option A** for call id, **Option I** for session keying.
+
+Rationale:
+
+- **`ChatId` dropped (Option 2 rejected).** The platform no longer supplies a chat key; carrying a synthetic one would invent identity the trust boundary does not provide. `HostedSessionContext` becomes user-only (`HostedSessionContext(string userId)` / `UserId`), and the strict-resume check validates `UserId` alone. The corresponding `HostedFoundryMemoryProviderScopes` values `PerChat` and `PerUserAndChat` are removed; `PerUser` is retained.
+- **Ambient call id (Option B rejected).** Writing `HostedCallContext.CallId` inside the streaming `async IAsyncEnumerable` iterator is reverted across each `yield`, so a single up-front assignment is lost before the toolbox/MCP egress runs. The handler therefore captures `context.PlatformContext?.CallId` once and **re-applies it immediately before each egress point**; `FoundryToolboxBearerTokenHandler` forwards it as `x-agent-foundry-call-id`. The ambient is request-scoped and never leaks into the caller's execution context (guarded by a unit test).
+- **`HostedConversationKey` (Option II rejected).** One container serves many conversations for its lifetime, so the container session id cannot key per-conversation state. The partition key is derived from the conversation/`previous_response_id`/minted response id instead.
+
+Implementation summary in `Microsoft.Agents.AI.Foundry.Hosting`:
+
+| Type | Visibility | Change vs ADR-0026 |
+|---|---|---|
+| `HostedSessionContext` | public sealed | Now user-only (`UserId`); `ChatId` removed. |
+| `PlatformHostedSessionIsolationKeyProvider` | internal sealed | Maps `context.PlatformContext.UserIdKey` (was `context.Isolation.UserIsolationKey` / `ChatIsolationKey`). |
+| `HostedCallContext` | internal static | New. Request-scoped `AsyncLocal<string?>` holding the `x-agent-foundry-call-id` value. |
+| `HostedConversationKey` | internal | New. Resolves the per-conversation partition key. |
+| `FoundryToolboxBearerTokenHandler` | internal | Now also forwards `x-agent-foundry-call-id` outbound. |
+| `HostedFoundryMemoryProviderScopes` | public | `PerChat` / `PerUserAndChat` removed; `PerUser` kept. |
+
+Package manifests bump the responses container protocol to `2.0.0` (invocations stays `1.0.0`).
+
+## Consequences
+
+Positive:
+
+- Per-user memory partitioning and the strict-resume tamper defense from ADR-0026 are preserved with no public API churn for samples or providers.
+- Per-user toolbox OAuth consent and other server-side caller-context lookups keep working because the per-request call id is forwarded on egress.
+- Works unchanged on protocol `1.0.0` (no call id) and `2.0.0`.
+
+Negative:
+
+- `HostedSessionContext.ChatId` and the `PerChat` / `PerUserAndChat` memory scopes are removed; any out-of-tree consumer that referenced them must move to user-scoped partitioning.
+- The call id must be re-applied before every egress point because of the async-iterator `AsyncLocal` revert; a missed re-apply silently drops the header. This is covered by unit tests.
+
+## Out of scope
+
+- HMAC tamper signatures over the persisted context remain unimplemented; equality comparison against `ResponseContext.PlatformContext` on every request is sufficient because the platform sets the header at the trust boundary.
+- The per-request `User` field on `CreateResponse` is still intentionally not consumed.

docs/decisions/0031-hosted-per-user-session-storage-isolation.md

@@ -0,0 +1,119 @@
+---
+status: accepted
+contact: rogerbarreto
+date: 2026-06-30
+deciders: rogerbarreto
+consulted: []
+informed: []
+---
+
+# Per-agent and per-user session-storage isolation for Foundry Hosting
+
+Builds on [ADR-0030](0030-hosted-platform-context-agentserver-2.0.md).
+
+## Context and Problem Statement
+
+A Foundry hosted container can serve many end users (and, in .NET, many agents) over its lifetime. The
+`AgentSessionStore` persists each turn's `AgentSession` (which for a workflow agent carries the workflow
+checkpoint, and which also carries the tool-approval mapping via `ToolApprovalIdMap` in the session state
+bag). [ADR-0030](0030-hosted-platform-context-agentserver-2.0.md) protected cross-user access only through
+the strict-resume identity check (a 403 when the persisted `HostedSessionContext.UserId` does not match the
+live request). The persisted artifacts themselves were keyed by `conversationId` (+ agent name), not
+physically partitioned per user, so a forged `conversation_id` would still resolve to another user's file
+path before the identity check rejected it.
+
+The Python hosting package added physical per-user partitioning (`<root>/<user_id>/<context_id>`) plus a
+reject-style path-traversal guard. We want .NET to provide the same defense-in-depth, adapted to the .NET
+hosting model.
+
+## Decision Drivers
+
+- Defense in depth: a forged/guessed id must not even resolve to another tenant's storage path, independent
+  of the identity check.
+- Multi-agent hosting: a single .NET container hosts multiple agents resolved from keyed DI, so the layout
+  must isolate per agent as well as per user (Python hosts a single agent and needs no agent layer).
+- Path-traversal safety (CWE-22) for the untrusted, platform-injected user id.
+- Back-compat for local development (no `x-agent-user-id` header) and for direct/non-hosted store use.
+- Keep the change contained and avoid the async-iterator `AsyncLocal` revert hazard from ADR-0030.
+
+## Considered Options
+
+- **Path partition inside `FileSystemAgentSessionStore`**, threading the user id explicitly through the
+  `AgentSessionStore` API, with self-describing prefixed segments.
+- A delegating store that prefixes the conversation id with the user id (the
+  `IsolationKeyScopedAgentSessionStore` pattern from `Microsoft.Agents.AI.Hosting`). Rejected: still needs the
+  user id on the read path and yields a flat key rather than nested per-tenant directories.
+- An `AsyncLocal<string?>` user-context set by the handler. Rejected: the session is saved in the handler's
+  `finally` after the streaming `yield`s, where an `AsyncLocal` set up front is reverted (the same hazard
+  that forced explicit call-id re-application in ADR-0030). Explicit threading is safer and clearer.
+- A separate per-user approval store (as in Python). Rejected as unnecessary: see below.
+
+## Decision Outcome
+
+Path layout with self-describing, prefixed segments; user id threaded explicitly:
+
+    {root}/ a-{agentName} / u-{userId} / c-{contextId}.json
+
+- `a-` (agent), `u-` (user), `c-` (context) are constant literals applied to the sanitized/validated value,
+  so a collapsed layout is never ambiguous and a user id can never masquerade as an agent name.
+- `contextId` is `HostedConversationKey.Resolve` (conversation_id, else the partition of
+  previous_response_id, else of the minted response id).
+- The agent and context layers are always present (Foundry always deploys a named agent). The only
+  collapse is the `u-` layer: present when a user id is resolved (Foundry header, or local dev fallback),
+  absent for raw local runs with no header (`{root}/a-{agent}/c-{conv}.json`). There is no user-only or
+  no-agent layout.
+
+Other elements:
+
+- `string? userId` was added as a **required** parameter (no default) on `AgentSessionStore.GetSessionAsync` /
+  `SaveSessionAsync` (a contained, breaking change to the experimental Foundry abstraction; both in-tree
+  implementations and the two handler call sites were updated). It is required rather than optional so a
+  caller can never silently persist a session unscoped; a genuine no-user caller (local without the header,
+  or a non-hosted direct caller) passes `null` explicitly. `AgentFrameworkResponseHandler` resolves the user
+  id before loading the session.
+- Path-traversal guard: the user id is rejected (not sanitized) when it is not a single safe path segment
+  (path separators, NUL, drive letters, rooted paths, all-dot segments). After building the path, the
+  fully-resolved path is asserted to remain under the storage root.
+- The strict-resume 403 identity check from ADR-0030 is **kept** as the second defense layer (it still
+  catches a session that reaches the wrong partition, e.g. via a non-partitioning custom store or in-process
+  tampering).
+- **No separate approval store.** The tool-approval mapping lives in `ToolApprovalIdMap` ->
+  `AgentSessionStateBag`, which is serialized into the session checkpoint, so partitioning the session path
+  isolates pending approvals per tenant automatically. (Python needs a separate per-user approval store only
+  because it models approvals as a standalone store.)
+
+## Consequences
+
+Positive:
+
+- Cross-tenant isolation is now defense-in-depth: physical per-agent/per-user partitioning plus the identity
+  check. Approvals and workflow checkpoints inherit the partitioning because they ride in the session.
+- Self-describing prefixes make the on-disk layout auditable and collision-free across collapse cases.
+
+Negative:
+
+- Breaking change to the experimental Foundry `AgentSessionStore` API (added `userId`).
+- The on-disk layout and leaf filename change (`<conv>.json` -> `c-<conv>.json`), orphaning sessions written
+  by the ADR-0030 release. Acceptable for an experimental package; a fresh session is created on next use.
+
+## Out of scope
+
+- Encryption at rest and quota enforcement remain platform concerns.
+- Non-Foundry hosting layers can adopt an equivalent scheme independently.
+
+## Update (2026-07-01): local runs no longer fail closed; sample dev provider removed
+
+Superseding the ADR-0026/0030 behavior where a `null` result from `HostedSessionIsolationKeyProvider`
+always became a 500, `AgentFrameworkResponseHandler` now branches on `FoundryEnvironment.IsHosted`:
+
+- **Hosted** (`IsHosted == true`, production): a `null` identity is still a hard error (500). Isolation
+  stays strict; the platform always injects `x-agent-user-id`.
+- **Not hosted** (local `docker run` / `dotnet run`): a `null` identity is tolerated. Per-user isolation
+  is simply not triggered — the handler passes `userId == null` to the store (the documented "no user
+  partition", `{root}/a-{agent}/c-{conv}.json`), stamps no `HostedSessionContext`, and runs no
+  strict-resume check. Contributors can run a hosted image locally with zero extra setup.
+
+Consequently the sample-side `DevTemporaryLocalUserIdProvider` and `AddDevTemporaryLocalContributorSetup`
+were removed. To simulate distinct users locally, send an `x-agent-user-id` request header; the default
+`PlatformHostedSessionIsolationKeyProvider` reads it via `ResponseContext.PlatformContext.UserIdKey`
+(the SDK's `PlatformContext.FromRequest` populates it from the header unconditionally, hosted or not).

docs/features/FIDES_IMPLEMENTATION_SUMMARY.md

@@ -8,6 +8,8 @@
 - **Context Provider Pattern** - `SecureAgentConfig` extends `ContextProvider`, injecting tools, instructions, and middleware automatically
 - **Automatic Variable Hiding** - UNTRUSTED content is automatically hidden without requiring manual intervention
 - **Per-Item Embedded Labels** - Tools return `list[Content]` with `Content.from_text()` for proper label propagation
+- **SecureMCPToolProxy Auto-Labeling** - MCP tools are labeled automatically from MCP `ToolAnnotations` hints
+- **MCP `_meta.ifc` Support** - Per-result IFC labels from servers (for example GitHub MCP with `X-MCP-Features: ifc_labels`) are parsed and enforced
 - **SecureAgentConfig** - One-line secure agent configuration via `context_providers=[config]`
 - **Data Exfiltration Prevention** - `max_allowed_confidentiality` prevents sensitive data leakage
 - **Message-Level Label Tracking** (Phase 1) - Track labels on every message in the conversation
@@ -23,6 +25,7 @@ The FIDES defense system consists of seven main components:
 5. **Security Tools** - Specialized tools for safe handling of untrusted content (`quarantined_llm`, `inspect_variable`)
 6. **SecureAgentConfig** - Context provider for easy secure agent configuration
 7. **Message-Level Label Tracking** - Track labels on every message in the conversation (Phase 1)
+8. **MCP Tool/Result Label Integration** - MCP hint-based tool labeling and `_meta.ifc` result label parsing
 
 ## Implementation Details
 
@@ -184,6 +187,17 @@ agent = Agent(
 )
 ```
 
+### 7. MCP Labeling Pipeline (Hints + `_meta.ifc`)
+
+FIDES now secures remote MCP integration end-to-end:
+
+- **Tool labels from hints**: `apply_mcp_security_labels(...)` maps MCP hints (`readOnlyHint`, `openWorldHint`) to FIDES tool properties.
+- **Safe sink defaults**: tools not explicitly marked `readOnlyHint=True` are treated as potential sinks and receive `max_allowed_confidentiality=public`.
+- **Result labels from metadata**: MCP result `_meta` is propagated via `__mcp_result_meta__`; `_meta.ifc` is parsed into `security_label` per result item.
+- **`SecureMCPToolProxy` convenience**: wraps MCP tools/URLs and applies this labeling automatically on connect.
+
+This behavior is used with the GitHub MCP server when `X-MCP-Features: ifc_labels` is passed, which causes the server to return IFC labels in `_meta` (for example `{"ifc": {"integrity": "untrusted", "confidentiality": "public"}}`).
+
 ## Security Properties
 
 ### Deterministic Defense

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

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

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

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

dotnet/.github/skills/verify-samples-tool/SKILL.md

@@ -1,4 +1,4 @@
----
+---
 name: verify-samples-tool
 description: How to use the verify-samples tool to run, verify, and manage sample definitions in the Agent Framework repository. Use this when adding, updating, or running sample verification.
 ---
@@ -157,7 +157,7 @@ new SampleDefinition
 new SampleDefinition
 {
     Name = "Agent_With_AzureOpenAIChatCompletion",
-    ProjectPath = "samples/02-agents/AgentProviders/Agent_With_AzureOpenAIChatCompletion",
+    ProjectPath = "samples/02-agents/AgentProviders/azure/Agent_With_AzureOpenAIChatCompletion",
     RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
     OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
     ExpectedOutputDescription =
@@ -173,11 +173,11 @@ new SampleDefinition
 ```csharp
 new SampleDefinition
 {
-    Name = "Workflow_Declarative_GenerateCode",
-    ProjectPath = "samples/03-workflows/Declarative/GenerateCode",
+    Name = "Workflow_Visualization",
+    ProjectPath = "samples/03-workflows/Visualization",
     IsDeterministic = true,
-    MustContain = ["WORKFLOW: Parsing", "WORKFLOW: Defined"],
-    ExpectedOutputDescription = ["The output should show a YAML workflow being parsed and C# code being generated from it."],
+    MustContain = ["Generating workflow visualization...", "Mermaid string:", "DiGraph string:"],
+    ExpectedOutputDescription = ["The output should show workflow visualization in Mermaid and DiGraph formats."],
 },
 ```
 
@@ -223,3 +223,5 @@ new SampleDefinition
     SkipReason = "Runs as an MCP stdio server that does not exit on its own.",
 },
 ```
+
+

dotnet/AGENTS.md

@@ -10,6 +10,10 @@ See `./.github/skills/build-and-test/SKILL.md` for detailed instructions on buil
 
 See `./.github/skills/project-structure/SKILL.md` for an overview of the project structure.
 
+## Pull Requests
+
+See `./.github/skills/pull-requests/SKILL.md` for guidance on writing PR descriptions and handling/resolving PR review comments.
+
 ### Core types
 
 - `AIAgent`: The abstract base class that all agents derive from, providing common methods for interacting with an agent.

dotnet/Directory.Packages.props

@@ -11,8 +11,8 @@
   </PropertyGroup>
   <ItemGroup>
     <!-- Aspire.* -->
-    <PackageVersion Include="Anthropic" Version="12.13.0" />
-    <PackageVersion Include="Anthropic.Foundry" Version="0.5.0" />
+    <PackageVersion Include="Anthropic" Version="12.20.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" />
@@ -21,14 +21,16 @@
     <PackageVersion Include="Aspire.Hosting.Azure.CognitiveServices" Version="$(AspireAppHostSdkVersion)" />
     <PackageVersion Include="Aspire.Microsoft.Azure.Cosmos" Version="$(AspireAppHostSdkVersion)" />
     <PackageVersion Include="CommunityToolkit.Aspire.OllamaSharp" Version="13.0.0" />
+    <PackageVersion Include="MessagePack" Version="3.1.7" /> <!-- Transitive dependency of Aspire pinned to newer version due to vulnerability in 2.5.192 -->
     <!-- Azure.* -->
-    <PackageVersion Include="Azure.AI.AgentServer.Core" Version="1.0.0-beta.23" />
-    <PackageVersion Include="Azure.AI.AgentServer.Invocations" Version="1.0.0-beta.3" />
-    <PackageVersion Include="Azure.AI.AgentServer.Responses" Version="1.0.0-beta.4" />
-    <PackageVersion Include="Azure.AI.Projects" Version="2.0.0" />
+    <PackageVersion Include="Azure.AI.AgentServer.Core" Version="1.0.0-beta.26" />
+    <PackageVersion Include="Azure.AI.AgentServer.Invocations" Version="1.0.0-beta.5" />
+    <PackageVersion Include="Azure.AI.AgentServer.Responses" Version="1.0.0-beta.6" />
+    <PackageVersion Include="Azure.Search.Documents" Version="12.0.0" />
+    <PackageVersion Include="Azure.AI.Projects" Version="2.1.0-beta.4" />
     <PackageVersion Include="Azure.AI.Agents.Persistent" Version="1.2.0-beta.10" />
     <PackageVersion Include="Azure.AI.OpenAI" Version="2.9.0-beta.1" />
-    <PackageVersion Include="Azure.Core" Version="1.53.0" />
+    <PackageVersion Include="Azure.Core" Version="1.60.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" />
@@ -40,19 +42,25 @@
     <!-- Newtonsoft.Json -->
     <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
     <!-- System.* -->
-    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.6" />
+    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.9" />
     <PackageVersion Include="Microsoft.Bcl.HashCode" Version="6.0.0" />
     <PackageVersion Include="Microsoft.Bcl.Memory" Version="10.0.5" />
-    <PackageVersion Include="System.ClientModel" Version="1.10.0" />
+    <PackageVersion Include="System.ClientModel" Version="1.14.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" />
-    <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="10.0.6" />
+    <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="10.0.9" />
     <PackageVersion Include="System.Linq.AsyncEnumerable" Version="10.0.5" />
     <PackageVersion Include="System.Net.Http.Json" Version="10.0.0" />
-    <PackageVersion Include="System.Net.ServerSentEvents" Version="10.0.5" />
-    <PackageVersion Include="System.Text.Json" Version="10.0.6" />
-    <PackageVersion Include="System.Threading.Channels" Version="10.0.6" />
+    <PackageVersion Include="System.Net.ServerSentEvents" Version="10.0.8" />
+    <!-- AG-UI .NET SDK packages (published by the AG-UI team). -->
+    <PackageVersion Include="AGUI.Abstractions" Version="0.0.1" />
+    <PackageVersion Include="AGUI.Formatting" Version="0.0.1" />
+    <PackageVersion Include="AGUI.Protobuf" Version="0.0.1" />
+    <PackageVersion Include="AGUI.Client" Version="0.0.1" />
+    <PackageVersion Include="AGUI.Server" Version="0.0.1" />
+    <PackageVersion Include="System.Text.Json" Version="10.0.9" />
+    <PackageVersion Include="System.Threading.Channels" Version="10.0.8" />
     <PackageVersion Include="System.Threading.Tasks.Extensions" Version="4.6.3" />
     <PackageVersion Include="System.Net.Security" Version="4.3.2" />
     <!-- OpenTelemetry -->
@@ -68,15 +76,16 @@
     <!-- Microsoft.AspNetCore.* -->
     <PackageVersion Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.0" />
     <PackageVersion Include="Microsoft.AspNetCore.Authentication.OpenIdConnect" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.9" />
+    <PackageVersion Include="Microsoft.OpenApi" Version="2.7.5" /> <!-- Pin patched OpenAPI.NET to remediate GHSA-v5pm-xwqc-g5wc -->
     <PackageVersion Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.0.0" />
     <!-- Microsoft.Extensions.* -->
-    <PackageVersion Include="Microsoft.Extensions.AI" Version="10.5.1" />
-    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="10.5.1" />
-    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation" Version="10.4.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation.Quality" Version="10.4.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation.Safety" Version="10.3.0-preview.1.26109.11" />
-    <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.5.1" />
+    <PackageVersion Include="Microsoft.Extensions.AI" Version="10.6.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="10.6.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation" Version="10.6.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation.Quality" Version="10.6.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation.Safety" Version="10.6.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.6.0" />
     <PackageVersion Include="Microsoft.Extensions.Caching.Memory" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Compliance.Abstractions" Version="10.5.0" />
     <PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.1" />
@@ -85,12 +94,12 @@
     <PackageVersion Include="Microsoft.Extensions.Configuration.Json" Version="10.0.1" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.1" />
     <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.1" />
-    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.6" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.9" />
     <PackageVersion Include="Microsoft.Extensions.FileSystemGlobbing" Version="10.0.6" />
     <PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.1" />
     <PackageVersion Include="Microsoft.Extensions.Http.Resilience" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Logging" Version="10.0.1" />
-    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.6" />
+    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.9" />
     <PackageVersion Include="Microsoft.Extensions.Logging.Console" Version="10.0.1" />
     <PackageVersion Include="Microsoft.Extensions.ServiceDiscovery" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.VectorData.Abstractions" Version="9.7.0" />
@@ -98,7 +107,7 @@
     <PackageVersion Include="Microsoft.SemanticKernel.Connectors.InMemory" Version="1.67.0-preview" />
     <PackageVersion Include="Microsoft.SemanticKernel.Connectors.Qdrant" Version="1.67.0-preview" />
     <!-- Agent SDKs -->
-    <PackageVersion Include="GitHub.Copilot.SDK" Version="1.0.0-beta.2" />
+    <PackageVersion Include="GitHub.Copilot.SDK" Version="1.0.5" />
     <PackageVersion Include="Microsoft.Agents.CopilotStudio.Client" Version="1.3.171-beta" />
     <!-- M365 Agents SDK -->
     <PackageVersion Include="AdaptiveCards" Version="3.1.0" />
@@ -108,16 +117,17 @@
     <PackageVersion Include="A2A" Version="1.0.0-preview2" />
     <PackageVersion Include="A2A.AspNetCore" Version="1.0.0-preview2" />
     <!-- MCP -->
-    <PackageVersion Include="ModelContextProtocol" Version="1.1.0" />
+    <PackageVersion Include="ModelContextProtocol" Version="1.2.0" />
     <!-- Hyperlight -->
     <PackageVersion Include="Hyperlight.HyperlightSandbox.Api" Version="0.4.0" />
+    <PackageVersion Include="Hyperlight.HyperlightSandbox.Guest.Python" Version="0.4.0" />
     <!-- Inference SDKs -->
     <PackageVersion Include="Microsoft.ML.OnnxRuntimeGenAI" Version="0.10.0" />
     <PackageVersion Include="Microsoft.ML.Tokenizers" Version="2.0.0" />
     <PackageVersion Include="OllamaSharp" Version="5.4.8" />
     <PackageVersion Include="OpenAI" Version="2.10.0" />
     <!-- Identity -->
-    <PackageVersion Include="Microsoft.Identity.Client.Extensions.Msal" Version="4.83.1" />
+    <PackageVersion Include="Microsoft.Identity.Client.Extensions.Msal" Version="4.84.2" />
     <!-- Workflows -->
     <PackageVersion Include="Microsoft.Agents.ObjectModel" Version="2026.2.4.1" />
     <PackageVersion Include="Microsoft.Agents.ObjectModel.Json" Version="2026.2.4.1" />
@@ -136,10 +146,15 @@
     <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" Version="2.1.0" />
     <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.Mcp" Version="1.0.0" />
     <PackageVersion Include="Microsoft.Azure.Functions.Worker.Sdk" Version="2.0.7" />
+    <!-- Valkey -->
     <!-- Redis -->
     <PackageVersion Include="StackExchange.Redis" Version="2.10.1" />
+    <!-- Valkey -->
+    <PackageVersion Include="Valkey.Glide" Version="1.1.0" />
     <!-- Console UX -->
     <PackageVersion Include="Spectre.Console" Version="0.49.1" />
+    <!-- AWS -->
+    <PackageVersion Include="AWSSDK.Extensions.Bedrock.MEAI" Version="4.0.6.10" />
     <!-- Test -->
     <PackageVersion Include="FluentAssertions" Version="8.8.0" />
     <PackageVersion Include="Microsoft.AspNetCore.TestHost" Condition="'$(TargetFramework)' == 'net8.0'" Version="8.0.22" />
@@ -193,4 +208,4 @@
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
   </ItemGroup>
-</Project>
+</Project>

dotnet/agent-framework-dotnet.slnx

@@ -1,4 +1,4 @@
-<Solution>
+<Solution>
   <Configurations>
     <BuildType Name="Debug" />
     <BuildType Name="Publish" />
@@ -22,20 +22,19 @@
   </Folder>
   <Folder Name="/Samples/02-agents/AgentProviders/">
     <File Path="samples/02-agents/AgentProviders/README.md" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_A2A/Agent_With_A2A.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_Anthropic/Agent_With_Anthropic.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_AzureAIAgentsPersistent/Agent_With_AzureAIAgentsPersistent.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_AzureAIProject/Agent_With_AzureAIProject.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_AzureFoundryModel/Agent_With_AzureFoundryModel.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_AzureOpenAIChatCompletion/Agent_With_AzureOpenAIChatCompletion.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_AzureOpenAIResponses/Agent_With_AzureOpenAIResponses.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_CustomImplementation/Agent_With_CustomImplementation.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_GitHubCopilot/Agent_With_GitHubCopilot.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_GoogleGemini/Agent_With_GoogleGemini.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_Ollama/Agent_With_Ollama.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_ONNX/Agent_With_ONNX.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_OpenAIChatCompletion/Agent_With_OpenAIChatCompletion.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_OpenAIResponses/Agent_With_OpenAIResponses.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/a2a/Agent_With_A2A/Agent_With_A2A.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/anthropic/Agent_With_Anthropic/Agent_With_Anthropic.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/azure/Agent_With_AzureAIProject/Agent_With_AzureAIProject.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/azure/Agent_With_AzureFoundryModel/Agent_With_AzureFoundryModel.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/azure/Agent_With_AzureOpenAIChatCompletion/Agent_With_AzureOpenAIChatCompletion.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/azure/Agent_With_AzureOpenAIResponses/Agent_With_AzureOpenAIResponses.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/custom/Agent_With_CustomImplementation/Agent_With_CustomImplementation.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/github-copilot/Agent_With_GitHubCopilot/Agent_With_GitHubCopilot.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/google-gemini/Agent_With_GoogleGemini/Agent_With_GoogleGemini.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/ollama/Agent_With_Ollama/Agent_With_Ollama.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/onnx/Agent_With_ONNX/Agent_With_ONNX.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/openai/Agent_With_OpenAIChatCompletion/Agent_With_OpenAIChatCompletion.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/openai/Agent_With_OpenAIResponses/Agent_With_OpenAIResponses.csproj" />
   </Folder>
   <Folder Name="/Samples/05-end-to-end/DevUIAspireIntegration/">
     <Project Path="samples/05-end-to-end/DevUIAspireIntegration/DevUIIntegration.AppHost/DevUIIntegration.AppHost.csproj" />
@@ -65,6 +64,7 @@
     <Project Path="samples/02-agents/Agents/Agent_Step18_CompactionPipeline/Agent_Step18_CompactionPipeline.csproj" />
     <Project Path="samples/02-agents/Agents/Agent_Step19_InFunctionLoopCheckpointing/Agent_Step19_InFunctionLoopCheckpointing.csproj" />
     <Project Path="samples/02-agents/Agents/Agent_Step20_DynamicFunctionTools/Agent_Step20_DynamicFunctionTools.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step21_ShellWithEnvironment/Agent_Step21_ShellWithEnvironment.csproj" />
   </Folder>
   <Folder Name="/Samples/02-agents/DeclarativeAgents/">
     <Project Path="samples/02-agents/DeclarativeAgents/ChatClient/DeclarativeChatClientAgents.csproj" />
@@ -116,13 +116,22 @@
     <Project Path="samples/02-agents/AgentSkills/Agent_Step03_ClassBasedSkills/Agent_Step03_ClassBasedSkills.csproj" />
     <Project Path="samples/02-agents/AgentSkills/Agent_Step04_MixedSkills/Agent_Step04_MixedSkills.csproj" />
     <Project Path="samples/02-agents/AgentSkills/Agent_Step05_SkillsWithDI/Agent_Step05_SkillsWithDI.csproj" />
+    <Project Path="samples/02-agents/AgentSkills/Agent_Step06_McpBasedSkills/Agent_Step06_McpBasedSkills.csproj" />
+    <Project Path="samples/02-agents/AgentSkills/Agent_Step07_SkillsAutoApproval/Agent_Step07_SkillsAutoApproval.csproj" />
   </Folder>
   <Folder Name="/Samples/02-agents/Harness/">
     <File Path="samples/02-agents/Harness/README.md" />
+    <Project Path="samples/02-agents/Harness/BuildYourOwnClaw/Claw_Step01_MeetYourClaw/Claw_Step01_MeetYourClaw.csproj" />
+    <Project Path="samples/02-agents/Harness/BuildYourOwnClaw/Claw_Step02_WorkingWithData/Claw_Step02_WorkingWithData.csproj" />
+    <Project Path="samples/02-agents/Harness/ConsoleReactiveComponents/ConsoleReactiveComponents.csproj" />
+    <Project Path="samples/02-agents/Harness/ConsoleReactiveFramework/ConsoleReactiveFramework.csproj" />
     <Project Path="samples/02-agents/Harness/Harness_Shared_Console/Harness_Shared_Console.csproj" />
+    <Project Path="samples/02-agents/Harness/Harness_Shared_Console_OpenAI/Harness_Shared_Console_OpenAI.csproj" />
     <Project Path="samples/02-agents/Harness/Harness_Step01_Research/Harness_Step01_Research.csproj" />
-    <Project Path="samples/02-agents/Harness/Harness_Step02_Research_WithSubAgents/Harness_Step02_Research_WithSubAgents.csproj" />
+    <Project Path="samples/02-agents/Harness/Harness_Step02_Research_WithBackgroundAgents/Harness_Step02_Research_WithBackgroundAgents.csproj" />
     <Project Path="samples/02-agents/Harness/Harness_Step03_DataProcessing/Harness_Step03_DataProcessing.csproj" />
+    <Project Path="samples/02-agents/Harness/Harness_Step04_CodeExecution/Harness_Step04_CodeExecution.csproj" />
+    <Project Path="samples/02-agents/Harness/Harness_Step05_Loop/Harness_Step05_Loop.csproj" />
   </Folder>
   <Folder Name="/Samples/02-agents/AGUI/Step05_StateManagement/">
     <Project Path="samples/02-agents/AGUI/Step05_StateManagement/Client/Client.csproj" />
@@ -132,42 +141,43 @@
     <File Path="samples/02-agents/DevUI/README.md" />
     <Project Path="samples/02-agents/DevUI/DevUI_Step01_BasicUsage/DevUI_Step01_BasicUsage.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AgentWithAnthropic/">
-    <File Path="samples/02-agents/AgentWithAnthropic/README.md" />
-    <Project Path="samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step01_Running/Agent_Anthropic_Step01_Running.csproj" />
-    <Project Path="samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step02_Reasoning/Agent_Anthropic_Step02_Reasoning.csproj" />
-    <Project Path="samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step03_UsingFunctionTools/Agent_Anthropic_Step03_UsingFunctionTools.csproj" />
-    <Project Path="samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step04_UsingSkills/Agent_Anthropic_Step04_UsingSkills.csproj" />
+  <Folder Name="/Samples/02-agents/AgentProviders/anthropic/">
+    <File Path="samples/02-agents/AgentProviders/anthropic/README.md" />
+    <Project Path="samples/02-agents/AgentProviders/anthropic/Agent_Anthropic_Step01_Running/Agent_Anthropic_Step01_Running.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/anthropic/Agent_Anthropic_Step02_Reasoning/Agent_Anthropic_Step02_Reasoning.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/anthropic/Agent_Anthropic_Step03_UsingFunctionTools/Agent_Anthropic_Step03_UsingFunctionTools.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/anthropic/Agent_Anthropic_Step04_UsingSkills/Agent_Anthropic_Step04_UsingSkills.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AgentsWithFoundry/">
-    <File Path="samples/02-agents/AgentsWithFoundry/README.md" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step00_FoundryAgentLifecycle/Agent_Step00_FoundryAgentLifecycle.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step01_Basics/Agent_Step01_Basics.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step02.1_MultiturnConversation/Agent_Step02.1_MultiturnConversation.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step02.2_MultiturnWithServerConversations/Agent_Step02.2_MultiturnWithServerConversations.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step03_UsingFunctionTools/Agent_Step03_UsingFunctionTools.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step04_UsingFunctionToolsWithApprovals/Agent_Step04_UsingFunctionToolsWithApprovals.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step05_StructuredOutput/Agent_Step05_StructuredOutput.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step06_PersistedConversations/Agent_Step06_PersistedConversations.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step07_Observability/Agent_Step07_Observability.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step08_DependencyInjection/Agent_Step08_DependencyInjection.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step09_UsingMcpClientAsTools/Agent_Step09_UsingMcpClientAsTools.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step10_UsingImages/Agent_Step10_UsingImages.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step11_AsFunctionTool/Agent_Step11_AsFunctionTool.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step12_Middleware/Agent_Step12_Middleware.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step13_Plugins/Agent_Step13_Plugins.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step14_CodeInterpreter/Agent_Step14_CodeInterpreter.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step15_ComputerUse/Agent_Step15_ComputerUse.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step16_FileSearch/Agent_Step16_FileSearch.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step17_OpenAPITools/Agent_Step17_OpenAPITools.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step18_BingCustomSearch/Agent_Step18_BingCustomSearch.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step19_SharePoint/Agent_Step19_SharePoint.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step20_MicrosoftFabric/Agent_Step20_MicrosoftFabric.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step21_WebSearch/Agent_Step21_WebSearch.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step22_MemorySearch/Agent_Step22_MemorySearch.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step23_LocalMCP/Agent_Step23_LocalMCP.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step24_CodeInterpreterFileDownload/Agent_Step24_CodeInterpreterFileDownload.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step25_ToolboxServerSideTools/Agent_Step25_ToolboxServerSideTools.csproj" />
+  <Folder Name="/Samples/02-agents/AgentProviders/foundry/">
+    <File Path="samples/02-agents/AgentProviders/foundry/README.md" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step00_FoundryAgentLifecycle/Agent_Step00_FoundryAgentLifecycle.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step01_Basics/Agent_Step01_Basics.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step02.1_MultiturnConversation/Agent_Step02.1_MultiturnConversation.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step02.2_MultiturnWithServerConversations/Agent_Step02.2_MultiturnWithServerConversations.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step03_UsingFunctionTools/Agent_Step03_UsingFunctionTools.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step04_UsingFunctionToolsWithApprovals/Agent_Step04_UsingFunctionToolsWithApprovals.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step05_StructuredOutput/Agent_Step05_StructuredOutput.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step06_PersistedConversations/Agent_Step06_PersistedConversations.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step07_Observability/Agent_Step07_Observability.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step08_DependencyInjection/Agent_Step08_DependencyInjection.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step09_UsingMcpClientAsTools/Agent_Step09_UsingMcpClientAsTools.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step10_UsingImages/Agent_Step10_UsingImages.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step11_AsFunctionTool/Agent_Step11_AsFunctionTool.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step12_Middleware/Agent_Step12_Middleware.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step13_Plugins/Agent_Step13_Plugins.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step14_CodeInterpreter/Agent_Step14_CodeInterpreter.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step15_ComputerUse/Agent_Step15_ComputerUse.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step16_FileSearch/Agent_Step16_FileSearch.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step17_OpenAPITools/Agent_Step17_OpenAPITools.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step18_BingCustomSearch/Agent_Step18_BingCustomSearch.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step19_SharePoint/Agent_Step19_SharePoint.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step20_MicrosoftFabric/Agent_Step20_MicrosoftFabric.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step21_WebSearch/Agent_Step21_WebSearch.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step22_MemorySearch/Agent_Step22_MemorySearch.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step23_LocalMCP/Agent_Step23_LocalMCP.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step24_CodeInterpreterFileDownload/Agent_Step24_CodeInterpreterFileDownload.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step25_FoundryToolboxMcp/Agent_Step25_FoundryToolboxMcp.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/foundry/Agent_Step26_FoundryToolboxMcpSkills/Agent_Step26_FoundryToolboxMcpSkills.csproj" />
   </Folder>
   <Folder Name="/Samples/02-agents/Evaluation/">
     <Project Path="samples/02-agents/Evaluation/Evaluation_CustomEvals/Evaluation_CustomEvals.csproj" />
@@ -185,17 +195,19 @@
     <File Path="samples/02-agents/AgentWithMemory/README.md" />
     <Project Path="samples/02-agents/AgentWithMemory/AgentWithMemory_Step01_ChatHistoryMemory/AgentWithMemory_Step01_ChatHistoryMemory.csproj" />
     <Project Path="samples/02-agents/AgentWithMemory/AgentWithMemory_Step02_MemoryUsingMem0/AgentWithMemory_Step02_MemoryUsingMem0.csproj" />
+    <Project Path="samples/02-agents/AgentWithMemory/AgentWithMemory_Step03_MemoryUsingValkey/AgentWithMemory_Step03_MemoryUsingValkey.csproj" />
+    <Project Path="samples/02-agents/AgentWithMemory/AgentWithMemory_Step03_MemoryUsingValkey_Bedrock/AgentWithMemory_Step03_MemoryUsingValkey_Bedrock.csproj" />
     <Project Path="samples/02-agents/AgentWithMemory/AgentWithMemory_Step04_MemoryUsingFoundry/AgentWithMemory_Step04_MemoryUsingFoundry.csproj" />
     <Project Path="samples/02-agents/AgentWithMemory/AgentWithMemory_Step05_BoundedChatHistory/AgentWithMemory_Step05_BoundedChatHistory.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AgentWithOpenAI/">
-    <File Path="samples/02-agents/AgentWithOpenAI/README.md" />
-    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step01_Running/Agent_OpenAI_Step01_Running.csproj" />
-    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step02_Reasoning/Agent_OpenAI_Step02_Reasoning.csproj" />
-    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step03_CreateFromChatClient/Agent_OpenAI_Step03_CreateFromChatClient.csproj" />
-    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient.csproj" />
-    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step05_Conversation/Agent_OpenAI_Step05_Conversation.csproj" />
-    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step06_CodeInterpreterFileDownload/Agent_OpenAI_Step06_CodeInterpreterFileDownload.csproj" />
+  <Folder Name="/Samples/02-agents/AgentProviders/openai/">
+    <File Path="samples/02-agents/AgentProviders/openai/README.md" />
+    <Project Path="samples/02-agents/AgentProviders/openai/Agent_OpenAI_Step01_Running/Agent_OpenAI_Step01_Running.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/openai/Agent_OpenAI_Step02_Reasoning/Agent_OpenAI_Step02_Reasoning.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/openai/Agent_OpenAI_Step03_CreateFromChatClient/Agent_OpenAI_Step03_CreateFromChatClient.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/openai/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/openai/Agent_OpenAI_Step05_Conversation/Agent_OpenAI_Step05_Conversation.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/openai/Agent_OpenAI_Step06_CodeInterpreterFileDownload/Agent_OpenAI_Step06_CodeInterpreterFileDownload.csproj" />
   </Folder>
   <Folder Name="/Samples/02-agents/AgentWithRAG/">
     <File Path="samples/02-agents/AgentWithRAG/README.md" />
@@ -207,6 +219,8 @@
   </Folder>
   <Folder Name="/Samples/02-agents/ModelContextProtocol/">
     <File Path="samples/02-agents/ModelContextProtocol/README.md" />
+    <Project Path="samples/02-agents/ModelContextProtocol/Agent_MCP_LongRunningTask_Client/Agent_MCP_LongRunningTask_Client.csproj" />
+    <Project Path="samples/02-agents/ModelContextProtocol/Agent_MCP_PerRun_AuthHeaders/Agent_MCP_PerRun_AuthHeaders.csproj" />
     <Project Path="samples/02-agents/ModelContextProtocol/Agent_MCP_Server/Agent_MCP_Server.csproj" />
     <Project Path="samples/02-agents/ModelContextProtocol/Agent_MCP_Server_Auth/Agent_MCP_Server_Auth.csproj" />
     <Project Path="samples/02-agents/ModelContextProtocol/FoundryAgent_Hosted_MCP/FoundryAgent_Hosted_MCP.csproj" />
@@ -229,15 +243,15 @@
   </Folder>
   <Folder Name="/Samples/03-workflows/Declarative/">
     <File Path="samples/03-workflows/Declarative/README.md" />
+    <Project Path="samples/03-workflows/Declarative/AotCheckpointing/AotCheckpointing.csproj" />
     <Project Path="samples/03-workflows/Declarative/ConfirmInput/ConfirmInput.csproj" />
     <Project Path="samples/03-workflows/Declarative/CustomerSupport/CustomerSupport.csproj" />
     <Project Path="samples/03-workflows/Declarative/DeepResearch/DeepResearch.csproj" />
-    <Project Path="samples/03-workflows/Declarative/ExecuteCode/ExecuteCode.csproj" />
     <Project Path="samples/03-workflows/Declarative/ExecuteWorkflow/ExecuteWorkflow.csproj" />
     <Project Path="samples/03-workflows/Declarative/FunctionTools/FunctionTools.csproj" />
-    <Project Path="samples/03-workflows/Declarative/GenerateCode/GenerateCode.csproj" />
     <Project Path="samples/03-workflows/Declarative/HostedWorkflow/HostedWorkflow.csproj" />
     <Project Path="samples/03-workflows/Declarative/InputArguments/InputArguments.csproj" />
+    <Project Path="samples/03-workflows/Declarative/InvokeFoundryToolboxMcp/InvokeFoundryToolboxMcp.csproj" />
     <Project Path="samples/03-workflows/Declarative/InvokeFunctionTool/InvokeFunctionTool.csproj" />
     <Project Path="samples/03-workflows/Declarative/InvokeHttpRequest/InvokeHttpRequest.csproj" />
     <Project Path="samples/03-workflows/Declarative/InvokeMcpTool/InvokeMcpTool.csproj" />
@@ -275,6 +289,7 @@
   </Folder>
   <Folder Name="/Samples/03-workflows/Orchestration/">
     <Project Path="samples/03-workflows/Orchestration/Handoff/Handoff.csproj" />
+    <Project Path="samples/03-workflows/Orchestration/Magentic/Magentic.csproj" />
   </Folder>
   <Folder Name="/Samples/03-workflows/Observability/">
     <Project Path="samples/03-workflows/Observability/ApplicationInsights/ApplicationInsights.csproj" />
@@ -295,6 +310,7 @@
   </Folder>
   <Folder Name="/Samples/03-workflows/Evaluation/">
     <Project Path="samples/03-workflows/Evaluation/Evaluation_WorkflowEval/Evaluation_WorkflowEval.csproj" />
+    <Project Path="samples/03-workflows/Evaluation/Evaluation_WorkflowExpectedOutputs/Evaluation_WorkflowExpectedOutputs.csproj" />
   </Folder>
   <Folder Name="/Samples/04-hosting/">
   </Folder>
@@ -313,18 +329,39 @@
   <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-FoundryAgent/">
     <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-FoundryAgent/HostedFoundryAgent.csproj" />
   </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files/HostedFiles.csproj" />
+  </Folder>
   <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalTools/">
     <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalTools/HostedLocalTools.csproj" />
   </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-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>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-MemoryAgent/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-MemoryAgent/HostedMemoryAgent.csproj" />
+  </Folder>
   <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-Observability/">
     <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-Observability/HostedObservability.csproj" />
   </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted_Shared_Contributor_Setup/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted_Shared_Contributor_Setup/Hosted_Shared_Contributor_Setup.csproj" />
+  </Folder>
   <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox/">
     <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox/HostedToolbox.csproj" />
   </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox-AuthPaths/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox-AuthPaths/Hosted-Toolbox-AuthPaths.csproj" />
+  </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-ToolboxMcpSkills/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-ToolboxMcpSkills/HostedToolboxMcpSkills.csproj" />
+  </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/HostedAzureSearchRag.csproj" />
+  </Folder>
   <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-TextRag/">
     <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-TextRag/HostedTextRag.csproj" />
   </Folder>
@@ -332,11 +369,16 @@
     <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Simple/HostedWorkflowSimple.csproj" />
   </Folder>
   <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/Hosted-Toolbox-AuthPaths-Client/Hosted-Toolbox-AuthPaths-Client.csproj" />
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SessionFilesClient/SessionFilesClient.csproj" />
     <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent/SimpleAgent.csproj" />
   </Folder>
   <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Handoff/">
     <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Handoff/HostedWorkflowHandoff.csproj" />
   </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-AgentSkills/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-AgentSkills/HostedAgentSkills.csproj" />
+  </Folder>
   <Folder Name="/Samples/04-hosting/DurableAgents/" />
   <Folder Name="/Samples/04-hosting/DurableAgents/AzureFunctions/">
     <File Path="samples/04-hosting/DurableAgents/AzureFunctions/.editorconfig" />
@@ -366,7 +408,7 @@
     <Project Path="samples/02-agents/A2A/A2AAgent_PollingForTaskCompletion/A2AAgent_PollingForTaskCompletion.csproj" />
     <Project Path="samples/02-agents/A2A/A2AAgent_ProtocolSelection/A2AAgent_ProtocolSelection.csproj" />
     <Project Path="samples/02-agents/A2A/A2AAgent_StreamReconnection/A2AAgent_StreamReconnection.csproj" />
-  </Folder>  
+  </Folder>
   <Folder Name="/Samples/05-end-to-end/">
     <Project Path="samples/05-end-to-end/AgentWithPurview/AgentWithPurview.csproj" />
     <Project Path="samples/05-end-to-end/M365Agent/M365Agent.csproj" />
@@ -374,6 +416,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/">
@@ -562,7 +605,6 @@
     <Project Path="src/Aspire.Hosting.AgentFramework.DevUI/Aspire.Hosting.AgentFramework.DevUI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.A2A/Microsoft.Agents.AI.A2A.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Abstractions/Microsoft.Agents.AI.Abstractions.csproj" />
-    <Project Path="src/Microsoft.Agents.AI.AGUI/Microsoft.Agents.AI.AGUI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Anthropic/Microsoft.Agents.AI.Anthropic.csproj" />
     <Project Path="src/Microsoft.Agents.AI.AzureAI.Persistent/Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
     <Project Path="src/Microsoft.Agents.AI.CopilotStudio/Microsoft.Agents.AI.CopilotStudio.csproj" />
@@ -573,16 +615,22 @@
     <Project Path="src/Microsoft.Agents.AI.Foundry.Hosting/Microsoft.Agents.AI.Foundry.Hosting.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Foundry/Microsoft.Agents.AI.Foundry.csproj" />
     <Project Path="src/Microsoft.Agents.AI.GitHub.Copilot/Microsoft.Agents.AI.GitHub.Copilot.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Harness/Microsoft.Agents.AI.Harness.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.A2A.AspNetCore/Microsoft.Agents.AI.Hosting.A2A.AspNetCore.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.A2A/Microsoft.Agents.AI.Hosting.A2A.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Hosting.AspNetCore/Microsoft.Agents.AI.Hosting.AspNetCore.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.AzureFunctions/Microsoft.Agents.AI.Hosting.AzureFunctions.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.OpenAI/Microsoft.Agents.AI.Hosting.OpenAI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting/Microsoft.Agents.AI.Hosting.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hyperlight/Microsoft.Agents.AI.Hyperlight.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.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" />
     <Project Path="src/Microsoft.Agents.AI.Purview/Microsoft.Agents.AI.Purview.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Tools.Shell/Microsoft.Agents.AI.Tools.Shell.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Valkey/Microsoft.Agents.AI.Valkey.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative.Foundry/Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative.Mcp/Microsoft.Agents.AI.Workflows.Declarative.Mcp.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative/Microsoft.Agents.AI.Workflows.Declarative.csproj" />
@@ -596,8 +644,8 @@
     <Project Path="tests/AnthropicChatCompletion.IntegrationTests/AnthropicChatCompletion.IntegrationTests.csproj" />
     <Project Path="tests/AzureAIAgentsPersistent.IntegrationTests/AzureAIAgentsPersistent.IntegrationTests.csproj" />
     <Project Path="tests/CopilotStudio.IntegrationTests/CopilotStudio.IntegrationTests.csproj" />
-    <Project Path="tests/Foundry.Hosting.IntegrationTests/Foundry.Hosting.IntegrationTests.csproj" />
     <Project Path="tests/Foundry.Hosting.IntegrationTests.TestContainer/Foundry.Hosting.IntegrationTests.TestContainer.csproj" />
+    <Project Path="tests/Foundry.Hosting.IntegrationTests/Foundry.Hosting.IntegrationTests.csproj" />
     <Project Path="tests/Foundry.IntegrationTests/Foundry.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.DurableTask.IntegrationTests/Microsoft.Agents.AI.DurableTask.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests.csproj" />
@@ -605,6 +653,7 @@
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hyperlight.IntegrationTests/Microsoft.Agents.AI.Hyperlight.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Mem0.IntegrationTests/Microsoft.Agents.AI.Mem0.IntegrationTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Tools.Shell.IntegrationTests/Microsoft.Agents.AI.Tools.Shell.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Workflows.Declarative.IntegrationTests/Microsoft.Agents.AI.Workflows.Declarative.IntegrationTests.csproj" />
     <Project Path="tests/OpenAIAssistant.IntegrationTests/OpenAIAssistant.IntegrationTests.csproj" />
     <Project Path="tests/OpenAIChatCompletion.IntegrationTests/OpenAIChatCompletion.IntegrationTests.csproj" />
@@ -614,29 +663,35 @@
     <Project Path="tests/Aspire.Hosting.AgentFramework.DevUI.UnitTests/Aspire.Hosting.AgentFramework.DevUI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.A2A.UnitTests/Microsoft.Agents.AI.A2A.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Abstractions.UnitTests/Microsoft.Agents.AI.Abstractions.UnitTests.csproj" />
-    <Project Path="tests/Microsoft.Agents.AI.AGUI.UnitTests/Microsoft.Agents.AI.AGUI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Anthropic.UnitTests/Microsoft.Agents.AI.Anthropic.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.AzureAI.Persistent.UnitTests/Microsoft.Agents.AI.AzureAI.Persistent.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.CosmosNoSql.UnitTests/Microsoft.Agents.AI.CosmosNoSql.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Declarative.UnitTests/Microsoft.Agents.AI.Declarative.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.DevUI.UnitTests/Microsoft.Agents.AI.DevUI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.DurableTask.UnitTests/Microsoft.Agents.AI.DurableTask.UnitTests.csproj" />
-    <Project Path="tests/Microsoft.Agents.AI.Foundry.UnitTests/Microsoft.Agents.AI.Foundry.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Foundry.Hosting.UnitTests/Microsoft.Agents.AI.Foundry.Hosting.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Foundry.UnitTests/Microsoft.Agents.AI.Foundry.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Harness.UnitTests/Microsoft.Agents.AI.Harness.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.A2A.UnitTests/Microsoft.Agents.AI.Hosting.A2A.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AzureFunctions.UnitTests/Microsoft.Agents.AI.Hosting.AzureFunctions.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.UnitTests/Microsoft.Agents.AI.Hosting.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hyperlight.UnitTests/Microsoft.Agents.AI.Hyperlight.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.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" />
     <Project Path="tests/Microsoft.Agents.AI.Purview.UnitTests/Microsoft.Agents.AI.Purview.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Tools.Shell.UnitTests/Microsoft.Agents.AI.Tools.Shell.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.UnitTests/Microsoft.Agents.AI.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Valkey.UnitTests/Microsoft.Agents.AI.Valkey.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Workflows.Declarative.Mcp.UnitTests/Microsoft.Agents.AI.Workflows.Declarative.Mcp.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Workflows.Generators.UnitTests/Microsoft.Agents.AI.Workflows.Generators.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Workflows.UnitTests/Microsoft.Agents.AI.Workflows.UnitTests.csproj" />
   </Folder>
 </Solution>
+
+

dotnet/agent-framework-release.slnf

@@ -4,9 +4,9 @@
     "projects": [
       "src\\Microsoft.Agents.AI.A2A\\Microsoft.Agents.AI.A2A.csproj",
       "src\\Microsoft.Agents.AI.Abstractions\\Microsoft.Agents.AI.Abstractions.csproj",
-      "src\\Microsoft.Agents.AI.AGUI\\Microsoft.Agents.AI.AGUI.csproj",
       "src\\Microsoft.Agents.AI.Anthropic\\Microsoft.Agents.AI.Anthropic.csproj",
       "src\\Microsoft.Agents.AI.GitHub.Copilot\\Microsoft.Agents.AI.GitHub.Copilot.csproj",
+      "src\\Microsoft.Agents.AI.Harness\\Microsoft.Agents.AI.Harness.csproj",
       "src\\Microsoft.Agents.AI.AzureAI.Persistent\\Microsoft.Agents.AI.AzureAI.Persistent.csproj",
       "src\\Microsoft.Agents.AI.Foundry\\Microsoft.Agents.AI.Foundry.csproj",
       "src\\Microsoft.Agents.AI.Foundry.Hosting\\Microsoft.Agents.AI.Foundry.Hosting.csproj",
@@ -19,18 +19,23 @@
       "src\\Microsoft.Agents.AI.Hosting.A2A.AspNetCore\\Microsoft.Agents.AI.Hosting.A2A.AspNetCore.csproj",
       "src\\Microsoft.Agents.AI.Hosting.A2A\\Microsoft.Agents.AI.Hosting.A2A.csproj",
       "src\\Microsoft.Agents.AI.Hosting.AGUI.AspNetCore\\Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.csproj",
-      "src\\Microsoft.Agents.AI.Hosting.AzureFunctions\\Microsoft.Agents.AI.Hosting.AzureFunctions.csproj",
+      "src\\Microsoft.Agents.AI.Hosting.AspNetCore\\Microsoft.Agents.AI.Hosting.AspNetCore.csproj",
+      "src\\Microsoft.Agents.AI.Hosting.AzureFunctions\\Microsoft.Agents.AI.Hosting.AzureFunctions.csproj",      
       "src\\Microsoft.Agents.AI.Hosting.OpenAI\\Microsoft.Agents.AI.Hosting.OpenAI.csproj",
       "src\\Microsoft.Agents.AI.Hosting\\Microsoft.Agents.AI.Hosting.csproj",
+      "src\\Microsoft.Agents.AI.Mcp\\Microsoft.Agents.AI.Mcp.csproj",
       "src\\Microsoft.Agents.AI.Mem0\\Microsoft.Agents.AI.Mem0.csproj",
       "src\\Microsoft.Agents.AI.OpenAI\\Microsoft.Agents.AI.OpenAI.csproj",
       "src\\Microsoft.Agents.AI.Purview\\Microsoft.Agents.AI.Purview.csproj",
+      "src\\Microsoft.Agents.AI.Tools.Shell\\Microsoft.Agents.AI.Tools.Shell.csproj",
       "src\\Microsoft.Agents.AI.Workflows.Declarative.Foundry\\Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj",
+      "src\\Microsoft.Agents.AI.Workflows.Declarative.Mcp\\Microsoft.Agents.AI.Workflows.Declarative.Mcp.csproj",
       "src\\Microsoft.Agents.AI.Workflows.Declarative\\Microsoft.Agents.AI.Workflows.Declarative.csproj",
       "src\\Microsoft.Agents.AI.Workflows.Generators\\Microsoft.Agents.AI.Workflows.Generators.csproj",
       "src\\Microsoft.Agents.AI.Workflows\\Microsoft.Agents.AI.Workflows.csproj",
       "src\\Microsoft.Agents.AI\\Microsoft.Agents.AI.csproj",
-      "src\\Aspire.Hosting.AgentFramework.DevUI\\Aspire.Hosting.AgentFramework.DevUI.csproj"
+      "src\\Aspire.Hosting.AgentFramework.DevUI\\Aspire.Hosting.AgentFramework.DevUI.csproj",
+      "src\\Microsoft.Agents.AI.Hyperlight\\Microsoft.Agents.AI.Hyperlight.csproj"
     ]
   }
 }

dotnet/eng/MSBuild/Shared.props

@@ -11,9 +11,6 @@
   <ItemGroup Condition="'$(InjectSharedIntegrationTestAzureCredentialsCode)' == 'true'">
     <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\IntegrationTestsAzureCredentials\*.cs" LinkBase="Shared\IntegrationTestsAzureCredentials" />
   </ItemGroup>
-  <ItemGroup Condition="'$(InjectSharedBuildTestCode)' == 'true'">
-    <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\CodeTests\*.cs" LinkBase="Shared\CodeTests" />
-  </ItemGroup>
   <ItemGroup Condition="'$(InjectSharedWorkflowsExecution)' == 'true'">
     <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\Workflows\Execution\*.cs" LinkBase="Shared\Workflows" />
   </ItemGroup>

dotnet/eng/scripts/New-FilteredSolution.ps1

@@ -21,10 +21,15 @@
 .PARAMETER Configuration
     Optional MSBuild configuration used when querying TargetFrameworks. Defaults to Debug.
 
-.PARAMETER TestProjectNameFilter
+.PARAMETER TestProjectNameIncludeFilter
     Optional wildcard pattern to filter test project names (e.g., *UnitTests*, *IntegrationTests*).
     When specified, only test projects whose filename matches this pattern are kept.
 
+.PARAMETER TestProjectNameExcludeFilter
+    Optional wildcard pattern(s) to exclude test projects by name (e.g., *DurableTask.IntegrationTests*).
+    When specified, test projects whose filename matches any of these patterns are removed.
+    Applied after TestProjectNameIncludeFilter. Can be a single string or an array of strings.
+
 .PARAMETER ExcludeSamples
     When specified, removes all projects under the samples/ directory from the solution.
 
@@ -38,11 +43,15 @@
 
 .EXAMPLE
     # Generate a solution with only unit test projects
-    ./dotnet/eng/scripts/New-FilteredSolution.ps1 -Solution dotnet/agent-framework-dotnet.slnx -TargetFramework net10.0 -TestProjectNameFilter "*UnitTests*" -OutputPath filtered-unit.slnx
+    ./dotnet/eng/scripts/New-FilteredSolution.ps1 -Solution dotnet/agent-framework-dotnet.slnx -TargetFramework net10.0 -TestProjectNameIncludeFilter "*UnitTests*" -OutputPath filtered-unit.slnx
 
 .EXAMPLE
     # Inline usage with dotnet test (PowerShell)
     dotnet test --solution (./dotnet/eng/scripts/New-FilteredSolution.ps1 -Solution dotnet/agent-framework-dotnet.slnx -TargetFramework net472) --no-build -f net472
+
+.EXAMPLE
+    # Generate integration tests excluding DurableTask and AzureFunctions
+    ./dotnet/eng/scripts/New-FilteredSolution.ps1 -Solution dotnet/agent-framework-dotnet.slnx -TargetFramework net10.0 -TestProjectNameIncludeFilter "*IntegrationTests*" -TestProjectNameExcludeFilter "*DurableTask.IntegrationTests*","*AzureFunctions.IntegrationTests*" -OutputPath filtered-other-integration.slnx
 #>
 
 [CmdletBinding()]
@@ -55,7 +64,9 @@ param(
 
     [string]$Configuration = "Debug",
 
-    [string]$TestProjectNameFilter,
+    [string]$TestProjectNameIncludeFilter,
+
+    [string[]]$TestProjectNameExcludeFilter,
 
     [switch]$ExcludeSamples,
 
@@ -100,13 +111,30 @@ foreach ($proj in $allProjects) {
     $isTestProject = $projRelPath -like "*tests/*"
 
     # Filter test projects by name pattern if specified
-    if ($isTestProject -and $TestProjectNameFilter -and ($projFileName -notlike $TestProjectNameFilter)) {
+    if ($isTestProject -and $TestProjectNameIncludeFilter -and ($projFileName -notlike $TestProjectNameIncludeFilter)) {
         Write-Verbose "Removing (name filter): $projRelPath"
         $removed += $projRelPath
         $proj.ParentNode.RemoveChild($proj) | Out-Null
         continue
     }
 
+    # Exclude test projects matching any exclusion pattern
+    if ($isTestProject -and $TestProjectNameExcludeFilter) {
+        $excluded = $false
+        foreach ($pattern in $TestProjectNameExcludeFilter) {
+            if ($projFileName -like $pattern) {
+                $excluded = $true
+                break
+            }
+        }
+        if ($excluded) {
+            Write-Verbose "Removing (exclude filter): $projRelPath"
+            $removed += $projRelPath
+            $proj.ParentNode.RemoveChild($proj) | Out-Null
+            continue
+        }
+    }
+
     if (-not (Test-Path $projFullPath)) {
         Write-Verbose "Project not found, keeping in solution: $projRelPath"
         $kept += $projRelPath

dotnet/eng/verify-samples/AgentsSamples.cs

@@ -14,7 +14,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "Agent_With_CustomImplementation",
-            ProjectPath = "samples/02-agents/AgentProviders/Agent_With_CustomImplementation",
+            ProjectPath = "samples/02-agents/AgentProviders/custom/Agent_With_CustomImplementation",
             RequiredEnvironmentVariables = [],
             ExpectedOutputDescription =
             [
@@ -27,7 +27,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "Agent_With_AzureOpenAIChatCompletion",
-            ProjectPath = "samples/02-agents/AgentProviders/Agent_With_AzureOpenAIChatCompletion",
+            ProjectPath = "samples/02-agents/AgentProviders/azure/Agent_With_AzureOpenAIChatCompletion",
             RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
             OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
             ExpectedOutputDescription =
@@ -40,7 +40,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "Agent_With_AzureOpenAIResponses",
-            ProjectPath = "samples/02-agents/AgentProviders/Agent_With_AzureOpenAIResponses",
+            ProjectPath = "samples/02-agents/AgentProviders/azure/Agent_With_AzureOpenAIResponses",
             RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
             OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
             ExpectedOutputDescription =
@@ -50,23 +50,10 @@ internal static class AgentsSamples
             ],
         },
 
-        new SampleDefinition
-        {
-            Name = "Agent_With_AzureAIAgentsPersistent",
-            ProjectPath = "samples/02-agents/AgentProviders/Agent_With_AzureAIAgentsPersistent",
-            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
-            ExpectedOutputDescription =
-            [
-                "The output should contain a joke about a pirate.",
-                "The output should not contain error messages or stack traces.",
-            ],
-        },
-
         new SampleDefinition
         {
             Name = "Agent_With_AzureAIProject",
-            ProjectPath = "samples/02-agents/AgentProviders/Agent_With_AzureAIProject",
+            ProjectPath = "samples/02-agents/AgentProviders/azure/Agent_With_AzureAIProject",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
             OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
             MustContain = ["Latest agent version id:"],
@@ -80,7 +67,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "Agent_With_AzureFoundryModel",
-            ProjectPath = "samples/02-agents/AgentProviders/Agent_With_AzureFoundryModel",
+            ProjectPath = "samples/02-agents/AgentProviders/azure/Agent_With_AzureFoundryModel",
             RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
             OptionalEnvironmentVariables = ["AZURE_OPENAI_API_KEY", "AZURE_AI_MODEL_DEPLOYMENT_NAME"],
             ExpectedOutputDescription =
@@ -348,8 +335,8 @@ internal static class AgentsSamples
         {
             Name = "Agent_Step01_FileBasedSkills",
             ProjectPath = "samples/02-agents/AgentSkills/Agent_Step01_FileBasedSkills",
-            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             MustContain =
             [
                 "Converting units with file-based skills",
@@ -363,6 +350,25 @@ internal static class AgentsSamples
             ],
         },
 
+        new SampleDefinition
+        {
+            Name = "Agent_Step06_McpBasedSkills",
+            ProjectPath = "samples/02-agents/AgentSkills/Agent_Step06_McpBasedSkills",
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
+            MustContain =
+            [
+                "Discovering MCP-based skills",
+                "Agent:",
+            ],
+            ExpectedOutputDescription =
+            [
+                "The output should show the agent converting 26.2 miles to kilometers and 75 kilograms to pounds.",
+                "The response should contain approximate numeric values for both conversions.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
         // ── AgentWithMemory ─────────────────────────────────────────────────
 
         new SampleDefinition
@@ -471,12 +477,12 @@ internal static class AgentsSamples
             ],
         },
 
-        // ── AgentsWithFoundry ────────────────────────────────────────────────
+        // ── Foundry ───────────────────────────────────────────────────────────
 
         new SampleDefinition
         {
             Name = "FoundryAgent_Step00_FoundryAgentLifecycle",
-            ProjectPath = "samples/02-agents/AgentsWithFoundry/Agent_Step00_FoundryAgentLifecycle",
+            ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step00_FoundryAgentLifecycle",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
             OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
             ExpectedOutputDescription =
@@ -489,7 +495,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "FoundryAgent_Step01_Basics",
-            ProjectPath = "samples/02-agents/AgentsWithFoundry/Agent_Step01_Basics",
+            ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step01_Basics",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
             OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
             ExpectedOutputDescription =
@@ -502,7 +508,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "FoundryAgent_Step02.1_MultiturnConversation",
-            ProjectPath = "samples/02-agents/AgentsWithFoundry/Agent_Step02.1_MultiturnConversation",
+            ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step02.1_MultiturnConversation",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
             OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
             ExpectedOutputDescription =
@@ -516,7 +522,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "FoundryAgent_Step02.2_MultiturnWithServerConversations",
-            ProjectPath = "samples/02-agents/AgentsWithFoundry/Agent_Step02.2_MultiturnWithServerConversations",
+            ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step02.2_MultiturnWithServerConversations",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
             OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
             ExpectedOutputDescription =
@@ -529,7 +535,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "FoundryAgent_Step03_UsingFunctionTools",
-            ProjectPath = "samples/02-agents/AgentsWithFoundry/Agent_Step03_UsingFunctionTools",
+            ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step03_UsingFunctionTools",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
             OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
             ExpectedOutputDescription =
@@ -544,7 +550,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "FoundryAgent_Step04_UsingFunctionToolsWithApprovals",
-            ProjectPath = "samples/02-agents/AgentsWithFoundry/Agent_Step04_UsingFunctionToolsWithApprovals",
+            ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step04_UsingFunctionToolsWithApprovals",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
             OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
             Inputs = ["Y", "Y", "Y"],
@@ -560,7 +566,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "FoundryAgent_Step05_StructuredOutput",
-            ProjectPath = "samples/02-agents/AgentsWithFoundry/Agent_Step05_StructuredOutput",
+            ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step05_StructuredOutput",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
             OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
             MustContain = ["Assistant Output:", "Name:"],
@@ -575,7 +581,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "FoundryAgent_Step06_PersistedConversations",
-            ProjectPath = "samples/02-agents/AgentsWithFoundry/Agent_Step06_PersistedConversations",
+            ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step06_PersistedConversations",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
             OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
             ExpectedOutputDescription =
@@ -588,7 +594,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "FoundryAgent_Step08_DependencyInjection",
-            ProjectPath = "samples/02-agents/AgentsWithFoundry/Agent_Step08_DependencyInjection",
+            ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step08_DependencyInjection",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
             OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
             Inputs = ["Tell me a joke about a pirate", ""],
@@ -603,7 +609,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "FoundryAgent_Step10_UsingImages",
-            ProjectPath = "samples/02-agents/AgentsWithFoundry/Agent_Step10_UsingImages",
+            ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step10_UsingImages",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
             OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
             ExpectedOutputDescription =
@@ -617,7 +623,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "FoundryAgent_Step11_AsFunctionTool",
-            ProjectPath = "samples/02-agents/AgentsWithFoundry/Agent_Step11_AsFunctionTool",
+            ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step11_AsFunctionTool",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
             OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
             ExpectedOutputDescription =
@@ -631,7 +637,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "FoundryAgent_Step12_Middleware",
-            ProjectPath = "samples/02-agents/AgentsWithFoundry/Agent_Step12_Middleware",
+            ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step12_Middleware",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
             OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
             Inputs = ["Y", "Y", "Y"],
@@ -647,7 +653,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "FoundryAgent_Step13_Plugins",
-            ProjectPath = "samples/02-agents/AgentsWithFoundry/Agent_Step13_Plugins",
+            ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step13_Plugins",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
             OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
             ExpectedOutputDescription =
@@ -661,7 +667,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "FoundryAgent_Step14_CodeInterpreter",
-            ProjectPath = "samples/02-agents/AgentsWithFoundry/Agent_Step14_CodeInterpreter",
+            ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step14_CodeInterpreter",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
             OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
             ExpectedOutputDescription =
@@ -676,7 +682,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "FoundryAgent_Step16_FileSearch",
-            ProjectPath = "samples/02-agents/AgentsWithFoundry/Agent_Step16_FileSearch",
+            ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step16_FileSearch",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
             OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
             MustContain = ["--- Running File Search Agent ---"],
@@ -690,12 +696,12 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "FoundryAgent_Step17_OpenAPITools",
-            ProjectPath = "samples/02-agents/AgentsWithFoundry/Agent_Step17_OpenAPITools",
+            ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step17_OpenAPITools",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
             OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
             ExpectedOutputDescription =
             [
-                "The output should contain a list of countries or information about countries that use the EUR currency.",
+                "The output should contain the current EUR exchange rate against USD and GBP as numeric values.",
                 "The output should not contain error messages or stack traces.",
             ],
         },
@@ -714,7 +720,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "Agent_With_A2A",
-            ProjectPath = "samples/02-agents/AgentProviders/Agent_With_A2A",
+            ProjectPath = "samples/02-agents/AgentProviders/a2a/Agent_With_A2A",
             RequiredEnvironmentVariables = ["A2A_AGENT_HOST"],
             SkipReason = "Requires an external A2A agent host.",
         },
@@ -722,7 +728,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "Agent_With_Anthropic",
-            ProjectPath = "samples/02-agents/AgentProviders/Agent_With_Anthropic",
+            ProjectPath = "samples/02-agents/AgentProviders/anthropic/Agent_With_Anthropic",
             RequiredEnvironmentVariables = ["ANTHROPIC_API_KEY"],
             OptionalEnvironmentVariables = ["ANTHROPIC_CHAT_MODEL_NAME", "ANTHROPIC_RESOURCE"],
             ExpectedOutputDescription =
@@ -735,7 +741,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "Agent_With_GitHubCopilot",
-            ProjectPath = "samples/02-agents/AgentProviders/Agent_With_GitHubCopilot",
+            ProjectPath = "samples/02-agents/AgentProviders/github-copilot/Agent_With_GitHubCopilot",
             RequiredEnvironmentVariables = [],
             // The sample prompts for shell command approval; provide "Y" for each possible permission request
             Inputs = ["Y", "Y", "Y"],
@@ -750,7 +756,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "Agent_With_GoogleGemini",
-            ProjectPath = "samples/02-agents/AgentProviders/Agent_With_GoogleGemini",
+            ProjectPath = "samples/02-agents/AgentProviders/google-gemini/Agent_With_GoogleGemini",
             RequiredEnvironmentVariables = ["GOOGLE_GENAI_API_KEY"],
             OptionalEnvironmentVariables = ["GOOGLE_GENAI_MODEL"],
             MustContain =
@@ -768,7 +774,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "Agent_With_ONNX",
-            ProjectPath = "samples/02-agents/AgentProviders/Agent_With_ONNX",
+            ProjectPath = "samples/02-agents/AgentProviders/onnx/Agent_With_ONNX",
             RequiredEnvironmentVariables = ["ONNX_MODEL_PATH"],
             SkipReason = "Requires local ONNX model.",
         },
@@ -776,7 +782,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "Agent_With_Ollama",
-            ProjectPath = "samples/02-agents/AgentProviders/Agent_With_Ollama",
+            ProjectPath = "samples/02-agents/AgentProviders/ollama/Agent_With_Ollama",
             RequiredEnvironmentVariables = ["OLLAMA_ENDPOINT", "OLLAMA_MODEL_NAME"],
             SkipReason = "Requires local Ollama server.",
         },
@@ -784,7 +790,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "Agent_With_OpenAIChatCompletion",
-            ProjectPath = "samples/02-agents/AgentProviders/Agent_With_OpenAIChatCompletion",
+            ProjectPath = "samples/02-agents/AgentProviders/openai/Agent_With_OpenAIChatCompletion",
             RequiredEnvironmentVariables = ["OPENAI_API_KEY"],
             OptionalEnvironmentVariables = ["OPENAI_CHAT_MODEL_NAME"],
             ExpectedOutputDescription =
@@ -797,7 +803,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "Agent_With_OpenAIResponses",
-            ProjectPath = "samples/02-agents/AgentProviders/Agent_With_OpenAIResponses",
+            ProjectPath = "samples/02-agents/AgentProviders/openai/Agent_With_OpenAIResponses",
             RequiredEnvironmentVariables = ["OPENAI_API_KEY"],
             OptionalEnvironmentVariables = ["OPENAI_CHAT_MODEL_NAME"],
             ExpectedOutputDescription =
@@ -837,7 +843,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "Agent_Anthropic_Step01_Running",
-            ProjectPath = "samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step01_Running",
+            ProjectPath = "samples/02-agents/AgentProviders/anthropic/Agent_Anthropic_Step01_Running",
             RequiredEnvironmentVariables = ["ANTHROPIC_API_KEY"],
             OptionalEnvironmentVariables = ["ANTHROPIC_CHAT_MODEL_NAME"],
             ExpectedOutputDescription =
@@ -851,7 +857,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "Agent_Anthropic_Step02_Reasoning",
-            ProjectPath = "samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step02_Reasoning",
+            ProjectPath = "samples/02-agents/AgentProviders/anthropic/Agent_Anthropic_Step02_Reasoning",
             RequiredEnvironmentVariables = ["ANTHROPIC_API_KEY"],
             OptionalEnvironmentVariables = ["ANTHROPIC_CHAT_MODEL_NAME"],
             MustContain =
@@ -874,7 +880,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "Agent_Anthropic_Step03_UsingFunctionTools",
-            ProjectPath = "samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step03_UsingFunctionTools",
+            ProjectPath = "samples/02-agents/AgentProviders/anthropic/Agent_Anthropic_Step03_UsingFunctionTools",
             RequiredEnvironmentVariables = ["ANTHROPIC_API_KEY"],
             OptionalEnvironmentVariables = ["ANTHROPIC_CHAT_MODEL_NAME"],
             ExpectedOutputDescription =
@@ -888,7 +894,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "Agent_Anthropic_Step04_UsingSkills",
-            ProjectPath = "samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step04_UsingSkills",
+            ProjectPath = "samples/02-agents/AgentProviders/anthropic/Agent_Anthropic_Step04_UsingSkills",
             RequiredEnvironmentVariables = ["ANTHROPIC_API_KEY"],
             OptionalEnvironmentVariables = ["ANTHROPIC_CHAT_MODEL_NAME"],
             MustContain =
@@ -915,7 +921,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "Agent_OpenAI_Step01_Running",
-            ProjectPath = "samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step01_Running",
+            ProjectPath = "samples/02-agents/AgentProviders/openai/Agent_OpenAI_Step01_Running",
             RequiredEnvironmentVariables = ["OPENAI_API_KEY"],
             OptionalEnvironmentVariables = ["OPENAI_CHAT_MODEL_NAME"],
             ExpectedOutputDescription =
@@ -928,7 +934,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "Agent_OpenAI_Step02_Reasoning",
-            ProjectPath = "samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step02_Reasoning",
+            ProjectPath = "samples/02-agents/AgentProviders/openai/Agent_OpenAI_Step02_Reasoning",
             RequiredEnvironmentVariables = ["OPENAI_API_KEY"],
             OptionalEnvironmentVariables = ["OPENAI_CHAT_MODEL_NAME"],
             MustContain =
@@ -948,7 +954,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "Agent_OpenAI_Step03_CreateFromChatClient",
-            ProjectPath = "samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step03_CreateFromChatClient",
+            ProjectPath = "samples/02-agents/AgentProviders/openai/Agent_OpenAI_Step03_CreateFromChatClient",
             RequiredEnvironmentVariables = ["OPENAI_API_KEY"],
             OptionalEnvironmentVariables = ["OPENAI_CHAT_MODEL_NAME"],
             ExpectedOutputDescription =
@@ -962,7 +968,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "Agent_OpenAI_Step04_CreateFromOpenAIResponseClient",
-            ProjectPath = "samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient",
+            ProjectPath = "samples/02-agents/AgentProviders/openai/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient",
             RequiredEnvironmentVariables = ["OPENAI_API_KEY"],
             OptionalEnvironmentVariables = ["OPENAI_CHAT_MODEL_NAME"],
             ExpectedOutputDescription =
@@ -976,7 +982,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "Agent_OpenAI_Step05_Conversation",
-            ProjectPath = "samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step05_Conversation",
+            ProjectPath = "samples/02-agents/AgentProviders/openai/Agent_OpenAI_Step05_Conversation",
             RequiredEnvironmentVariables = ["OPENAI_API_KEY"],
             OptionalEnvironmentVariables = ["OPENAI_CHAT_MODEL_NAME"],
             MustContain =
@@ -1023,7 +1029,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "FoundryAgent_Step07_Observability",
-            ProjectPath = "samples/02-agents/AgentsWithFoundry/Agent_Step07_Observability",
+            ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step07_Observability",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
             OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME", "APPLICATIONINSIGHTS_CONNECTION_STRING"],
             SkipReason = "Requires Application Insights / OpenTelemetry infrastructure.",
@@ -1032,7 +1038,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "FoundryAgent_Step09_UsingMcpClientAsTools",
-            ProjectPath = "samples/02-agents/AgentsWithFoundry/Agent_Step09_UsingMcpClientAsTools",
+            ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step09_UsingMcpClientAsTools",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
             OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
             ExpectedOutputDescription =
@@ -1045,16 +1051,16 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "FoundryAgent_Step15_ComputerUse",
-            ProjectPath = "samples/02-agents/AgentsWithFoundry/Agent_Step15_ComputerUse",
-            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step15_ComputerUse",
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT", "AZURE_AI_COMPUTER_USE_DEPLOYMENT_NAME"],
+            OptionalEnvironmentVariables = [],
             ExpectedOutputDescription = ["The output should show a computer automation session processing simulated browser screenshots with iteration steps and a final response describing search results."],
         },
 
         new SampleDefinition
         {
             Name = "FoundryAgent_Step18_BingCustomSearch",
-            ProjectPath = "samples/02-agents/AgentsWithFoundry/Agent_Step18_BingCustomSearch",
+            ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step18_BingCustomSearch",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT", "AZURE_AI_MODEL_DEPLOYMENT_NAME", "AZURE_AI_CUSTOM_SEARCH_CONNECTION_ID", "AZURE_AI_CUSTOM_SEARCH_INSTANCE_NAME"],
             SkipReason = "Requires Bing Custom Search connection.",
         },
@@ -1062,7 +1068,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "FoundryAgent_Step19_SharePoint",
-            ProjectPath = "samples/02-agents/AgentsWithFoundry/Agent_Step19_SharePoint",
+            ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step19_SharePoint",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT", "AZURE_AI_MODEL_DEPLOYMENT_NAME", "SHAREPOINT_PROJECT_CONNECTION_ID"],
             SkipReason = "Requires SharePoint connection.",
         },
@@ -1070,7 +1076,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "FoundryAgent_Step20_MicrosoftFabric",
-            ProjectPath = "samples/02-agents/AgentsWithFoundry/Agent_Step20_MicrosoftFabric",
+            ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step20_MicrosoftFabric",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT", "AZURE_AI_MODEL_DEPLOYMENT_NAME", "FABRIC_PROJECT_CONNECTION_ID"],
             SkipReason = "Requires Microsoft Fabric connection.",
         },
@@ -1078,7 +1084,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "FoundryAgent_Step21_WebSearch",
-            ProjectPath = "samples/02-agents/AgentsWithFoundry/Agent_Step21_WebSearch",
+            ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step21_WebSearch",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
             OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
             ExpectedOutputDescription =
@@ -1091,7 +1097,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "FoundryAgent_Step22_MemorySearch",
-            ProjectPath = "samples/02-agents/AgentsWithFoundry/Agent_Step22_MemorySearch",
+            ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step22_MemorySearch",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT", "AZURE_AI_MODEL_DEPLOYMENT_NAME", "AZURE_AI_EMBEDDING_DEPLOYMENT_NAME"],
             OptionalEnvironmentVariables = ["AZURE_AI_MEMORY_STORE_ID"],
             MustContain = ["Agent created with Memory Search tool. Starting conversation..."],
@@ -1105,7 +1111,7 @@ internal static class AgentsSamples
         new SampleDefinition
         {
             Name = "FoundryAgent_Step23_LocalMCP",
-            ProjectPath = "samples/02-agents/AgentsWithFoundry/Agent_Step23_LocalMCP",
+            ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step23_LocalMCP",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
             OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
             ExpectedOutputDescription = ["The output should show an agent using the Microsoft Learn MCP server to search for documentation and provide a response."],
@@ -1151,6 +1157,25 @@ internal static class AgentsSamples
             SkipReason = "Runs as an MCP stdio server that does not exit on its own.",
         },
 
+        new SampleDefinition
+        {
+            Name = "Agent_MCP_LongRunningTask_Client",
+            ProjectPath = "samples/02-agents/ModelContextProtocol/Agent_MCP_LongRunningTask_Client",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            MustContain =
+            [
+                "=== Transparent long-running MCP task (RunAsync) ===",
+                "=== Transparent long-running MCP task (RunStreamingAsync) ===",
+            ],
+            ExpectedOutputDescription =
+            [
+                "The output should show an agent analyzing a dataset named 'sales-2025-q1' and producing a summary mentioning rows, revenue, anomalies, or outliers.",
+                "The output should contain both a non-streaming response (after RunAsync) and a streaming response (after RunStreamingAsync) for the same analysis question.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
         new SampleDefinition
         {
             Name = "AGUI_Step01_GettingStarted_Client",

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/eng/verify-samples/Program.cs

@@ -18,13 +18,14 @@
 // Note: By default, this tool expects sample build outputs to already exist.
 // Pre-build the solution before running, or pass --build to avoid missing build output failures.
 //
-// Required environment variables (for AI-powered samples):
-//   AZURE_OPENAI_ENDPOINT
-//   AZURE_OPENAI_DEPLOYMENT_NAME (optional, defaults to gpt-5-mini)
+// Required environment variables (for AI-powered verification):
+//   FOUNDRY_PROJECT_ENDPOINT  — Your Azure AI Foundry project endpoint
+//   FOUNDRY_MODEL             — Model deployment name (optional, defaults to gpt-5.4-mini)
 
 using System.Diagnostics;
-using Azure.AI.OpenAI;
+using Azure.AI.Projects;
 using Azure.Identity;
+using Microsoft.Agents.AI;
 using VerifySamples;
 
 var options = VerifyOptions.Parse(args);
@@ -43,14 +44,33 @@ if (!File.Exists(Path.Combine(dotnetRoot, "agent-framework-dotnet.slnx")))
 }
 
 // Set up the AI verifier
-var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5-mini";
+var foundryEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT");
+var foundryModel = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
 
-OpenAI.Chat.ChatClient? chatClient = null;
-if (!string.IsNullOrEmpty(endpoint))
+AIAgent? verifierAgent = null;
+if (!string.IsNullOrEmpty(foundryEndpoint))
 {
-    chatClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
-        .GetChatClient(deploymentName);
+    verifierAgent = new AIProjectClient(new Uri(foundryEndpoint), new DefaultAzureCredential())
+        .AsAIAgent(
+            model: foundryModel,
+            instructions: """
+                You are a test output verifier. You will be given:
+                1. The actual stdout output of a program
+                2. The stderr output (if any)
+                3. A list of expectations about what the output should contain or demonstrate
+
+                Your job is to determine whether the actual output satisfies each expectation.
+                Be reasonable — the output comes from an LLM so exact wording won't match, but the
+                semantic intent should be clearly satisfied.
+
+                In your response, you MUST:
+                - Always provide ai_reasoning with a brief overall assessment.
+                - Always provide exactly one entry in expectation_results for each expectation,
+                  in the same order as the input list.
+                - For each expectation_results entry, echo the expectation text in the expectation
+                  field and explain your assessment in the detail field, citing evidence from the output.
+                """,
+            name: "OutputVerifier");
 }
 
 // Set up optional log file writer
@@ -61,11 +81,13 @@ if (options.LogFilePath is not null)
     await logWriter.WriteHeaderAsync();
 }
 
+Console.WriteLine($"Foundry endpoint: {foundryEndpoint ?? "(not set — AI verification disabled)"}, Model: {foundryModel}");
+
 try
 {
     // Run all samples
     var reporter = new ConsoleReporter();
-    var verifier = new SampleVerifier(chatClient);
+    var verifier = new SampleVerifier(verifierAgent);
     var orchestrator = new VerificationOrchestrator(verifier, reporter, dotnetRoot, TimeSpan.FromMinutes(3), logWriter, buildSamples: options.BuildSamples);
 
     var run = await orchestrator.RunAllAsync(options.Samples, options.MaxParallelism);

dotnet/eng/verify-samples/SampleVerifier.cs

@@ -3,8 +3,6 @@
 using System.ComponentModel;
 using System.Text.Json.Serialization;
 using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-using OpenAI.Chat;
 
 namespace VerifySamples;
 
@@ -17,33 +15,12 @@ internal sealed class SampleVerifier
     private readonly AIAgent? _verifierAgent;
 
     /// <summary>
-    /// Creates a verifier. If <paramref name="chatClient"/> is provided,
+    /// Creates a verifier. If <paramref name="verifierAgent"/> is provided,
     /// AI-based verification is available for non-deterministic samples.
     /// </summary>
-    public SampleVerifier(ChatClient? chatClient = null)
+    public SampleVerifier(AIAgent? verifierAgent = null)
     {
-        if (chatClient is not null)
-        {
-            this._verifierAgent = chatClient.AsAIAgent(
-                instructions: """
-                    You are a test output verifier. You will be given:
-                    1. The actual stdout output of a program
-                    2. The stderr output (if any)
-                    3. A list of expectations about what the output should contain or demonstrate
-
-                    Your job is to determine whether the actual output satisfies each expectation.
-                    Be reasonable — the output comes from an LLM so exact wording won't match, but the
-                    semantic intent should be clearly satisfied.
-
-                    In your response, you MUST:
-                    - Always provide ai_reasoning with a brief overall assessment.
-                    - Always provide exactly one entry in expectation_results for each expectation,
-                      in the same order as the input list.
-                    - For each expectation_results entry, echo the expectation text in the expectation
-                      field and explain your assessment in the detail field, citing evidence from the output.
-                    """,
-                name: "OutputVerifier");
-        }
+        this._verifierAgent = verifierAgent;
     }
 
     /// <summary>

dotnet/eng/verify-samples/WorkflowSamples.cs

@@ -30,8 +30,8 @@ internal static class WorkflowSamples
         {
             Name = "Workflow_StartHere_02_AgentsInWorkflows",
             ProjectPath = "samples/03-workflows/_StartHere/02_AgentsInWorkflows",
-            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             ExpectedOutputDescription =
             [
                 "The output should show agent responses from a translation workflow.",
@@ -43,8 +43,8 @@ internal static class WorkflowSamples
         {
             Name = "Workflow_StartHere_03_AgentWorkflowPatterns",
             ProjectPath = "samples/03-workflows/_StartHere/03_AgentWorkflowPatterns",
-            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             Inputs = ["sequential"],
             InputDelayMs = 3000,
             ExpectedOutputDescription =
@@ -81,8 +81,8 @@ internal static class WorkflowSamples
         {
             Name = "Workflow_StartHere_06_MixedWorkflowAgentsAndExecutors",
             ProjectPath = "samples/03-workflows/_StartHere/06_MixedWorkflowAgentsAndExecutors",
-            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             Inputs = ["What is 2 plus 2?"],
             InputDelayMs = 3000,
             ExpectedOutputDescription =
@@ -96,8 +96,8 @@ internal static class WorkflowSamples
         {
             Name = "Workflow_StartHere_07_WriterCriticWorkflow",
             ProjectPath = "samples/03-workflows/_StartHere/07_WriterCriticWorkflow",
-            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             MustContain = ["=== Writer-Critic Iteration Workflow ==="],
             ExpectedOutputDescription =
             [
@@ -115,8 +115,8 @@ internal static class WorkflowSamples
         {
             Name = "Workflow_Agents_CustomAgentExecutors",
             ProjectPath = "samples/03-workflows/Agents/CustomAgentExecutors",
-            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             ExpectedOutputDescription =
             [
                 "The output should show custom workflow events including slogan generation and feedback.",
@@ -128,8 +128,8 @@ internal static class WorkflowSamples
         {
             Name = "Workflow_Agents_FoundryAgent",
             ProjectPath = "samples/03-workflows/Agents/FoundryAgent",
-            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             SkipReason = "Requires Azure AI Foundry project endpoint.",
         },
 
@@ -137,8 +137,8 @@ internal static class WorkflowSamples
         {
             Name = "Workflow_Agents_GroupChatToolApproval",
             ProjectPath = "samples/03-workflows/Agents/GroupChatToolApproval",
-            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             MustContain = ["Starting group chat workflow for software deployment..."],
             ExpectedOutputDescription =
             [
@@ -153,8 +153,8 @@ internal static class WorkflowSamples
         {
             Name = "Workflow_Agents_WorkflowAsAnAgent",
             ProjectPath = "samples/03-workflows/Agents/WorkflowAsAnAgent",
-            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             Inputs = ["hello", "exit"],
             InputDelayMs = 5000,
             ExpectedOutputDescription =
@@ -219,8 +219,8 @@ internal static class WorkflowSamples
         {
             Name = "Workflow_Concurrent_Concurrent",
             ProjectPath = "samples/03-workflows/Concurrent/Concurrent",
-            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             ExpectedOutputDescription =
             [
                 "The output should show results from concurrent agent processing.",
@@ -247,8 +247,8 @@ internal static class WorkflowSamples
         {
             Name = "Workflow_ConditionalEdges_01_EdgeCondition",
             ProjectPath = "samples/03-workflows/ConditionalEdges/01_EdgeCondition",
-            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             ExpectedOutputDescription =
             [
                 "The output should show an email being classified as spam or not spam and processed accordingly.",
@@ -260,8 +260,8 @@ internal static class WorkflowSamples
         {
             Name = "Workflow_ConditionalEdges_02_SwitchCase",
             ProjectPath = "samples/03-workflows/ConditionalEdges/02_SwitchCase",
-            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             ExpectedOutputDescription =
             [
                 "The output should show an ambiguous email being classified as spam, not spam, or uncertain.",
@@ -273,8 +273,8 @@ internal static class WorkflowSamples
         {
             Name = "Workflow_ConditionalEdges_03_MultiSelection",
             ProjectPath = "samples/03-workflows/ConditionalEdges/03_MultiSelection",
-            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             ExpectedOutputDescription =
             [
                 "The output should show an email being classified and potentially routed to multiple handlers.",
@@ -371,8 +371,8 @@ internal static class WorkflowSamples
         {
             Name = "Workflow_Observability_WorkflowAsAnAgent",
             ProjectPath = "samples/03-workflows/Observability/WorkflowAsAnAgent",
-            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             SkipReason = "Interactive console with ReadLine loop; requires OTLP endpoint.",
         },
 
@@ -384,7 +384,7 @@ internal static class WorkflowSamples
         {
             Name = "Workflow_Declarative_ConfirmInput",
             ProjectPath = "samples/03-workflows/Declarative/ConfirmInput",
-            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
             Inputs = ["hello", "hello"],
             InputDelayMs = 8000,
             ExpectedOutputDescription = ["The output should show a confirmation prompt and a user response."],
@@ -394,10 +394,10 @@ internal static class WorkflowSamples
         {
             Name = "Workflow_Declarative_CustomerSupport",
             ProjectPath = "samples/03-workflows/Declarative/CustomerSupport",
-            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
-            Inputs = ["My laptop won't start"],
-            InputDelayMs = 3000,
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
+            Inputs = ["My laptop won't start", "The laptop is now working, thank you!"],
+            InputDelayMs = 5000,
             ExpectedOutputDescription = ["The output should show a customer support workflow processing a laptop issue, with agent responses providing troubleshooting or support."],
         },
 
@@ -405,26 +405,16 @@ internal static class WorkflowSamples
         {
             Name = "Workflow_Declarative_DeepResearch",
             ProjectPath = "samples/03-workflows/Declarative/DeepResearch",
-            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             SkipReason = "Requires external weather API (wttr.in).",
         },
 
-        new SampleDefinition
-        {
-            Name = "Workflow_Declarative_ExecuteCode",
-            ProjectPath = "samples/03-workflows/Declarative/ExecuteCode",
-            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
-            Inputs = ["What is 12 * 34?"],
-            InputDelayMs = 5000,
-            ExpectedOutputDescription = ["The output should show a declarative workflow executing generated code, processing a math question and producing a result."],
-        },
-
         new SampleDefinition
         {
             Name = "Workflow_Declarative_ExecuteWorkflow",
             ProjectPath = "samples/03-workflows/Declarative/ExecuteWorkflow",
-            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
             SkipReason = "Requires a workflow file path as a CLI argument.",
         },
 
@@ -432,27 +422,18 @@ internal static class WorkflowSamples
         {
             Name = "Workflow_Declarative_FunctionTools",
             ProjectPath = "samples/03-workflows/Declarative/FunctionTools",
-            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             Inputs = ["What are today's specials?", "EXIT"],
             InputDelayMs = 8000,
             ExpectedOutputDescription = ["The output should show a workflow calling function tools (e.g. a menu plugin) to answer a question about restaurant specials."],
         },
 
-        new SampleDefinition
-        {
-            Name = "Workflow_Declarative_GenerateCode",
-            ProjectPath = "samples/03-workflows/Declarative/GenerateCode",
-            IsDeterministic = true,
-            MustContain = ["WORKFLOW: Parsing", "WORKFLOW: Defined"],
-            ExpectedOutputDescription = ["The output should show a YAML workflow being parsed and C# code being generated from it."],
-        },
-
         new SampleDefinition
         {
             Name = "Workflow_Declarative_HostedWorkflow",
             ProjectPath = "samples/03-workflows/Declarative/HostedWorkflow",
-            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
             SkipReason = "Hosts a persistent workflow server that does not exit.",
         },
 
@@ -460,9 +441,9 @@ internal static class WorkflowSamples
         {
             Name = "Workflow_Declarative_InputArguments",
             ProjectPath = "samples/03-workflows/Declarative/InputArguments",
-            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
-            Inputs = ["I'd like to visit Seattle", "EXIT"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
+            Inputs = ["I'd like to visit Seattle", "Seattle, WA", "EXIT"],
             InputDelayMs = 8000,
             ExpectedOutputDescription = ["The output should show a workflow capturing location input and providing travel-related information about Seattle."],
         },
@@ -471,19 +452,30 @@ internal static class WorkflowSamples
         {
             Name = "Workflow_Declarative_InvokeFunctionTool",
             ProjectPath = "samples/03-workflows/Declarative/InvokeFunctionTool",
-            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             Inputs = ["What's the soup of the day?", "EXIT"],
             InputDelayMs = 8000,
             ExpectedOutputDescription = ["The output should show a workflow invoking a function tool (e.g. a menu plugin) to answer a question about the soup of the day."],
         },
 
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_InvokeFoundryToolboxMcp",
+            ProjectPath = "samples/03-workflows/Declarative/InvokeFoundryToolboxMcp",
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL", "FOUNDRY_TOOLBOX_NAME", "FOUNDRY_AGENT_TOOLSET_API_VERSION"],
+            Inputs = ["How do I use Azure OpenAI with my data?"],
+            InputDelayMs = 3000,
+            ExpectedOutputDescription = ["The output should show a workflow using Foundry Toolbox MCP tools to search Microsoft Learn documentation and web search to provide a summary of results."],
+        },
+
         new SampleDefinition
         {
             Name = "Workflow_Declarative_InvokeMcpTool",
             ProjectPath = "samples/03-workflows/Declarative/InvokeMcpTool",
-            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             Inputs = ["Search for .NET tutorials on Microsoft Learn"],
             InputDelayMs = 3000,
             ExpectedOutputDescription = ["The output should show a workflow using MCP tools to search Microsoft Learn documentation and provide a summary of results."],
@@ -493,8 +485,8 @@ internal static class WorkflowSamples
         {
             Name = "Workflow_Declarative_Marketing",
             ProjectPath = "samples/03-workflows/Declarative/Marketing",
-            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             Inputs = ["A smart water bottle that tracks hydration"],
             InputDelayMs = 3000,
             ExpectedOutputDescription = ["The output should show a marketing workflow generating content about a smart water bottle product."],
@@ -504,8 +496,8 @@ internal static class WorkflowSamples
         {
             Name = "Workflow_Declarative_StudentTeacher",
             ProjectPath = "samples/03-workflows/Declarative/StudentTeacher",
-            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             Inputs = ["What is 18 + 27?"],
             InputDelayMs = 3000,
             ExpectedOutputDescription = ["The output should show a student-teacher workflow where a student asks a math question and a teacher provides the answer."],
@@ -515,8 +507,8 @@ internal static class WorkflowSamples
         {
             Name = "Workflow_Declarative_ToolApproval",
             ProjectPath = "samples/03-workflows/Declarative/ToolApproval",
-            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             Inputs = ["Search for .NET tutorials", "EXIT"],
             InputDelayMs = 8000,
             ExpectedOutputDescription = ["The output should show a workflow using an MCP tool with approval to search Microsoft Learn, followed by an exit from the input loop."],

dotnet/eng/verify-samples/verify-samples.csproj

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

dotnet/global.json

@@ -1,6 +1,6 @@
 {
     "sdk": {
-        "version": "10.0.200",
+        "version": "10.0.301",
         "rollForward": "minor",
         "allowPrerelease": false
     },

dotnet/nuget/nuget-package.props

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

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

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

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

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

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

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

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

@@ -1,31 +1,27 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-// This sample demonstrates how to use a ChatClientAgent with function tools.
-// It shows both non-streaming and streaming agent interactions using menu-related tools.
+// This sample demonstrates how to use an AIProjectClient agent with function tools.
+// It shows both non-streaming and streaming agent interactions using weather tools.
 
 using System.ComponentModel;
-using Azure.AI.OpenAI;
+using Azure.AI.Projects;
 using Azure.Identity;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
-using OpenAI.Chat;
 
-var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var model = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
 
 [Description("Get the weather for a given location.")]
 static string GetWeather([Description("The location to get the weather for.")] string location)
     => $"The weather in {location} is cloudy with a high of 15°C.";
 
-// Create the chat client and agent, and provide the function tool to the agent.
+// Create the agent and provide the function tool to the agent.
 // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
 // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
 // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-AIAgent agent = new AzureOpenAIClient(
-    new Uri(endpoint),
-    new DefaultAzureCredential())
-    .GetChatClient(deploymentName)
-    .AsAIAgent(instructions: "You are a helpful assistant", tools: [AIFunctionFactory.Create(GetWeather)]);
+AIAgent agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
+    .AsAIAgent(model: model, instructions: "You are a helpful assistant", tools: [AIFunctionFactory.Create(GetWeather)]);
 
 // Non-streaming agent interaction with function tools.
 Console.WriteLine(await agent.RunAsync("What is the weather like in Amsterdam?"));

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

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

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

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

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

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

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

@@ -8,35 +8,48 @@
 
 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());
 
-// 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
-// user info object, so each session will have its own memory.
+// Create a separate IChatClient for the memory component to use for structured extraction.
+// The memory component calls the model with a ResponseFormat (JSON schema) to extract user info.
+// Using a dedicated client here avoids mixing side-channel extraction calls with the agent's
+// conversation history, and avoids the chicken-and-egg problem of needing an IChatClient
+// before the main agent is constructed.
+IChatClient extractionClient =
+    new AIProjectClient(
+        new Uri(endpoint),
+        new DefaultAzureCredential())
+    .GetProjectOpenAIClient()
+    .GetResponsesClient()
+    .AsIChatClient(model);
+
+// Create the agent with instructions and the custom memory context provider.
+// The memory component is attached to all sessions created by the agent. Here each new memory
+// component will have its own user info object, so each session will have its own memory.
 // In real world applications/services, where the user info would be persisted in a database,
 // and preferably shared between multiple sessions used by the same user, ensure that the
 // factory reads the user id from the current context and scopes the memory component
 // and its storage to that user id.
-AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions()
+AIAgent agent = projectClient.AsAIAgent(new ChatClientAgentOptions
 {
-    ChatOptions = new() { Instructions = "You are a friendly assistant. Always address the user by their name." },
-    AIContextProviders = [new UserInfoMemory(chatClient.AsIChatClient())]
+    ChatOptions = new ChatOptions
+    {
+        ModelId = model,
+        Instructions = "You are a friendly assistant. Always address the user by their name.",
+    },
+    AIContextProviders = [new UserInfoMemory(extractionClient)]
 });
 
 // Create a new session for the conversation.
@@ -115,10 +128,17 @@ namespace SampleApp
             // Try and extract the user name and age from the message if we don't have it already and it's a user message.
             if ((userInfo.UserName is null || userInfo.UserAge is null) && context.RequestMessages.Any(x => x.Role == ChatRole.User))
             {
+                // The Foundry Responses API requires the model name in the request body.
+                // Retrieve it from the client's metadata so callers don't need to pass it separately.
+                var modelId = this._chatClient.GetService<ChatClientMetadata>()?.DefaultModelId
+                    ?? throw new InvalidOperationException(
+                        "Could not retrieve DefaultModelId from the extraction IChatClient. " +
+                        "Ensure the client was created with a model ID (e.g., via projectClient.AsAIAgent(...)).");
                 var result = await this._chatClient.GetResponseAsync<UserInfo>(
                     context.RequestMessages,
                     new ChatOptions()
                     {
+                        ModelId = modelId,
                         Instructions = "Extract the user's name and age from the message if present. If not present return nulls."
                     },
                     cancellationToken: cancellationToken);

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/AGUI/README.md

@@ -35,7 +35,7 @@ A basic AG-UI server and client that demonstrate the foundational concepts.
 A basic AG-UI server that hosts an AI agent accessible via HTTP. Demonstrates:
 
 - Creating an ASP.NET Core web application
-- Setting up an AG-UI server endpoint with `MapAGUI`
+- Setting up an AG-UI server endpoint with `MapAGUIServer`
 - Creating an AI agent from an Azure OpenAI chat client
 - Streaming responses via Server-Sent Events (SSE)
 
@@ -204,7 +204,7 @@ dotnet run
 ### Server-Side
 
 1. Client sends HTTP POST request with messages
-2. ASP.NET Core endpoint receives the request via `MapAGUI`
+2. ASP.NET Core endpoint receives the request via `MapAGUIServer`
 3. Agent processes messages using Agent Framework
 4. Responses are streamed back as Server-Sent Events (SSE)
 
@@ -214,16 +214,22 @@ dotnet run
 2. Server responds with SSE stream
 3. Client parses events into `AgentResponseUpdate` objects
 4. Updates are displayed based on content type
-5. `ConversationId` maintains conversation context
+5. The client sends the full message history each turn (the stateless AG-UI client does not rely on a server-assigned `ConversationId`)
 
 ### Protocol Features
 
 - **HTTP POST** for requests
 - **Server-Sent Events (SSE)** for streaming responses
 - **JSON** for event serialization
-- **Thread IDs** (as `ConversationId`) for conversation context
+- **Thread IDs** (read from the `RUN_STARTED` event's raw representation) for conversation context. `AGUIChatClient` is stateless and intentionally does not surface a `ConversationId`.
 - **Run IDs** (as `ResponseId`) for tracking individual executions
 
+## Security considerations
+
+`ConversationId` keeps request/response continuity. It is not proof that the caller owns that conversation. In multi-user deployments, authenticate each AG-UI request and authorize conversation access using your application's real boundary, such as the authenticated user, tenant, or workspace.
+
+If your ASP.NET Core host shares session storage across users, pair `MapAGUI` with an isolation strategy such as `UseClaimsBasedSessionIsolation(...)` so the storage key includes a principal-specific dimension instead of relying on the conversation identifier alone.
+
 ## Troubleshooting
 
 ### Connection Refused

dotnet/samples/02-agents/AGUI/Step01_GettingStarted/Client/Client.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
@@ -9,7 +9,7 @@
 
   <ItemGroup>
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
-    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.AGUI\Microsoft.Agents.AI.AGUI.csproj" />
+    <PackageReference Include="AGUI.Client" />
   </ItemGroup>
 
 </Project>

dotnet/samples/02-agents/AGUI/Step01_GettingStarted/Client/Program.cs

@@ -1,7 +1,8 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using AGUI.Abstractions;
+using AGUI.Client;
 using Microsoft.Agents.AI;
-using Microsoft.Agents.AI.AGUI;
 using Microsoft.Extensions.AI;
 
 string serverUrl = Environment.GetEnvironmentVariable("AGUI_SERVER_URL") ?? "http://localhost:8888";
@@ -14,7 +15,7 @@ using HttpClient httpClient = new()
     Timeout = TimeSpan.FromSeconds(60)
 };
 
-AGUIChatClient chatClient = new(httpClient, serverUrl);
+AGUIChatClient chatClient = new(new(httpClient, serverUrl));
 
 AIAgent agent = chatClient.AsAIAgent(
     name: "agui-client",
@@ -49,7 +50,7 @@ try
 
         // Stream the response
         bool isFirstUpdate = true;
-        string? sessionId = null;
+        string? threadId = null;
 
         await foreach (AgentResponseUpdate update in agent.RunStreamingAsync(messages, session))
         {
@@ -58,9 +59,11 @@ try
             // First update indicates run started
             if (isFirstUpdate)
             {
-                sessionId = chatUpdate.ConversationId;
+                // AGUIChatClient is stateless and never surfaces a ConversationId; the thread
+                // id is carried on the AG-UI RUN_STARTED event's raw representation.
+                threadId = (chatUpdate.RawRepresentation as RunStartedEvent)?.ThreadId;
                 Console.ForegroundColor = ConsoleColor.Yellow;
-                Console.WriteLine($"\n[Run Started - Session: {chatUpdate.ConversationId}, Run: {chatUpdate.ResponseId}]");
+                Console.WriteLine($"\n[Run Started - Thread: {threadId}, Run: {chatUpdate.ResponseId}]");
                 Console.ResetColor();
                 isFirstUpdate = false;
             }
@@ -84,7 +87,7 @@ try
         }
 
         Console.ForegroundColor = ConsoleColor.Green;
-        Console.WriteLine($"\n[Run Finished - Session: {sessionId}]");
+        Console.WriteLine($"\n[Run Finished - Thread: {threadId}]");
         Console.ResetColor();
     }
 }

dotnet/samples/02-agents/AGUI/Step01_GettingStarted/Server/Program.cs

@@ -8,7 +8,12 @@ using OpenAI.Chat;
 
 WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
 builder.Services.AddHttpClient().AddLogging();
-builder.Services.AddAGUI();
+builder.Services.AddAGUIServer();
+
+// WARNING: When adding session persistence (e.g., WithInMemorySessionStore), or running in production,
+// make sure to also register a SessionIsolationKeyProvider to scope sessions by principal in multi-user
+// deployments, e.g.:
+// builder.Services.UseClaimsBasedSessionIsolation(new() { ClaimType = ClaimTypes.NameIdentifier });
 
 WebApplication app = builder.Build();
 
@@ -31,6 +36,6 @@ AIAgent agent = chatClient.AsAIAgent(
     instructions: "You are a helpful assistant.");
 
 // Map the AG-UI agent endpoint
-app.MapAGUI("/", agent);
+app.MapAGUIServer("/", agent);
 
 await app.RunAsync();

dotnet/samples/02-agents/AGUI/Step01_GettingStarted/Server/Server.csproj

@@ -14,6 +14,7 @@
 
   <ItemGroup>
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Hosting.AGUI.AspNetCore\Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Hosting.AspNetCore\Microsoft.Agents.AI.Hosting.AspNetCore.csproj" />
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
   </ItemGroup>
 

dotnet/samples/02-agents/AGUI/Step02_BackendTools/Client/Client.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
@@ -9,7 +9,7 @@
 
   <ItemGroup>
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
-    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.AGUI\Microsoft.Agents.AI.AGUI.csproj" />
+    <PackageReference Include="AGUI.Client" />
   </ItemGroup>
 
 </Project>

dotnet/samples/02-agents/AGUI/Step02_BackendTools/Client/Program.cs

@@ -1,7 +1,8 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using AGUI.Abstractions;
+using AGUI.Client;
 using Microsoft.Agents.AI;
-using Microsoft.Agents.AI.AGUI;
 using Microsoft.Extensions.AI;
 
 string serverUrl = Environment.GetEnvironmentVariable("AGUI_SERVER_URL") ?? "http://localhost:8888";
@@ -14,7 +15,7 @@ using HttpClient httpClient = new()
     Timeout = TimeSpan.FromSeconds(60)
 };
 
-AGUIChatClient chatClient = new(httpClient, serverUrl);
+AGUIChatClient chatClient = new(new(httpClient, serverUrl));
 
 AIAgent agent = chatClient.AsAIAgent(
     name: "agui-client",
@@ -49,7 +50,7 @@ try
 
         // Stream the response
         bool isFirstUpdate = true;
-        string? sessionId = null;
+        string? threadId = null;
 
         await foreach (AgentResponseUpdate update in agent.RunStreamingAsync(messages, session))
         {
@@ -58,9 +59,11 @@ try
             // First update indicates run started
             if (isFirstUpdate)
             {
-                sessionId = chatUpdate.ConversationId;
+                // AGUIChatClient is stateless and never surfaces a ConversationId; the thread
+                // id is carried on the AG-UI RUN_STARTED event's raw representation.
+                threadId = (chatUpdate.RawRepresentation as RunStartedEvent)?.ThreadId;
                 Console.ForegroundColor = ConsoleColor.Yellow;
-                Console.WriteLine($"\n[Run Started - Session: {chatUpdate.ConversationId}, Run: {chatUpdate.ResponseId}]");
+                Console.WriteLine($"\n[Run Started - Thread: {threadId}, Run: {chatUpdate.ResponseId}]");
                 Console.ResetColor();
                 isFirstUpdate = false;
             }
@@ -116,7 +119,7 @@ try
         }
 
         Console.ForegroundColor = ConsoleColor.Green;
-        Console.WriteLine($"\n[Run Finished - Session: {sessionId}]");
+        Console.WriteLine($"\n[Run Finished - Thread: {threadId}]");
         Console.ResetColor();
     }
 }