Fix CI failures.

* declarative workflow approval flow fix

* Update mcp handler cache construction

* fix method argument.

* Update dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ObjectModel/InvokeFunctionToolExecutor.cs

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Fix identation

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@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"

.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/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/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/dotnet-build-and-test.yml

@@ -121,6 +121,9 @@ jobs:
               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:
@@ -191,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)) }}
@@ -365,6 +371,9 @@ jobs:
             dotnet
             python
 
+      - name: Free runner disk space
+        uses: ./.github/actions/free-runner-disk-space
+
       - name: Setup dotnet
         uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7 # v5.2.0
         with:
@@ -452,6 +461,9 @@ jobs:
             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:

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

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

@@ -23,6 +23,14 @@ jobs:
         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@963b6264d7de32c904942a70b488d3407453049e # v1

.github/workflows/merge-gatekeeper.yml

@@ -27,7 +27,7 @@ jobs:
           # "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_NAMES: "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);

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

@@ -474,6 +474,45 @@ jobs:
           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,6 +529,7 @@ jobs:
         python-tests-foundry,
         python-tests-foundry-hosting,
         python-tests-cosmos,
+        python-tests-github-copilot,
       ]
     runs-on: ubuntu-latest
     defaults:
@@ -553,7 +593,8 @@ 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

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

@@ -40,6 +40,7 @@ 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@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       - uses: dorny/paths-filter@d1c1ffe0248fe513906c8e24db8ea791d46f8590 # v3
@@ -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'
@@ -658,6 +661,58 @@ jobs:
           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,6 +729,7 @@ jobs:
         python-tests-foundry,
         python-tests-foundry-hosting,
         python-tests-cosmos,
+        python-tests-github-copilot,
       ]
     runs-on: ubuntu-latest
     defaults:
@@ -735,6 +791,7 @@ jobs:
         python-tests-foundry,
         python-tests-foundry-hosting,
         python-tests-cosmos,
+        python-tests-github-copilot,
       ]
     steps:
       - name: Fail workflow if tests failed

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

@@ -8,6 +8,7 @@ on:
 
 permissions:
   contents: read
+  actions: read
   pull-requests: write
 
 jobs:
@@ -23,7 +24,7 @@ jobs:
       - name: Download coverage report
         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
@@ -38,9 +39,9 @@ jobs:
             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"
+          PR_NUMBER=$(cat pr_number)
+          if ! [[ "$PR_NUMBER" =~ ^[0-9]+$ ]]; then
+            echo "::error::PR number file contains invalid content"
             exit 1
           fi
           echo "PR_NUMBER=$PR_NUMBER" >> "$GITHUB_ENV"
@@ -48,7 +49,7 @@ jobs:
         id: coverageComment
         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"

.gitignore

@@ -206,6 +206,7 @@ temp*/
 .temp/
 
 # AI
+**/.checkpoints/
 .claude/
 .omc/
 .omx/
@@ -248,3 +249,4 @@ dotnet/filtered-*.slnx
 .omx/
 
 **/issues/
+.test_*

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.

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)
 

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

@@ -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."],
 },
 ```
 

dotnet/Directory.Packages.props

@@ -22,14 +22,14 @@
     <PackageVersion Include="Aspire.Microsoft.Azure.Cosmos" Version="$(AspireAppHostSdkVersion)" />
     <PackageVersion Include="CommunityToolkit.Aspire.OllamaSharp" Version="13.0.0" />
     <!-- 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.AgentServer.Core" Version="1.0.0-beta.25" />
+    <PackageVersion Include="Azure.AI.AgentServer.Invocations" Version="1.0.0-beta.4" />
+    <PackageVersion Include="Azure.AI.AgentServer.Responses" Version="1.0.0-beta.5" />
     <PackageVersion Include="Azure.Search.Documents" Version="12.0.0" />
     <PackageVersion Include="Azure.AI.Projects" Version="2.1.0-beta.2" />
     <PackageVersion Include="Azure.AI.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.55.0" />
+    <PackageVersion Include="Azure.Core" Version="1.56.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" />
@@ -41,19 +41,19 @@
     <!-- 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.8" />
     <PackageVersion Include="Microsoft.Bcl.HashCode" Version="6.0.0" />
     <PackageVersion Include="Microsoft.Bcl.Memory" Version="10.0.5" />
-    <PackageVersion Include="System.ClientModel" Version="1.11.0" />
+    <PackageVersion Include="System.ClientModel" Version="1.12.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.8" />
     <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.Text.Json" Version="10.0.8" />
+    <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 -->
@@ -72,12 +72,12 @@
     <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
     <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" />
@@ -86,12 +86,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.8" />
     <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.8" />
     <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" />
@@ -99,7 +99,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.0" />
     <PackageVersion Include="Microsoft.Agents.CopilotStudio.Client" Version="1.3.171-beta" />
     <!-- M365 Agents SDK -->
     <PackageVersion Include="AdaptiveCards" Version="3.1.0" />
@@ -109,7 +109,7 @@
     <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" />

dotnet/agent-framework-dotnet.slnx

@@ -117,17 +117,18 @@
     <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" />
   </Folder>
   <Folder Name="/Samples/02-agents/Harness/">
     <File Path="samples/02-agents/Harness/README.md" />
+    <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_WithBackgroundAgents/Harness_Step02_Research_WithBackgroundAgents.csproj" />
     <Project Path="samples/02-agents/Harness/Harness_Step03_DataProcessing/Harness_Step03_DataProcessing.csproj" />
     <Project Path="samples/02-agents/Harness/Harness_Step04_CodeExecution/Harness_Step04_CodeExecution.csproj" />
-    <Project Path="samples/02-agents/Harness/ConsoleReactiveFramework/ConsoleReactiveFramework.csproj" />
-    <Project Path="samples/02-agents/Harness/ConsoleReactiveComponents/ConsoleReactiveComponents.csproj" />
   </Folder>
   <Folder Name="/Samples/02-agents/AGUI/Step05_StateManagement/">
     <Project Path="samples/02-agents/AGUI/Step05_StateManagement/Client/Client.csproj" />
@@ -173,6 +174,7 @@
     <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_FoundryToolboxMcp/Agent_Step25_FoundryToolboxMcp.csproj" />
+    <Project Path="samples/02-agents/AgentsWithFoundry/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" />
@@ -212,6 +214,7 @@
   </Folder>
   <Folder Name="/Samples/02-agents/ModelContextProtocol/">
     <File Path="samples/02-agents/ModelContextProtocol/README.md" />
+    <Project Path="samples/02-agents/ModelContextProtocol/Agent_MCP_LongRunningTask_Client/Agent_MCP_LongRunningTask_Client.csproj" />
     <Project Path="samples/02-agents/ModelContextProtocol/Agent_MCP_Server/Agent_MCP_Server.csproj" />
     <Project Path="samples/02-agents/ModelContextProtocol/Agent_MCP_Server_Auth/Agent_MCP_Server_Auth.csproj" />
     <Project Path="samples/02-agents/ModelContextProtocol/FoundryAgent_Hosted_MCP/FoundryAgent_Hosted_MCP.csproj" />
@@ -240,11 +243,10 @@
     <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/InvokeFunctionTool/InvokeFunctionTool.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" />
     <Project Path="samples/03-workflows/Declarative/Marketing/Marketing.csproj" />
@@ -281,6 +283,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" />
@@ -341,6 +344,12 @@
   <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>
@@ -357,6 +366,9 @@
   <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Handoff/">
     <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Handoff/HostedWorkflowHandoff.csproj" />
   </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-AgentSkills/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-AgentSkills/HostedAgentSkills.csproj" />
+  </Folder>
   <Folder Name="/Samples/04-hosting/DurableAgents/" />
   <Folder Name="/Samples/04-hosting/DurableAgents/AzureFunctions/">
     <File Path="samples/04-hosting/DurableAgents/AzureFunctions/.editorconfig" />
@@ -592,15 +604,17 @@
     <Project Path="src/Microsoft.Agents.AI.DurableTask/Microsoft.Agents.AI.DurableTask.csproj" />
     <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.Harness/Microsoft.Agents.AI.Harness.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.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.AspNetCore/Microsoft.Agents.AI.Hosting.AspNetCore.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting/Microsoft.Agents.AI.Hosting.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hyperlight/Microsoft.Agents.AI.Hyperlight.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.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" />
@@ -618,8 +632,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" />
@@ -644,8 +658,8 @@
     <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" />
@@ -654,6 +668,7 @@
     <Project Path="tests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.UnitTests/Microsoft.Agents.AI.Hosting.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hyperlight.UnitTests/Microsoft.Agents.AI.Hyperlight.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Mcp.UnitTests/Microsoft.Agents.AI.Mcp.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Mem0.UnitTests/Microsoft.Agents.AI.Mem0.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.OpenAI.UnitTests/Microsoft.Agents.AI.OpenAI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Purview.UnitTests/Microsoft.Agents.AI.Purview.UnitTests.csproj" />

dotnet/agent-framework-release.slnf

@@ -20,13 +20,17 @@
       "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",

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

@@ -363,6 +363,25 @@ internal static class AgentsSamples
             ],
         },
 
+        new SampleDefinition
+        {
+            Name = "Agent_Step06_McpBasedSkills",
+            ProjectPath = "samples/02-agents/AgentSkills/Agent_Step06_McpBasedSkills",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            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
@@ -1151,6 +1170,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/WorkflowSamples.cs

@@ -439,15 +439,6 @@ internal static class WorkflowSamples
             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",

dotnet/nuget/nuget-package.props

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

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

@@ -10,6 +10,11 @@ WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
 builder.Services.AddHttpClient().AddLogging();
 builder.Services.AddAGUI();
 
+// 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();
 
 string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"]

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/Server/Program.cs

@@ -16,6 +16,11 @@ builder.Services.ConfigureHttpJsonOptions(options =>
     options.SerializerOptions.TypeInfoResolverChain.Add(SampleJsonSerializerContext.Default));
 builder.Services.AddAGUI();
 
+// 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();
 
 string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"]

dotnet/samples/02-agents/AGUI/Step02_BackendTools/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/Step03_FrontendTools/Server/Program.cs

@@ -10,6 +10,11 @@ WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
 builder.Services.AddHttpClient().AddLogging();
 builder.Services.AddAGUI();
 
+// 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();
 
 string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"]

dotnet/samples/02-agents/AGUI/Step03_FrontendTools/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/Step04_HumanInLoop/Server/Program.cs

@@ -27,6 +27,11 @@ builder.Services.ConfigureHttpJsonOptions(options =>
     options.SerializerOptions.TypeInfoResolverChain.Add(ApprovalJsonContext.Default));
 builder.Services.AddAGUI();
 
+// 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();
 
 app.UseHttpLogging();

dotnet/samples/02-agents/AGUI/Step04_HumanInLoop/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/Step05_StateManagement/Server/Program.cs

@@ -17,6 +17,11 @@ builder.Services.AddAGUI();
 // Configure to listen on port 8888
 builder.WebHost.UseUrls("http://localhost:8888");
 
+// 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();
 
 string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"]

dotnet/samples/02-agents/AGUI/Step05_StateManagement/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/AgentProviders/Agent_With_GitHubCopilot/Agent_With_GitHubCopilot.csproj

@@ -6,6 +6,7 @@
 
     <Nullable>enable</Nullable>
     <ImplicitUsings>enable</ImplicitUsings>
+    <NoWarn>$(NoWarn);GHCP001</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

dotnet/samples/02-agents/AgentProviders/Agent_With_GitHubCopilot/Program.cs

@@ -2,21 +2,22 @@
 
 // This sample shows how to create a GitHub Copilot agent with shell command permissions.
 
-using GitHub.Copilot.SDK;
+using GitHub.Copilot;
+using GitHub.Copilot.Rpc;
 using Microsoft.Agents.AI;
 
 // Permission handler that prompts the user for approval
-static Task<PermissionRequestResult> PromptPermission(PermissionRequest request, PermissionInvocation invocation)
+static Task<PermissionDecision> PromptPermission(PermissionRequest request, PermissionInvocation invocation)
 {
     Console.WriteLine($"\n[Permission Request: {request.Kind}]");
     Console.Write("Approve? (y/n): ");
 
     string? input = Console.ReadLine()?.Trim().ToUpperInvariant();
-    PermissionRequestResultKind kind = input is "Y" or "YES"
-                                     ? PermissionRequestResultKind.Approved
-                                     : PermissionRequestResultKind.Rejected;
+    PermissionDecision decision = input is "Y" or "YES"
+                                     ? PermissionDecision.ApproveOnce()
+                                     : PermissionDecision.Reject();
 
-    return Task.FromResult(new PermissionRequestResult { Kind = kind });
+    return Task.FromResult(decision);
 }
 
 // Create and start a Copilot client

dotnet/samples/02-agents/AgentProviders/Agent_With_GitHubCopilot/README.md

@@ -36,7 +36,7 @@ dotnet run
 You can customize the agent by providing additional configuration:
 
 ```csharp
-using GitHub.Copilot.SDK;
+using GitHub.Copilot;
 using Microsoft.Agents.AI;
 
 // Create and start a Copilot client

dotnet/samples/02-agents/AgentSkills/Agent_Step01_FileBasedSkills/Program.cs

@@ -24,6 +24,7 @@ string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYM
 var skillsProvider = new AgentSkillsProvider(
     Path.Combine(AppContext.BaseDirectory, "skills"),
     SubprocessScriptRunner.RunAsync);
+
 // --- Agent Setup ---
 AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
     .GetResponsesClient()

dotnet/samples/02-agents/AgentSkills/Agent_Step03_ClassBasedSkills/Program.cs

@@ -51,7 +51,7 @@ Console.WriteLine($"Agent: {response.Text}");
 /// Properties annotated with <see cref="AgentSkillResourceAttribute"/> are automatically
 /// discovered as skill resources, and methods annotated with <see cref="AgentSkillScriptAttribute"/>
 /// are automatically discovered as skill scripts. Alternatively,
-/// <see cref="AgentSkill.Resources"/> and <see cref="AgentSkill.Scripts"/> can be overridden.
+/// <see cref="AgentClassSkill{TSelf}.Resources"/> and <see cref="AgentClassSkill{TSelf}.Scripts"/> can be overridden.
 /// </remarks>
 internal sealed class UnitConverterSkill : AgentClassSkill<UnitConverterSkill>
 {

dotnet/samples/02-agents/AgentSkills/Agent_Step06_McpBasedSkills/Agent_Step06_McpBasedSkills.csproj

@@ -0,0 +1,24 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <NoWarn>$(NoWarn);MAAI001;MCPEXP001</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.Hosting" />
+    <PackageReference Include="ModelContextProtocol" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Mcp\Microsoft.Agents.AI.Mcp.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/02-agents/AgentSkills/Agent_Step06_McpBasedSkills/Program.cs

@@ -0,0 +1,142 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to discover Agent Skills served over MCP.
+//
+// When launched with "--server", this executable runs a small MCP stdio server
+// that exposes a unit-converter skill via the SEP-2640 convention:
+//   - skill://index.json      — discovery document listing all skills
+//   - skill://unit-converter/SKILL.md — the skill instructions
+//
+// In default (client) mode the sample launches itself as a child process,
+// connects via StdioClientTransport, and uses AgentSkillsProviderBuilder
+// to discover and inject the skill into a ChatClientAgent.
+
+using System.ComponentModel;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using ModelContextProtocol.Client;
+using ModelContextProtocol.Server;
+using OpenAI.Responses;
+
+if (args.Length > 0 && args[0] == "--server")
+{
+    await RunMcpServerAsync();
+    return;
+}
+
+// --- Configuration ---
+string openAiEndpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+
+// --- MCP client + skill discovery ---
+// Launch this same assembly as a stdio MCP server in a child process.
+var thisAssemblyPath = typeof(Program).Assembly.Location;
+Console.WriteLine("Discovering MCP-based skills");
+
+await using McpClient client = await McpClient.CreateAsync(
+    new StdioClientTransport(new()
+    {
+        Name = "skills-server",
+        Command = "dotnet",
+        Arguments = [thisAssemblyPath, "--server"],
+    }));
+
+var skillsProvider = new AgentSkillsProviderBuilder()
+    .UseMcpSkills(client)
+    .Build();
+
+// --- 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(openAiEndpoint), new DefaultAzureCredential())
+    .GetResponsesClient()
+    .AsAIAgent(new ChatClientAgentOptions
+    {
+        Name = "SkillsAgent",
+        ChatOptions = new()
+        {
+            Instructions = "You are a helpful assistant. Use available skills to answer the user.",
+        },
+        AIContextProviders = [skillsProvider],
+    },
+    model: deploymentName);
+
+// --- Run ---
+Console.WriteLine(new string('-', 60));
+
+AgentResponse response = await agent.RunAsync(
+    "How many kilometers is a marathon (26.2 miles)? And how many pounds is 75 kilograms?");
+
+Console.WriteLine($"Agent: {response.Text}");
+
+// --- Server mode (launched as a child process via --server) ---------------------------------
+static async Task RunMcpServerAsync()
+{
+    var builder = Host.CreateApplicationBuilder();
+
+    // Critical for stdio transport: any provider that writes to stdout will corrupt the
+    // JSON-RPC channel. Clear all providers; the MCP SDK routes its own diagnostics
+    // appropriately.
+    builder.Logging.ClearProviders();
+    builder.Logging.AddConsole(o => o.LogToStandardErrorThreshold = LogLevel.Trace);
+
+    builder.Services.AddMcpServer(o => o.ServerInfo = new() { Name = "SkillsServer", Version = "1.0.0" })
+    .WithStdioServerTransport()
+    .WithResources<SkillResources>();
+
+    await builder.Build().RunAsync();
+}
+
+#pragma warning disable CA1812 // Discovered by MCP SDK via [McpServerResourceType] attribute
+[McpServerResourceType]
+internal sealed class SkillResources
+#pragma warning restore CA1812
+{
+    private const string IndexJson = """
+        {
+            "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
+            "skills": [
+                {
+                    "name": "unit-converter",
+                    "type": "skill-md",
+                    "description": "Convert between common units using a multiplication factor. Use when asked to convert miles, kilometers, pounds, or kilograms.",
+                    "url": "skill://unit-converter/SKILL.md"
+                }
+            ]
+        }
+        """;
+
+    private const string SkillMd = """
+        ---
+        name: unit-converter
+        description: Convert between common units using a multiplication factor. Use when asked to convert miles, kilometers, pounds, or kilograms.
+        ---
+
+        ## Usage
+
+        When the user requests a unit conversion, use these factors:
+
+        | From        | To          | Factor   |
+        |-------------|-------------|----------|
+        | miles       | kilometers  | 1.60934  |
+        | kilometers  | miles       | 0.621371 |
+        | pounds      | kilograms   | 0.453592 |
+        | kilograms   | pounds      | 2.20462  |
+
+        Formula: result = value × factor
+        """;
+
+    [McpServerResource(UriTemplate = "skill://index.json", Name = "Skill Index", MimeType = "application/json")]
+    [Description("SEP-2640 skill discovery index")]
+    public static string GetIndex() => IndexJson;
+
+    [McpServerResource(UriTemplate = "skill://unit-converter/SKILL.md", Name = "Unit Converter Skill", MimeType = "text/markdown")]
+    [Description("Unit converter skill instructions")]
+    public static string GetSkillMd() => SkillMd;
+}

dotnet/samples/02-agents/AgentSkills/Agent_Step06_McpBasedSkills/README.md

@@ -0,0 +1,34 @@
+# MCP-Based Agent Skills Sample
+
+This sample demonstrates how to discover **Agent Skills served over MCP** with a `ChatClientAgent`.
+
+## What it demonstrates
+
+- Hosting a small MCP server (in this same executable, launched with `--server`) that
+  exposes skill resources following the SEP-2640 convention.
+- Connecting an `McpClient` to the embedded server via stdio transport.
+- Building an `AgentSkillsProvider` via `UseMcpSkills(client)`, which reads
+  `skill://index.json` (SEP-2640 canonical discovery) and constructs skills from the
+  index entries.
+- The progressive disclosure pattern across MCP: advertise → load → read resources, exactly
+  as for filesystem-backed skills.
+
+## Running the Sample
+
+### Prerequisites
+
+- .NET 10.0 SDK
+- Azure OpenAI endpoint with a deployed model
+
+### Setup
+
+```powershell
+$env:AZURE_OPENAI_ENDPOINT="https://your-endpoint.openai.azure.com/"
+$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-5.4-mini"
+```
+
+### Run
+
+```powershell
+dotnet run
+```

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

@@ -9,6 +9,7 @@ Samples demonstrating Agent Skills capabilities. Each sample shows a different w
 | [Agent_Step03_ClassBasedSkills](Agent_Step03_ClassBasedSkills/) | Define skills as C# classes using `AgentClassSkill`. |
 | [Agent_Step04_MixedSkills](Agent_Step04_MixedSkills/) | **(Advanced)** Combine file-based, code-defined, and class-based skills using `AgentSkillsProviderBuilder`. |
 | [Agent_Step05_SkillsWithDI](Agent_Step05_SkillsWithDI/) | Use Dependency Injection with both code-defined (`AgentInlineSkill`) and class-based (`AgentClassSkill`) skills. |
+| [Agent_Step06_McpBasedSkills](Agent_Step06_McpBasedSkills/) | Discover skills served over the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) via `AgentMcpSkillsSource`. Spins up an in-process MCP server that exposes skills as resources (`skill://...`) and connects an `McpClient` to it. |
 
 ## Key Concepts
 

dotnet/samples/02-agents/AgentWithRAG/AgentWithRAG_Step05_Neo4jGraphRAG/AgentWithRAG_Step05_Neo4jGraphRAG.csproj

@@ -23,7 +23,7 @@
     <PackageReference Include="Azure.AI.OpenAI" Version="2.9.0-beta.1" />
     <PackageReference Include="Azure.Identity" Version="1.19.0" />
     <PackageReference Include="Microsoft.Agents.AI.OpenAI" Version="1.0.0-rc4" />
-    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="10.4.0" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="10.6.0" />
     <PackageReference Include="Neo4j.AgentFramework.GraphRAG" Version="0.1.0-preview.2" />
     <PackageReference Include="Neo4j.Driver" Version="5.28.0" />
   </ItemGroup>

dotnet/samples/02-agents/AgentsWithFoundry/Agent_Step26_FoundryToolboxMcpSkills/Agent_Step26_FoundryToolboxMcpSkills.csproj

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

dotnet/samples/02-agents/AgentsWithFoundry/Agent_Step26_FoundryToolboxMcpSkills/Program.cs

@@ -0,0 +1,93 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// Foundry Toolbox MCP Skills.
+//
+// Uses AgentSkillsProviderBuilder to discover MCP-based skills from a Foundry
+// Toolbox endpoint and inject them as AIContextProviders so the agent can
+// discover and use them at runtime.
+
+using System.Net.Http.Headers;
+using Azure.AI.Projects;
+using Azure.Core;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using ModelContextProtocol.Client;
+
+// --- Configuration ---
+string endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+string toolboxMcpServerUrl = Environment.GetEnvironmentVariable("FOUNDRY_TOOLBOX_MCP_SERVER_URL")
+    ?? throw new InvalidOperationException("FOUNDRY_TOOLBOX_MCP_SERVER_URL is not set.");
+
+// 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.
+TokenCredential credential = new DefaultAzureCredential();
+
+using var httpClient = new HttpClient(new BearerTokenHandler(credential, "https://ai.azure.com/.default")
+{
+    InnerHandler = new HttpClientHandler(),
+});
+
+// --- Connect to the Foundry Toolbox MCP endpoint ---
+await using McpClient mcpClient = await McpClient.CreateAsync(
+    new HttpClientTransport(
+        new HttpClientTransportOptions
+        {
+            Endpoint = new Uri(toolboxMcpServerUrl),
+            Name = "foundry_toolbox",
+            TransportMode = HttpTransportMode.StreamableHttp,
+            AdditionalHeaders = new Dictionary<string, string>
+            {
+                ["Foundry-Features"] = "Toolboxes=V1Preview",
+            },
+        },
+        httpClient));
+
+// --- Discover MCP-based skills ---
+var skillsProvider = new AgentSkillsProviderBuilder()
+    .UseMcpSkills(mcpClient)
+    .Build();
+
+// --- Create the agent ---
+AIProjectClient aiProjectClient = new(new Uri(endpoint), credential);
+
+AIAgent agent = aiProjectClient.AsAIAgent(
+    options: new ChatClientAgentOptions
+    {
+        Name = "ToolboxMcpSkillsAgent",
+        ChatOptions = new()
+        {
+            ModelId = deploymentName,
+            Instructions = "You are a helpful assistant. Use available skills to answer the user.",
+        },
+        AIContextProviders = [skillsProvider],
+    });
+
+// --- Interactive prompt ---
+Console.Write("User: ");
+string? query = Console.ReadLine();
+
+if (string.IsNullOrWhiteSpace(query))
+{
+    Console.WriteLine("No input provided.");
+    return;
+}
+
+Console.WriteLine($"Assistant: {await agent.RunAsync(query)}");
+
+// ---------------------------------------------------------------------------
+// DelegatingHandler: attaches a fresh Foundry bearer token to every request
+// ---------------------------------------------------------------------------
+internal sealed class BearerTokenHandler(TokenCredential credential, string scope) : DelegatingHandler
+{
+    private readonly TokenRequestContext _tokenContext = new([scope]);
+
+    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
+    {
+        AccessToken token = await credential.GetTokenAsync(this._tokenContext, cancellationToken).ConfigureAwait(false);
+        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token.Token);
+        return await base.SendAsync(request, cancellationToken).ConfigureAwait(false);
+    }
+}

dotnet/samples/02-agents/AgentsWithFoundry/Agent_Step26_FoundryToolboxMcpSkills/README.md

@@ -0,0 +1,32 @@
+# Foundry Toolbox MCP Skills
+
+This sample uses
+`AgentSkillsProviderBuilder` to discover MCP-based skills from a Foundry Toolbox endpoint
+and inject them as `AIContextProviders` so the agent can discover and use them at runtime.
+
+## What this sample demonstrates
+
+- Connecting to a Foundry toolbox's MCP endpoint via Streamable HTTP transport
+- Injecting a fresh Azure AI bearer token (`https://ai.azure.com/.default`) on every MCP request
+- Using `AgentSkillsProviderBuilder.UseMcpSkills(client)` to discover skills from the toolbox
+- Injecting the discovered skills into `AIProjectClient.AsAIAgent(...)` via `AIContextProviders`
+
+## Prerequisites
+
+- A Microsoft Foundry project with a toolbox already configured
+- The toolbox MCP endpoint must expose `skill://index.json` with `skill-md` entries (SEP-2640). If the resource is absent, the sample runs but the skills provider will be empty.
+- Azure CLI installed and authenticated (`az login`)
+
+Set the following environment variables:
+
+```powershell
+$env:AZURE_AI_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project"
+$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-5.4-mini"
+$env:FOUNDRY_TOOLBOX_MCP_SERVER_URL="https://your-foundry-service.services.ai.azure.com/api/projects/your-project/toolboxes/your-toolbox/mcp?api-version=v1"
+```
+
+## Run the sample
+
+```powershell
+dotnet run
+```

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

@@ -74,6 +74,7 @@ Some samples require extra tool-specific environment variables. See each sample
 | [Local MCP](./Agent_Step23_LocalMCP/) | Local MCP client with HTTP transport |
 | [Code interpreter file download](./Agent_Step24_CodeInterpreterFileDownload/) | Download container files generated by code interpreter |
 | [Foundry toolbox via MCP](./Agent_Step25_FoundryToolboxMcp/) | Use a Foundry Toolbox from a non-hosted agent via its MCP endpoint |
+| [Foundry toolbox MCP skills](./Agent_Step26_FoundryToolboxMcpSkills/) | Use a Foundry Toolbox with MCP-based skills discovery (SEP-2640) via AIContextProviders |
 
 ## Running the samples
 

dotnet/samples/02-agents/Harness/ConsoleReactiveComponents/AnsiEscapes.cs

@@ -72,6 +72,95 @@ public static class AnsiEscapes
     /// </summary>
     public static string ResetAttributes => "\x1b[0m";
 
+    /// <summary>
+    /// Returns the visible (printed) length of a string after stripping ANSI escape sequences.
+    /// Escape sequences are zero-width on screen but occupy characters in the raw string.
+    /// </summary>
+    /// <remarks>
+    /// This counts UTF-16 code units (chars) rather than terminal display cells. Emoji,
+    /// combining characters, variation selectors, and East Asian wide characters may be
+    /// measured incorrectly. For the console harness this is acceptable since content is
+    /// predominantly ASCII, and emoji are padded with surrounding spaces.
+    /// </remarks>
+    public static int VisibleLength(string text)
+    {
+        if (string.IsNullOrEmpty(text))
+        {
+            return 0;
+        }
+
+        int length = 0;
+        for (int i = 0; i < text.Length; i++)
+        {
+            if (text[i] == '\x1b' && i + 1 < text.Length && text[i + 1] == '[')
+            {
+                // Skip the ESC[ and all characters up to and including the final byte (0x40–0x7E).
+                i += 2;
+                while (i < text.Length && text[i] < 0x40)
+                {
+                    i++;
+                }
+
+                // i now points to the final byte of the escape sequence; the for-loop will advance past it.
+            }
+            else if (text[i] != '\n' && text[i] != '\r')
+            {
+                length++;
+            }
+        }
+
+        return length;
+    }
+
+    /// <summary>
+    /// Counts the number of physical terminal rows a text item will occupy,
+    /// accounting for both explicit newlines and terminal line wrapping.
+    /// </summary>
+    /// <param name="text">The text to measure.</param>
+    /// <param name="terminalWidth">The terminal width in columns. If &lt;= 0, wrapping is ignored (1 row per logical line).</param>
+    /// <returns>The number of physical rows the text occupies.</returns>
+    public static int CountPhysicalLines(string text, int terminalWidth)
+    {
+        if (string.IsNullOrEmpty(text))
+        {
+            return 0;
+        }
+
+        int physicalLines = 0;
+        int lineStart = 0;
+
+        for (int i = 0; i <= text.Length; i++)
+        {
+            if (i == text.Length || text[i] == '\n')
+            {
+                if (terminalWidth <= 0)
+                {
+                    // No wrapping — each logical line is one physical row
+                    physicalLines += 1;
+                }
+                else
+                {
+                    string logicalLine = text[lineStart..i];
+                    int visibleWidth = VisibleLength(logicalLine);
+
+                    physicalLines += visibleWidth == 0
+                        ? 1
+                        : (visibleWidth - 1) / terminalWidth + 1;
+                }
+
+                lineStart = i + 1;
+            }
+        }
+
+        // If text ends with a newline, don't count the trailing empty line
+        if (text[text.Length - 1] == '\n')
+        {
+            physicalLines--;
+        }
+
+        return physicalLines;
+    }
+
     private static int ConsoleColorToAnsi(ConsoleColor color) => color switch
     {
         ConsoleColor.Black => 30,

dotnet/samples/02-agents/Harness/ConsoleReactiveComponents/ListSelection.cs

@@ -40,8 +40,8 @@ public class ListSelection : ConsoleReactiveComponent<ListSelectionProps, Consol
             foreach (string line in props.Title.Split('\n'))
             {
                 Console.Write(AnsiEscapes.MoveCursor(props.Y + row, props.X));
-                Console.Write(AnsiEscapes.EraseEntireLine);
                 Console.Write(line);
+                Console.Write(AnsiEscapes.EraseToEndOfLine);
                 row++;
             }
         }
@@ -52,7 +52,6 @@ public class ListSelection : ConsoleReactiveComponent<ListSelectionProps, Consol
         for (int i = 0; i < totalItems; i++)
         {
             Console.Write(AnsiEscapes.MoveCursor(props.Y + row, props.X));
-            Console.Write(AnsiEscapes.EraseEntireLine);
 
             bool isSelected = i == props.SelectedIndex;
             bool isCustomTextOption = props.CustomTextPlaceholder != null && i == props.Items.Count;
@@ -72,6 +71,7 @@ public class ListSelection : ConsoleReactiveComponent<ListSelectionProps, Consol
                 }
 
                 Console.Write(props.Items[i]);
+                Console.Write(AnsiEscapes.EraseToEndOfLine);
 
                 if (isSelected)
                 {
@@ -101,6 +101,7 @@ public class ListSelection : ConsoleReactiveComponent<ListSelectionProps, Consol
             }
 
             Console.Write(props.CustomText);
+            Console.Write(AnsiEscapes.EraseToEndOfLine);
 
             if (isSelected)
             {
@@ -121,6 +122,7 @@ public class ListSelection : ConsoleReactiveComponent<ListSelectionProps, Consol
 
             Console.Write(" ");
             Console.Write(props.CustomTextPlaceholder);
+            Console.Write(AnsiEscapes.EraseToEndOfLine);
             Console.Write(AnsiEscapes.ResetAttributes);
         }
     }

dotnet/samples/02-agents/Harness/ConsoleReactiveComponents/TextPanel.cs

@@ -23,16 +23,18 @@ public record TextPanelProps : ConsoleReactiveProps
 public class TextPanel : ConsoleReactiveComponent<TextPanelProps, ConsoleReactiveState>
 {
     /// <summary>
-    /// Calculates the height (in lines) needed to render all items.
+    /// Calculates the height (in lines) needed to render all items,
+    /// accounting for terminal line wrapping at the specified width.
     /// </summary>
     /// <param name="items">The items to measure.</param>
-    /// <returns>The total number of lines all items will occupy.</returns>
-    public static int CalculateHeight(IReadOnlyList<string> items)
+    /// <param name="terminalWidth">The terminal width in columns. When 0 or negative, wrapping is ignored.</param>
+    /// <returns>The total number of physical lines all items will occupy.</returns>
+    public static int CalculateHeight(IReadOnlyList<string> items, int terminalWidth = 0)
     {
         int total = 0;
         for (int i = 0; i < items.Count; i++)
         {
-            total += CountLines(items[i]);
+            total += AnsiEscapes.CountPhysicalLines(items[i], terminalWidth);
         }
 
         return total;
@@ -47,13 +49,20 @@ public class TextPanel : ConsoleReactiveComponent<TextPanelProps, ConsoleReactiv
         {
             string text = props.Items[i];
             string[] lines = text.Split('\n');
-            int lineCount = CountLines(text);
+            int itemLineCount = AnsiEscapes.CountPhysicalLines(text, props.Width);
+            int itemRow = 0;
 
-            for (int j = 0; j < lineCount; j++)
+            for (int j = 0; j < lines.Length && itemRow < itemLineCount; j++)
             {
+                int linePhysicalRows = props.Width > 0
+                    ? Math.Max(1, (AnsiEscapes.VisibleLength(lines[j]) - 1) / props.Width + 1)
+                    : 1;
+
                 Console.Write(AnsiEscapes.MoveAndEraseLine(props.Y + currentRow));
                 Console.Write(lines[j]);
-                currentRow++;
+
+                currentRow += linePhysicalRows;
+                itemRow += linePhysicalRows;
             }
         }
 
@@ -66,29 +75,4 @@ public class TextPanel : ConsoleReactiveComponent<TextPanelProps, ConsoleReactiv
             }
         }
     }
-
-    private static int CountLines(string text)
-    {
-        if (string.IsNullOrEmpty(text))
-        {
-            return 0;
-        }
-
-        int count = 1;
-        for (int i = 0; i < text.Length; i++)
-        {
-            if (text[i] == '\n')
-            {
-                count++;
-            }
-        }
-
-        // If text ends with a newline, don't count the trailing empty line
-        if (text[text.Length - 1] == '\n')
-        {
-            count--;
-        }
-
-        return count;
-    }
 }

dotnet/samples/02-agents/Harness/ConsoleReactiveComponents/TextScrollPanel.cs

@@ -17,16 +17,19 @@ public record TextScrollPanelProps : ConsoleReactiveProps
 /// <summary>
 /// State for <see cref="TextScrollPanel"/>.
 /// </summary>
-/// <param name="RenderedCount">The number of items already rendered.</param>
-public record TextScrollPanelState(int RenderedCount = 0) : ConsoleReactiveState;
+public record TextScrollPanelState : ConsoleReactiveState;
 
 /// <summary>
 /// A component that renders pre-rendered string items within a scroll area.
-/// All items are considered finalized — only new items since the last render are output.
-/// Use <see cref="Reset"/> to force a full re-render.
+/// The last rendered item is considered dynamic and will be re-rendered on each call.
+/// All prior items are considered finalized and are not re-rendered.
+/// Use <see cref="Invalidate"/> to force a full re-render.
 /// </summary>
 public class TextScrollPanel : ConsoleReactiveComponent<TextScrollPanelProps, TextScrollPanelState>
 {
+    private int _renderedCount;
+    private int _lastItemOffsetFromBottom;
+
     /// <summary>
     /// Initializes a new instance of the <see cref="TextScrollPanel"/> class.
     /// </summary>
@@ -35,12 +38,12 @@ public class TextScrollPanel : ConsoleReactiveComponent<TextScrollPanelProps, Te
         this.State = new TextScrollPanelState();
     }
 
-    /// <summary>
-    /// Resets the panel so all items will be re-rendered on the next Render call.
-    /// </summary>
-    public void Reset()
+    /// <inheritdoc />
+    public override void Invalidate()
     {
-        this.State = new TextScrollPanelState();
+        this._renderedCount = 0;
+        this._lastItemOffsetFromBottom = 0;
+        base.Invalidate();
     }
 
     /// <inheritdoc />
@@ -51,16 +54,35 @@ public class TextScrollPanel : ConsoleReactiveComponent<TextScrollPanelProps, Te
             return;
         }
 
-        // Move cursor to the bottom of the scroll area
-        Console.Write(AnsiEscapes.MoveCursor(props.Y + props.Height - 1, props.X));
+        int bottomRow = props.Y + props.Height - 1;
 
-        // Output only new items since last rendered
-        for (int i = state.RenderedCount; i < props.Items.Count; i++)
+        // Determine the first item to render. If we previously rendered items,
+        // re-render the last one (it may have changed/grown) from its stored position.
+        int startIndex = this._renderedCount > 0 ? this._renderedCount - 1 : 0;
+
+        if (this._renderedCount > 0 && this._lastItemOffsetFromBottom > 0)
+        {
+            // Reposition cursor to where the last rendered item began
+            Console.Write(AnsiEscapes.MoveCursor(bottomRow - this._lastItemOffsetFromBottom, props.X));
+        }
+        else
+        {
+            // First render — position at the bottom of the scroll area
+            Console.Write(AnsiEscapes.MoveCursor(bottomRow, props.X));
+        }
+
+        // Render from startIndex onwards
+        for (int i = startIndex; i < props.Items.Count; i++)
         {
             Console.Write(props.Items[i]);
         }
 
-        // Update state to track what we've rendered
-        this.State = new TextScrollPanelState(props.Items.Count);
+        // Calculate the offset from bottom for the start of the new last item,
+        // accounting for terminal line wrapping at the available width.
+        int lastItemLines = AnsiEscapes.CountPhysicalLines(props.Items[^1], props.Width);
+        this._lastItemOffsetFromBottom = lastItemLines > 0 ? lastItemLines - 1 : 0;
+
+        // Update rendered count
+        this._renderedCount = props.Items.Count;
     }
 }

dotnet/samples/02-agents/Harness/ConsoleReactiveFramework/ConsoleReactiveComponent.cs

@@ -13,6 +13,11 @@ public abstract class ConsoleReactiveComponent
     {
     }
 
+    /// <summary>
+    /// Gets the shared render lock across all component types to prevent ANSI escape sequence interleaving.
+    /// </summary>
+    protected static object RenderLock { get; } = new();
+
     /// <summary>
     /// Gets or sets the component's props as the base <see cref="ConsoleReactiveProps"/> type.
     /// Used by parent components to set layout (X, Y, Width, Height) on children without
@@ -40,7 +45,6 @@ public abstract class ConsoleReactiveComponent<TProps, TState> : ConsoleReactive
     where TProps : ConsoleReactiveProps
     where TState : ConsoleReactiveState
 {
-    private readonly object _renderLock = new();
     private TProps? _lastRenderedProps;
     private TState? _lastRenderedState;
 
@@ -74,7 +78,7 @@ public abstract class ConsoleReactiveComponent<TProps, TState> : ConsoleReactive
     /// </summary>
     public override void Render()
     {
-        lock (this._renderLock)
+        lock (RenderLock)
         {
             if (this.Props is null)
             {
@@ -97,7 +101,7 @@ public abstract class ConsoleReactiveComponent<TProps, TState> : ConsoleReactive
     /// <inheritdoc/>
     public override void Invalidate()
     {
-        lock (this._renderLock)
+        lock (RenderLock)
         {
             this._lastRenderedProps = default;
             this._lastRenderedState = default;

dotnet/samples/02-agents/Harness/ConsoleReactiveFramework/ConsoleReactiveMemo.cs

@@ -0,0 +1,36 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Harness.ConsoleReactiveFramework;
+
+/// <summary>
+/// Caches the result of a mapping function and only recomputes when the input changes.
+/// </summary>
+/// <typeparam name="TInput">The type of the input value.</typeparam>
+/// <typeparam name="TOutput">The type of the mapped output value.</typeparam>
+public class ConsoleReactiveMemo<TInput, TOutput>
+{
+    private TInput? _previousInput;
+    private TOutput? _cachedOutput;
+    private bool _hasValue;
+
+    /// <summary>
+    /// Returns the cached output if <paramref name="input"/> equals the previously stored input;
+    /// otherwise invokes <paramref name="mapper"/> to compute and cache a new output.
+    /// </summary>
+    /// <param name="input">The current input value.</param>
+    /// <param name="mapper">A function that maps the input to an output value.</param>
+    /// <returns>The cached or newly computed output.</returns>
+    public TOutput Map(TInput input, Func<TInput, TOutput> mapper)
+    {
+        ArgumentNullException.ThrowIfNull(mapper);
+
+        if (!this._hasValue || !EqualityComparer<TInput>.Default.Equals(input, this._previousInput))
+        {
+            this._previousInput = input;
+            this._cachedOutput = mapper(input);
+            this._hasValue = true;
+        }
+
+        return this._cachedOutput!;
+    }
+}

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

@@ -19,7 +19,6 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
     private readonly ListSelection _listSelection = new();
     private readonly TextInput _textInput = new();
     private readonly TextScrollPanel _textScrollPanel = new();
-    private readonly TextPanel _textPanel = new();
     private readonly TextPanel _queuedPanel = new();
     private readonly AgentStatus _agentStatus = new();
     private readonly AgentModeAndHelp _modeAndHelp = new();
@@ -29,6 +28,7 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
     private int _scrollRegionBottom;
     private bool _resizedSinceLastRender = true;
     private bool _deactivated;
+    private BottomPanelMode _lastRenderedBottomPanelMode;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="HarnessAppComponent"/> class.
@@ -341,18 +341,8 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
             return;
         }
 
-        // Determine the text panel height for the last scroll item
-        IReadOnlyList<string> lastItems = state.ScrollAreaContentItems.Count > 0
-            ? [state.ScrollAreaContentItems[^1]]
-            : [];
-        int textPanelHeight = TextPanel.CalculateHeight(lastItems);
-        if (textPanelHeight > 0)
-        {
-            textPanelHeight++; // Extra line for spacing between text panel and rule
-        }
-
         // Calculate queued items panel height
-        int queuedPanelHeight = TextPanel.CalculateHeight(state.QueuedItems);
+        int queuedPanelHeight = TextPanel.CalculateHeight(state.QueuedItems, state.ConsoleWidth);
 
         // Build the bottom panel child based on mode
         ConsoleReactiveComponent bottomChild;
@@ -417,6 +407,14 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
             bottomChild = this._textInput;
         }
 
+        // When the bottom panel mode changes, the new child must repaint even if its
+        // props haven't changed — the screen area was overwritten by the previous child.
+        if (state.Mode != this._lastRenderedBottomPanelMode)
+        {
+            bottomChild.Invalidate();
+            this._lastRenderedBottomPanelMode = state.Mode;
+        }
+
         var ruleProps = new TopBottomRuleProps
         {
             Width = state.ConsoleWidth,
@@ -444,7 +442,7 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
         int modeAndHelpHeight = showStatusAndHelp ? AgentModeAndHelp.CalculateHeight(modeAndHelpProps) : 0;
 
         int ruleHeight = TopBottomRule.CalculateHeight(ruleProps);
-        int nonScrollHeight = ruleHeight + textPanelHeight + agentStatusHeight + queuedPanelHeight + modeAndHelpHeight + 1; // +1 for bottom padding
+        int nonScrollHeight = ruleHeight + agentStatusHeight + queuedPanelHeight + modeAndHelpHeight + 1; // +1 for bottom padding
         int scrollBottom = Math.Max(1, state.ConsoleHeight - nonScrollHeight);
 
         // If scroll region changed or a clear is needed, reset everything
@@ -455,52 +453,36 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
             System.Console.Write(AnsiEscapes.ResetScrollRegion);
             System.Console.Write(AnsiEscapes.EraseEntireScreen);
             System.Console.Write(AnsiEscapes.EraseScrollbackBuffer);
-            this._textScrollPanel.Reset();
-            this._resizedSinceLastRender = false;
 
             // Invalidate all children so they re-render even if props haven't changed
             this._rule.Invalidate();
             this._textScrollPanel.Invalidate();
-            this._textPanel.Invalidate();
             this._queuedPanel.Invalidate();
             this._agentStatus.Invalidate();
             this._modeAndHelp.Invalidate();
             this._textInput.Invalidate();
             this._listSelection.Invalidate();
+
+            this._resizedSinceLastRender = false;
         }
 
         this._scrollRegionBottom = scrollBottom;
 
         System.Console.Write(AnsiEscapes.SetScrollRegion(scrollBottom));
 
-        // Render text scroll panel in the scroll area (all items except the last)
-        IReadOnlyList<string> scrollItems = state.ScrollAreaContentItems.Count > 1
-            ? state.ScrollAreaContentItems.Take(state.ScrollAreaContentItems.Count - 1).ToList()
-            : [];
-
+        // Render text scroll panel in the scroll area
         this._textScrollPanel.Props = new TextScrollPanelProps
         {
             X = 1,
             Y = 1,
             Width = state.ConsoleWidth,
             Height = scrollBottom,
-            Items = scrollItems,
+            Items = state.ScrollAreaContentItems,
         };
         this._textScrollPanel.Render();
 
-        // Render the text panel for the last (dynamic) item just below the scroll region
-        this._textPanel.Props = new TextPanelProps
-        {
-            X = 1,
-            Y = scrollBottom + 1,
-            Width = state.ConsoleWidth,
-            Height = textPanelHeight,
-            Items = lastItems,
-        };
-        this._textPanel.Render();
-
-        // Render queued input items between text panel and agent status
-        int queuedPanelY = scrollBottom + textPanelHeight + 1;
+        // Render queued input items between scroll area and agent status
+        int queuedPanelY = scrollBottom + 1;
         this._queuedPanel.Props = new TextPanelProps
         {
             X = 1,

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/PlanningOutputObserver.cs

@@ -88,16 +88,17 @@ public sealed class PlanningOutputObserver : ConsoleObserver
         {
             planningResponse = JsonSerializer.Deserialize<PlanningResponse>(collectedText);
         }
-        catch (JsonException ex)
+        catch (JsonException)
         {
-            await ux.WriteInfoLineAsync($"❌ Failed to parse planning response: {ex.Message}", ConsoleColor.Red);
-            await ux.WriteInfoLineAsync($"(raw response) {collectedText}", ConsoleColor.DarkYellow);
+            // JSON parsing failed — fall back to rendering as regular text output.
+            await ux.WriteTextAsync(collectedText).ConfigureAwait(false);
             return null;
         }
 
         if (planningResponse is null)
         {
-            await ux.WriteInfoLineAsync("(no structured response from agent)", ConsoleColor.DarkYellow);
+            // Null result — fall back to rendering as regular text output.
+            await ux.WriteTextAsync(collectedText).ConfigureAwait(false);
             return null;
         }
 
@@ -118,7 +119,8 @@ public sealed class PlanningOutputObserver : ConsoleObserver
             return new List<FollowUpAction> { this.BuildApprovalAction(question, session) };
         }
 
-        await ux.WriteInfoLineAsync($"(unexpected response type: {planningResponse.Type})", ConsoleColor.DarkYellow);
+        // Unexpected type — fall back to rendering as regular text output.
+        await ux.WriteTextAsync(collectedText).ConfigureAwait(false);
         return null;
     }
 

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

@@ -5,17 +5,17 @@ using Microsoft.Extensions.AI;
 namespace Harness.Shared.Console.ToolFormatters;
 
 /// <summary>
-/// Formats <c>AgentMode_*</c> tool calls, showing the target mode for Set operations.
+/// Formats <c>mode_*</c> tool calls, showing the target mode for Set operations.
 /// </summary>
 public sealed class ModeToolFormatter : ToolCallFormatter
 {
     /// <inheritdoc/>
-    public override bool CanFormat(FunctionCallContent call) => call.Name.StartsWith("AgentMode_", StringComparison.Ordinal);
+    public override bool CanFormat(FunctionCallContent call) => call.Name.StartsWith("mode_", StringComparison.Ordinal);
 
     /// <inheritdoc/>
     public override string? FormatDetail(FunctionCallContent call) => call.Name switch
     {
-        "AgentMode_Set" => FormatStringArg(call, "mode"),
+        "mode_set" => FormatStringArg(call, "mode"),
         _ => null,
     };
 

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

@@ -7,20 +7,20 @@ using Microsoft.Extensions.AI;
 namespace Harness.Shared.Console.ToolFormatters;
 
 /// <summary>
-/// Formats <c>TodoList_*</c> tool calls with tree-view output for added items
+/// Formats <c>todos_*</c> tool calls with tree-view output for added items
 /// and structured output for complete/remove operations.
 /// </summary>
 public sealed class TodoToolFormatter : ToolCallFormatter
 {
     /// <inheritdoc/>
-    public override bool CanFormat(FunctionCallContent call) => call.Name.StartsWith("TodoList_", StringComparison.Ordinal);
+    public override bool CanFormat(FunctionCallContent call) => call.Name.StartsWith("todos_", StringComparison.Ordinal);
 
     /// <inheritdoc/>
     public override string? FormatDetail(FunctionCallContent call) => call.Name switch
     {
-        "TodoList_Add" => FormatAddTodos(call),
-        "TodoList_Complete" => FormatCompleteTodos(call),
-        "TodoList_Remove" => FormatIdList(call, "ids", "Remove"),
+        "todos_add" => FormatAddTodos(call),
+        "todos_complete" => FormatCompleteTodos(call),
+        "todos_remove" => FormatIdList(call, "ids", "Remove"),
         _ => null,
     };
 

dotnet/samples/02-agents/Harness/Harness_Shared_Console_OpenAI/OpenAIResponsesErrorObserver.cs

@@ -2,6 +2,7 @@
 
 #pragma warning disable OPENAI001 // Suppress experimental API warnings for Responses API usage.
 
+using System.Text.Json;
 using Harness.Shared.Console.Observers;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
@@ -53,9 +54,94 @@ public sealed class OpenAIResponsesErrorObserver : ConsoleObserver
 
             case StreamingResponseIncompleteUpdate incompleteUpdate:
                 string? reason = incompleteUpdate.Response?.IncompleteStatusDetails?.Reason?.ToString();
-                string incompleteText = $"⚠️ Response incomplete: {reason ?? "unknown reason"}";
-                await ux.WriteInfoLineAsync(incompleteText, ConsoleColor.Yellow);
+                if (string.Equals(reason, "content_filter", StringComparison.OrdinalIgnoreCase))
+                {
+                    string detail = GetContentFilterDetails(incompleteUpdate);
+                    const string Message = "🛡️  The service's built-in content filter guardrails were triggered and the response was cut short.";
+                    await ux.WriteInfoLineAsync(
+                        string.IsNullOrEmpty(detail) ? Message : $"{Message}\n{detail}",
+                        ConsoleColor.Yellow);
+                }
+                else
+                {
+                    string incompleteText = $"⚠️ Response incomplete: {reason ?? "unknown reason"}";
+                    await ux.WriteInfoLineAsync(incompleteText, ConsoleColor.Yellow);
+                }
+
                 break;
         }
     }
+
+    /// <summary>
+    /// Extracts content filter details from the serialized response JSON and returns
+    /// a formatted string showing which specific categories were triggered.
+    /// Returns <see cref="string.Empty"/> if details cannot be extracted.
+    /// </summary>
+    private static string GetContentFilterDetails(StreamingResponseIncompleteUpdate incompleteUpdate)
+    {
+        try
+        {
+            var data = System.ClientModel.Primitives.ModelReaderWriter.Write(incompleteUpdate);
+            using var doc = JsonDocument.Parse(data.ToString());
+            var root = doc.RootElement;
+
+            // Navigate into the nested response object if present.
+            JsonElement responseElement = root.TryGetProperty("response", out var resp) ? resp : root;
+
+            if (!responseElement.TryGetProperty("content_filters", out var filtersArray)
+                || filtersArray.ValueKind != JsonValueKind.Array)
+            {
+                return string.Empty;
+            }
+
+            foreach (var filter in filtersArray.EnumerateArray())
+            {
+                if (!filter.TryGetProperty("content_filter_results", out var results)
+                    || results.ValueKind != JsonValueKind.Object)
+                {
+                    continue;
+                }
+
+                // Collect category data for aligned output.
+                var categories = new List<(string Name, bool Filtered, string? Severity)>();
+                foreach (var category in results.EnumerateObject())
+                {
+                    if (category.Value.ValueKind != JsonValueKind.Object)
+                    {
+                        continue;
+                    }
+
+                    bool filtered = category.Value.TryGetProperty("filtered", out var f) && f.GetBoolean();
+                    string? severity = category.Value.TryGetProperty("severity", out var s) ? s.GetString() : null;
+                    categories.Add((category.Name, filtered, severity));
+                }
+
+                // Build all category lines into a single string.
+                int maxNameLen = categories.Count > 0 ? categories.Max(c => c.Name.Length) : 0;
+                var lines = new List<string>();
+
+                foreach (var (name, filtered, severity) in categories)
+                {
+                    string paddedName = name.PadRight(maxNameLen);
+                    string icon = filtered ? "❌" : "✅";
+                    string statusText = filtered ? "Filtered    " : "Not Filtered";
+                    string severityText = severity is not null ? $"   Severity: {severity}" : "";
+
+                    lines.Add($"    {icon} {paddedName}  {statusText}{severityText}");
+                }
+
+                if (lines.Count > 0)
+                {
+                    return string.Join("\n", lines);
+                }
+            }
+
+            return string.Empty;
+        }
+        catch
+        {
+            // Parsing not critical — skip silently if it fails.
+            return string.Empty;
+        }
+    }
 }

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

@@ -79,8 +79,10 @@ AIAgent agent =
     .GetProjectOpenAIClient()
     .GetResponsesClient()
     .AsIChatClient(deploymentName)
-    .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
+    .AsHarnessAgent(new HarnessAgentOptions
     {
+        MaxContextWindowTokens = MaxContextWindowTokens,
+        MaxOutputTokens = MaxOutputTokens,
         Name = "ResearchAgent",
         Description = "A research assistant that plans and executes research tasks.",
         DisableFileAccess = true,                           // If enabled, this would allow the agent to read/write files in a working directory

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

@@ -44,8 +44,10 @@ AIAgent webSearchAgent =
     .GetProjectOpenAIClient()
     .GetResponsesClient()
     .AsIChatClient(deploymentName)
-    .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
+    .AsHarnessAgent(new HarnessAgentOptions
     {
+        MaxContextWindowTokens = MaxContextWindowTokens,
+        MaxOutputTokens = MaxOutputTokens,
         Name = "WebSearchAgent",
         Description = "An agent that can search the web to find information.",
         OpenTelemetrySourceName = TracingSourceName,
@@ -92,8 +94,10 @@ AIAgent parentAgent =
     .GetProjectOpenAIClient()
     .GetResponsesClient()
     .AsIChatClient(deploymentName)
-    .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
+    .AsHarnessAgent(new HarnessAgentOptions
     {
+        MaxContextWindowTokens = MaxContextWindowTokens,
+        MaxOutputTokens = MaxOutputTokens,
         Name = "StockPriceResearcher",
         Description = "An agent that researches stock prices using background agents.",
         OpenTelemetrySourceName = TracingSourceName,

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

@@ -68,8 +68,10 @@ AIAgent agent =
     .GetProjectOpenAIClient()
     .GetResponsesClient()
     .AsIChatClient(deploymentName)
-    .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
+    .AsHarnessAgent(new HarnessAgentOptions
     {
+        MaxContextWindowTokens = MaxContextWindowTokens,
+        MaxOutputTokens = MaxOutputTokens,
         Name = "DataAnalyst",
         Description = "A data analyst assistant that reads, analyzes, and processes data files.",
         OpenTelemetrySourceName = TracingSourceName,

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

@@ -89,8 +89,10 @@ AIAgent agent =
     .GetProjectOpenAIClient()
     .GetResponsesClient()
     .AsIChatClient(deploymentName)
-    .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
+    .AsHarnessAgent(new HarnessAgentOptions
     {
+        MaxContextWindowTokens = MaxContextWindowTokens,
+        MaxOutputTokens = MaxOutputTokens,
         Name = "CodeExecutionAgent",
         Description = "A technical assistant with sandboxed code execution and skill-based workflows.",
         OpenTelemetrySourceName = TracingSourceName,

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

@@ -0,0 +1,25 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <NoWarn>$(NoWarn);MAAI001;MEAI001;MCPEXP001</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+    <PackageReference Include="Microsoft.Extensions.Hosting" />
+    <PackageReference Include="ModelContextProtocol" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Mcp\Microsoft.Agents.AI.Mcp.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

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

@@ -0,0 +1,145 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates the Microsoft Agent Framework's MCP long-running task support.
+//
+// A small MCP server (hosted in this same executable when launched with "--server") exposes
+// a single task-supporting tool "AnalyzeDataset" that simulates ~15 seconds of work. The
+// client (default mode) connects to it over stdio via Microsoft.Agents.AI.Mcp's
+// McpClientTaskExtensions.ListAgentToolsWithTaskSupportAsync, hands the wrapped tools to a
+// ChatClientAgent, and exercises both invocation styles:
+//   * RunAsync          — blocks until the agent's final response is ready.
+//   * RunStreamingAsync — yields response updates as the model produces them; the model
+//                         still waits for the tool's terminal result before it can begin
+//                         producing the final answer, so the perceived "pause" reflects
+//                         tool execution time, not stream-channel latency.
+//
+// In both cases the wrapper transparently:
+//   1. Calls tools/call with task augmentation (CallToolAsTaskAsync)
+//   2. Polls tasks/get until terminal (PollTaskUntilCompleteAsync)
+//   3. Fetches tasks/result and returns the final result to the function-calling loop
+//
+// No application-level loop or continuation tokens are required in either mode.
+
+using System.ComponentModel;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Mcp;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using ModelContextProtocol;
+using ModelContextProtocol.Client;
+using ModelContextProtocol.Protocol;
+using ModelContextProtocol.Server;
+using OpenAI.Chat;
+
+if (args.Length > 0 && args[0] == "--server")
+{
+    await RunMcpServerAsync();
+    return;
+}
+
+var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+
+// Launch this same assembly as a stdio MCP server in a child process.
+var thisAssemblyPath = typeof(Program).Assembly.Location;
+await using var mcpClient = await McpClient.CreateAsync(new StdioClientTransport(new()
+{
+    Name = "DatasetAnalyzer",
+    Command = "dotnet",
+    Arguments = [thisAssemblyPath, "--server"],
+}));
+
+// Wrap each MCP tool with task-aware behavior. The wrapper inspects the server's
+// execution.taskSupport on each tool and, when it is Required, drives the task lifecycle
+// transparently within the agent's tool loop. Tools that don't require task semantics are
+// returned as-is and invoked inline.
+var taskOptions = new McpTaskOptions
+{
+    DefaultTimeToLive = TimeSpan.FromMinutes(5),
+};
+var mcpTools = await mcpClient.ListAgentToolsWithTaskSupportAsync(taskOptions);
+
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+AIAgent agent = new AzureOpenAIClient(
+    new Uri(endpoint),
+    new DefaultAzureCredential())
+     .GetChatClient(deploymentName)
+     .AsAIAgent(
+        instructions: "You answer data-analysis questions by invoking the available tools. Always invoke a tool when one matches the request.",
+        tools: [.. mcpTools.Cast<AITool>()]);
+
+const string Prompt = "Analyze the dataset named 'sales-2025-q1' and summarize the findings.";
+
+Console.WriteLine("=== Transparent long-running MCP task (RunAsync) ===");
+Console.WriteLine("Asking the agent to analyze a dataset; the tool takes ~15s to complete.");
+Console.WriteLine("RunAsync blocks while the wrapper polls the task to completion.");
+Console.WriteLine();
+
+var stopwatch = System.Diagnostics.Stopwatch.StartNew();
+var response = await agent.RunAsync(Prompt);
+stopwatch.Stop();
+
+Console.WriteLine($"Agent response (after {stopwatch.Elapsed.TotalSeconds:F1}s):");
+Console.WriteLine(response.Text);
+
+Console.WriteLine();
+Console.WriteLine("=== Transparent long-running MCP task (RunStreamingAsync) ===");
+Console.WriteLine("Same request via the streaming API. Updates only begin to arrive after the");
+Console.WriteLine("tool's task reaches the Completed state, since the model needs the tool result");
+Console.WriteLine("before it can produce its final answer.");
+Console.WriteLine();
+
+stopwatch.Restart();
+await foreach (var update in agent.RunStreamingAsync(Prompt))
+{
+    Console.Write(update.Text);
+}
+stopwatch.Stop();
+
+Console.WriteLine();
+Console.WriteLine($"(Streaming completed after {stopwatch.Elapsed.TotalSeconds:F1}s.)");
+
+// --- Server mode (launched as a child process via --server) ---------------------------------
+static async Task RunMcpServerAsync()
+{
+    var builder = Host.CreateApplicationBuilder();
+
+    // Critical for stdio transport: any provider that writes to stdout will corrupt the
+    // JSON-RPC channel. Clear all providers; the MCP SDK routes its own diagnostics
+    // appropriately.
+    builder.Logging.ClearProviders();
+    builder.Logging.AddConsole(o => o.LogToStandardErrorThreshold = LogLevel.Trace);
+
+    builder.Services.AddMcpServer(o =>
+    {
+        o.TaskStore = new InMemoryMcpTaskStore();
+        o.ServerInfo = new Implementation { Name = "DatasetAnalyzer", Version = "1.0.0" };
+    })
+    .WithStdioServerTransport()
+    .WithTools<DatasetAnalysisTools>();
+
+    await builder.Build().RunAsync();
+}
+
+#pragma warning disable CA1812 // Discovered by MCP SDK via [McpServerToolType] attribute
+[McpServerToolType]
+internal sealed class DatasetAnalysisTools
+#pragma warning restore CA1812
+{
+    [McpServerTool(Name = "AnalyzeDataset", TaskSupport = ToolTaskSupport.Required)]
+    [Description("Analyze a tabular dataset and return summary statistics. This tool simulates a long-running analytic job (~15 seconds).")]
+    public static async Task<string> AnalyzeDatasetAsync(
+        [Description("The dataset identifier, e.g. 'sales-2025-q1'.")] string datasetName,
+        CancellationToken cancellationToken)
+    {
+        await Task.Delay(TimeSpan.FromSeconds(15), cancellationToken).ConfigureAwait(false);
+
+        return $"Findings for '{datasetName}': 12,403 rows; avg revenue $48,712; 3 anomalies detected in week 7; outliers concentrated in EMEA region.";
+    }
+}

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

@@ -0,0 +1,60 @@
+# Agent with MCP long-running task (transparent polling)
+
+This sample demonstrates Microsoft Agent Framework's MCP long-running task support: an agent invokes an MCP tool whose execution takes too long for a single request/response cycle, and the framework polls it to completion behind the function-calling loop. From the agent's perspective the tool simply returns its result.
+
+## What this sample shows
+
+- Using `McpClient.ListAgentToolsWithTaskSupportAsync(...)` (in `Microsoft.Agents.AI.Mcp`) to wrap MCP tools with task-aware behavior.
+- Configuring `McpTaskOptions.DefaultTimeToLive` to bound the server-side task.
+- Hosting a small MCP server (in this same executable, launched with `--server`) that advertises `execution.taskSupport=required` on a tool that sleeps for ~15 seconds.
+- No application-level polling, continuation tokens, or `AllowBackgroundResponses` flag are required.
+
+The decorator drives the lifecycle internally:
+
+1. `tools/call` augmented with task metadata (`CallToolAsTaskAsync`)
+2. `tasks/get` polled until terminal (`PollTaskUntilCompleteAsync`)
+3. `tasks/result` retrieved (`GetTaskResultAsync`) and returned to the function-calling loop
+
+The sample exercises both invocation styles against the same wrapper:
+
+- `agent.RunAsync(...)` blocks until the tool completes (~15 seconds in this sample) and returns the final response.
+- `agent.RunStreamingAsync(...)` returns immediately and yields `AgentResponseUpdate` chunks as the model emits them; in this scenario the model only begins streaming its answer once the wrapped tool's task reaches the `Completed` state, so the perceived "pause" before tokens arrive reflects tool execution time, not stream-channel latency.
+
+# Prerequisites
+
+- .NET 10 SDK or later
+- Azure OpenAI service endpoint and a chat-completions deployment
+- Azure CLI installed and authenticated (`az login`)
+
+Set the following environment variables:
+
+```powershell
+$env:AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
+$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-5.4-mini"  # optional; defaults to gpt-5.4-mini
+```
+
+# Running
+
+```powershell
+cd Agent_MCP_LongRunningTask_Client
+dotnet run
+```
+
+You should see output similar to:
+
+```
+=== Transparent long-running MCP task (RunAsync) ===
+Asking the agent to analyze a dataset; the tool takes ~15s to complete.
+RunAsync blocks while the wrapper polls the task to completion.
+
+Agent response (after 15.4s):
+The 'sales-2025-q1' dataset contains 12,403 rows ...
+
+=== Transparent long-running MCP task (RunStreamingAsync) ===
+Same request via the streaming API. Updates only begin to arrive after the
+tool's task reaches the Completed state, since the model needs the tool result
+before it can produce its final answer.
+
+The 'sales-2025-q1' dataset contains 12,403 rows ...
+(Streaming completed after 15.7s.)
+```

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

@@ -22,6 +22,7 @@ Before you begin, ensure you have the following prerequisites:
 |[Agent with MCP server tools](./Agent_MCP_Server/)|This sample demonstrates how to use MCP server tools with a simple agent|
 |[Agent with MCP server tools and authorization](./Agent_MCP_Server_Auth/)|This sample demonstrates how to use MCP Server tools from a protected MCP server with a simple agent|
 |[Responses Agent with Hosted MCP tool](./ResponseAgent_Hosted_MCP/)|This sample demonstrates how to use the Hosted MCP tool with the Responses Service, where the service invokes any MCP tools directly|
+|[Agent with long-running MCP task (transparent polling)](./Agent_MCP_LongRunningTask_Client/)|This sample demonstrates how an agent transparently drives a long-running MCP task (SEP-2663) to completion. The wrapper polls the task internally on both `RunAsync` and `RunStreamingAsync` invocations.|
 
 ## Running the samples from the console
 

dotnet/samples/03-workflows/Declarative/GenerateCode/GenerateCode.csproj

@@ -1,30 +0,0 @@
-<Project Sdk="Microsoft.NET.Sdk">
-
-  <PropertyGroup>
-    <OutputType>Exe</OutputType>
-    <TargetFrameworks>net10.0</TargetFrameworks>
-    <Nullable>enable</Nullable>
-    <ImplicitUsings>enable</ImplicitUsings>
-    <UserSecretsId>5ee045b0-aea3-4f08-8d31-32d1a6f8fed0</UserSecretsId>
-    <NoWarn>$(NoWarn);CA1812</NoWarn>
-  </PropertyGroup>
-
-  <PropertyGroup>
-    <InjectSharedThrow>true</InjectSharedThrow>
-  </PropertyGroup>
-
-  <ItemGroup>
-    <PackageReference Include="Microsoft.Extensions.Configuration" />
-    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
-    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
-    <PackageReference Include="Microsoft.Extensions.Configuration.Json" />
-    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
-    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
-    <PackageReference Include="Microsoft.Extensions.Logging" />
-  </ItemGroup>
-  
-  <ItemGroup>
-    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative\Microsoft.Agents.AI.Workflows.Declarative.csproj" />
-  </ItemGroup>
-
-</Project>

dotnet/samples/03-workflows/Declarative/GenerateCode/Program.cs

@@ -1,105 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using System.Diagnostics;
-using Microsoft.Agents.AI.Workflows.Declarative;
-
-namespace Demo.DeclarativeEject;
-
-/// <summary>
-/// HOW TO: Convert a workflow from a declartive (yaml based) definition to code.
-/// </summary>
-/// <remarks>
-/// <b>Usage</b>
-/// Provide the path to the workflow definition file as the first argument.
-/// All other arguments are intepreted as a queue of inputs.
-/// When no input is queued, interactive input is requested from the console.
-/// </remarks>
-internal sealed class Program
-{
-    public static void Main(string[] args)
-    {
-        Program program = new(args);
-        program.Execute();
-    }
-
-    private void Execute()
-    {
-        // Read and parse the declarative workflow.
-        Notify($"WORKFLOW: Parsing {Path.GetFullPath(this.WorkflowFile)}");
-
-        Stopwatch timer = Stopwatch.StartNew();
-
-        // Use DeclarativeWorkflowBuilder to generate code based on a YAML file.
-        string code =
-            DeclarativeWorkflowBuilder.Eject(
-                this.WorkflowFile,
-                DeclarativeWorkflowLanguage.CSharp,
-                workflowNamespace: "Demo.DeclarativeCode",
-                workflowPrefix: "Sample");
-
-        Notify($"\nWORKFLOW: Defined {timer.Elapsed}\n");
-
-        Console.WriteLine(code);
-    }
-
-    private const string DefaultWorkflow = "Marketing.yaml";
-
-    private string WorkflowFile { get; }
-
-    private Program(string[] args)
-    {
-        this.WorkflowFile = ParseWorkflowFile(args);
-    }
-
-    private static string ParseWorkflowFile(string[] args)
-    {
-        string workflowFile = args.FirstOrDefault() ?? DefaultWorkflow;
-
-        if (!File.Exists(workflowFile) && !Path.IsPathFullyQualified(workflowFile))
-        {
-            string? repoFolder = GetRepoFolder();
-            if (repoFolder is not null)
-            {
-                workflowFile = Path.Combine(repoFolder, "declarative-agents", "workflow-samples", workflowFile);
-                workflowFile = Path.ChangeExtension(workflowFile, ".yaml");
-            }
-        }
-
-        if (!File.Exists(workflowFile))
-        {
-            throw new InvalidOperationException($"Unable to locate workflow: {Path.GetFullPath(workflowFile)}.");
-        }
-
-        return workflowFile;
-
-        static string? GetRepoFolder()
-        {
-            DirectoryInfo? current = new(Directory.GetCurrentDirectory());
-
-            while (current is not null)
-            {
-                if (Directory.Exists(Path.Combine(current.FullName, ".git")))
-                {
-                    return current.FullName;
-                }
-
-                current = current.Parent;
-            }
-
-            return null;
-        }
-    }
-
-    private static void Notify(string message)
-    {
-        Console.ForegroundColor = ConsoleColor.Cyan;
-        try
-        {
-            Console.WriteLine(message);
-        }
-        finally
-        {
-            Console.ResetColor();
-        }
-    }
-}

dotnet/samples/03-workflows/Declarative/GenerateCode/Properties/launchSettings.json

@@ -1,28 +0,0 @@
-{
-  "profiles": {
-    "Marketing": {
-      "commandName": "Project",
-      "commandLineArgs": "\"Marketing.yaml\""
-    },
-    "MathChat": {
-      "commandName": "Project",
-      "commandLineArgs": "\"MathChat.yaml\""
-    },
-    "Question": {
-      "commandName": "Project",
-      "commandLineArgs": "\"Question.yaml\""
-    },
-    "Research": {
-      "commandName": "Project",
-      "commandLineArgs": "\"DeepResearch.yaml\""
-    },
-    "ResponseObject": {
-      "commandName": "Project",
-      "commandLineArgs": "\"ResponseObject.yaml\""
-    },
-    "UserInput": {
-      "commandName": "Project",
-      "commandLineArgs": "\"UserInput.yaml\""
-    }
-  }
-}

dotnet/samples/03-workflows/Observability/WorkflowAsAnAgent/WorkflowHelper.cs

@@ -50,12 +50,16 @@ internal static partial class WorkflowHelper
     /// <summary>
     /// Executor that starts the concurrent processing by sending messages to the agents.
     /// </summary>
-    private sealed partial class ConcurrentStartExecutor() : Executor("ConcurrentStartExecutor")
+    [SendsMessage(typeof(List<ChatMessage>))]
+    [SendsMessage(typeof(TurnToken))]
+    private sealed partial class ConcurrentStartExecutor()
+        : Executor("ConcurrentStartExecutor", declareCrossRunShareable: true), IResettableExecutor
     {
         [MessageHandler]
-        internal ValueTask RouteMessages(List<ChatMessage> messages, IWorkflowContext context, CancellationToken cancellationToken)
+        internal ValueTask RouteMessages(IEnumerable<ChatMessage> messages, IWorkflowContext context, CancellationToken cancellationToken)
         {
-            return context.SendMessageAsync(messages, cancellationToken: cancellationToken);
+            List<ChatMessage> payload = messages as List<ChatMessage> ?? messages.ToList();
+            return context.SendMessageAsync(payload, cancellationToken: cancellationToken);
         }
 
         [MessageHandler]
@@ -63,13 +67,16 @@ internal static partial class WorkflowHelper
         {
             return context.SendMessageAsync(token, cancellationToken: cancellationToken);
         }
+
+        public ValueTask ResetAsync() => default;
     }
 
     /// <summary>
     /// Executor that aggregates the results from the concurrent agents.
     /// </summary>
-    [YieldsOutput(typeof(List<ChatMessage>))]
-    private sealed partial class ConcurrentAggregationExecutor() : Executor<List<ChatMessage>>("ConcurrentAggregationExecutor")
+    [YieldsOutput(typeof(string))]
+    private sealed partial class ConcurrentAggregationExecutor() :
+        Executor<List<ChatMessage>>("ConcurrentAggregationExecutor"), IResettableExecutor
     {
         private readonly List<ChatMessage> _messages = [];
 
@@ -90,5 +97,11 @@ internal static partial class WorkflowHelper
                 await context.YieldOutputAsync(formattedMessages, cancellationToken);
             }
         }
+
+        public ValueTask ResetAsync()
+        {
+            this._messages.Clear();
+            return default;
+        }
     }
 }

dotnet/samples/03-workflows/Orchestration/Magentic/Magentic.csproj

@@ -0,0 +1,23 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <NoWarn>$(NoWarn);MAAIW001;OPENAI001</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Projects" />
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Orchestration/Magentic/Program.cs

@@ -0,0 +1,193 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample ports the Python Magentic orchestration sample to .NET.
+// A Magentic workflow coordinates a researcher and a coder, streams orchestration
+// events as the plan evolves, and prints the final conversation transcript.
+
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Agents.AI.Workflows.Specialized.Magentic;
+using Microsoft.Extensions.AI;
+
+namespace WorkflowMagenticOrchestrationSample;
+
+/// <summary>
+/// Demonstrates Magentic orchestration with a researcher, a coder, and an LLM manager.
+/// </summary>
+/// <remarks>
+/// Pre-requisites:
+/// - An Azure AI Foundry project endpoint and model deployment must be configured.
+/// - Run <c>az login</c> before executing the sample.
+/// </remarks>
+public static class Program
+{
+    private const string TaskPrompt =
+        "I am preparing a report on the energy efficiency of different machine learning model architectures. " +
+        "Compare the estimated training and inference energy consumption of ResNet-50, BERT-base, and GPT-2 " +
+        "on standard datasets (e.g., ImageNet for ResNet, GLUE for BERT, WebText for GPT-2). " +
+        "Then, estimate the CO2 emissions associated with each, assuming training on an Azure Standard_NC6s_v3 " +
+        "VM for 24 hours. Provide tables for clarity, and recommend the most energy-efficient model " +
+        "per task type (image classification, text classification, and text generation).";
+
+    private static async Task Main()
+    {
+        string endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
+            ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
+        string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+        AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
+
+        AIAgent researcherAgent = projectClient.AsAIAgent(
+            deploymentName,
+            name: "ResearcherAgent",
+            description: "Specialist in research and information gathering.",
+            instructions: "You are a researcher. Find relevant information without doing additional computation or quantitative analysis.");
+
+        AIAgent coderAgent = projectClient.AsAIAgent(
+            deploymentName,
+            name: "CoderAgent",
+            description: "A helpful assistant that writes and executes code to analyze data.",
+            instructions: "You solve quantitative questions by writing and running code. Show the analysis and the computation process clearly.",
+            tools: [new HostedCodeInterpreterTool()]);
+
+        AIAgent managerAgent = projectClient.AsAIAgent(
+            deploymentName,
+            name: "MagenticManager",
+            description: "Orchestrator that coordinates the research and coding workflow.",
+            instructions: "You coordinate the team to complete complex tasks efficiently.");
+
+        Workflow workflow = new MagenticWorkflowBuilder(managerAgent)
+            .AddParticipants([researcherAgent, coderAgent])
+            .WithName("Magentic Orchestration Workflow")
+            .WithDescription("Coordinates a researcher and coder to solve a complex analytical task.")
+            .RequirePlanSignoff(false)
+            .WithMaxRounds(10)
+            .WithMaxStalls(3)
+            .WithMaxResets(2)
+            .Build();
+
+        Console.WriteLine("Building Magentic workflow...");
+        Console.WriteLine();
+        Console.WriteLine($"Task: {TaskPrompt}");
+        Console.WriteLine();
+        Console.WriteLine("Starting workflow execution...");
+
+        await using StreamingRun run = await InProcessExecution.RunStreamingAsync(
+            workflow,
+            new List<ChatMessage> { new(ChatRole.User, TaskPrompt) });
+
+        await run.TrySendMessageAsync(new TurnToken(emitEvents: true));
+
+        string? lastResponseId = null;
+        WorkflowOutputEvent? finalOutput = null;
+
+        await foreach (WorkflowEvent workflowEvent in run.WatchStreamAsync())
+        {
+            switch (workflowEvent)
+            {
+                case AgentResponseUpdateEvent updateEvent:
+                    WriteStreamingUpdate(updateEvent, ref lastResponseId);
+                    break;
+
+                case MagenticPlanCreatedEvent planCreated:
+                    WriteMagenticMessage("Initial Plan", planCreated.FullTaskLedger.Text);
+                    PauseIfInteractive();
+                    break;
+
+                case MagenticReplannedEvent replanned:
+                    WriteMagenticMessage("Replanned", replanned.FullTaskLedger.Text);
+                    PauseIfInteractive();
+                    break;
+
+                case MagenticProgressLedgerUpdatedEvent progressUpdated:
+                    WriteMagenticMessage("Progress Ledger", FormatProgressLedger(progressUpdated.ProgressLedger));
+                    PauseIfInteractive();
+                    break;
+
+                case WorkflowOutputEvent outputEvent when outputEvent.Is<List<ChatMessage>>():
+                    finalOutput = outputEvent;
+                    break;
+
+                case WorkflowErrorEvent workflowError:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Error.WriteLine(workflowError.Exception?.ToString() ?? "Unknown workflow error occurred.");
+                    Console.ResetColor();
+                    break;
+
+                case ExecutorFailedEvent executorFailed:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Error.WriteLine($"Executor '{executorFailed.ExecutorId}' failed with {(executorFailed.Data is null ? "unknown error" : $"exception {executorFailed.Data}")}.");
+                    Console.ResetColor();
+                    break;
+            }
+        }
+
+        if (finalOutput?.As<List<ChatMessage>>() is { } transcript)
+        {
+            Console.WriteLine();
+            Console.WriteLine(new string('=', 80));
+            Console.WriteLine();
+            Console.WriteLine("Final Conversation Transcript:");
+            Console.WriteLine();
+
+            foreach (ChatMessage message in transcript)
+            {
+                Console.WriteLine($"{message.AuthorName ?? message.Role.ToString()}: {message.Text}");
+                Console.WriteLine();
+            }
+        }
+    }
+
+    private static void WriteStreamingUpdate(AgentResponseUpdateEvent updateEvent, ref string? lastResponseId)
+    {
+        string responseId = updateEvent.Update.ResponseId ?? updateEvent.Update.MessageId ?? updateEvent.ExecutorId;
+        if (!string.Equals(responseId, lastResponseId, StringComparison.Ordinal))
+        {
+            if (lastResponseId is not null)
+            {
+                Console.WriteLine();
+                Console.WriteLine();
+            }
+
+            Console.Write($"- {updateEvent.ExecutorId}: ");
+            lastResponseId = responseId;
+        }
+
+        if (!string.IsNullOrEmpty(updateEvent.Update.Text))
+        {
+            Console.Write(updateEvent.Update.Text);
+        }
+    }
+
+    private static void WriteMagenticMessage(string title, string? content)
+    {
+        Console.WriteLine();
+        Console.WriteLine($"[Magentic {title}]");
+        Console.WriteLine(content);
+    }
+
+    private static string FormatProgressLedger(MagenticProgressLedger ledger) =>
+        string.Join(Environment.NewLine,
+            $"Request satisfied: {ledger.IsRequestSatisfied}",
+            $"In loop: {ledger.IsInLoop}",
+            $"Making progress: {ledger.IsProgressBeingMade}",
+            $"Next speaker: {ledger.NextSpeaker}",
+            $"Instruction: {ledger.InstructionOrQuestion}");
+
+    private static void PauseIfInteractive()
+    {
+        if (Console.IsInputRedirected || Console.IsOutputRedirected)
+        {
+            return;
+        }
+
+        Console.Write("Press Enter to continue...");
+        Console.ReadLine();
+        Console.WriteLine();
+    }
+}

dotnet/samples/03-workflows/Orchestration/Magentic/README.md

@@ -0,0 +1,40 @@
+# Magentic Orchestration Sample
+
+This sample showcases the Magentic Orchestration Pattern in .NET, setting up a team with three roles:
+
+- **ResearcherAgent** gathers factual background information.
+- **CoderAgent** uses `HostedCodeInterpreterTool` for quantitative analysis.
+- **MagenticManager** plans the work, tracks progress, and decides who should act next.
+
+## What This Sample Demonstrates
+
+- Building a Magentic workflow with `MagenticWorkflowBuilder`
+- Combining standard responses-based agents with a code interpreter-enabled participant
+- Streaming orchestration events such as the initial plan, replans, and progress-ledger updates
+- Printing the final multi-agent conversation transcript
+
+## Prerequisites
+
+- `AZURE_AI_PROJECT_ENDPOINT` set to your Azure AI Foundry project endpoint
+- `AZURE_AI_MODEL_DEPLOYMENT_NAME` set to your model deployment name (defaults to `gpt-5.4-mini`)
+- `az login` completed before running the sample
+
+## Running the Sample
+
+```bash
+dotnet run
+```
+
+## Expected Output
+
+The sample prints:
+
+1. The original task prompt
+2. Streamed updates from the participating agents
+3. Magentic plan and progress-ledger events as the workflow coordinates the team
+4. The final conversation transcript returned by the workflow
+
+## Related Samples
+
+- [Handoff Orchestration](../Handoff) - another multi-agent orchestration pattern in .NET workflows
+- [Python Magentic workflow sample](../../../../../python/samples/03-workflows/orchestrations/magentic.py) - the source scenario that this sample ports

dotnet/samples/03-workflows/README.md

@@ -62,3 +62,4 @@ Once completed, please proceed to the other samples listed below.
 | Sample | Concepts |
 |--------|----------|
 | [Handoff Orchestration](./Orchestration/Handoff) | Introduces the Handoff Orchestration pattern |
+| [Magentic Orchestration](./Orchestration/Magentic) | Coordinates multiple agents with a Magentic manager, streamed plan events, and a final transcript |

dotnet/samples/04-hosting/DurableAgents/AzureFunctions/01_SingleAgent/local.settings.json

@@ -1,10 +0,0 @@
-{
-  "IsEncrypted": false,
-  "Values": {
-    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
-    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
-    "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None",
-    "AZURE_OPENAI_ENDPOINT": "<AZURE_OPENAI_ENDPOINT>",
-    "AZURE_OPENAI_DEPLOYMENT_NAME": "<AZURE_OPENAI_DEPLOYMENT_NAME>"
-  }
-}

dotnet/samples/04-hosting/DurableAgents/AzureFunctions/02_AgentOrchestration_Chaining/local.settings.json

@@ -1,10 +0,0 @@
-{
-  "IsEncrypted": false,
-  "Values": {
-    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
-    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
-    "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None",
-    "AZURE_OPENAI_ENDPOINT": "<AZURE_OPENAI_ENDPOINT>",
-    "AZURE_OPENAI_DEPLOYMENT_NAME": "<AZURE_OPENAI_DEPLOYMENT_NAME>"
-  }
-}

dotnet/samples/04-hosting/DurableAgents/AzureFunctions/03_AgentOrchestration_Concurrency/local.settings.json

@@ -1,10 +0,0 @@
-{
-  "IsEncrypted": false,
-  "Values": {
-    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
-    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
-    "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None",
-    "AZURE_OPENAI_ENDPOINT": "<AZURE_OPENAI_ENDPOINT>",
-    "AZURE_OPENAI_DEPLOYMENT_NAME": "<AZURE_OPENAI_DEPLOYMENT_NAME>"
-  }
-}

dotnet/samples/04-hosting/DurableAgents/AzureFunctions/04_AgentOrchestration_Conditionals/local.settings.json

@@ -1,10 +0,0 @@
-{
-  "IsEncrypted": false,
-  "Values": {
-    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
-    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
-    "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None",
-    "AZURE_OPENAI_ENDPOINT": "<AZURE_OPENAI_ENDPOINT>",
-    "AZURE_OPENAI_DEPLOYMENT_NAME": "<AZURE_OPENAI_DEPLOYMENT_NAME>"
-  }
-}

dotnet/samples/04-hosting/DurableAgents/AzureFunctions/05_AgentOrchestration_HITL/local.settings.json

@@ -1,10 +0,0 @@
-{
-  "IsEncrypted": false,
-  "Values": {
-    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
-    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
-    "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None",
-    "AZURE_OPENAI_ENDPOINT": "<AZURE_OPENAI_ENDPOINT>",
-    "AZURE_OPENAI_DEPLOYMENT_NAME": "<AZURE_OPENAI_DEPLOYMENT_NAME>"
-  }
-}

dotnet/samples/04-hosting/DurableAgents/AzureFunctions/06_LongRunningTools/local.settings.json

@@ -1,10 +0,0 @@
-{
-  "IsEncrypted": false,
-  "Values": {
-    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
-    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
-    "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None",
-    "AZURE_OPENAI_ENDPOINT": "<AZURE_OPENAI_ENDPOINT>",
-    "AZURE_OPENAI_DEPLOYMENT_NAME": "<AZURE_OPENAI_DEPLOYMENT_NAME>"
-  }
-}

dotnet/samples/04-hosting/DurableAgents/AzureFunctions/07_AgentAsMcpTool/local.settings.json

@@ -1,10 +0,0 @@
-{
-  "IsEncrypted": false,
-  "Values": {
-    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
-    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
-    "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None",
-    "AZURE_OPENAI_ENDPOINT": "<AZURE_OPENAI_ENDPOINT>",
-    "AZURE_OPENAI_DEPLOYMENT_NAME": "<AZURE_OPENAI_DEPLOYMENT_NAME>"
-  }
-}

dotnet/samples/04-hosting/DurableAgents/AzureFunctions/08_ReliableStreaming/local.settings.json

@@ -1,12 +0,0 @@
-{
-  "IsEncrypted": false,
-  "Values": {
-    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
-    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
-    "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None",
-    "AZURE_OPENAI_ENDPOINT": "<AZURE_OPENAI_ENDPOINT>",
-    "AZURE_OPENAI_DEPLOYMENT_NAME": "<AZURE_OPENAI_DEPLOYMENT_NAME>",
-    "REDIS_CONNECTION_STRING": "localhost:6379",
-    "REDIS_STREAM_TTL_MINUTES": "10"
-  }
-}

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/01_SequentialWorkflow/local.settings.json

@@ -1,10 +0,0 @@
-{
-  "IsEncrypted": false,
-  "Values": {
-    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
-    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
-    "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None",
-    "AZURE_OPENAI_ENDPOINT": "<AZURE_OPENAI_ENDPOINT>",
-    "AZURE_OPENAI_DEPLOYMENT_NAME": "<AZURE_OPENAI_DEPLOYMENT_NAME>"
-  }
-}

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/02_ConcurrentWorkflow/local.settings.json

@@ -1,10 +0,0 @@
-{
-  "IsEncrypted": false,
-  "Values": {
-    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
-    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
-    "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None",
-    "AZURE_OPENAI_ENDPOINT": "<AZURE_OPENAI_ENDPOINT>",
-    "AZURE_OPENAI_DEPLOYMENT_NAME": "<AZURE_OPENAI_DEPLOYMENT_NAME>"
-  }
-}

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/03_WorkflowHITL/local.settings.json

@@ -1,10 +0,0 @@
-{
-  "IsEncrypted": false,
-  "Values": {
-    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
-    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
-    "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None",
-    "AZURE_OPENAI_ENDPOINT": "<AZURE_OPENAI_ENDPOINT>",
-    "AZURE_OPENAI_DEPLOYMENT_NAME": "<AZURE_OPENAI_DEPLOYMENT_NAME>"
-  }
-}

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/04_WorkflowMcpTool/local.settings.json

@@ -1,8 +0,0 @@
-{
-  "IsEncrypted": false,
-  "Values": {
-    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
-    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
-    "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None"
-  }
-}

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/05_WorkflowAndAgents/local.settings.json

@@ -1,10 +0,0 @@
-{
-  "IsEncrypted": false,
-  "Values": {
-    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
-    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
-    "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None",
-    "AZURE_OPENAI_ENDPOINT": "<AZURE_OPENAI_ENDPOINT>",
-    "AZURE_OPENAI_DEPLOYMENT_NAME": "<AZURE_OPENAI_DEPLOYMENT_NAME>"
-  }
-}

dotnet/samples/04-hosting/FoundryHostedAgents/invocations/Hosted-Invocations-EchoAgent/README.md

@@ -71,6 +71,34 @@ curl -X POST http://localhost:8088/invocations \
   -d "Hello from Docker!"
 ```
 
+## Deploying to Foundry (azd spec)
+
+This sample includes an `azd` manifest (`agent.manifest.yaml`) and hosted agent spec (`agent.yaml`) for deployment to Foundry.
+
+Initialize an `azd` project from this sample's manifest:
+
+```bash
+mkdir hosted-invocations-echo-agent && cd hosted-invocations-echo-agent
+azd ai agent init -m https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/04-hosting/FoundryHostedAgents/invocations/Hosted-Invocations-EchoAgent/agent.manifest.yaml
+```
+
+Then deploy:
+
+```bash
+azd deploy
+```
+
+If you need to override defaults, set deployment-time environment variables in the `azd` environment before deploying:
+
+```bash
+azd env set AGENT_NAME hosted-invocations-echo-agent
+azd env set AZURE_AI_MODEL_DEPLOYMENT_NAME gpt-4o
+```
+
+For end-to-end hosted agent deployment guidance, see the [official deployment guide](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent).
+
+---
+
 ## NuGet package users
 
 If you are consuming the Agent Framework as a NuGet package (not building from source), use the standard `Dockerfile` instead of `Dockerfile.contributor`. See the commented section in `Hosted-Invocations-EchoAgent.csproj` for the `PackageReference` alternative.