[BREAKING] Python: Ensure session isolation for FHA invocation impl (#7158)

* Ensure session isolation for FHA invocation impl

* Fix type check errors

* Add user isolation to sample

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

@@ -17,7 +17,7 @@ runs:
     using: "composite"
     steps:
       - name: Set up uv
-        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
             version-file: "python/pyproject.toml"
             enable-cache: true
@@ -46,4 +46,4 @@ runs:
       - name: Install the project
         shell: bash
         run: |
-          cd python && uv sync --all-packages --all-extras --dev --prerelease=if-necessary-or-explicit
+          cd python && uv sync --all-packages --all-extras --all-groups --prerelease=if-necessary-or-explicit

.github/scripts/check_team_membership.js

@@ -1,25 +1,38 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 /**
- * Resolve the issue author and check their team membership.
+ * Resolve the issue or pull request author and check their team membership.
  *
  * @param {object} opts
  * @param {object} opts.github - Octokit REST client from actions/github-script
  * @param {object} opts.context - GitHub Actions context
  * @param {object} opts.core - GitHub Actions core toolkit
  * @param {string} opts.teamSlug - Team slug to check membership against
- * @param {string|number} opts.issueNumber - Issue number to resolve author for
+ * @param {string|number} opts.issueNumber - Issue or pull request number to resolve author for
  * @returns {Promise<{author: string|null, isTeamMember: boolean}>}
  */
 async function checkTeamMembership({ github, context, core, teamSlug, issueNumber }) {
-  let author = context.payload.issue?.user?.login;
+  let author =
+    context.payload.issue?.user?.login ??
+    context.payload.pull_request?.user?.login;
+
   if (!author) {
-    const { data: issue } = await github.rest.issues.get({
-      owner: context.repo.owner,
-      repo: context.repo.repo,
-      issue_number: Number(issueNumber),
-    });
-    author = issue.user?.login;
+    const number = Number(issueNumber);
+    if (context.payload.pull_request) {
+      const { data: pr } = await github.rest.pulls.get({
+        owner: context.repo.owner,
+        repo: context.repo.repo,
+        pull_number: number,
+      });
+      author = pr.user?.login;
+    } else {
+      const { data: issue } = await github.rest.issues.get({
+        owner: context.repo.owner,
+        repo: context.repo.repo,
+        issue_number: number,
+      });
+      author = issue.user?.login;
+    }
   }
 
   if (!author) {

.github/scripts/resolve_integration_test_target.js

@@ -0,0 +1,170 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+const DECISIVE_REVIEW_STATES = new Set(['APPROVED', 'CHANGES_REQUESTED', 'DISMISSED']);
+const SHA_PATTERN = /^[0-9a-f]{40}$/;
+const BRANCH_PATTERN = /^[a-zA-Z0-9_./-]+$/;
+
+function assertValidSha(sha, description) {
+  if (!SHA_PATTERN.test(sha)) {
+    throw new Error(`GitHub returned an invalid ${description} SHA.`);
+  }
+}
+
+function hasWritePermission(permissionData) {
+  return permissionData.user?.permissions?.push === true
+    || ['admin', 'maintain', 'write'].includes(permissionData.permission);
+}
+
+function latestDecisiveReviews(reviews) {
+  const latestByReviewer = new Map();
+  const sortedReviews = [...reviews].sort((left, right) => {
+    const submittedComparison = (left.submitted_at || '').localeCompare(right.submitted_at || '');
+    return submittedComparison || Number(left.id) - Number(right.id);
+  });
+
+  for (const review of sortedReviews) {
+    const state = review.state?.toUpperCase();
+    const reviewer = review.user?.login?.toLowerCase();
+    if (reviewer && DECISIVE_REVIEW_STATES.has(state)) {
+      latestByReviewer.set(reviewer, review);
+    }
+  }
+
+  return latestByReviewer;
+}
+
+async function resolvePullRequest({ github, context, core, prNumber, requiredApprovals }) {
+  if (!/^[0-9]+$/.test(prNumber)) {
+    throw new Error('Invalid PR number. Only numeric values are allowed.');
+  }
+
+  const pullNumber = Number(prNumber);
+  const { data: pullRequest } = await github.rest.pulls.get({
+    ...context.repo,
+    pull_number: pullNumber,
+  });
+
+  if (pullRequest.state !== 'open') {
+    throw new Error(`PR #${pullNumber} is not open (state: ${pullRequest.state}).`);
+  }
+
+  const headSha = pullRequest.head.sha;
+  const baseSha = pullRequest.base.sha;
+  assertValidSha(headSha, 'PR head');
+  assertValidSha(baseSha, 'PR base');
+
+  const reviews = await github.paginate(github.rest.pulls.listReviews, {
+    ...context.repo,
+    pull_number: pullNumber,
+    per_page: 100,
+  });
+  const latestReviews = latestDecisiveReviews(reviews);
+  const author = pullRequest.user?.login?.toLowerCase();
+  const approvalCandidates = [...latestReviews.entries()]
+    .filter(([, review]) => review.state.toUpperCase() === 'APPROVED')
+    .filter(([, review]) => review.commit_id === headSha)
+    .filter(([reviewer]) => reviewer !== author);
+
+  const approvedMaintainers = [];
+  for (const [reviewer] of approvalCandidates) {
+    const { data: permissionData } = await github.rest.repos.getCollaboratorPermissionLevel({
+      ...context.repo,
+      username: reviewer,
+    });
+    if (hasWritePermission(permissionData)) {
+      approvedMaintainers.push(reviewer);
+    } else {
+      core.info(`Ignoring approval from ${reviewer}: reviewer does not have write permission.`);
+    }
+  }
+
+  if (approvedMaintainers.length < requiredApprovals) {
+    throw new Error(
+      `PR #${pullNumber} head ${headSha} requires ${requiredApprovals} approvals from unique `
+      + `write-capable maintainers; found ${approvedMaintainers.length}.`,
+    );
+  }
+
+  core.info(
+    `PR #${pullNumber} head ${headSha} approved by: ${approvedMaintainers.join(', ')}.`,
+  );
+  return {
+    baseRef: baseSha,
+    checkoutRef: headSha,
+    description: `PR #${pullNumber}`,
+  };
+}
+
+async function resolveBranch({ github, context, core, branch }) {
+  if (!BRANCH_PATTERN.test(branch)) {
+    throw new Error(
+      'Invalid branch name. Only alphanumeric characters, hyphens, underscores, dots, and slashes '
+      + 'are allowed.',
+    );
+  }
+
+  const [{ data: repository }, { data: targetBranch }] = await Promise.all([
+    github.rest.repos.get(context.repo),
+    github.rest.repos.getBranch({ ...context.repo, branch }),
+  ]);
+  const { data: baseBranch } = await github.rest.repos.getBranch({
+    ...context.repo,
+    branch: repository.default_branch,
+  });
+
+  const checkoutRef = targetBranch.commit.sha;
+  const baseRef = baseBranch.commit.sha;
+  assertValidSha(checkoutRef, 'branch head');
+  assertValidSha(baseRef, 'default branch');
+  core.info(`Branch ${branch} resolved to immutable commit ${checkoutRef}.`);
+
+  return {
+    baseRef,
+    checkoutRef,
+    description: `branch ${branch}`,
+  };
+}
+
+/**
+ * Resolve a manually requested integration-test target to an immutable commit.
+ *
+ * Pull requests must have fresh approvals from two unique write-capable
+ * maintainers for the exact head commit. Branches are limited to branches in
+ * the base repository and are pinned to their current commit.
+ */
+async function resolveIntegrationTestTarget({
+  github,
+  context,
+  core,
+  prNumber = '',
+  branch = '',
+  requiredApprovals = 2,
+}) {
+  const normalizedPrNumber = prNumber.trim();
+  const normalizedBranch = branch.trim();
+
+  if (normalizedPrNumber && normalizedBranch) {
+    throw new Error('Please provide either a PR number or a branch name, not both.');
+  }
+  if (!normalizedPrNumber && !normalizedBranch) {
+    throw new Error('Please provide either a PR number or a branch name.');
+  }
+
+  if (normalizedPrNumber) {
+    return resolvePullRequest({
+      github,
+      context,
+      core,
+      prNumber: normalizedPrNumber,
+      requiredApprovals,
+    });
+  }
+  return resolveBranch({
+    github,
+    context,
+    core,
+    branch: normalizedBranch,
+  });
+}
+
+module.exports = resolveIntegrationTestTarget;

.github/tests/test_check_team_membership.js

@@ -16,7 +16,12 @@ const checkTeamMembership = require('../scripts/check_team_membership.js');
 // Helpers
 // ---------------------------------------------------------------------------
 
-function createMocks({ payloadIssue = undefined, apiUser = 'api-user', teamState = 'active' } = {}) {
+function createMocks({
+  payloadIssue = undefined,
+  payloadPullRequest = undefined,
+  apiUser = 'api-user',
+  teamState = 'active',
+} = {}) {
   const core = {
     _infoMessages: [],
     _failedMessages: [],
@@ -24,8 +29,16 @@ function createMocks({ payloadIssue = undefined, apiUser = 'api-user', teamState
     setFailed(msg) { this._failedMessages.push(msg); },
   };
 
+  const payload = {};
+  if (payloadIssue !== undefined) {
+    payload.issue = payloadIssue;
+  }
+  if (payloadPullRequest !== undefined) {
+    payload.pull_request = payloadPullRequest;
+  }
+
   const context = {
-    payload: { issue: payloadIssue },
+    payload,
     repo: { owner: 'test-org', repo: 'test-repo' },
   };
 
@@ -36,6 +49,11 @@ function createMocks({ payloadIssue = undefined, apiUser = 'api-user', teamState
           data: { user: apiUser ? { login: apiUser } : null },
         }),
       },
+      pulls: {
+        get: async () => ({
+          data: { user: apiUser ? { login: apiUser } : null },
+        }),
+      },
       teams: {
         getByName: async () => ({}),
         getMembershipForUserInOrg: async () => ({
@@ -64,6 +82,37 @@ describe('author resolution', () => {
     assert.equal(result.author, 'payload-user');
   });
 
+  it('resolves author from pull_request event payload', async () => {
+    const { github, context, core } = createMocks({
+      payloadPullRequest: { user: { login: 'pr-author' } },
+    });
+    let issuesGetCalled = false;
+    github.rest.issues.get = async () => {
+      issuesGetCalled = true;
+      return { data: { user: { login: 'api-user' } } };
+    };
+
+    const result = await checkTeamMembership({ github, context, core, ...BASE_OPTS });
+    assert.equal(result.author, 'pr-author');
+    assert.equal(issuesGetCalled, false);
+  });
+
+  it('resolves author via pulls API when pull_request payload user is null', async () => {
+    const { github, context, core } = createMocks({
+      payloadPullRequest: { user: null },
+      apiUser: 'fetched-pr-author',
+    });
+    let pullsGetCalled = false;
+    github.rest.pulls.get = async () => {
+      pullsGetCalled = true;
+      return { data: { user: { login: 'fetched-pr-author' } } };
+    };
+
+    const result = await checkTeamMembership({ github, context, core, ...BASE_OPTS });
+    assert.equal(result.author, 'fetched-pr-author');
+    assert.equal(pullsGetCalled, true);
+  });
+
   it('resolves author via API when payload issue is absent', async () => {
     const { github, context, core } = createMocks({ apiUser: 'api-user' });
     const result = await checkTeamMembership({ github, context, core, ...BASE_OPTS });

.github/tests/test_resolve_integration_test_target.js

@@ -0,0 +1,212 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+/**
+ * Tests for resolve_integration_test_target.js.
+ *
+ * Run with: node --test .github/tests/test_resolve_integration_test_target.js
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+
+const resolveIntegrationTestTarget = require('../scripts/resolve_integration_test_target.js');
+
+const HEAD_SHA = 'a'.repeat(40);
+const BASE_SHA = 'b'.repeat(40);
+
+function review({
+  id,
+  login,
+  state = 'APPROVED',
+  commitId = HEAD_SHA,
+  submittedAt = `2026-07-13T00:00:${String(id).padStart(2, '0')}Z`,
+}) {
+  return {
+    id,
+    state,
+    commit_id: commitId,
+    submitted_at: submittedAt,
+    user: { login },
+  };
+}
+
+function createMocks({
+  pullState = 'open',
+  pullAuthor = 'contributor',
+  reviews = [],
+  permissions = {},
+} = {}) {
+  const core = {
+    infoMessages: [],
+    info(message) {
+      this.infoMessages.push(message);
+    },
+  };
+  const context = {
+    repo: { owner: 'microsoft', repo: 'agent-framework' },
+  };
+  const github = {
+    paginate: async () => reviews,
+    rest: {
+      pulls: {
+        get: async () => ({
+          data: {
+            state: pullState,
+            user: { login: pullAuthor },
+            head: { sha: HEAD_SHA },
+            base: { sha: BASE_SHA },
+          },
+        }),
+        listReviews: async () => {},
+      },
+      repos: {
+        get: async () => ({ data: { default_branch: 'main' } }),
+        getBranch: async ({ branch }) => ({
+          data: { commit: { sha: branch === 'main' ? BASE_SHA : HEAD_SHA } },
+        }),
+        getCollaboratorPermissionLevel: async ({ username }) => ({
+          data: permissions[username] || {
+            permission: 'read',
+            user: { permissions: { push: false } },
+          },
+        }),
+      },
+    },
+  };
+
+  return { core, context, github };
+}
+
+const WRITE_PERMISSION = {
+  permission: 'write',
+  user: { permissions: { push: true } },
+};
+
+describe('input validation', () => {
+  it('rejects missing and conflicting targets', async () => {
+    const mocks = createMocks();
+    await assert.rejects(
+      () => resolveIntegrationTestTarget(mocks),
+      /provide either a PR number or a branch name/,
+    );
+    await assert.rejects(
+      () => resolveIntegrationTestTarget({ ...mocks, prNumber: '1', branch: 'feature' }),
+      /not both/,
+    );
+  });
+
+  it('rejects invalid PR numbers and branch names', async () => {
+    const mocks = createMocks();
+    await assert.rejects(
+      () => resolveIntegrationTestTarget({ ...mocks, prNumber: '1;echo' }),
+      /Invalid PR number/,
+    );
+    await assert.rejects(
+      () => resolveIntegrationTestTarget({ ...mocks, branch: 'feature branch' }),
+      /Invalid branch name/,
+    );
+  });
+});
+
+describe('pull request resolution', () => {
+  it('pins an open PR with two fresh write-capable approvals', async () => {
+    const mocks = createMocks({
+      reviews: [
+        review({ id: 1, login: 'maintainer-one' }),
+        review({ id: 2, login: 'maintainer-two' }),
+      ],
+      permissions: {
+        'maintainer-one': WRITE_PERMISSION,
+        'maintainer-two': WRITE_PERMISSION,
+      },
+    });
+
+    const result = await resolveIntegrationTestTarget({ ...mocks, prNumber: '123' });
+
+    assert.deepEqual(result, {
+      baseRef: BASE_SHA,
+      checkoutRef: HEAD_SHA,
+      description: 'PR #123',
+    });
+  });
+
+  it('rejects closed PRs', async () => {
+    const mocks = createMocks({ pullState: 'closed' });
+    await assert.rejects(
+      () => resolveIntegrationTestTarget({ ...mocks, prNumber: '123' }),
+      /is not open/,
+    );
+  });
+
+  it('ignores stale, self, and read-only approvals', async () => {
+    const mocks = createMocks({
+      reviews: [
+        review({ id: 1, login: 'stale', commitId: 'c'.repeat(40) }),
+        review({ id: 2, login: 'contributor' }),
+        review({ id: 3, login: 'reader' }),
+        review({ id: 4, login: 'maintainer' }),
+      ],
+      permissions: {
+        contributor: WRITE_PERMISSION,
+        reader: { permission: 'read', user: { permissions: { push: false } } },
+        maintainer: WRITE_PERMISSION,
+      },
+    });
+
+    await assert.rejects(
+      () => resolveIntegrationTestTarget({ ...mocks, prNumber: '123' }),
+      /found 1/,
+    );
+  });
+
+  it('uses each reviewer latest decisive review and ignores later comments', async () => {
+    const mocks = createMocks({
+      reviews: [
+        review({ id: 1, login: 'changes-requested' }),
+        review({ id: 2, login: 'changes-requested', state: 'CHANGES_REQUESTED' }),
+        review({ id: 3, login: 'maintainer-one' }),
+        review({ id: 4, login: 'maintainer-one', state: 'COMMENTED' }),
+        review({ id: 5, login: 'maintainer-two' }),
+      ],
+      permissions: {
+        'changes-requested': WRITE_PERMISSION,
+        'maintainer-one': WRITE_PERMISSION,
+        'maintainer-two': WRITE_PERMISSION,
+      },
+    });
+
+    const result = await resolveIntegrationTestTarget({ ...mocks, prNumber: '123' });
+    assert.equal(result.checkoutRef, HEAD_SHA);
+  });
+
+  it('does not count a dismissed approval', async () => {
+    const mocks = createMocks({
+      reviews: [
+        review({ id: 1, login: 'dismissed', state: 'DISMISSED' }),
+        review({ id: 2, login: 'maintainer' }),
+      ],
+      permissions: {
+        dismissed: WRITE_PERMISSION,
+        maintainer: WRITE_PERMISSION,
+      },
+    });
+
+    await assert.rejects(
+      () => resolveIntegrationTestTarget({ ...mocks, prNumber: '123' }),
+      /found 1/,
+    );
+  });
+});
+
+describe('branch resolution', () => {
+  it('pins base-repository branches and their comparison base to SHAs', async () => {
+    const mocks = createMocks();
+    const result = await resolveIntegrationTestTarget({ ...mocks, branch: 'feature/test' });
+
+    assert.deepEqual(result, {
+      baseRef: BASE_SHA,
+      checkoutRef: HEAD_SHA,
+      description: 'branch feature/test',
+    });
+  });
+});

.github/upgrades/prompts/SemanticKernelToAgentFramework.md

@@ -23,16 +23,16 @@ For each project that needs to be migrated, you need to do the following:
 - Identify the specific Semantic Kernel agent types being used:
   - `ChatCompletionAgent` → `ChatClientAgent`
   - `OpenAIAssistantAgent` → `assistantsClient.CreateAIAgent()` (via OpenAI Assistants client extension)
-  - `AzureAIAgent` → `persistentAgentsClient.CreateAIAgent()` (via Azure AI Foundry client extension)
+  - `AzureAIAgent` → `persistentAgentsClient.CreateAIAgent()` (via Microsoft Foundry client extension)
   - `OpenAIResponseAgent` → `responsesClient.CreateAIAgent()` (via OpenAI Responses client extension)
   - `A2AAgent` → `AIAgent` (via A2A card resolver)
   - `BedrockAgent` → Custom implementation required (not supported)
 - Determine if agents are being created new or retrieved from hosted services:
   - **New agents**: Use `CreateAIAgent()` methods
-  - **Existing hosted agents**: Use `GetAIAgent(agentId)` methods for OpenAI Assistants and Azure AI Foundry
+  - **Existing hosted agents**: Use `GetAIAgent(agentId)` methods for OpenAI Assistants and Microsoft Foundry
 </agent_type_identification>
 
-- Determine the AI provider being used (OpenAI, Azure OpenAI, Azure AI Foundry, etc.)
+- Determine the AI provider being used (OpenAI, Azure OpenAI, Microsoft Foundry, etc.)
 - Analyze tool/function registration patterns
 - Review thread management and invocation patterns
 
@@ -90,7 +90,7 @@ below in wrong order or skip any of them):
    you generate report when migration complete. Report should contain:
      - all project dependencies changes (mention what was changed, added or removed, including provider-specific packages)
      - all code files that were changed (mention what was changed in the file, if it was not changed, just mention that the file was not changed)
-     - provider-specific migration patterns used (OpenAI, Azure OpenAI, Azure AI Foundry, A2A, ONNX, etc.)
+     - provider-specific migration patterns used (OpenAI, Azure OpenAI, Microsoft Foundry, A2A, ONNX, etc.)
      - all cases where you could not convert the code because of unsupported features and you were unable to find a workaround
      - unsupported providers that require custom implementation (Bedrock, CopilotStudio)
      - breaking glass pattern migrations (InnerContent → RawRepresentation) and any CodeInterpreter or advanced tool usage
@@ -223,7 +223,7 @@ using Microsoft.Agents.AI;
 // Provider-specific namespaces (add only if needed):
 using OpenAI; // For OpenAI provider
 using Azure.AI.OpenAI; // For Azure OpenAI provider
-using Azure.AI.Agents.Persistent; // For Azure AI Foundry provider
+using Azure.AI.Agents.Persistent; // For Microsoft Foundry provider
 using Azure.Identity; // For Azure authentication
 ```
 </configuration_changes>
@@ -499,7 +499,7 @@ For every thread created if there's intent to cleanup, the caller should track a
 var assistantClient = new OpenAIClient(apiKey).GetAssistantClient();
 await assistantClient.DeleteThreadAsync(thread.ConversationId);
 
-// For Azure AI Foundry (when cleanup is needed):
+// For Microsoft Foundry (when cleanup is needed):
 var persistentClient = new PersistentAgentsClient(endpoint, credential);
 await persistentClient.Threads.DeleteThreadAsync(thread.ConversationId);
 
@@ -514,7 +514,7 @@ await persistentClient.Threads.DeleteThreadAsync(thread.ConversationId);
 1. Remove `thread.DeleteAsync()` calls
 2. Use provider-specific client for cleanup when required
 3. Access thread ID via `thread.ConversationId` property
-4. Only implement cleanup for providers that require it (Assistants, Azure AI Foundry)
+4. Only implement cleanup for providers that require it (Assistants, Microsoft Foundry)
 </api_changes>
 
 ### Provider-Specific Creation Patterns
@@ -550,13 +550,13 @@ AIAgent agent = new AzureOpenAIClient(endpoint, credential)
     .CreateAIAgent(instructions: instructions);
 ```
 
-**Azure AI Foundry (New):**
+**Microsoft Foundry (New):**
 ```csharp
 AIAgent agent = new PersistentAgentsClient(endpoint, credential)
     .CreateAIAgent(model: deploymentName, instructions: instructions);
 ```
 
-**Azure AI Foundry (Existing):**
+**Microsoft Foundry (Existing):**
 ```csharp
 AIAgent agent = await new PersistentAgentsClient(endpoint, credential)
     .GetAIAgentAsync(agentId);
@@ -1079,7 +1079,7 @@ AgentThread thread = agent.GetNewThread();
 ```
 </api_changes>
 
-### 4. Azure AI Foundry (AzureAIAgent) Migration
+### 4. Microsoft Foundry (AzureAIAgent) Migration
 
 <configuration_changes>
 **Remove Semantic Kernel Packages:**

.github/workflows/codeql-analysis.yml

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

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

@@ -140,7 +140,7 @@ jobs:
           python-version: "3.13"
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           version: "0.11.x"
           enable-cache: true

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

@@ -42,7 +42,7 @@ jobs:
       coreChanged: ${{ steps.filter.outputs.core }}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
-      - uses: dorny/paths-filter@d1c1ffe0248fe513906c8e24db8ea791d46f8590 # v3
+      - uses: dorny/paths-filter@7b450fff21473bca461d4b92ce414b9d0420d706 # v4.0.2
         id: filter
         with:
           filters: |
@@ -163,6 +163,7 @@ jobs:
           # Change to project directory to ensure local nuget.config is used
           pushd consoleapp
           dotnet add packcheck.csproj package Microsoft.Agents.AI --prerelease
+          dotnet add packcheck.csproj package Microsoft.Agents.AI.LocalCodeAct --prerelease
           dotnet build -f ${{ matrix.targetFramework }} -c ${{ matrix.configuration }} packcheck.csproj
 
           # Clean up
@@ -312,7 +313,7 @@ jobs:
           AZURE_OPENAI_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_DEPLOYMENT_NAME }}
           AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_DEPLOYMENT_NAME }}
           AZURE_OPENAI_ENDPOINT: ${{ vars.AZURE_OPENAI_ENDPOINT }}
-          # Azure AI Foundry
+          # Microsoft Foundry
           AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
           AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZURE_AI_MODEL_DEPLOYMENT_NAME }}
           AZURE_AI_BING_CONNECTION_ID: ${{ vars.AZURE_AI_BING_CONNECTION_ID }}
@@ -528,7 +529,7 @@ jobs:
           AZURE_OPENAI_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_DEPLOYMENT_NAME }}
           AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_DEPLOYMENT_NAME }}
           AZURE_OPENAI_ENDPOINT: ${{ vars.AZURE_OPENAI_ENDPOINT }}
-          # Azure AI Foundry
+          # Microsoft Foundry
           AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
           AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZURE_AI_MODEL_DEPLOYMENT_NAME }}
           AZURE_AI_BING_CONNECTION_ID: ${{ vars.AZURE_AI_BING_CONNECTION_ID }}
@@ -610,12 +611,12 @@ jobs:
           python-version: "3.13"
           os: ${{ runner.os }}
       - name: Download all test results from current run
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           pattern: dotnet-test-results-*
           path: dotnet-test-results/
       - name: Restore report history cache
-        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: python/dotnet-integration-report-history.json
           key: dotnet-integration-report-history-${{ github.run_id }}
@@ -632,7 +633,7 @@ jobs:
         run: cat dotnet-integration-test-report.md >> $GITHUB_STEP_SUMMARY
       - name: Save report history cache
         if: always()
-        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: python/dotnet-integration-report-history.json
           key: dotnet-integration-report-history-${{ github.run_id }}

.github/workflows/dotnet-format.yml

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

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

@@ -9,16 +9,31 @@ on:
   workflow_call:
     inputs:
       checkout-ref:
-        description: "Git ref to checkout (e.g., refs/pull/123/head)"
+        description: "Immutable commit SHA to check out"
         required: true
         type: string
+    secrets:
+      AZURE_CLIENT_ID:
+        required: true
+      AZURE_TENANT_ID:
+        required: true
+      AZURE_SUBSCRIPTION_ID:
+        required: true
+      AZUREAI__ENDPOINT:
+        required: true
+      COPILOT_GITHUB_TOKEN:
+        required: true
+      OPENAI__APIKEY:
+        required: true
 
 permissions:
   contents: read
-  id-token: write
 
 jobs:
   dotnet-integration-tests:
+    permissions:
+      contents: read
+      id-token: write
     strategy:
       fail-fast: false
       matrix:

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

@@ -105,7 +105,7 @@ jobs:
           AZURE_OPENAI_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_DEPLOYMENT_NAME }}
           AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_DEPLOYMENT_NAME }}
           AZURE_OPENAI_ENDPOINT: ${{ vars.AZURE_OPENAI_ENDPOINT }}
-          # Azure AI Foundry
+          # Microsoft Foundry
           AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
           AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZURE_AI_MODEL_DEPLOYMENT_NAME }}
           AZURE_AI_BING_CONNECTION_ID: ${{ vars.AZURE_AI_BING_CONNECTION_ID }}

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

@@ -3,7 +3,7 @@
 # Go to Actions → "Integration Tests (Manual)" → Run workflow → enter a PR number or branch name.
 #
 # It calls dedicated integration-only workflows (dotnet-integration-tests and python-integration-tests),
-# passing a ref so they check out and test the correct code.
+# passing an immutable commit SHA so they check out and test the approved code.
 # Changed paths are detected here so only the relevant test suites run.
 #
 
@@ -26,7 +26,6 @@ on:
 permissions:
   contents: read
   pull-requests: read
-  id-token: write
 
 concurrency:
   group: integration-tests-manual-${{ github.event.inputs.pr-number || github.event.inputs.branch }}
@@ -38,67 +37,50 @@ jobs:
     runs-on: ubuntu-latest
     outputs:
       checkout-ref: ${{ steps.resolve.outputs.checkout-ref }}
+      base-ref: ${{ steps.resolve.outputs.base-ref }}
       dotnet-changes: ${{ steps.detect-changes.outputs.dotnet }}
       python-changes: ${{ steps.detect-changes.outputs.python }}
     steps:
-      - name: Resolve checkout ref
+      - name: Check out trusted workflow helpers
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: ${{ github.sha }}
+          persist-credentials: false
+          sparse-checkout: .github/scripts
+
+      - name: Resolve and authorize checkout ref
         id: resolve
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const resolveIntegrationTestTarget = require(
+              './.github/scripts/resolve_integration_test_target.js'
+            );
+            const target = await resolveIntegrationTestTarget({
+              github,
+              context,
+              core,
+              prNumber: process.env.PR_NUMBER,
+              branch: process.env.BRANCH,
+            });
+            core.setOutput('checkout-ref', target.checkoutRef);
+            core.setOutput('base-ref', target.baseRef);
+            core.info(`Running integration tests for ${target.description} at ${target.checkoutRef}.`);
         env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PR_NUMBER: ${{ github.event.inputs.pr-number }}
           BRANCH: ${{ github.event.inputs.branch }}
-          REPO: ${{ github.repository }}
-        run: |
-          if [ -n "$PR_NUMBER" ] && [ -n "$BRANCH" ]; then
-            echo "::error::Please provide either a PR number or a branch name, not both."
-            exit 1
-          fi
-
-          if [ -z "$PR_NUMBER" ] && [ -z "$BRANCH" ]; then
-            echo "::error::Please provide either a PR number or a branch name."
-            exit 1
-          fi
-
-          if [ -n "$PR_NUMBER" ]; then
-            if ! echo "$PR_NUMBER" | grep -Eq '^[0-9]+$'; then
-              echo "::error::Invalid PR number. Only numeric values are allowed."
-              exit 1
-            fi
-
-            PR_DATA=$(gh pr view "$PR_NUMBER" --repo "$REPO" --json state)
-            PR_STATE=$(echo "$PR_DATA" | jq -r '.state')
-
-            if [ "$PR_STATE" != "OPEN" ]; then
-              echo "::error::PR #$PR_NUMBER is not open (state: $PR_STATE)"
-              exit 1
-            fi
-
-            echo "checkout-ref=refs/pull/$PR_NUMBER/head" >> "$GITHUB_OUTPUT"
-            echo "Running integration tests for PR #$PR_NUMBER"
-          else
-            if ! echo "$BRANCH" | grep -Eq '^[a-zA-Z0-9_./-]+$'; then
-              echo "::error::Invalid branch name. Only alphanumeric characters, hyphens, underscores, dots, and slashes are allowed."
-              exit 1
-            fi
-
-            echo "checkout-ref=$BRANCH" >> "$GITHUB_OUTPUT"
-            echo "Running integration tests for branch $BRANCH"
-          fi
 
       - name: Detect changed paths
         id: detect-changes
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          PR_NUMBER: ${{ github.event.inputs.pr-number }}
-          BRANCH: ${{ github.event.inputs.branch }}
+          BASE_REF: ${{ steps.resolve.outputs.base-ref }}
+          CHECKOUT_REF: ${{ steps.resolve.outputs.checkout-ref }}
           REPO: ${{ github.repository }}
         run: |
-          if [ -n "$PR_NUMBER" ]; then
-            CHANGED_FILES=$(gh pr diff "$PR_NUMBER" --repo "$REPO" --name-only)
-          else
-            # For branches, compare against main using the GitHub API
-            CHANGED_FILES=$(gh api "repos/$REPO/compare/main...$BRANCH" --jq '.files[].filename')
-          fi
+          CHANGED_FILES=$(gh api "repos/$REPO/compare/$BASE_REF...$CHECKOUT_REF" \
+            --jq '.files[].filename')
 
           DOTNET_CHANGES=false
           PYTHON_CHANGES=false
@@ -113,22 +95,41 @@ jobs:
 
           echo "dotnet=$DOTNET_CHANGES" >> "$GITHUB_OUTPUT"
           echo "python=$PYTHON_CHANGES" >> "$GITHUB_OUTPUT"
-          echo "Detected changes — dotnet: $DOTNET_CHANGES, python: $PYTHON_CHANGES"
+          echo "Detected changes; dotnet: $DOTNET_CHANGES, python: $PYTHON_CHANGES"
 
   dotnet-integration-tests:
     name: .NET Integration Tests
     needs: resolve-ref
     if: needs.resolve-ref.outputs.dotnet-changes == 'true'
+    permissions:
+      contents: read
+      id-token: write
     uses: ./.github/workflows/dotnet-integration-tests.yml
     with:
       checkout-ref: ${{ needs.resolve-ref.outputs.checkout-ref }}
-    secrets: inherit
+    secrets:
+      AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
+      AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
+      AZURE_SUBSCRIPTION_ID: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+      AZUREAI__ENDPOINT: ${{ secrets.AZUREAI__ENDPOINT }}
+      COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+      OPENAI__APIKEY: ${{ secrets.OPENAI__APIKEY }}
 
   python-integration-tests:
     name: Python Integration Tests
     needs: resolve-ref
     if: needs.resolve-ref.outputs.python-changes == 'true'
+    permissions:
+      contents: read
+      id-token: write
     uses: ./.github/workflows/python-integration-tests.yml
     with:
       checkout-ref: ${{ needs.resolve-ref.outputs.checkout-ref }}
-    secrets: inherit
+    secrets:
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
+      AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
+      AZURE_SUBSCRIPTION_ID: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+      COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+      FOUNDRY_MODELS_API_KEY: ${{ secrets.FOUNDRY_MODELS_API_KEY }}
+      OPENAI__APIKEY: ${{ secrets.OPENAI__APIKEY }}

.github/workflows/issue-triage.yml

@@ -3,6 +3,12 @@ name: Issue Triage
 on:
   issues:
     types: [opened, typed]
+  workflow_dispatch:
+    inputs:
+      issue_number:
+        description: Issue number to triage
+        required: true
+        type: string
 
 permissions:
   contents: read
@@ -12,7 +18,8 @@ permissions:
 concurrency:
   group: >-
     issue-triage-${{ github.repository }}-${{
-      github.event.issue.type.name == 'Bug' && github.event.issue.number
+      github.event_name == 'workflow_dispatch' && inputs.issue_number
+      || github.event.issue.type.name == 'Bug' && github.event.issue.number
       || github.run_id
     }}
   cancel-in-progress: true
@@ -26,7 +33,11 @@ env:
 jobs:
   team_check:
     runs-on: ubuntu-latest
-    if: ${{ github.event.issue.type.name == 'Bug' }}
+    if: >-
+      ${{
+        github.event_name == 'workflow_dispatch'
+        || github.event.issue.type.name == 'Bug'
+      }}
     outputs:
       is_team_member: ${{ steps.check.outputs.is_team_member }}
       issue_number: ${{ steps.issue.outputs.issue_number }}
@@ -36,14 +47,18 @@ jobs:
         id: issue
         shell: bash
         env:
-          ISSUE_NUMBER_EVENT: ${{ github.event.issue.number }}
+          ISSUE_NUMBER: >-
+            ${{
+              github.event_name == 'workflow_dispatch' && inputs.issue_number
+              || github.event.issue.number
+            }}
         run: |
           set -euo pipefail
 
-          issue_number="${ISSUE_NUMBER_EVENT}"
+          issue_number="${ISSUE_NUMBER}"
 
           if [[ ! "$issue_number" =~ ^[1-9][0-9]*$ ]]; then
-            echo "Could not determine issue number from event payload." >&2
+            echo "Could not determine issue number from event payload or manual input." >&2
             exit 1
           fi
 
@@ -58,6 +73,7 @@ jobs:
           persist-credentials: false
 
       - name: Check issue author team membership
+        if: ${{ github.event_name != 'workflow_dispatch' }}
         id: check
         uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
         env:
@@ -84,7 +100,11 @@ jobs:
   triage:
     runs-on: ubuntu-latest
     needs: team_check
-    if: ${{ needs.team_check.outputs.is_team_member == 'false' }}
+    if: >-
+      ${{
+        github.event_name == 'workflow_dispatch'
+        || needs.team_check.outputs.is_team_member == 'false'
+      }}
     environment: integration
     timeout-minutes: 60
 
@@ -114,7 +134,7 @@ jobs:
           python-version: "3.13"
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           version: "0.11.x"
           enable-cache: true

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

@@ -46,7 +46,7 @@ jobs:
         with:
           path: ~/.cache/prek
           key: prek|${{ matrix.python-version }}|${{ hashFiles('python/.pre-commit-config.yaml') }}
-      - uses: j178/prek-action@0bb87d7f00b0c99306c8bcb8b8beba1eb581c037 # v1
+      - uses: j178/prek-action@bdca6f102f98e2b4c7029491a53dfd366469e33d # v2.0.4
         name: Run Pre-commit Hooks (excluding poe-check)
         env:
           SKIP: poe-check

.github/workflows/python-docs.yml

@@ -26,7 +26,7 @@ jobs:
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       - name: Set up uv
-        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           version-file: "python/pyproject.toml"
           enable-cache: true

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

@@ -13,13 +13,27 @@ on:
   workflow_call:
     inputs:
       checkout-ref:
-        description: "Git ref to checkout (e.g., refs/pull/123/head)"
+        description: "Immutable commit SHA to check out"
         required: true
         type: string
+    secrets:
+      ANTHROPIC_API_KEY:
+        required: true
+      AZURE_CLIENT_ID:
+        required: true
+      AZURE_TENANT_ID:
+        required: true
+      AZURE_SUBSCRIPTION_ID:
+        required: true
+      COPILOT_GITHUB_TOKEN:
+        required: true
+      FOUNDRY_MODELS_API_KEY:
+        required: false
+      OPENAI__APIKEY:
+        required: true
 
 permissions:
   contents: read
-  id-token: write
 
 env:
   UV_CACHE_DIR: /tmp/.uv-cache
@@ -99,6 +113,9 @@ jobs:
   # Azure OpenAI integration tests
   python-tests-azure-openai:
     name: Python Integration Tests - Azure OpenAI
+    permissions:
+      contents: read
+      id-token: write
     runs-on: ubuntu-latest
     environment: integration
     timeout-minutes: 60
@@ -177,7 +194,7 @@ jobs:
         run: curl -fsSL https://ollama.com/install.sh | sh
         working-directory: .
       - name: Cache Ollama models
-        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
         with:
           path: ~/.ollama/models
           key: ollama-models-qwen2.5-1.5b-nomic-embed-text-v1
@@ -224,6 +241,7 @@ jobs:
           packages/hyperlight/tests
           packages/ollama/tests
           packages/core/tests/core/test_mcp.py
+          packages/hosting-mcp/tests
           -m integration
           -n logical --dist worksteal
           --timeout=120 --session-timeout=900 --timeout_method thread
@@ -260,6 +278,9 @@ jobs:
   # Azure Functions + Durable Task integration tests
   python-tests-functions:
     name: Python Integration Tests - Functions
+    permissions:
+      contents: read
+      id-token: write
     runs-on: ubuntu-latest
     environment: integration
     timeout-minutes: 60
@@ -324,6 +345,9 @@ jobs:
   # Foundry integration tests
   python-tests-foundry:
     name: Python Integration Tests - Foundry
+    permissions:
+      contents: read
+      id-token: write
     runs-on: ubuntu-latest
     environment: integration
     timeout-minutes: 60
@@ -378,6 +402,9 @@ jobs:
   # Foundry Hosting integration tests
   python-tests-foundry-hosting:
     name: Python Integration Tests - Foundry Hosting
+    permissions:
+      contents: read
+      id-token: write
     runs-on: ubuntu-latest
     environment: integration
     timeout-minutes: 60
@@ -546,12 +573,12 @@ jobs:
           python-version: ${{ env.UV_PYTHON }}
           os: ${{ runner.os }}
       - name: Download all test results from current run
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           pattern: test-results-*
           path: test-results/
       - name: Restore report history cache
-        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: python/integration-report-history.json
           key: integration-report-history-integration-${{ github.run_id }}
@@ -568,7 +595,7 @@ jobs:
         run: cat integration-test-report.md >> $GITHUB_STEP_SUMMARY
       - name: Save report history cache
         if: always()
-        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: python/integration-report-history.json
           key: integration-report-history-integration-${{ github.run_id }}

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

@@ -25,7 +25,7 @@ jobs:
       pythonChanges: ${{ steps.filter.outputs.python}}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
-      - uses: dorny/paths-filter@d1c1ffe0248fe513906c8e24db8ea791d46f8590 # v3
+      - uses: dorny/paths-filter@7b450fff21473bca461d4b92ce414b9d0420d706 # v4.0.2
         id: filter
         with:
           filters: |
@@ -71,7 +71,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
           os: ${{ runner.os }}
-          exclude-packages: ${{ matrix.python-version == '3.10' && 'agent-framework-github-copilot' || '' }}
+          exclude-packages: ${{ matrix.python-version == '3.10' && 'agent-framework-github-copilot agent-framework-azure-cosmos-memory' || '' }}
         env:
           # Configure a constant location for the uv cache
           UV_CACHE_DIR: /tmp/.uv-cache

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

@@ -43,7 +43,7 @@ jobs:
       githubCopilotChanged: ${{ steps.filter.outputs.github_copilot }}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
-      - uses: dorny/paths-filter@d1c1ffe0248fe513906c8e24db8ea791d46f8590 # v3
+      - uses: dorny/paths-filter@7b450fff21473bca461d4b92ce414b9d0420d706 # v4.0.2
         id: filter
         with:
           filters: |
@@ -71,6 +71,7 @@ jobs:
               - 'python/packages/ollama/**'
               - 'python/packages/core/agent_framework/_mcp.py'
               - 'python/packages/core/tests/core/test_mcp.py'
+              - 'python/packages/hosting-mcp/**'
               - 'python/scripts/local_mcp_streamable_http_server.py'
               - '.github/actions/setup-local-mcp-server/**'
               - '.github/workflows/python-merge-tests.yml'
@@ -298,7 +299,7 @@ jobs:
         run: curl -fsSL https://ollama.com/install.sh | sh
         working-directory: .
       - name: Cache Ollama models
-        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
         with:
           path: ~/.ollama/models
           key: ollama-models-qwen2.5-1.5b-nomic-embed-text-v1
@@ -345,6 +346,7 @@ jobs:
           packages/hyperlight/tests
           packages/ollama/tests
           packages/core/tests/core/test_mcp.py
+          packages/hosting-mcp/tests
           -m integration
           -n logical --dist worksteal
           --timeout=120 --session-timeout=900 --timeout_method thread
@@ -743,12 +745,12 @@ jobs:
           python-version: ${{ env.UV_PYTHON }}
           os: ${{ runner.os }}
       - name: Download all test results from current run
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           pattern: test-results-*
           path: test-results/
       - name: Restore report history cache
-        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: python/integration-report-history.json
           key: integration-report-history-merge-${{ github.run_id }}
@@ -765,7 +767,7 @@ jobs:
         run: cat integration-test-report.md >> $GITHUB_STEP_SUMMARY
       - name: Save report history cache
         if: always()
-        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: python/integration-report-history.json
           key: integration-report-history-merge-${{ github.run_id }}

.github/workflows/python-release.yml

@@ -56,7 +56,7 @@ jobs:
       - name: Build the package
         run: uv run poe --directory packages/${{ env.PACKAGE }} build
       - name: Release
-        uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2
+        uses: softprops/action-gh-release@718ea10b132b3b2eba29c1007bb80653f286566b # v3.0.1
         with:
           files: |
             python/dist/*

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

@@ -693,7 +693,7 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
       - name: Download all validation reports
-        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           pattern: validation-report-*
           path: reports/
@@ -701,7 +701,7 @@ jobs:
 
       - name: Restore validation history
         id: cache-restore
-        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: validation-history/
           key: validation-history-${{ github.run_id }}
@@ -719,7 +719,7 @@ jobs:
         run: cat trend-report.md >> "$GITHUB_STEP_SUMMARY"
 
       - name: Save validation history
-        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: validation-history/
           key: validation-history-${{ github.run_id }}

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

@@ -57,7 +57,7 @@ jobs:
           echo "PR_NUMBER=$ARTIFACT_PR_NUMBER" >> "$GITHUB_ENV"
       - name: Pytest coverage comment
         id: coverageComment
-        uses: MishaKav/pytest-coverage-comment@26f986d2599c288bb62f623d29c2da98609e9cd4 # v1.6.0
+        uses: MishaKav/pytest-coverage-comment@dd5b80bde6d16941f336518e92929e89069d8451 # v1.7.2
         with:
           github-token: ${{ github.token }}
           issue-number: ${{ env.PR_NUMBER }}

.github/workflows/python-tests.yml

@@ -38,7 +38,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
           os: ${{ runner.os }}
-          exclude-packages: ${{ matrix.python-version == '3.10' && 'agent-framework-github-copilot' || '' }}
+          exclude-packages: ${{ matrix.python-version == '3.10' && 'agent-framework-github-copilot agent-framework-azure-cosmos-memory' || '' }}
         env:
           # Configure a constant location for the uv cache
           UV_CACHE_DIR: /tmp/.uv-cache

README.md

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

TRANSPARENCY_FAQ.md

@@ -2,7 +2,7 @@
 
 **What is Microsoft Agent Framework?**
 
-Microsoft Agent Framework is a comprehensive multi-language (C#/.NET and Python) framework for building, orchestrating, and deploying AI agents and multi-agent workflows. The system takes user instructions and conversation inputs and produces intelligent responses through AI agents that can integrate with various LLM providers (OpenAI, Azure OpenAI, Azure AI Foundry). It provides both simple chat agents and complex multi-agent workflows with graph-based orchestration.
+Microsoft Agent Framework is a comprehensive multi-language (C#/.NET and Python) framework for building, orchestrating, and deploying AI agents and multi-agent workflows. The system takes user instructions and conversation inputs and produces intelligent responses through AI agents that can integrate with various LLM providers (OpenAI, Azure OpenAI, Microsoft Foundry). It provides both simple chat agents and complex multi-agent workflows with graph-based orchestration.
 
 **What can Microsoft Agent Framework do?**
 
@@ -12,7 +12,7 @@ The framework offers:
 - **Multi-Agent Orchestration**: Group chat, sequential, concurrent, and handoff patterns
 - **Graph-based Workflows**: Connect agents and deterministic functions using data flows with streaming, checkpointing, time-travel, and Human-in-the-loop
 - **Extensibility Framework**: Extend with native functions, A2A, Model Context Protocol (MCP)
-- **LLM Integration**: Support for OpenAI, Azure OpenAI, Azure AI Foundry, and other providers
+- **LLM Integration**: Support for OpenAI, Azure OpenAI, Microsoft Foundry, and other providers
 - **Runtime Support**: Both in-process and distributed agent execution
 
 **What is/are Microsoft Agent Framework's intended use(s)?**

docs/decisions/0001-agent-run-response.md

@@ -2,7 +2,7 @@
 # These are optional elements. Feel free to remove any of them.
 status: accepted
 contact: westey-m
-date: 2025-07-10 {YYYY-MM-DD when the decision was last updated}
+date: 2025-07-10
 deciders: sergeymenshykh, markwallace, rbarreto, dmytrostruk, westey-m, eavanvalkenburg, stephentoub
 consulted:
 informed:
@@ -139,7 +139,7 @@ Therefore something like `AgentResponse.Text` which also aggregates all `TextCon
 
 #### Option 1.2 Presence of Secondary Content is determined by a runtime parameter
 
-We can allow callers to choose whether to include secondary content in the list of reponse messages.
+We can allow callers to choose whether to include secondary content in the list of response messages.
 Open Question: Do we allow secondary content to use `TextContent` types?
 
 ```csharp

docs/decisions/0002-agent-tools.md

@@ -113,7 +113,7 @@ Implement a hybrid strategy where common tools use generic `AITool`-derived abst
 
 ### AI Agent Tool Types Availability
 
-Tool Type | Azure AI Foundry Agent Service | OpenAI Assistant API | OpenAI ChatCompletion API | OpenAI Responses API | Amazon Bedrock Agents | Google | Anthropic | Description
+Tool Type | Microsoft Foundry Agent Service | OpenAI Assistant API | OpenAI ChatCompletion API | OpenAI Responses API | Amazon Bedrock Agents | Google | Anthropic | Description
 -- | -- | -- | -- | -- | -- | -- | -- | --
 Function Calling | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | Enables custom, stateless functions to define specific agent behaviors.
 Code Interpreter | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | Allows agents to execute code for tasks like data analysis or problem-solving.
@@ -132,7 +132,7 @@ Image Generation | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | Generates or edits
 
 #### Function Calling
 <details>
-  <summary>Azure AI Foundry Agent Service</summary>
+  <summary>Microsoft Foundry Agent Service</summary>
   Source: <a href="https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/function-calling?pivots=rest">https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/function-calling?pivots=rest</a>
 
   Message Request:
@@ -401,7 +401,7 @@ Image Generation | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | Generates or edits
 
 #### Code Interpreter
 <details>
-  <summary>Azure AI Foundry Agent Service</summary>
+  <summary>Microsoft Foundry Agent Service</summary>
   <p>Source: <a href="https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/code-interpreter-samples?pivots=rest-api">https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/code-interpreter-samples?pivots=rest-api</a></p>
 
   <p>.NET Support: ✅</p>
@@ -709,7 +709,7 @@ Image Generation | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | Generates or edits
 
 #### Search and Retrieval
 <details>
-  <summary>Azure AI Foundry Agent Service</summary>
+  <summary>Microsoft Foundry Agent Service</summary>
   Source: <a href="https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/file-search-upload-files?pivots=rest">https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/file-search-upload-files?pivots=rest</a>
 
   File Search Request:
@@ -1083,7 +1083,7 @@ Image Generation | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | Generates or edits
 
 #### Web Search
 <details>
-  <summary>Azure AI Foundry Agent Service</summary>
+  <summary>Microsoft Foundry Agent Service</summary>
   Source: <a href="https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/bing-code-samples?pivots=rest">https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/bing-code-samples?pivots=rest</a>
 
   Bing Search Message Request:
@@ -1630,7 +1630,7 @@ Image Generation | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | Generates or edits
 
 #### OpenAPI Spec Tool
 <details>
-  <summary>Azure AI Foundry Agent Service</summary>
+  <summary>Microsoft Foundry Agent Service</summary>
   Source: <a href="https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/openapi-spec-samples?pivots=rest-api">https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/openapi-spec-samples?pivots=rest-api</a><br>
   Source: <a href="https://learn.microsoft.com/en-us/rest/api/aifoundry/aiagents/run-steps/get-run-step?view=rest-aifoundry-aiagents-v1&tabs=HTTP#runstepopenapitoolcall">https://learn.microsoft.com/en-us/rest/api/aifoundry/aiagents/run-steps/get-run-step?view=rest-aifoundry-aiagents-v1&tabs=HTTP#runstepopenapitoolcall</a>
 
@@ -1712,7 +1712,7 @@ Image Generation | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | Generates or edits
 
 #### Stateful Functions
 <details>
-  <summary>Azure AI Foundry Agent Service</summary>
+  <summary>Microsoft Foundry Agent Service</summary>
   Source: <a href="https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/azure-functions-samples?pivots=rest">https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/azure-functions-samples?pivots=rest</a>
 
   Message Request:
@@ -1832,7 +1832,7 @@ Image Generation | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | Generates or edits
 
 #### Microsoft Fabric
 <details>
-  <summary>Azure AI Foundry Agent Service</summary>
+  <summary>Microsoft Foundry Agent Service</summary>
   Source: <a href="https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/fabric?pivots=rest">https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/fabric?pivots=rest</a>
 
   Message Request:

docs/decisions/0006-userapproval.md

@@ -2,7 +2,7 @@
 # These are optional elements. Feel free to remove any of them.
 status: accepted
 contact: westey-m
-date: 2025-09-12 {YYYY-MM-DD when the decision was last updated}
+date: 2025-09-12
 deciders: sergeymenshykh, markwallace-microsoft, rogerbarreto, dmytrostruk, westey-m, eavanvalkenburg, stephentoub, peterychang
 consulted: 
 informed: 
@@ -25,7 +25,7 @@ See various features that would need to be supported via this type of mechanism,
 - Also see [the openai human-in-the-loop guide](https://openai.github.io/openai-agents-js/guides/human-in-the-loop/#approval-requests).
 - Also see [the openai MCP guide](https://openai.github.io/openai-agents-js/guides/mcp/#optional-approval-flow).
 - Also see [MCP Approval Requests from OpenAI](https://platform.openai.com/docs/guides/tools-remote-mcp#approvals).
-- Also see [Azure AI Foundry MCP Approvals](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/model-context-protocol-samples?pivots=rest#submit-your-approval).
+- Also see [Microsoft Foundry MCP Approvals](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/model-context-protocol-samples?pivots=rest#submit-your-approval).
 - Also see [MCP Elicitation requests](https://modelcontextprotocol.io/specification/draft/client/elicitation)
 
 ## Decision Drivers

docs/decisions/0009-support-long-running-operations.md

@@ -57,7 +57,7 @@ This section describes different options for various aspects required to add lon
 
 ### 1. Methods for Working with Long-Running Operations
 
-Based on the analysis of existing APIs that support long-running operations (such as OpenAI Responses, Azure AI Foundry Agents, and A2A), 
+Based on the analysis of existing APIs that support long-running operations (such as OpenAI Responses, Microsoft Foundry Agents, and A2A),
 the following operations are used for working with long-running operations:
 - Common operations:
   - **Start Long-Running Execution**: Initiates a long-running operation and returns its Id.
@@ -757,7 +757,7 @@ Some of them natively support resuming streaming from a specific point in the st
 | API                     | Can Resume Streaming                 | Model                                                                                                      |
 |-------------------------|--------------------------------------|------------------------------------------------------------------------------------------------------------|
 | OpenAI Responses        | Yes                                  | StreamingResponseUpdate.**SequenceNumber** + GetResponseStreamingAsync(responseId, **startingAfter**, ct)  |
-| Azure AI Foundry Agents | Emulated<sup>2</sup>                 | RunStep.**Id** + custom pseudo code: client.Runs.GetRunStepsAsync(...).AllStepsAfter(**stepId**)           |
+| Microsoft Foundry Agents | Emulated<sup>2</sup>                 | RunStep.**Id** + custom pseudo code: client.Runs.GetRunStepsAsync(...).AllStepsAfter(**stepId**)           |
 | A2A                     | Implementation dependent<sup>1</sup> |          																				                  |
 
 <sup>1</sup> The [A2A specification](https://github.com/a2aproject/A2A/blob/main/docs/topics/streaming-and-async.md#1-streaming-with-server-sent-events-sse)
@@ -765,7 +765,7 @@ allows an A2A agent implementation to decide how to handle streaming resumption:
 a task is still active (and the server hasn't sent a final: true event for that phase), the client can attempt to reconnect to the stream using the tasks/resubscribe RPC method. 
 The server's behavior regarding missed events during the disconnection period (e.g., whether it backfills or only sends new updates) is implementation-dependent._
 
-<sup>2</sup> The Azure AI Foundry Agents API has an API to start a streaming run but does not have an API to resume streaming from a specific point in the stream.
+<sup>2</sup> The Microsoft Foundry Agents API has an API to start a streaming run but does not have an API to resume streaming from a specific point in the stream.
 However, it has non-streaming APIs to access already started runs, which can be used to emulate streaming resumption by accessing a run and its steps and streaming all the steps after a specific step.
 
 #### Required Changes
@@ -828,7 +828,7 @@ Sequence of updates from OpenAI Responses API to answer the question "What time
 | resp_2 | 10 | resp.output_item.done    | -               | InProgress                |                                                   |
 | resp_2 | 11 | resp.completed           | Completed       | Completed                 |                                                   |
 
-Sequence of updates from Azure AI Foundry Agents API to answer the question "What time is it?" using a function call:
+Sequence of updates from Microsoft Foundry Agents API to answer the question "What time is it?" using a function call:
 | Id     | SN      | UpdateKind        | Run.Status     | Step.Status | Message.Status  | ChatResponseUpdate.Status | Description                                       |
 |--------|---------|-------------------|----------------|-------------|-----------------|---------------------------|---------------------------------------------------|
 | run_1  | -       | RunCreated        | Queued         | -           | -               | Queued                    |                                                   |
@@ -852,7 +852,7 @@ Sequence of updates from Azure AI Foundry Agents API to answer the question "Wha
 
 To support long-running operations, the following values need to be returned by the GetResponseAsync and GetStreamingResponseAsync methods:
 - `ResponseId` - identifier of the long-running operation or an entity representing it, such as a task.
-- `ConversationId` - identifier of the conversation or thread the long-running operation is part of. Some APIs, like Azure AI Foundry Agents, use 
+- `ConversationId` - identifier of the conversation or thread the long-running operation is part of. Some APIs, like Microsoft Foundry Agents, use
   this identifier together with the ResponseId to identify a run.
 - `SequenceNumber` - identifier of an update within a stream of updates. This is required to support streaming resumption by the GetStreamingResponseAsync method only.
 - `Status` - status of the long-running operation: whether it is queued, running, failed, cancelled, completed, etc.
@@ -1089,7 +1089,7 @@ public class ChatOptions
 
 ##### 6.1.5 Continuation Token of a Custom Type
 
-The option is similar the the "6.1.3 Continuation Token of System.ClientModel.ContinuationToken Type" option but suggests using a 
+The option is similar to the "6.1.3 Continuation Token of System.ClientModel.ContinuationToken Type" option but suggests using a 
 custom type for the continuation token instead of the `System.ClientModel.ContinuationToken` type.
 
 **Pros**
@@ -1203,7 +1203,7 @@ response = await agent.CancelRunAsync(response.ResponseId, new AgentCancelRunOpt
 In case an agent supports either or both cancellation and deletion of long-running operations, it will override the corresponding methods.
 Otherwise, it won't override them, and the base implementations will return null by default.
 
-Some agents, for example Azure AI Foundry Agents, require the thread identifier to cancel a run. To accommodate this requirement, the `CancelRunAsync` method
+Some agents, for example Microsoft Foundry Agents, require the thread identifier to cancel a run. To accommodate this requirement, the `CancelRunAsync` method
 accepts an optional `AgentCancelRunOptions` parameter that allows callers to specify the thread associated with the run they want to cancel.
 
 ```csharp
@@ -1574,7 +1574,7 @@ the thread is provided with background operations consistently for all runs.
 </details>
 
 <details>
-<summary>Azure AI Foundry Agents</summary>
+<summary>Microsoft Foundry Agents</summary>
 
 - Create a thread and run the agent against it and wait for it to complete using polling:
     ```csharp

docs/decisions/0021-provider-leading-clients.md

@@ -34,11 +34,11 @@ Key changes:
 1. **New `agent-framework-openai` package** with dependencies on `agent-framework-core`, `openai`, and `packaging` only.
 2. **Class renames**: `OpenAIResponsesClient` → `OpenAIChatClient` (Responses API), `OpenAIChatClient` → `OpenAIChatCompletionClient` (Chat Completions API). Old names remain as deprecated aliases.
 3. **Deprecated classes**: `OpenAIAssistantsClient`, all `AzureOpenAI*Client` classes, `AzureAIClient`, `AzureAIAgentClient`, and `AzureAIProjectAgentProvider` are marked deprecated.
-4. **New `FoundryChatClient`** in azure-ai for Azure AI Foundry Responses API access, built on `RawFoundryChatClient(RawOpenAIChatClient)`.
+4. **New `FoundryChatClient`** in azure-ai for Microsoft Foundry Responses API access, built on `RawFoundryChatClient(RawOpenAIChatClient)`.
 5. **All deprecated `AzureOpenAI*` classes** consolidated into a single file (`_deprecated_azure_openai.py`) in the azure-ai package for clean future deletion.
 6. **Core's `agent_framework.openai` and `agent_framework.azure` namespaces** become lazy-loading gateways, preserving backward-compatible import paths while removing hard dependencies.
 7. **Unified `model` parameter** replaces `model_id` (OpenAI), `deployment_name` (Azure OpenAI), and `model_deployment_name` (Azure AI) across all client constructors. The term `model` is intentionally generic: it naturally maps to an OpenAI model name *and* to an Azure OpenAI deployment name, making it straightforward to use `OpenAIChatClient` with either OpenAI or Azure OpenAI backends (via `AsyncAzureOpenAI`). Environment variables are similarly unified (e.g., `OPENAI_MODEL` instead of separate `OPENAI_CHAT_MODEL_ID` / `OPENAI_CHAT_COMPLETION_MODEL_ID`).
-8. **`FoundryAgent`** replaces the pattern of `Agent(client=AzureAIClient(...))` for connecting to pre-configured agents in Azure AI Foundry (PromptAgents and HostedAgents). The underlying `RawFoundryAgentChatClient` is an implementation detail — most users interact only with `FoundryAgent`. `AzureAIAgentClient` is separately deprecated as it refers to the V1 Agents Service API. See below for design rationale.
+8. **`FoundryAgent`** replaces the pattern of `Agent(client=AzureAIClient(...))` for connecting to pre-configured agents in Microsoft Foundry (PromptAgents and HostedAgents). The underlying `RawFoundryAgentChatClient` is an implementation detail — most users interact only with `FoundryAgent`. `AzureAIAgentClient` is separately deprecated as it refers to the V1 Agents Service API. See below for design rationale.
 
 ### Foundry Agent Design: `FoundryAgentClient` vs `FoundryAgent`
 

docs/decisions/0023-foundry-evals-integration.md

@@ -7,11 +7,11 @@ consulted: Pratyush Mishra, Shivam Shrivastava, Manni Arora (Centrica eval scena
 informed: Agent Framework team, Foundry Evals team
 ---
 
-# Agent Evaluation Architecture with Azure AI Foundry Integration
+# Agent Evaluation Architecture with Microsoft Foundry Integration
 
 ## Context and Problem Statement
 
-Azure AI Foundry provides a rich evaluation service for AI agents — built-in evaluators for agent behavior (task adherence, intent resolution), tool usage (tool call accuracy, tool selection), quality (coherence, fluency, relevance), and safety (violence, self-harm, prohibited actions). Results are viewable in the Foundry portal with dashboards and comparison views.
+Microsoft Foundry provides a rich evaluation service for AI agents — built-in evaluators for agent behavior (task adherence, intent resolution), tool usage (tool call accuracy, tool selection), quality (coherence, fluency, relevance), and safety (violence, self-harm, prohibited actions). Results are viewable in the Foundry portal with dashboards and comparison views.
 
 However, using Foundry Evals with an agent-framework agent today requires significant manual effort. Developers must:
 
@@ -445,7 +445,7 @@ These factorings produce different scores for the same conversation. The framewo
 
 ### Azure AI: FoundryEvals
 
-`Evaluator` implementation backed by Azure AI Foundry:
+`Evaluator` implementation backed by Microsoft Foundry:
 
 ```python
 class FoundryEvals:
@@ -812,4 +812,4 @@ public sealed class EvalItem
 
 ## More Information
 
-- [Foundry Evals documentation](https://learn.microsoft.com/azure/ai-foundry/concepts/evaluation-approach-gen-ai) — Azure AI Foundry evaluation overview
+- [Foundry Evals documentation](https://learn.microsoft.com/azure/ai-foundry/concepts/evaluation-approach-gen-ai) — Microsoft Foundry evaluation overview

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

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

docs/decisions/0025-foundry-toolbox-support.md

@@ -9,7 +9,7 @@ deciders: evmattso
 
 ## What is the goal of this feature?
 
-Enable Agent Framework users to consume Foundry **toolboxes** — named, versioned bundles of tool definitions stored server-side in an Azure AI Foundry project — directly from `FoundryChatClient`, without dropping to the raw `azure-ai-projects` SDK.
+Enable Agent Framework users to consume Foundry **toolboxes** — named, versioned bundles of tool definitions stored server-side in a Microsoft Foundry project — directly from `FoundryChatClient`, without dropping to the raw `azure-ai-projects` SDK.
 
 A user who has configured a toolbox in the Foundry portal (or via the raw SDK) should be able to load it into an agent with a single call:
 

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

@@ -1,7 +1,7 @@
 ---
-status: accepted
+status: superseded by [ADR-0030](0030-hosted-platform-context-agentserver-2.0.md)
 contact: rogerbarreto
-date: 2026-05-07
+date: 2026-06-29
 deciders: rogerbarreto
 consulted: []
 informed: []
@@ -9,6 +9,8 @@ informed: []
 
 # Hosted session identity context for Foundry Hosting
 
+> **Superseded by [ADR-0030](0030-hosted-platform-context-agentserver-2.0.md).** `Azure.AI.AgentServer.*` 2.0.0 (responses protocol `2.0.0`) replaced `ResponseContext.Isolation` (`UserIsolationKey` / `ChatIsolationKey`, headers `x-agent-user-isolation-key` / `x-agent-chat-isolation-key`) with `ResponseContext.PlatformContext` (`UserIdKey` / `CallId`, headers `x-agent-user-id` / `x-agent-foundry-call-id`). The chat isolation key was removed and `HostedSessionContext` is now user-only. This ADR is retained as the historical record of the original design.
+
 ## Context and Problem Statement
 
 Server-hosted Foundry agents need a way to scope per-user state (most notably `FoundryMemoryProvider` memories) by the end user that initiated the request. The Foundry platform already injects `x-agent-user-isolation-key` and `x-agent-chat-isolation-key` headers on every Responses request, but the agent-framework hosting layer did not surface those values to `AIContextProvider` instances. The provider's `stateInitializer` only received an `AgentSession?` with no identity attached, so per-user scoping was impossible without out-of-band plumbing.

docs/decisions/0027-hosting-channels.md

@@ -1,144 +1,524 @@
 ---
 status: accepted
 contact: eavanvalkenburg
-date: 2026-06-11
+date: 2026-06-30
 deciders: eavanvalkenburg
+consulted: rogerbarreto, moonbox3
 ---
 
-# Python minimal hosting core and pluggable channels
+# Python protocol helpers and optional execution state
 
 ## Context and Problem Statement
 
-Agent Framework has several protocol-specific hosting surfaces. App authors who want one agent or workflow on multiple protocols must compose servers, routes, middleware, session handling, and lifecycle code by hand.
+Agent Framework needs to help applications expose agents and workflows over external protocols such as OpenAI
+Responses, Telegram, Activity Protocol, and future transports.
 
-We will introduce a small Python hosting core that owns the common server shape and leaves protocol details inside channel packages. The first public contract must be intentionally narrow so Python can ship a base contract before adding identity linking, proactive delivery, or multicast behavior. Other language implementations may reuse the same conceptual boundary, but this ADR records the Python decision.
+FastAPI, Starlette, Azure Functions, Django, Telegram SDKs, Bot Framework SDKs, and other app frameworks already own
+route registration, dependency injection, middleware, authentication, background tasks, lifecycle, and native client
+calls. Agent Framework should not duplicate those surfaces unless a specific hosting environment requires it.
 
 ## Decision Drivers
 
-- Keep the first host easy to explain: one app, one hostable target, one or more channels.
-- Reuse Agent Framework's existing agent, workflow, session, history, and checkpoint primitives.
-- Let channel packages own protocol parsing, protocol responses, authentication details, and native command surfaces.
-- Make session continuity explicit through a channel-supplied `ChannelSession(isolation_key=...)`.
-- Avoid approving cross-channel identity and delivery semantics before their safety model is reviewed.
+- Keep the released surface small enough to explain without first teaching a channel framework.
+- Provide reusable Agent Framework run translation that works with FastAPI, Django, and other web frameworks.
+- Let app/framework code own route declaration, auth, middleware, native SDK clients, command handling, and background
+  work.
+- Keep stateful execution support explicit: session lookup/storage and workflow checkpoint lookup/storage may still need
+  a small AF-owned home.
 
 ## Considered Options
 
-1. Keep only protocol-specific hosts.
-2. Ship a large hosting core with identity linking, authorization, background delivery, active-channel routing, and multicast in v1.
-3. Ship a minimal host/channel core now and track linking/multicast as follow-up work.
+1. Create protocol-specific hosts.
+2. Ship a full host/channel framework with route contribution and channel hooks.
+3. Ship protocol conversion helpers plus optional execution state.
 
-### Keep only protocol-specific hosts
+### 1. Create protocol-specific hosts
 
-- Good: no new abstraction or package surface.
-- Neutral: each protocol can continue evolving independently.
-- Bad: every multi-channel app still has to compose servers, lifecycle, and session handling by hand.
+- Good: no new shared abstraction.
+- Neutral: each protocol host can evolve independently.
+- Bad: every package reinvents AF input/result mapping, session-key conventions, and stateful execution helpers.
 
-### Ship the large cross-channel host in v1
+### 2. Ship a full host/channel framework
 
-- Good: the richest cross-channel scenarios are available immediately.
-- Neutral: the host becomes the natural place to demonstrate identity and delivery policy.
-- Bad: v1 becomes a security-sensitive identity and delivery system before the safety model is reviewed.
+- Good: one object can assemble routes, channels, session handling, hooks, and lifecycle callbacks.
+- Good: app code using the supported host shape can be short.
+- Bad: the framework owns concerns already handled by web frameworks, protocol SDKs and/or other services.
+- Bad: users must understand `Channel`, contribution, hook, and host-dispatch concepts before they can see how a request
+  becomes `agent.run(...)`.
+- Bad: the abstraction is hard to reuse outside the chosen web framework.
 
-### Ship the minimal core now
+### 3. Ship protocol helpers plus optional execution state
 
-- Good: the host/channel boundary can be implemented, tested, and explained without solving linking and durable delivery at the same time.
-- Neutral: apps that need richer behavior must build it locally or wait for ADR-0028 follow-up work.
-- Bad: proactive delivery and multicast scenarios are deliberately absent from v1.
+- Good: protocol packages provide the Agent Framework run value directly: `<protocol>_to_run(...)` and
+  `<protocol>_from_run(...)` style helpers.
+- Good: apps keep native FastAPI, Starlette, Azure Functions, Django, Bot Framework, or Telegram SDK code.
+- Good: helper functions can be tested without a web framework app or host pipeline.
+- Good: small state objects can still own target-coupled state: `AgentState` pairs an agent target with a `SessionStore`,
+  and `WorkflowState` resolves a workflow target while reusing the existing `CheckpointStorage` abstraction.
+- Good: provides maximum configurability in handling input and outputs (outside of the conversions)
+- Bad: building a first iteration of a new Host is more verbose.
+- Bad: samples show more explicit route/client code than a fully assembled channel host.
 
 ## Decision Outcome
 
-Chosen option: **minimal host/channel core now, follow-up enhancements later**.
+Chosen option: **3. Ship protocol helpers plus optional execution state**.
 
-`AgentFrameworkHost` owns:
+Protocol packages own:
 
-- one application object,
-- one hostable target (`SupportsAgentRun` agent-compatible object or a `Workflow`), and
-- one or more channels.
+- parsing protocol-native input into Agent Framework run input and options;
+- rendering `AgentResponse`, `AgentResponseUpdate`, workflow results, or workflow updates back into protocol-native
+  response/event payloads;
+- protocol-specific isolation/session id helper functions when useful, such as `telegram_session_id(update)`;
+- protocol-specific typing/update event helpers where the protocol has a native concept.
 
-Channels own:
+Application or web-framework code owns:
 
-- contributed routes, middleware, commands, and lifecycle callbacks,
-- protocol-native request parsing into `ChannelRequest`,
-- protocol-native rendering of the originating response, and
-- any channel-specific authentication or signature validation.
+- HTTP route declaration and route grouping;
+- dependency injection;
+- authentication and authorization;
+- middleware;
+- background tasks and webhook acknowledgement policy;
+- native protocol SDK clients and outbound calls;
+- command registration and command dispatch;
+- request/response status codes and framework-specific error handling;
+- choosing the isolation/session id source for the current deployment and route.
 
-The host owns:
+The application builder can make the server exactly as they see fit, but this is outside the responsibilities of this proposed scheme.
+This might include implementing other known API surfaces from vendors like OpenAI, such as creating conversations, vector stores, deleting things, etc.
+If they want they can build the full OpenAI API, but it will include code that does not rely on agent-framework-hosting, which is fine.
+They are responsible for what they expose.
 
-- route/lifecycle aggregation,
-- invocation of the target,
-- `ChannelSession(isolation_key=...)` to `AgentSession` resolution and caching,
-- `reset_session(isolation_key=...)`,
-- host-level middleware, including Foundry isolation middleware only when the Foundry hosting environment flag is present,
-- invocation of per-channel hooks (`ChannelRunHook`, `ChannelResponseHook`, `ChannelStreamUpdateHook`), and
-- workflow checkpoint wiring through an explicit `checkpoint_location`.
+The optional execution-state helpers, if provided, are limited to shared execution state:
 
-`ChannelIdentity`, when present, is request metadata only. In v1 it is not a linking, authorization, or delivery key.
+- `AgentState`: one `SupportsAgentRun`-compatible target plus a `SessionStore`;
+- `WorkflowState`: one `Workflow`, `WorkflowBuilder`-shaped builder, orchestration builder, or workflow factory;
+- `SessionStore`: plain async storage (`get` / `set` / `delete`) by an app-selected id.
 
-### Trust boundary for `isolation_key`
+The store does not create sessions. `AgentState` provides the target-aware `get_or_create_session(...)` helper because
+only the state object has both the store and the resolved agent target. Workflow checkpointing should use the existing
+`CheckpointStorage` abstraction directly; app/state code may keep a small cursor (`session_id -> checkpoint_id`) when it
+needs to resume a workflow for a session.
 
-The host treats `ChannelSession.isolation_key` as a session partition key, not as proof of identity. Channels or host middleware must authenticate and authorize any externally supplied value before passing it to the host. For example, a Responses caller must not be allowed to choose an arbitrary `previous_response_id` or header-derived key unless the platform or middleware has already established that the caller owns that conversation. The host deliberately does not infer that trust from the string itself.
+These objects are **not** app objects, channel registries, or route owners. They do not own FastAPI/Starlette setup,
+route contribution, protocol dispatch, command projection, or native SDK calls.
 
-### Hook ownership
+### Helper naming and families
 
-Channels provide hook configuration and protocol-native context. The host invokes those hooks as part of the common invocation pipeline:
+Helpers should be protocol-specific, not generic. Avoid a generic `protocol_to_run(...)` name in public samples because it
+hides the protocol-specific contract behind a second abstraction.
 
-- `ChannelRunHook` runs after channel parsing and before target invocation.
-- `ChannelResponseHook` runs after target invocation and before the originating channel serializes its response.
-- `ChannelStreamUpdateHook` is applied by the host while the channel consumes streamed updates because streaming serialization is protocol-specific.
+Protocol packages should consider these helper families. This table is a set of examples, not a required protocol or
+checklist. Not every protocol needs every helper, but when a protocol has the concept the naming should stay consistent:
 
-`ChannelStreamUpdateHook` is an update hook, not a final-response sanitizer. Channels that use it for redaction or filtering must also apply equivalent policy to any final response they render. Channels choose whether the response is streaming before run hooks execute.
+| Helper family | Shape | Purpose |
+| --- | --- | --- |
+| Run conversion | `<protocol>_to_run(...)` | Convert one protocol-native call/update/request into `Agent.run` or `Workflow.run` values. |
+| Final rendering | `<protocol>_from_run(...)` | Convert a final `AgentResponse` / workflow result into protocol-native response payloads or operations. |
+| Stream rendering | `<protocol>_from_streaming_run(...)` | Convert `ResponseStream` / workflow updates into protocol-native events or operations. |
+| Session id extraction | `<protocol>_session_id(...)` | Extract the protocol's natural continuation/partition key from the call, if present. |
+| Command/action parsing | `<protocol>_command(...)` | Parse a protocol-native command/action/operation name without deciding app policy. |
 
-This keeps hook call conventions centralized while leaving protocol payload parsing and response formatting in channel packages.
+Examples:
 
-### State owned by v1
+- `responses_to_run(...)`, `responses_from_run(...)`, `responses_from_streaming_run(...)`,
+  `responses_session_id(...)`;
+- `telegram_to_run(...)`, `telegram_from_run(...)`, `telegram_from_streaming_run(...)`,
+  `telegram_session_id(...)`, `telegram_command(...)`;
+- `activity_to_run(...)`, `activity_from_run(...)`, `activity_session_id(...)`, `activity_command(...)`;
+- `discord_to_run(...)`, `discord_from_run(...)`, `discord_session_id(...)`, `discord_command(...)`.
 
-`state_dir` is limited to host-owned local files for reset-session aliases and workflow checkpoint path derivation. It does not store linked identities, active-channel state, response-routing state, continuation records, durable runner queues, or delivery attempts. Those storage concerns belong to ADR-0028.
+The app still owns what a parsed command means. For example, a Telegram `/new`, Discord slash command, Bot Framework
+command activity, or A2A cancellation/request action may parse through a command/action helper, but the route or SDK
+handler decides whether that command clears a session, cancels a task, calls an agent, or is ignored.
+
+Additional helper functions can be protocol-specific when the concept is not broadly shared. Examples include
+`telegram_chat_id(...)`, `telegram_callback_query_id(...)`, `telegram_media_file_id(...)`,
+`discord_interaction_id(...)`, `a2a_task_id(...)`, `a2a_context_id(...)`, and MCP tool/prompt/resource helpers. These
+helpers should still stay side-effect-free: they extract, normalize, or describe protocol data, while app/native SDK code
+performs acknowledgements, sends/edits messages, resolves protected file URLs, applies rate limits, and registers
+handlers.
+
+### Security responsibilities for application builders
+
+The application builder owns the trust boundary. Protocol helper packages can parse native payloads and expose candidate
+ids or operations, but they do not authenticate callers, authorize access to state, or decide which side effects are
+allowed.
+
+Application code that uses these helpers are responsible for (this means that we advice you to think through these topics,
+but ultimately, the choice of which controls are needed for the intended use case is up to the application builder):
+
+- authenticate the caller through the app's normal mechanism before using protocol-provided ids;
+- authorize any caller-supplied session, checkpoint, task, context, conversation, thread, or response id before loading
+  state for it;
+- bind externally supplied ids to the authenticated user, tenant, workspace, installation, or chat context before using
+  them as `SessionStore` keys or checkpoint cursor keys;
+- treat `<protocol>_session_id(...)` results as untrusted candidate keys until that ownership check has passed;
+- keep platform-provided isolation helpers fail-closed outside their trusted hosting environment;
+- authorize command/action effects such as reset, cancel, approve, submit, or tool invocation after parsing them;
+- opt in explicitly before resolving protected media/resource/file URLs and passing them to a remote model provider;
+- persist post-run session or checkpoint state only after `agent.run(...)`, `workflow.run(...)`, or stream finalization has
+  updated that state.
+
+For Foundry specifically, helpers may read values established by Foundry hosting middleware, but must not treat raw
+request headers as trusted Foundry isolation when the app is running outside Foundry. Implementations must test that
+non-Foundry requests do not accept spoofable isolation headers as platform-provided keys.
+
+For workflow checkpointing, the checkpoint boundary must be at least as specific as the authorized session/tenant
+boundary. A shared storage lookup such as "latest checkpoint for workflow name" is safe only when the storage is already
+scoped to the authorized session. In a shared durable store, map the authorized `session_id` to a checkpoint id or other
+cursor and load that specific checkpoint.
+
+### Session continuity
+
+Session continuity remains explicit. Run parsing and isolation/session id selection are separate operations because
+isolation can come from more than one source:
+
+- protocol input, such as OpenAI Responses `previous_response_id`, a Telegram chat id, or an Activity conversation id;
+- running environment, such as Foundry Hosted Agents user/chat isolation context;
+- app-specific trusted middleware or route state.
+
+The app chooses which helper to call for that route and deployment. For example:
+
+- `responses_session_id(body)` from `agent-framework-hosting-responses`, which can return either a `resp_*` previous
+  response id or a `conv_*` conversation id when present;
+- `telegram_session_id(update, bot_id=...)` from `agent-framework-hosting-telegram`, which uses the bot and sender for
+  private chats and the bot and chat for shared group sessions;
+- `activity_session_id(activity)`, `discord_session_id(interaction_or_message)`, or
+  `a2a_session_id(request_context)` from their respective protocol packages;
+- `foundry_user_isolation_key()` or `foundry_chat_isolation_key()` from `agent-framework-foundry-hosting`.
+
+Keep these helpers outside `responses_to_run(...)`, `telegram_to_run(...)`, and other run-input parsers. That makes the
+trust boundary visible: using a request-derived key is a different decision than using a platform-provided isolation key.
+
+The application builder is also responsible for deciding whether the hosting environment is **persistent** (for example,
+a long-running container or web app) or **transient** (for example, Azure Functions, Foundry Hosted Agents, or any
+environment where process memory is not a reliable continuity boundary). That decision controls which state mechanisms are
+safe to use:
+
+- persistent single-process apps may use in-memory state for local development or simple deployments, while still needing
+  durable state for multi-replica continuity;
+- transient apps must not rely on in-memory `SessionStore` state between calls and need a durable session store or a
+  service-owned continuation id;
+- workflow hosts must choose an explicit `CheckpointStorage` and, when they need per-session resume, a durable
+  `session_id -> checkpoint_id` cursor because in-process workflow state and in-memory checkpoint cursors do not survive
+  transient execution.
+
+A `SessionStore` stores `session_id -> AgentSession`, but it does not create sessions. `AgentState` resolves the agent
+target and creates the session on first use. Reads return independent working copies so running from one continuation
+point does not mutate the stored snapshot or another simultaneous branch:
+
+For agent targets:
+
+```python
+session = await state.get_or_create_session(session_id)
+target = await state.get_target()
+result = await target.run(messages, session=session, options=options)
+```
+
+If the protocol mints a new continuation id as part of the response being created (for example, OpenAI Responses
+`resp_*` ids), store the **post-run** session explicitly under that new id:
+
+```python
+session = await state.get_or_create_session(previous_response_id)
+target = await state.get_target()
+result = await target.run(messages, session=session, options=options)
+await state.set_session(response_id, session)
+```
+
+`agent.run(...)` may update the session object (for example, with service continuation state), so the explicit store call
+belongs after the run, not before it.
+
+Response ids are immutable continuation points, so simultaneous callers can branch from one `previous_response_id` and
+store their completed sessions under different new response ids. A stable `conversation_id` is a mutable head: the app
+must explicitly update it after the run and provide single-writer coordination. The hosting state helper does not lock
+an entire run or resolve concurrent updates to that stable key.
+
+The session id is a partition key, not proof of identity. App or platform code must authenticate and authorize any
+externally supplied key before using it.
+
+### Workflow checkpoints
+
+Workflow checkpointing is execution state, not protocol state. `WorkflowState` pairs a workflow target with checkpoint
+state, but it should not wrap or replace the existing `CheckpointStorage` abstraction. Apps should pass the actual
+`CheckpointStorage` they want the workflow to use. If an app needs per-session resume, it can keep a small cursor from
+authorized `session_id` to `checkpoint_id` (or an equivalent store-specific resume token).
+
+Workflow runs do not currently emit a checkpoint id on `WorkflowRunResult` or normal workflow events by default. The
+runner receives checkpoint ids internally from `CheckpointStorage.save(...)`. App/state code that owns the storage can
+observe the latest id by querying the storage after a run, for example
+`await storage.get_latest(workflow_name=target.name)`.
+
+For workflow targets, app code adapts the protocol helper output into the workflow's expected input and invokes the
+workflow through the state object's target:
+
+```python
+# session_id must already be authenticated and authorized for this caller
+target = await state.get_target()
+result = await target.run(message=workflow_input, checkpoint_storage=checkpoint_storage)
+latest = await checkpoint_storage.get_latest(workflow_name=target.name)
+if latest is not None:
+    await checkpoint_cursor_store.set(session_id, latest.checkpoint_id)
+```
+
+If a route wants to resume from a prior checkpoint, it explicitly chooses the checkpoint and passes it to
+`workflow.run(...)`:
+
+```python
+# session_id must already be authenticated and authorized for this caller
+target = await state.get_target()
+checkpoint_id = await checkpoint_cursor_store.get(session_id)
+if checkpoint_id is None:
+    result = await target.run(message=workflow_input, checkpoint_storage=checkpoint_storage)
+else:
+    result = await target.run(checkpoint_id=checkpoint_id, checkpoint_storage=checkpoint_storage)
+latest = await checkpoint_storage.get_latest(workflow_name=target.name)
+if latest is not None:
+    await checkpoint_cursor_store.set(session_id, latest.checkpoint_id)
+```
+
+`workflow.run(...)` writes checkpoints to the provided storage, so storage selection must be explicit at the route layer.
+Protocol helper packages should not own checkpoint layout, route lifecycle, or durable execution.
 
 ## Non-goals for v1
 
-The following are deliberately **not** part of the v1 contract:
+The following remain outside the v1 protocol-helper contract. Some are deliberately app-owned in v1; others are possible
+future framework work only after a separate design.
 
-- cross-channel identity linking (`IdentityLinker`, `local_identity_link`, or `agent-framework-hosting-entra`),
-- identity allowlists or authorization policy (`IdentityAllowlist`, `AuthPolicy`),
-- response routing beyond the originating channel (`ResponseTarget`, active channel, specific linked channel, `all_linked`),
-- push or payload codecs (`ChannelPush`, `ChannelPushCodec`),
-- background/continuation delivery,
-- durable task runners (`DurableTaskRunner`, `InProcessTaskRunner`),
-- retry/replay policy (`RetryPolicy`),
-- fan-out, multicast, or all-linked delivery,
-- confidentiality tiers and `LinkPolicy`, and
-- a host-level multi-agent router.
+### App-owned in v1
 
-These areas are follow-up enhancements covered by [ADR-0028](0028-hosting-linking-multicast-enhancements.md). They are not prerequisites for shipping or using the v1 host.
+The app builder owns these concerns with normal web-framework, SDK, platform, or application code:
+
+- authentication, authorization policy, and allowlists;
+- deciding whether identities across protocols map to the same `session_id`;
+- non-originating sends using native SDK clients;
+- background work, durable execution, retry, and replay when app code owns the work;
+- routing between multiple agents.
+
+This is easier in the protocol-helper model than it was in the host/channel model: app code already owns the native SDK
+clients, route handlers, authenticated caller context, session id selection, and outbound send calls. An app can link
+channels by choosing the same authorized `session_id` for multiple protocols, and can do non-originating delivery by
+calling the destination protocol's native client directly. That does not make a reusable framework feature safe by
+default; it just means the app-specific version no longer has to fight a host abstraction.
+
+### Future framework work
+
+The following require a reviewed identity, storage, delivery, replay, and observability model before becoming reusable
+framework features:
+
+- reusable cross-channel identity linking;
+- framework-owned proactive or non-originating delivery;
+- fan-out, multicast, selected-channel, active-channel, or all-linked delivery;
+- framework-owned delivery observability, dead-letter handling, and replay semantics;
+- cross-channel confidentiality and link policy.
+
+These possible framework enhancements are tracked by [ADR-0028](0028-hosting-linking-multicast-enhancements.md). They are
+not prerequisites for shipping or using the v1 protocol-helper surface. ADR-0028 was written against the earlier
+host/channel framing and must be revised to align with this protocol-helper and execution-state boundary before those
+enhancements are implemented.
 
 ## Consequences
 
 Positive:
 
-- The host/channel model can be implemented and tested without designing a security-sensitive identity graph.
-- Existing and new channel packages can share one Starlette app, middleware stack, lifecycle, and target invocation path.
-- Session continuity is explicit and debuggable: two channels share history only when they produce the same `isolation_key`.
-- Hook invocation is centralized in the host, so channels do not each invent the call convention.
+- The released surface is smaller and easier to inspect: helpers plus state, not a channel framework.
+- Protocol helpers can be used from FastAPI, Starlette, Azure Functions, Django, CLI tools, tests, or native SDK webhook
+  handlers.
+- App authors can use the authentication, dependency injection, lifecycle, and background-task tools they already know.
+- Session continuity stays explicit and debuggable.
+- Workflow checkpointing can still be centralized if needed without making protocol packages own routing.
 
 Negative:
 
-- Apps that need OAuth linking, allowlists, proactive messages, or multicast must continue to implement those behaviors outside the v1 host.
-- Some richer cross-channel scenarios from the original design move to a separate decision and validation cycle.
-- The host must document `isolation_key` trust clearly because it now provides the shared session boundary.
-
-## Validation Gates
-
-Before this ADR is accepted:
-
-- A sample can expose one target on multiple channels with one `AgentFrameworkHost` and no handwritten Starlette route composition.
-- Built-in channel tests prove that routes, commands, startup, and shutdown callbacks are contributed by channels and aggregated by the host.
-- Session tests prove that identical `ChannelSession.isolation_key` values resolve to the same cached `AgentSession`, and `reset_session` rotates that mapping.
-- Channel tests prove that each channel renders only its own originating response; there is no host-level push, multicast, or active-channel delivery path.
-- Workflow tests or samples use an explicit `checkpoint_location`.
-- Foundry isolation middleware is documented and covered by integration or contract tests, including the non-Foundry case where raw isolation headers are ignored.
-- The v1 API and packages do not expose the removed symbols or packages listed in [Non-goals for v1](#non-goals-for-v1).
-- The Python spec is updated to match this simplified contract and uses "public", "stable", or "released" terminology for Agent Framework APIs.
+- Multi-protocol samples include explicit route/client code.
+- Apps that want a batteries-included ASGI app must write or depend on an app-specific wrapper.
+- Existing unreleased code and docs that mention channels, contribution, or hooks must be revised before release.
 
 ## More Information
 
-- Follow-up linking and multicast ADR: [ADR-0028](0028-hosting-linking-multicast-enhancements.md)
+- Follow-up linking and multicast ADR: [ADR-0028](0028-hosting-linking-multicast-enhancements.md). That ADR still uses
+  some earlier host/channel terminology and must be aligned before implementation work starts.
+
+## Appendix: Developer experience sketch
+
+The examples below are sketches, not runtime-ready sample code. They show the minimum shape a developer would need to
+build: where protocol helpers are called, where app-owned auth/authorization belongs, where state is loaded/stored, and
+where native framework code remains in charge.
+
+### Optional execution state
+
+`AgentState` and `WorkflowState` stay small: they are target-specific state holders, not app hosts.
+
+```python
+from typing import Protocol
+
+from agent_framework import AgentSession, SupportsAgentRun, Workflow
+
+
+class SupportsBuild(Protocol):
+    def build(self) -> Workflow: ...
+
+
+class SessionStore:
+    async def get(self, session_id: str) -> AgentSession | None: ...
+    async def set(self, session_id: str, session: AgentSession) -> None: ...
+    async def delete(self, session_id: str) -> None: ...
+
+
+class CheckpointCursorStore:
+    async def get(self, session_id: str) -> str | None: ...
+    async def set(self, session_id: str, checkpoint_id: str) -> None: ...
+    async def delete(self, session_id: str) -> None: ...
+
+
+class AgentState:
+    def __init__(self, target: SupportsAgentRun, *, session_store: SessionStore | None = None) -> None: ...
+    async def get_target(self) -> SupportsAgentRun: ...
+    async def get_or_create_session(self, session_id: str) -> AgentSession: ...
+    async def set_session(self, session_id: str, session: AgentSession) -> None: ...
+
+
+class WorkflowState:
+    def __init__(self, target: Workflow | SupportsBuild) -> None: ...
+    async def get_target(self) -> Workflow: ...
+```
+
+`WorkflowState` accepts direct `Workflow` instances, workflow factories, and builder-shaped objects with
+`build() -> Workflow`. That structurally covers `WorkflowBuilder` and the builders in `agent_framework_orchestrations`
+without making `agent-framework-hosting` depend on the orchestration package.
+
+### Responses-only route
+
+This sketch shows the intended Responses-only shape. The protocol package owns the Agent Framework run conversion helpers and
+response-id minting details; the application owns FastAPI routing, auth, policy adjustment, and response construction.
+
+```python
+import os
+from collections.abc import AsyncIterator
+
+from agent_framework import Agent, ResponseStream
+from agent_framework.openai import OpenAIChatClient
+from agent_framework_hosting import AgentState  # pyright: ignore[reportAttributeAccessIssue]
+from agent_framework_hosting_responses import create_response_id, responses_from_run, responses_from_streaming_run, responses_session_id, responses_to_run  # pyright: ignore[reportAttributeAccessIssue]
+from fastapi import Body, FastAPI, Header, HTTPException
+from fastapi.responses import JSONResponse, StreamingResponse
+
+app = FastAPI()
+agent = Agent(
+    client=OpenAIChatClient(),
+    name="Assistant",
+    instructions="Be concise and helpful.",
+)
+state = AgentState(agent)
+
+
+@app.post("/responses")
+async def responses(body: dict = Body(...), x_api_key: str | None = Header(default=None)) -> JSONResponse | StreamingResponse:
+    if x_api_key != os.environ["RESPONSES_API_KEY"]:
+        raise HTTPException(status_code=401, detail="bad api key")
+
+    # parse the request body into a set of AF objects
+    run = responses_to_run(body)
+    # get the candidate session id from the body
+    # can be a resp_* for previous_response_id or a conv_* for a conversation
+    candidate_session_id = responses_session_id(body)
+    # create a new response_id for this run
+    response_id = create_response_id()
+
+    # the developer can make any adjustments to the request, i.e.:
+    run["options"]["store"] = False
+    run["options"].pop("model", None)
+    # the options here are of the shape defined by the ChatClient/Agent
+
+    # load the session (or create a new one) - this is optional
+    # verify this caller owns candidate_session_id before loading it; API-key auth
+    # alone does not prove ownership of a caller-supplied resp_* or conv_* id
+    session_id = candidate_session_id or response_id
+    session = await state.get_or_create_session(session_id)
+    target = await state.get_target()
+
+    if run["stream"]:
+        stream = target.run(
+            run["messages"],
+            stream=True,
+            session=session,
+            options=run["options"],
+        )
+        async def stream_events() -> AsyncIterator[str]:
+            async for event in responses_from_streaming_run(
+                stream,
+                response_id=response_id,
+                session_id=candidate_session_id,
+            ):
+                yield event
+            # agent.run may update the session during stream finalization, so store the post-run session explicitly
+            await state.set_session(response_id, session)
+
+        return StreamingResponse(stream_events(), media_type="text/event-stream")
+
+    result = await target.run(
+        run["messages"],
+        session=session,
+        options=run["options"],
+    )
+    # agent.run may update the session, so store the post-run session explicitly under the response id
+    # this might also be skipped, if the app chooses to respect `store=False` policy
+    await state.set_session(response_id, session)
+    return JSONResponse(responses_from_run(result, response_id=response_id, session_id=candidate_session_id))
+
+```
+
+### Responses-only Django class-based view
+
+The same helper surface can be used without FastAPI. A Django app owns URL routing, CSRF/auth policy, request parsing,
+and `JsonResponse` construction. In a real Django project this would live in the app's normal view module (for example
+`assistant/views.py`) and be routed from that app's `urls.py`; Django discovers it through its standard project/app
+layout, not through Agent Framework. This sketch shows the non-streaming path only; the streaming branch is the same
+state/finalization pattern shown in the FastAPI sketch and is omitted here to avoid duplicating it.
+
+```python
+import json
+import os
+
+from agent_framework import Agent
+from agent_framework.openai import OpenAIChatClient
+from agent_framework_hosting import AgentState  # pyright: ignore[reportAttributeAccessIssue]
+from agent_framework_hosting_responses import create_response_id, responses_from_run, responses_session_id, responses_to_run  # pyright: ignore[reportAttributeAccessIssue]
+from django.http import HttpRequest, HttpResponseBadRequest, HttpResponseForbidden, JsonResponse
+from django.views import View
+
+
+agent = Agent(
+    client=OpenAIChatClient(),
+    name="Assistant",
+    instructions="Be concise and helpful.",
+)
+state = AgentState(agent)
+
+
+class ResponsesView(View):
+    async def post(self, request: HttpRequest) -> JsonResponse:
+        if request.headers.get("x-api-key") != os.environ["RESPONSES_API_KEY"]:
+            return HttpResponseForbidden("bad api key")
+
+        try:
+            body = json.loads(request.body)
+        except json.JSONDecodeError:
+            return HttpResponseBadRequest("invalid json")
+
+        run = responses_to_run(body)
+        candidate_session_id = responses_session_id(body)
+        response_id = create_response_id()
+        options = run["options"]
+        # verify this caller owns candidate_session_id before loading it; API-key auth
+        # alone does not prove ownership of a caller-supplied resp_* or conv_* id
+        session_id = candidate_session_id or response_id
+        session = await state.get_or_create_session(session_id)
+        target = await state.get_target()
+        result = await target.run(
+            run["messages"],
+            session=session,
+            options=options,
+        )
+        await state.set_session(response_id, session)
+        return JsonResponse(responses_from_run(result, response_id=response_id, session_id=candidate_session_id))
+```

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

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

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

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

docs/features/FIDES_IMPLEMENTATION_SUMMARY.md

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

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

@@ -1,320 +1,498 @@
 ---
 status: proposed
 contact: eavanvalkenburg
-date: 2026-06-11
+date: 2026-07-08
 deciders: eavanvalkenburg
 ---
 
-# Python hosting core and pluggable channels
+# Python protocol helpers and optional execution state
 
 ## Scope
 
-This specification is the Python implementation plan for [ADR-0027](../decisions/0027-hosting-channels.md). It documents the simplified v1 host/channel contract only.
+This specification is the Python implementation plan for
+[ADR-0027](../decisions/0027-hosting-channels.md). It documents the helper-first v1 contract for Python hosting.
 
 The v1 contract is:
 
-- `AgentFrameworkHost` owns one Starlette app, one hostable target, and one or more channels.
-- A hostable target is either a `SupportsAgentRun`-compatible agent or a `Workflow`.
-- Channels contribute routes, middleware, commands, and lifecycle callbacks.
-- Channels parse protocol-native input into `ChannelRequest`.
-- Channels render their own originating response.
-- Session continuity is explicit: a channel supplies `ChannelSession(isolation_key=...)`, and the host resolves/caches an `AgentSession` for that key.
-- The host invokes `ChannelRunHook` and `ChannelResponseHook`; channels provide hook configuration and protocol context.
-
-The host does not link identities, route responses to other channels, run background continuations, or multicast in v1. Those enhancements are tracked in [ADR-0028](../decisions/0028-hosting-linking-multicast-enhancements.md).
+- protocol packages expose helper functions that convert protocol-native input to Agent Framework run values;
+- protocol packages expose helper functions that convert Agent Framework run results or streams back to protocol-native
+  payloads or operations;
+- application/framework code owns routes, native SDK clients, authentication, command policy, webhooks, response status
+  codes, and outbound sends;
+- `agent-framework-hosting` provides small optional state holders for Agent Framework targets;
+- state helpers do not own web apps, route contribution, protocol dispatch, command projection, or native SDK calls.
 
 ## Goals
 
-- Let an app expose one agent or workflow on multiple protocols without handwritten Starlette composition.
-- Keep protocol parsing and response formatting inside channel packages.
-- Provide one session-resolution path shared by all channels.
-- Keep the channel authoring surface small enough for new channels to implement.
-- Preserve full-fidelity agent and workflow results until a channel decides how to render them.
+- Let apps expose agents and workflows from FastAPI, Starlette, Django, Azure Functions, native SDK webhooks, CLIs, and
+  tests without adopting a host/channel framework.
+- Keep protocol parsing and response formatting inside protocol packages.
+- Keep session continuity explicit and app-owned at the trust boundary.
+- Reuse Agent Framework primitives: `AgentSession`, `CheckpointStorage`, `Agent.run(...)`, `Workflow.run(...)`, and
+  `ResponseStream`.
+- Preserve full-fidelity Agent Framework results until a protocol helper renders them.
 
 ## Non-goals for v1
 
-The following are removed from the v1 implementation pass:
+### App-owned in v1
 
-- `IdentityLinker`, `IdentityAllowlist`, `AuthPolicy`, and `LinkPolicy`
-- `ResponseTarget`, active-channel routing, `all_linked`, fan-out, and multicast
-- `ChannelPush` and `ChannelPushCodec`
-- `DurableTaskRunner`, `InProcessTaskRunner`, and `RetryPolicy`
-- continuation tokens and background delivery
-- confidentiality tiers
-- `agent-framework-hosting-entra`
-- `local_identity_link`
+The app builder owns these concerns with normal web-framework, SDK, platform, or application code:
 
-These are follow-up design topics, not hidden requirements of the v1 host.
+- authentication, authorization policy, and allowlists;
+- deciding whether identities across protocols map to the same `session_id`;
+- non-originating sends using native SDK clients;
+- background work, durable execution, retry, and replay when app code owns the work;
+- routing between multiple agents.
+
+The helper-first model makes app-owned linking and non-originating delivery easier than the old host/channel model because
+app code already owns the native SDK clients, authenticated caller context, session id selection, and outbound sends.
+
+### Future framework work
+
+The following require a separate reviewed design before becoming reusable framework features:
+
+- reusable cross-channel identity linking;
+- framework-owned proactive or non-originating delivery;
+- fan-out, multicast, selected-channel, active-channel, or all-linked delivery;
+- framework-owned delivery observability, dead-letter handling, and replay semantics;
+- cross-channel confidentiality and link policy.
+
+[ADR-0028](../decisions/0028-hosting-linking-multicast-enhancements.md) tracks possible follow-up work in this area and
+must be aligned with the helper-first model before implementation. Old vocabulary such as `IdentityLinker`,
+`ResponseTarget`, `ChannelPush`, `ChannelPushCodec`, `DurableTaskRunner`, `RetryPolicy`, and `LinkPolicy` is not v1 API.
 
 ## Packages
 
-| Package | Import surface | Contents |
+| Package | Import surface | v1 helper-first contents |
 |---|---|---|
-| `agent-framework-hosting` | `agent_framework_hosting` | `AgentFrameworkHost`, channel protocols, key request/result types, hooks, `reset_session`, state-path helpers. |
-| `agent-framework-hosting-responses` | `agent_framework_hosting_responses` | `ResponsesChannel`. |
-| `agent-framework-hosting-invocations` | `agent_framework_hosting_invocations` | `InvocationsChannel`. |
-| `agent-framework-hosting-telegram` | `agent_framework_hosting_telegram` | `TelegramChannel` and Telegram command helpers. |
-| `agent-framework-hosting-activity-protocol` | `agent_framework_hosting_activity_protocol` | `ActivityProtocolChannel` for Activity Protocol over Azure Bot Service. |
-| `agent-framework-hosting-discord` | `agent_framework_hosting_discord` | `DiscordChannel` and Discord command/interaction helpers. |
-| `agent-framework-foundry-hosting` | `agent_framework.foundry_hosting` | Foundry isolation middleware and Foundry-backed hosting helpers usable with the v1 host. |
+| `agent-framework-hosting` | `agent_framework_hosting` | `AgentState`, `WorkflowState`, `SessionStore`, and run-argument `TypedDict`s. |
+| `agent-framework-hosting-a2a` | `agent_framework_hosting_a2a` | A2A `Message` to run conversion and Agent Framework output to A2A `Part` conversion. |
+| `agent-framework-hosting-mcp` | `agent_framework_hosting_mcp` | Agent and workflow MCP tool adapters, MCP tool arguments to run conversion, and Agent Framework output to MCP `ContentBlock` conversion. |
+| `agent-framework-hosting-responses` | `agent_framework_hosting_responses` | Responses helpers: request parsing, session id extraction, response id creation, response rendering, streaming rendering. |
+| `agent-framework-hosting-telegram` | `agent_framework_hosting_telegram` | Telegram Bot API helpers: update parsing, chat/session/command/media extraction, final rendering, and streaming edit rendering. |
+| Future protocol packages | e.g. `agent_framework_hosting_activity_protocol` | Protocol-specific helpers such as `activity_to_run(...)`, `activity_from_run(...)`, `activity_session_id(...)`, and command/media helpers when useful. |
 
-Channel packages may depend on their native SDKs. The core hosting package should not depend on channel SDKs or on top-level legacy protocol hosts.
+The core hosting package must not depend on protocol SDKs. Protocol packages may depend on their native protocol SDKs if
+needed, but helper functions should stay usable from plain app code and tests.
 
-## Key Types
+## Helper naming and families
 
-### `AgentFrameworkHost`
+Helper names are protocol-specific. Avoid a generic `protocol_to_run(...)` public surface.
 
-The host constructor accepts:
+Protocol packages may provide the following helper families when the protocol has the concept:
 
-- `target`: one `SupportsAgentRun`-compatible object or one `Workflow`
-- `channels`: one or more `Channel` instances
-- optional Starlette middleware
-- optional `state_dir`
-- optional workflow `checkpoint_location`
+| Helper family | Shape | Purpose |
+| --- | --- | --- |
+| Run conversion | `<protocol>_to_run(...)` | Convert one protocol-native call/update/request into `Agent.run` or `Workflow.run` values. |
+| Final rendering | `<protocol>_from_run(...)` | Convert a final `AgentResponse` or workflow result into protocol-native response payloads or operations. |
+| Stream rendering | `<protocol>_from_streaming_run(...)` | Convert `ResponseStream` or workflow updates into protocol-native events or operations. |
+| Session id extraction | `<protocol>_session_id(...)` | Extract the protocol's natural continuation/partition key from the call, if present. |
+| Command/action parsing | `<protocol>_command(...)` | Parse a protocol-native command/action/operation name without deciding app policy. |
 
-The host exposes:
+Examples:
 
-- `app`: the canonical Starlette ASGI application
-- `serve(...)`: a convenience wrapper for local serving
-- `reset_session(isolation_key: str)`: rotate the cached `AgentSession` for a host-tracked conversation
+- `responses_to_run(...)`, `responses_from_run(...)`, `responses_from_streaming_run(...)`,
+  `responses_session_id(...)`;
+- `a2a_to_run(...)`, `a2a_from_run(...)`;
+- `telegram_to_run(...)`, `telegram_from_run(...)`, `telegram_from_streaming_run(...)`,
+  `telegram_session_id(...)`, `telegram_command(...)`;
+- `activity_to_run(...)`, `activity_from_run(...)`, `activity_session_id(...)`, `activity_command(...)`;
+- `discord_to_run(...)`, `discord_from_run(...)`, `discord_session_id(...)`, `discord_command(...)`.
 
-`state_dir` is narrowed to v1 host-owned local files only:
+This table is a naming guide, not a required checklist. A protocol package should add only the helpers that match native
+protocol concepts and current samples.
 
-- session aliases (`isolation_key` to current `AgentSession` id), and
-- workflow checkpoint paths when the app chooses the host-provided file layout.
+Protocol-specific helpers may also exist for native details such as `telegram_chat_id(...)`,
+`telegram_callback_query_id(...)`, `telegram_media_file_id(...)`, `discord_interaction_id(...)`, `a2a_task_id(...)`,
+`a2a_context_id(...)`, or MCP tool/prompt/resource helpers. These helpers should stay side-effect-free. App/native SDK
+code performs acknowledgements, sends/edits messages, resolves protected file URLs, applies rate limits, and registers
+handlers.
 
-It is not a store for identity links, continuations, active-channel state, delivery attempts, or multicast payloads.
+## `agent-framework-hosting` state helpers
 
-Externally supplied isolation keys are trusted only after the channel or host middleware has authenticated and authorized the caller. The host uses `isolation_key` as a partition key; the string itself is not proof of identity or ownership.
+### `SessionStore`
 
-### `Channel`
-
-A channel implements a small protocol:
-
-- declare a stable channel id/name,
-- contribute routes, middleware, commands, and lifecycle callbacks,
-- parse inbound protocol data into `ChannelRequest`,
-- call the host through `ChannelContext.run(...)` or `ChannelContext.run_stream(...)`, and
-- serialize the returned result to the originating protocol response.
-
-Channels own protocol authentication, signature validation, native command registration, and protocol-specific error bodies.
-
-### `ChannelContribution`
-
-`ChannelContribution` is the channel's host-facing contribution:
-
-- Starlette routes and optional middleware,
-- native command descriptors,
-- startup and shutdown callbacks, and
-- any channel-local metadata needed by the package.
-
-The host aggregates contributions but does not interpret protocol payloads.
-
-### `ChannelRequest`
-
-`ChannelRequest` is the host-neutral request envelope produced by a channel. It carries:
-
-- target input,
-- optional `ChannelSession`,
-- optional `ChannelIdentity`,
-- options and attributes produced by the channel, and
-- request metadata useful to hooks and context providers.
-
-The host may pass attributes through to context providers and middleware. Channels should treat attributes as a documented extension bag, not as a cross-channel delivery contract.
-
-### `ChannelSession`
-
-`ChannelSession(isolation_key=...)` is the only v1 session-continuity mechanism.
-
-When a request contains an isolation key:
-
-1. The host looks up or creates the cached `AgentSession` for that key.
-2. The target runs with that `AgentSession` when the target is an agent.
-3. `reset_session(isolation_key)` rotates the alias so the next request starts a new conversation.
-
-If two channels produce the same isolation key on the same host, they share the same cached session. If they produce different keys, they do not share session state.
-
-### `ChannelIdentity`
-
-`ChannelIdentity` is optional request metadata such as channel id, native user id, tenant id, claims, or display attributes.
-
-In v1, `ChannelIdentity` does not link channels, authorize callers, select delivery destinations, or imply that two identities should share an `AgentSession`. A channel that wants shared history must still produce the same `ChannelSession.isolation_key`.
-
-### Hooks
-
-Hooks are optional and channel-owned:
-
-- `ChannelRunHook`: runs after channel parsing and before host invocation; returns the `ChannelRequest` to execute.
-- `ChannelResponseHook`: runs after target completion and before the originating channel renders a one-shot response.
-- `ChannelStreamUpdateHook`: the host applies it to streamed updates before the originating channel serializes the stream.
-
-Common uses include adapting chat text into workflow inputs, enforcing deployment-specific options, flattening rich output for text-only protocols, or filtering streamed updates for a protocol. Stream update hooks are update-only; they do not automatically sanitize `get_final_response()` output. Channels choose their response transport from the parsed protocol request before invoking run hooks.
-
-### `HostedRunResult`
-
-`HostedRunResult[T]` wraps the target's full-fidelity result plus the resolved `AgentSession | None`.
-
-- Agent targets produce `HostedRunResult[AgentResponse]`.
-- Workflow targets produce `HostedRunResult[WorkflowRunResult]`.
-
-The host does not flatten, filter, or translate the result. Each channel decides how much of the result its protocol can carry.
-
-## Host Behavior
-
-1. `AgentFrameworkHost` builds one Starlette app and asks each channel for its contribution.
-2. A channel route receives a protocol-native request.
-3. The channel validates/parses the native payload and creates `ChannelRequest`.
-4. The channel passes the request, optional `ChannelRunHook`, and protocol-native context to the host.
-5. The host invokes `ChannelRunHook`, if configured, and receives the prepared request.
-6. The host resolves an `AgentSession` from `ChannelSession.isolation_key` when present.
-7. The host invokes the agent or workflow target.
-8. The host wraps the result in `HostedRunResult` or the streaming equivalent.
-9. The host invokes `ChannelResponseHook`, if configured, for non-streaming/final response shaping.
-10. The host applies stream update hooks while the channel consumes streams; the channel renders the originating protocol response.
-
-There is no host-level route from one channel's request to another channel's response in v1.
-
-## Workflow Checkpoints
-
-Workflow checkpointing is explicit. Apps either configure checkpoint storage on the workflow itself or pass a `checkpoint_location` to the host so the workflow dispatch path can use the intended file location.
-
-`state_dir` may provide a conventional location for workflow checkpoint files, but checkpointing is still opt-in and separate from agent session history. Checkpoints are workflow-runtime state, not channel state and not identity-link state.
-
-## Foundry Isolation Middleware
-
-V1 keeps Foundry isolation as middleware rather than as a channel-linking feature.
-
-The middleware is installed only when the Foundry hosting environment flag is present. In that environment it reads Foundry-provided isolation values at the trusted hosting boundary, exposes them as read-only request context for Foundry-aware history or memory providers, and rejects unsafe session resumes when the live isolation context does not match persisted session context. Outside Foundry, raw isolation headers are ignored unless an app supplies its own trusted middleware.
-
-This middleware does not create cross-channel identity links and does not authorize non-Foundry channels.
-
-## Current Channels
-
-### Responses
-
-`ResponsesChannel` exposes the OpenAI-compatible Responses API shape. It maps request body fields such as input, options, and conversation identifiers into `ChannelRequest`, and it renders Responses-compatible one-shot or streaming responses.
-
-Responses session continuity uses a channel-selected `isolation_key`, commonly derived from a response/conversation id, caller-provided session id, Foundry isolation context, or deployment-specific request metadata.
-
-### Invocations
-
-`InvocationsChannel` exposes an invocation endpoint for server-side callers and tools. It maps the request body into `ChannelRequest` and renders the invocation result on the same HTTP response.
-
-Invocations is useful for typed workflow inputs because a `ChannelRunHook` can translate the request body into the workflow's expected input type.
-
-### Telegram
-
-`TelegramChannel` supports webhook or polling transport, native command registration, and message rendering back to the originating Telegram chat.
-
-The channel chooses a default `isolation_key` from Telegram-native data such as chat id, user id, or a configured user/chat scope. A `/new` or equivalent command may call `reset_session` for that isolation key.
-
-### Activity Protocol
-
-`ActivityChannel` supports Activity Protocol requests, typically through Azure Bot Service for Teams, Web Chat, and other Bot Framework-fronted surfaces.
-
-The channel maps incoming `Activity` objects to `ChannelRequest` and renders a reply activity to the originating conversation. Proactive Activity delivery, active-channel routing, and all-linked fan-out are not v1 host semantics.
-
-### Discord
-
-`DiscordChannel` supports Discord messages, slash commands, and interactions as channel-native input.
-
-The channel maps Discord-native user, guild, channel, thread, and interaction data into `ChannelRequest` metadata and a configured `ChannelSession.isolation_key`. It renders the result to the originating Discord response path.
-
-## High-level Samples
-
-### One agent on Responses
+`SessionStore` is an in-memory async lookup:
 
 ```python
-host = AgentFrameworkHost(
-    target=agent,
-    channels=[ResponsesChannel()],
+class SessionStore:
+    async def get(self, session_id: str) -> AgentSession | None: ...
+    async def set(self, session_id: str, session: AgentSession) -> None: ...
+    async def delete(self, session_id: str) -> None: ...
+```
+
+The store does not create sessions. It stores `session_id -> AgentSession` values supplied by callers.
+
+The built-in store has no TTL or eviction. This is intentional for local/dev and simple process-local scenarios: protocols
+such as OpenAI Responses can continue from any prior response id. Durable or multi-replica deployments should provide a
+durable store and their own TTL/eviction policy.
+
+### `AgentState`
+
+`AgentState` holds an agent target and an optional `SessionStore`:
+
+```python
+state = AgentState(agent)
+state = AgentState(create_agent)
+state = AgentState(create_agent, cache_target=False)
+```
+
+The target may be:
+
+- a `SupportsAgentRun` instance;
+- a synchronous factory;
+- an asynchronous factory;
+- an awaitable target.
+
+`AgentState` provides:
+
+- `await get_target()`;
+- synchronous `target` only after a target is already available/resolved;
+- `session_store`;
+- `await get_or_create_session(session_id)`;
+- `await set_session(session_id, session)`.
+
+`get_or_create_session(...)` resolves the target and calls `target.create_session(session_id=...)` only when the store has
+no session for that id.
+
+Apps must store the post-run session explicitly after `agent.run(...)` or stream finalization:
+
+```python
+session = await state.get_or_create_session(session_id)
+target = await state.get_target()
+result = await target.run(messages, session=session, options=options)
+await state.set_session(response_id, session)
+```
+
+### `WorkflowState`
+
+`WorkflowState` resolves a workflow target. It does not own checkpoint storage.
+
+The target may be:
+
+- a `Workflow` instance;
+- a `WorkflowBuilder` or other object with `build() -> Workflow`;
+- a synchronous factory;
+- an asynchronous factory;
+- an awaitable target.
+
+`WorkflowState` provides:
+
+- `await get_target()`;
+- synchronous `target` only after a target is already available/resolved.
+
+A workflow instance permits one active run. Concurrent hosts use a factory or
+builder with `cache_target=False` to resolve a fresh instance per run.
+
+Workflow checkpointing uses Agent Framework's existing `CheckpointStorage` abstraction directly. Apps that need
+per-session workflow resume should keep an app-owned cursor such as `session_id -> checkpoint_id`. When the app uses
+file-backed cursor storage, the file-based checkpoint storage should share the same app storage root and should be
+scoped to the current authenticated user/tenant/session bucket, for example
+`storage/checkpoints/<session-bucket>/` beside `storage/checkpoint_cursors.json`:
+
+```python
+# session_id must already be authenticated and authorized for this caller
+target = await workflow_state.get_target()
+checkpoint_id = await checkpoint_cursor_store.get(session_id)
+if checkpoint_id is None:
+    result = await target.run(message=workflow_input, checkpoint_storage=checkpoint_storage)
+else:
+    result = await target.run(checkpoint_id=checkpoint_id, checkpoint_storage=checkpoint_storage)
+latest = await checkpoint_storage.get_latest(workflow_name=target.name)
+if latest is not None:
+    await checkpoint_cursor_store.set(session_id, latest.checkpoint_id)
+```
+
+`Workflow.run(...)` does not currently emit a checkpoint id on `WorkflowRunResult` or normal workflow events by default.
+The runner receives checkpoint ids internally from `CheckpointStorage.save(...)`. Apps that own the storage can query
+`get_latest(workflow_name=...)` after the run if they need to update a cursor.
+
+## `agent-framework-hosting-responses`
+
+The Responses package provides the helper-first surface for OpenAI Responses-shaped requests.
+
+### Request helpers
+
+- `messages_from_responses_input(input) -> list[Message]`
+- `responses_to_run(body) -> AgentRunArgs`
+- `responses_session_id(body) -> str | None`
+- `create_response_id() -> str`
+
+`responses_to_run(...)` returns values corresponding to `Agent.run(...)`:
+
+```python
+run = responses_to_run(body)
+messages = run["messages"]
+options = run["options"]
+stream = run["stream"]
+```
+
+It excludes protocol transport/session fields from `options` and remaps known Responses option names such as
+`max_output_tokens -> max_tokens`.
+
+`responses_session_id(...)` returns:
+
+- `previous_response_id` when present (`resp_*`);
+- otherwise `conversation_id` when present (`conv_*`);
+- otherwise `None`.
+
+The helper only extracts the candidate key. App code decides whether to trust and use that key.
+
+### Response helpers
+
+- `responses_from_run(result, *, response_id, session_id=None) -> dict[str, Any]`
+- `responses_from_streaming_run(stream, *, response_id, session_id=None) -> AsyncIterator[str]`
+
+`responses_from_run(...)` renders a full Responses JSON payload from an `AgentResponse`. It renders the full set of
+OpenAI Responses output item types supported by Agent Framework content.
+
+`responses_from_streaming_run(...)` renders Server-Sent Event strings for a `ResponseStream`. It emits a created event,
+text deltas, and a completed event. The final completed payload is produced through `responses_from_run(...)`; the helper
+also preserves the model id observed on streaming updates when the finalized `AgentResponse` no longer carries raw model
+metadata.
+
+## `agent-framework-hosting-a2a`
+
+The A2A package provides only the conversion seam between the native A2A SDK
+and Agent Framework:
+
+- `a2a_to_run(message, *, stream=False) -> AgentRunArgs`
+- `a2a_from_run(result) -> list[a2a.types.Part]`
+
+`a2a_to_run(...)` accepts a native A2A `Message` and converts its text, URL,
+raw-byte, and structured-data parts into one Agent Framework user message.
+
+`a2a_from_run(...)` accepts an `AgentResponse`, `Message`, or
+`AgentResponseUpdate` and converts supported text, URI, and data content into
+native A2A `Part` values. This one helper is usable for both completed and
+streaming runs.
+
+The package does not provide an A2A `AgentExecutor`, application, route,
+request handler, task store, event queue, `TaskUpdater`, task-state policy,
+artifact-id policy, or session-key policy. Application code composes the two
+helpers with those native A2A SDK constructs and may use any server framework
+supported by the SDK.
+
+## `agent-framework-hosting-mcp`
+
+The MCP package provides only the conversion seam between native MCP SDK values
+and Agent Framework:
+
+- `MCPAgentTool(target, ...)`
+- `MCPWorkflowTool(target, ...)`
+- `mcp_to_run(arguments, *, argument_name="task", chat_option_arguments=()) -> AgentRunArgs`
+- `mcp_from_run(result) -> list[mcp.types.ContentBlock]`
+
+`MCPAgentTool` represents one Agent Framework agent as one native MCP tool. It
+derives the default tool name and description from the agent, accepts
+overrides for those values and the main text parameter, includes app-owned
+additional parameter schemas, and explicitly maps selected parameter schemas
+to ChatOptions. Its asynchronous `list_tools()` returns the native `Tool` list,
+and `call_tool(...)` performs conversion, agent execution, and final result
+conversion.
+
+The adapter accepts either an agent or an existing `AgentState`. With a
+configured `session_id_parameter`, it loads and stores the corresponding
+`AgentSession`. The application remains responsible for deriving and
+authorizing the session id and preventing concurrent updates to the same
+session.
+
+`MCPWorkflowTool` represents one Agent Framework workflow as one native MCP
+tool. It derives the tool name and description from the workflow and derives
+the input schema from the start executor's single declared input type.
+Object-shaped dataclass and Pydantic inputs become top-level MCP arguments;
+primitive inputs are wrapped in one configurable argument. The adapter
+validates the arguments against that type, runs the workflow, and converts
+terminal outputs to MCP content blocks.
+
+Workflow instances preserve state and reject concurrent runs. Applications
+that need independent calls should provide a `WorkflowState` factory with
+`cache_target=False`. Checkpoint restoration, human-in-the-loop responses, and
+continuation identifiers remain application-owned contracts. If a workflow
+stops to request external input, the adapter raises rather than returning an
+empty successful tool result.
+
+`mcp_to_run(...)` accepts the argument mapping from a native MCP `call_tool`
+handler. The application owns the tool schema and may select which required
+string argument contains the user request. The application should define that
+argument name once and use the same value in the native tool schema and the
+`argument_name` parameter so those two sides of the contract remain aligned.
+Applications may also expose selected ChatOptions fields in their native tool
+schema and pass those names through `chat_option_arguments`. Only explicitly
+selected names are copied to run options; the helper does not forward all MCP
+arguments or own their JSON Schema validation.
+
+MCP `tools/call` arguments are JSON-only and do not have a native multimodal
+content-block union. The package does not impose a non-standard JSON
+representation for multimodal tool arguments.
+
+`mcp_from_run(...)` accepts an `AgentResponse` or `Message`. It converts text,
+URI, image data, audio data, and other binary data into native MCP content
+blocks.
+
+Its output is specifically the content union accepted by `CallToolResult`.
+Sampling-only values such as `ToolUseContent` belong to the separate MCP
+sampling response path and are not emitted by this hosting helper.
+
+MCP `tools/call` returns one final `CallToolResult`. Streamable HTTP can carry
+multiple MCP messages and progress notifications can report operation status,
+but the protocol does not define partial tool-result content chunks.
+Experimental MCP tasks defer retrieval of the same final result. Therefore the
+conversion helpers do not expose Agent Framework streaming updates.
+
+The package does not provide an MCP `Server`, handler registration, transport, route,
+session policy, authentication, authorization, or deployment wrapper.
+Application code composes the adapters and conversion helpers with native MCP SDK constructs and
+may use stdio, streamable HTTP, or another transport supported by the SDK.
+
+## `agent-framework-hosting-telegram`
+
+The Telegram package provides side-effect-free helpers around Telegram Bot API
+update and method payloads. It does not provide a Bot API client, polling loop,
+webhook route, command registry, retry policy, or rate limiter.
+
+### Update helpers
+
+- `telegram_to_run(update, *, resolve_file_url=None, stream=False) -> AgentRunArgs`
+- `telegram_chat_id(update) -> int | None`
+- `telegram_session_id(update, *, bot_id) -> str | None`
+- `telegram_command(update) -> str | None`
+- `telegram_callback_query_id(update) -> str | None`
+- `telegram_media_file_id(update_or_message) -> tuple[str, str] | None`
+
+`telegram_to_run(...)` handles `message`, `edited_message`, and
+`callback_query` updates. Text and captions become AF text content. When the
+app supplies an async `resolve_file_url` callback, supported Telegram media
+file ids can become AF URI content. The package does not call Telegram's
+`getFile` method itself.
+
+`telegram_session_id(..., bot_id=...)` includes the bot identity in every key.
+Private chats return `telegram:<bot_id>:<user_id>`; other chats return
+`telegram:<bot_id>:<chat_id>`, giving groups a shared session by default. This
+matches Telegram's native isolation boundaries while preventing two bots from
+sharing state accidentally. Apps that want per-user sessions inside a group
+can construct a key that includes both chat and sender ids. The app must
+authorize those Telegram identities before loading session state.
+
+`telegram_command(...)` parses Telegram's `/name` and `/name@bot` syntax. It
+does not register commands or invoke handlers.
+
+### Response helpers
+
+- `telegram_from_run(result, *, chat_id, parse_mode=None)`
+- `telegram_from_streaming_run(stream, *, chat_id, message_id, initial_text=None, parse_mode=None)`
+
+The helpers produce Telegram method/payload values for app-owned Bot API
+calls. Final rendering supports text and image URI output and applies
+Telegram's text-length boundary. Streaming rendering produces cumulative
+`editMessageText` payloads for a placeholder message id supplied by the app,
+omitting edits that match an optional `initial_text`, then renders the final
+rich output. Image-only responses remove the placeholder with `deleteMessage`
+before sending the image. The app owns the initial placeholder send, Bot API
+calls, edit throttling, retries, and failure policy.
+
+## Security responsibilities
+
+Protocol helper packages parse and render. They do not authenticate callers, authorize access to state, or decide which
+side effects are allowed.
+
+Application code that uses these helpers is responsible for:
+
+- authenticating the caller through the app's normal mechanism before using protocol-provided ids;
+- authorizing any caller-supplied session, checkpoint, task, context, conversation, thread, or response id before loading
+  state for it;
+- binding externally supplied ids to the authenticated user, tenant, workspace, installation, or chat context before
+  using them as `SessionStore` keys or checkpoint cursor keys;
+- treating `<protocol>_session_id(...)` results as untrusted candidate keys until that ownership check has passed;
+- keeping platform-provided isolation helpers fail-closed outside their trusted hosting environment;
+- authorizing command/action effects such as reset, cancel, approve, submit, or tool invocation after parsing them;
+- opting in explicitly before resolving protected media/resource/file URLs and passing them to a remote model provider;
+- persisting post-run session or checkpoint state only after `agent.run(...)`, `workflow.run(...)`, or stream finalization
+  has updated that state.
+
+## Persistent versus transient hosting
+
+The application builder decides whether the server is persistent or transient.
+
+- Persistent single-process apps, such as a long-running container or web app, may use in-memory state for local
+  development or simple deployments. Multi-replica persistent apps still need durable state for continuity.
+- Transient apps, such as Azure Functions, Foundry Hosted Agents, or any environment where process memory is not a
+  reliable boundary, must not rely on in-memory `SessionStore` state between calls. They need a durable session store or
+  a service-owned continuation id.
+- Workflow hosts must choose an explicit `CheckpointStorage` and, when they need per-session resume, a durable
+  `session_id -> checkpoint_id` cursor. File-backed checkpoint storage and file-backed cursor storage should live under
+  the same app storage root, with checkpoints scoped to the current authenticated user/tenant/session bucket so a
+  "latest checkpoint" lookup cannot cross conversations. In-process workflow state and in-memory checkpoint cursors do
+  not survive transient execution.
+
+## Minimal FastAPI Responses shape
+
+This is the shape the local Responses sample should demonstrate. It is not an app framework.
+
+```python
+from collections.abc import AsyncIterator
+
+from agent_framework import ResponseStream
+from agent_framework_hosting import AgentState
+from agent_framework_hosting_responses import (
+    create_response_id,
+    responses_from_run,
+    responses_from_streaming_run,
+    responses_session_id,
+    responses_to_run,
 )
+from fastapi import Body, FastAPI, HTTPException
+from fastapi.responses import JSONResponse, StreamingResponse
 
-app = host.app
+app = FastAPI()
+state = AgentState(create_agent)
+
+
+@app.post("/responses", response_model=None)
+async def responses(body: dict = Body(...)) -> JSONResponse | StreamingResponse:
+    run = responses_to_run(body)
+    candidate_session_id = responses_session_id(body)
+    response_id = create_response_id()
+
+    # Verify this caller owns candidate_session_id before loading it.
+    session_id = candidate_session_id or response_id
+    session = await state.get_or_create_session(session_id)
+    target = await state.get_target()
+
+    if run["stream"]:
+        stream = target.run(run["messages"], stream=True, session=session, options=run["options"])
+        if not isinstance(stream, ResponseStream):
+            raise HTTPException(status_code=500, detail="agent did not return a response stream")
+
+        async def events() -> AsyncIterator[str]:
+            async for event in responses_from_streaming_run(
+                stream,
+                response_id=response_id,
+                session_id=candidate_session_id,
+            ):
+                yield event
+            await state.set_session(response_id, session)
+
+        return StreamingResponse(events(), media_type="text/event-stream")
+
+    result = await target.run(run["messages"], session=session, options=run["options"])
+    await state.set_session(response_id, session)
+    return JSONResponse(responses_from_run(result, response_id=response_id, session_id=candidate_session_id))
 ```
 
-### One agent on multiple channels
+## Validation
 
-```python
-host = AgentFrameworkHost(
-    target=agent,
-    channels=[
-        ResponsesChannel(),
-        InvocationsChannel(),
-        TelegramChannel(bot_token=os.environ["TELEGRAM_BOT_TOKEN"]),
-    ],
-)
+Implementation validation must cover:
 
-host.serve(host="localhost", port=8000)
-```
-
-The host owns one Starlette app. Each channel contributes its own routes and renders its own response.
-
-### Adapting a request before execution
-
-```python
-from dataclasses import replace
-
-
-def enforce_options(request: ChannelRequest) -> ChannelRequest:
-    options = dict(request.options or {})
-    options["temperature"] = 0
-    return replace(request, options=options)
-
-
-host = AgentFrameworkHost(
-    target=agent,
-    channels=[ResponsesChannel(run_hook=enforce_options)],
-)
-```
-
-### Workflow with explicit checkpoints
-
-```python
-host = AgentFrameworkHost(
-    target=workflow,
-    channels=[InvocationsChannel(run_hook=adapt_to_workflow_input)],
-    checkpoint_location=Path("./.af-hosting/workflow_checkpoints"),
-)
-```
-
-The hook adapts channel-native input to the workflow's typed input. Checkpoints use the explicit workflow checkpoint location, not identity-link or delivery storage.
-
-### Message channel reset command
-
-```python
-async def new_chat(context):
-    if context.request.session is not None:
-        await context.host.reset_session(context.request.session.isolation_key)
-        await context.reply("Started a new conversation.")
-```
-
-Telegram, Activity Protocol, and Discord can expose equivalent native commands when their protocols support them.
-
-## Follow-up Enhancements
-
-See [ADR-0028](../decisions/0028-hosting-linking-multicast-enhancements.md) for the deferred design covering:
-
-- cross-channel identity linking,
-- authorization and allowlists,
-- non-originating response delivery,
-- active-channel routing,
-- multicast and all-linked delivery,
-- background runs and continuation tokens,
-- durable delivery runners,
-- retry/replay semantics, and
-- payload serialization.
-
-Those enhancements must layer on top of this v1 contract without requiring v1 users to adopt them.
-
-## Validation Gates
-
-The Python implementation should be considered complete when:
-
-- a sample uses one `AgentFrameworkHost` with multiple channels and no manual Starlette route composition,
-- each current channel has contract tests for route contribution, lifecycle, request parsing, hooks, and originating response rendering,
-- session tests prove shared `isolation_key` values share an `AgentSession` and `reset_session` rotates it,
-- workflow tests or samples use explicit `checkpoint_location`,
-- Foundry isolation middleware is covered by integration or contract tests,
-- no v1 package exposes the removed linking, multicast, durable-runner, or continuation APIs, and
-- this spec and ADR-0027 remain aligned.
+- `SessionStore` plain get/set/delete behavior;
+- `AgentState` target resolution, target caching, and get-or-create session behavior;
+- `WorkflowState` target resolution for direct workflows, factories, `WorkflowBuilder`, and orchestration-style builders;
+- Responses request parsing and option remapping;
+- Responses session id extraction;
+- Responses response rendering, including rich output item mapping;
+- Responses streaming SSE rendering;
+- HTTP round-trip tests showing a native FastAPI route using `AgentState` and Responses helpers;
+- sample type checking for the local Responses sample.
+- Telegram update parsing, chat/session/command/media extraction, final
+  rendering, and streaming edit rendering;
+- sample type checking for the local Telegram polling and webhook entry points.

dotnet/Directory.Packages.props

@@ -11,8 +11,8 @@
   </PropertyGroup>
   <ItemGroup>
     <!-- Aspire.* -->
-    <PackageVersion Include="Anthropic" Version="12.20.0" />
-    <PackageVersion Include="Anthropic.Foundry" Version="0.6.0" />
+    <PackageVersion Include="Anthropic" Version="12.35.1" />
+    <PackageVersion Include="Anthropic.Foundry" Version="0.7.1" />
     <PackageVersion Include="Aspire.Hosting" Version="$(AspireAppHostSdkVersion)" />
     <PackageVersion Include="Aspire.Azure.AI.OpenAI" Version="13.0.0-preview.1.25560.3" />
     <PackageVersion Include="Aspire.Azure.AI.Inference" Version="13.1.0-preview.1.25616.3" />
@@ -23,14 +23,14 @@
     <PackageVersion Include="CommunityToolkit.Aspire.OllamaSharp" Version="13.0.0" />
     <PackageVersion Include="MessagePack" Version="3.1.7" /> <!-- Transitive dependency of Aspire pinned to newer version due to vulnerability in 2.5.192 -->
     <!-- Azure.* -->
-    <PackageVersion Include="Azure.AI.AgentServer.Core" Version="1.0.0-beta.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.AI.AgentServer.Core" Version="1.0.0-beta.26" />
+    <PackageVersion Include="Azure.AI.AgentServer.Invocations" Version="1.0.0-beta.5" />
+    <PackageVersion Include="Azure.AI.AgentServer.Responses" Version="1.0.0-beta.6" />
     <PackageVersion Include="Azure.Search.Documents" Version="12.0.0" />
-    <PackageVersion Include="Azure.AI.Projects" Version="2.1.0-beta.3" />
+    <PackageVersion Include="Azure.AI.Projects" Version="2.1.0-beta.4" />
     <PackageVersion Include="Azure.AI.Agents.Persistent" Version="1.2.0-beta.10" />
     <PackageVersion Include="Azure.AI.OpenAI" Version="2.9.0-beta.1" />
-    <PackageVersion Include="Azure.Core" Version="1.57.0" />
+    <PackageVersion Include="Azure.Core" Version="1.60.0" />
     <PackageVersion Include="Azure.Identity" Version="1.21.0" />
     <PackageVersion Include="DotNetEnv" Version="3.1.1" />
     <PackageVersion Include="Azure.Monitor.OpenTelemetry.Exporter" Version="1.5.0" />
@@ -42,18 +42,24 @@
     <!-- Newtonsoft.Json -->
     <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
     <!-- System.* -->
-    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.8" />
+    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.9" />
     <PackageVersion Include="Microsoft.Bcl.HashCode" Version="6.0.0" />
     <PackageVersion Include="Microsoft.Bcl.Memory" Version="10.0.5" />
-    <PackageVersion Include="System.ClientModel" Version="1.13.0" />
+    <PackageVersion Include="System.ClientModel" Version="1.14.0" />
     <PackageVersion Include="System.CodeDom" Version="10.0.0" />
     <PackageVersion Include="System.Collections.Immutable" Version="10.0.1" />
     <PackageVersion Include="System.CommandLine" Version="2.0.0-rc.2.25502.107" />
-    <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="10.0.8" />
+    <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="10.0.9" />
     <PackageVersion Include="System.Linq.AsyncEnumerable" Version="10.0.5" />
     <PackageVersion Include="System.Net.Http.Json" Version="10.0.0" />
-    <PackageVersion Include="System.Net.ServerSentEvents" Version="10.0.5" />
-    <PackageVersion Include="System.Text.Json" Version="10.0.8" />
+    <PackageVersion Include="System.Net.ServerSentEvents" Version="10.0.8" />
+    <!-- AG-UI .NET SDK packages (published by the AG-UI team). -->
+    <PackageVersion Include="AGUI.Abstractions" Version="0.0.3" />
+    <PackageVersion Include="AGUI.Formatting" Version="0.0.3" />
+    <PackageVersion Include="AGUI.Protobuf" Version="0.0.3" />
+    <PackageVersion Include="AGUI.Client" Version="0.0.3" />
+    <PackageVersion Include="AGUI.Server" Version="0.0.3" />
+    <PackageVersion Include="System.Text.Json" Version="10.0.9" />
     <PackageVersion Include="System.Threading.Channels" Version="10.0.8" />
     <PackageVersion Include="System.Threading.Tasks.Extensions" Version="4.6.3" />
     <PackageVersion Include="System.Net.Security" Version="4.3.2" />
@@ -70,7 +76,8 @@
     <!-- Microsoft.AspNetCore.* -->
     <PackageVersion Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.0" />
     <PackageVersion Include="Microsoft.AspNetCore.Authentication.OpenIdConnect" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.9" />
+    <PackageVersion Include="Microsoft.OpenApi" Version="2.7.5" /> <!-- Pin patched OpenAPI.NET to remediate GHSA-v5pm-xwqc-g5wc -->
     <PackageVersion Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.0.0" />
     <!-- Microsoft.Extensions.* -->
     <PackageVersion Include="Microsoft.Extensions.AI" Version="10.6.0" />
@@ -87,12 +94,12 @@
     <PackageVersion Include="Microsoft.Extensions.Configuration.Json" Version="10.0.1" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.1" />
     <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.1" />
-    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.8" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.9" />
     <PackageVersion Include="Microsoft.Extensions.FileSystemGlobbing" Version="10.0.6" />
     <PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.1" />
     <PackageVersion Include="Microsoft.Extensions.Http.Resilience" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Logging" Version="10.0.1" />
-    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.8" />
+    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.9" />
     <PackageVersion Include="Microsoft.Extensions.Logging.Console" Version="10.0.1" />
     <PackageVersion Include="Microsoft.Extensions.ServiceDiscovery" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.VectorData.Abstractions" Version="9.7.0" />
@@ -100,7 +107,7 @@
     <PackageVersion Include="Microsoft.SemanticKernel.Connectors.InMemory" Version="1.67.0-preview" />
     <PackageVersion Include="Microsoft.SemanticKernel.Connectors.Qdrant" Version="1.67.0-preview" />
     <!-- Agent SDKs -->
-    <PackageVersion Include="GitHub.Copilot.SDK" Version="1.0.0" />
+    <PackageVersion Include="GitHub.Copilot.SDK" Version="1.0.5" />
     <PackageVersion Include="Microsoft.Agents.CopilotStudio.Client" Version="1.3.171-beta" />
     <!-- M365 Agents SDK -->
     <PackageVersion Include="AdaptiveCards" Version="3.1.0" />
@@ -120,7 +127,7 @@
     <PackageVersion Include="OllamaSharp" Version="5.4.8" />
     <PackageVersion Include="OpenAI" Version="2.10.0" />
     <!-- Identity -->
-    <PackageVersion Include="Microsoft.Identity.Client.Extensions.Msal" Version="4.83.1" />
+    <PackageVersion Include="Microsoft.Identity.Client.Extensions.Msal" Version="4.84.2" />
     <!-- Workflows -->
     <PackageVersion Include="Microsoft.Agents.ObjectModel" Version="2026.2.4.1" />
     <PackageVersion Include="Microsoft.Agents.ObjectModel.Json" Version="2026.2.4.1" />

dotnet/agent-framework-dotnet.slnx

@@ -122,6 +122,8 @@
   <Folder Name="/Samples/02-agents/Harness/">
     <File Path="samples/02-agents/Harness/README.md" />
     <Project Path="samples/02-agents/Harness/BuildYourOwnClaw/Claw_Step01_MeetYourClaw/Claw_Step01_MeetYourClaw.csproj" />
+    <Project Path="samples/02-agents/Harness/BuildYourOwnClaw/Claw_Step02_WorkingWithData/Claw_Step02_WorkingWithData.csproj" />
+    <Project Path="samples/02-agents/Harness/BuildYourOwnClaw/Claw_Step03_ScalingCapabilities/Claw_Step03_ScalingCapabilities.csproj" />
     <Project Path="samples/02-agents/Harness/ConsoleReactiveComponents/ConsoleReactiveComponents.csproj" />
     <Project Path="samples/02-agents/Harness/ConsoleReactiveFramework/ConsoleReactiveFramework.csproj" />
     <Project Path="samples/02-agents/Harness/Harness_Shared_Console/Harness_Shared_Console.csproj" />
@@ -198,6 +200,7 @@
     <Project Path="samples/02-agents/AgentWithMemory/AgentWithMemory_Step03_MemoryUsingValkey_Bedrock/AgentWithMemory_Step03_MemoryUsingValkey_Bedrock.csproj" />
     <Project Path="samples/02-agents/AgentWithMemory/AgentWithMemory_Step04_MemoryUsingFoundry/AgentWithMemory_Step04_MemoryUsingFoundry.csproj" />
     <Project Path="samples/02-agents/AgentWithMemory/AgentWithMemory_Step05_BoundedChatHistory/AgentWithMemory_Step05_BoundedChatHistory.csproj" />
+    <Project Path="samples/02-agents/AgentWithMemory/AgentWithMemory_Step06_MemoryUsingAgentMemory/AgentWithMemory_Step06_MemoryUsingAgentMemory.csproj" />
   </Folder>
   <Folder Name="/Samples/02-agents/AgentProviders/openai/">
     <File Path="samples/02-agents/AgentProviders/openai/README.md" />
@@ -368,6 +371,7 @@
     <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Simple/HostedWorkflowSimple.csproj" />
   </Folder>
   <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/Hosted-Toolbox-AuthPaths-Client/Hosted-Toolbox-AuthPaths-Client.csproj" />
     <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SessionFilesClient/SessionFilesClient.csproj" />
     <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent/SimpleAgent.csproj" />
   </Folder>
@@ -603,7 +607,6 @@
     <Project Path="src/Aspire.Hosting.AgentFramework.DevUI/Aspire.Hosting.AgentFramework.DevUI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.A2A/Microsoft.Agents.AI.A2A.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Abstractions/Microsoft.Agents.AI.Abstractions.csproj" />
-    <Project Path="src/Microsoft.Agents.AI.AGUI/Microsoft.Agents.AI.AGUI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Anthropic/Microsoft.Agents.AI.Anthropic.csproj" />
     <Project Path="src/Microsoft.Agents.AI.AzureAI.Persistent/Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
     <Project Path="src/Microsoft.Agents.AI.CopilotStudio/Microsoft.Agents.AI.CopilotStudio.csproj" />
@@ -662,7 +665,6 @@
     <Project Path="tests/Aspire.Hosting.AgentFramework.DevUI.UnitTests/Aspire.Hosting.AgentFramework.DevUI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.A2A.UnitTests/Microsoft.Agents.AI.A2A.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Abstractions.UnitTests/Microsoft.Agents.AI.Abstractions.UnitTests.csproj" />
-    <Project Path="tests/Microsoft.Agents.AI.AGUI.UnitTests/Microsoft.Agents.AI.AGUI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Anthropic.UnitTests/Microsoft.Agents.AI.Anthropic.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.AzureAI.Persistent.UnitTests/Microsoft.Agents.AI.AzureAI.Persistent.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.CosmosNoSql.UnitTests/Microsoft.Agents.AI.CosmosNoSql.UnitTests.csproj" />

dotnet/agent-framework-release.slnf

@@ -4,7 +4,6 @@
     "projects": [
       "src\\Microsoft.Agents.AI.A2A\\Microsoft.Agents.AI.A2A.csproj",
       "src\\Microsoft.Agents.AI.Abstractions\\Microsoft.Agents.AI.Abstractions.csproj",
-      "src\\Microsoft.Agents.AI.AGUI\\Microsoft.Agents.AI.AGUI.csproj",
       "src\\Microsoft.Agents.AI.Anthropic\\Microsoft.Agents.AI.Anthropic.csproj",
       "src\\Microsoft.Agents.AI.GitHub.Copilot\\Microsoft.Agents.AI.GitHub.Copilot.csproj",
       "src\\Microsoft.Agents.AI.Harness\\Microsoft.Agents.AI.Harness.csproj",
@@ -29,6 +28,7 @@
       "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.Valkey\\Microsoft.Agents.AI.Valkey.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",

dotnet/eng/verify-samples/AgentsSamples.cs

@@ -335,8 +335,8 @@ internal static class AgentsSamples
         {
             Name = "Agent_Step01_FileBasedSkills",
             ProjectPath = "samples/02-agents/AgentSkills/Agent_Step01_FileBasedSkills",
-            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             MustContain =
             [
                 "Converting units with file-based skills",
@@ -354,8 +354,8 @@ internal static class AgentsSamples
         {
             Name = "Agent_Step06_McpBasedSkills",
             ProjectPath = "samples/02-agents/AgentSkills/Agent_Step06_McpBasedSkills",
-            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
             MustContain =
             [
                 "Discovering MCP-based skills",
@@ -427,6 +427,15 @@ internal static class AgentsSamples
             ],
         },
 
+        new SampleDefinition
+        {
+            Name = "AgentWithMemory_Step06_MemoryUsingAgentMemory",
+            ProjectPath = "samples/02-agents/AgentWithMemory/AgentWithMemory_Step06_MemoryUsingAgentMemory",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_API_KEY", "FOUNDRY_MODEL", "FOUNDRY_EMBEDDING_MODEL", "NEO4J_URI", "NEO4J_USER", "NEO4J_PASSWORD"],
+            SkipReason = "Requires a running Neo4j instance; standalone sample outside the repo's CPM build.",
+        },
+
         // ── AgentWithRAG ────────────────────────────────────────────────────
 
         new SampleDefinition
@@ -701,7 +710,7 @@ internal static class AgentsSamples
             OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
             ExpectedOutputDescription =
             [
-                "The output should contain a list of countries or information about countries that use the EUR currency.",
+                "The output should contain the current EUR exchange rate against USD and GBP as numeric values.",
                 "The output should not contain error messages or stack traces.",
             ],
         },
@@ -837,7 +846,7 @@ internal static class AgentsSamples
             ProjectPath = "samples/02-agents/Agents/Agent_Step15_DeepResearch",
             RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT", "AZURE_AI_MODEL_DEPLOYMENT_NAME", "AZURE_AI_BING_CONNECTION_ID"],
             OptionalEnvironmentVariables = ["AZURE_AI_REASONING_DEPLOYMENT_NAME"],
-            SkipReason = "Requires Azure AI Foundry project with Bing search connection.",
+            SkipReason = "Requires Microsoft Foundry project with Bing search connection.",
         },
 
         new SampleDefinition
@@ -1052,8 +1061,8 @@ internal static class AgentsSamples
         {
             Name = "FoundryAgent_Step15_ComputerUse",
             ProjectPath = "samples/02-agents/AgentProviders/foundry/Agent_Step15_ComputerUse",
-            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
-            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT", "AZURE_AI_COMPUTER_USE_DEPLOYMENT_NAME"],
+            OptionalEnvironmentVariables = [],
             ExpectedOutputDescription = ["The output should show a computer automation session processing simulated browser screenshots with iteration steps and a final response describing search results."],
         },
 

dotnet/eng/verify-samples/Program.cs

@@ -19,7 +19,7 @@
 // Pre-build the solution before running, or pass --build to avoid missing build output failures.
 //
 // Required environment variables (for AI-powered verification):
-//   FOUNDRY_PROJECT_ENDPOINT  — Your Azure AI Foundry project endpoint
+//   FOUNDRY_PROJECT_ENDPOINT  — Your Microsoft Foundry project endpoint
 //   FOUNDRY_MODEL             — Model deployment name (optional, defaults to gpt-5.4-mini)
 
 using System.Diagnostics;

dotnet/eng/verify-samples/WorkflowSamples.cs

@@ -130,7 +130,7 @@ internal static class WorkflowSamples
             ProjectPath = "samples/03-workflows/Agents/FoundryAgent",
             RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
             OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
-            SkipReason = "Requires Azure AI Foundry project endpoint.",
+            SkipReason = "Requires Microsoft Foundry project endpoint.",
         },
 
         new SampleDefinition
@@ -396,8 +396,8 @@ internal static class WorkflowSamples
             ProjectPath = "samples/03-workflows/Declarative/CustomerSupport",
             RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
             OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
-            Inputs = ["My laptop won't start"],
-            InputDelayMs = 3000,
+            Inputs = ["My laptop won't start", "The laptop is now working, thank you!"],
+            InputDelayMs = 5000,
             ExpectedOutputDescription = ["The output should show a customer support workflow processing a laptop issue, with agent responses providing troubleshooting or support."],
         },
 
@@ -443,7 +443,7 @@ internal static class WorkflowSamples
             ProjectPath = "samples/03-workflows/Declarative/InputArguments",
             RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
             OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
-            Inputs = ["I'd like to visit Seattle", "EXIT"],
+            Inputs = ["I'd like to visit Seattle", "Seattle, WA", "EXIT"],
             InputDelayMs = 8000,
             ExpectedOutputDescription = ["The output should show a workflow capturing location input and providing travel-related information about Seattle."],
         },

dotnet/nuget/nuget-package.props

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -14,7 +14,7 @@ WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
 builder.Services.AddHttpClient().AddLogging();
 builder.Services.ConfigureHttpJsonOptions(options =>
     options.SerializerOptions.TypeInfoResolverChain.Add(SampleJsonSerializerContext.Default));
-builder.Services.AddAGUI();
+builder.Services.AddAGUIServer();
 
 // WARNING: When adding session persistence (e.g., WithInMemorySessionStore), or running in production,
 // make sure to also register a SessionIsolationKeyProvider to scope sessions by principal in multi-user
@@ -93,7 +93,7 @@ ChatClientAgent agent = chatClient.AsAIAgent(
     tools: tools);
 
 // Map the AG-UI agent endpoint
-app.MapAGUI("/", agent);
+app.MapAGUIServer("/", agent);
 
 await app.RunAsync();
 

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

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

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

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

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

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

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

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

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

@@ -1,8 +1,8 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 using System.Text.Json;
+using AGUI.Client;
 using Microsoft.Agents.AI;
-using Microsoft.Agents.AI.AGUI;
 using Microsoft.Extensions.AI;
 
 string serverUrl = Environment.GetEnvironmentVariable("AGUI_SERVER_URL") ?? "http://localhost:5100";
@@ -13,7 +13,7 @@ using HttpClient httpClient = new()
     Timeout = TimeSpan.FromSeconds(60)
 };
 
-AGUIChatClient chatClient = new(httpClient, serverUrl);
+AGUIChatClient chatClient = new(new(httpClient, serverUrl));
 
 // Create agent
 ChatClientAgent baseAgent = chatClient.AsAIAgent(

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

@@ -25,7 +25,7 @@ builder.Services.AddHttpLogging(logging =>
 builder.Services.AddHttpClient().AddLogging();
 builder.Services.ConfigureHttpJsonOptions(options =>
     options.SerializerOptions.TypeInfoResolverChain.Add(ApprovalJsonContext.Default));
-builder.Services.AddAGUI();
+builder.Services.AddAGUIServer();
 
 // WARNING: When adding session persistence (e.g., WithInMemorySessionStore), or running in production,
 // make sure to also register a SessionIsolationKeyProvider to scope sessions by principal in multi-user
@@ -73,5 +73,5 @@ ChatClientAgent baseAgent = openAIChatClient.AsAIAgent(
 // Wrap with ServerFunctionApprovalAgent
 var agent = new ServerFunctionApprovalAgent(baseAgent, jsonOptions.SerializerOptions);
 
-app.MapAGUI("/", agent);
+app.MapAGUIServer("/", agent);
 await app.RunAsync();

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

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

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

@@ -2,8 +2,9 @@
 
 using System.Text.Json;
 using System.Text.Json.Serialization;
+using AGUI.Abstractions;
+using AGUI.Client;
 using Microsoft.Agents.AI;
-using Microsoft.Agents.AI.AGUI;
 using Microsoft.Extensions.AI;
 using RecipeClient;
 
@@ -17,7 +18,7 @@ using HttpClient httpClient = new()
     Timeout = TimeSpan.FromSeconds(60)
 };
 
-AGUIChatClient chatClient = new(httpClient, serverUrl);
+AGUIChatClient chatClient = new(new(httpClient, serverUrl));
 
 AIAgent baseAgent = chatClient.AsAIAgent(
     name: "recipe-client",
@@ -65,7 +66,7 @@ try
 
         // Stream the response
         bool isFirstUpdate = true;
-        string? sessionId = null;
+        string? threadId = null;
         bool stateReceived = false;
 
         Console.WriteLine();
@@ -77,9 +78,11 @@ try
             // First update indicates run started
             if (isFirstUpdate)
             {
-                sessionId = chatUpdate.ConversationId;
+                // AGUIChatClient is stateless and never surfaces a ConversationId; the thread
+                // id is carried on the AG-UI RUN_STARTED event's raw representation.
+                threadId = (chatUpdate.RawRepresentation as RunStartedEvent)?.ThreadId;
                 Console.ForegroundColor = ConsoleColor.Yellow;
-                Console.WriteLine($"[Run Started - Session: {chatUpdate.ConversationId}, Run: {chatUpdate.ResponseId}]");
+                Console.WriteLine($"[Run Started - Thread: {threadId}, Run: {chatUpdate.ResponseId}]");
                 Console.ResetColor();
                 isFirstUpdate = false;
             }
@@ -113,7 +116,7 @@ try
         }
 
         Console.ForegroundColor = ConsoleColor.Green;
-        Console.WriteLine($"\n[Run Finished - Session: {sessionId}]");
+        Console.WriteLine($"\n[Run Finished - Thread: {threadId}]");
         Console.ResetColor();
 
         // Display final state if received

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

@@ -12,7 +12,7 @@ WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
 builder.Services.AddHttpClient().AddLogging();
 builder.Services.ConfigureHttpJsonOptions(options =>
     options.SerializerOptions.TypeInfoResolverChain.Add(RecipeSerializerContext.Default));
-builder.Services.AddAGUI();
+builder.Services.AddAGUIServer();
 
 // Configure to listen on port 8888
 builder.WebHost.UseUrls("http://localhost:8888");
@@ -61,6 +61,6 @@ AIAgent baseAgent = chatClient.AsAIAgent(
 AIAgent agent = new SharedStateAgent(baseAgent, jsonOptions.SerializerOptions);
 
 // Map the AG-UI agent endpoint
-app.MapAGUI("/", agent);
+app.MapAGUIServer("/", agent);
 
 await app.RunAsync();

dotnet/samples/02-agents/AGUI/Step05_StateManagement/Server/SharedStateAgent.cs

@@ -2,6 +2,8 @@
 
 using System.Runtime.CompilerServices;
 using System.Text.Json;
+using AGUI.Abstractions;
+using AGUI.Server;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 
@@ -34,10 +36,9 @@ internal sealed class SharedStateAgent : DelegatingAIAgent
         [EnumeratorCancellation] CancellationToken cancellationToken = default)
     {
         // Check if the client sent state in the request
-        if (options is not ChatClientAgentRunOptions { ChatOptions.AdditionalProperties: { } properties } chatRunOptions ||
-            !properties.TryGetValue("ag_ui_state", out object? stateObj) ||
-            stateObj is not JsonElement state ||
-            state.ValueKind != JsonValueKind.Object)
+        if (options is not ChatClientAgentRunOptions { ChatOptions: { } chatOptions } chatRunOptions ||
+            !chatOptions.TryGetRunAgentInput(out RunAgentInput? agentInput) ||
+            agentInput.State is not { ValueKind: JsonValueKind.Object } state)
         {
             // No state management requested, pass through to inner agent
             await foreach (var update in this.InnerAgent.RunStreamingAsync(messages, session, options, cancellationToken).ConfigureAwait(false))

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

@@ -12,7 +12,7 @@ using Microsoft.Extensions.AI;
 string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
 string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
 
-const string AgentInstructions = "You are a helpful assistant that can use the countries API to retrieve information about countries by their currency code.";
+const string AgentInstructions = "You are a helpful assistant that can retrieve the latest currency exchange rates using the Frankfurter API. Always call the API to get live data rather than guessing.";
 // 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.
@@ -25,36 +25,46 @@ AIAgent agent = aiProjectClient.AsAIAgent(deploymentName,
     name: "OpenAPIToolsAgent",
     tools: [openApiTool]);
 
-// Run the agent with a question about countries
-Console.WriteLine(await agent.RunAsync("What countries use the Euro (EUR) as their currency? Please list them."));
+// Run the agent with a question about EUR exchange rates
+Console.WriteLine(await agent.RunAsync("What is the latest EUR exchange rate against the US Dollar (USD) and British Pound (GBP)?"));
 
 OpenApiFunctionDefinition CreateOpenAPIFunctionDefinition()
 {
-    // A simple OpenAPI specification for the REST Countries API
-    const string CountriesOpenApiSpec = """
+    // OpenAPI spec for Frankfurter — a free, no-auth exchange rate API backed by ECB data.
+    // See https://www.frankfurter.dev/ for documentation.
+    const string FrankfurterOpenApiSpec = """
 {
   "openapi": "3.1.0",
   "info": {
-    "title": "REST Countries API",
-    "description": "Retrieve information about countries by currency code",
-    "version": "v3.1"
+    "title": "Frankfurter Exchange Rate API",
+    "description": "Free currency exchange rates from the European Central Bank",
+    "version": "v1"
   },
   "servers": [
     {
-      "url": "https://restcountries.com/v3.1"
+      "url": "https://api.frankfurter.dev/v1"
     }
   ],
   "paths": {
-    "/currency/{currency}": {
+    "/latest": {
       "get": {
-        "description": "Get countries that use a specific currency code (e.g., USD, EUR, GBP)",
-        "operationId": "GetCountriesByCurrency",
+        "description": "Get the latest exchange rates for a given base currency",
+        "operationId": "GetLatestExchangeRates",
         "parameters": [
           {
-            "name": "currency",
-            "in": "path",
-            "description": "Currency code (e.g., USD, EUR, GBP)",
-            "required": true,
+            "name": "from",
+            "in": "query",
+            "description": "Base currency code (e.g. EUR, USD, GBP). Defaults to EUR.",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "to",
+            "in": "query",
+            "description": "Comma-separated list of target currency codes (e.g. USD,GBP,JPY).",
+            "required": false,
             "schema": {
               "type": "string"
             }
@@ -62,20 +72,14 @@ OpenApiFunctionDefinition CreateOpenAPIFunctionDefinition()
         ],
         "responses": {
           "200": {
-            "description": "Successful response with list of countries",
+            "description": "Latest exchange rates",
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "array",
-                  "items": {
-                    "type": "object"
-                  }
+                  "type": "object"
                 }
               }
             }
-          },
-          "404": {
-            "description": "No countries found for the currency"
           }
         }
       }
@@ -84,12 +88,11 @@ OpenApiFunctionDefinition CreateOpenAPIFunctionDefinition()
 }
 """;
 
-    // Create the OpenAPI function definition
     return new(
-        "get_countries",
-        BinaryData.FromString(CountriesOpenApiSpec),
+        "get_exchange_rates",
+        BinaryData.FromString(FrankfurterOpenApiSpec),
         new OpenAPIAnonymousAuthenticationDetails())
     {
-        Description = "Retrieve information about countries by currency code"
+        Description = "Get live currency exchange rates from the European Central Bank via Frankfurter"
     };
 }

dotnet/samples/02-agents/AgentProviders/foundry/Agent_Step17_OpenAPITools/README.md

@@ -5,7 +5,7 @@ This sample shows how to use OpenAPI tools with a `ChatClientAgent` using the Re
 ## What this sample demonstrates
 
 - Defining an OpenAPI specification inline
-- Creating an `OpenAPIFunctionDefinition` for the REST Countries API
+- Creating an `OpenAPIFunctionDefinition` for the Frankfurter exchange rate API
 - Using `FoundryAITool.CreateOpenApiTool()` with `ChatClientAgent`
 - Server-side execution of OpenAPI tool calls
 

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

@@ -90,7 +90,7 @@ static async Task<string> CreateSampleToolboxAsync(string name, string endpoint,
     // Delete existing toolbox if present (ignore 404).
     try
     {
-        await toolboxClient.DeleteToolboxAsync(name);
+        await toolboxClient.DeleteAsync(name);
         Console.WriteLine($"Deleted existing toolbox '{name}'");
     }
     catch (ClientResultException ex) when (ex.Status == 404)
@@ -99,12 +99,13 @@ static async Task<string> CreateSampleToolboxAsync(string name, string endpoint,
     }
 
     // Create a fresh version with a single MCP tool.
-    ProjectsAgentTool mcpTool = ProjectsAgentTool.AsProjectTool(ResponseTool.CreateMcpTool(
-        serverLabel: "api-specs",
-        serverUri: new Uri("https://gitmcp.io/Azure/azure-rest-api-specs"),
-        toolCallApprovalPolicy: new McpToolCallApprovalPolicy(GlobalMcpToolCallApprovalPolicy.NeverRequireApproval)));
+    MCPToolboxTool mcpTool = new("api-specs")
+    {
+        ServerUri = new Uri("https://gitmcp.io/Azure/azure-rest-api-specs"),
+        ToolCallApprovalPolicy = new McpToolCallApprovalPolicy(GlobalMcpToolCallApprovalPolicy.NeverRequireApproval),
+    };
 
-    ToolboxVersion created = (await toolboxClient.CreateToolboxVersionAsync(
+    ToolboxVersion created = (await toolboxClient.CreateVersionAsync(
         name: name,
         tools: [mcpTool],
         description: "Sample toolbox with an MCP tool — created by Agent_Step25 sample.")).Value;

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

@@ -64,6 +64,43 @@ AgentResponse response = await agent.RunAsync("Write a small .NET 10 C# hello wo
 Console.WriteLine(response);
 ```
 
+## Approving or denying tool execution
+
+The GitHub Copilot SDK owns the tool-calling loop for this provider, so approval is enforced through the SDK's
+native pre-execution hook rather than the Agent Framework chat-client approval round-trip.
+
+When you register a tool wrapped in `ApprovalRequiredAIFunction`, `GitHubCopilotAgent` installs a default
+`SessionConfig.Hooks.OnPreToolUse` hook that returns `"ask"` for that tool and defers (`null`) for all other tools.
+The `"ask"` decision routes to your `SessionConfig.OnPermissionRequest` handler, where you approve or deny the call
+(this also fires even for tools configured with `SkipPermission = true`):
+
+```csharp
+using GitHub.Copilot;
+
+AIFunction deleteFile = AIFunctionFactory.Create(DeleteFile, "DeleteFile", "Deletes a file.");
+
+SessionConfig sessionConfig = new()
+{
+    // Wrapping the tool marks it approval-required; the agent turns this into an "ask" at OnPreToolUse.
+    Tools = [new ApprovalRequiredAIFunction(deleteFile)],
+
+    // OnPermissionRequest decides the "asked" tools (and Copilot's built-in shell/file/URL prompts).
+    OnPermissionRequest = (request, invocation) =>
+    {
+        // Surface to a human, check policy, etc.
+        bool approved = AskHuman(request);
+        return Task.FromResult(approved
+            ? PermissionDecision.ApproveOnce()
+            : PermissionDecision.Reject("Denied by user."));
+    },
+};
+```
+
+> **⚠️ If you provide your own `OnPreToolUse` hook**, it takes precedence and the agent does **not** install its
+> default approval hook. In that case **you are fully responsible** for enforcing approval — including for any
+> `ApprovalRequiredAIFunction` you register (e.g. by returning a `"deny"` or `"ask"` `PreToolUseHookOutput`). The
+> agent logs a warning when it detects an approval-required tool that your hook must handle.
+
 ## Streaming Responses
 
 To get streaming responses:

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

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

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

@@ -38,7 +38,17 @@ AIAgent agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredentia
             Instructions = "You are a helpful assistant that can convert units.",
         },
         AIContextProviders = [skillsProvider],
-    });
+    })
+    .AsBuilder()
+    .UseToolApproval(new ToolApprovalAgentOptions
+    {
+        // NOTE: Auto-approving all skill tools is done here for simplicity in
+        // this demonstration. In production, you should prompt the user before
+        // allowing script execution. See Agent_Step07_SkillsAutoApproval for a
+        // walkthrough of the full approval flow.
+        AutoApprovalRules = [AgentSkillsProvider.AllToolsAutoApprovalRule],
+    })
+    .Build();
 
 // --- Example: Unit conversion ---
 Console.WriteLine("Converting units with file-based skills");

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

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

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

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

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

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

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

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

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

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

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

@@ -63,7 +63,17 @@ AIAgent agent = new AIProjectClient(new Uri(openAiEndpoint), new DefaultAzureCre
             Instructions = "You are a helpful assistant. Use available skills to answer the user.",
         },
         AIContextProviders = [skillsProvider],
-    });
+    })
+    .AsBuilder()
+    .UseToolApproval(new ToolApprovalAgentOptions
+    {
+        // NOTE: Auto-approving all skill tools is done here for simplicity in
+        // this demonstration. In production, you should prompt the user before
+        // allowing skill tools to execute. See Agent_Step07_SkillsAutoApproval
+        // for a walkthrough of the full approval flow.
+        AutoApprovalRules = [AgentSkillsProvider.AllToolsAutoApprovalRule],
+    })
+    .Build();
 
 // --- Run ---
 Console.WriteLine(new string('-', 60));

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

@@ -32,3 +32,12 @@ $env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-5.4-mini"
 ```powershell
 dotnet run
 ```
+
+## Security Considerations
+
+Discovering skills over MCP means an external MCP server controls what skill content (including
+instructions and, for archive-type entries, extracted files) reaches the agent. A compromised or
+untrustworthy server could return adversarial content designed to manipulate the agent (indirect
+prompt injection) or to exfiltrate data through skill instructions/scripts. Only connect `UseMcpSkills`
+to MCP servers you have vetted and trust, and keep the conservative archive size/file-count limits in
+`AgentMcpSkillsSourceOptions` unless you have a specific reason to raise them.

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

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>

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

@@ -66,6 +66,18 @@ When using multiple providers (e.g., skills + file access), combine their rules
 })
 ```
 
+## ⚠️ Security: avoid tool-name collisions
+
+Built-in auto-approval rules match tool calls **solely by tool name**. A rule cannot tell the
+provider's own tool apart from any other registered tool that happens to share the same name. If a
+different tool — especially one with a caller-configurable name, such as the Harness shell tool
+(`HarnessAgentOptions.ShellToolName`) — is registered under a name that one of these rules approves
+(e.g. `load_skill`, `read_skill_resource`, `run_skill_script`, or the `file_access_*` names), that
+tool will be **silently auto-approved**, bypassing the human approval boundary.
+
+When using auto-approval rules, ensure no other tool's name collides with the reserved names the
+rules approve, and never assign a configurable tool name that matches one of them.
+
 ## Skills Included
 
 ### unit-converter

dotnet/samples/02-agents/AgentWithMemory/AgentWithMemory_Step06_MemoryUsingAgentMemory/AgentWithMemory_Step06_MemoryUsingAgentMemory.csproj

@@ -0,0 +1,78 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <!--
+    This project is part of the repo's solution and targets .NET 10 like the rest of the repo, but it
+    intentionally opts out of Central Package Management and source-referencing Microsoft.Agents.AI:
+    it consumes the *published* AgentMemory NuGet packages (which target Microsoft.Agents.AI 1.9.0)
+    instead. Run it with `dotnet run` from this folder.
+
+    ManagePackageVersionsCentrally is off, but dotnet/Directory.Packages.props still unconditionally
+    merges its repo-wide analyzer PackageReference items (no Version, resolved via CPM) into every
+    project that imports it — including this one. With CPM off here those versions can't resolve
+    (NU1015), so each is removed and re-added with an explicit version below (matching
+    AgentWithRAG_Step05_Neo4jGraphRAG, which hits the same issue). xunit.analyzers/Moq.Analyzers are
+    dropped rather than re-added since this project has no test code.
+  -->
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <ManagePackageVersionsCentrally>false</ManagePackageVersionsCentrally>
+    <RootNamespace>AgentMemoryShoppingAssistant</RootNamespace>
+    <!-- OPENAI001: the OpenAIClient(AuthenticationPolicy, options) ctor used for keyless Azure auth is
+         marked experimental in the OpenAI SDK (the MAF Foundry samples use the same pattern). -->
+    <NoWarn>$(NoWarn);OPENAI001</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Remove="Microsoft.CodeAnalysis.NetAnalyzers" />
+    <PackageReference Remove="Microsoft.VisualStudio.Threading.Analyzers" />
+    <PackageReference Remove="xunit.analyzers" />
+    <PackageReference Remove="Moq.Analyzers" />
+    <PackageReference Remove="Roslynator.Analyzers" />
+    <PackageReference Remove="Roslynator.CodeAnalysis.Analyzers" />
+    <PackageReference Remove="Roslynator.Formatting.Analyzers" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <!-- AgentMemory (published) — an unofficial .NET port of the Neo4j Labs agent-memory library + its
+         Microsoft Agent Framework adapter. -->
+    <PackageReference Include="AgentMemory" Version="1.2.0" />
+    <PackageReference Include="AgentMemory.AgentFramework" Version="1.2.0" />
+    <!-- Microsoft Agent Framework (matches AgentMemory's target) + the OpenAI/Foundry chat & embedding clients. -->
+    <PackageReference Include="Microsoft.Agents.AI" Version="1.9.0" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="10.5.1" />
+    <PackageReference Include="Azure.Identity" Version="1.21.0" />
+    <PackageReference Include="Microsoft.Extensions.Hosting" Version="9.0.17" />
+    <!-- Transitive dependency of Microsoft.Agents.AI; pinned explicitly (CPM is off here) because the
+         version it would otherwise resolve to, 1.12.0, has a known moderate severity vulnerability
+         (GHSA-g94r-2vxg-569j) that fails the repo's NuGet audit (NU1902 as error). Matches the version
+         pinned in dotnet/Directory.Packages.props. -->
+    <PackageReference Include="OpenTelemetry.Api" Version="1.15.3" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="10.0.100">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="Microsoft.VisualStudio.Threading.Analyzers" Version="17.14.15">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="Roslynator.Analyzers" Version="4.14.1">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="Roslynator.CodeAnalysis.Analyzers" Version="4.14.1">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="Roslynator.Formatting.Analyzers" Version="4.14.1">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+  </ItemGroup>
+
+</Project>

dotnet/samples/02-agents/AgentWithMemory/AgentWithMemory_Step06_MemoryUsingAgentMemory/ProductCatalog.cs

@@ -0,0 +1,195 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+using System.Text;
+using AgentMemory.Neo4j.Infrastructure;
+using Microsoft.Extensions.AI;
+using Neo4j.Driver;
+
+namespace AgentMemoryShoppingAssistant;
+
+/// <summary>
+/// A small retail product graph plus the shopping tools that query it — the .NET counterpart of the
+/// Python retail-assistant's <c>get_product_tools</c>. Products live in Neo4j as <c>:Product</c> nodes
+/// linked to <c>:ProductCategory</c> / <c>:ProductBrand</c> nodes, so recommendations and "related
+/// products" come from graph traversals. Cypher runs through the public <see cref="INeo4jTransactionRunner"/>
+/// seam. Exposed as <see cref="AIFunction"/>s so a real chat model can call them during a run — the same
+/// way <c>Neo4jMemoryContextProvider</c> surfaces the memory tools through <c>AIContext.Tools</c> when
+/// <c>ExposeMemoryToolsFromContextProvider</c> is enabled.
+/// </summary>
+public sealed class ProductCatalog(INeo4jTransactionRunner runner)
+{
+    private readonly INeo4jTransactionRunner _runner = runner;
+
+    private static readonly (string Name, string Category, string Brand, double Price, bool InStock, int Inventory, string Description, int Popularity)[] s_seed =
+    [
+        ("Nike Air Zoom Pegasus 40", "shoes",       "Nike",   130, true,  40, "Everyday running shoe with responsive cushioning.",   95),
+        ("Nike Revolution 7",        "shoes",       "Nike",    70, true,  60, "Lightweight, budget-friendly running shoe.",          80),
+        ("Adidas Ultraboost Light",  "shoes",       "Adidas",  190, true, 25, "Premium running shoe with Boost cushioning.",         90),
+        ("Asics Gel-Kayano 31",      "shoes",       "Asics",   165, false,  0, "Stability running shoe for overpronation.",           70),
+        ("Sony WH-1000XM5",          "electronics", "Sony",    350, true,  18, "Industry-leading noise-cancelling headphones.",       92),
+        ("Bose QuietComfort Ultra",  "electronics", "Bose",    330, true,  12, "Premium noise-cancelling over-ear headphones.",       85),
+        ("Apple AirPods Pro 2",      "electronics", "Apple",   250, true,  50, "Wireless earbuds with active noise cancellation.",    88),
+        ("Garmin Forerunner 265",    "electronics", "Garmin",  450, true,   9, "GPS running watch with training metrics.",            78),
+        ("Nike Dri-FIT Running Tee", "apparel",     "Nike",     35, true, 120, "Breathable, moisture-wicking running shirt.",         65),
+        ("Adidas Own the Run Jacket","apparel",     "Adidas",   80, true,  33, "Lightweight, water-repellent running jacket.",        60),
+    ];
+
+    /// <summary>Seeds the sample product graph (idempotent — safe to run every start).</summary>
+    public Task SeedAsync(CancellationToken ct = default) => this._runner.WriteAsync(async r =>
+    {
+        await r.RunAsync(
+            """
+            UNWIND $products AS row
+            MERGE (p:Product {name: row.name})
+              SET p.category = row.category, p.brand = row.brand, p.price = row.price,
+                  p.in_stock = row.in_stock, p.inventory = row.inventory,
+                  p.description = row.description, p.popularity = row.popularity
+            MERGE (c:ProductCategory {name: row.category})
+            MERGE (b:ProductBrand {name: row.brand})
+            MERGE (p)-[:IN_CATEGORY]->(c)
+            MERGE (p)-[:MADE_BY]->(b)
+            """,
+            new
+            {
+                products = s_seed.Select(p => (object)new Dictionary<string, object>
+                {
+                    ["name"] = p.Name, ["category"] = p.Category, ["brand"] = p.Brand, ["price"] = p.Price,
+                    ["in_stock"] = p.InStock, ["inventory"] = p.Inventory, ["description"] = p.Description,
+                    ["popularity"] = p.Popularity,
+                }).ToList(),
+            });
+    }, ct);
+
+    // ── Tools (also usable directly in the scripted demo) ────────────────────────────────────────
+
+    [Description("Search the product catalog for items matching a query, with optional category, brand, and max-price filters.")]
+    public Task<string> SearchProductsAsync(
+        [Description("What the customer is looking for, e.g. 'running shoes'.")] string query,
+        [Description("Optional category filter: shoes, electronics, apparel.")] string? category = null,
+        [Description("Optional brand filter, e.g. 'Nike'.")] string? brand = null,
+        [Description("Optional maximum price.")] double? maxPrice = null,
+        CancellationToken ct = default) => this._runner.ReadAsync(async r =>
+    {
+        const string Cypher =
+            """
+            MATCH (p:Product)
+            WHERE ANY(w IN split(toLower($query), ' ') WHERE
+                      toLower(p.name) CONTAINS w OR toLower(p.description) CONTAINS w OR toLower(p.category) CONTAINS w)
+              AND ($category IS NULL OR p.category = $category)
+              AND ($brand    IS NULL OR p.brand = $brand)
+              AND ($maxPrice IS NULL OR p.price <= $maxPrice)
+            RETURN p.name AS name, p.brand AS brand, p.category AS category,
+                   p.price AS price, p.in_stock AS inStock
+            ORDER BY p.popularity DESC
+            LIMIT 10
+            """;
+        var cursor = await r.RunAsync(Cypher, new { query, category, brand, maxPrice });
+        return Render("Matches", await cursor.ToListAsync());
+    }, ct);
+
+    [Description("Get personalized product recommendations, optionally biased toward a preferred brand and/or category.")]
+    public Task<string> GetRecommendationsAsync(
+        [Description("The customer's preferred brand (from their saved preferences), if known.")] string? preferredBrand = null,
+        [Description("Optional category to recommend within.")] string? category = null,
+        [Description("How many recommendations to return.")] int limit = 5,
+        CancellationToken ct = default) => this._runner.ReadAsync(async r =>
+    {
+        const string Cypher =
+            """
+            MATCH (p:Product)
+            WHERE p.in_stock = true
+              AND ($category IS NULL OR p.category = $category)
+            WITH p, (CASE WHEN $preferredBrand IS NOT NULL AND p.brand = $preferredBrand THEN 1 ELSE 0 END) AS onBrand
+            RETURN p.name AS name, p.brand AS brand, p.category AS category, p.price AS price, p.in_stock AS inStock
+            ORDER BY onBrand DESC, p.popularity DESC
+            LIMIT $limit
+            """;
+        var cursor = await r.RunAsync(Cypher, new { preferredBrand, category, limit });
+        var header = preferredBrand is null ? "Recommended for you" : $"Recommended for you (favoring {preferredBrand})";
+        return Render(header, await cursor.ToListAsync());
+    }, ct);
+
+    [Description("Find products related to a given product — same category or same brand — via graph traversal.")]
+    public Task<string> GetRelatedProductsAsync(
+        [Description("The exact product name to find related items for.")] string productName,
+        CancellationToken ct = default) => this._runner.ReadAsync(async r =>
+    {
+        const string Cypher =
+            """
+            MATCH (p:Product {name: $productName})
+            CALL (p) {
+                MATCH (p)-[:IN_CATEGORY]->(c)<-[:IN_CATEGORY]-(rel:Product) WHERE rel <> p
+                RETURN rel, 'same category' AS reason
+              UNION
+                MATCH (p)-[:MADE_BY]->(b)<-[:MADE_BY]-(rel:Product) WHERE rel <> p
+                RETURN rel, 'same brand' AS reason
+            }
+            WITH rel, collect(DISTINCT reason) AS reasons
+            RETURN rel.name AS name, rel.brand AS brand, rel.category AS category,
+                   rel.price AS price, rel.in_stock AS inStock, rel.popularity AS popularity,
+                   reduce(s = '', x IN reasons | CASE WHEN s = '' THEN x ELSE s + ', ' + x END) AS reason
+            ORDER BY popularity DESC
+            LIMIT 5
+            """;
+        var cursor = await r.RunAsync(Cypher, new { productName });
+        return Render($"Related to {productName}", await cursor.ToListAsync());
+    }, ct);
+
+    [Description("Check whether a product is in stock and how many units are available.")]
+    public Task<string> CheckInventoryAsync(
+        [Description("The exact product name to check.")] string productName,
+        CancellationToken ct = default) => this._runner.ReadAsync(async r =>
+    {
+        var cursor = await r.RunAsync(
+            "MATCH (p:Product {name: $productName}) RETURN p.name AS name, p.in_stock AS inStock, p.inventory AS inventory",
+            new { productName });
+        var rows = await cursor.ToListAsync();
+        if (rows.Count == 0)
+        {
+            return $"'{productName}' was not found in the catalog.";
+        }
+
+        var rec = rows[0];
+        var inStock = rec["inStock"].As<bool>();
+        return inStock
+            ? $"{rec["name"].As<string>()}: In stock ({rec["inventory"].As<long>()} available)."
+            : $"{rec["name"].As<string>()}: Out of stock.";
+    }, ct);
+
+    /// <summary>The retail tools as MAF/MEAI <see cref="AIFunction"/>s (attach to the agent's ChatOptions.Tools).</summary>
+    public IReadOnlyList<AIFunction> CreateAIFunctions() =>
+    [
+        AIFunctionFactory.Create(this.SearchProductsAsync, "search_products",
+            "Search the product catalog with optional category/brand/price filters."),
+        AIFunctionFactory.Create(this.GetRecommendationsAsync, "get_recommendations",
+            "Get personalized recommendations, optionally favoring a preferred brand/category."),
+        AIFunctionFactory.Create(this.GetRelatedProductsAsync, "get_related_products",
+            "Find products related to a given product via the graph."),
+        AIFunctionFactory.Create(this.CheckInventoryAsync, "check_inventory",
+            "Check stock/availability for a product."),
+    ];
+
+    private static string Render(string header, List<IRecord> rows)
+    {
+        if (rows.Count == 0)
+        {
+            return $"{header}: (no matches)";
+        }
+
+        var sb = new StringBuilder().Append(header).Append(':').AppendLine();
+        foreach (var rec in rows)
+        {
+            var stock = rec["inStock"].As<bool>() ? "in stock" : "out of stock";
+            var reason = rec.Keys.Contains("reason") ? $"  [{rec["reason"].As<string>()}]" : string.Empty;
+            sb.Append("  • ")
+              .Append(rec["name"].As<string>())
+              .Append(" — ").Append(rec["brand"].As<string>())
+              .Append(", ").Append(rec["category"].As<string>())
+              .Append(", $").Append(rec["price"].As<double>().ToString("0"))
+              .Append(", ").Append(stock).Append(reason)
+              .AppendLine();
+        }
+        return sb.ToString().TrimEnd();
+    }
+}

dotnet/samples/02-agents/AgentWithMemory/AgentWithMemory_Step06_MemoryUsingAgentMemory/Program.cs

@@ -0,0 +1,156 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// Agent Memory — Shopping Assistant (Microsoft Agent Framework, .NET)
+//
+// A .NET port of the Neo4j Labs "agent-memory" retail-assistant example
+// (https://github.com/neo4j-labs/agent-memory/tree/main/examples/microsoft_agent_retail_assistant,
+// referenced from https://learn.microsoft.com/en-us/agent-framework/integrations/neo4j-memory).
+//
+// A shopping assistant that LEARNS a customer's preferences and RECOMMENDS products via graph
+// traversal, backed by DURABLE memory in Neo4j. It uses the AgentMemory library — a .NET port of the
+// Python memory provider, not an officially recognized Neo4j integration — and its Microsoft Agent
+// Framework adapter:
+//   • Neo4jMemoryContextProvider  (an AIContextProvider)  — recalls memory before each run, persists
+//     after, and (via ExposeMemoryToolsFromContextProvider) surfaces the memory tools (search/remember/
+//     recall) itself through AIContext.Tools
+//   • ProductCatalog.CreateAIFunctions()                  — retail tools over a Neo4j :Product graph
+//
+// Configuration (environment variables, matching the other Foundry samples):
+//   AZURE_OPENAI_ENDPOINT     (required)  — your Azure OpenAI / Foundry endpoint
+//   AZURE_OPENAI_API_KEY      (optional)  — API key; if unset, DefaultAzureCredential (az login) is used
+//   FOUNDRY_MODEL             (default: gpt-4o-mini)            — chat model deployment
+//   FOUNDRY_EMBEDDING_MODEL   (default: text-embedding-3-small) — embedding model deployment (1536 dims)
+//   NEO4J_URI                 (default: bolt://localhost:7687)
+//   NEO4J_USER                (default: neo4j)
+//   NEO4J_PASSWORD            (default: password)
+
+using System.ClientModel;
+using System.ClientModel.Primitives;
+using AgentMemory.Abstractions.Services;
+using AgentMemory.AgentFramework;
+using AgentMemory.Core;
+using AgentMemory.Core.Stubs;
+using AgentMemory.Neo4j.Infrastructure;
+using AgentMemoryShoppingAssistant;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.DependencyInjection.Extensions;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using OpenAI;
+
+// ── Model + credentials (Azure OpenAI / Foundry, via env vars) ───────────────────────────────────
+var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+var apiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY");
+var chatModel = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-4o-mini";
+var embeddingModel = Environment.GetEnvironmentVariable("FOUNDRY_EMBEDDING_MODEL") ?? "text-embedding-3-small";
+
+var clientOptions = new OpenAIClientOptions { Endpoint = new Uri(endpoint) };
+// API key if provided, otherwise Azure credential (dev: `az login`).
+// 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.
+OpenAIClient openAI = string.IsNullOrWhiteSpace(apiKey)
+    ? new OpenAIClient(new BearerTokenPolicy(new DefaultAzureCredential(), "https://ai.azure.com/.default"), clientOptions)
+    : new OpenAIClient(new ApiKeyCredential(apiKey), clientOptions);
+
+IChatClient chatClient = openAI.GetChatClient(chatModel).AsIChatClient();
+IEmbeddingGenerator<string, Embedding<float>> embeddingGenerator =
+    openAI.GetEmbeddingClient(embeddingModel).AsIEmbeddingGenerator();
+
+// ── AgentMemory (Neo4j) DI ───────────────────────────────────────────────────────────────────────
+var builder = Host.CreateApplicationBuilder(args);
+builder.Logging.SetMinimumLevel(LogLevel.Warning);
+
+builder.Services.AddNeo4jAgentMemory(options =>
+{
+    options.Uri = Environment.GetEnvironmentVariable("NEO4J_URI") ?? "bolt://localhost:7687";
+    options.Username = Environment.GetEnvironmentVariable("NEO4J_USER") ?? "neo4j";
+    options.Password = Environment.GetEnvironmentVariable("NEO4J_PASSWORD") ?? "password";
+});
+builder.Services.AddAgentMemoryCore(_ => { });
+builder.Services.AddSingleton<IClock, SystemClock>();
+builder.Services.AddSingleton<IIdGenerator, GuidIdGenerator>();
+builder.Services.TryAddSingleton(chatClient);
+builder.Services.TryAddSingleton(embeddingGenerator);
+builder.Services.AddAgentMemoryFramework(options =>
+{
+    options.AutoExtractOnPersist = true;
+    options.ContextFormat.IncludeEntities = true;
+    options.ContextFormat.IncludeFacts = true;
+    options.ContextFormat.IncludePreferences = true;
+    options.ExposeMemoryToolsFromContextProvider = true;
+});
+
+var host = builder.Build();
+await using var hostDisposal = (IAsyncDisposable)host;
+
+await using var scope = host.Services.CreateAsyncScope();
+var sp = scope.ServiceProvider;
+
+// ── Setup: schema + sample product graph ─────────────────────────────────────────────────────────
+var catalog = new ProductCatalog(sp.GetRequiredService<INeo4jTransactionRunner>());
+await sp.GetRequiredService<ISchemaBootstrapper>().BootstrapAsync();
+await catalog.SeedAsync();
+Console.WriteLine("Neo4j schema ready; sample products loaded.\n");
+
+// ── The shopping assistant: context provider (recall + memory tools) + product tools ─────────────
+var memoryProvider = sp.GetRequiredService<Neo4jMemoryContextProvider>();
+var productTools = catalog.CreateAIFunctions();
+
+// WithMemoryOwnerScoping(sp) scopes the whole invocation (recall, tool calls, persistence) to the
+// owner set via WithMemoryIdentity below — no manual BeginOwnerScope wrapping needed per turn.
+AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions
+{
+    Name = "ShoppingAssistant",
+    ChatOptions = new ChatOptions
+    {
+        ModelId = chatModel,
+        Instructions =
+            "You are a helpful shopping assistant for an online store. Learn and remember the customer's "
+          + "preferences (brands, budget, categories) using the memory tools, and recommend products that "
+          + "fit using the product tools. Explain why each recommendation matches, and suggest alternatives "
+          + "when something is out of stock.",
+        // memoryProvider appends the six memory tools (search_memory, remember_fact, ...) to this list
+        // on every model call via AIContext.Tools — see ExposeMemoryToolsFromContextProvider above.
+        Tools = [.. productTools],
+    },
+    AIContextProviders = [memoryProvider],
+}).WithMemoryOwnerScoping(sp);
+
+const string Shopper = "shopper-amelia";
+
+// ── Session A — the customer shops; the model calls the tools and remembers preferences ──────────
+Console.WriteLine(">> Session A\n");
+var sessionA = (await agent.CreateSessionAsync())
+    .WithMemoryIdentity(userId: Shopper, sessionId: "cart-a", applicationId: "retail-demo");
+
+foreach (var turn in new[]
+{
+    "Hi! I'm looking for running shoes. I love Nike and want to stay under $150.",
+    "Nice — what would you recommend for me, and is anything I might like out of stock?",
+})
+{
+    await SayAsync(agent, sessionA, turn);
+}
+
+// ── Session B — a NEW session for the same shopper still recalls her preferences ─────────────────
+Console.WriteLine(">> Session B — a brand-new session; memory is durable\n");
+var sessionB = (await agent.CreateSessionAsync())
+    .WithMemoryIdentity(userId: Shopper, sessionId: "cart-b", applicationId: "retail-demo");
+
+await SayAsync(agent, sessionB, "I'm back — remind me what I like and suggest something new.");
+
+Console.WriteLine("=== Done. Preferences + messages persist in Neo4j across sessions. ===");
+
+// One conversational turn. Owner scoping (recall, tool calls, and persistence) is guaranteed
+// automatically by the WithMemoryOwnerScoping-wrapped agent — no manual BeginOwnerScope needed here.
+static async Task SayAsync(AIAgent agent, AgentSession session, string message)
+{
+    Console.WriteLine($"USER      : {message}");
+    var response = await agent.RunAsync(message, session);
+    Console.WriteLine($"ASSISTANT : {response.Text}\n");
+}

dotnet/samples/02-agents/AgentWithMemory/AgentWithMemory_Step06_MemoryUsingAgentMemory/README.md

@@ -0,0 +1,75 @@
+# Agent with Memory Using AgentMemory — Shopping Assistant
+
+A **.NET port of the Neo4j Labs "agent-memory" retail assistant** example
+([`microsoft_agent_retail_assistant`](https://github.com/neo4j-labs/agent-memory/tree/main/examples/microsoft_agent_retail_assistant),
+referenced from the [Learn integration page](https://learn.microsoft.com/en-us/agent-framework/integrations/neo4j-memory)).
+A shopping assistant that **learns a customer's preferences** and **recommends products via graph
+traversal**, backed by durable memory in Neo4j.
+
+It uses the [`AgentMemory`](https://www.nuget.org/packages/AgentMemory) library — a .NET port of the
+(Python-only) Neo4j Labs memory provider, **not an officially recognized Neo4j integration** — through
+its Microsoft Agent Framework adapter.
+
+## Features Demonstrated
+
+- **`Neo4jMemoryContextProvider`** (an `AIContextProvider`) — recalls relevant memory before each run,
+  persists new memory after (the same bidirectional pattern as the official provider), and — via
+  `ExposeMemoryToolsFromContextProvider = true` — surfaces the memory tools (search / remember / recall)
+  itself through `AIContext.Tools`.
+- **`ProductCatalog.CreateAIFunctions()`** — retail tools over a Neo4j `:Product` graph (search /
+  recommend / related / inventory).
+- Preference learning that persists across a brand-new `AgentSession` for the same shopper.
+- Graph-based product recommendations and "related products" via traversal.
+
+## Prerequisites
+
+- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
+- A **Neo4j 5.x** instance (the sample bootstraps the schema and seeds sample products)
+- An **Azure OpenAI / Foundry** deployment (a chat model + an embedding model)
+
+
+## Configuration
+
+Set the following environment variables:
+
+| Variable | Required | Default | Purpose |
+|---|---|---|---|
+| `AZURE_OPENAI_ENDPOINT` | ✅ | — | Azure OpenAI / Foundry endpoint |
+| `AZURE_OPENAI_API_KEY` | — | — | API key; if unset, `DefaultAzureCredential` (`az login`) is used |
+| `FOUNDRY_MODEL` | — | `gpt-4o-mini` | chat model deployment |
+| `FOUNDRY_EMBEDDING_MODEL` | — | `text-embedding-3-small` | embedding model deployment (1536 dims) |
+| `NEO4J_URI` | — | `bolt://localhost:7687` | Neo4j bolt URI |
+| `NEO4J_USER` | — | `neo4j` | Neo4j user |
+| `NEO4J_PASSWORD` | — | `password` | Neo4j password |
+
+> Ensure the embedding model's dimensions match the Neo4j vector-index dimensions AgentMemory bootstraps
+> (default 1536, which matches `text-embedding-3-small`).
+
+## Run the Sample
+
+```bash
+docker run -d --name neo4j -p 7474:7474 -p 7687:7687 -e NEO4J_AUTH=neo4j/password neo4j:5.26
+
+export AZURE_OPENAI_ENDPOINT="https://<your-resource>.openai.azure.com"
+export AZURE_OPENAI_API_KEY="<your-key>"          # or omit and `az login`
+export FOUNDRY_MODEL="gpt-4o-mini"
+
+dotnet run
+```
+
+## Expected Output
+
+1. The sample bootstraps the Neo4j schema and seeds a small product graph (`:Product`,
+   `:ProductCategory`, `:ProductBrand` nodes).
+2. **Session A** — the shopper says she wants running shoes, loves Nike, and has a $150 budget; the
+   agent calls the memory tools to remember this and the product tools to recommend matching items.
+3. **Session B** — a brand-new session for the same shopper (`shopper-amelia`) still recalls her
+   preferences and can suggest something new, because memory persists in Neo4j across sessions.
+
+## Note on packaging
+
+This sample is part of the repo's solution and targets .NET 10 like every other sample, but it
+deliberately opts out of **Central Package Management** and does **not** reference `Microsoft.Agents.AI`
+via the repo's in-source project — it consumes the **published** `AgentMemory` NuGet packages instead
+(which target `Microsoft.Agents.AI` 1.9.0). A version that references the repo's current
+`Microsoft.Agents.AI` source would require AgentMemory to be rebuilt against that version first.

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

@@ -9,6 +9,7 @@ These samples show how to create an agent with the Agent Framework that uses Mem
 |[Custom Memory Implementation](../../01-get-started/04_memory/)|This sample demonstrates how to create a custom memory component and attach it to an agent.|
 |[Memory with Microsoft Foundry](./AgentWithMemory_Step04_MemoryUsingFoundry/)|This sample demonstrates how to create and run an agent that uses Microsoft Foundry's managed memory service to extract and retrieve individual memories.|
 |[Bounded Chat History with Overflow](./AgentWithMemory_Step05_BoundedChatHistory/)|This sample demonstrates how to create a bounded chat history provider that overflows older messages to a vector store and recalls them as memories.|
+|[Memory Using AgentMemory](./AgentWithMemory_Step06_MemoryUsingAgentMemory/)|This sample demonstrates a retail shopping assistant built with [`AgentMemory`](https://www.nuget.org/packages/AgentMemory), an unofficial .NET port of the Neo4j Labs graph-memory provider, to learn customer preferences and recommend products via graph traversal.|
 
 > **See also**: [Memory Search with Foundry Agents](../AgentProviders/foundry/Agent_Step22_MemorySearch/) - demonstrates using the built-in Memory Search tool with Microsoft Foundry agents.
 

dotnet/samples/02-agents/AgentWithRAG/AgentWithRAG_Step01_BasicTextRAG/Program.cs

@@ -24,7 +24,7 @@ AIProjectClient aiProjectClient = new(
     new Uri(endpoint),
     new DefaultAzureCredential());
 
-// Create an In-Memory vector store that uses the Azure AI Foundry embedding model to generate embeddings.
+// Create an In-Memory vector store that uses the Microsoft Foundry embedding model to generate embeddings.
 VectorStore vectorStore = new InMemoryVectorStore(new()
 {
     EmbeddingGenerator = aiProjectClient.GetProjectOpenAIClient().GetEmbeddingClient(embeddingDeploymentName).AsIEmbeddingGenerator()

dotnet/samples/02-agents/AgentWithRAG/AgentWithRAG_Step02_CustomVectorStoreRAG/Program.cs

@@ -25,7 +25,7 @@ AIProjectClient aiProjectClient = new(
     new Uri(endpoint),
     new DefaultAzureCredential());
 
-// Create a Qdrant vector store that uses the Azure AI Foundry embedding model to generate embeddings.
+// Create a Qdrant vector store that uses the Microsoft Foundry embedding model to generate embeddings.
 QdrantClient client = new("localhost");
 VectorStore vectorStore = new QdrantVectorStore(client, ownsClient: true, new()
 {

dotnet/samples/02-agents/Agents/Agent_Step02_StructuredOutput/Program.cs

@@ -3,7 +3,7 @@
 // Structured Output — Configure agents to return typed JSON
 //
 // This sample shows how to configure a ChatClientAgent to produce
-// structured output using JSON schema constraints with Azure AI Foundry.
+// structured output using JSON schema constraints with Microsoft Foundry.
 
 using System.ComponentModel;
 using System.Text.Json;

dotnet/samples/02-agents/Agents/Agent_Step05_Observability/Program.cs

@@ -1,6 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-// Agent Observability — OpenTelemetry tracing with Azure AI Foundry
+// Agent Observability — OpenTelemetry tracing with Microsoft Foundry
 //
 // This sample shows how to instrument an AI agent with OpenTelemetry
 // for distributed tracing and telemetry logging.

dotnet/samples/02-agents/Agents/Agent_Step06_DependencyInjection/Program.cs

@@ -19,7 +19,7 @@ var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt
 // Create a host builder that we will register services with and then run.
 HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
 
-// Create the AI agent from the Azure AI Foundry project client.
+// Create the AI agent from the Microsoft Foundry project client.
 // 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.

dotnet/samples/02-agents/Agents/Agent_Step10_BackgroundResponsesWithToolsAndPersistence/Program.cs

@@ -40,7 +40,7 @@ AgentRunOptions options = new() { AllowBackgroundResponses = true };
 AgentSession session = await agent.CreateSessionAsync();
 
 // Start the initial run.
-AgentResponse response = await agent.RunAsync("Write a very long novel about a team of astronauts exploring an uncharted galaxy.", session, options);
+AgentResponse response = await agent.RunAsync("Write a short story about a team of astronauts exploring an uncharted galaxy.", session, options);
 
 // Poll for background responses until complete.
 while (response.ContinuationToken is not null)

dotnet/samples/02-agents/Agents/Agent_Step11_Middleware/Program.cs

@@ -2,7 +2,7 @@
 
 // Middleware — Chain multiple middleware layers on an agent
 //
-// This sample shows multiple middleware layers working together with Azure AI Foundry:
+// This sample shows multiple middleware layers working together with Microsoft Foundry:
 // chat client (global/per-request), agent run (PII filtering and guardrails),
 // function invocation (logging and result overrides), human-in-the-loop
 // approval workflows for sensitive function calls, and MessageAIContextProvider
@@ -15,7 +15,7 @@ using Azure.Identity;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 
-// Get Azure AI Foundry configuration from environment variables
+// Get Microsoft Foundry configuration from environment variables
 var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
 var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
 

dotnet/samples/02-agents/Agents/Agent_Step14_BackgroundResponses/Program.cs

@@ -3,7 +3,7 @@
 // Background Responses — Asynchronous agent execution with polling
 //
 // This sample shows how to use background responses with ChatClientAgent
-// and Azure AI Foundry for non-blocking agent execution.
+// and Microsoft Foundry for non-blocking agent execution.
 
 using Azure.AI.Projects;
 using Azure.Identity;
@@ -54,8 +54,13 @@ await foreach (AgentResponseUpdate update in agent.RunStreamingAsync("Write a ve
     // Output each update.
     Console.Write(update.Text);
 
-    // Track last update.
-    lastReceivedUpdate = update;
+    // Track the last update that carries a resumable continuation token.
+    // Lifecycle events like response.completed return null tokens (response is finished),
+    // so we only update our reference when a token is actually present.
+    if (update.ContinuationToken is not null)
+    {
+        lastReceivedUpdate = update;
+    }
 
     // Simulate connection loss after first piece of content received.
     if (update.Text.Length > 0)

dotnet/samples/02-agents/Agents/Agent_Step18_CompactionPipeline/Program.cs

@@ -72,6 +72,7 @@ AIAgent agent =
                         """
                         You are a helpful, but long winded, shopping assistant.
                         Help the user look up prices and compare products.
+                        You MUST use the LookupPrice tool for every price question — never answer price questions from memory.
                         When responding, Be sure to be extra descriptive and use as
                         many words as possible without sounding ridiculous.
                         """,

dotnet/samples/02-agents/Agents/Agent_Step18_CompactionPipeline/README.md

@@ -130,3 +130,13 @@ AIAgent agent = agentChatClient
 This places the compaction provider at the agent level instead of the chat client level, which allows you to use different compaction strategies for different agents that share the same chat client.
 
 > Note: In this mode the `CompactionProvider` is not engaged during the tool calling loop. Agent-level `AIContextProviders` run before chat history is stored, so any synthetic summary messages produced by `CompactionProvider` can become part of the persisted history when using `ChatHistoryProvider`. If you want to compact only the request context while preserving the original stored history, register `CompactionProvider` on the `ChatClientBuilder` via `UseAIContextProviders(...)` instead of on `ChatClientAgentOptions`.
+
+## Security Considerations
+
+Most compaction strategies in this pipeline (tool-result summarization, sliding window, truncation) only
+remove or reorder existing messages and carry no additional risk. `SummarizationCompactionStrategy` is
+the exception: it calls out to an LLM to produce replacement summary content that permanently becomes
+part of chat history. A compromised or malicious summarization service could return a summary containing
+unsafe instructions, creating a persistent indirect-prompt-injection vector. Using
+`SummarizationCompactionStrategy` is optional and requires explicit configuration — only point its
+`IChatClient` at a summarization service you trust as much as the primary model.

dotnet/samples/02-agents/Agents/Agent_Step19_InFunctionLoopCheckpointing/Program.cs

@@ -67,7 +67,7 @@ static string GetTime([Description("The city name.")] string city) =>
 // asking for alternative destinations. The model will process this injected message on the next
 // service call — even though the parent FunctionInvokingChatClient loop would otherwise stop.
 [Description("Check current travel advisories for a city.")]
-static string CheckTravelAdvisory([Description("The city name.")] string city)
+static async Task<string> CheckTravelAdvisory([Description("The city name.")] string city)
 {
     // Simulated travel advisory data.
     var advisory = city.ToUpperInvariant() switch
@@ -85,9 +85,13 @@ static string CheckTravelAdvisory([Description("The city name.")] string city)
     // When an advisory is found, inject a follow-up question so the model automatically
     // suggests alternatives without the user needing to ask.
     var runContext = AIAgent.CurrentRunContext!;
-    runContext.Agent.GetService<MessageInjectingChatClient>()?.EnqueueMessages(
-        runContext.Session!,
-        [new ChatMessage(ChatRole.User, $"Given the travel advisory for {city}, what alternative cities would you recommend instead?")]);
+    var injector = runContext.Agent.GetService<MessageInjectingChatClient>();
+    if (injector is not null)
+    {
+        await injector.EnqueueMessagesAsync(
+            runContext.Session!,
+            [new ChatMessage(ChatRole.User, $"Given the travel advisory for {city}, what alternative cities would you recommend instead?")]);
+    }
 
     return advisory;
 }

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

@@ -18,7 +18,7 @@ Before you begin, ensure you have the following prerequisites:
 - Azure CLI installed and authenticated (for Azure credential authentication)
 - User has the required role to invoke models in the Foundry project.
 
-**Note**: These samples use models hosted through Microsoft Foundry. For more information, see [Azure AI Foundry documentation](https://learn.microsoft.com/en-us/azure/ai-foundry/).
+**Note**: These samples use models hosted through Microsoft Foundry. For more information, see [Microsoft Foundry documentation](https://learn.microsoft.com/en-us/azure/ai-foundry/).
 
 **Note**: These samples use Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Foundry project. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
 

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

@@ -12,7 +12,7 @@ The simplest agent evaluation: create a Foundry agent, run it against test quest
 
 - .NET 10 SDK or later
 - Azure authentication available to `DefaultAzureCredential` (for local development, run `az login`)
-- A deployed model in your Azure AI Foundry project
+- A deployed model in your Microsoft Foundry project
 
 Set the following environment variables:
 

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

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

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

@@ -0,0 +1,180 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// "Working with your data, safely" — Post 2 of the "Build your own claw and agent harness with Microsoft Agent Framework" series.
+// See: https://devblogs.microsoft.com/agent-framework/agent-harness-working-with-your-data-safely.
+//
+// This sample builds on Post 1's personal finance assistant and adds three abilities:
+//   1. File access  — read the user's portfolio.csv and write report files (file_access_* tools).
+//   2. Approvals    — the place_trade tool is wrapped so it requires human approval before running.
+//   3. Durable memory — two complementary kinds:
+//        * File memory   (coarse-grained, explicit) — the agent reads/writes files like
+//                         watchlist.md. Its files live on disk under {cwd}/agent-file-memory/<session-id>/,
+//                         so they persist across runs on this machine; /session-export and /session-import
+//                         preserve the session id so a relaunched session re-links to its memory files.
+//        * Foundry memory (fine-grained, automatic) — Microsoft Foundry extracts durable facts
+//                         (e.g. the user's risk tolerance) from the conversation. Opt-in: enabled
+//                         only when FOUNDRY_MEMORY_STORE and FOUNDRY_EMBEDDING_MODEL are set.
+//
+// Special commands (handled by the shared HarnessConsole):
+//   /todos  — Display the current todo list without invoking the agent.
+//   /mode   — Get or set the current agent mode.
+//   /exit   — End the session.
+
+#pragma warning disable OPENAI001 // Suppress experimental API warnings for Responses API usage.
+#pragma warning disable MAAI001  // Suppress experimental API warnings for Agents AI experiments.
+
+using System.ClientModel.Primitives;
+using Azure.AI.Projects;
+using Azure.Identity;
+using ClawSample;
+using Harness.Shared.Console;
+using Harness.Shared.Console.OpenAI;
+using Harness.Shared.Console.ToolFormatters;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry;
+using Microsoft.Extensions.AI;
+
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4";
+
+// <instructions>
+var instructions =
+    """
+    ## Personal Finance Assistant Instructions
+
+    You are a personal finance and investing assistant. You help the user understand their
+    portfolio and watchlist, and you can place trades on their behalf.
+
+    ### Working style
+
+    - The user's holdings live in a file called portfolio.csv. Read it with the file_access tools
+      before answering questions about their portfolio, and never modify it unless asked.
+    - When asked for a report or analysis, write it to a Markdown file with the file_access tools
+      (e.g. reports/portfolio-review.md) and tell the user where you saved it.
+    - Keep the user's watchlist in a memory file called watchlist.md: read it when reviewing the
+      watchlist, and update it whenever the user adds or removes a ticker.
+    - To buy or sell, use the place_trade tool. This takes a real action, so the user will be
+      asked to approve it before it runs — explain what you are about to do first.
+    - Remember durable facts the user tells you about themselves (risk tolerance, goals,
+      preferences) and take them into account when giving analysis.
+
+    ### Important
+
+    You provide information and analysis only — you are not a licensed financial advisor and you
+    must not present your output as personalized investment advice. Remind the user to do their
+    own research before making decisions.
+    """;
+// </instructions>
+
+// <create_client>
+// Construct an IChatClient backed by a Microsoft Foundry project (see Post 1 for details).
+var projectClient = new AIProjectClient(
+    new Uri(endpoint),
+    // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+    // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+    // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+    new DefaultAzureCredential(),
+    new AIProjectClientOptions { RetryPolicy = new ClientRetryPolicy(3) });
+
+IChatClient chatClient = projectClient
+    .GetProjectOpenAIClient()
+    .GetResponsesClient()
+    .AsIChatClient(deploymentName);
+// </create_client>
+
+// <memory>
+// Fine-grained Foundry memory is opt-in: it needs a memory store and an embedding model. When the
+// environment is configured we add a FoundryMemoryProvider scoped to a single user, so the facts it
+// extracts are recalled across sessions. Otherwise we fall back to file memory only.
+var memoryStoreName = Environment.GetEnvironmentVariable("FOUNDRY_MEMORY_STORE");
+var embeddingModel = Environment.GetEnvironmentVariable("FOUNDRY_EMBEDDING_MODEL");
+
+FoundryMemoryProvider? foundryMemory = null;
+if (!string.IsNullOrWhiteSpace(memoryStoreName) && !string.IsNullOrWhiteSpace(embeddingModel))
+{
+    foundryMemory = new FoundryMemoryProvider(
+        projectClient,
+        memoryStoreName,
+        // In a real world scenario, "claw-sample-user" should be replaced with a unique identifier
+        // for the active user.
+        // To tie memories to the session, replace "claw-sample-user" with Guid.NewGuid().ToString().
+        // stateInitializer is called once per session to define the scope for the memory provider.
+        stateInitializer: _ => new(new FoundryMemoryProviderScope("claw-sample-user")),
+        new FoundryMemoryProviderOptions()
+        {
+            // For demo purposes, configure the memory provider to extract facts immediately
+            // from each message. In a real-world scenario, you may want to set this to a higher value.
+            UpdateDelay = 0,
+        });
+
+    // Create the memory store on first use (no-op if it already exists).
+    await foundryMemory.EnsureMemoryStoreCreatedAsync(
+        deploymentName,
+        embeddingModel,
+        "Durable memory for the Build-your-own-claw finance assistant.");
+
+    Console.WriteLine($"Foundry memory enabled (store: {memoryStoreName}).");
+}
+else
+{
+    Console.WriteLine("Foundry memory disabled. Set FOUNDRY_MEMORY_STORE and FOUNDRY_EMBEDDING_MODEL to enable it.");
+}
+// </memory>
+
+// <create_agent>
+// Turn the chat client into a HarnessAgent. On top of Post 1's defaults we point file access at a
+// fixed folder, add our approval-gated place_trade tool, and (optionally) wire in the Foundry
+// memory provider for automatic, fine-grained fact extraction. File memory keeps its on-disk default
+// store (see below), and we don't point it at a custom folder.
+AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
+{
+    // File access: read portfolio.csv and write reports under the sample's working/ folder.
+    FileAccessStore = new FileSystemAgentFileStore(Path.Combine(AppContext.BaseDirectory, "working")),
+    // Auto-approve the read-only file tools so reading portfolio.csv is frictionless, while saving,
+    // deleting, and place_trade still pause for explicit approval.
+    ToolApprovalAgentOptions = new ToolApprovalAgentOptions
+    {
+        AutoApprovalRules = [FileAccessProvider.ReadOnlyToolsAutoApprovalRule],
+    },
+    // Start in "execute" mode: this assistant is mostly quick lookups and single actions, so a plan
+    // would be overkill. (Planning is still available — switch any time with /mode plan.)
+    AgentModeProviderOptions = new AgentModeProviderOptions { DefaultMode = "execute" },
+    // File memory is on by default. Its files live on disk under {cwd}/agent-file-memory/<session-id>/,
+    // so they persist across runs on this machine. A brand-new session gets a new id (and so an empty
+    // memory); /session-export and /session-import preserve the session's identity so a relaunched
+    // session re-links to its existing on-disk memory files. The export file holds session state, not
+    // the memory files themselves.
+    // Fine-grained, automatic memory (when configured).
+    AIContextProviders = foundryMemory is null ? null : [foundryMemory],
+    ChatOptions = new ChatOptions
+    {
+        Instructions = instructions,
+        Tools =
+        [
+            StockTools.CreateGetStockPriceTool(),
+            TradingTools.CreatePlaceTradeTool(),
+        ],
+        Reasoning = new() { Effort = ReasoningEffort.Medium },
+    },
+});
+// </create_agent>
+
+// <run>
+// Run the interactive console session. The default planning observers already include a tool
+// approval observer, so the place_trade approval prompt is surfaced automatically.
+await HarnessConsole.RunAgentAsync(
+    agent,
+    userPrompt: "Ask me to review your portfolio, draft a report, update your watchlist, or place a trade.",
+    new HarnessConsoleOptions
+    {
+        Observers = [
+            new OpenAIResponsesWebSearchDisplayObserver(),
+            new OpenAIResponsesErrorObserver(),
+            .. HarnessConsoleOptions.BuildObserversWithPlanning(
+                agent,
+                planModeName: "plan",
+                executionModeName: "execute",
+                toolFormatters: ToolCallFormatter.BuildDefaultToolFormatters())],
+        CommandHandlers = HarnessConsoleOptions.BuildDefaultCommandHandlers(agent),
+    });
+// </run>