New Microsoft Agent Framework logos

* feat(python): Add MCP client OTel spans per GenAI semantic conventions

Implement MCP client spans per the OTel GenAI Semantic Conventions for MCP
(https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/#client).

Operations instrumented:
- initialize: CLIENT span capturing MCP session setup
- tools/list: CLIENT span for tool listing (per-page)
- prompts/list: CLIENT span for prompt listing (per-page)
- tools/call: CLIENT span (nested under execute_tool when called via FunctionTool)
- prompts/get: CLIENT span

Span attributes follow the MCP semantic conventions:
- Required: mcp.method.name
- Conditional: error.type, gen_ai.tool.name, gen_ai.prompt.name
- Recommended: gen_ai.operation.name, mcp.protocol.version, mcp.session.id,
  network.transport, server.address, server.port

Transport-specific attributes per subclass:
- MCPStdioTool: network.transport=pipe
- MCPStreamableHTTPTool: network.transport=tcp, network.protocol.name=http
- MCPWebsocketTool: network.transport=tcp, network.protocol.name=websocket

All span creation gated behind OBSERVABILITY_SETTINGS.ENABLED.

Closes #3624
Closes #4697

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

* refactor: simplify MCP spans — remove enrichment logic and protocol version caching

- Always create nested CLIENT spans for tools/call instead of enriching
  the parent execute_tool span
- Remove _ACTIVE_TOOL_EXECUTION_SPAN contextvar (no longer needed)
- Remove enrich_span_with_mcp_attributes() helper
- Remove _otel_error_type preservation in FunctionTool.invoke()
- Remove _mcp_protocol_version instance variable; protocol version is
  only set on the initialize span where it is available

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

* Refine copilot solution

* fix: enable automatic exception recording on MCP spans

Remove record_exception=False and set_status_on_exception=False from
create_mcp_client_span. Let OTel handle exception recording and status
setting automatically. The manual set_mcp_span_error calls for tools/call
still correctly set error.type (which OTel's automatic handling doesn't
touch), so tool_error is preserved.

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

* Reduce number of lines

* Add comment to sample

* test: address PR review comments on MCP observability tests

- Fix initialize test to call mocked session.initialize() and read
  protocolVersion from the result instead of hardcoding it
- Add tools/call McpError error-path test
- Add prompts/get McpError error-path test

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

* Fix export error

---------

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

.github/scripts/pr_limit_moderation.js

@@ -8,6 +8,7 @@ function getPullRequest(context) {
 
   return {
     author: pullRequest.user.login,
+    authorType: pullRequest.user.type,
     labels: pullRequest.labels?.map((label) => label.name).filter(Boolean) ?? [],
     number: pullRequest.number,
   };
@@ -49,6 +50,10 @@ function hasLabel(labels, labelName) {
   return labels.some((label) => label.toLowerCase() === labelName.toLowerCase());
 }
 
+function isDependabotAuthor({ author, authorType }) {
+  return authorType === 'Bot' && author.toLowerCase() === 'dependabot[bot]';
+}
+
 function buildLimitMessage({ author, exemptLabelName, maxOpenPrs, openPrCount }) {
   return [
     `Thank you for your contribution, @${author}.`,
@@ -83,7 +88,17 @@ async function getOpenPrCount({ github, owner, repo, author, pullRequestNumber }
 
 async function enforcePrLimit({ github, context, core, exemptLabelName, maxOpenPrs, labelName }) {
   const { owner, repo } = context.repo;
-  const { author, labels, number } = getPullRequest(context);
+  const { author, authorType, labels, number } = getPullRequest(context);
+
+  if (isDependabotAuthor({ author, authorType })) {
+    core.info(`Author ${author} is Dependabot; skipping open PR limit enforcement.`);
+    return {
+      author,
+      closed: false,
+      dependabotExempt: true,
+      openPrCount: null,
+    };
+  }
 
   if (hasLabel(labels, exemptLabelName)) {
     core.info(`PR #${number} has the ${exemptLabelName} label; skipping open PR limit enforcement.`);

.github/tests/test_pr_limit_moderation.js

@@ -16,7 +16,7 @@ const { enforcePrLimit } = require('../scripts/pr_limit_moderation.js');
 // Helpers
 // ---------------------------------------------------------------------------
 
-function createContext({ author = 'community-user', labels = [], number = 123 } = {}) {
+function createContext({ author = 'community-user', authorType = 'User', labels = [], number = 123 } = {}) {
   return {
     repo: {
       owner: 'microsoft',
@@ -28,6 +28,7 @@ function createContext({ author = 'community-user', labels = [], number = 123 }
         labels: labels.map((name) => ({ name })),
         user: {
           login: author,
+          type: authorType,
         },
       },
     },
@@ -296,6 +297,30 @@ describe('PR limit enforcement', () => {
     assert.deepEqual(github.calls, []);
   });
 
+  it('does not close Dependabot PRs', async () => {
+    const github = createGithub({
+      itemNumbers: [123, ...Array.from({ length: 25 }, (_, index) => index + 1)],
+      pullRequests: createPullRequestPage({
+        author: 'dependabot[bot]',
+        numbers: [123, ...Array.from({ length: 25 }, (_, index) => index + 1)],
+      }),
+    });
+
+    const result = await enforcePrLimit({
+      github,
+      context: createContext({ author: 'dependabot[bot]', authorType: 'Bot' }),
+      core: createCore(),
+      exemptLabelName: 'pr-limit-exempt',
+      maxOpenPrs: 10,
+      labelName: 'too-many-prs',
+    });
+
+    assert.equal(result.closed, false);
+    assert.equal(result.dependabotExempt, true);
+    assert.equal(result.openPrCount, null);
+    assert.deepEqual(github.calls, []);
+  });
+
   it('counts the current PR when the author has more than one page of open PRs', async () => {
     const github = createGithub({
       itemNumbers: [123, ...Array.from({ length: 100 }, (_, index) => index + 1)],

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

@@ -474,6 +474,45 @@ jobs:
           path: ./python/pytest.xml
           if-no-files-found: ignore
 
+  # GitHub Copilot integration tests
+  python-tests-github-copilot:
+    name: Python Integration Tests - GitHub Copilot
+    runs-on: ubuntu-latest
+    environment: integration
+    timeout-minutes: 60
+    env:
+      COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+      GITHUB_COPILOT_TIMEOUT: "120"
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
+          persist-credentials: false
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Test with pytest (GitHub Copilot integration)
+        run: >
+          uv run pytest --import-mode=importlib
+          packages/github_copilot/tests
+          -m integration
+          --timeout=120 --session-timeout=900 --timeout_method thread
+          --retries 2 --retry-delay 5
+          --junitxml=pytest.xml
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: test-results-github-copilot
+          path: ./python/pytest.xml
+          if-no-files-found: ignore
+
   # Integration test trend report (aggregates per-job JUnit XML results)
   python-integration-test-report:
     name: Integration Test Report
@@ -490,6 +529,7 @@ jobs:
         python-tests-foundry,
         python-tests-foundry-hosting,
         python-tests-cosmos,
+        python-tests-github-copilot,
       ]
     runs-on: ubuntu-latest
     defaults:
@@ -553,7 +593,8 @@ jobs:
         python-tests-functions,
         python-tests-foundry,
         python-tests-foundry-hosting,
-        python-tests-cosmos
+        python-tests-cosmos,
+        python-tests-github-copilot
       ]
     steps:
       - name: Fail workflow if tests failed

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

@@ -40,6 +40,7 @@ jobs:
       foundryChanged: ${{ steps.filter.outputs.foundry }}
       foundryHostingChanged: ${{ steps.filter.outputs.foundry_hosting }}
       cosmosChanged: ${{ steps.filter.outputs.cosmos }}
+      githubCopilotChanged: ${{ steps.filter.outputs.github_copilot }}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       - uses: dorny/paths-filter@d1c1ffe0248fe513906c8e24db8ea791d46f8590 # v3
@@ -85,6 +86,8 @@ jobs:
               - 'python/packages/foundry_hosting/**'
             cosmos:
               - 'python/packages/azure-cosmos/**'
+            github_copilot:
+              - 'python/packages/github_copilot/**'
       # run only if 'python' files were changed
       - name: python tests
         if: steps.filter.outputs.python == 'true'
@@ -658,6 +661,58 @@ jobs:
           path: ./python/pytest.xml
           if-no-files-found: ignore
 
+  # GitHub Copilot integration tests
+  python-tests-github-copilot:
+    name: Python Tests - GitHub Copilot Integration
+    needs: paths-filter
+    if: >
+      github.event_name != 'pull_request' &&
+      needs.paths-filter.outputs.pythonChanges == 'true' &&
+      (github.event_name != 'merge_group' ||
+       needs.paths-filter.outputs.githubCopilotChanged == 'true' ||
+       needs.paths-filter.outputs.coreChanged == 'true')
+    runs-on: ubuntu-latest
+    environment: integration
+    timeout-minutes: 60
+    env:
+      COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+      GITHUB_COPILOT_TIMEOUT: "120"
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Test with pytest (GitHub Copilot integration)
+        run: >
+          uv run pytest --import-mode=importlib
+          packages/github_copilot/tests
+          -m integration
+          --timeout=120 --session-timeout=900 --timeout_method thread
+          --retries 2 --retry-delay 5
+          --junitxml=pytest.xml
+      - name: Surface failing tests
+        if: always()
+        uses: pmeier/pytest-results-action@20b595761ba9bf89e115e875f8bc863f913bc8ad # v0.7.2
+        with:
+          path: ./python/pytest.xml
+          summary: true
+          display-options: fEX
+          fail-on-empty: false
+          title: GitHub Copilot integration test results
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: test-results-github-copilot
+          path: ./python/pytest.xml
+          if-no-files-found: ignore
+
   # Integration test trend report (aggregates per-job JUnit XML results)
   python-integration-test-report:
     name: Integration Test Report
@@ -674,6 +729,7 @@ jobs:
         python-tests-foundry,
         python-tests-foundry-hosting,
         python-tests-cosmos,
+        python-tests-github-copilot,
       ]
     runs-on: ubuntu-latest
     defaults:
@@ -735,6 +791,7 @@ jobs:
         python-tests-foundry,
         python-tests-foundry-hosting,
         python-tests-cosmos,
+        python-tests-github-copilot,
       ]
     steps:
       - name: Fail workflow if tests failed

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

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

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

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

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

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

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

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

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

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

dotnet/Directory.Packages.props

@@ -109,7 +109,7 @@
     <PackageVersion Include="A2A" Version="1.0.0-preview2" />
     <PackageVersion Include="A2A.AspNetCore" Version="1.0.0-preview2" />
     <!-- MCP -->
-    <PackageVersion Include="ModelContextProtocol" Version="1.1.0" />
+    <PackageVersion Include="ModelContextProtocol" Version="1.2.0" />
     <!-- Hyperlight -->
     <PackageVersion Include="Hyperlight.HyperlightSandbox.Api" Version="0.4.0" />
     <PackageVersion Include="Hyperlight.HyperlightSandbox.Guest.Python" Version="0.4.0" />

dotnet/nuget/nuget-package.props

@@ -1,14 +1,14 @@
 <Project>
   <PropertyGroup>
     <!-- Central version prefix - applies to all nuget packages. -->
-    <VersionPrefix>1.8.0</VersionPrefix>
+    <VersionPrefix>1.9.0</VersionPrefix>
     <RCNumber>1</RCNumber>
-    <DateSuffix>260528</DateSuffix>
+    <DateSuffix>260603</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.8.0</GitTag>
+    <GitTag>1.9.0</GitTag>
 
     <Configurations>Debug;Release;Publish</Configurations>
     <IsPackable>true</IsPackable>

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

@@ -10,6 +10,11 @@ WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
 builder.Services.AddHttpClient().AddLogging();
 builder.Services.AddAGUI();
 
+// WARNING: When adding session persistence (e.g., WithInMemorySessionStore), or running in production,
+// make sure to also register a SessionIsolationKeyProvider to scope sessions by principal in multi-user
+// deployments, e.g.:
+// builder.Services.UseClaimsBasedSessionIsolation(new() { ClaimType = ClaimTypes.NameIdentifier });
+
 WebApplication app = builder.Build();
 
 string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"]

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

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

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

@@ -16,6 +16,11 @@ builder.Services.ConfigureHttpJsonOptions(options =>
     options.SerializerOptions.TypeInfoResolverChain.Add(SampleJsonSerializerContext.Default));
 builder.Services.AddAGUI();
 
+// WARNING: When adding session persistence (e.g., WithInMemorySessionStore), or running in production,
+// make sure to also register a SessionIsolationKeyProvider to scope sessions by principal in multi-user
+// deployments, e.g.:
+// builder.Services.UseClaimsBasedSessionIsolation(new() { ClaimType = ClaimTypes.NameIdentifier });
+
 WebApplication app = builder.Build();
 
 string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"]

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

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

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

@@ -10,6 +10,11 @@ WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
 builder.Services.AddHttpClient().AddLogging();
 builder.Services.AddAGUI();
 
+// WARNING: When adding session persistence (e.g., WithInMemorySessionStore), or running in production,
+// make sure to also register a SessionIsolationKeyProvider to scope sessions by principal in multi-user
+// deployments, e.g.:
+// builder.Services.UseClaimsBasedSessionIsolation(new() { ClaimType = ClaimTypes.NameIdentifier });
+
 WebApplication app = builder.Build();
 
 string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"]

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

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

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

@@ -27,6 +27,11 @@ builder.Services.ConfigureHttpJsonOptions(options =>
     options.SerializerOptions.TypeInfoResolverChain.Add(ApprovalJsonContext.Default));
 builder.Services.AddAGUI();
 
+// WARNING: When adding session persistence (e.g., WithInMemorySessionStore), or running in production,
+// make sure to also register a SessionIsolationKeyProvider to scope sessions by principal in multi-user
+// deployments, e.g.:
+// builder.Services.UseClaimsBasedSessionIsolation(new() { ClaimType = ClaimTypes.NameIdentifier });
+
 WebApplication app = builder.Build();
 
 app.UseHttpLogging();

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

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

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

@@ -17,6 +17,11 @@ builder.Services.AddAGUI();
 // Configure to listen on port 8888
 builder.WebHost.UseUrls("http://localhost:8888");
 
+// WARNING: When adding session persistence (e.g., WithInMemorySessionStore), or running in production,
+// make sure to also register a SessionIsolationKeyProvider to scope sessions by principal in multi-user
+// deployments, e.g.:
+// builder.Services.UseClaimsBasedSessionIsolation(new() { ClaimType = ClaimTypes.NameIdentifier });
+
 WebApplication app = builder.Build();
 
 string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"]

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

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

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

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

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-McpTools/HostedMcpTools.csproj

@@ -13,7 +13,7 @@
   <ItemGroup>
     <PackageReference Include="Azure.AI.Projects" />
     <PackageReference Include="Azure.Identity" />
-    <PackageReference Include="ModelContextProtocol" VersionOverride="1.2.0" />
+    <PackageReference Include="ModelContextProtocol" />
     <PackageReference Include="DotNetEnv" />
   </ItemGroup>
 

dotnet/samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/AGUIDojoServer.csproj

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

dotnet/samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/Program.cs

@@ -19,6 +19,11 @@ builder.Services.AddHttpClient().AddLogging();
 builder.Services.ConfigureHttpJsonOptions(options => options.SerializerOptions.TypeInfoResolverChain.Add(AGUIDojoServerSerializerContext.Default));
 builder.Services.AddAGUI();
 
+// WARNING: When adding session persistence (e.g., WithInMemorySessionStore), or running in production,
+// make sure to also register a SessionIsolationKeyProvider to scope sessions by principal in multi-user
+// deployments, e.g.:
+// builder.Services.UseClaimsBasedSessionIsolation(new() { ClaimType = ClaimTypes.NameIdentifier });
+
 WebApplication app = builder.Build();
 
 app.UseHttpLogging();

dotnet/samples/05-end-to-end/AGUIClientServer/AGUIServer/Program.cs

@@ -49,8 +49,9 @@ var agent = new AzureOpenAIClient(
                 AGUIServerSerializerContext.Default.Options)
         ]);
 
-// When running in production, make sure to use an SessionIsolationKeyProvider, e.g. ClaimsIdentity-based
-// if using Claims-based Identity for Authentication/Authorization
+// WARNING: When adding session persistence (e.g., WithInMemorySessionStore), or running in production,
+// make sure to also register a SessionIsolationKeyProvider to scope sessions by principal in multi-user
+// deployments, e.g.:
 // builder.Services.UseClaimsBasedSessionIsolation(new() { ClaimType = ClaimTypes.NameIdentifier });
 
 // Register the agent with the host and configure it to use an in-memory session store

dotnet/samples/05-end-to-end/AGUIWebChat/Server/AGUIWebChatServer.csproj

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

dotnet/samples/05-end-to-end/AGUIWebChat/Server/Program.cs

@@ -12,6 +12,11 @@ WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
 builder.Services.AddHttpClient().AddLogging();
 builder.Services.AddAGUI();
 
+// WARNING: When adding session persistence (e.g., WithInMemorySessionStore), or running in production,
+// make sure to also register a SessionIsolationKeyProvider to scope sessions by principal in multi-user
+// deployments, e.g.:
+// builder.Services.UseClaimsBasedSessionIsolation(new() { ClaimType = ClaimTypes.NameIdentifier });
+
 WebApplication app = builder.Build();
 
 string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"] ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");

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

@@ -1,7 +1,9 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using System;
 using System.Diagnostics.CodeAnalysis;
 using Microsoft.Agents.AI;
+using Microsoft.Extensions.Logging;
 using Microsoft.Shared.DiagnosticIds;
 
 namespace Microsoft.Extensions.AI;
@@ -32,11 +34,19 @@ public static class ChatClientHarnessExtensions
     /// additional context providers, and chat history provider.
     /// When <see langword="null"/>, the agent uses built-in default settings.
     /// </param>
+    /// <param name="loggerFactory">
+    /// Optional logger factory for creating loggers used by the agent and its components.
+    /// </param>
+    /// <param name="services">
+    /// Optional service provider for resolving dependencies required by AI functions and other agent components.
+    /// </param>
     /// <returns>A new <see cref="HarnessAgent"/> instance.</returns>
     public static HarnessAgent AsHarnessAgent(
         this IChatClient chatClient,
         int maxContextWindowTokens,
         int maxOutputTokens,
-        HarnessAgentOptions? options = null) =>
-        new(chatClient, maxContextWindowTokens, maxOutputTokens, options);
+        HarnessAgentOptions? options = null,
+        ILoggerFactory? loggerFactory = null,
+        IServiceProvider? services = null) =>
+        new(chatClient, maxContextWindowTokens, maxOutputTokens, options, loggerFactory, services);
 }

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

@@ -10,6 +10,7 @@ using Microsoft.Agents.AI.Compaction;
 using Microsoft.Agents.AI.Tools.Shell;
 #endif
 using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Logging;
 using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 
@@ -105,6 +106,12 @@ public sealed class HarnessAgent : DelegatingAIAgent
     /// additional context providers, and chat history provider.
     /// When <see langword="null"/>, the agent uses built-in default settings.
     /// </param>
+    /// <param name="loggerFactory">
+    /// Optional logger factory for creating loggers used by the agent and its components.
+    /// </param>
+    /// <param name="services">
+    /// Optional service provider for resolving dependencies required by AI functions and other agent components.
+    /// </param>
     /// <exception cref="ArgumentNullException">
     /// <paramref name="chatClient"/> is <see langword="null"/>.
     /// </exception>
@@ -112,24 +119,26 @@ public sealed class HarnessAgent : DelegatingAIAgent
     /// <paramref name="maxContextWindowTokens"/> is not positive, or
     /// <paramref name="maxOutputTokens"/> is negative or greater than or equal to <paramref name="maxContextWindowTokens"/>.
     /// </exception>
-    public HarnessAgent(IChatClient chatClient, int maxContextWindowTokens, int maxOutputTokens, HarnessAgentOptions? options = null)
+    public HarnessAgent(IChatClient chatClient, int maxContextWindowTokens, int maxOutputTokens, HarnessAgentOptions? options = null, ILoggerFactory? loggerFactory = null, IServiceProvider? services = null)
         : base(BuildAgent(
             Throw.IfNull(chatClient),
             maxContextWindowTokens,
             maxOutputTokens,
-            options))
+            options,
+            loggerFactory,
+            services))
     {
     }
 
-    private static AIAgent BuildAgent(IChatClient chatClient, int maxContextWindowTokens, int maxOutputTokens, HarnessAgentOptions? options)
+    private static AIAgent BuildAgent(IChatClient chatClient, int maxContextWindowTokens, int maxOutputTokens, HarnessAgentOptions? options, ILoggerFactory? loggerFactory, IServiceProvider? services)
     {
-        ChatClientAgent innerAgent = BuildInnerAgent(chatClient, maxContextWindowTokens, maxOutputTokens, options);
+        ChatClientAgent innerAgent = BuildInnerAgent(chatClient, maxContextWindowTokens, maxOutputTokens, options, loggerFactory, services);
 
         AIAgentBuilder builder = innerAgent.AsBuilder();
 
         if (options?.DisableToolApproval is not true)
         {
-            builder.UseToolApproval();
+            builder.UseToolApproval(options?.ToolApprovalAgentOptions);
         }
 
         if (options?.DisableOpenTelemetry is not true)
@@ -137,10 +146,10 @@ public sealed class HarnessAgent : DelegatingAIAgent
             builder.UseOpenTelemetry(sourceName: options?.OpenTelemetrySourceName);
         }
 
-        return builder.Build();
+        return builder.Build(services);
     }
 
-    private static ChatClientAgent BuildInnerAgent(IChatClient chatClient, int maxContextWindowTokens, int maxOutputTokens, HarnessAgentOptions? options)
+    private static ChatClientAgent BuildInnerAgent(IChatClient chatClient, int maxContextWindowTokens, int maxOutputTokens, HarnessAgentOptions? options, ILoggerFactory? loggerFactory, IServiceProvider? services)
     {
         var compactionStrategy = new ContextWindowCompactionStrategy(
             maxContextWindowTokens: maxContextWindowTokens,
@@ -165,13 +174,13 @@ public sealed class HarnessAgent : DelegatingAIAgent
 
         ChatOptions chatOptions = BuildChatOptions(options, instructions, maxOutputTokens);
 
-        var compactionProvider = new CompactionProvider(compactionStrategy);
+        var compactionProvider = new CompactionProvider(compactionStrategy, loggerFactory: loggerFactory);
 
-        IEnumerable<AIContextProvider> contextProviders = BuildContextProviders(options);
+        IEnumerable<AIContextProvider> contextProviders = BuildContextProviders(options, loggerFactory);
 
         return chatClient
             .AsBuilder()
-            .UseFunctionInvocation(configure: options?.MaximumIterationsPerRequest is int maxIterations
+            .UseFunctionInvocation(loggerFactory, configure: options?.MaximumIterationsPerRequest is int maxIterations
                 ? ficc => ficc.MaximumIterationsPerRequest = maxIterations
                 : null)
             .UseMessageInjection()
@@ -189,7 +198,9 @@ public sealed class HarnessAgent : DelegatingAIAgent
                 RequirePerServiceCallChatHistoryPersistence = true,
                 WarnOnChatHistoryProviderConflict = false,
                 ThrowOnChatHistoryProviderConflict = false,
-            });
+            },
+            loggerFactory,
+            services);
     }
 
     private static ChatOptions BuildChatOptions(HarnessAgentOptions? options, string instructions, int maxOutputTokens)
@@ -215,7 +226,7 @@ public sealed class HarnessAgent : DelegatingAIAgent
         return result;
     }
 
-    private static List<AIContextProvider> BuildContextProviders(HarnessAgentOptions? options)
+    private static List<AIContextProvider> BuildContextProviders(HarnessAgentOptions? options, ILoggerFactory? loggerFactory)
     {
         var providers = new List<AIContextProvider>();
 
@@ -255,8 +266,8 @@ public sealed class HarnessAgent : DelegatingAIAgent
         if (options?.DisableAgentSkillsProvider is not true)
         {
             AgentSkillsProvider skillsProvider = options?.AgentSkillsSource is AgentSkillsSource source
-                ? new AgentSkillsProvider(source)
-                : new AgentSkillsProvider(Directory.GetCurrentDirectory());
+                ? new AgentSkillsProvider(source, loggerFactory: loggerFactory)
+                : new AgentSkillsProvider(Directory.GetCurrentDirectory(), loggerFactory: loggerFactory);
 
             providers.Add(skillsProvider);
         }

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

@@ -101,6 +101,15 @@ public sealed class HarnessAgentOptions
     /// </remarks>
     public bool DisableToolApproval { get; set; }
 
+    /// <summary>
+    /// Gets or sets the options for the <see cref="ToolApprovalAgent"/> middleware.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="null"/>, the <see cref="ToolApprovalAgent"/> uses default settings.
+    /// This property has no effect when <see cref="DisableToolApproval"/> is <see langword="true"/>.
+    /// </remarks>
+    public ToolApprovalAgentOptions? ToolApprovalAgentOptions { get; set; }
+
     /// <summary>
     /// Gets or sets a value indicating whether the <see cref="FileMemoryProvider"/> is disabled.
     /// </summary>

dotnet/src/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore/AGUIEndpointRouteBuilderExtensions.cs

@@ -103,7 +103,16 @@ public static class AGUIEndpointRouteBuilderExtensions
         ArgumentNullException.ThrowIfNull(aiAgent);
 
         var agentSessionStore = endpoints.ServiceProvider.GetKeyedService<AgentSessionStore>(aiAgent.Name);
-        var hostAgent = new AIHostAgent(aiAgent, agentSessionStore ?? new NoopAgentSessionStore());
+
+        // Ensure that we have an IsolationKeyScopedAgentSessionStore registered.
+        var isolationKeyProvider = endpoints.ServiceProvider.GetService<SessionIsolationKeyProvider>();
+        if (agentSessionStore?.GetService<IsolationKeyScopedAgentSessionStore>() is null)
+        {
+            agentSessionStore ??= new NoopAgentSessionStore();
+            agentSessionStore = new IsolationKeyScopedAgentSessionStore(agentSessionStore, isolationKeyProvider, new() { Strict = isolationKeyProvider != null });
+        }
+
+        var hostAgent = new AIHostAgent(aiAgent, agentSessionStore);
 
         return endpoints.MapPost(pattern, async ([FromBody] RunAgentInput? input, HttpContext context, CancellationToken cancellationToken) =>
         {

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ObjectModel/ForeachExecutor.cs

@@ -49,7 +49,7 @@ internal sealed class ForeachExecutor : DeclarativeActionExecutor<Foreach>
         EvaluationResult<DataValue> expressionResult = this.Evaluator.GetValue(this.Model.Items);
         if (expressionResult.Value is TableDataValue tableValue)
         {
-            this._values = [.. tableValue.Values.Select(value => value.Properties.Values.First().ToFormula())];
+            this._values = [.. tableValue.Values.Select(value => value.ToFormula())];
         }
         else
         {

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ObjectModel/InvokeMcpToolExecutor.cs

@@ -27,6 +27,14 @@ internal sealed class InvokeMcpToolExecutor(
     WorkflowFormulaState state) :
     DeclarativeActionExecutor<InvokeMcpTool>(model, state)
 {
+    private const string ApprovalSnapshotStateKey = nameof(_approvalSnapshot);
+
+    /// <summary>
+    /// Snapshot of evaluated parameters at approval-request time.
+    /// Used to prevent TOCTOU attacks where state mutates during the approval window.
+    /// </summary>
+    private ApprovalSnapshot? _approvalSnapshot;
+
     /// <summary>
     /// Step identifiers for the MCP tool invocation workflow.
     /// </summary>
@@ -75,6 +83,10 @@ internal sealed class InvokeMcpToolExecutor(
 
         if (requireApproval)
         {
+            // Snapshot the evaluated parameters to prevent TOCTOU attacks.
+            // If state mutates during the approval window, the approved values are used on resume.
+            this._approvalSnapshot = new ApprovalSnapshot(serverUrl, serverLabel, toolName, arguments, connectionName);
+
             // Create tool call content for approval request.
             // Transport headers (e.g. Authorization) are intentionally excluded from the
             // approval event: they must not cross into the externally-surfaced approval request.
@@ -137,13 +149,14 @@ internal sealed class InvokeMcpToolExecutor(
             return;
         }
 
-        // Approved - now invoke the tool
-        string serverUrl = this.GetServerUrl();
-        string? serverLabel = this.GetServerLabel();
-        string toolName = this.GetToolName();
-        Dictionary<string, object?>? arguments = this.GetArguments();
+        // Approved - use the snapshot from approval-request time to prevent TOCTOU attacks.
+        // Headers are re-evaluated (they may contain auth secrets that should not be persisted).
+        string serverUrl = this._approvalSnapshot?.ServerUrl ?? this.GetServerUrl();
+        string? serverLabel = this._approvalSnapshot?.ServerLabel ?? this.GetServerLabel();
+        string toolName = this._approvalSnapshot?.ToolName ?? this.GetToolName();
+        Dictionary<string, object?>? arguments = this._approvalSnapshot?.Arguments ?? this.GetArguments();
         Dictionary<string, string>? headers = this.GetHeaders();
-        string? connectionName = this.GetConnectionName();
+        string? connectionName = this._approvalSnapshot?.ConnectionName ?? this.GetConnectionName();
 
         McpServerToolResultContent resultContent = await mcpToolHandler.InvokeToolAsync(
             serverUrl,
@@ -162,9 +175,33 @@ internal sealed class InvokeMcpToolExecutor(
     /// </summary>
     public async ValueTask CompleteAsync(IWorkflowContext context, ActionExecutorResult message, CancellationToken cancellationToken)
     {
+        // Clear the approval snapshot after successful completion.
+        this._approvalSnapshot = null;
+        await ClearSnapshotStateAsync(context, cancellationToken).ConfigureAwait(false);
+
         await context.RaiseCompletionEventAsync(this.Model, cancellationToken).ConfigureAwait(false);
     }
 
+    /// <inheritdoc/>
+    /// <remarks>
+    /// Persists the approval snapshot to workflow state so it survives checkpoint/restore cycles.
+    /// </remarks>
+    protected override async ValueTask OnCheckpointingAsync(IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        await context.QueueStateUpdateAsync(ApprovalSnapshotStateKey, this._approvalSnapshot, null, cancellationToken).ConfigureAwait(false);
+        await base.OnCheckpointingAsync(context, cancellationToken).ConfigureAwait(false);
+    }
+
+    /// <inheritdoc/>
+    /// <remarks>
+    /// Restores the approval snapshot from workflow state after a checkpoint restore.
+    /// </remarks>
+    protected override async ValueTask OnCheckpointRestoredAsync(IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        await base.OnCheckpointRestoredAsync(context, cancellationToken).ConfigureAwait(false);
+        this._approvalSnapshot = await context.ReadStateAsync<ApprovalSnapshot>(ApprovalSnapshotStateKey, null, cancellationToken).ConfigureAwait(false);
+    }
+
     private async ValueTask ProcessResultAsync(IWorkflowContext context, McpServerToolResultContent resultContent, CancellationToken cancellationToken)
     {
         bool autoSend = this.GetAutoSendValue();
@@ -365,4 +402,24 @@ internal sealed class InvokeMcpToolExecutor(
 
         return result;
     }
+
+    /// <summary>
+    /// Clears the persisted approval snapshot state after a successful tool invocation.
+    /// </summary>
+    private static async ValueTask ClearSnapshotStateAsync(IWorkflowContext context, CancellationToken cancellationToken)
+    {
+        await context.QueueStateUpdateAsync<ApprovalSnapshot?>(ApprovalSnapshotStateKey, null, null, cancellationToken).ConfigureAwait(false);
+    }
+
+    /// <summary>
+    /// Stores the evaluated parameters at approval-request time so that
+    /// <see cref="CaptureResponseAsync"/> uses the values the user reviewed,
+    /// even if <see cref="WorkflowFormulaState"/> mutates during the approval window.
+    /// </summary>
+    internal sealed record ApprovalSnapshot(
+        string ServerUrl,
+        string? ServerLabel,
+        string ToolName,
+        Dictionary<string, object?>? Arguments,
+        string? ConnectionName);
 }

dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgentOptions.cs

@@ -181,6 +181,36 @@ public sealed class ChatClientAgentOptions
     [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
     public bool EnableMessageInjection { get; set; }
 
+    /// <summary>
+    /// Gets or sets a value indicating whether to store automatically approved function calls in the session state
+    /// for tools that do not require approval when they are returned alongside tools that do.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// <see cref="FunctionInvokingChatClient"/> has an all-or-nothing behavior for approvals: when any tool
+    /// in a response is an <see cref="ApprovalRequiredAIFunction"/>, it converts all <see cref="FunctionCallContent"/>
+    /// items to <see cref="ToolApprovalRequestContent"/>, even for tools that do not require approval.
+    /// </para>
+    /// <para>
+    /// Setting this property to <see langword="true"/> injects an <see cref="NonApprovalRequiredFunctionBypassingChatClient"/>
+    /// decorator above <see cref="FunctionInvokingChatClient"/> in the pipeline. This decorator identifies approval
+    /// requests for non-approval-required tools, removes them from the response, and stores them in the session.
+    /// On the next request, the stored items are automatically re-injected as approved, so the caller only needs
+    /// to handle approval requests for tools that truly require human approval.
+    /// </para>
+    /// <para>
+    /// This option has no effect when <see cref="UseProvidedChatClientAsIs"/> is <see langword="true"/>.
+    /// When using a custom chat client stack, you can add an <see cref="NonApprovalRequiredFunctionBypassingChatClient"/>
+    /// manually via the <see cref="ChatClientBuilderExtensions.UseNonApprovalRequiredFunctionBypassing"/>
+    /// extension method.
+    /// </para>
+    /// </remarks>
+    /// <value>
+    /// Default is <see langword="false"/>.
+    /// </value>
+    [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+    public bool EnableNonApprovalRequiredFunctionBypassing { get; set; }
+
     /// <summary>
     /// Creates a new instance of <see cref="ChatClientAgentOptions"/> with the same values as this instance.
     /// </summary>
@@ -199,5 +229,6 @@ public sealed class ChatClientAgentOptions
             ThrowOnChatHistoryProviderConflict = this.ThrowOnChatHistoryProviderConflict,
             RequirePerServiceCallChatHistoryPersistence = this.RequirePerServiceCallChatHistoryPersistence,
             EnableMessageInjection = this.EnableMessageInjection,
+            EnableNonApprovalRequiredFunctionBypassing = this.EnableNonApprovalRequiredFunctionBypassing,
         };
 }

dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientBuilderExtensions.cs

@@ -148,4 +148,35 @@ public static class ChatClientBuilderExtensions
     {
         return builder.Use(innerClient => new MessageInjectingChatClient(innerClient));
     }
+
+    /// <summary>
+    /// Adds an <see cref="NonApprovalRequiredFunctionBypassingChatClient"/> to the chat client pipeline.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This decorator should be positioned above the <see cref="FunctionInvokingChatClient"/> in the pipeline
+    /// so that it can intercept approval requests for tools that do not require approval. When
+    /// <see cref="FunctionInvokingChatClient"/> converts all function calls to approval requests (because at
+    /// least one tool requires approval), this decorator removes the requests for non-approval-required tools,
+    /// stores them in the session, and automatically re-injects them as approved on the next request.
+    /// </para>
+    /// <para>
+    /// This extension method is intended for use with custom chat client stacks when
+    /// <see cref="ChatClientAgentOptions.UseProvidedChatClientAsIs"/> is <see langword="true"/>.
+    /// When <see cref="ChatClientAgentOptions.UseProvidedChatClientAsIs"/> is <see langword="false"/> (the default),
+    /// the <see cref="ChatClientAgent"/> automatically injects this decorator when
+    /// <see cref="ChatClientAgentOptions.EnableNonApprovalRequiredFunctionBypassing"/> is <see langword="true"/>.
+    /// </para>
+    /// <para>
+    /// This decorator only works within the context of a running <see cref="ChatClientAgent"/> with
+    /// an active session, and will throw an exception if used in any other stack.
+    /// </para>
+    /// </remarks>
+    /// <param name="builder">The <see cref="ChatClientBuilder"/> to add the decorator to.</param>
+    /// <returns>The <paramref name="builder"/> for chaining.</returns>
+    [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+    public static ChatClientBuilder UseNonApprovalRequiredFunctionBypassing(this ChatClientBuilder builder)
+    {
+        return builder.Use(innerClient => new NonApprovalRequiredFunctionBypassingChatClient(innerClient));
+    }
 }

dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientExtensions.cs

@@ -53,6 +53,17 @@ public static class ChatClientExtensions
     {
         var chatBuilder = chatClient.AsBuilder();
 
+        // NonApprovalRequiredFunctionBypassingChatClient is registered before FunctionInvokingChatClient so that
+        // it sits above FICC in the pipeline. ChatClientBuilder.Build applies factories in reverse order,
+        // making the first Use() call outermost. By adding this decorator first, the resulting pipeline is:
+        //   NonApprovalRequiredFunctionBypassingChatClient → FunctionInvokingChatClient → ChatHistoryPersistingChatClient → leaf IChatClient
+        // This allows the decorator to intercept FICC's responses and remove approval requests for tools
+        // that don't actually require approval, storing them for automatic re-injection on the next request.
+        if (options?.EnableNonApprovalRequiredFunctionBypassing is true)
+        {
+            chatBuilder.Use(innerClient => new NonApprovalRequiredFunctionBypassingChatClient(innerClient));
+        }
+
         if (chatClient.GetService<FunctionInvokingChatClient>() is null)
         {
             chatBuilder.Use((innerClient, services) =>

dotnet/src/Microsoft.Agents.AI/ChatClient/NonApprovalRequiredFunctionBypassingChatClient.cs

@@ -0,0 +1,285 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Runtime.CompilerServices;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// A delegating chat client that automatically removes <see cref="ToolApprovalRequestContent"/> for tools
+/// that do not actually require approval, storing auto-approved results in the session for transparent
+/// re-injection on the next request.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <see cref="FunctionInvokingChatClient"/> has an all-or-nothing behavior for approvals: when any tool
+/// in a response is an <see cref="ApprovalRequiredAIFunction"/>, it converts all <see cref="FunctionCallContent"/>
+/// items to <see cref="ToolApprovalRequestContent"/> — even for tools that do not require approval. This
+/// decorator sits above <see cref="FunctionInvokingChatClient"/> in the pipeline and transparently handles
+/// the non-approval-required items so callers only see approval requests for tools that truly need them.
+/// </para>
+/// <para>
+/// On outbound responses, the decorator identifies <see cref="ToolApprovalRequestContent"/> items for tools
+/// that are not wrapped in <see cref="ApprovalRequiredAIFunction"/>, removes them from the response, and
+/// stores them in the session's <see cref="AgentSessionStateBag"/>. On the next inbound request, the stored
+/// items are re-injected as pre-approved <see cref="ToolApprovalResponseContent"/> so that
+/// <see cref="FunctionInvokingChatClient"/> can process them alongside the caller's human-approved responses.
+/// </para>
+/// <para>
+/// This decorator requires an active <see cref="AIAgent.CurrentRunContext"/> with a non-null
+/// <see cref="AgentRunContext.Session"/>. An <see cref="InvalidOperationException"/> is thrown if no
+/// run context or session is available.
+/// </para>
+/// </remarks>
+internal sealed class NonApprovalRequiredFunctionBypassingChatClient : DelegatingChatClient
+{
+    /// <summary>
+    /// The key used in <see cref="AgentSessionStateBag"/> to store pending auto-approved function calls
+    /// between agent runs.
+    /// </summary>
+    internal const string StateBagKey = "_autoApprovedFunctionCalls";
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="NonApprovalRequiredFunctionBypassingChatClient"/> class.
+    /// </summary>
+    /// <param name="innerClient">The underlying chat client (typically a <see cref="FunctionInvokingChatClient"/>).</param>
+    public NonApprovalRequiredFunctionBypassingChatClient(IChatClient innerClient)
+        : base(innerClient)
+    {
+    }
+
+    /// <inheritdoc/>
+    public override async Task<ChatResponse> GetResponseAsync(
+        IEnumerable<ChatMessage> messages,
+        ChatOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        var session = GetRequiredSession();
+        var autoApprovableNames = this.GetAutoApprovableToolNames(options);
+
+        messages = InjectPendingAutoApprovals(messages, session);
+
+        var response = await base.GetResponseAsync(messages, options, cancellationToken).ConfigureAwait(false);
+
+        RemoveAutoApprovedFromMessages(response.Messages, autoApprovableNames, session);
+
+        return response;
+    }
+
+    /// <inheritdoc/>
+    public override async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
+        IEnumerable<ChatMessage> messages,
+        ChatOptions? options = null,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        var session = GetRequiredSession();
+        var autoApprovableNames = this.GetAutoApprovableToolNames(options);
+
+        messages = InjectPendingAutoApprovals(messages, session);
+        List<ToolApprovalRequestContent>? autoApproved = null;
+
+        try
+        {
+            await foreach (var update in base.GetStreamingResponseAsync(messages, options, cancellationToken).ConfigureAwait(false))
+            {
+                if (FilterUpdateContents(update, autoApprovableNames, ref autoApproved))
+                {
+                    yield return update;
+                }
+            }
+        }
+        finally
+        {
+            if (autoApproved is { Count: > 0 })
+            {
+                session.StateBag.SetValue(StateBagKey, autoApproved, AgentJsonUtilities.DefaultOptions);
+            }
+        }
+    }
+
+    /// <summary>
+    /// Gets the current <see cref="AgentSession"/> from the ambient run context.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">No run context or session is available.</exception>
+    private static AgentSession GetRequiredSession()
+    {
+        var runContext = AIAgent.CurrentRunContext
+            ?? throw new InvalidOperationException(
+                $"{nameof(NonApprovalRequiredFunctionBypassingChatClient)} can only be used within the context of a running AIAgent. " +
+                "Ensure that the chat client is being invoked as part of an AIAgent.RunAsync or AIAgent.RunStreamingAsync call.");
+
+        return runContext.Session
+            ?? throw new InvalidOperationException(
+                $"{nameof(NonApprovalRequiredFunctionBypassingChatClient)} requires a session. " +
+                "Ensure the agent has a resolved session before invoking the chat client.");
+    }
+
+    /// <summary>
+    /// Checks the session for stored auto-approvals from a previous turn and injects them as
+    /// a user message containing <see cref="ToolApprovalResponseContent"/> items appended to the input messages.
+    /// </summary>
+    /// <remarks>
+    /// All stored requests are unconditionally injected as approved responses regardless of whether the
+    /// tool set has changed, because the LLM requires a complete set of tool call responses for a prior turn.
+    /// </remarks>
+    private static IEnumerable<ChatMessage> InjectPendingAutoApprovals(
+        IEnumerable<ChatMessage> messages,
+        AgentSession session)
+    {
+        if (!session.StateBag.TryGetValue<List<ToolApprovalRequestContent>>(
+            StateBagKey,
+            out var pendingRequests,
+            AgentJsonUtilities.DefaultOptions)
+            || pendingRequests is not { Count: > 0 })
+        {
+            return messages;
+        }
+
+        session.StateBag.TryRemoveValue(StateBagKey);
+
+        List<AIContent> approvalResponses = [];
+        foreach (var request in pendingRequests)
+        {
+            approvalResponses.Add(request.CreateResponse(approved: true));
+        }
+
+        var userMessage = new ChatMessage(ChatRole.User, approvalResponses);
+        return messages.Concat([userMessage]);
+    }
+
+    /// <summary>
+    /// Builds a set of tool names that do not require approval and can be auto-approved,
+    /// by checking all available tools from <see cref="ChatOptions.Tools"/> and
+    /// <see cref="FunctionInvokingChatClient.AdditionalTools"/>.
+    /// </summary>
+    private HashSet<string> GetAutoApprovableToolNames(ChatOptions? options)
+    {
+        var ficc = this.GetService<FunctionInvokingChatClient>();
+
+        var allTools = (options?.Tools ?? Enumerable.Empty<AITool>())
+            .Concat(ficc?.AdditionalTools ?? Enumerable.Empty<AITool>());
+
+        return new HashSet<string>(
+            allTools
+                .OfType<AIFunction>()
+                .Where(static f => f.GetService<ApprovalRequiredAIFunction>() is null)
+                .Select(static f => f.Name),
+            StringComparer.Ordinal);
+    }
+
+    /// <summary>
+    /// Determines whether a <see cref="ToolApprovalRequestContent"/> can be auto-approved because
+    /// the underlying tool is not an <see cref="ApprovalRequiredAIFunction"/>.
+    /// </summary>
+    /// <returns>
+    /// <see langword="true"/> if the approval request is for a known tool that does not require approval
+    /// and can be auto-approved; <see langword="false"/> otherwise.
+    /// </returns>
+    private static bool IsAutoApprovable(ToolApprovalRequestContent approval, HashSet<string> autoApprovableNames)
+    {
+        if (approval.ToolCall is not FunctionCallContent fcc)
+        {
+            // Non-function tool calls cannot be auto-approved.
+            return false;
+        }
+
+        // Auto-approve only if the tool is known and explicitly does NOT require approval.
+        // Unknown tools are not in the set and are treated as approval-required (safe default).
+        return autoApprovableNames.Contains(fcc.Name);
+    }
+
+    /// <summary>
+    /// Scans response messages for auto-approvable <see cref="ToolApprovalRequestContent"/> items,
+    /// removes them from the messages, and stores them in the session for the next request.
+    /// </summary>
+    private static void RemoveAutoApprovedFromMessages(
+        IList<ChatMessage> messages,
+        HashSet<string> autoApprovableNames,
+        AgentSession session)
+    {
+        List<ToolApprovalRequestContent>? autoApproved = null;
+
+        foreach (var message in messages)
+        {
+            for (int i = message.Contents.Count - 1; i >= 0; i--)
+            {
+                if (message.Contents[i] is ToolApprovalRequestContent approval
+                    && IsAutoApprovable(approval, autoApprovableNames))
+                {
+                    (autoApproved ??= []).Add(approval);
+                    message.Contents.RemoveAt(i);
+                }
+            }
+        }
+
+        // Remove messages that are now empty after filtering.
+        for (int i = messages.Count - 1; i >= 0; i--)
+        {
+            if (messages[i].Contents.Count == 0)
+            {
+                messages.RemoveAt(i);
+            }
+        }
+
+        if (autoApproved is { Count: > 0 })
+        {
+            session.StateBag.SetValue(StateBagKey, autoApproved, AgentJsonUtilities.DefaultOptions);
+        }
+    }
+
+    /// <summary>
+    /// Filters auto-approvable <see cref="ToolApprovalRequestContent"/> items from a streaming update's
+    /// contents, collecting them for later storage.
+    /// </summary>
+    /// <returns>
+    /// <see langword="true"/> if the update should be yielded (has remaining content or had no
+    /// approval content to begin with); <see langword="false"/> if the update is now empty and
+    /// should be skipped.
+    /// </returns>
+    private static bool FilterUpdateContents(
+        ChatResponseUpdate update,
+        HashSet<string> autoApprovableNames,
+        ref List<ToolApprovalRequestContent>? autoApproved)
+    {
+        bool hasApprovalContent = false;
+        List<AIContent> filteredContents = [];
+        bool removedAny = false;
+
+        for (int i = 0; i < update.Contents.Count; i++)
+        {
+            var content = update.Contents[i];
+
+            if (content is ToolApprovalRequestContent approval)
+            {
+                hasApprovalContent = true;
+
+                if (IsAutoApprovable(approval, autoApprovableNames))
+                {
+                    (autoApproved ??= []).Add(approval);
+                    removedAny = true;
+                }
+                else
+                {
+                    filteredContents.Add(content);
+                }
+            }
+            else
+            {
+                filteredContents.Add(content);
+            }
+        }
+
+        if (removedAny)
+        {
+            update.Contents = filteredContents;
+        }
+
+        // Yield the update unless it was purely auto-approvable approval content (now empty).
+        return update.Contents.Count > 0 || !hasApprovalContent;
+    }
+}

dotnet/src/Microsoft.Agents.AI/Harness/ToolApproval/ToolApprovalAgent.cs

@@ -51,20 +51,22 @@ public sealed class ToolApprovalAgent : DelegatingAIAgent
 {
     private readonly ProviderSessionState<ToolApprovalState> _sessionState;
     private readonly JsonSerializerOptions _jsonSerializerOptions;
+    private readonly Func<FunctionCallContent, ValueTask<bool>>[]? _autoApprovalRules;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="ToolApprovalAgent"/> class.
     /// </summary>
     /// <param name="innerAgent">The underlying agent to delegate to.</param>
-    /// <param name="jsonSerializerOptions">
-    /// Optional <see cref="JsonSerializerOptions"/> used for serializing argument values when storing rules
-    /// and for persisting state. When <see langword="null"/>, <see cref="AgentJsonUtilities.DefaultOptions"/> is used.
+    /// <param name="options">
+    /// Optional <see cref="ToolApprovalAgentOptions"/> for configuring serialization and auto-approval rules.
+    /// When <see langword="null"/>, default settings are used.
     /// </param>
     /// <exception cref="ArgumentNullException"><paramref name="innerAgent"/> is <see langword="null"/>.</exception>
-    public ToolApprovalAgent(AIAgent innerAgent, JsonSerializerOptions? jsonSerializerOptions = null)
+    public ToolApprovalAgent(AIAgent innerAgent, ToolApprovalAgentOptions? options = null)
         : base(innerAgent)
     {
-        this._jsonSerializerOptions = jsonSerializerOptions ?? AgentJsonUtilities.DefaultOptions;
+        this._jsonSerializerOptions = options?.JsonSerializerOptions ?? AgentJsonUtilities.DefaultOptions;
+        this._autoApprovalRules = options?.AutoApprovalRules?.ToArray();
         this._sessionState = new ProviderSessionState<ToolApprovalState>(
             _ => new ToolApprovalState(),
             "toolApprovalState",
@@ -79,7 +81,7 @@ public sealed class ToolApprovalAgent : DelegatingAIAgent
         CancellationToken cancellationToken = default)
     {
         // Steps 1–2: Unwrap AlwaysApprove wrappers, process any queued approval requests.
-        var (state, callerMessages, nextQueuedItem) = this.PrepareInboundMessages(messages, session);
+        var (state, callerMessages, nextQueuedItem) = await this.PrepareInboundMessagesAsync(messages, session).ConfigureAwait(false);
 
         if (nextQueuedItem is not null)
         {
@@ -98,7 +100,7 @@ public sealed class ToolApprovalAgent : DelegatingAIAgent
             var response = await this.InnerAgent.RunAsync(processedMessages, session, options, cancellationToken).ConfigureAwait(false);
 
             // Classify approval requests: auto-approve matching, queue excess, keep first unapproved.
-            bool allAutoApproved = this.ProcessAndQueueOutboundApprovalRequests(response.Messages, state, session);
+            bool allAutoApproved = await this.ProcessAndQueueOutboundApprovalRequestsAsync(response.Messages, state, session).ConfigureAwait(false);
 
             if (!allAutoApproved)
             {
@@ -119,7 +121,7 @@ public sealed class ToolApprovalAgent : DelegatingAIAgent
         [EnumeratorCancellation] CancellationToken cancellationToken = default)
     {
         // Steps 1–2: Unwrap AlwaysApprove wrappers, process any queued approval requests.
-        var (state, callerMessages, nextQueuedItem) = this.PrepareInboundMessages(messages, session);
+        var (state, callerMessages, nextQueuedItem) = await this.PrepareInboundMessagesAsync(messages, session).ConfigureAwait(false);
 
         if (nextQueuedItem is not null)
         {
@@ -197,7 +199,7 @@ public sealed class ToolApprovalAgent : DelegatingAIAgent
                 yield break;
             }
 
-            // 4. Classify the collected approval requests against standing rules.
+            // 4. Classify the collected approval requests against standing rules and auto-approval rules.
             List<ToolApprovalRequestContent> unapproved = [];
             foreach (var tarc in streamedApprovalRequests)
             {
@@ -206,6 +208,11 @@ public sealed class ToolApprovalAgent : DelegatingAIAgent
                     state.CollectedApprovalResponses.Add(
                         tarc.CreateResponse(approved: true, reason: "Auto-approved by standing rule"));
                 }
+                else if (await this.MatchesAutoApprovalRuleAsync(tarc).ConfigureAwait(false))
+                {
+                    state.CollectedApprovalResponses.Add(
+                        tarc.CreateResponse(approved: true, reason: "Auto-approved by auto-approval rule"));
+                }
                 else
                 {
                     unapproved.Add(tarc);
@@ -291,9 +298,9 @@ public sealed class ToolApprovalAgent : DelegatingAIAgent
     }
 
     /// <summary>
-    /// Re-evaluates queued approval requests against current rules and auto-approves any that now match.
+    /// Re-evaluates queued approval requests against current rules and auto-approval rules, and auto-approves any that now match.
     /// </summary>
-    private void DrainAutoApprovableFromQueue(ToolApprovalState state)
+    private async ValueTask DrainAutoApprovableFromQueueAsync(ToolApprovalState state)
     {
         for (int i = state.QueuedApprovalRequests.Count - 1; i >= 0; i--)
         {
@@ -303,6 +310,12 @@ public sealed class ToolApprovalAgent : DelegatingAIAgent
                     state.QueuedApprovalRequests[i].CreateResponse(approved: true, reason: "Auto-approved by standing rule"));
                 state.QueuedApprovalRequests.RemoveAt(i);
             }
+            else if (await this.MatchesAutoApprovalRuleAsync(state.QueuedApprovalRequests[i]).ConfigureAwait(false))
+            {
+                state.CollectedApprovalResponses.Add(
+                    state.QueuedApprovalRequests[i].CreateResponse(approved: true, reason: "Auto-approved by auto-approval rule"));
+                state.QueuedApprovalRequests.RemoveAt(i);
+            }
         }
     }
 
@@ -318,8 +331,8 @@ public sealed class ToolApprovalAgent : DelegatingAIAgent
     /// A tuple of (state, processed caller messages, next queued item or <see langword="null"/> if the queue is resolved).
     /// When the returned item is non-null, the caller should return/yield it without calling the inner agent.
     /// </returns>
-    private (ToolApprovalState State, List<ChatMessage> CallerMessages, ToolApprovalRequestContent? NextQueuedItem)
-        PrepareInboundMessages(IEnumerable<ChatMessage> messages, AgentSession? session)
+    private async ValueTask<(ToolApprovalState State, List<ChatMessage> CallerMessages, ToolApprovalRequestContent? NextQueuedItem)>
+        PrepareInboundMessagesAsync(IEnumerable<ChatMessage> messages, AgentSession? session)
     {
         var state = this._sessionState.GetOrInitializeState(session);
 
@@ -337,7 +350,7 @@ public sealed class ToolApprovalAgent : DelegatingAIAgent
 
             // Re-evaluate remaining queued items — the caller may have added new rules
             // (e.g., "always approve this tool") that resolve additional items.
-            this.DrainAutoApprovableFromQueue(state);
+            await this.DrainAutoApprovableFromQueueAsync(state).ConfigureAwait(false);
 
             if (state.QueuedApprovalRequests.Count > 0)
             {
@@ -386,15 +399,18 @@ public sealed class ToolApprovalAgent : DelegatingAIAgent
     /// <see langword="true"/> if all TARc items were auto-approved (caller should re-invoke the inner agent);
     /// <see langword="false"/> otherwise.
     /// </returns>
-    private bool ProcessAndQueueOutboundApprovalRequests(
+    private async ValueTask<bool> ProcessAndQueueOutboundApprovalRequestsAsync(
         IList<ChatMessage> responseMessages,
         ToolApprovalState state,
         AgentSession? session)
     {
-        // Pass 1: Scan all response messages and classify each approval request as
-        //         auto-approved (matches a standing rule) or unapproved (needs caller decision).
-        var autoApproved = new List<ToolApprovalRequestContent>();
+        // Pass 1: Scan all response messages and classify each approval request.
+        //         Auto-approved requests (matching a standing rule or auto-approval rule) have their
+        //         responses collected immediately, preserving the original request order, and are
+        //         marked for removal. Unapproved requests are collected for the caller to decide.
+        var toRemove = new HashSet<ToolApprovalRequestContent>();
         var unapproved = new List<ToolApprovalRequestContent>();
+        int autoApprovedCount = 0;
 
         foreach (var message in responseMessages)
         {
@@ -404,7 +420,17 @@ public sealed class ToolApprovalAgent : DelegatingAIAgent
                 {
                     if (MatchesRule(tarc, state.Rules, this._jsonSerializerOptions))
                     {
-                        autoApproved.Add(tarc);
+                        state.CollectedApprovalResponses.Add(
+                            tarc.CreateResponse(approved: true, reason: "Auto-approved by standing rule"));
+                        toRemove.Add(tarc);
+                        autoApprovedCount++;
+                    }
+                    else if (await this.MatchesAutoApprovalRuleAsync(tarc).ConfigureAwait(false))
+                    {
+                        state.CollectedApprovalResponses.Add(
+                            tarc.CreateResponse(approved: true, reason: "Auto-approved by auto-approval rule"));
+                        toRemove.Add(tarc);
+                        autoApprovedCount++;
                     }
                     else
                     {
@@ -415,18 +441,12 @@ public sealed class ToolApprovalAgent : DelegatingAIAgent
         }
 
         // Nothing to process: no auto-approved items and at most one unapproved (no queueing needed).
-        if (autoApproved.Count == 0 && unapproved.Count <= 1)
+        // No responses were collected above in this case, so state is unmodified and safe to leave.
+        if (autoApprovedCount == 0 && unapproved.Count <= 1)
         {
             return false;
         }
 
-        // Store auto-approved responses for later injection into the inner agent.
-        foreach (var tarc in autoApproved)
-        {
-            state.CollectedApprovalResponses.Add(
-                tarc.CreateResponse(approved: true, reason: "Auto-approved by standing rule"));
-        }
-
         // If every approval request was auto-approved, strip them all and signal the caller
         // to re-invoke the inner agent immediately with the collected responses.
         if (unapproved.Count == 0)
@@ -439,14 +459,10 @@ public sealed class ToolApprovalAgent : DelegatingAIAgent
         // Pass 2: Keep only the first unapproved request in the response (for the caller to decide).
         //         Queue the remaining unapproved requests for subsequent one-at-a-time delivery.
         //         Remove all auto-approved and queued items from the response messages.
-        var toRemove = new HashSet<ToolApprovalRequestContent>(autoApproved);
-        if (unapproved.Count > 1)
+        for (int i = 1; i < unapproved.Count; i++)
         {
-            for (int i = 1; i < unapproved.Count; i++)
-            {
-                toRemove.Add(unapproved[i]);
-                state.QueuedApprovalRequests.Add(unapproved[i]);
-            }
+            toRemove.Add(unapproved[i]);
+            state.QueuedApprovalRequests.Add(unapproved[i]);
         }
 
         // Walk messages in reverse and strip marked items.
@@ -663,8 +679,36 @@ public sealed class ToolApprovalAgent : DelegatingAIAgent
     }
 
     /// <summary>
-    /// Compares stored rule arguments against actual function call arguments for an exact match.
+    /// Checks whether a <see cref="ToolApprovalRequestContent"/> is approved by any of the configured
+    /// auto-approval rules (heuristic functions).
     /// </summary>
+    /// <returns>
+    /// <see langword="true"/> if any auto-approval rule returns <see langword="true"/> for the function call;
+    /// <see langword="false"/> if no rules are configured, the request is not a function call, or no rule approves it.
+    /// </returns>
+    private async ValueTask<bool> MatchesAutoApprovalRuleAsync(ToolApprovalRequestContent request)
+    {
+        if (this._autoApprovalRules is not { Length: > 0 })
+        {
+            return false;
+        }
+
+        if (request.ToolCall is not FunctionCallContent functionCall)
+        {
+            return false;
+        }
+
+        foreach (var rule in this._autoApprovalRules)
+        {
+            if (await rule(functionCall).ConfigureAwait(false))
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
     private static bool ArgumentsMatch(IDictionary<string, string> ruleArguments, IDictionary<string, object?>? callArguments, JsonSerializerOptions jsonSerializerOptions)
     {
         if (callArguments is null)

dotnet/src/Microsoft.Agents.AI/Harness/ToolApproval/ToolApprovalAgentBuilderExtensions.cs

@@ -1,7 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 using System.Diagnostics.CodeAnalysis;
-using System.Text.Json;
 using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 
@@ -17,9 +16,9 @@ public static class ToolApprovalAgentBuilderExtensions
     /// Adds tool approval middleware to the agent pipeline, enabling "don't ask again" approval behavior.
     /// </summary>
     /// <param name="builder">The <see cref="AIAgentBuilder"/> to which tool approval support will be added.</param>
-    /// <param name="jsonSerializerOptions">
-    /// Optional <see cref="JsonSerializerOptions"/> used for serializing argument values when storing rules
-    /// and for persisting state. When <see langword="null"/>, <see cref="AgentJsonUtilities.DefaultOptions"/> is used.
+    /// <param name="options">
+    /// Optional <see cref="ToolApprovalAgentOptions"/> for configuring serialization and auto-approval rules.
+    /// When <see langword="null"/>, default settings are used.
     /// </param>
     /// <returns>The <see cref="AIAgentBuilder"/> with tool approval middleware added, enabling method chaining.</returns>
     /// <exception cref="System.ArgumentNullException"><paramref name="builder"/> is <see langword="null"/>.</exception>
@@ -32,6 +31,6 @@ public static class ToolApprovalAgentBuilderExtensions
     /// </remarks>
     public static AIAgentBuilder UseToolApproval(
         this AIAgentBuilder builder,
-        JsonSerializerOptions? jsonSerializerOptions = null)
-        => Throw.IfNull(builder).Use(innerAgent => new ToolApprovalAgent(innerAgent, jsonSerializerOptions));
+        ToolApprovalAgentOptions? options = null)
+        => Throw.IfNull(builder).Use(innerAgent => new ToolApprovalAgent(innerAgent, options));
 }

dotnet/src/Microsoft.Agents.AI/Harness/ToolApproval/ToolApprovalAgentOptions.cs

@@ -0,0 +1,45 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Options for configuring the <see cref="ToolApprovalAgent"/> middleware.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public class ToolApprovalAgentOptions
+{
+    /// <summary>
+    /// Gets or sets the <see cref="System.Text.Json.JsonSerializerOptions"/> used for serializing argument values
+    /// when storing rules and for persisting state.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="null"/>, <see cref="AgentJsonUtilities.DefaultOptions"/> is used.
+    /// </remarks>
+    public JsonSerializerOptions? JsonSerializerOptions { get; set; }
+
+    /// <summary>
+    /// Gets or sets a collection of heuristic functions that can automatically approve function calls
+    /// that would otherwise require user approval.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Each function receives a <see cref="FunctionCallContent"/> representing the tool call that requires approval
+    /// and returns a <see cref="ValueTask{Boolean}"/> that resolves to <see langword="true"/> to auto-approve
+    /// the call, or <see langword="false"/> to continue evaluating the next rule.
+    /// </para>
+    /// <para>
+    /// Auto-approval rules are evaluated after standing rules (derived from prior user approvals) but before
+    /// prompting the user. Rules are evaluated in order; the first rule returning <see langword="true"/>
+    /// causes the function call to be auto-approved.
+    /// </para>
+    /// </remarks>
+    public IEnumerable<Func<FunctionCallContent, ValueTask<bool>>>? AutoApprovalRules { get; set; }
+}

dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkill.cs

@@ -49,14 +49,13 @@ public sealed class AgentFileSkill : AgentSkill
     /// <inheritdoc/>
     /// <remarks>
     /// Returns the raw SKILL.md content. When the skill has scripts, a
-    /// <c>&lt;scripts&gt;&lt;script name="..."&gt;&lt;parameters_schema&gt;...&lt;/parameters_schema&gt;&lt;/script&gt;&lt;/scripts&gt;</c>
-    /// block is appended with a per-script entry describing the expected argument format.
+    /// <c>&lt;script_schemas&gt;</c> block is appended describing the argument format.
     /// The result is cached after the first access.
     /// </remarks>
     public override ValueTask<string> GetContentAsync(CancellationToken cancellationToken = default)
     {
         var content = this._content ??= this._scripts is { Count: > 0 }
-            ? this._originalContent + AgentInlineSkillContentBuilder.BuildScriptsBlock(this._scripts)
+            ? this._originalContent + AgentInlineSkillContentBuilder.BuildScriptSchemasBlock(this._scripts)
             : this._originalContent;
         return new(content);
     }

dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentClassSkill.cs

@@ -114,7 +114,6 @@ public abstract class AgentClassSkill<
             this.Frontmatter.Name,
             this.Frontmatter.Description,
             this.Instructions,
-            this.Resources,
             this.Scripts));
     }
 
@@ -147,11 +146,17 @@ public abstract class AgentClassSkill<
     /// Gets the resources associated with this skill, or <see langword="null"/> if none.
     /// </summary>
     /// <remarks>
+    /// <para>
     /// The default implementation returns resources discovered via reflection by scanning
     /// <typeparamref name="TSelf"/> for members annotated with <see cref="AgentSkillResourceAttribute"/>.
     /// This discovery is compatible with Native AOT because <typeparamref name="TSelf"/> is annotated with
     /// <see cref="DynamicallyAccessedMembersAttribute"/>. The result is cached after the first access.
     /// Override this property in derived classes to provide skill-specific resources.
+    /// </para>
+    /// <para>
+    /// Resources are not automatically included in the skill body.
+    /// To enable discovery, reference resources by name in the skill's instructions or in other resources.
+    /// </para>
     /// </remarks>
     public virtual IReadOnlyList<AgentSkillResource>? Resources => this._resources.Value;
 
@@ -159,11 +164,17 @@ public abstract class AgentClassSkill<
     /// Gets the scripts associated with this skill, or <see langword="null"/> if none.
     /// </summary>
     /// <remarks>
+    /// <para>
     /// The default implementation returns scripts discovered via reflection by scanning
     /// <typeparamref name="TSelf"/> for methods annotated with <see cref="AgentSkillScriptAttribute"/>.
     /// This discovery is compatible with Native AOT because <typeparamref name="TSelf"/> is annotated with
     /// <see cref="DynamicallyAccessedMembersAttribute"/>. The result is cached after the first access.
     /// Override this property in derived classes to provide skill-specific scripts.
+    /// </para>
+    /// <para>
+    /// Only script parameter schemas are included in the skill body (as a <c>&lt;script_schemas&gt;</c> block).
+    /// To enable discovery, reference scripts by name in the skill's instructions or in a resource.
+    /// </para>
     /// </remarks>
     public virtual IReadOnlyList<AgentSkillScript>? Scripts => this._scripts.Value;
 
@@ -184,6 +195,10 @@ public abstract class AgentClassSkill<
     /// <summary>
     /// Creates a skill resource backed by a static value.
     /// </summary>
+    /// <remarks>
+    /// Resources are not automatically included in the skill body.
+    /// To enable discovery, reference the resource by name in the skill's instructions or in another resource.
+    /// </remarks>
     /// <param name="name">The resource name.</param>
     /// <param name="value">The static resource value.</param>
     /// <param name="description">An optional description of the resource.</param>
@@ -194,6 +209,10 @@ public abstract class AgentClassSkill<
     /// <summary>
     /// Creates a skill resource backed by a delegate that produces a dynamic value.
     /// </summary>
+    /// <remarks>
+    /// Resources are not automatically included in the skill body.
+    /// To enable discovery, reference the resource by name in the skill's instructions or in another resource.
+    /// </remarks>
     /// <param name="name">The resource name.</param>
     /// <param name="method">A method that produces the resource value when requested.</param>
     /// <param name="description">An optional description of the resource.</param>
@@ -208,6 +227,10 @@ public abstract class AgentClassSkill<
     /// <summary>
     /// Creates a skill script backed by a delegate.
     /// </summary>
+    /// <remarks>
+    /// Only the script's parameter schema is included in the skill body (as a <c>&lt;script_schemas&gt;</c> block).
+    /// To enable discovery, reference the script by name in the skill's instructions or in a resource.
+    /// </remarks>
     /// <param name="name">The script name.</param>
     /// <param name="method">A method to execute when the script is invoked.</param>
     /// <param name="description">An optional description of the script.</param>

dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkill.cs

@@ -95,7 +95,7 @@ public sealed class AgentInlineSkill : AgentSkill
     /// <inheritdoc/>
     public override ValueTask<string> GetContentAsync(CancellationToken cancellationToken = default)
     {
-        return new(this._cachedContent ??= AgentInlineSkillContentBuilder.Build(this.Frontmatter.Name, this.Frontmatter.Description, this._instructions, this._resources, this._scripts));
+        return new(this._cachedContent ??= AgentInlineSkillContentBuilder.Build(this.Frontmatter.Name, this.Frontmatter.Description, this._instructions, this._scripts));
     }
 
     /// <inheritdoc/>
@@ -115,6 +115,10 @@ public sealed class AgentInlineSkill : AgentSkill
     /// <summary>
     /// Registers a static resource with this skill.
     /// </summary>
+    /// <remarks>
+    /// Resources are not automatically included in the skill body.
+    /// To enable discovery, reference the resource by name in the skill's instructions or in another resource.
+    /// </remarks>
     /// <param name="name">The resource name.</param>
     /// <param name="value">The static resource value.</param>
     /// <param name="description">An optional description of the resource.</param>
@@ -129,6 +133,10 @@ public sealed class AgentInlineSkill : AgentSkill
     /// Registers a dynamic resource with this skill, backed by a C# delegate.
     /// The delegate's parameters and return type are automatically marshaled via <c>AIFunctionFactory</c>.
     /// </summary>
+    /// <remarks>
+    /// Resources are not automatically included in the skill body.
+    /// To enable discovery, reference the resource by name in the skill's instructions or in another resource.
+    /// </remarks>
     /// <param name="name">The resource name.</param>
     /// <param name="method">A method that produces the resource value when requested.</param>
     /// <param name="description">An optional description of the resource.</param>
@@ -147,6 +155,10 @@ public sealed class AgentInlineSkill : AgentSkill
     /// Registers a script with this skill, backed by a C# delegate.
     /// The delegate's parameters and return type are automatically marshaled via <c>AIFunctionFactory</c>.
     /// </summary>
+    /// <remarks>
+    /// Only the script's parameter schema is included in the skill body (as a <c>&lt;script_schemas&gt;</c> block).
+    /// To enable discovery, reference the script by name in the skill's instructions or in a resource.
+    /// </remarks>
     /// <param name="name">The script name.</param>
     /// <param name="method">A method to execute when the script is invoked.</param>
     /// <param name="description">An optional description of the script.</param>

dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkillContentBuilder.cs

@@ -12,19 +12,17 @@ namespace Microsoft.Agents.AI;
 internal static class AgentInlineSkillContentBuilder
 {
     /// <summary>
-    /// Builds the complete skill content containing name, description, instructions, resources, and scripts.
+    /// Builds the complete skill content containing name, description, instructions, and script parameter schemas.
     /// </summary>
     /// <param name="name">The skill name.</param>
     /// <param name="description">The skill description.</param>
     /// <param name="instructions">The raw instructions text.</param>
-    /// <param name="resources">Optional resources associated with the skill.</param>
     /// <param name="scripts">Optional scripts associated with the skill.</param>
     /// <returns>An XML-structured content string.</returns>
     public static string Build(
         string name,
         string description,
         string instructions,
-        IReadOnlyList<AgentSkillResource>? resources,
         IReadOnlyList<AgentSkillScript>? scripts)
     {
         _ = Throw.IfNullOrWhitespace(name);
@@ -39,41 +37,24 @@ internal static class AgentInlineSkillContentBuilder
         .Append(EscapeXmlString(instructions))
         .Append("\n</instructions>");
 
-        if (resources is { Count: > 0 })
-        {
-            sb.Append("\n\n<resources>\n");
-            foreach (var resource in resources)
-            {
-                if (resource.Description is not null)
-                {
-                    sb.Append($"  <resource name=\"{EscapeXmlString(resource.Name)}\" description=\"{EscapeXmlString(resource.Description)}\"/>\n");
-                }
-                else
-                {
-                    sb.Append($"  <resource name=\"{EscapeXmlString(resource.Name)}\"/>\n");
-                }
-            }
-
-            sb.Append("</resources>");
-        }
-
         if (scripts is { Count: > 0 })
         {
             sb.Append('\n');
-            sb.Append(BuildScriptsBlock(scripts));
+            sb.Append(BuildScriptSchemasBlock(scripts));
         }
 
         return sb.ToString();
     }
 
     /// <summary>
-    /// Builds a <c>&lt;scripts&gt;...&lt;/scripts&gt;</c> XML block for the given scripts.
-    /// Each script is emitted as a <c>&lt;script name="..."&gt;</c> element with optional
-    /// <c>description</c> attribute and <c>&lt;parameters_schema&gt;</c> child element.
+    /// Builds a <c>&lt;script_schemas&gt;...&lt;/script_schemas&gt;</c> XML block for the given scripts.
+    /// Each script is emitted as a <c>&lt;schema script="..."&gt;</c> element containing only
+    /// the parameter schema. This block serves as a reference for the model to know how to
+    /// format arguments when calling scripts, not as a discovery mechanism.
     /// </summary>
     /// <param name="scripts">The scripts to include in the block.</param>
-    /// <returns>An XML string starting with <c>\n&lt;scripts&gt;</c>, or an empty string if the list is empty.</returns>
-    public static string BuildScriptsBlock(IReadOnlyList<AgentSkillScript> scripts)
+    /// <returns>An XML string starting with <c>\n&lt;script_schemas&gt;</c>, or an empty string if the list is empty.</returns>
+    public static string BuildScriptSchemasBlock(IReadOnlyList<AgentSkillScript> scripts)
     {
         _ = Throw.IfNull(scripts);
 
@@ -83,32 +64,23 @@ internal static class AgentInlineSkillContentBuilder
         }
 
         var sb = new StringBuilder();
-        sb.Append("\n<scripts>\n");
+        sb.Append("\n<script_schemas>\n");
 
         foreach (var script in scripts)
         {
             var parametersSchema = script.ParametersSchema;
 
-            if (script.Description is null && parametersSchema is null)
+            if (parametersSchema is null)
             {
-                sb.Append($"  <script name=\"{EscapeXmlString(script.Name)}\"/>\n");
+                sb.Append($"  <schema script=\"{EscapeXmlString(script.Name)}\"/>\n");
             }
             else
             {
-                sb.Append(script.Description is not null
-                    ? $"  <script name=\"{EscapeXmlString(script.Name)}\" description=\"{EscapeXmlString(script.Description)}\">\n"
-                    : $"  <script name=\"{EscapeXmlString(script.Name)}\">\n");
-
-                if (parametersSchema is not null)
-                {
-                    sb.Append($"    <parameters_schema>{EscapeXmlString(parametersSchema.Value.GetRawText(), preserveQuotes: true)}</parameters_schema>\n");
-                }
-
-                sb.Append("  </script>\n");
+                sb.Append($"  <schema script=\"{EscapeXmlString(script.Name)}\">{EscapeXmlString(parametersSchema.Value.GetRawText(), preserveQuotes: true)}</schema>\n");
             }
         }
 
-        sb.Append("</scripts>");
+        sb.Append("</script_schemas>");
 
         return sb.ToString();
     }

dotnet/tests/Microsoft.Agents.AI.Harness.UnitTests/HarnessAgentTests.cs

@@ -9,6 +9,7 @@ using System.Threading.Tasks;
 using Microsoft.Agents.AI.Tools.Shell;
 #endif
 using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Logging;
 using Moq;
 
 namespace Microsoft.Agents.AI.UnitTests;
@@ -643,6 +644,51 @@ public class HarnessAgentTests
         Assert.Null(agent.GetService<ToolApprovalAgent>());
     }
 
+    /// <summary>
+    /// Verify that ToolApprovalAgentOptions auto-approval rules are passed through and actually used.
+    /// </summary>
+    [Fact]
+    public async Task ToolApproval_AutoApprovalRulesAreAppliedAsync()
+    {
+        // Arrange — inner client returns an approval request on first call, then final response on second.
+        var callCount = 0;
+        var approvalRequest = new ToolApprovalRequestContent("req1", new FunctionCallContent("call1", "ReadTool"));
+
+        var mockClient = new Mock<IChatClient>();
+        mockClient
+            .Setup(c => c.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>()))
+            .ReturnsAsync(() =>
+            {
+                callCount++;
+                if (callCount == 1)
+                {
+                    return new ChatResponse(new ChatMessage(ChatRole.Assistant, [approvalRequest]));
+                }
+
+                return new ChatResponse(new ChatMessage(ChatRole.Assistant, "Done"));
+            });
+
+        var options = CreateAllDisabledOptions();
+        options.DisableToolApproval = false;
+        options.ToolApprovalAgentOptions = new ToolApprovalAgentOptions
+        {
+            AutoApprovalRules = [fcc => new ValueTask<bool>(fcc.Name == "ReadTool")]
+        };
+
+        var agent = new HarnessAgent(mockClient.Object, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var session = await agent.CreateSessionAsync();
+
+        // Act
+        var response = await agent.RunAsync([new ChatMessage(ChatRole.User, "Hi")], session);
+
+        // Assert — the auto-approval rule approved the request, so we get "Done" (not an approval request)
+        Assert.Equal(2, callCount);
+        Assert.Equal("Done", response.Text);
+    }
+
     #endregion
 
     #region Feature: OpenTelemetry
@@ -1460,4 +1506,131 @@ public class HarnessAgentTests
 
     #endregion
 #endif
+
+    #region LoggerFactory and ServiceProvider
+
+    /// <summary>
+    /// Verify that the constructor succeeds when loggerFactory is provided.
+    /// </summary>
+    [Fact]
+    public void Constructor_SucceedsWithLoggerFactory()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var loggerFactory = new Mock<ILoggerFactory>().Object;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions(), loggerFactory);
+
+        // Assert
+        Assert.NotNull(agent);
+    }
+
+    /// <summary>
+    /// Verify that the constructor succeeds when serviceProvider is provided.
+    /// </summary>
+    [Fact]
+    public void Constructor_SucceedsWithServiceProvider()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var services = new Mock<IServiceProvider>().Object;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions(), services: services);
+
+        // Assert
+        Assert.NotNull(agent);
+    }
+
+    /// <summary>
+    /// Verify that the constructor succeeds when both loggerFactory and serviceProvider are provided.
+    /// </summary>
+    [Fact]
+    public void Constructor_SucceedsWithLoggerFactoryAndServiceProvider()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var loggerFactory = new Mock<ILoggerFactory>().Object;
+        var services = new Mock<IServiceProvider>().Object;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions(), loggerFactory, services);
+
+        // Assert
+        Assert.NotNull(agent);
+    }
+
+    /// <summary>
+    /// Verify that AsHarnessAgent extension method accepts loggerFactory and serviceProvider.
+    /// </summary>
+    [Fact]
+    public void AsHarnessAgent_SucceedsWithLoggerFactoryAndServiceProvider()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var loggerFactory = new Mock<ILoggerFactory>().Object;
+        var services = new Mock<IServiceProvider>().Object;
+
+        // Act
+        var agent = chatClient.AsHarnessAgent(TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions(), loggerFactory, services);
+
+        // Assert
+        Assert.NotNull(agent);
+    }
+
+    /// <summary>
+    /// Verify that ILoggerFactory is threaded to downstream components by confirming CreateLogger is called.
+    /// </summary>
+    [Fact]
+    public void Constructor_LoggerFactoryIsUsedByDownstreamComponents()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var mockLoggerFactory = new Mock<ILoggerFactory>();
+        mockLoggerFactory
+            .Setup(lf => lf.CreateLogger(It.IsAny<string>()))
+            .Returns(new Mock<ILogger>().Object);
+
+        // Act — use options that leave CompactionProvider and AgentSkillsProvider enabled
+        var options = new HarnessAgentOptions
+        {
+            DisableToolApproval = true,
+            DisableOpenTelemetry = true,
+            DisableFileMemory = true,
+            DisableFileAccess = true,
+            DisableWebSearch = true,
+            DisableTodoProvider = true,
+            DisableAgentModeProvider = true,
+        };
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options, mockLoggerFactory.Object);
+
+        // Assert — CreateLogger should have been called by one or more downstream components
+        Assert.NotNull(agent);
+        mockLoggerFactory.Verify(lf => lf.CreateLogger(It.IsAny<string>()), Times.AtLeastOnce());
+    }
+
+    /// <summary>
+    /// Verify that IServiceProvider is propagated through the agent pipeline by confirming
+    /// it is queried during agent construction.
+    /// </summary>
+    [Fact]
+    public void Constructor_ServiceProviderIsQueriedDuringBuild()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var mockServices = new Mock<IServiceProvider>();
+        mockServices
+            .Setup(sp => sp.GetService(It.IsAny<Type>()))
+            .Returns(null!);
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions(), services: mockServices.Object);
+
+        // Assert — the service provider should have been queried during pipeline construction
+        Assert.NotNull(agent);
+        mockServices.Verify(sp => sp.GetService(It.IsAny<Type>()), Times.AtLeastOnce());
+    }
+
+    #endregion
 }

dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/AgentClassSkillTests.cs

@@ -51,9 +51,8 @@ public sealed class AgentClassSkillTests
         // Act & Assert — Content is cached
         Assert.Same(await skill.GetContentAsync(), await skill.GetContentAsync());
 
-        // Act & Assert — Content includes parameter schema from typed script
-        Assert.Contains("parameters_schema", await skill.GetContentAsync());
-        Assert.Contains("value", await skill.GetContentAsync());
+        // Act & Assert — Content includes parameter schema from typed script (with preserved quotes)
+        Assert.Contains("\"value\"", await skill.GetContentAsync());
     }
 
     [Fact]
@@ -383,10 +382,9 @@ public sealed class AgentClassSkillTests
         // Arrange
         var skill = new AttributedFullSkill();
 
-        // Act & Assert — Content includes reflected resources and scripts
-        Assert.Contains("<resources>", await skill.GetContentAsync());
-        Assert.Contains("conversion-table", await skill.GetContentAsync());
-        Assert.Contains("<scripts>", await skill.GetContentAsync());
+        // Act & Assert — Content no longer includes resources in body; scripts are in script_schemas
+        Assert.DoesNotContain("<resources>", await skill.GetContentAsync());
+        Assert.Contains("<script_schemas>", await skill.GetContentAsync());
         Assert.Contains("convert", await skill.GetContentAsync());
 
         // Act & Assert — discovered members are cached
@@ -504,7 +502,7 @@ public sealed class AgentClassSkillTests
     }
 
     [Fact]
-    public async Task Content_IncludesDescription_ForReflectedResourcesAsync()
+    public async Task Content_DoesNotRenderResources_InBodyAsync()
     {
         // Arrange
         var skill = new AttributedResourcePropertiesSkill();
@@ -512,8 +510,8 @@ public sealed class AgentClassSkillTests
         // Act
         var content = await skill.GetContentAsync();
 
-        // Assert — descriptions from [Description] attribute appear in synthesized content
-        Assert.Contains("Some important data.", content);
+        // Assert — resources are no longer rendered in body content
+        Assert.DoesNotContain("<resources>", content);
     }
 
     [Fact]

dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/AgentFileSkillScriptTests.cs

@@ -122,11 +122,10 @@ public sealed class AgentFileSkillScriptTests
 
         // Assert — content starts with original and appends per-script entries
         Assert.StartsWith("Original content", content);
-        Assert.Contains("<scripts>", content);
-        Assert.Contains("<script name=\"build\">", content);
-        Assert.Contains("<script name=\"deploy\">", content);
-        Assert.Contains("<parameters_schema>", content);
-        Assert.Contains("</scripts>", content);
+        Assert.Contains("<script_schemas>", content);
+        Assert.Contains("<schema script=\"build\">", content);
+        Assert.Contains("<schema script=\"deploy\">", content);
+        Assert.Contains("</script_schemas>", content);
     }
 
     [Fact]

dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/AgentInlineSkillTests.cs

@@ -149,7 +149,7 @@ public sealed class AgentInlineSkillTests
     }
 
     [Fact]
-    public async Task Content_IncludesResourcesAddedBeforeFirstAccessAsync()
+    public async Task Content_DoesNotIncludeResourcesInBodyAsync()
     {
         // Arrange
         var skill = new AgentInlineSkill("my-skill", "A valid skill.", "Instructions.");
@@ -158,13 +158,12 @@ public sealed class AgentInlineSkillTests
         // Act
         var content = await skill.GetContentAsync();
 
-        // Assert
-        Assert.Contains("<resources>", content);
-        Assert.Contains("config", content);
+        // Assert — resources are no longer rendered in the body; they're accessed via GetResourceAsync
+        Assert.DoesNotContain("<resources>", content);
     }
 
     [Fact]
-    public async Task Content_IncludesDelegateResourcesAddedBeforeFirstAccessAsync()
+    public async Task Content_DoesNotIncludeDelegateResourcesInBodyAsync()
     {
         // Arrange
         var skill = new AgentInlineSkill("my-skill", "A valid skill.", "Instructions.");
@@ -173,9 +172,8 @@ public sealed class AgentInlineSkillTests
         // Act
         var content = await skill.GetContentAsync();
 
-        // Assert
-        Assert.Contains("<resources>", content);
-        Assert.Contains("dynamic", content);
+        // Assert — resources are no longer rendered in the body
+        Assert.DoesNotContain("<resources>", content);
     }
 
     [Fact]
@@ -189,7 +187,7 @@ public sealed class AgentInlineSkillTests
         var content = await skill.GetContentAsync();
 
         // Assert
-        Assert.Contains("<scripts>", content);
+        Assert.Contains("<script_schemas>", content);
         Assert.Contains("run", content);
     }
 
@@ -209,7 +207,7 @@ public sealed class AgentInlineSkillTests
     }
 
     [Fact]
-    public async Task Content_IncludesResourcesAndScriptsAddedBeforeFirstAccessAsync()
+    public async Task Content_IncludesScriptSchemasAddedBeforeFirstAccessAsync()
     {
         // Arrange
         var skill = new AgentInlineSkill("my-skill", "A valid skill.", "Instructions.");
@@ -220,9 +218,8 @@ public sealed class AgentInlineSkillTests
         var content = await skill.GetContentAsync();
 
         // Assert
-        Assert.Contains("<resources>", content);
-        Assert.Contains("r1", content);
-        Assert.Contains("<scripts>", content);
+        Assert.DoesNotContain("<resources>", content);
+        Assert.Contains("<script_schemas>", content);
         Assert.Contains("s1", content);
     }
 
@@ -236,8 +233,9 @@ public sealed class AgentInlineSkillTests
         // Act
         var content = await skill.GetContentAsync();
 
-        // Assert — JSON schema should be present and XML content chars escaped
-        Assert.Contains("parameters_schema", content);
+        // Assert — JSON schema should be present inside <schema> element (no extra wrapper) with preserved quotes
+        Assert.Contains("<schema script=\"search\">", content);
+        Assert.Contains("\"query\"", content);
         Assert.DoesNotContain("<![CDATA[", content);
     }
 
@@ -429,7 +427,7 @@ public sealed class AgentInlineSkillTests
 
         // Assert
         Assert.DoesNotContain("<resources>", content);
-        Assert.DoesNotContain("<scripts>", content);
+        Assert.DoesNotContain("<script_schemas>", content);
     }
 
     [Fact]
@@ -463,7 +461,7 @@ public sealed class AgentInlineSkillTests
     }
 
     [Fact]
-    public async Task Content_ScriptWithDescription_IncludesDescriptionAttributeAsync()
+    public async Task Content_ScriptWithDescription_DoesNotEmitDescriptionAttributeAsync()
     {
         // Arrange
         var skill = new AgentInlineSkill("my-skill", "A valid skill.", "Instructions.");
@@ -472,8 +470,10 @@ public sealed class AgentInlineSkillTests
         // Act
         var content = await skill.GetContentAsync();
 
-        // Assert
-        Assert.Contains("description=\"Runs something.\"", content);
+        // Assert — description is no longer emitted in the script_schemas block;
+        // the block only contains parameter schemas for calling scripts.
+        Assert.Contains("<schema script=\"my-script\"", content);
+        Assert.DoesNotContain("description=\"Runs something.\"", content);
     }
 
     [Fact]
@@ -492,7 +492,7 @@ public sealed class AgentInlineSkillTests
     }
 
     [Fact]
-    public async Task Content_ResourceWithDescription_IncludesDescriptionAttributeAsync()
+    public async Task Content_ResourceWithDescription_NotRenderedInBodyAsync()
     {
         // Arrange
         var skill = new AgentInlineSkill("my-skill", "A valid skill.", "Instructions.");
@@ -502,9 +502,10 @@ public sealed class AgentInlineSkillTests
         // Act
         var content = await skill.GetContentAsync();
 
-        // Assert
-        Assert.Contains("description=\"A described resource.\"", content);
-        Assert.DoesNotContain("no-desc\" description", content);
+        // Assert — resources are no longer rendered in the body
+        Assert.DoesNotContain("<resources>", content);
+        Assert.DoesNotContain("with-desc", content);
+        Assert.DoesNotContain("no-desc", content);
     }
 
     [Fact]

dotnet/tests/Microsoft.Agents.AI.UnitTests/ChatClient/ChatClientAgentOptionsTests.cs

@@ -134,6 +134,7 @@ public class ChatClientAgentOptionsTests
             ClearOnChatHistoryProviderConflict = false,
             WarnOnChatHistoryProviderConflict = false,
             ThrowOnChatHistoryProviderConflict = false,
+            EnableNonApprovalRequiredFunctionBypassing = true,
         };
 
         // Act
@@ -150,6 +151,7 @@ public class ChatClientAgentOptionsTests
         Assert.Equal(original.ClearOnChatHistoryProviderConflict, clone.ClearOnChatHistoryProviderConflict);
         Assert.Equal(original.WarnOnChatHistoryProviderConflict, clone.WarnOnChatHistoryProviderConflict);
         Assert.Equal(original.ThrowOnChatHistoryProviderConflict, clone.ThrowOnChatHistoryProviderConflict);
+        Assert.Equal(original.EnableNonApprovalRequiredFunctionBypassing, clone.EnableNonApprovalRequiredFunctionBypassing);
 
         // ChatOptions should be cloned, not the same reference
         Assert.NotSame(original.ChatOptions, clone.ChatOptions);

dotnet/tests/Microsoft.Agents.AI.UnitTests/ChatClient/NonApprovalRequiredFunctionBypassingChatClientTests.cs

@@ -0,0 +1,574 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Moq;
+
+namespace Microsoft.Agents.AI.UnitTests;
+
+public class NonApprovalRequiredFunctionBypassingChatClientTests
+{
+    #region GetResponseAsync Tests
+
+    [Fact]
+    public async Task GetResponseAsync_NoApprovalContent_PassesThroughUnchangedAsync()
+    {
+        // Arrange
+        var innerClient = CreateMockChatClient((_, _, _) =>
+            Task.FromResult(new ChatResponse([new ChatMessage(ChatRole.Assistant, "Hello")])));
+
+        var decorator = new NonApprovalRequiredFunctionBypassingChatClient(innerClient);
+        var session = new ChatClientAgentSession();
+
+        // Act
+        var response = await RunWithAgentContextAsync(decorator, session);
+
+        // Assert
+        Assert.Single(response.Messages);
+        Assert.Equal("Hello", response.Messages[0].Text);
+        Assert.Equal(0, session.StateBag.Count);
+    }
+
+    [Fact]
+    public async Task GetResponseAsync_AllToolsRequireApproval_PassesThroughUnchangedAsync()
+    {
+        // Arrange
+        var approvalTool = new ApprovalRequiredAIFunction(AIFunctionFactory.Create(() => "result", "approvalTool"));
+        var fcc = new FunctionCallContent("call1", "approvalTool");
+        var approval = new ToolApprovalRequestContent("req1", fcc);
+
+        var innerClient = CreateMockChatClient((_, _, _) =>
+            Task.FromResult(new ChatResponse([new ChatMessage(ChatRole.Assistant, [approval])])));
+
+        var decorator = new NonApprovalRequiredFunctionBypassingChatClient(innerClient);
+        var session = new ChatClientAgentSession();
+        var options = new ChatOptions { Tools = [approvalTool] };
+
+        // Act
+        var response = await RunWithAgentContextAsync(decorator, session, options);
+
+        // Assert — approval request should remain
+        Assert.Single(response.Messages);
+        var contents = response.Messages[0].Contents;
+        Assert.Single(contents);
+        Assert.IsType<ToolApprovalRequestContent>(contents[0]);
+        Assert.Equal(0, session.StateBag.Count);
+    }
+
+    [Fact]
+    public async Task GetResponseAsync_MixedApproval_RemovesNonApprovalItemsAsync()
+    {
+        // Arrange
+        var normalTool = AIFunctionFactory.Create(() => "result", "normalTool");
+        var approvalTool = new ApprovalRequiredAIFunction(AIFunctionFactory.Create(() => "result", "approvalTool"));
+
+        var fccNormal = new FunctionCallContent("call1", "normalTool");
+        var fccApproval = new FunctionCallContent("call2", "approvalTool");
+        var approvalNormal = new ToolApprovalRequestContent("req1", fccNormal);
+        var approvalRequired = new ToolApprovalRequestContent("req2", fccApproval);
+
+        var innerClient = CreateMockChatClient((_, _, _) =>
+            Task.FromResult(new ChatResponse([
+                new ChatMessage(ChatRole.Assistant, [approvalNormal, approvalRequired])
+            ])));
+
+        var decorator = new NonApprovalRequiredFunctionBypassingChatClient(innerClient);
+        var session = new ChatClientAgentSession();
+        var options = new ChatOptions { Tools = [normalTool, approvalTool] };
+
+        // Act
+        var response = await RunWithAgentContextAsync(decorator, session, options);
+
+        // Assert — only the approval-required item remains in the response
+        Assert.Single(response.Messages);
+        var contents = response.Messages[0].Contents;
+        Assert.Single(contents);
+        var remainingApproval = Assert.IsType<ToolApprovalRequestContent>(contents[0]);
+        Assert.Equal("req2", remainingApproval.RequestId);
+    }
+
+    [Fact]
+    public async Task GetResponseAsync_MixedApproval_StoresAutoApprovedInSessionAsync()
+    {
+        // Arrange
+        var normalTool = AIFunctionFactory.Create(() => "result", "normalTool");
+        var approvalTool = new ApprovalRequiredAIFunction(AIFunctionFactory.Create(() => "result", "approvalTool"));
+
+        var fccNormal = new FunctionCallContent("call1", "normalTool");
+        var fccApproval = new FunctionCallContent("call2", "approvalTool");
+        var approvalNormal = new ToolApprovalRequestContent("req1", fccNormal);
+        var approvalRequired = new ToolApprovalRequestContent("req2", fccApproval);
+
+        var innerClient = CreateMockChatClient((_, _, _) =>
+            Task.FromResult(new ChatResponse([
+                new ChatMessage(ChatRole.Assistant, [approvalNormal, approvalRequired])
+            ])));
+
+        var decorator = new NonApprovalRequiredFunctionBypassingChatClient(innerClient);
+        var session = new ChatClientAgentSession();
+        var options = new ChatOptions { Tools = [normalTool, approvalTool] };
+
+        // Act
+        await RunWithAgentContextAsync(decorator, session, options);
+
+        // Assert — the auto-approved item should be stored in the session
+        Assert.True(session.StateBag.TryGetValue<List<ToolApprovalRequestContent>>(
+            NonApprovalRequiredFunctionBypassingChatClient.StateBagKey, out var stored, AgentJsonUtilities.DefaultOptions));
+        Assert.NotNull(stored);
+        Assert.Single(stored!);
+        Assert.Equal("req1", stored![0].RequestId);
+    }
+
+    [Fact]
+    public async Task GetResponseAsync_AllNonApproval_RemovesAllApprovalsAndRemovesEmptyMessageAsync()
+    {
+        // Arrange
+        var normalTool = AIFunctionFactory.Create(() => "result", "normalTool");
+
+        var fccNormal = new FunctionCallContent("call1", "normalTool");
+        var approvalNormal = new ToolApprovalRequestContent("req1", fccNormal);
+
+        var innerClient = CreateMockChatClient((_, _, _) =>
+            Task.FromResult(new ChatResponse([
+                new ChatMessage(ChatRole.Assistant, [approvalNormal])
+            ])));
+
+        var decorator = new NonApprovalRequiredFunctionBypassingChatClient(innerClient);
+        var session = new ChatClientAgentSession();
+        var options = new ChatOptions { Tools = [normalTool] };
+
+        // Act
+        var response = await RunWithAgentContextAsync(decorator, session, options);
+
+        // Assert — the message should be removed since it's now empty
+        Assert.Empty(response.Messages);
+    }
+
+    [Fact]
+    public async Task GetResponseAsync_NextRequest_InjectsStoredAutoApprovalsAsync()
+    {
+        // Arrange
+        var fccNormal = new FunctionCallContent("call1", "normalTool");
+        var storedApproval = new ToolApprovalRequestContent("req1", fccNormal);
+
+        var session = new ChatClientAgentSession();
+        session.StateBag.SetValue(
+            NonApprovalRequiredFunctionBypassingChatClient.StateBagKey,
+            new List<ToolApprovalRequestContent> { storedApproval },
+            AgentJsonUtilities.DefaultOptions);
+
+        IEnumerable<ChatMessage>? capturedMessages = null;
+        var innerClient = CreateMockChatClient((messages, _, _) =>
+        {
+            capturedMessages = messages.ToList();
+            return Task.FromResult(new ChatResponse([new ChatMessage(ChatRole.Assistant, "Done")]));
+        });
+
+        var decorator = new NonApprovalRequiredFunctionBypassingChatClient(innerClient);
+        var options = new ChatOptions { Tools = [AIFunctionFactory.Create(() => "result", "normalTool")] };
+
+        // Act
+        await RunWithAgentContextAsync(decorator, session, options);
+
+        // Assert — the inner client should receive injected messages
+        Assert.NotNull(capturedMessages);
+        var messagesList = capturedMessages!.ToList();
+
+        // Original user message + user message with approved responses.
+        Assert.Equal(2, messagesList.Count);
+        Assert.Equal(ChatRole.User, messagesList[0].Role);
+
+        // User message with the auto-approved ToolApprovalResponseContent
+        Assert.Equal(ChatRole.User, messagesList[1].Role);
+        var userContent = messagesList[1].Contents.OfType<ToolApprovalResponseContent>().ToList();
+        Assert.Single(userContent);
+        Assert.Equal("req1", userContent[0].RequestId);
+        Assert.True(userContent[0].Approved);
+    }
+
+    [Fact]
+    public async Task GetResponseAsync_NextRequest_ClearsStoredAfterInjectionAsync()
+    {
+        // Arrange
+        var fccNormal = new FunctionCallContent("call1", "normalTool");
+        var storedApproval = new ToolApprovalRequestContent("req1", fccNormal);
+
+        var session = new ChatClientAgentSession();
+        session.StateBag.SetValue(
+            NonApprovalRequiredFunctionBypassingChatClient.StateBagKey,
+            new List<ToolApprovalRequestContent> { storedApproval },
+            AgentJsonUtilities.DefaultOptions);
+
+        var innerClient = CreateMockChatClient((_, _, _) =>
+            Task.FromResult(new ChatResponse([new ChatMessage(ChatRole.Assistant, "Done")])));
+
+        var decorator = new NonApprovalRequiredFunctionBypassingChatClient(innerClient);
+        var options = new ChatOptions { Tools = [AIFunctionFactory.Create(() => "result", "normalTool")] };
+
+        // Act
+        await RunWithAgentContextAsync(decorator, session, options);
+
+        // Assert — the stored data should be cleared after successful injection
+        Assert.False(session.StateBag.TryGetValue<List<ToolApprovalRequestContent>>(
+            NonApprovalRequiredFunctionBypassingChatClient.StateBagKey, out _, AgentJsonUtilities.DefaultOptions));
+    }
+
+    [Fact]
+    public async Task GetResponseAsync_UnknownTool_TreatedAsApprovalRequiredAsync()
+    {
+        // Arrange — tool is not in ChatOptions.Tools
+        var fccUnknown = new FunctionCallContent("call1", "unknownTool");
+        var approvalUnknown = new ToolApprovalRequestContent("req1", fccUnknown);
+
+        var innerClient = CreateMockChatClient((_, _, _) =>
+            Task.FromResult(new ChatResponse([
+                new ChatMessage(ChatRole.Assistant, [approvalUnknown])
+            ])));
+
+        var decorator = new NonApprovalRequiredFunctionBypassingChatClient(innerClient);
+        var session = new ChatClientAgentSession();
+        var options = new ChatOptions { Tools = [] };
+
+        // Act
+        var response = await RunWithAgentContextAsync(decorator, session, options);
+
+        // Assert — unknown tool should NOT be auto-approved
+        Assert.Single(response.Messages);
+        Assert.Single(response.Messages[0].Contents);
+        Assert.IsType<ToolApprovalRequestContent>(response.Messages[0].Contents[0]);
+        Assert.Equal(0, session.StateBag.Count);
+    }
+
+    [Fact]
+    public async Task GetResponseAsync_StoredRequestToolSetChanged_StillInjectsAsApprovedAsync()
+    {
+        // Arrange — tool was previously non-approval-required but is now wrapped in ApprovalRequiredAIFunction.
+        // The LLM still requires a complete set of responses, so we inject unconditionally.
+        var fccTool = new FunctionCallContent("call1", "changingTool");
+        var storedApproval = new ToolApprovalRequestContent("req1", fccTool);
+
+        var session = new ChatClientAgentSession();
+        session.StateBag.SetValue(
+            NonApprovalRequiredFunctionBypassingChatClient.StateBagKey,
+            new List<ToolApprovalRequestContent> { storedApproval },
+            AgentJsonUtilities.DefaultOptions);
+
+        IEnumerable<ChatMessage>? capturedMessages = null;
+        var innerClient = CreateMockChatClient((messages, _, _) =>
+        {
+            capturedMessages = messages.ToList();
+            return Task.FromResult(new ChatResponse([new ChatMessage(ChatRole.Assistant, "Done")]));
+        });
+
+        var decorator = new NonApprovalRequiredFunctionBypassingChatClient(innerClient);
+
+        // The tool is now wrapped in ApprovalRequiredAIFunction — but we still inject unconditionally
+        var approvalTool = new ApprovalRequiredAIFunction(AIFunctionFactory.Create(() => "result", "changingTool"));
+        var options = new ChatOptions { Tools = [approvalTool] };
+
+        // Act
+        await RunWithAgentContextAsync(decorator, session, options);
+
+        // Assert — the stored request should still be injected as approved
+        Assert.NotNull(capturedMessages);
+        var messagesList = capturedMessages!.ToList();
+        Assert.Equal(2, messagesList.Count);
+        var userContent = messagesList[1].Contents.OfType<ToolApprovalResponseContent>().ToList();
+        Assert.Single(userContent);
+        Assert.Equal("req1", userContent[0].RequestId);
+        Assert.True(userContent[0].Approved);
+
+        // Session should be cleared
+        Assert.False(session.StateBag.TryGetValue<List<ToolApprovalRequestContent>>(
+            NonApprovalRequiredFunctionBypassingChatClient.StateBagKey, out _, AgentJsonUtilities.DefaultOptions));
+    }
+
+    #endregion
+
+    #region GetStreamingResponseAsync Tests
+
+    [Fact]
+    public async Task GetStreamingResponseAsync_NoApprovalContent_PassesThroughUnchangedAsync()
+    {
+        // Arrange
+        var innerClient = CreateMockStreamingChatClient((_, _, _) =>
+            ToAsyncEnumerableAsync(
+                new ChatResponseUpdate(ChatRole.Assistant, "Hello")));
+
+        var decorator = new NonApprovalRequiredFunctionBypassingChatClient(innerClient);
+        var session = new ChatClientAgentSession();
+
+        // Act
+        var updates = new List<ChatResponseUpdate>();
+        await RunStreamingWithAgentContextAsync(decorator, session, updates);
+
+        // Assert
+        Assert.Single(updates);
+        Assert.Equal("Hello", updates[0].Text);
+        Assert.Equal(0, session.StateBag.Count);
+    }
+
+    [Fact]
+    public async Task GetStreamingResponseAsync_MixedApproval_FiltersNonApprovalItemsAsync()
+    {
+        // Arrange
+        var normalTool = AIFunctionFactory.Create(() => "result", "normalTool");
+        var approvalTool = new ApprovalRequiredAIFunction(AIFunctionFactory.Create(() => "result", "approvalTool"));
+
+        var fccNormal = new FunctionCallContent("call1", "normalTool");
+        var fccApproval = new FunctionCallContent("call2", "approvalTool");
+        var approvalNormal = new ToolApprovalRequestContent("req1", fccNormal);
+        var approvalRequired = new ToolApprovalRequestContent("req2", fccApproval);
+
+        var innerClient = CreateMockStreamingChatClient((_, _, _) =>
+            ToAsyncEnumerableAsync(
+                new ChatResponseUpdate(ChatRole.Assistant, "text"),
+                new ChatResponseUpdate { Contents = [approvalNormal, approvalRequired] }));
+
+        var decorator = new NonApprovalRequiredFunctionBypassingChatClient(innerClient);
+        var session = new ChatClientAgentSession();
+        var options = new ChatOptions { Tools = [normalTool, approvalTool] };
+
+        // Act
+        var updates = new List<ChatResponseUpdate>();
+        await RunStreamingWithAgentContextAsync(decorator, session, updates, options);
+
+        // Assert — text update + filtered approval update
+        Assert.Equal(2, updates.Count);
+        Assert.Equal("text", updates[0].Text);
+
+        // Second update should only have the approval-required item
+        var approvalContents = updates[1].Contents.OfType<ToolApprovalRequestContent>().ToList();
+        Assert.Single(approvalContents);
+        Assert.Equal("req2", approvalContents[0].RequestId);
+    }
+
+    [Fact]
+    public async Task GetStreamingResponseAsync_MixedApproval_StoresAutoApprovedInSessionAsync()
+    {
+        // Arrange
+        var normalTool = AIFunctionFactory.Create(() => "result", "normalTool");
+        var approvalTool = new ApprovalRequiredAIFunction(AIFunctionFactory.Create(() => "result", "approvalTool"));
+
+        var fccNormal = new FunctionCallContent("call1", "normalTool");
+        var fccApproval = new FunctionCallContent("call2", "approvalTool");
+        var approvalNormal = new ToolApprovalRequestContent("req1", fccNormal);
+        var approvalRequired = new ToolApprovalRequestContent("req2", fccApproval);
+
+        var innerClient = CreateMockStreamingChatClient((_, _, _) =>
+            ToAsyncEnumerableAsync(
+                new ChatResponseUpdate { Contents = [approvalNormal, approvalRequired] }));
+
+        var decorator = new NonApprovalRequiredFunctionBypassingChatClient(innerClient);
+        var session = new ChatClientAgentSession();
+        var options = new ChatOptions { Tools = [normalTool, approvalTool] };
+
+        // Act
+        var updates = new List<ChatResponseUpdate>();
+        await RunStreamingWithAgentContextAsync(decorator, session, updates, options);
+
+        // Assert — the auto-approved item should be stored in the session
+        Assert.True(session.StateBag.TryGetValue<List<ToolApprovalRequestContent>>(
+            NonApprovalRequiredFunctionBypassingChatClient.StateBagKey, out var stored, AgentJsonUtilities.DefaultOptions));
+        Assert.NotNull(stored);
+        Assert.Single(stored!);
+        Assert.Equal("req1", stored![0].RequestId);
+    }
+
+    [Fact]
+    public async Task GetStreamingResponseAsync_AllNonApproval_SkipsEmptyUpdateAsync()
+    {
+        // Arrange
+        var normalTool = AIFunctionFactory.Create(() => "result", "normalTool");
+
+        var fccNormal = new FunctionCallContent("call1", "normalTool");
+        var approvalNormal = new ToolApprovalRequestContent("req1", fccNormal);
+
+        var innerClient = CreateMockStreamingChatClient((_, _, _) =>
+            ToAsyncEnumerableAsync(
+                new ChatResponseUpdate(ChatRole.Assistant, "text"),
+                new ChatResponseUpdate { Contents = [approvalNormal] }));
+
+        var decorator = new NonApprovalRequiredFunctionBypassingChatClient(innerClient);
+        var session = new ChatClientAgentSession();
+        var options = new ChatOptions { Tools = [normalTool] };
+
+        // Act
+        var updates = new List<ChatResponseUpdate>();
+        await RunStreamingWithAgentContextAsync(decorator, session, updates, options);
+
+        // Assert — the approval update should be skipped entirely
+        Assert.Single(updates);
+        Assert.Equal("text", updates[0].Text);
+    }
+
+    #endregion
+
+    #region Error Handling Tests
+
+    [Fact]
+    public async Task GetResponseAsync_NoRunContext_ThrowsInvalidOperationExceptionAsync()
+    {
+        // Arrange
+        var innerClient = CreateMockChatClient((_, _, _) =>
+            Task.FromResult(new ChatResponse([new ChatMessage(ChatRole.Assistant, "response")])));
+
+        var decorator = new NonApprovalRequiredFunctionBypassingChatClient(innerClient);
+
+        // Act & Assert — calling directly without agent context
+        await Assert.ThrowsAsync<InvalidOperationException>(
+            () => decorator.GetResponseAsync([new ChatMessage(ChatRole.User, "test")]));
+    }
+
+    [Fact]
+    public async Task GetResponseAsync_NoSession_ThrowsInvalidOperationExceptionAsync()
+    {
+        // Arrange
+        var innerClient = CreateMockChatClient((_, _, _) =>
+            Task.FromResult(new ChatResponse([new ChatMessage(ChatRole.Assistant, "response")])));
+
+        var decorator = new NonApprovalRequiredFunctionBypassingChatClient(innerClient);
+
+        // Act & Assert — run with null session
+        await Assert.ThrowsAsync<InvalidOperationException>(
+            () => RunWithAgentContextAsync(decorator, session: null!));
+    }
+
+    #endregion
+
+    #region Builder Extension Tests
+
+    [Fact]
+    public void UseNonApprovalRequiredFunctionBypassing_AddsDecoratorToPipeline()
+    {
+        // Arrange
+        var innerClient = new Mock<IChatClient>().Object;
+
+        // Act
+        var pipeline = innerClient.AsBuilder()
+            .UseNonApprovalRequiredFunctionBypassing()
+            .Build();
+
+        // Assert
+        Assert.NotNull(pipeline.GetService<NonApprovalRequiredFunctionBypassingChatClient>());
+    }
+
+    [Fact]
+    public void WithDefaultAgentMiddleware_EnableNonApprovalRequiredFunctionBypassing_InjectsDecorator()
+    {
+        // Arrange
+        var innerClient = new Mock<IChatClient>().Object;
+        var options = new ChatClientAgentOptions { EnableNonApprovalRequiredFunctionBypassing = true };
+
+        // Act
+        var pipeline = innerClient.WithDefaultAgentMiddleware(options);
+
+        // Assert
+        Assert.NotNull(pipeline.GetService<NonApprovalRequiredFunctionBypassingChatClient>());
+    }
+
+    [Fact]
+    public void WithDefaultAgentMiddleware_EnableNonApprovalRequiredFunctionBypassingFalse_DoesNotInjectDecorator()
+    {
+        // Arrange
+        var innerClient = new Mock<IChatClient>().Object;
+        var options = new ChatClientAgentOptions { EnableNonApprovalRequiredFunctionBypassing = false };
+
+        // Act
+        var pipeline = innerClient.WithDefaultAgentMiddleware(options);
+
+        // Assert
+        Assert.Null(pipeline.GetService<NonApprovalRequiredFunctionBypassingChatClient>());
+    }
+
+    #endregion
+
+    #region Helpers
+
+    private static async Task<ChatResponse> RunWithAgentContextAsync(
+        NonApprovalRequiredFunctionBypassingChatClient decorator,
+        AgentSession? session,
+        ChatOptions? options = null)
+    {
+        ChatResponse? capturedResponse = null;
+
+        var agent = new TestAIAgent
+        {
+            RunAsyncFunc = async (messages, agentSession, agentOptions, ct) =>
+            {
+                capturedResponse = await decorator.GetResponseAsync(messages, options, ct);
+                return new AgentResponse(capturedResponse);
+            }
+        };
+
+        await agent.RunAsync([new ChatMessage(ChatRole.User, "Hello")], session);
+        return capturedResponse!;
+    }
+
+    private static Task<ChatResponse> RunWithAgentContextAsync(
+        NonApprovalRequiredFunctionBypassingChatClient decorator,
+        AgentSession session)
+        => RunWithAgentContextAsync(decorator, session, options: null);
+
+    private static async Task RunStreamingWithAgentContextAsync(
+        NonApprovalRequiredFunctionBypassingChatClient decorator,
+        AgentSession session,
+        List<ChatResponseUpdate> updates,
+        ChatOptions? options = null)
+    {
+        var agent = new TestAIAgent
+        {
+            RunAsyncFunc = async (messages, agentSession, agentOptions, ct) =>
+            {
+                await foreach (var update in decorator.GetStreamingResponseAsync(messages, options, ct))
+                {
+                    updates.Add(update);
+                }
+
+                return new AgentResponse([new ChatMessage(ChatRole.Assistant, "done")]);
+            }
+        };
+
+        await agent.RunAsync([new ChatMessage(ChatRole.User, "Hello")], session);
+    }
+
+    private static IChatClient CreateMockChatClient(
+        Func<IEnumerable<ChatMessage>, ChatOptions?, CancellationToken, Task<ChatResponse>> onGetResponse)
+    {
+        var mock = new Mock<IChatClient>();
+        mock.Setup(c => c.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions?>(),
+                It.IsAny<CancellationToken>()))
+            .Returns((IEnumerable<ChatMessage> m, ChatOptions? o, CancellationToken ct) => onGetResponse(m, o, ct));
+        return mock.Object;
+    }
+
+    private static IChatClient CreateMockStreamingChatClient(
+        Func<IEnumerable<ChatMessage>, ChatOptions?, CancellationToken, IAsyncEnumerable<ChatResponseUpdate>> onGetStreamingResponse)
+    {
+        var mock = new Mock<IChatClient>();
+        mock.Setup(c => c.GetStreamingResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions?>(),
+                It.IsAny<CancellationToken>()))
+            .Returns((IEnumerable<ChatMessage> m, ChatOptions? o, CancellationToken ct) => onGetStreamingResponse(m, o, ct));
+        return mock.Object;
+    }
+
+    private static async IAsyncEnumerable<ChatResponseUpdate> ToAsyncEnumerableAsync(params ChatResponseUpdate[] updates)
+    {
+        foreach (var update in updates)
+        {
+            yield return update;
+        }
+
+        await Task.CompletedTask;
+    }
+
+    #endregion
+}

dotnet/tests/Microsoft.Agents.AI.UnitTests/Harness/ToolApproval/ToolApprovalAgentBuilderExtensionsTests.cs

@@ -59,15 +59,15 @@ public class ToolApprovalAgentBuilderExtensionsTests
     /// Verify that UseToolApproval with custom JsonSerializerOptions works correctly.
     /// </summary>
     [Fact]
-    public void UseToolApproval_WithCustomJsonSerializerOptions_ReturnsToolApprovalAgent()
+    public void UseToolApproval_WithCustomOptions_ReturnsToolApprovalAgent()
     {
         // Arrange
         var mockAgent = new Mock<AIAgent>();
         var builder = new AIAgentBuilder(mockAgent.Object);
-        var options = new JsonSerializerOptions();
+        var options = new ToolApprovalAgentOptions { JsonSerializerOptions = new JsonSerializerOptions() };
 
         // Act
-        var result = builder.UseToolApproval(jsonSerializerOptions: options).Build();
+        var result = builder.UseToolApproval(options: options).Build();
 
         // Assert
         Assert.IsType<ToolApprovalAgent>(result);

dotnet/tests/Microsoft.Agents.AI.UnitTests/Harness/ToolApproval/ToolApprovalAgentTests.cs

@@ -47,14 +47,14 @@ public class ToolApprovalAgentTests
     }
 
     /// <summary>
-    /// Verify that constructor accepts custom JsonSerializerOptions.
+    /// Verify that constructor accepts custom options.
     /// </summary>
     [Fact]
-    public void Constructor_CustomJsonSerializerOptions_CreatesInstanceAsync()
+    public void Constructor_CustomOptions_CreatesInstance()
     {
         // Arrange
         var innerAgent = new Mock<AIAgent>().Object;
-        var options = new JsonSerializerOptions();
+        var options = new ToolApprovalAgentOptions { JsonSerializerOptions = new JsonSerializerOptions() };
 
         // Act
         var agent = new ToolApprovalAgent(innerAgent, options);
@@ -1535,4 +1535,311 @@ public class ToolApprovalAgentTests
     }
 
     #endregion
+
+    #region Auto-Approval Rules (Heuristics)
+
+    /// <summary>
+    /// Verify that an auto-approval rule can approve a function call that would otherwise need user approval.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_AutoApprovalRule_ApprovesMatchingToolAsync()
+    {
+        // Arrange
+        var session = new ChatClientAgentSession();
+        var approvalRequest = new ToolApprovalRequestContent("req1", new FunctionCallContent("call1", "ReadTool"));
+
+        // Inner agent: first call returns approval request, second returns final response.
+        var callCount = 0;
+        var innerAgent = new Mock<AIAgent>();
+        innerAgent
+            .Protected()
+            .Setup<Task<AgentResponse>>("RunCoreAsync",
+                ItExpr.IsAny<IEnumerable<ChatMessage>>(),
+                ItExpr.IsAny<AgentSession?>(),
+                ItExpr.IsAny<AgentRunOptions?>(),
+                ItExpr.IsAny<CancellationToken>())
+            .ReturnsAsync(() =>
+            {
+                callCount++;
+                if (callCount == 1)
+                {
+                    return new AgentResponse([new ChatMessage(ChatRole.Assistant, [approvalRequest])]);
+                }
+
+                return new AgentResponse([new ChatMessage(ChatRole.Assistant, "Done")]);
+            });
+
+        var options = new ToolApprovalAgentOptions
+        {
+            AutoApprovalRules = [fcc => new ValueTask<bool>(fcc.Name == "ReadTool")]
+        };
+        var agent = new ToolApprovalAgent(innerAgent.Object, options);
+
+        // Act
+        var response = await agent.RunAsync(
+            [new ChatMessage(ChatRole.User, "Hi")],
+            session);
+
+        // Assert — the approval request was auto-approved, inner agent called twice
+        Assert.Equal(2, callCount);
+        Assert.Equal("Done", response.Text);
+    }
+
+    /// <summary>
+    /// Verify that when auto-approval rule does not match, request is surfaced to the caller.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_AutoApprovalRule_DoesNotMatchSurfacesToCallerAsync()
+    {
+        // Arrange
+        var session = new ChatClientAgentSession();
+        var approvalRequest = new ToolApprovalRequestContent("req1", new FunctionCallContent("call1", "DangerousTool"));
+
+        var innerAgent = CreateMockAgent(new AgentResponse([new ChatMessage(ChatRole.Assistant, [approvalRequest])]));
+
+        var options = new ToolApprovalAgentOptions
+        {
+            AutoApprovalRules = [fcc => new ValueTask<bool>(fcc.Name == "ReadTool")]  // Only approves ReadTool
+        };
+        var agent = new ToolApprovalAgent(innerAgent.Object, options);
+
+        // Act
+        var response = await agent.RunAsync(
+            [new ChatMessage(ChatRole.User, "Hi")],
+            session);
+
+        // Assert — request surfaced to caller since heuristic doesn't match
+        var requests = response.Messages.SelectMany(m => m.Contents).OfType<ToolApprovalRequestContent>().ToList();
+        Assert.Single(requests);
+        Assert.Equal("DangerousTool", ((FunctionCallContent)requests[0].ToolCall).Name);
+    }
+
+    /// <summary>
+    /// Verify that multiple auto-approval rules are evaluated in order; first match wins.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_MultipleAutoApprovalRules_FirstMatchWinsAsync()
+    {
+        // Arrange
+        var session = new ChatClientAgentSession();
+        var approvalRequest = new ToolApprovalRequestContent("req1", new FunctionCallContent("call1", "SpecialTool"));
+
+        var callCount = 0;
+        var innerAgent = new Mock<AIAgent>();
+        innerAgent
+            .Protected()
+            .Setup<Task<AgentResponse>>("RunCoreAsync",
+                ItExpr.IsAny<IEnumerable<ChatMessage>>(),
+                ItExpr.IsAny<AgentSession?>(),
+                ItExpr.IsAny<AgentRunOptions?>(),
+                ItExpr.IsAny<CancellationToken>())
+            .ReturnsAsync(() =>
+            {
+                callCount++;
+                if (callCount == 1)
+                {
+                    return new AgentResponse([new ChatMessage(ChatRole.Assistant, [approvalRequest])]);
+                }
+
+                return new AgentResponse([new ChatMessage(ChatRole.Assistant, "Done")]);
+            });
+
+        var rule1Called = false;
+        var rule2Called = false;
+        var options = new ToolApprovalAgentOptions
+        {
+            AutoApprovalRules =
+            [
+                fcc => { rule1Called = true; return new ValueTask<bool>(fcc.Name == "SpecialTool"); },
+                fcc => { rule2Called = true; return new ValueTask<bool>(true); }  // Should not be reached
+            ]
+        };
+        var agent = new ToolApprovalAgent(innerAgent.Object, options);
+
+        // Act
+        await agent.RunAsync([new ChatMessage(ChatRole.User, "Hi")], session);
+
+        // Assert — first rule matched, second was never called
+        Assert.True(rule1Called);
+        Assert.False(rule2Called);
+    }
+
+    /// <summary>
+    /// Verify that standing rules are evaluated before auto-approval rules.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_StandingRuleTakesPrecedenceOverAutoApprovalRuleAsync()
+    {
+        // Arrange
+        var session = new ChatClientAgentSession();
+        var approvalRequest = new ToolApprovalRequestContent("req1", new FunctionCallContent("call1", "MyTool"));
+
+        var callCount = 0;
+        var innerAgent = new Mock<AIAgent>();
+        innerAgent
+            .Protected()
+            .Setup<Task<AgentResponse>>("RunCoreAsync",
+                ItExpr.IsAny<IEnumerable<ChatMessage>>(),
+                ItExpr.IsAny<AgentSession?>(),
+                ItExpr.IsAny<AgentRunOptions?>(),
+                ItExpr.IsAny<CancellationToken>())
+            .ReturnsAsync(() =>
+            {
+                callCount++;
+                if (callCount <= 2)
+                {
+                    return new AgentResponse([new ChatMessage(ChatRole.Assistant, [approvalRequest])]);
+                }
+
+                return new AgentResponse([new ChatMessage(ChatRole.Assistant, "Done")]);
+            });
+
+        var heuristicCalled = false;
+        var options = new ToolApprovalAgentOptions
+        {
+            AutoApprovalRules = [fcc => { heuristicCalled = true; return new ValueTask<bool>(true); }]
+        };
+        var agent = new ToolApprovalAgent(innerAgent.Object, options);
+
+        // Call 1: heuristic should be called (no standing rule yet)
+        var response1 = await agent.RunAsync([new ChatMessage(ChatRole.User, "Hi")], session);
+        Assert.True(heuristicCalled);
+        Assert.Equal("Done", response1.Text);
+
+        // Now establish a standing rule by sending AlwaysApprove
+        heuristicCalled = false;
+        callCount = 0;
+        var alwaysApprove = new AlwaysApproveToolApprovalResponseContent(
+            approvalRequest.CreateResponse(approved: true),
+            alwaysApproveTool: true,
+            alwaysApproveToolWithArguments: false);
+
+        // Call 2: standing rule should match first, heuristic should NOT be called
+        var response2 = await agent.RunAsync(
+            [new ChatMessage(ChatRole.User, [alwaysApprove])],
+            session);
+        Assert.False(heuristicCalled);
+        Assert.Equal("Done", response2.Text);
+    }
+
+    /// <summary>
+    /// Verify that when a batch contains a mix of heuristic-approved and standing-rule-approved
+    /// requests, the collected approval responses preserve the original request order rather than
+    /// being grouped by approval kind.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_MixedAutoApprovals_PreserveOriginalOrderAsync()
+    {
+        // Arrange
+        var session = new ChatClientAgentSession();
+
+        // Batch ordering: first request is approved by a heuristic, second by a standing rule.
+        var heuristicRequest = new ToolApprovalRequestContent("reqA", new FunctionCallContent("callA", "HeuristicTool"));
+        var standingRequest = new ToolApprovalRequestContent("reqB", new FunctionCallContent("callB", "StandingTool"));
+
+        var batchResponse = new AgentResponse([new ChatMessage(ChatRole.Assistant, [heuristicRequest, standingRequest])]);
+        var finalResponse = new AgentResponse([new ChatMessage(ChatRole.Assistant, "Done")]);
+
+        var callCount = 0;
+        List<ChatMessage>? secondCallMessages = null;
+        var innerAgent = new Mock<AIAgent>();
+        innerAgent
+            .Protected()
+            .Setup<Task<AgentResponse>>("RunCoreAsync",
+                ItExpr.IsAny<IEnumerable<ChatMessage>>(),
+                ItExpr.IsAny<AgentSession?>(),
+                ItExpr.IsAny<AgentRunOptions?>(),
+                ItExpr.IsAny<CancellationToken>())
+            .Callback<IEnumerable<ChatMessage>, AgentSession?, AgentRunOptions?, CancellationToken>((msgs, _, _, _) =>
+            {
+                callCount++;
+                if (callCount == 2)
+                {
+                    secondCallMessages = msgs.ToList();
+                }
+            })
+            .ReturnsAsync(() => callCount == 1 ? batchResponse : finalResponse);
+
+        var options = new ToolApprovalAgentOptions
+        {
+            AutoApprovalRules = [fcc => new ValueTask<bool>(fcc.Name == "HeuristicTool")]
+        };
+        var agent = new ToolApprovalAgent(innerAgent.Object, options);
+
+        // Establish a standing rule for "StandingTool" via an AlwaysApprove response in the same call.
+        var alwaysApprove = standingRequest.CreateAlwaysApproveToolResponse("User said always");
+
+        // Act — both requests auto-approve (heuristic + standing rule), so the inner agent is re-invoked.
+        var response = await agent.RunAsync(
+            [new ChatMessage(ChatRole.User, [alwaysApprove])],
+            session);
+
+        // Assert — inner agent re-called and final response returned.
+        Assert.Equal(2, callCount);
+        Assert.Equal("Done", response.Text);
+
+        // The injected approval responses must preserve the original request order: reqA before reqB,
+        // even though reqA was approved by a heuristic and reqB by a standing rule.
+        Assert.NotNull(secondCallMessages);
+        var injected = secondCallMessages!
+            .SelectMany(m => m.Contents)
+            .OfType<ToolApprovalResponseContent>()
+            .Where(r => r.RequestId is "reqA" or "reqB")
+            .ToList();
+        Assert.Equal(2, injected.Count);
+        Assert.Equal("reqA", injected[0].RequestId);
+        Assert.Equal("reqB", injected[1].RequestId);
+        Assert.All(injected, r => Assert.True(r.Approved));
+    }
+
+    /// <summary>
+    /// Verify that auto-approval rules work in the streaming path.
+    /// </summary>
+    [Fact]
+    public async Task RunStreamingAsync_AutoApprovalRule_ApprovesMatchingToolAsync()
+    {
+        // Arrange
+        var session = new ChatClientAgentSession();
+        var approvalRequest = new ToolApprovalRequestContent("req1", new FunctionCallContent("call1", "ReadTool"));
+
+        var callCount = 0;
+        var innerAgent = new Mock<AIAgent>();
+        innerAgent
+            .Protected()
+            .Setup<IAsyncEnumerable<AgentResponseUpdate>>("RunCoreStreamingAsync",
+                ItExpr.IsAny<IEnumerable<ChatMessage>>(),
+                ItExpr.IsAny<AgentSession?>(),
+                ItExpr.IsAny<AgentRunOptions?>(),
+                ItExpr.IsAny<CancellationToken>())
+            .Returns(() =>
+            {
+                callCount++;
+                if (callCount == 1)
+                {
+                    return ToAsyncEnumerableAsync([new AgentResponseUpdate(ChatRole.Assistant, [approvalRequest])]);
+                }
+
+                return ToAsyncEnumerableAsync([new AgentResponseUpdate(ChatRole.Assistant, "Done")]);
+            });
+
+        var options = new ToolApprovalAgentOptions
+        {
+            AutoApprovalRules = [fcc => new ValueTask<bool>(fcc.Name == "ReadTool")]
+        };
+        var agent = new ToolApprovalAgent(innerAgent.Object, options);
+
+        // Act
+        var updates = new List<AgentResponseUpdate>();
+        await foreach (var update in agent.RunStreamingAsync([new ChatMessage(ChatRole.User, "Hi")], session))
+        {
+            updates.Add(update);
+        }
+
+        // Assert — the approval request was auto-approved, inner agent streamed twice
+        Assert.Equal(2, callCount);
+        Assert.Single(updates);
+        Assert.Equal("Done", updates[0].Text);
+    }
+
+    #endregion
 }

dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/ObjectModel/ForeachExecutorTest.cs

@@ -142,6 +142,34 @@ public sealed class ForeachExecutorTest(ITestOutputHelper output) : WorkflowActi
             indexName: "CurrentIndex");
     }
 
+    [Fact]
+    public async Task ForeachTakeNextWithMultiFieldRecordAsync()
+    {
+        // Arrange
+        const string CurrentValueName = "CurrentValue";
+        this.SetVariableState(CurrentValueName);
+
+        TableDataValue tableValue = DataValue.TableFromRecords(
+            DataValue.RecordFromFields(
+                new KeyValuePair<string, DataValue>("name", new StringDataValue("Alice")),
+                new KeyValuePair<string, DataValue>("role", new StringDataValue("Engineer"))));
+
+        Foreach model = this.CreateModel(
+            displayName: nameof(ForeachTakeNextWithMultiFieldRecordAsync),
+            items: ValueExpression.Literal(tableValue),
+            valueName: CurrentValueName,
+            indexName: null);
+        ForeachExecutor action = new(model, this.State);
+
+        // Act
+        await this.ExecuteAsync(action, ForeachExecutor.Steps.Next(action.Id), action.TakeNextAsync);
+
+        // Assert
+        RecordValue currentValue = Assert.IsType<RecordValue>(this.State.Get(CurrentValueName), exactMatch: false);
+        Assert.Equal("Alice", currentValue.GetField("name").ToObject());
+        Assert.Equal("Engineer", currentValue.GetField("role").ToObject());
+    }
+
     [Fact]
     public async Task ForeachTakeLastAsync()
     {

dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/ObjectModel/InvokeMcpToolExecutorTest.cs

@@ -2,6 +2,7 @@
 
 using System.Collections.Generic;
 using System.Linq;
+using System.Reflection;
 using System.Threading;
 using System.Threading.Tasks;
 using Microsoft.Agents.AI.Workflows.Declarative.Events;
@@ -11,7 +12,9 @@ using Microsoft.Agents.AI.Workflows.Declarative.ObjectModel;
 using Microsoft.Agents.AI.Workflows.Declarative.PowerFx;
 using Microsoft.Agents.ObjectModel;
 using Microsoft.Extensions.AI;
+using Microsoft.PowerFx.Types;
 using Moq;
+using ApprovalSnapshot = Microsoft.Agents.AI.Workflows.Declarative.ObjectModel.InvokeMcpToolExecutor.ApprovalSnapshot;
 
 namespace Microsoft.Agents.AI.Workflows.Declarative.UnitTests.ObjectModel;
 
@@ -842,6 +845,313 @@ public sealed class InvokeMcpToolExecutorTest(ITestOutputHelper output) : Workfl
 
     #endregion
 
+    #region Approval Snapshot Security Tests
+
+    /// <summary>
+    /// Verifies that mutating the tool name variable after approval does not change
+    /// which tool is actually invoked. The originally-approved tool name must be used.
+    /// </summary>
+    [Fact]
+    public async Task InvokeMcpToolCaptureResponseUsesApprovedToolNameNotMutatedAsync()
+    {
+        // Arrange
+        const string ApprovedToolName = "safe_readonly_query";
+        const string MutatedToolName = "dangerous_admin_tool";
+
+        this.State.Set("TargetTool", FormulaValue.New(ApprovedToolName));
+        this.State.InitializeSystem();
+        this.State.Bind();
+
+        InvokeMcpTool model = this.CreateModelWithVariableToolName(
+            displayName: nameof(InvokeMcpToolCaptureResponseUsesApprovedToolNameNotMutatedAsync),
+            serverUrl: TestServerUrl,
+            variableName: "TargetTool");
+
+        string? capturedToolName = null;
+        Mock<IMcpToolHandler> mockProvider = new();
+        mockProvider.Setup(provider => provider.InvokeToolAsync(
+                It.IsAny<string>(),
+                It.IsAny<string?>(),
+                It.IsAny<string>(),
+                It.IsAny<IDictionary<string, object?>?>(),
+                It.IsAny<IDictionary<string, string>?>(),
+                It.IsAny<string?>(),
+                It.IsAny<CancellationToken>()))
+            .Callback<string, string?, string, IDictionary<string, object?>?, IDictionary<string, string>?, string?, CancellationToken>(
+                (_, _, toolName, _, _, _, _) => capturedToolName = toolName)
+            .ReturnsAsync(new McpServerToolResultContent("capture-call-id")
+            {
+                Outputs = [new TextContent("result")]
+            });
+        MockAgentProvider mockAgentProvider = new();
+        InvokeMcpToolExecutor action = new(model, mockProvider.Object, mockAgentProvider.Object, this.State);
+
+        // Act - trigger ExecuteAsync to store the approval snapshot
+        Mock<IWorkflowContext> mockContext = CreateMockWorkflowContext();
+        await action.HandleAsync(new ActionExecutorResult(action.Id), mockContext.Object, CancellationToken.None);
+
+        // Simulate parallel branch mutating state during the approval window
+        this.State.Set("TargetTool", FormulaValue.New(MutatedToolName));
+        this.State.Bind();
+
+        // User clicks approve (they saw "safe_readonly_query" in the approval UI)
+        McpServerToolCallContent toolCall = new(action.Id, ApprovedToolName, TestServerUrl);
+        ToolApprovalRequestContent approvalRequest = new(action.Id, toolCall);
+        ToolApprovalResponseContent approvalResponse = approvalRequest.CreateResponse(approved: true);
+        ExternalInputResponse response = new(new ChatMessage(ChatRole.User, [approvalResponse]));
+
+        // Resume after approval
+        await action.CaptureResponseAsync(mockContext.Object, response, CancellationToken.None);
+
+        // Assert - the originally-approved tool name must be used, not the mutated one
+        Assert.NotNull(capturedToolName);
+        Assert.Equal(ApprovedToolName, capturedToolName);
+    }
+
+    /// <summary>
+    /// Verifies that mutating an argument variable after approval does not change
+    /// the arguments actually passed to the MCP tool. The originally-approved arguments must be used.
+    /// </summary>
+    [Fact]
+    public async Task InvokeMcpToolCaptureResponseUsesApprovedArgumentsNotMutatedAsync()
+    {
+        // Arrange
+        const string ApprovedQuery = "SELECT * FROM users LIMIT 10";
+        const string MutatedQuery = "DROP TABLE users CASCADE; --";
+
+        this.State.Set("SqlQuery", FormulaValue.New(ApprovedQuery));
+        this.State.InitializeSystem();
+        this.State.Bind();
+
+        InvokeMcpTool model = this.CreateModelWithVariableArgument(
+            displayName: nameof(InvokeMcpToolCaptureResponseUsesApprovedArgumentsNotMutatedAsync),
+            serverUrl: TestServerUrl,
+            toolName: TestToolName,
+            argumentKey: "query",
+            variableName: "SqlQuery");
+
+        IDictionary<string, object?>? capturedArguments = null;
+        Mock<IMcpToolHandler> mockProvider = new();
+        mockProvider.Setup(provider => provider.InvokeToolAsync(
+                It.IsAny<string>(),
+                It.IsAny<string?>(),
+                It.IsAny<string>(),
+                It.IsAny<IDictionary<string, object?>?>(),
+                It.IsAny<IDictionary<string, string>?>(),
+                It.IsAny<string?>(),
+                It.IsAny<CancellationToken>()))
+            .Callback<string, string?, string, IDictionary<string, object?>?, IDictionary<string, string>?, string?, CancellationToken>(
+                (_, _, _, arguments, _, _, _) => capturedArguments = arguments)
+            .ReturnsAsync(new McpServerToolResultContent("capture-call-id")
+            {
+                Outputs = [new TextContent("result")]
+            });
+        MockAgentProvider mockAgentProvider = new();
+        InvokeMcpToolExecutor action = new(model, mockProvider.Object, mockAgentProvider.Object, this.State);
+
+        // Act - trigger ExecuteAsync to store the approval snapshot
+        Mock<IWorkflowContext> mockContext = CreateMockWorkflowContext();
+        await action.HandleAsync(new ActionExecutorResult(action.Id), mockContext.Object, CancellationToken.None);
+
+        // Simulate parallel branch mutating state during the approval window
+        this.State.Set("SqlQuery", FormulaValue.New(MutatedQuery));
+        this.State.Bind();
+
+        // User clicks approve
+        McpServerToolCallContent toolCall = new(action.Id, TestToolName, TestServerUrl);
+        ToolApprovalRequestContent approvalRequest = new(action.Id, toolCall);
+        ToolApprovalResponseContent approvalResponse = approvalRequest.CreateResponse(approved: true);
+        ExternalInputResponse response = new(new ChatMessage(ChatRole.User, [approvalResponse]));
+
+        // Resume after approval
+        await action.CaptureResponseAsync(mockContext.Object, response, CancellationToken.None);
+
+        // Assert - the originally-approved argument must be used, not the mutated one
+        Assert.NotNull(capturedArguments);
+        Assert.Equal(ApprovedQuery, capturedArguments["query"]?.ToString());
+    }
+
+    /// <summary>
+    /// Verifies that mutating the server URL variable after approval does not redirect
+    /// the MCP tool call to a different server. The originally-approved server URL must be used.
+    /// </summary>
+    [Fact]
+    public async Task InvokeMcpToolCaptureResponseUsesApprovedServerUrlNotMutatedAsync()
+    {
+        // Arrange
+        const string ApprovedServerUrl = "https://internal-mcp.corp";
+        const string MutatedServerUrl = "https://attacker.evil/steal";
+
+        this.State.Set("McpEndpoint", FormulaValue.New(ApprovedServerUrl));
+        this.State.InitializeSystem();
+        this.State.Bind();
+
+        InvokeMcpTool model = this.CreateModelWithVariableServerUrl(
+            displayName: nameof(InvokeMcpToolCaptureResponseUsesApprovedServerUrlNotMutatedAsync),
+            variableName: "McpEndpoint",
+            toolName: TestToolName);
+
+        string? capturedServerUrl = null;
+        Mock<IMcpToolHandler> mockProvider = new();
+        mockProvider.Setup(provider => provider.InvokeToolAsync(
+                It.IsAny<string>(),
+                It.IsAny<string?>(),
+                It.IsAny<string>(),
+                It.IsAny<IDictionary<string, object?>?>(),
+                It.IsAny<IDictionary<string, string>?>(),
+                It.IsAny<string?>(),
+                It.IsAny<CancellationToken>()))
+            .Callback<string, string?, string, IDictionary<string, object?>?, IDictionary<string, string>?, string?, CancellationToken>(
+                (serverUrl, _, _, _, _, _, _) => capturedServerUrl = serverUrl)
+            .ReturnsAsync(new McpServerToolResultContent("capture-call-id")
+            {
+                Outputs = [new TextContent("result")]
+            });
+        MockAgentProvider mockAgentProvider = new();
+        InvokeMcpToolExecutor action = new(model, mockProvider.Object, mockAgentProvider.Object, this.State);
+
+        // Act - trigger ExecuteAsync to store the approval snapshot
+        Mock<IWorkflowContext> mockContext = CreateMockWorkflowContext();
+        await action.HandleAsync(new ActionExecutorResult(action.Id), mockContext.Object, CancellationToken.None);
+
+        // Simulate parallel branch mutating state during the approval window
+        this.State.Set("McpEndpoint", FormulaValue.New(MutatedServerUrl));
+        this.State.Bind();
+
+        // User clicks approve
+        McpServerToolCallContent toolCall = new(action.Id, TestToolName, ApprovedServerUrl);
+        ToolApprovalRequestContent approvalRequest = new(action.Id, toolCall);
+        ToolApprovalResponseContent approvalResponse = approvalRequest.CreateResponse(approved: true);
+        ExternalInputResponse response = new(new ChatMessage(ChatRole.User, [approvalResponse]));
+
+        // Resume after approval
+        await action.CaptureResponseAsync(mockContext.Object, response, CancellationToken.None);
+
+        // Assert - the originally-approved server URL must be used, not the mutated one
+        Assert.NotNull(capturedServerUrl);
+        Assert.Equal(ApprovedServerUrl, capturedServerUrl);
+    }
+
+    /// <summary>
+    /// Verifies that the approval snapshot survives a checkpoint/restore cycle.
+    /// After restore, the originally-approved tool name must still be used even if state was mutated.
+    /// </summary>
+    [Fact]
+    public async Task InvokeMcpToolCaptureResponseUsesSnapshotAfterCheckpointRestoreAsync()
+    {
+        // Arrange
+        const string ApprovedToolName = "safe_readonly_query";
+        const string MutatedToolName = "dangerous_admin_tool";
+
+        this.State.Set("TargetTool", FormulaValue.New(ApprovedToolName));
+        this.State.InitializeSystem();
+        this.State.Bind();
+
+        InvokeMcpTool model = this.CreateModelWithVariableToolName(
+            displayName: nameof(InvokeMcpToolCaptureResponseUsesSnapshotAfterCheckpointRestoreAsync),
+            serverUrl: TestServerUrl,
+            variableName: "TargetTool");
+
+        string? capturedToolName = null;
+        Mock<IMcpToolHandler> mockProvider = new();
+        mockProvider.Setup(provider => provider.InvokeToolAsync(
+                It.IsAny<string>(),
+                It.IsAny<string?>(),
+                It.IsAny<string>(),
+                It.IsAny<IDictionary<string, object?>?>(),
+                It.IsAny<IDictionary<string, string>?>(),
+                It.IsAny<string?>(),
+                It.IsAny<CancellationToken>()))
+            .Callback<string, string?, string, IDictionary<string, object?>?, IDictionary<string, string>?, string?, CancellationToken>(
+                (_, _, toolName, _, _, _, _) => capturedToolName = toolName)
+            .ReturnsAsync(new McpServerToolResultContent("capture-call-id")
+            {
+                Outputs = [new TextContent("result")]
+            });
+        MockAgentProvider mockAgentProvider = new();
+        InvokeMcpToolExecutor action = new(model, mockProvider.Object, mockAgentProvider.Object, this.State);
+
+        // Act - trigger ExecuteAsync to store the approval snapshot
+        Mock<IWorkflowContext> mockContext = CreateMockWorkflowContextWithStateStore();
+        await action.HandleAsync(new ActionExecutorResult(action.Id), mockContext.Object, CancellationToken.None);
+
+        // Simulate checkpoint: persist to state store
+        await InvokeProtectedMethodAsync(action, "OnCheckpointingAsync", mockContext.Object, CancellationToken.None);
+
+        // Simulate restore on a "new" executor instance by clearing the in-memory field via reflection
+        // (In production, a new executor instance would be created with _approvalSnapshot == null)
+        typeof(InvokeMcpToolExecutor)
+            .GetField("_approvalSnapshot", BindingFlags.NonPublic | BindingFlags.Instance)!
+            .SetValue(action, null);
+
+        // Restore from state store
+        await InvokeProtectedMethodAsync(action, "OnCheckpointRestoredAsync", mockContext.Object, CancellationToken.None);
+
+        // Mutate state after restore (simulating parallel branch)
+        this.State.Set("TargetTool", FormulaValue.New(MutatedToolName));
+        this.State.Bind();
+
+        // User clicks approve
+        McpServerToolCallContent toolCall = new(action.Id, ApprovedToolName, TestServerUrl);
+        ToolApprovalRequestContent approvalRequest = new(action.Id, toolCall);
+        ToolApprovalResponseContent approvalResponse = approvalRequest.CreateResponse(approved: true);
+        ExternalInputResponse response = new(new ChatMessage(ChatRole.User, [approvalResponse]));
+
+        // Resume after approval
+        await action.CaptureResponseAsync(mockContext.Object, response, CancellationToken.None);
+
+        // Assert - the originally-approved tool name must be used, not the mutated one
+        Assert.NotNull(capturedToolName);
+        Assert.Equal(ApprovedToolName, capturedToolName);
+    }
+
+    private static Mock<IWorkflowContext> CreateMockWorkflowContext()
+    {
+        Mock<IWorkflowContext> mockContext = new();
+        mockContext.Setup(c => c.AddEventAsync(It.IsAny<WorkflowEvent>(), It.IsAny<CancellationToken>()))
+            .Returns(default(ValueTask));
+        mockContext.Setup(c => c.QueueStateUpdateAsync(It.IsAny<string>(), It.IsAny<object?>(), It.IsAny<string?>(), It.IsAny<CancellationToken>()))
+            .Returns(default(ValueTask));
+        mockContext.Setup(c => c.SendMessageAsync(It.IsAny<object>(), It.IsAny<string?>(), It.IsAny<CancellationToken>()))
+            .Returns(default(ValueTask));
+        return mockContext;
+    }
+
+    /// <summary>
+    /// Creates a mock workflow context that actually stores state values (for checkpoint/restore tests).
+    /// </summary>
+    private static Mock<IWorkflowContext> CreateMockWorkflowContextWithStateStore()
+    {
+        Dictionary<string, object?> stateStore = new();
+        Mock<IWorkflowContext> mockContext = new();
+        mockContext.Setup(c => c.AddEventAsync(It.IsAny<WorkflowEvent>(), It.IsAny<CancellationToken>()))
+            .Returns(default(ValueTask));
+        mockContext.Setup(c => c.QueueStateUpdateAsync(It.IsAny<string>(), It.IsAny<ApprovalSnapshot?>(), It.IsAny<string?>(), It.IsAny<CancellationToken>()))
+            .Callback<string, ApprovalSnapshot?, string?, CancellationToken>((key, value, _, _) => stateStore[key] = value)
+            .Returns(default(ValueTask));
+        mockContext.Setup(c => c.SendMessageAsync(It.IsAny<object>(), It.IsAny<string?>(), It.IsAny<CancellationToken>()))
+            .Returns(default(ValueTask));
+        mockContext.Setup(c => c.ReadStateAsync<ApprovalSnapshot>(It.IsAny<string>(), It.IsAny<string?>(), It.IsAny<CancellationToken>()))
+            .Returns<string, string?, CancellationToken>((key, _, _) =>
+                new ValueTask<ApprovalSnapshot?>(stateStore.TryGetValue(key, out object? val) ? val as ApprovalSnapshot : null));
+        mockContext.Setup(c => c.ReadStateKeysAsync(It.IsAny<string?>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(new HashSet<string>());
+        return mockContext;
+    }
+
+    /// <summary>
+    /// Invokes a protected method on an executor via reflection (for testing checkpoint hooks).
+    /// </summary>
+    private static async ValueTask InvokeProtectedMethodAsync(InvokeMcpToolExecutor action, string methodName, IWorkflowContext context, CancellationToken cancellationToken)
+    {
+        MethodInfo method = typeof(InvokeMcpToolExecutor)
+            .GetMethod(methodName, BindingFlags.NonPublic | BindingFlags.Instance)!;
+        ValueTask result = (ValueTask)method.Invoke(action, [context, cancellationToken])!;
+        await result.ConfigureAwait(false);
+    }
+
+    #endregion
+
     #region CompleteAsync Tests
 
     [Fact]
@@ -951,6 +1261,50 @@ public sealed class InvokeMcpToolExecutorTest(ITestOutputHelper output) : Workfl
         return AssignParent<InvokeMcpTool>(builder);
     }
 
+    private InvokeMcpTool CreateModelWithVariableToolName(string displayName, string serverUrl, string variableName)
+    {
+        InvokeMcpTool.Builder builder = new()
+        {
+            Id = this.CreateActionId(),
+            DisplayName = this.FormatDisplayName(displayName),
+            ServerUrl = new StringExpression.Builder(StringExpression.Literal(serverUrl)),
+            ToolName = new StringExpression.Builder(
+                StringExpression.Variable(PropertyPath.TopicVariable(variableName))),
+            RequireApproval = new BoolExpression.Builder(BoolExpression.Literal(true)),
+        };
+        return AssignParent<InvokeMcpTool>(builder);
+    }
+
+    private InvokeMcpTool CreateModelWithVariableArgument(
+        string displayName, string serverUrl, string toolName, string argumentKey, string variableName)
+    {
+        InvokeMcpTool.Builder builder = new()
+        {
+            Id = this.CreateActionId(),
+            DisplayName = this.FormatDisplayName(displayName),
+            ServerUrl = new StringExpression.Builder(StringExpression.Literal(serverUrl)),
+            ToolName = new StringExpression.Builder(StringExpression.Literal(toolName)),
+            RequireApproval = new BoolExpression.Builder(BoolExpression.Literal(true)),
+        };
+        builder.Arguments.Add(argumentKey,
+            ValueExpression.Variable(PropertyPath.TopicVariable(variableName)));
+        return AssignParent<InvokeMcpTool>(builder);
+    }
+
+    private InvokeMcpTool CreateModelWithVariableServerUrl(string displayName, string variableName, string toolName)
+    {
+        InvokeMcpTool.Builder builder = new()
+        {
+            Id = this.CreateActionId(),
+            DisplayName = this.FormatDisplayName(displayName),
+            ServerUrl = new StringExpression.Builder(
+                StringExpression.Variable(PropertyPath.TopicVariable(variableName))),
+            ToolName = new StringExpression.Builder(StringExpression.Literal(toolName)),
+            RequireApproval = new BoolExpression.Builder(BoolExpression.Literal(true)),
+        };
+        return AssignParent<InvokeMcpTool>(builder);
+    }
+
     #endregion
 
     #region Mock MCP Tool Provider

python/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.8.0] - 2026-06-04
+
+### Added
+- **agent-framework-core**: Add MCP-based skills discovery (`McpSkillsSource`) ([#6169](https://github.com/microsoft/agent-framework/pull/6169))
+- **agent-framework-core**: Progressive tool exposure via `FunctionInvocationContext` ([#6233](https://github.com/microsoft/agent-framework/pull/6233))
+- **agent-framework-core**: Add background agent support to harness agent ([#6155](https://github.com/microsoft/agent-framework/pull/6155))
+- **agent-framework-core**: Add `AgentFileStore` and `FileAccessProvider` for file access operations ([#6099](https://github.com/microsoft/agent-framework/pull/6099))
+- **agent-framework-core**: Coalesce code interpreter history chunks ([#5801](https://github.com/microsoft/agent-framework/pull/5801))
+- **agent-framework-core**: Run sync tools off the event loop ([#5773](https://github.com/microsoft/agent-framework/pull/5773))
+- **agent-framework-bedrock**: Implement native structured output support via Converse API ([#6052](https://github.com/microsoft/agent-framework/pull/6052))
+- **agent-framework-foundry**: Add Foundry Adaptive Evals integration for rubric-generation ([#6101](https://github.com/microsoft/agent-framework/pull/6101))
+- **agent-framework-foundry**: Add `timeout` parameter to `FoundryAgent` to fix `ConnectTimeout` on multi-turn conversations ([#6263](https://github.com/microsoft/agent-framework/pull/6263))
+- **agent-framework-mistral**: Add Mistral AI embedding client package ([#5480](https://github.com/microsoft/agent-framework/pull/5480))
+- **agent-framework-a2a**: Expose `supported_protocol_bindings` as configurable parameter ([#6098](https://github.com/microsoft/agent-framework/pull/6098))
+- **agent-framework-a2a**: Set `message_id` on `AgentResponseUpdate` for message-bearing paths ([#6163](https://github.com/microsoft/agent-framework/pull/6163))
+- **agent-framework-foundry-hosting**: Persist hosted MCP call/results as canonical `mcp_call` output ([#6070](https://github.com/microsoft/agent-framework/pull/6070))
+
+### Changed
+- **agent-framework-github-copilot**: [BREAKING] Upgrade `github-copilot-sdk` to v1.0.0 (stable) ([#6292](https://github.com/microsoft/agent-framework/pull/6292))
+- **agent-framework-core**: [BREAKING — experimental] Refactor Skill API to async resource and script lookup ([#6135](https://github.com/microsoft/agent-framework/pull/6135))
+- **agent-framework-github-copilot**: Promote to release candidate (`1.0.0rc1`)
+- **agent-framework-declarative**: Promote to release candidate (`1.0.0rc1`) ([#6256](https://github.com/microsoft/agent-framework/pull/6256))
+
+### Fixed
+- **agent-framework-core**: Fix compaction message-id collisions and tool-loop summary persistence ([#6299](https://github.com/microsoft/agent-framework/pull/6299))
+- **agent-framework-core**: Fix observability unsafe serialization of function-call arguments containing dataclass/framework objects ([#6026](https://github.com/microsoft/agent-framework/pull/6026))
+- **agent-framework-core**: Consolidate MCP reliability fixes ([#6145](https://github.com/microsoft/agent-framework/pull/6145))
+- **agent-framework-core**: Backfill chat span request model if unknown and response model is available ([#6160](https://github.com/microsoft/agent-framework/pull/6160))
+- **agent-framework-anthropic**: Skip orphan anthropic thinking signatures ([#5784](https://github.com/microsoft/agent-framework/pull/5784))
+- **agent-framework-foundry**: Fix `FoundryAgent` stripping model from `PromptAgent` requests ([#5526](https://github.com/microsoft/agent-framework/pull/5526))
+- **agent-framework-foundry-hosting**: Fix toolbox consent flow in hosted agent ([#6249](https://github.com/microsoft/agent-framework/pull/6249))
+- **agent-framework-foundry-hosting**: Drop hosted MCP calls when reasoning is stripped ([#6210](https://github.com/microsoft/agent-framework/pull/6210))
+- **agent-framework-openai**: Fix OTLP HTTP base-endpoint losing `/v1/{signal}` auto-append ([#5913](https://github.com/microsoft/agent-framework/pull/5913))
+- **agent-framework-openai**: Drop hosted MCP calls when reasoning is stripped ([#6210](https://github.com/microsoft/agent-framework/pull/6210))
+- **agent-framework-orchestrations**: Fix spurious Magentic custom manager warning ([#6261](https://github.com/microsoft/agent-framework/pull/6261))
+- **agent-framework-azurefunctions**: Fix integration test worker crashes on Py3.13 ([#4260](https://github.com/microsoft/agent-framework/pull/4260))
+
 ## [1.7.0] - 2026-05-28
 
 ### Added
@@ -1132,7 +1169,8 @@ Release candidate for **agent-framework-core** and **agent-framework-azure-ai**
 
 For more information, see the [announcement blog post](https://devblogs.microsoft.com/foundry/introducing-microsoft-agent-framework-the-open-source-engine-for-agentic-ai-apps/).
 
-[Unreleased]: https://github.com/microsoft/agent-framework/compare/python-1.7.0...HEAD
+[Unreleased]: https://github.com/microsoft/agent-framework/compare/python-1.8.0...HEAD
+[1.8.0]: https://github.com/microsoft/agent-framework/compare/python-1.7.0...python-1.8.0
 [1.7.0]: https://github.com/microsoft/agent-framework/compare/python-1.6.0...python-1.7.0
 [1.6.0]: https://github.com/microsoft/agent-framework/compare/python-1.5.0...python-1.6.0
 [1.5.0]: https://github.com/microsoft/agent-framework/compare/python-1.4.0...python-1.5.0

python/PACKAGE_STATUS.md

@@ -33,7 +33,7 @@ Status is grouped into these buckets:
 | `agent-framework-foundry` | `python/packages/foundry` | `released` |
 | `agent-framework-foundry-local` | `python/packages/foundry_local` | `beta` |
 | `agent-framework-gemini` | `python/packages/gemini` | `alpha` |
-| `agent-framework-github-copilot` | `python/packages/github_copilot` | `beta` |
+| `agent-framework-github-copilot` | `python/packages/github_copilot` | `rc` |
 | `agent-framework-hyperlight` | `python/packages/hyperlight` | `beta` |
 | `agent-framework-lab` | `python/packages/lab` | `beta` |
 | `agent-framework-mem0` | `python/packages/mem0` | `beta` |

python/packages/a2a/pyproject.toml

@@ -4,7 +4,7 @@ description = "A2A integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260528"
+version = "1.0.0b260604"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.7.0,<2",
+    "agent-framework-core>=1.8.0,<2",
     "a2a-sdk>=1.0.0,<2",
 ]
 

python/packages/anthropic/pyproject.toml

@@ -4,7 +4,7 @@ description = "Anthropic integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260521"
+version = "1.0.0b260604"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.6.0,<2",
+    "agent-framework-core>=1.8.0,<2",
     "anthropic>=0.80.0,<0.80.1",
 ]
 

python/packages/azurefunctions/agent_framework_azurefunctions/_serialization.py

@@ -14,24 +14,6 @@ This module adds:
 - reconstruct_to_type: for HITL responses where external data (without type markers)
   needs to be reconstructed to a known type
 - resolve_type: resolves 'module:class' type keys to Python types
-
-Security Model
---------------
-The underlying Azure Durable Functions storage (Azure Storage account) is the
-trusted persistence layer for serialized checkpoint data.  The
-``RestrictedUnpickler`` in the core encoding module provides defense-in-depth
-type filtering, but checkpoint storage itself must be properly access-controlled:
-
-- Ensure the Azure Storage account used by Durable Functions is not publicly
-  writable and uses appropriate RBAC / shared-access policies.
-- Never route untrusted user input directly into ``deserialize_value`` without
-  first calling :func:`strip_pickle_markers` to neutralize injection of
-  pickle markers into the data path.
-- Configure your checkpoint storage with ``allowed_checkpoint_types`` (or call
-  ``decode_checkpoint_value(..., allowed_types=...)`` directly) to restrict the set of types that can be deserialized.
-
-See :mod:`agent_framework._workflows._checkpoint_encoding` for the full
-security model documentation.
 """
 
 from __future__ import annotations

python/packages/azurefunctions/pyproject.toml

@@ -4,7 +4,7 @@ description = "Azure Functions integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260521"
+version = "1.0.0b260604"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -22,8 +22,8 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.6.0,<2",
-    "agent-framework-durabletask>=1.0.0b260521,<2",
+    "agent-framework-core>=1.8.0,<2",
+    "agent-framework-durabletask>=1.0.0b260604,<2",
     "azure-functions>=1.24.0,<2",
     "azure-functions-durable>=1.3.1,<2",
 ]

python/packages/bedrock/agent_framework_bedrock/_chat_client.py

@@ -795,10 +795,7 @@ class BedrockChatClient(
             schema = copy.deepcopy(schema_src)
         else:
             if not isinstance(response_format, type) or not issubclass(response_format, BaseModel):
-                raise TypeError(
-                    "response_format must be None, a dict JSON schema, "
-                    "or a Pydantic BaseModel subclass."
-                )
+                raise TypeError("response_format must be None, a dict JSON schema, or a Pydantic BaseModel subclass.")
             # response_format is a Pydantic model class
             schema = response_format.model_json_schema()
             name = response_format.__name__
@@ -817,9 +814,7 @@ class BedrockChatClient(
         return {
             "textFormat": {
                 "type": "json_schema",
-                "structure": {
-                    "jsonSchema": json_schema
-                },
+                "structure": {"jsonSchema": json_schema},
             }
         }
 
@@ -840,9 +835,7 @@ class BedrockChatClient(
                 if node_id in visited:
                     return
                 visited.add(node_id)
-                if node.get("type") == "object" or (
-                    "properties" in node and "type" not in node
-                ):
+                if node.get("type") == "object" or ("properties" in node and "type" not in node):
                     existing = node.get("additionalProperties")
                     if existing is None or existing is True:
                         node["additionalProperties"] = False

python/packages/bedrock/pyproject.toml

@@ -4,7 +4,7 @@ description = "Amazon Bedrock integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260521"
+version = "1.0.0b260604"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.6.0,<2",
+    "agent-framework-core>=1.8.0,<2",
     "boto3>=1.35.0,<2.0.0",
     "botocore>=1.35.0,<2.0.0",
 ]

python/packages/bedrock/tests/test_bedrock_structured_output.py

@@ -238,6 +238,7 @@ async def test_chat_response_value_populated_streaming() -> None:
 
 async def test_unsupported_model_validation_exception() -> None:
     """When a model doesn't support outputConfig, a clear error should be raised."""
+
     class _FailingStubBedrockRuntime:
         def converse(self, **kwargs: Any) -> dict[str, Any]:
             # Simulate botocore ClientError for ValidationException

python/packages/core/AGENTS.md

@@ -56,7 +56,7 @@ agent_framework/
 - **`AgentMiddleware`** - Intercepts agent `run()` calls
 - **`ChatMiddleware`** - Intercepts chat client `get_response()` calls
 - **`FunctionMiddleware`** - Intercepts function/tool invocations
-- **`AgentContext`** / **`ChatContext`** / **`FunctionInvocationContext`** - Context objects passed through middleware
+- **`AgentContext`** / **`ChatContext`** / **`FunctionInvocationContext`** - Context objects passed through middleware. A tool can declare a `FunctionInvocationContext` parameter to receive it; `context.tools` is the live, mutable tools list for the run, and `context.add_tools(...)` / `context.remove_tools(...)` enable progressive tool exposure (changes apply on the next function-calling iteration).
 
 ### Sessions (`_sessions.py`)
 
@@ -76,6 +76,19 @@ agent_framework/
 - **`SkillScriptRunner`** - Protocol for file-based script execution. Any callable matching `(skill, script, args) -> Any` satisfies it. Code-defined scripts do not use a runner.
 - **`SkillsProvider`** - Context provider (extends `ContextProvider`) that discovers file-based skills from `SKILL.md` files and/or accepts code-defined `Skill` instances. Follows progressive disclosure: advertise → load → read resources / run scripts.
 
+### Model Context Protocol (`_mcp.py`)
+
+- **`MCPTool`** - Base wrapper that owns the MCP `ClientSession` and exposes the remote server's tools as `FunctionTool`s.
+- **`MCPStdioTool`** / **`MCPStreamableHTTPTool`** / **`MCPWebsocketTool`** - Transport-specific subclasses.
+- **`MCPTaskOptions`** (experimental, `MCP_LONG_RUNNING_TASKS` feature, **frozen**) - Per-tool-instance options controlling the SEP-2663 long-running task lifecycle. When the server advertises a tool with `execution.taskSupport == "required"`, `MCPTool.call_tool` transparently routes through `call_tool_as_task`, which sends an augmented `tools/call`, polls `tasks/get` until terminal, and reinterprets `tasks/result` as a normal `CallToolResult`. Instances are immutable; replace via `MCPTool.task_options = MCPTaskOptions(...)`. Fields:
+  - `default_ttl: timedelta | None` — forwarded to the server as `params.task.ttl` (milliseconds). When `None`, the server's default applies.
+  - `cancel_remote_task_on_local_cancellation: bool = True` — only gates the `CancelledError` path. Abandonment paths (see below) always cancel.
+  - `max_task_wait: timedelta | None` — client-side deadline for the whole post-create lifecycle (poll + result fetch). When exceeded, raises `ToolExecutionException` and fires a best-effort `tasks/cancel`. `None` (default) means no client-side bound. Bounds sleeps, sends, AND reconnects via `asyncio.wait_for`.
+- **Permissive fallback**: servers that ignore the augmentation (return `CallToolResult` directly) or reject the unknown `task` field with `METHOD_NOT_FOUND` / `INVALID_PARAMS` fall back to the plain `session.call_tool(...)` path so legacy servers keep working. An unparseable success response (server accepted the augmented call but returned a payload that is neither `CreateTaskResult` nor `CallToolResult`) **does not** fall back — it raises `ToolExecutionException` to avoid double-executing a side-effecting tool.
+- **Submit-vs-track reconnect policy**: a dropped connection before a `task_id` is known raises `ToolExecutionException("connection lost; task state unknown")` without re-issuing the augmented `tools/call`, so a server that accepted the request but lost the response cannot be made to start the same operation twice; once a `task_id` exists, `tasks/get` / `tasks/result` reconnect once and retry against the same id (a shared `_send_with_one_reconnect` helper).
+- **Cancel-on-abandonment vs terminal failure**: any path where the remote task may still be running (max-wait exceeded, hard `McpError` in poll, malformed `tasks/get`, second connection loss in poll/fetch, reconnect failure) fires best-effort `tasks/cancel` before raising. Terminal failures (`failed`/`cancelled`/`input_required` server-side, `completed+isError`, malformed `tasks/result` after server completed) do **not** cancel — the server is already done. `_MCPTaskAbandoned` is the private marker distinguishing the two.
+- **Transient poll retry**: a slow `tasks/get` that surfaces as `McpError(code=408 REQUEST_TIMEOUT)` is retried (bounded by `max_task_wait`). All other non-connection `McpError`s during poll are treated as abandonment. `tasks/result` does not get transient retry — the server has already completed, so a slow payload fetch is anomalous.
+
 ### File Access Harness (`_harness/_file_access.py`)
 
 - **`AgentFileStore`** - Abstract async store backing the file-access harness. Implementations expose `write_file`, `read_file`, `delete_file`, `list_files`, `file_exists`, `search_files`, and `create_directory` over forward-slash relative paths.

python/packages/core/agent_framework/__init__.py

@@ -124,7 +124,7 @@ from ._harness._todo import (
     TodoSessionStore,
     TodoStore,
 )
-from ._mcp import MCPStdioTool, MCPStreamableHTTPTool, MCPWebsocketTool
+from ._mcp import MCPStdioTool, MCPStreamableHTTPTool, MCPTaskOptions, MCPWebsocketTool
 from ._middleware import (
     AgentContext,
     AgentMiddleware,
@@ -168,6 +168,9 @@ from ._skills import (
     InlineSkillResource,
     InlineSkillScript,
     InMemorySkillsSource,
+    MCPSkill,
+    MCPSkillResource,
+    MCPSkillsSource,
     Skill,
     SkillFrontmatter,
     SkillResource,
@@ -441,8 +444,12 @@ __all__ = [
     "InlineSkillResource",
     "InlineSkillScript",
     "LocalEvaluator",
+    "MCPSkill",
+    "MCPSkillResource",
+    "MCPSkillsSource",
     "MCPStdioTool",
     "MCPStreamableHTTPTool",
+    "MCPTaskOptions",
     "MCPWebsocketTool",
     "MemoryContextProvider",
     "MemoryFileStore",

python/packages/core/agent_framework/_clients.py

@@ -380,8 +380,15 @@ class BaseChatClient(SerializationMixin, ABC, Generic[OptionsCoT]):
             return prepared_messages
         from ._compaction import apply_compaction
 
+        # Compact the caller's list in place when possible. A compaction operation has
+        # two halves: exclusion flags (mutated on shared Message objects) and inserted
+        # summary messages. Operating on the original list keeps both halves on the list
+        # the function-invocation tool loop reuses across iterations; otherwise inserted
+        # summaries would be lost on a throwaway copy while exclusions persisted, silently
+        # dropping older groups (issue #4991).
+        working_messages = messages if isinstance(messages, list) else prepared_messages
         return await apply_compaction(
-            prepared_messages,
+            working_messages,
             strategy=compaction_strategy,
             tokenizer=tokenizer,
         )

python/packages/core/agent_framework/_compaction.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import json
 import logging
-from collections.abc import Mapping, Sequence
+from collections.abc import Iterable, Mapping, Sequence
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -92,10 +92,23 @@ def _is_reasoning_only_assistant(message: Message) -> bool:
     return all(content.type == "text_reasoning" for content in message.contents)
 
 
-def _ensure_message_ids(messages: list[Message]) -> None:
+def _ensure_message_ids(
+    messages: list[Message], *, id_offset: int = 0, reserved_ids: Iterable[str] | None = None
+) -> None:
+    existing_ids: set[str] = set(reserved_ids) if reserved_ids is not None else set()
+    existing_ids.update(message.message_id for message in messages if message.message_id)
     for index, message in enumerate(messages):
-        if not message.message_id:
-            message.message_id = f"msg_{index}"
+        if message.message_id:
+            continue
+        candidate = f"msg_{id_offset + index}"
+        if candidate in existing_ids:
+            counter = id_offset + len(messages)
+            candidate = f"msg_{counter}"
+            while candidate in existing_ids:
+                counter += 1
+                candidate = f"msg_{counter}"
+        message.message_id = candidate
+        existing_ids.add(candidate)
 
 
 def _group_id_for(message: Message, group_index: int) -> str:
@@ -104,14 +117,27 @@ def _group_id_for(message: Message, group_index: int) -> str:
     return f"group_index_{group_index}"
 
 
-def group_messages(messages: list[Message]) -> list[dict[str, Any]]:
+def group_messages(
+    messages: list[Message], *, id_offset: int = 0, reserved_ids: Iterable[str] | None = None
+) -> list[dict[str, Any]]:
     """Compute group spans and metadata for annotation.
 
+    Args:
+        messages: The messages (or a slice of them) to group.
+
+    Keyword Args:
+        id_offset: Absolute starting index used when auto-assigning ``message_id``
+            values, so incremental annotation of a list slice produces ids that
+            stay unique across the full list.
+        reserved_ids: Message ids that already exist outside ``messages`` (for
+            example in a preserved prefix). Auto-assigned ids are guaranteed not
+            to collide with these, preventing duplicate ids across the full list.
+
     Returns:
         Ordered list of lightweight span dicts with keys:
         ``group_id``, ``kind``, ``start_index``, ``end_index``, ``has_reasoning``.
     """
-    _ensure_message_ids(messages)
+    _ensure_message_ids(messages, id_offset=id_offset, reserved_ids=reserved_ids)
     spans: list[dict[str, Any]] = []
     i = 0
     group_index = 0
@@ -439,7 +465,8 @@ def annotate_message_groups(
         if previous_group_index is not None:
             group_index_offset = previous_group_index + 1
 
-    spans = group_messages(messages[start_index:])
+    reserved_ids = {message.message_id for message in messages[:start_index] if message.message_id}
+    spans = group_messages(messages[start_index:], id_offset=start_index, reserved_ids=reserved_ids)
     for span_index, span in enumerate(spans):
         group_id = str(span["group_id"])
         kind = _coerce_group_kind(span["kind"])

python/packages/core/agent_framework/_feature_stage.py

@@ -58,6 +58,9 @@ class ExperimentalFeature(str, Enum):
     FOUNDRY_PREVIEW_TOOLS = "FOUNDRY_PREVIEW_TOOLS"
     FUNCTIONAL_WORKFLOWS = "FUNCTIONAL_WORKFLOWS"
     HARNESS = "HARNESS"
+    MCP_LONG_RUNNING_TASKS = "MCP_LONG_RUNNING_TASKS"
+    MCP_SKILLS = "MCP_SKILLS"
+    PROGRESSIVE_TOOLS = "PROGRESSIVE_TOOLS"
     SKILLS = "SKILLS"
     TO_PROMPT_AGENT = "TO_PROMPT_AGENT"
 

python/packages/core/agent_framework/_harness/_background_agents.py

@@ -349,6 +349,8 @@ class BackgroundAgentsProvider(ContextProvider):
             _save_provider_state(session, provider_state, source_id=source_id)
             return f"Background task {task_id} started on agent '{agent_name}'."
 
+        background_agents_start_task._invoke_sync_on_event_loop = True  # pyright: ignore[reportPrivateUsage]
+
         @tool(name="background_agents_wait_for_first_completion", approval_mode="never_require")
         async def background_agents_wait_for_first_completion(task_ids: list[int]) -> str:
             """Block until the first of the specified background tasks completes. Returns the completed task's ID."""
@@ -471,6 +473,8 @@ class BackgroundAgentsProvider(ContextProvider):
             _save_provider_state(session, provider_state, source_id=source_id)
             return f"Task {task_id} continued with new input."
 
+        background_agents_continue_task._invoke_sync_on_event_loop = True  # pyright: ignore[reportPrivateUsage]
+
         @tool(name="background_agents_clear_completed_task", approval_mode="never_require")
         def background_agents_clear_completed_task(task_id: int) -> str:
             """Remove a completed or failed task and release its session to free memory."""

python/packages/core/agent_framework/_middleware.py

@@ -11,6 +11,7 @@ from enum import Enum
 from typing import TYPE_CHECKING, Any, Generic, Literal, TypeAlias, cast, overload
 
 from ._clients import SupportsChatGetResponse
+from ._feature_stage import ExperimentalFeature, experimental
 from ._types import (
     AgentResponse,
     AgentResponseUpdate,
@@ -214,6 +215,12 @@ class FunctionInvocationContext:
         result: Function execution result. Can be observed after calling ``call_next()``
                 to see the actual execution result or can be set to override the execution result.
         kwargs: Additional runtime keyword arguments forwarded to the function invocation.
+        tools: The live, mutable list of tools available to the model for the current
+                agent run, or ``None`` when the function is invoked outside of a
+                function-calling loop (for example via ``FunctionTool.invoke`` directly).
+                Tools can add or remove tools during execution using :meth:`add_tools`
+                and :meth:`remove_tools` (progressive tool exposure). Mutations take
+                effect on the **next** model iteration, not the in-flight batch.
 
     Examples:
         .. code-block:: python
@@ -232,6 +239,18 @@ class FunctionInvocationContext:
 
                     # Continue execution
                     await call_next()
+
+        Progressive tool exposure from inside a tool:
+
+        .. code-block:: python
+
+            from agent_framework import FunctionInvocationContext, tool
+
+
+            @tool(approval_mode="never_require")
+            def load_math_tools(ctx: FunctionInvocationContext) -> str:
+                ctx.add_tools([factorial, fibonacci])
+                return "Math tools are now available."
     """
 
     def __init__(
@@ -242,6 +261,7 @@ class FunctionInvocationContext:
         metadata: Mapping[str, Any] | None = None,
         result: Any = None,
         kwargs: Mapping[str, Any] | None = None,
+        tools: list[ToolTypes] | None = None,
     ) -> None:
         """Initialize the FunctionInvocationContext.
 
@@ -252,6 +272,9 @@ class FunctionInvocationContext:
             metadata: Metadata dictionary for sharing data between function middleware.
             result: Function execution result.
             kwargs: Additional runtime keyword arguments forwarded to the function invocation.
+            tools: The live, mutable list of tools for the current agent run. When provided,
+                this is the same list object the model sees on the next iteration, so
+                appending or removing tools changes the model's available tools.
         """
         self.function = function
         self.arguments = arguments
@@ -259,6 +282,96 @@ class FunctionInvocationContext:
         self.metadata: dict[str, Any] = dict(metadata) if metadata is not None else {}
         self.result = result
         self.kwargs: dict[str, Any] = dict(kwargs) if kwargs is not None else {}
+        self.tools = tools
+
+    @experimental(feature_id=ExperimentalFeature.PROGRESSIVE_TOOLS)
+    def add_tools(
+        self,
+        tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]],
+    ) -> None:
+        """Add one or more tools to the current agent run (progressive tool exposure).
+
+        Callable inputs are converted to :class:`FunctionTool`, and tool collections are
+        flattened, using the same normalization as the rest of the framework. Added tools
+        become available to the model on the **next** iteration of the function-calling
+        loop; they do not affect tool calls already requested in the in-flight batch.
+
+        Adding a tool whose name already exists is a no-op when it is the same object, and
+        raises ``ValueError`` when it is a different object with a duplicate name.
+
+        Args:
+            tools: A single tool/callable or a sequence of tools/callables to add.
+
+        Raises:
+            RuntimeError: If the context has no live tools list (for example when the
+                function is invoked outside of a function-calling loop).
+            ValueError: If a different tool with a duplicate name is added.
+        """
+        from ._tools import _append_unique_tools, normalize_tools  # type: ignore[reportPrivateUsage]
+
+        if self.tools is None:
+            raise RuntimeError(
+                "Cannot add tools: this FunctionInvocationContext is not bound to a live "
+                "agent run. add_tools is only available for functions invoked within an "
+                "agent's function-calling loop."
+            )
+        # Validate the whole batch against a throwaway copy first, so a duplicate-name
+        # clash partway through the batch raises before the live tool list is mutated
+        # (all-or-nothing semantics).
+        merged = _append_unique_tools(list(self.tools), normalize_tools(tools))
+        self.tools[:] = merged
+
+    @experimental(feature_id=ExperimentalFeature.PROGRESSIVE_TOOLS)
+    def remove_tools(
+        self,
+        tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | str | Sequence[str],
+    ) -> None:
+        """Remove one or more tools from the current agent run (progressive tool exposure).
+
+        Tools may be specified by name, by tool object, or by the original callable. Names
+        that are not currently present are ignored. Removals take effect on the **next**
+        iteration of the function-calling loop; tool calls already requested in the
+        in-flight batch still execute.
+
+        Args:
+            tools: A tool name, tool/callable, or a sequence of any of these to remove.
+
+        Raises:
+            RuntimeError: If the context has no live tools list (for example when the
+                function is invoked outside of a function-calling loop).
+        """
+        from ._tools import _get_tool_name, normalize_tools  # type: ignore[reportPrivateUsage]
+
+        if self.tools is None:
+            raise RuntimeError(
+                "Cannot remove tools: this FunctionInvocationContext is not bound to a live "
+                "agent run. remove_tools is only available for functions invoked within an "
+                "agent's function-calling loop."
+            )
+
+        names_to_remove: set[str] = set()
+        raw_items: list[Any]
+        if isinstance(tools, str):
+            raw_items = [tools]
+        elif isinstance(tools, Sequence) and not isinstance(tools, (bytes, bytearray)):
+            raw_items = list(cast("Sequence[Any]", tools))
+        else:
+            raw_items = [tools]
+        for item in raw_items:
+            if isinstance(item, str):
+                names_to_remove.add(item)
+                continue
+            for normalized in normalize_tools(item):
+                if name := _get_tool_name(normalized):  # type: ignore[reportPrivateUsage]
+                    names_to_remove.add(name)
+
+        if not names_to_remove:
+            return
+        self.tools[:] = [
+            tool
+            for tool in self.tools
+            if _get_tool_name(tool) not in names_to_remove  # type: ignore[reportPrivateUsage]
+        ]
 
 
 class ChatContext:

python/packages/core/agent_framework/_skills.py

@@ -44,6 +44,7 @@ Only use skills from trusted sources.
 from __future__ import annotations
 
 import asyncio
+import base64
 import inspect
 import json
 import logging
@@ -60,6 +61,10 @@ from ._sessions import ContextProvider
 from ._tools import FunctionTool
 
 if TYPE_CHECKING:
+    from mcp.client.session import ClientSession
+    from mcp.types import ReadResourceResult
+    from pydantic import AnyUrl
+
     from ._agents import SupportsAgentRun
     from ._sessions import AgentSession, SessionContext
 
@@ -3285,4 +3290,443 @@ class AggregatingSkillsSource(SkillsSource):
         return result
 
 
+# region MCP Skills
+
+
+def _mcp_any_url(uri: str) -> AnyUrl:
+    """Convert a string URI to a :class:`pydantic.AnyUrl` for MCP client calls."""
+    from pydantic import AnyUrl as _AnyUrl
+
+    return _AnyUrl(uri)
+
+
+def _is_mcp_resource_not_found(ex: Exception) -> bool:
+    """Return ``True`` when *ex* is an :class:`McpError` indicating a missing resource.
+
+    Two codes are treated as "not found":
+
+    * ``-32002`` — the MCP-spec "Resource not found" code returned by a
+      compliant server when the URI does not exist. Not exported as a
+      constant from ``mcp.types`` but defined by the resources subprotocol.
+    * ``METHOD_NOT_FOUND`` (``-32601``) — the server does not implement
+      ``resources/read`` at all, which for the skills source is functionally
+      equivalent to "no skills available."
+
+    All other codes — ``INVALID_PARAMS``, ``INTERNAL_ERROR``, ``PARSE_ERROR``,
+    ``CONNECTION_CLOSED``, auth rejections, and generic handler errors
+    (code ``0``) — are treated as real failures so that a misconfigured
+    token or crashing server is not silently mistaken for "the server has no
+    skills."
+    """
+    from mcp.shared.exceptions import McpError as _McpError
+
+    if not isinstance(ex, _McpError):
+        return False
+    from mcp.types import METHOD_NOT_FOUND as _METHOD_NOT_FOUND
+
+    return ex.error.code in {-32002, _METHOD_NOT_FOUND}
+
+
+def _mcp_join_text(result: ReadResourceResult) -> str:
+    """Join all :class:`TextResourceContents` items in a result into a single string."""
+    from mcp.types import TextResourceContents as _TextResourceContents
+
+    return "\n".join(c.text for c in result.contents if isinstance(c, _TextResourceContents))
+
+
+class _McpSkillIndexEntry:  # noqa: B903
+    """A single entry in the ``skill://index.json`` discovery document.
+
+    All fields are optional to support lenient deserialization; callers
+    validate required fields before use.
+    """
+
+    def __init__(
+        self,
+        *,
+        name: str | None = None,
+        type: str | None = None,
+        description: str | None = None,
+        url: str | None = None,
+        digest: str | None = None,
+    ) -> None:
+        self.name = name
+        self.type = type
+        self.description = description
+        self.url = url
+        self.digest = digest
+
+
+class _McpSkillIndex:
+    """DTO for the ``skill://index.json`` discovery document.
+
+    Represents the Agent Skills Discovery v0.2.0 schema as bound to MCP
+    by SEP-2640.
+    """
+
+    def __init__(
+        self,
+        *,
+        schema: str | None = None,
+        skills: list[_McpSkillIndexEntry] | None = None,
+    ) -> None:
+        self.schema = schema
+        self.skills: list[_McpSkillIndexEntry] = skills if skills is not None else []
+
+
+def _parse_mcp_skill_index(text: str) -> _McpSkillIndex:
+    """Parse a JSON string into a :class:`_McpSkillIndex`.
+
+    Args:
+        text: Raw JSON text from ``skill://index.json``.
+
+    Returns:
+        A populated :class:`_McpSkillIndex` instance.
+
+    Raises:
+        json.JSONDecodeError: If the text is not valid JSON.
+        ValueError: If the top-level value is not a JSON object.
+    """
+    raw: dict[str, Any] = json.loads(text)
+
+    if not isinstance(raw, dict):
+        raise ValueError("skill://index.json must be a JSON object")
+
+    entries: list[_McpSkillIndexEntry] = []
+
+    raw_skills: list[Any] = raw.get("skills") or []
+
+    for item in raw_skills:
+        if isinstance(item, dict):
+            d = cast(dict[str, Any], item)
+
+            entries.append(
+                _McpSkillIndexEntry(
+                    name=d.get("name"),
+                    type=d.get("type"),
+                    description=d.get("description"),
+                    url=d.get("url"),
+                    digest=d.get("digest"),
+                )
+            )
+
+    return _McpSkillIndex(schema=raw.get("$schema"), skills=entries)
+
+
+@experimental(feature_id=ExperimentalFeature.MCP_SKILLS)
+class MCPSkillResource(SkillResource):
+    """A :class:`SkillResource` backed by content fetched from an MCP server.
+
+    The :class:`~mcp.types.ReadResourceResult` is fetched eagerly by
+    :meth:`MCPSkill.get_resource` at construction time; :meth:`read`
+    extracts text or binary content from the result.
+    """
+
+    def __init__(self, *, name: str, result: ReadResourceResult) -> None:
+        """Initialize an MCPSkillResource.
+
+        Args:
+            name: The resource name (e.g. a relative path or identifier).
+            result: The result returned by the MCP server's ``resources/read`` request.
+        """
+        super().__init__(name=name)
+        self._result = result
+
+    async def read(self, **kwargs: Any) -> Any:
+        """Read the resource content.
+
+        Returns:
+            A ``bytes`` object when the resource contains binary content,
+            a ``str`` when it contains text, or ``None`` when the server
+            returned no content blocks.
+        """
+        from mcp.types import BlobResourceContents, TextResourceContents
+
+        for content in self._result.contents:
+            if isinstance(content, BlobResourceContents):
+                blob = content.blob
+                # Strip data-URI prefix if present (some MCP servers send
+                # full data URIs instead of raw base64).
+                if blob.startswith("data:"):
+                    blob = blob.split(",", 1)[-1]
+                return base64.b64decode(blob)
+
+        text = "\n".join(c.text for c in self._result.contents if isinstance(c, TextResourceContents))
+        return text if text else None
+
+
+@experimental(feature_id=ExperimentalFeature.MCP_SKILLS)
+class MCPSkill(Skill):
+    """A :class:`Skill` discovered from an MCP server exposing the Agent Skills convention.
+
+    The skill is constructed from ``skill://index.json`` discovery metadata;
+    :meth:`get_content` fetches the full ``SKILL.md`` content from the MCP
+    server on demand via ``resources/read``.
+
+    Per SEP-2640, resources referenced inside SKILL.md are fetched on demand
+     via the originating MCP server: :meth:`get_resource` resolves a relative
+    resource name against the skill's root URI, issues a ``resources/read``
+     request, and returns an :class:`MCPSkillResource` with pre-fetched content.
+    """
+
+    _SKILL_MD_SUFFIX: Final[str] = "SKILL.md"
+
+    def __init__(
+        self,
+        frontmatter: SkillFrontmatter,
+        skill_md_uri: str,
+        client: ClientSession,
+    ) -> None:
+        """Initialize an MCPSkill.
+
+        Args:
+            frontmatter: The parsed frontmatter metadata for this skill.
+            skill_md_uri: The full MCP resource URI of the ``SKILL.md`` resource
+                (e.g. ``skill://unit-converter/SKILL.md``). The skill's root URI
+                is derived by stripping the trailing ``SKILL.md`` segment.
+            client: The MCP client session used to fetch resources on demand.
+        """
+        self._frontmatter = frontmatter
+        self._skill_md_uri = skill_md_uri
+        self._skill_root_uri = self._compute_skill_root_uri(skill_md_uri)
+        self._client = client
+        self._content: str | None = None
+
+    @property
+    def frontmatter(self) -> SkillFrontmatter:
+        """The L1 discovery metadata for this skill."""
+        return self._frontmatter
+
+    async def get_content(self) -> str:
+        """Get the full SKILL.md content from the MCP server.
+
+        Fetches the content via ``resources/read`` on the first call and
+        caches the result for subsequent calls.
+
+        Returns:
+            The SKILL.md content string.
+
+        Raises:
+            ValueError: If the MCP server returned no text content for the
+                SKILL.md resource.
+        """
+        if self._content is not None:
+            return self._content
+
+        result = await self._client.read_resource(_mcp_any_url(self._skill_md_uri))
+        text = _mcp_join_text(result)
+        if not text:
+            raise ValueError(
+                f"The MCP server returned no text content for SKILL.md resource '{self._skill_md_uri}'."
+            )
+        self._content = text
+        return text
+
+    async def get_resource(self, name: str) -> SkillResource | None:
+        """Get a sibling resource by name from the MCP server.
+
+        Resolves *name* as a relative path against the skill's root URI,
+        issues a ``resources/read`` request to the MCP server, and returns
+        an :class:`MCPSkillResource` with the pre-fetched content.
+
+        Args:
+            name: The resource name (e.g. ``references/checklist.md``).
+
+        Returns:
+            An :class:`MCPSkillResource`, or ``None`` when the name is empty
+            or the resource does not exist on the server.
+        """
+        if not name or not name.strip():
+            return None
+
+        normalized = self._validate_resource_name(name)
+        if normalized is None:
+            return None
+
+        uri = self._skill_root_uri + normalized
+        try:
+            result = await self._client.read_resource(_mcp_any_url(uri))
+        except Exception as ex:
+            if _is_mcp_resource_not_found(ex):
+                logger.debug("MCP resource '%s' not available: %s", uri, ex)
+                return None
+            raise
+
+        return MCPSkillResource(name=name, result=result)
+
+    @staticmethod
+    def _validate_resource_name(name: str) -> str | None:
+        """Validate a resource name and return the normalized form.
+
+        Defense in depth: refuses names that could escape the skill root
+        (absolute paths, embedded URI schemes, parent-traversal segments).
+        The MCP server is the authority on URI resolution, but rejecting
+        obviously unsafe shapes client-side avoids leaking escape attempts
+        upstream.
+
+        Args:
+            name: The raw resource name to validate.
+
+        Returns:
+            The normalized name with backslashes replaced by forward slashes,
+            or ``None`` if the name is unsafe.
+        """
+        normalized = name.replace("\\", "/")
+        if (
+            normalized.startswith("/")
+            or "://" in normalized
+            or any(seg == ".." for seg in normalized.split("/"))
+        ):
+            logger.debug("Rejecting resource name with unsafe path components: %r", name)
+            return None
+        return normalized
+
+    @staticmethod
+    def _compute_skill_root_uri(skill_md_uri: str) -> str:
+        """Strip the trailing ``SKILL.md`` from the URI to produce the skill root.
+
+        If the URI doesn't end with ``SKILL.md``, ensures it ends with a
+        trailing slash.
+        """
+        if skill_md_uri.endswith(MCPSkill._SKILL_MD_SUFFIX):
+            return skill_md_uri[: -len(MCPSkill._SKILL_MD_SUFFIX)]
+        if skill_md_uri.endswith("/"):
+            return skill_md_uri
+        return skill_md_uri + "/"
+
+
+@experimental(feature_id=ExperimentalFeature.MCP_SKILLS)
+class MCPSkillsSource(SkillsSource):
+    """A :class:`SkillsSource` that discovers Agent Skills served over MCP.
+
+    Discovery follows the SEP-2640 recommended approach: the source reads
+    the well-known ``skill://index.json`` resource and constructs one
+    :class:`MCPSkill` per ``skill-md`` entry directly from the entry's
+    ``name``, ``description``, and ``url`` fields.
+
+    The referenced ``SKILL.md`` resource is **not** read during discovery;
+    the host fetches its body on demand via ``resources/read`` when the
+    skill content is needed.
+
+    Only index entries of type ``skill-md`` are supported; entries of any
+    other type are silently skipped.
+
+    If ``skill://index.json`` is absent, unreadable, empty, or fails to
+    parse, this source returns an empty list.
+
+    Examples:
+        .. code-block:: python
+
+            from mcp.client.session import ClientSession
+
+            source = MCPSkillsSource(client=session)
+            skills = await source.get_skills()
+    """
+
+    _INDEX_URI: Final[str] = "skill://index.json"
+    _SKILL_MD_TYPE: Final[str] = "skill-md"
+
+    def __init__(self, client: ClientSession) -> None:
+        """Initialize an MCPSkillsSource.
+
+        Args:
+            client: An MCP client session connected to a server that
+                exposes Agent Skills resources.
+        """
+        self._client = client
+
+    async def get_skills(self) -> list[Skill]:
+        """Discover and return skills from the MCP server.
+
+        Reads ``skill://index.json``, parses it, and creates an
+        :class:`MCPSkill` for each valid ``skill-md`` entry.
+
+        Returns:
+            A list of discovered :class:`MCPSkill` instances.
+        """
+        index = await self._try_read_index()
+        if index is None:
+            return []
+
+        skills: list[Skill] = []
+        for entry in index.skills:
+            result = self._try_create_skill(entry)
+            if result is not None:
+                skills.append(result)
+                logger.info("Loaded MCP skill: %s", result.frontmatter.name)
+            else:
+                logger.debug(
+                    "Skipping skill index entry '%s'",
+                    entry.name or "(unnamed)",
+                )
+
+        logger.info("Successfully loaded %d skills from MCP server", len(skills))
+        return skills
+
+    async def _try_read_index(self) -> _McpSkillIndex | None:
+        """Attempt to read and parse ``skill://index.json`` from the MCP server.
+
+        Returns:
+            A parsed :class:`_McpSkillIndex`, or ``None`` if the index is
+            absent, empty, or malformed.
+        """
+        try:
+            result = await self._client.read_resource(_mcp_any_url(self._INDEX_URI))
+        except Exception as ex:
+            if _is_mcp_resource_not_found(ex):
+                logger.debug("No skill://index.json resource available on MCP server: %s", ex)
+                return None
+            logger.warning("Failed to read skill://index.json from MCP server.", exc_info=True)
+            raise
+
+        index_text = _mcp_join_text(result)
+        if not index_text:
+            logger.debug("skill://index.json on MCP server returned empty/non-text contents")
+            return None
+
+        try:
+            return _parse_mcp_skill_index(index_text)
+        except (json.JSONDecodeError, ValueError):
+            logger.warning("Failed to parse skill://index.json JSON document.", exc_info=True)
+            return None
+
+    def _try_create_skill(self, entry: _McpSkillIndexEntry) -> MCPSkill | None:
+        """Attempt to create an :class:`MCPSkill` from an index entry.
+
+        Args:
+            entry: A single entry from the skill index.
+
+        Returns:
+            An :class:`MCPSkill` if the entry is valid, or ``None`` if the
+            entry should be skipped.
+        """
+        if entry.type != self._SKILL_MD_TYPE:
+            logger.debug(
+                "Skipping entry '%s': unsupported type '%s'",
+                entry.name or "(unnamed)",
+                entry.type or "(none)",
+            )
+            return None
+
+        if not entry.name or not entry.name.strip():
+            logger.debug("Skipping entry: missing required 'name' field")
+            return None
+
+        if not entry.description or not entry.description.strip():
+            logger.debug("Skipping entry '%s': missing required 'description' field", entry.name)
+            return None
+
+        if not entry.url or not entry.url.strip():
+            logger.debug("Skipping entry '%s': missing required 'url' field", entry.name)
+            return None
+
+        try:
+            fm = SkillFrontmatter(name=entry.name, description=entry.description)
+        except ValueError as ex:
+            logger.debug("Skipping entry '%s': invalid metadata: %s", entry.name, ex)
+            return None
+
+        return MCPSkill(frontmatter=fm, skill_md_uri=entry.url, client=self._client)
+
+
 # endregion

python/packages/core/agent_framework/_tools.py

@@ -292,6 +292,7 @@ class FunctionTool(SerializationMixin):
         "_cached_parameters",
         "_input_schema",
         "_schema_supplied",
+        "_invoke_sync_on_event_loop",
     }
 
     def __init__(
@@ -366,6 +367,7 @@ class FunctionTool(SerializationMixin):
         self.description = description
         self.kind = kind
         self.additional_properties = additional_properties
+        self._invoke_sync_on_event_loop = False
         for key, value in kwargs.items():
             setattr(self, key, value)
 
@@ -537,6 +539,16 @@ class FunctionTool(SerializationMixin):
             self.invocation_exception_count += 1
             raise
 
+    async def _invoke_function(self, call_kwargs: Mapping[str, Any]) -> Any:
+        """Run sync tools off the event loop during async invocation."""
+        func = self.func.func if isinstance(self.func, FunctionTool) else self.func
+        if inspect.iscoroutinefunction(func) or getattr(self, "_invoke_sync_on_event_loop", False):
+            res = self.__call__(**call_kwargs)
+            return await res if inspect.isawaitable(res) else res
+
+        res = await asyncio.to_thread(self.__call__, **call_kwargs)
+        return await res if inspect.isawaitable(res) else res
+
     @overload
     async def invoke(
         self,
@@ -679,8 +691,7 @@ class FunctionTool(SerializationMixin):
         if not OBSERVABILITY_SETTINGS.ENABLED:  # type: ignore[name-defined]
             logger.info(f"Function name: {self.name}")
             logger.debug(f"Function arguments: {observable_kwargs}")
-            res = self.__call__(**call_kwargs)
-            result = await res if inspect.isawaitable(res) else res
+            result = await self._invoke_function(call_kwargs)
             if skip_parsing:
                 logger.info(f"Function {self.name} succeeded.")
                 logger.debug(f"Function result: {type(result).__name__}")
@@ -730,8 +741,7 @@ class FunctionTool(SerializationMixin):
             start_time_stamp = perf_counter()
             end_time_stamp: float | None = None
             try:
-                res = self.__call__(**call_kwargs)
-                result = await res if inspect.isawaitable(res) else res
+                result = await self._invoke_function(call_kwargs)
                 end_time_stamp = perf_counter()
             except Exception as exception:
                 end_time_stamp = perf_counter()
@@ -1418,6 +1428,7 @@ async def _auto_invoke_function(
     sequence_index: int | None = None,
     request_index: int | None = None,
     middleware_pipeline: FunctionMiddlewarePipeline | None = None,
+    live_tools: list[ToolTypes] | None = None,
 ) -> Content:
     """Invoke a function call requested by the agent, applying middleware that is defined.
 
@@ -1432,6 +1443,8 @@ async def _auto_invoke_function(
         sequence_index: The index of the function call in the sequence.
         request_index: The index of the request iteration.
         middleware_pipeline: Optional middleware pipeline to apply during execution.
+        live_tools: The live, mutable tools list for the current agent run, exposed on
+            the FunctionInvocationContext so tools can add/remove tools at runtime.
 
     Returns:
         The function result content.
@@ -1523,6 +1536,7 @@ async def _auto_invoke_function(
                     arguments=args,
                     session=invocation_session,
                     kwargs=runtime_kwargs.copy(),
+                    tools=live_tools,
                 )
             function_result = await tool.invoke(
                 arguments=args,
@@ -1537,6 +1551,10 @@ async def _auto_invoke_function(
         except UserInputRequiredException:
             raise
         except Exception as exc:
+            logger.warning(
+                f"Function '{tool.name}' raised an exception; returning an error result to the "
+                f"model. Set include_detailed_errors=True for the full detail. Exception: {exc!r}"
+            )
             message = "Error: Function failed."
             if config.get("include_detailed_errors", False):
                 message = f"{message} Exception: {exc}"
@@ -1552,6 +1570,7 @@ async def _auto_invoke_function(
         arguments=args,
         session=invocation_session,
         kwargs=runtime_kwargs.copy(),
+        tools=live_tools,
     )
 
     call_id = function_call_content.call_id
@@ -1608,6 +1627,10 @@ async def _auto_invoke_function(
     except UserInputRequiredException:
         raise
     except Exception as exc:
+        logger.warning(
+            f"Function '{tool.name}' raised an exception; returning an error result to the "
+            f"model. Set include_detailed_errors=True for the full detail. Exception: {exc!r}"
+        )
         message = "Error: Function failed."
         if config.get("include_detailed_errors", False):
             message = f"{message} Exception: {exc}"
@@ -1659,6 +1682,9 @@ async def _try_execute_function_calls(
     from ._types import Content
 
     tool_map = _get_tool_map(tools)
+    # The live tools list (when tools is the run-local list) is exposed on the
+    # FunctionInvocationContext so tools can add/remove tools during the run.
+    live_tools: list[ToolTypes] | None = cast("list[ToolTypes]", tools) if isinstance(tools, list) else None
     approval_tools = [tool_name for tool_name, tool in tool_map.items() if tool.approval_mode == "always_require"]
     logger.debug(
         "_try_execute_function_calls: tool_map keys=%s, approval_tools=%s",
@@ -1733,6 +1759,7 @@ async def _try_execute_function_calls(
                 request_index=attempt_idx,
                 middleware_pipeline=middleware_pipeline,
                 config=config,
+                live_tools=live_tools,
             )
             return (result, False)
         except MiddlewareTermination as exc:
@@ -2371,6 +2398,13 @@ class FunctionInvocationLayer(Generic[OptionsCoT]):
                 function_invocation_kwargs=function_invocation_kwargs,
                 client_kwargs=filtered_kwargs,
             )
+        # Establish a single, run-local mutable tools list so that tools can add or remove
+        # tools during the run (progressive tool exposure). A fresh list is created via
+        # normalize_tools so the caller's original tools container is never mutated, while
+        # the same list object is shared with the model (options["tools"]) and the tool map
+        # rebuilt on every loop iteration.
+        if mutable_options.get("tools"):
+            mutable_options["tools"] = normalize_tools(mutable_options["tools"])
         if not stream:
 
             async def _get_response() -> ChatResponse[Any]:

python/packages/core/agent_framework/_workflows/_agent.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import json
 import logging
 import sys
 import uuid
@@ -12,7 +11,6 @@ from datetime import datetime, timezone
 from typing import TYPE_CHECKING, Any, ClassVar, Literal, cast, overload
 
 from .._agents import BaseAgent
-from .._serialization import make_json_safe
 from .._sessions import (
     AgentSession,
     ContextProvider,
@@ -30,11 +28,12 @@ from .._types import (
     UsageDetails,
     add_usage_details,
 )
-from ..exceptions import AgentInvalidRequestException, AgentInvalidResponseException
+from ..exceptions import AgentException, AgentInvalidRequestException, AgentInvalidResponseException
 from ._checkpoint import CheckpointStorage
 from ._events import (
     AGENT_FORWARDED_EVENT_TYPES,
     WorkflowEvent,
+    WorkflowRunState,
 )
 from ._message_utils import normalize_messages_input
 from ._typing_utils import is_instance_of, is_type_compatible
@@ -59,27 +58,24 @@ class WorkflowAgent(BaseAgent):
     @dataclass
     class RequestInfoFunctionArgs:
         request_id: str
-        data: Any
+        request_event: WorkflowEvent
 
         def to_dict(self) -> dict[str, Any]:
-            return {"request_id": self.request_id, "data": make_json_safe(self.data)}
-
-        def to_json(self) -> str:
-            return json.dumps(self.to_dict())
+            return {"request_id": self.request_id, "request_event": self.request_event.to_dict()}
 
         @classmethod
         def from_dict(cls, payload: dict[str, Any]) -> WorkflowAgent.RequestInfoFunctionArgs:
-            return cls(request_id=payload.get("request_id", ""), data=payload.get("data"))
+            if "request_id" not in payload or "request_event" not in payload:
+                raise ValueError(
+                    "Invalid payload for RequestInfoFunctionArgs. 'request_id' and 'request_event' are required."
+                )
+            if not payload["request_id"]:
+                raise ValueError("request_id cannot be empty.")
 
-        @classmethod
-        def from_json(cls, raw: str) -> WorkflowAgent.RequestInfoFunctionArgs:
-            try:
-                parsed: Any = json.loads(raw)
-            except json.JSONDecodeError as exc:
-                raise ValueError(f"RequestInfoFunctionArgs JSON payload is malformed: {exc}") from exc
-            if not isinstance(parsed, dict):
-                raise ValueError("RequestInfoFunctionArgs JSON payload must decode to a mapping")
-            return cls.from_dict(cast(dict[str, Any], parsed))
+            return cls(
+                request_id=payload.get("request_id", ""),
+                request_event=WorkflowEvent.from_dict(payload.get("request_event", {})),
+            )
 
     def __init__(
         self,
@@ -129,16 +125,11 @@ class WorkflowAgent(BaseAgent):
             **kwargs,
         )
         self._workflow: Workflow = workflow
-        self._pending_requests: dict[str, WorkflowEvent[Any]] = {}
 
     @property
     def workflow(self) -> Workflow:
         return self._workflow
 
-    @property
-    def pending_requests(self) -> dict[str, WorkflowEvent[Any]]:
-        return self._pending_requests
-
     # region Run Methods
 
     @overload
@@ -182,7 +173,7 @@ class WorkflowAgent(BaseAgent):
 
         Args:
             messages: The message(s) to send to the workflow. Required for new runs,
-                should be None when resuming from checkpoint.
+                could be None if only restoring the underlying workflow from a checkpoint.
 
         Keyword Args:
             stream: If True, returns an async iterable of updates. If False (default),
@@ -416,101 +407,79 @@ class WorkflowAgent(BaseAgent):
         Yields:
             WorkflowEvent objects from the workflow execution.
         """
-        # Determine the execution mode based on state.
-        # The streaming flag controls the workflow's internal streaming mode,
-        # which affects executor behavior (e.g. AgentExecutor emits different event
-        # types in streaming vs non-streaming mode).
-        if bool(self.pending_requests):
-            function_responses = self._process_pending_requests(input_messages)
+        # Restore the workflow state if a checkpoint is provided
+        if checkpoint_id is not None:
+            if checkpoint_storage is None:
+                raise AgentInvalidRequestException("checkpoint_storage must be provided when checkpoint_id is provided")
+            logger.debug(f"Restoring workflow from checkpoint {checkpoint_id}")
+            # Restore the workflow from checkpoint
             if streaming:
-                async for event in self.workflow.run(
-                    responses=function_responses,
-                    stream=True,
-                    function_invocation_kwargs=function_invocation_kwargs,
-                    client_kwargs=client_kwargs,
-                ):
-                    yield event
-            else:
-                for event in await self.workflow.run(
-                    responses=function_responses,
-                    function_invocation_kwargs=function_invocation_kwargs,
-                    client_kwargs=client_kwargs,
-                ):
-                    yield event
-
-        elif checkpoint_id is not None:
-            # Restore the prior workflow state from the checkpoint. Shared
-            # state (e.g. accumulated conversation history maintained by the
-            # workflow's executors) survives across turns because Workflow.run
-            # no longer wipes state per call. Callers who want to deliver a
-            # new user message after restore should make a second
-            # `workflow.run(message=...)` call - they are NOT mutually
-            # exclusive on the same instance, but each must be its own call.
-            if streaming:
-                async for event in self.workflow.run(
+                async for _ in self.workflow.run(
                     stream=True,
                     checkpoint_id=checkpoint_id,
                     checkpoint_storage=checkpoint_storage,
+                ):
+                    pass
+            else:
+                _ = await self.workflow.run(
+                    checkpoint_id=checkpoint_id,
+                    checkpoint_storage=checkpoint_storage,
+                )
+            if not input_messages:
+                logger.info("No input messages provided; the workflow has been restored to the checkpoint state.")
+                return
+
+        final_state = self._workflow.status
+        logger.debug(f"Workflow state: {final_state}")
+
+        if final_state == WorkflowRunState.IDLE_WITH_PENDING_REQUESTS:
+            # Extract function responses from input messages, and ensure that
+            # only function responses are present in messages if there is any
+            # pending request.
+            # NOTE: It is possible that some pending requests are not fulfilled,
+            # and we will let the workflow to handle this -- the agent does not
+            # have an opinion on this.
+            function_responses = self._extract_function_responses(input_messages)
+            if streaming:
+                async for event in self.workflow.run(
+                    responses=function_responses,
+                    stream=True,
+                    checkpoint_storage=checkpoint_storage,
                     function_invocation_kwargs=function_invocation_kwargs,
                     client_kwargs=client_kwargs,
                 ):
                     yield event
             else:
                 for event in await self.workflow.run(
-                    checkpoint_id=checkpoint_id,
+                    responses=function_responses,
+                    checkpoint_storage=checkpoint_storage,
+                    function_invocation_kwargs=function_invocation_kwargs,
+                    client_kwargs=client_kwargs,
+                ):
+                    yield event
+        elif final_state == WorkflowRunState.IDLE:
+            if streaming:
+                async for event in self.workflow.run(
+                    message=input_messages,
+                    stream=True,
+                    checkpoint_storage=checkpoint_storage,
+                    function_invocation_kwargs=function_invocation_kwargs,
+                    client_kwargs=client_kwargs,
+                ):
+                    yield event
+            else:
+                for event in await self.workflow.run(
+                    message=input_messages,
                     checkpoint_storage=checkpoint_storage,
                     function_invocation_kwargs=function_invocation_kwargs,
                     client_kwargs=client_kwargs,
                 ):
                     yield event
-
         else:
-            if streaming:
-                async for event in self.workflow.run(
-                    message=input_messages,
-                    stream=True,
-                    checkpoint_storage=checkpoint_storage,
-                    function_invocation_kwargs=function_invocation_kwargs,
-                    client_kwargs=client_kwargs,
-                ):
-                    yield event
-            else:
-                for event in await self.workflow.run(
-                    message=input_messages,
-                    checkpoint_storage=checkpoint_storage,
-                    function_invocation_kwargs=function_invocation_kwargs,
-                    client_kwargs=client_kwargs,
-                ):
-                    yield event
+            raise AgentException(f"The underlying workflow is in an invalid state to restart: {final_state}.")
 
     # endregion Run Methods
 
-    def _process_pending_requests(self, input_messages: Sequence[Message]) -> dict[str, Any]:
-        """Process pending requests by extracting function responses and updating state.
-
-        Args:
-            input_messages: Input messages that may contain function responses.
-
-        Returns:
-            A dictionary mapping request IDs to their response data.
-        """
-        logger.info(f"Continuing workflow to address {len(self.pending_requests)} requests")
-
-        # Extract function responses from input messages, and ensure that
-        # only function responses are present in messages if there is any
-        # pending request.
-        function_responses = self._extract_function_responses(input_messages)
-
-        # Pop pending requests if fulfilled.
-        for request_id in list(self.pending_requests.keys()):
-            if request_id in function_responses:
-                self.pending_requests.pop(request_id)
-
-        # NOTE: It is possible that some pending requests are not fulfilled,
-        # and we will let the workflow to handle this -- the agent does not
-        # have an opinion on this.
-        return function_responses
-
     def _convert_workflow_events_to_agent_response(
         self,
         response_id: str,
@@ -528,10 +497,10 @@ class WorkflowAgent(BaseAgent):
 
         for output_event in output_events:
             if output_event.type == "request_info":
-                function_call, approval_request = self._process_request_info_event(output_event)
+                request_content = self._process_request_info_event(output_event)
                 messages.append(
                     Message(
-                        contents=[function_call, approval_request],
+                        contents=[request_content],
                         role="assistant",
                         author_name=output_event.source_executor_id,
                         message_id=str(uuid.uuid4()),
@@ -598,38 +567,6 @@ class WorkflowAgent(BaseAgent):
             raw_representation=raw_representations,
         )
 
-    def _process_request_info_event(
-        self,
-        event: WorkflowEvent[Any],
-    ) -> tuple[Content, Content]:
-        """Convert a request_info event to FunctionCallContent and FunctionApprovalRequestContent.
-
-        Args:
-            event: A WorkflowEvent with type='request_info'.
-
-        Returns:
-            A tuple of (FunctionCallContent, FunctionApprovalRequestContent).
-        """
-        request_id = event.request_id
-        if not request_id:
-            raise ValueError("request_info event must have a request_id")
-
-        self.pending_requests[request_id] = event
-
-        args = self.RequestInfoFunctionArgs(request_id=request_id, data=event.data).to_dict()
-
-        function_call = Content.from_function_call(
-            call_id=request_id,
-            name=self.REQUEST_INFO_FUNCTION_NAME,
-            arguments=args,
-        )
-        approval_request = Content.from_function_approval_request(
-            id=request_id,
-            function_call=function_call,
-            additional_properties={"request_id": request_id},
-        )
-        return function_call, approval_request
-
     def _convert_workflow_event_to_agent_response_updates(
         self,
         response_id: str,
@@ -731,85 +668,72 @@ class WorkflowAgent(BaseAgent):
             ]
 
         if event.type == "request_info":
-            # Store the pending request for later correlation
-            request_id = event.request_id
-            if not request_id:
-                raise ValueError("request_info event must have a request_id")
-
-            self.pending_requests[request_id] = event
-
-            args = self.RequestInfoFunctionArgs(request_id=request_id, data=event.data).to_dict()
-
-            function_call = Content.from_function_call(
-                call_id=request_id,
-                name=self.REQUEST_INFO_FUNCTION_NAME,
-                arguments=args,
-            )
-            approval_request = Content.from_function_approval_request(
-                id=request_id,
-                function_call=function_call,
-                additional_properties={"request_id": request_id},
-            )
+            request_content = self._process_request_info_event(event)
             return [
                 AgentResponseUpdate(
-                    contents=[function_call, approval_request],
+                    contents=[request_content],
                     role="assistant",
                     author_name=self.name,
                     response_id=response_id,
                     message_id=str(uuid.uuid4()),
                     created_at=datetime.now(tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ"),
+                    raw_representation=event,
                 )
             ]
 
         # Ignore workflow-internal events
         return []
 
+    def _process_request_info_event(
+        self,
+        event: WorkflowEvent[Any],
+    ) -> Content:
+        """Convert a request_info event to FunctionApprovalRequestContent.
+
+        Args:
+            event: A WorkflowEvent with type='request_info'.
+
+        Returns:
+            A content object representing the request info. The content can be a `function_approval_request`
+            or a `function_call` depending on the structure of the event data.
+
+        Note:
+            If the event data is already a FunctionApprovalRequestContent, it will be returned as-is.
+        """
+        if isinstance(event.data, Content) and event.data.user_input_request:
+            # Return the event data as-is if it's already a properly formed FunctionApprovalRequestContent
+            return event.data
+
+        request_id = event.request_id
+        args = self.RequestInfoFunctionArgs(request_id=request_id, request_event=event).to_dict()
+
+        return Content.from_function_call(
+            call_id=request_id,
+            name=self.REQUEST_INFO_FUNCTION_NAME,
+            arguments=args,
+        )
+
     def _extract_function_responses(self, input_messages: Sequence[Message]) -> dict[str, Any]:
-        """Extract function responses from input messages."""
+        """Extract function responses from input messages.
+
+        The responses are for pending requests that the workflow is waiting on, and
+        will be passed to the workflow. The pending requests are processed to either
+        `function_approval_request` or `function_call` content by `_process_request_info_event`.
+        """
         function_responses: dict[str, Any] = {}
         for message in input_messages:
             for content in message.contents:
                 if content.type == "function_approval_response":
-                    # Parse the function arguments to recover request payload
-                    arguments_payload = content.function_call.arguments  # type: ignore[attr-defined, union-attr]
-                    if isinstance(arguments_payload, str):
-                        try:
-                            parsed_args = self.RequestInfoFunctionArgs.from_json(arguments_payload)
-                        except ValueError as exc:
-                            raise AgentInvalidResponseException(
-                                "FunctionApprovalResponseContent arguments must decode to a mapping."
-                            ) from exc
-                    elif isinstance(arguments_payload, dict):
-                        parsed_args = self.RequestInfoFunctionArgs.from_dict(arguments_payload)
-                    else:
-                        raise AgentInvalidResponseException(
-                            "FunctionApprovalResponseContent arguments must be a mapping or JSON string."
-                        )
-
-                    request_id = parsed_args.request_id or content.id  # type: ignore[attr-defined]
-                    if not content.approved:  # type: ignore[attr-defined]
-                        raise AgentInvalidResponseException(f"Request '{request_id}' was not approved by the caller.")
-
-                    if request_id in self.pending_requests:
-                        function_responses[request_id] = parsed_args.data
-                    elif bool(self.pending_requests):
-                        raise AgentInvalidRequestException(
-                            "Only responses for pending requests are allowed when there are outstanding approvals."
-                        )
+                    request_id: str = content.id  # type: ignore[assignment]
+                    function_responses[request_id] = content
                 elif content.type == "function_result":
-                    request_id = content.call_id  # type: ignore[attr-defined]
-                    if request_id in self.pending_requests:
-                        response_data = content.result if hasattr(content, "result") else str(content)  # type: ignore[attr-defined]
-                        function_responses[request_id] = response_data
-                    elif bool(self.pending_requests):
-                        raise AgentInvalidRequestException(
-                            "Only function responses for pending requests are allowed while requests are outstanding."
-                        )
+                    response_data = content.result if hasattr(content, "result") else str(content)  # type: ignore[attr-defined]
+                    function_responses[content.call_id] = response_data  # type: ignore
                 else:
-                    if bool(self.pending_requests):
-                        raise AgentInvalidResponseException(
-                            "Unexpected content type while awaiting request info responses."
-                        )
+                    raise AgentInvalidResponseException(
+                        "Unexpected content type while awaiting request info responses."
+                    )
+
         return function_responses
 
     def _extract_contents(self, data: Any) -> list[Content]:

python/packages/core/agent_framework/_workflows/_agent_executor.py

@@ -429,15 +429,30 @@ class AgentExecutor(Executor):
             function_invocation_kwargs=function_invocation_kwargs,
             client_kwargs=client_kwargs,
         )
-        await ctx.yield_output(response)
 
         # Handle any user input requests
         if response.user_input_requests:
+            user_input_request_count = len(response.user_input_requests)
+            total_message_content_count = sum(len(msg.contents) for msg in response.messages)
+            if user_input_request_count != total_message_content_count:
+                logger.warning(
+                    "Response %s contains %d user input requests but total message contents are %d. "
+                    "This indicates the response contains both user input requests and message contents. "
+                    "Double check if this is the intended behavior, as non user input request contents in "
+                    "this response will not be emitted.",
+                    response.response_id,
+                    user_input_request_count,
+                    total_message_content_count,
+                )
             for user_input_request in response.user_input_requests:
                 self._pending_agent_requests[user_input_request.id] = user_input_request  # type: ignore[index]
-                await ctx.request_info(user_input_request, Content)
+                await ctx.request_info(user_input_request, Content, request_id=user_input_request.id)
             return None
 
+        # Only yield output if the response is complete and not waiting for user input.
+        # This is to avoid emitting two events of different types ('output' and 'request_info')
+        # that carry the same payload.
+        await ctx.yield_output(response)
         return response
 
     async def _run_agent_streaming(self, ctx: WorkflowContext[Never, AgentResponseUpdate]) -> AgentResponse | None:
@@ -472,9 +487,25 @@ class AgentExecutor(Executor):
         )
         async for update in stream:
             updates.append(update)
-            await ctx.yield_output(update)
             if update.user_input_requests:
+                user_input_request_count = len(update.user_input_requests)
+                total_message_content_count = len(update.contents)
+                if user_input_request_count != total_message_content_count:
+                    logger.warning(
+                        "Response update %s contains %d user input requests but total message contents are %d. "
+                        "This indicates the response update contains both user input requests and message contents. "
+                        "Double check if this is the intended behavior, as non user input request contents will "
+                        "not be emitted.",
+                        update.response_id,
+                        user_input_request_count,
+                        total_message_content_count,
+                    )
                 streamed_user_input_requests.extend(update.user_input_requests)
+            else:
+                # Only yield output events for updates that do not contain user input requests.
+                # This is to avoid emitting two events of different types ('output' and 'request_info')
+                # that carry the same payload.
+                await ctx.yield_output(update)
 
         # Prefer stream finalization when available so result hooks run
         # (e.g., thread conversation updates). Fall back to reconstructing from updates
@@ -509,7 +540,7 @@ class AgentExecutor(Executor):
         if user_input_requests:
             for user_input_request in user_input_requests:
                 self._pending_agent_requests[user_input_request.id] = user_input_request  # type: ignore[index]
-                await ctx.request_info(user_input_request, Content)
+                await ctx.request_info(user_input_request, Content, request_id=user_input_request.id)
             return None
 
         return response

python/packages/core/agent_framework/_workflows/_checkpoint_encoding.py

@@ -13,35 +13,6 @@ during deserialization.  The default built-in safe set covers common Python
 value types (primitives, datetime, uuid, ...), all ``agent_framework`` internal
 types, and all ``openai.types`` types.  Callers can extend the set by passing
 additional ``"module:qualname"`` strings.
-
-Security Model
---------------
-Checkpoint storage is treated as a **trusted data source**.  The serialization
-format uses Python's ``pickle`` module which can execute arbitrary code during
-deserialization.  The ``RestrictedUnpickler`` provides a defense-in-depth
-allowlist that limits instantiable classes, but it is **not** a security
-boundary — certain allowlisted builtins (e.g. ``getattr``) are required for
-legitimate object reconstruction (enums, named tuples) and cannot be removed
-without breaking compatibility.
-
-Developers **must** ensure that:
-
-1. The checkpoint storage backend (file system, Cosmos DB, Azure Blob, Durable
-   Functions storage) is access-controlled and not writable by untrusted
-   parties.
-2. Data flowing into ``decode_checkpoint_value`` originates exclusively from
-   the application's own checkpoint storage — never from user-supplied HTTP
-   requests, message payloads, or other untrusted sources.
-3. The ``allowed_types`` parameter is specified whenever possible to restrict
-   the set of reconstructible types to the minimum required by the application.
-4. Never pass untrusted external input to ``decode_checkpoint_value``. If you
-   must accept external JSON that might contain checkpoint markers, sanitize it
-   first (for example, :func:`agent_framework_azurefunctions._serialization.strip_pickle_markers`).
-
-The allowlist is a mitigation that reduces attack surface but does not
-eliminate the inherent risks of deserializing untrusted pickle data.  Treat
-your checkpoint storage with the same access controls you would apply to
-application secrets or database credentials.
 """
 
 from __future__ import annotations

python/packages/core/agent_framework/_workflows/_workflow.py

@@ -360,6 +360,22 @@ class Workflow(DictConvertible):
         # Flag to prevent concurrent workflow executions
         self._is_running = False
 
+        # Current run-level status of this workflow instance. Updated in lockstep with
+        # the status events emitted from `_run_workflow_with_tracing`. Defaults to IDLE
+        # for a freshly built workflow that has not yet been run.
+        self._status: WorkflowRunState = WorkflowRunState.IDLE
+
+    @property
+    def status(self) -> WorkflowRunState:
+        """Return the current run-level status of this workflow instance.
+
+        Mirrors the most recent status event emitted by the workflow. Safe to read at
+        any time: workflows run on a single asyncio event loop, and the underlying
+        attribute is a single enum reference whose assignment is atomic under the
+        CPython GIL, so no locking is required.
+        """
+        return self._status
+
     def _ensure_not_running(self) -> None:
         """Ensure the workflow is not already running."""
         if self._is_running:
@@ -513,8 +529,9 @@ class Workflow(DictConvertible):
                 with _framework_event_origin():
                     started = WorkflowEvent.started()
                 yield started  # noqa: RUF070
+                self._status = WorkflowRunState.IN_PROGRESS
                 with _framework_event_origin():
-                    in_progress = WorkflowEvent.status(WorkflowRunState.IN_PROGRESS)
+                    in_progress = WorkflowEvent.status(self._status)
                 yield in_progress  # noqa: RUF070
 
                 # Per-run reset for fresh-message runs only. We deliberately
@@ -569,17 +586,20 @@ class Workflow(DictConvertible):
 
                     if event.type == "request_info" and not emitted_in_progress_pending:
                         emitted_in_progress_pending = True
+                        self._status = WorkflowRunState.IN_PROGRESS_PENDING_REQUESTS
                         with _framework_event_origin():
-                            pending_status = WorkflowEvent.status(WorkflowRunState.IN_PROGRESS_PENDING_REQUESTS)
+                            pending_status = WorkflowEvent.status(self._status)
                         yield pending_status  # noqa: RUF070
                 # Workflow runs until idle - emit final status based on whether requests are pending
                 if saw_request:
+                    self._status = WorkflowRunState.IDLE_WITH_PENDING_REQUESTS
                     with _framework_event_origin():
-                        terminal_status = WorkflowEvent.status(WorkflowRunState.IDLE_WITH_PENDING_REQUESTS)
+                        terminal_status = WorkflowEvent.status(self._status)
                     yield terminal_status
                 else:
+                    self._status = WorkflowRunState.IDLE
                     with _framework_event_origin():
-                        terminal_status = WorkflowEvent.status(WorkflowRunState.IDLE)
+                        terminal_status = WorkflowEvent.status(self._status)
                     yield terminal_status
 
                 span.add_event(OtelAttr.WORKFLOW_COMPLETED)
@@ -593,6 +613,7 @@ class Workflow(DictConvertible):
                 with _framework_event_origin():
                     failed_event = WorkflowEvent.failed(details)
                 yield failed_event  # noqa: RUF070
+                self._status = WorkflowRunState.FAILED
                 with _framework_event_origin():
                     failed_status = WorkflowEvent.status(WorkflowRunState.FAILED)
                 yield failed_status  # noqa: RUF070

python/packages/core/agent_framework/observability.py

@@ -80,6 +80,7 @@ __all__ = [
     "EmbeddingTelemetryLayer",
     "OtelAttr",
     "configure_otel_providers",
+    "create_mcp_client_span",
     "create_metric_views",
     "create_resource",
     "disable_instrumentation",
@@ -87,6 +88,7 @@ __all__ = [
     "enable_sensitive_telemetry",
     "get_meter",
     "get_tracer",
+    "set_mcp_span_error",
 ]
 
 
@@ -110,7 +112,6 @@ INNER_ACCUMULATED_USAGE: Final[contextvars.ContextVar[UsageDetails | None]] = co
     "inner_accumulated_usage", default=None
 )
 
-
 OTEL_METRICS: Final[str] = "__otel_metrics__"
 TOKEN_USAGE_BUCKET_BOUNDARIES: Final[tuple[float, ...]] = (
     1,
@@ -292,6 +293,14 @@ class OtelAttr(str, Enum):
     AGENT_CREATE_OPERATION = "create_agent"
     AGENT_INVOKE_OPERATION = "invoke_agent"
 
+    # MCP attributes (https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/)
+    MCP_METHOD_NAME = "mcp.method.name"
+    MCP_PROTOCOL_VERSION = "mcp.protocol.version"
+    MCP_SESSION_ID = "mcp.session.id"
+    PROMPT_NAME = "gen_ai.prompt.name"
+    NETWORK_TRANSPORT = "network.transport"
+    NETWORK_PROTOCOL_NAME = "network.protocol.name"
+
     # Agent Framework specific attributes
     MEASUREMENT_FUNCTION_TAG_NAME = "agent_framework.function.name"
     MEASUREMENT_FUNCTION_INVOCATION_DURATION = "agent_framework.function.invocation.duration"
@@ -2013,6 +2022,61 @@ def get_function_span(
     )
 
 
+# region MCP span helpers
+
+
+@contextlib.contextmanager
+def create_mcp_client_span(
+    method_name: str,
+    target: str | None = None,
+    attributes: dict[str, Any] | None = None,
+) -> Generator[trace.Span, Any, Any]:
+    """Create an MCP client span per OTel MCP semantic conventions.
+
+    Span name follows the format ``{mcp.method.name} {target}`` when a target
+    is available, otherwise just ``{mcp.method.name}``.
+
+    See: https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/#client
+
+    Args:
+        method_name: The MCP method name (e.g. ``initialize``, ``tools/call``).
+        target: Optional low-cardinality target (tool name, prompt name).
+        attributes: Additional span attributes.
+    """
+    span_name = f"{method_name} {target}" if target else method_name
+    attrs: dict[str, Any] = {OtelAttr.MCP_METHOD_NAME: method_name}
+    if attributes:
+        attrs.update(attributes)
+    tracer = get_tracer() if OBSERVABILITY_SETTINGS.ENABLED else trace.NoOpTracer()
+    span = tracer.start_span(span_name, kind=trace.SpanKind.CLIENT, attributes=attrs)
+    with trace.use_span(
+        span=span,
+        end_on_exit=True,
+        record_exception=True,
+        set_status_on_exception=True,
+    ) as current_span:
+        yield current_span
+
+
+def set_mcp_span_error(
+    span: trace.Span,
+    error_type: str,
+    description: str | None = None,
+) -> None:
+    """Set error status and ``error.type`` on an MCP span.
+
+    Args:
+        span: The span to mark as errored.
+        error_type: The error type string (e.g. ``tool_error``, exception class name).
+        description: Optional description (e.g. JSON-RPC error message).
+    """
+    span.set_attribute(OtelAttr.ERROR_TYPE, error_type)
+    span.set_status(trace.StatusCode.ERROR, description=description)
+
+
+# endregion
+
+
 @contextlib.contextmanager
 def _activate_span(span: trace.Span) -> Generator[None]:
     """Attach ``span`` as the current span in the OpenTelemetry context.

python/packages/core/pyproject.toml

@@ -4,7 +4,7 @@ description = "Microsoft Agent Framework for building AI Agents with Python. Thi
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.7.0"
+version = "1.8.0"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"

python/packages/core/tests/core/test_clients.py

@@ -11,10 +11,14 @@ from agent_framework import (
     GROUP_TOKEN_COUNT_KEY,
     BaseChatClient,
     ChatResponse,
+    ChatResponseUpdate,
+    Content,
     Message,
     SlidingWindowStrategy,
     SupportsChatGetResponse,
+    ToolResultCompactionStrategy,
     TruncationStrategy,
+    tool,
 )
 
 
@@ -258,6 +262,196 @@ async def test_base_client_default_tokenizer_without_strategy_annotates_messages
     assert captured_token_counts == [[19, 19]]
 
 
+def _tool_call_response(call_id: str, location: str) -> ChatResponse:
+    return ChatResponse(
+        messages=Message(
+            role="assistant",
+            contents=[
+                Content.from_function_call(
+                    call_id=call_id,
+                    name="lookup_weather",
+                    arguments=f'{{"location": "{location}"}}',
+                )
+            ],
+        ),
+        response_id=f"resp_{call_id}",
+    )
+
+
+def _is_tool_result_summary(message: Message) -> bool:
+    text = message.text or ""
+    return message.role == "assistant" and text.startswith("[Tool results:")
+
+
+async def test_function_loop_persists_inserted_summaries_across_iterations(
+    chat_client_base: SupportsChatGetResponse,
+) -> None:
+    # Regression test for #4991: compaction inserts summary messages and excludes the
+    # originals. Across tool-loop iterations the exclusion flags persisted (shared Message
+    # objects) but the inserted summaries were dropped (they only lived on a throwaway copy),
+    # so older tool groups were silently lost with no summary representing them.
+    chat_client_base.function_invocation_configuration["enabled"] = True  # type: ignore[attr-defined]
+    chat_client_base.function_invocation_configuration["max_iterations"] = 3  # type: ignore[attr-defined]
+    chat_client_base.compaction_strategy = ToolResultCompactionStrategy(keep_last_tool_call_groups=1)  # type: ignore[attr-defined]
+
+    @tool(name="lookup_weather", approval_mode="never_require")
+    def lookup_weather(location: str) -> str:
+        return f"Weather in {location}: sunny"
+
+    chat_client_base.run_responses = [  # type: ignore[attr-defined]
+        _tool_call_response("call_1", "London"),
+        _tool_call_response("call_2", "Paris"),
+        _tool_call_response("call_3", "Tokyo"),
+    ]
+
+    captured_inputs: list[list[Message]] = []
+    original = chat_client_base._get_non_streaming_response  # type: ignore[attr-defined]
+
+    async def _capture(
+        *,
+        messages: list[Message],
+        options: dict[str, Any],
+        **kwargs: Any,
+    ) -> ChatResponse:
+        captured_inputs.append(list(messages))
+        return await original(messages=messages, options=options, **kwargs)
+
+    chat_client_base._get_non_streaming_response = _capture  # type: ignore[attr-defined,method-assign]
+
+    await chat_client_base.get_response(
+        [Message(role="user", contents=["What is the weather in London?"])],
+        options={"tools": [lookup_weather]},  # type: ignore[typeddict-unknown-key]
+    )
+
+    # The final model call should represent every compacted tool group with a summary.
+    # Two older tool groups get collapsed (London, Paris) while the last (Tokyo) is kept.
+    final_input = captured_inputs[-1]
+    summaries = [message for message in final_input if _is_tool_result_summary(message)]
+    summary_text = " ".join(message.text or "" for message in summaries)
+
+    assert len(summaries) == 2, [message.text for message in final_input]
+    assert "London" in summary_text
+    assert "Paris" in summary_text
+
+
+def _tool_call_update(call_id: str, location: str) -> list[ChatResponseUpdate]:
+    return [
+        ChatResponseUpdate(
+            contents=[
+                Content.from_function_call(
+                    call_id=call_id,
+                    name="lookup_weather",
+                    arguments=f'{{"location": "{location}"}}',
+                )
+            ],
+            role="assistant",
+            finish_reason="stop",
+            response_id=f"resp_{call_id}",
+        )
+    ]
+
+
+async def test_function_loop_persists_inserted_summaries_across_iterations_streaming(
+    chat_client_base: SupportsChatGetResponse,
+) -> None:
+    # Streaming counterpart of the #4991 regression test: the summary persistence fix in
+    # ``_prepare_messages_for_model_call`` must cover the streaming tool loop too.
+    chat_client_base.function_invocation_configuration["enabled"] = True  # type: ignore[attr-defined]
+    chat_client_base.function_invocation_configuration["max_iterations"] = 3  # type: ignore[attr-defined]
+    chat_client_base.compaction_strategy = ToolResultCompactionStrategy(keep_last_tool_call_groups=1)  # type: ignore[attr-defined]
+
+    @tool(name="lookup_weather", approval_mode="never_require")
+    def lookup_weather(location: str) -> str:
+        return f"Weather in {location}: sunny"
+
+    chat_client_base.streaming_responses = [  # type: ignore[attr-defined]
+        _tool_call_update("call_1", "London"),
+        _tool_call_update("call_2", "Paris"),
+        _tool_call_update("call_3", "Tokyo"),
+    ]
+
+    captured_inputs: list[list[Message]] = []
+    original = chat_client_base._get_streaming_response  # type: ignore[attr-defined]
+
+    def _capture(
+        *,
+        messages: list[Message],
+        options: dict[str, Any],
+        **kwargs: Any,
+    ):
+        captured_inputs.append(list(messages))
+        return original(messages=messages, options=options, **kwargs)
+
+    chat_client_base._get_streaming_response = _capture  # type: ignore[attr-defined,method-assign]
+
+    stream = chat_client_base.get_response(
+        [Message(role="user", contents=["What is the weather in London?"])],
+        stream=True,
+        options={"tools": [lookup_weather]},  # type: ignore[typeddict-unknown-key]
+    )
+    async for _ in stream:
+        pass
+
+    final_input = captured_inputs[-1]
+    summaries = [message for message in final_input if _is_tool_result_summary(message)]
+    summary_text = " ".join(message.text or "" for message in summaries)
+
+    assert len(summaries) == 2, [message.text for message in final_input]
+    assert "London" in summary_text
+    assert "Paris" in summary_text
+
+
+async def test_function_loop_compaction_conversation_id_mode_does_not_resend_history(
+    chat_client_base: SupportsChatGetResponse,
+) -> None:
+    # In conversation-id mode the server owns prior context, so the tool loop clears
+    # ``prepped_messages`` and only sends the latest message. Compaction must not fight that
+    # by re-inserting summaries or re-sending earlier turns.
+    chat_client_base.function_invocation_configuration["enabled"] = True  # type: ignore[attr-defined]
+    chat_client_base.function_invocation_configuration["max_iterations"] = 3  # type: ignore[attr-defined]
+    chat_client_base.compaction_strategy = ToolResultCompactionStrategy(keep_last_tool_call_groups=1)  # type: ignore[attr-defined]
+
+    @tool(name="lookup_weather", approval_mode="never_require")
+    def lookup_weather(location: str) -> str:
+        return f"Weather in {location}: sunny"
+
+    def _conversation_tool_call(call_id: str, location: str) -> ChatResponse:
+        response = _tool_call_response(call_id, location)
+        response.conversation_id = "conv_1"
+        return response
+
+    chat_client_base.run_responses = [  # type: ignore[attr-defined]
+        _conversation_tool_call("call_1", "London"),
+        _conversation_tool_call("call_2", "Paris"),
+        _conversation_tool_call("call_3", "Tokyo"),
+    ]
+
+    captured_inputs: list[list[Message]] = []
+    original = chat_client_base._get_non_streaming_response  # type: ignore[attr-defined]
+
+    async def _capture(
+        *,
+        messages: list[Message],
+        options: dict[str, Any],
+        **kwargs: Any,
+    ) -> ChatResponse:
+        captured_inputs.append(list(messages))
+        return await original(messages=messages, options=options, **kwargs)
+
+    chat_client_base._get_non_streaming_response = _capture  # type: ignore[attr-defined,method-assign]
+
+    await chat_client_base.get_response(
+        [Message(role="user", contents=["What is the weather in London?"])],
+        options={"tools": [lookup_weather]},  # type: ignore[typeddict-unknown-key]
+    )
+
+    # After the conversation id is established the loop only forwards the latest message,
+    # so subsequent model calls never receive the full history or summary messages.
+    for sent in captured_inputs[1:]:
+        assert len(sent) <= 1, [message.text for message in sent]
+        assert not any(_is_tool_result_summary(message) for message in sent)
+
+
 def test_base_client_as_agent_does_not_copy_client_compaction_defaults(
     chat_client_base: SupportsChatGetResponse,
 ) -> None:

python/packages/core/tests/core/test_compaction.py

@@ -196,6 +196,64 @@ def test_append_compaction_message_annotates_new_message() -> None:
     assert isinstance(_group_id(messages[1]), str)
 
 
+def test_incremental_annotation_assigns_unique_message_ids() -> None:
+    # Regression test for #5237: ``_ensure_message_ids`` assigned ``msg_{index}``
+    # using the position within the slice handed to ``group_messages``. Successive
+    # incremental annotations restart the index at 0, so distinct messages collided
+    # on the same ``message_id``.
+    messages: list[Message] = []
+    for turn in range(4):
+        messages.append(Message(role="user", contents=[f"user {turn}"]))
+        annotate_message_groups(messages)
+        messages.append(Message(role="assistant", contents=[f"assistant {turn}"]))
+        annotate_message_groups(messages)
+
+    message_ids = [message.message_id for message in messages]
+    assert all(message_ids), "every message should receive an id"
+    assert len(set(message_ids)) == len(message_ids), f"duplicate message ids: {message_ids}"
+
+
+def test_ensure_message_ids_avoids_existing_id_collisions() -> None:
+    # An auto-generated ``msg_{index}`` must not collide with an id already present
+    # on another message (user-supplied or assigned by an earlier annotation pass).
+    messages = [
+        Message(role="user", contents=["zero"]),
+        Message(role="assistant", contents=["one"], message_id="msg_2"),
+        Message(role="user", contents=["two"]),
+    ]
+    annotate_message_groups(messages)
+
+    message_ids = [message.message_id for message in messages]
+    assert message_ids[1] == "msg_2"
+    assert len(set(message_ids)) == len(message_ids), f"duplicate message ids: {message_ids}"
+
+
+def test_incremental_annotation_avoids_prefix_id_collision() -> None:
+    # Regression for the PR review on #5237: when only a suffix is re-annotated,
+    # an auto-assigned ``msg_{index}`` in the suffix must not collide with a
+    # preexisting id carried by a message in the *preserved prefix* (a group
+    # before the one re-annotation pulls back to). Otherwise ``_group_id_for``
+    # derives the same group id and merges groups across the boundary.
+    messages = [
+        # Out-of-position, user-supplied id that matches the ``msg_{index}`` the
+        # suffix pass would assign to the appended message below. This message is
+        # two groups back, so it stays outside the re-annotated slice.
+        Message(role="user", contents=["zero"], message_id="msg_2"),
+        Message(role="user", contents=["one"]),
+    ]
+    annotate_message_groups(messages)
+    assert messages[0].message_id == "msg_2"
+    assert messages[1].message_id == "msg_1"
+
+    messages.append(Message(role="user", contents=["two"]))
+    annotate_message_groups(messages, from_index=2)
+
+    message_ids = [message.message_id for message in messages]
+    assert all(message_ids), "every message should receive an id"
+    assert len(set(message_ids)) == len(message_ids), f"duplicate message ids: {message_ids}"
+    assert messages[0].message_id == "msg_2"
+
+
 async def test_truncation_strategy_keeps_system_anchor() -> None:
     messages = [
         Message(role="system", contents=["you are helpful"]),
@@ -484,6 +542,44 @@ async def test_tool_result_compaction_collapses_old_groups_into_summary() -> Non
     assert any(m.role == "tool" for m in projected)
 
 
+async def test_tool_result_compaction_is_idempotent_after_summary_insertion() -> None:
+    """Re-running compaction after a mid-list summary insertion must not duplicate it.
+
+    Mirrors a subsequent tool-loop iteration (issue #4991): the inserted summary and the
+    excluded originals now persist on the same list, so a second annotate + compaction pass
+    over the same groups should be a no-op rather than collapsing the group again.
+    """
+    messages = [
+        Message(role="user", contents=["u"]),
+        _assistant_function_call("call-1"),
+        _tool_result("call-1", "r1"),
+        _assistant_function_call("call-2"),
+        _tool_result("call-2", "r2"),
+        Message(role="assistant", contents=["done"]),
+    ]
+    strategy = ToolResultCompactionStrategy(keep_last_tool_call_groups=1)
+    annotate_message_groups(messages)
+    assert await strategy(messages) is True
+
+    summaries_after_first = [m for m in messages if (m.text or "").startswith("[Tool results:")]
+    assert len(summaries_after_first) == 1
+    summary = summaries_after_first[0]
+    summary_group_ids = _group_unknown_value(summary, SUMMARY_OF_GROUP_IDS_KEY)
+
+    # Second pass over the same (now partially compacted) list.
+    annotate_message_groups(messages)
+    changed = await strategy(messages)
+
+    assert changed is False
+    summaries_after_second = [m for m in messages if (m.text or "").startswith("[Tool results:")]
+    assert len(summaries_after_second) == 1
+    assert _group_unknown_value(summaries_after_second[0], SUMMARY_OF_GROUP_IDS_KEY) == summary_group_ids
+
+    # The kept tool-call group stays atomic and included.
+    projected = included_messages(messages)
+    assert any(m.role == "tool" for m in projected)
+
+
 async def test_tool_result_compaction_zero_collapses_all() -> None:
     """With keep=0, all tool-call groups are collapsed into summaries."""
     messages = [

python/packages/core/tests/core/test_function_invocation_logic.py

@@ -3975,3 +3975,425 @@ async def test_user_input_request_empty_contents_returns_fallback(chat_client_ba
     ]
     assert len(function_results) >= 1
     assert any("user input" in (fr.result or "").lower() for fr in function_results)
+
+
+# region Progressive tool exposure (FunctionInvocationContext.add_tools / remove_tools)
+
+
+def _pte_function_call_response(call_id: str, name: str, arguments: str = "{}") -> ChatResponse:
+    return ChatResponse(
+        messages=Message(
+            role="assistant",
+            contents=[Content.from_function_call(call_id=call_id, name=name, arguments=arguments)],
+        )
+    )
+
+
+def _pte_text_response(text: str = "done") -> ChatResponse:
+    return ChatResponse(messages=Message(role="assistant", contents=[text]))
+
+
+@tool(name="factorial", approval_mode="never_require")
+def _pte_factorial(n: int) -> int:
+    """Compute the factorial of n."""
+    result = 1
+    for value in range(2, n + 1):
+        result *= value
+    return result
+
+
+async def test_context_exposes_live_tools(chat_client_base: SupportsChatGetResponse):
+    from agent_framework import FunctionTool
+
+    seen_names: list[str] = []
+
+    @tool(name="inspect_tools", approval_mode="never_require")
+    def inspect_tools(ctx: FunctionInvocationContext) -> str:
+        assert ctx.tools is not None
+        seen_names.extend(t.name for t in ctx.tools if isinstance(t, FunctionTool))
+        return "inspected"
+
+    chat_client_base.run_responses = [
+        _pte_function_call_response("1", "inspect_tools"),
+        _pte_text_response(),
+    ]
+    await chat_client_base.get_response(
+        [Message(role="user", contents=["hi"])],
+        options={"tool_choice": "auto", "tools": [inspect_tools]},
+    )
+    assert "inspect_tools" in seen_names
+
+
+async def test_add_tools_available_next_iteration(chat_client_base: SupportsChatGetResponse):
+    exec_counter = 0
+
+    @tool(name="factorial", approval_mode="never_require")
+    def factorial(n: int) -> int:
+        nonlocal exec_counter
+        exec_counter += 1
+        return 120
+
+    @tool(name="load_math", approval_mode="never_require")
+    def load_math(ctx: FunctionInvocationContext) -> str:
+        ctx.add_tools(factorial)
+        return "math tools loaded"
+
+    chat_client_base.function_invocation_configuration["max_iterations"] = 3  # type: ignore[attr-defined]
+    chat_client_base.run_responses = [
+        _pte_function_call_response("1", "load_math"),
+        _pte_function_call_response("2", "factorial", '{"n": 5}'),
+        _pte_text_response(),
+    ]
+    response = await chat_client_base.get_response(
+        [Message(role="user", contents=["compute 5!"])],
+        options={"tool_choice": "auto", "tools": [load_math]},
+    )
+    assert exec_counter == 1
+    assert response.messages[-1].text == "done"
+
+
+async def test_add_tools_model_sees_added_tools_in_options(chat_client_base: SupportsChatGetResponse):
+    from agent_framework import FunctionTool
+
+    recorded: list[list[str]] = []
+    client_cls = type(chat_client_base)
+    original = client_cls._get_non_streaming_response
+
+    async def recording(self: Any, *, messages: Any, options: dict[str, Any], **kwargs: Any) -> ChatResponse:
+        tools = options.get("tools") or []
+        recorded.append([t.name for t in tools if isinstance(t, FunctionTool)])
+        return await original(self, messages=messages, options=options, **kwargs)
+
+    @tool(name="load_math", approval_mode="never_require")
+    def load_math(ctx: FunctionInvocationContext) -> str:
+        ctx.add_tools(_pte_factorial)
+        return "loaded"
+
+    chat_client_base.function_invocation_configuration["max_iterations"] = 3  # type: ignore[attr-defined]
+    chat_client_base.run_responses = [
+        _pte_function_call_response("1", "load_math"),
+        _pte_function_call_response("2", "factorial", '{"n": 5}'),
+        _pte_text_response(),
+    ]
+    monkey = pytest.MonkeyPatch()
+    monkey.setattr(client_cls, "_get_non_streaming_response", recording)
+    try:
+        await chat_client_base.get_response(
+            [Message(role="user", contents=["compute 5!"])],
+            options={"tool_choice": "auto", "tools": [load_math]},
+        )
+    finally:
+        monkey.undo()
+
+    assert recorded[0] == ["load_math"]
+    assert "factorial" in recorded[1]
+
+
+async def test_remove_tools_next_iteration(chat_client_base: SupportsChatGetResponse):
+    from agent_framework import FunctionTool
+
+    recorded: list[list[str]] = []
+    client_cls = type(chat_client_base)
+    original = client_cls._get_non_streaming_response
+
+    async def recording(self: Any, *, messages: Any, options: dict[str, Any], **kwargs: Any) -> ChatResponse:
+        tools = options.get("tools") or []
+        recorded.append([t.name for t in tools if isinstance(t, FunctionTool)])
+        return await original(self, messages=messages, options=options, **kwargs)
+
+    @tool(name="get_weather", approval_mode="never_require")
+    def get_weather(location: str) -> str:
+        return "sunny"
+
+    @tool(name="drop_weather", approval_mode="never_require")
+    def drop_weather(ctx: FunctionInvocationContext) -> str:
+        ctx.remove_tools("get_weather")
+        return "removed"
+
+    chat_client_base.function_invocation_configuration["max_iterations"] = 3  # type: ignore[attr-defined]
+    chat_client_base.run_responses = [
+        _pte_function_call_response("1", "drop_weather"),
+        _pte_text_response(),
+    ]
+    monkey = pytest.MonkeyPatch()
+    monkey.setattr(client_cls, "_get_non_streaming_response", recording)
+    try:
+        await chat_client_base.get_response(
+            [Message(role="user", contents=["hi"])],
+            options={"tool_choice": "auto", "tools": [get_weather, drop_weather]},
+        )
+    finally:
+        monkey.undo()
+
+    assert set(recorded[0]) == {"get_weather", "drop_weather"}
+    assert "get_weather" not in recorded[1]
+
+
+async def test_add_tools_does_not_mutate_caller_tools_list(chat_client_base: SupportsChatGetResponse):
+    @tool(name="load_math", approval_mode="never_require")
+    def load_math(ctx: FunctionInvocationContext) -> str:
+        ctx.add_tools(_pte_factorial)
+        return "loaded"
+
+    original_tools: list[Any] = [load_math]
+    chat_client_base.function_invocation_configuration["max_iterations"] = 3  # type: ignore[attr-defined]
+    chat_client_base.run_responses = [
+        _pte_function_call_response("1", "load_math"),
+        _pte_text_response(),
+    ]
+    await chat_client_base.get_response(
+        [Message(role="user", contents=["hi"])],
+        options={"tool_choice": "auto", "tools": original_tools},
+    )
+    assert original_tools == [load_math]
+
+
+async def test_add_tools_persists_across_iterations(chat_client_base: SupportsChatGetResponse):
+    from agent_framework import FunctionTool
+
+    recorded: list[list[str]] = []
+    client_cls = type(chat_client_base)
+    original = client_cls._get_non_streaming_response
+
+    async def recording(self: Any, *, messages: Any, options: dict[str, Any], **kwargs: Any) -> ChatResponse:
+        tools = options.get("tools") or []
+        recorded.append([t.name for t in tools if isinstance(t, FunctionTool)])
+        return await original(self, messages=messages, options=options, **kwargs)
+
+    @tool(name="load_math", approval_mode="never_require")
+    def load_math(ctx: FunctionInvocationContext) -> str:
+        ctx.add_tools(_pte_factorial)
+        return "loaded"
+
+    chat_client_base.function_invocation_configuration["max_iterations"] = 4  # type: ignore[attr-defined]
+    chat_client_base.run_responses = [
+        _pte_function_call_response("1", "load_math"),
+        _pte_function_call_response("2", "factorial", '{"n": 5}'),
+        _pte_function_call_response("3", "factorial", '{"n": 3}'),
+        _pte_text_response(),
+    ]
+    monkey = pytest.MonkeyPatch()
+    monkey.setattr(client_cls, "_get_non_streaming_response", recording)
+    try:
+        await chat_client_base.get_response(
+            [Message(role="user", contents=["hi"])],
+            options={"tool_choice": "auto", "tools": [load_math]},
+        )
+    finally:
+        monkey.undo()
+
+    assert "factorial" in recorded[1]
+    assert "factorial" in recorded[2]
+
+
+async def test_add_tools_through_function_middleware(chat_client_base: SupportsChatGetResponse):
+    exec_counter = 0
+
+    class PassthroughMiddleware(FunctionMiddleware):
+        async def process(self, context: FunctionInvocationContext, call_next: Any) -> None:
+            await call_next()
+
+    @tool(name="factorial", approval_mode="never_require")
+    def factorial(n: int) -> int:
+        nonlocal exec_counter
+        exec_counter += 1
+        return 120
+
+    @tool(name="load_math", approval_mode="never_require")
+    def load_math(ctx: FunctionInvocationContext) -> str:
+        ctx.add_tools(factorial)
+        return "loaded"
+
+    chat_client_base.function_invocation_configuration["max_iterations"] = 3  # type: ignore[attr-defined]
+    chat_client_base.run_responses = [
+        _pte_function_call_response("1", "load_math"),
+        _pte_function_call_response("2", "factorial", '{"n": 5}'),
+        _pte_text_response(),
+    ]
+    await chat_client_base.get_response(
+        [Message(role="user", contents=["hi"])],
+        options={"tool_choice": "auto", "tools": [load_math]},
+        middleware=[PassthroughMiddleware()],
+    )
+    assert exec_counter == 1
+
+
+async def test_add_tools_with_approval_required_tool(chat_client_base: SupportsChatGetResponse):
+    @tool(name="secure_tool", approval_mode="always_require")
+    def secure_tool(value: str) -> str:
+        return f"secure: {value}"
+
+    @tool(name="load_secure", approval_mode="never_require")
+    def load_secure(ctx: FunctionInvocationContext) -> str:
+        ctx.add_tools(secure_tool)
+        return "loaded"
+
+    chat_client_base.function_invocation_configuration["max_iterations"] = 3  # type: ignore[attr-defined]
+    chat_client_base.run_responses = [
+        _pte_function_call_response("1", "load_secure"),
+        _pte_function_call_response("2", "secure_tool", '{"value": "x"}'),
+        _pte_text_response(),
+    ]
+    response = await chat_client_base.get_response(
+        [Message(role="user", contents=["hi"])],
+        options={"tool_choice": "auto", "tools": [load_secure]},
+    )
+    assert any(item.type == "function_approval_request" for msg in response.messages for item in msg.contents)
+
+
+async def test_add_tools_accepts_plain_callable(chat_client_base: SupportsChatGetResponse):
+    exec_counter = 0
+
+    def plain_factorial(n: int) -> int:
+        """Compute factorial."""
+        nonlocal exec_counter
+        exec_counter += 1
+        return 120
+
+    @tool(name="load_math", approval_mode="never_require")
+    def load_math(ctx: FunctionInvocationContext) -> str:
+        ctx.add_tools(plain_factorial)
+        return "loaded"
+
+    chat_client_base.function_invocation_configuration["max_iterations"] = 3  # type: ignore[attr-defined]
+    chat_client_base.run_responses = [
+        _pte_function_call_response("1", "load_math"),
+        _pte_function_call_response("2", "plain_factorial", '{"n": 5}'),
+        _pte_text_response(),
+    ]
+    await chat_client_base.get_response(
+        [Message(role="user", contents=["hi"])],
+        options={"tool_choice": "auto", "tools": [load_math]},
+    )
+    assert exec_counter == 1
+
+
+async def test_add_tools_streaming(chat_client_base: SupportsChatGetResponse):
+    exec_counter = 0
+
+    @tool(name="factorial", approval_mode="never_require")
+    def factorial(n: int) -> int:
+        nonlocal exec_counter
+        exec_counter += 1
+        return 120
+
+    @tool(name="load_math", approval_mode="never_require")
+    def load_math(ctx: FunctionInvocationContext) -> str:
+        ctx.add_tools(factorial)
+        return "loaded"
+
+    chat_client_base.function_invocation_configuration["max_iterations"] = 3  # type: ignore[attr-defined]
+    chat_client_base.streaming_responses = [
+        [
+            ChatResponseUpdate(
+                contents=[Content.from_function_call(call_id="1", name="load_math", arguments="{}")],
+                role="assistant",
+            )
+        ],
+        [
+            ChatResponseUpdate(
+                contents=[Content.from_function_call(call_id="2", name="factorial", arguments='{"n": 5}')],
+                role="assistant",
+            )
+        ],
+        [ChatResponseUpdate(contents=[Content.from_text("done")], role="assistant", finish_reason="stop")],
+    ]
+    async for _ in chat_client_base.get_response(
+        [Message(role="user", contents=["hi"])],
+        stream=True,
+        options={"tool_choice": "auto", "tools": [load_math]},
+    ):
+        pass
+    assert exec_counter == 1
+
+
+def test_add_tools_duplicate_same_object_is_noop():
+    @tool(name="dup", approval_mode="never_require")
+    def dup(x: int) -> int:
+        return x
+
+    ctx = FunctionInvocationContext(function=dup, arguments={}, tools=[dup])
+    ctx.add_tools(dup)
+    assert ctx.tools is not None
+    assert len(ctx.tools) == 1
+
+
+def test_add_tools_duplicate_name_different_object_raises():
+    @tool(name="dup", approval_mode="never_require")
+    def dup_a(x: int) -> int:
+        return x
+
+    @tool(name="dup", approval_mode="never_require")
+    def dup_b(x: int) -> int:
+        return x
+
+    ctx = FunctionInvocationContext(function=dup_a, arguments={}, tools=[dup_a])
+    with pytest.raises(ValueError):
+        ctx.add_tools(dup_b)
+
+
+def test_add_tools_batch_with_duplicate_is_atomic():
+    """A duplicate-name clash partway through a batch must leave the live list unchanged."""
+
+    @tool(name="existing", approval_mode="never_require")
+    def existing(x: int) -> int:
+        return x
+
+    @tool(name="fresh", approval_mode="never_require")
+    def fresh(x: int) -> int:
+        return x
+
+    @tool(name="existing", approval_mode="never_require")
+    def clashing(x: int) -> int:
+        return x
+
+    ctx = FunctionInvocationContext(function=existing, arguments={}, tools=[existing])
+    with pytest.raises(ValueError):
+        ctx.add_tools([fresh, clashing])
+    assert ctx.tools is not None
+    # The valid "fresh" tool must not have been committed before the clash raised.
+    assert ctx.tools == [existing]
+
+
+def test_remove_tools_by_name_and_object():
+    @tool(name="a", approval_mode="never_require")
+    def a(x: int) -> int:
+        return x
+
+    @tool(name="b", approval_mode="never_require")
+    def b(x: int) -> int:
+        return x
+
+    ctx = FunctionInvocationContext(function=a, arguments={}, tools=[a, b])
+    ctx.remove_tools("a")
+    assert ctx.tools is not None
+    assert [t.name for t in ctx.tools] == ["b"]
+    ctx.remove_tools(b)
+    assert ctx.tools == []
+
+
+def test_remove_tools_unknown_name_is_noop():
+    @tool(name="a", approval_mode="never_require")
+    def a(x: int) -> int:
+        return x
+
+    ctx = FunctionInvocationContext(function=a, arguments={}, tools=[a])
+    ctx.remove_tools("nonexistent")
+    assert ctx.tools is not None
+    assert [t.name for t in ctx.tools] == ["a"]
+
+
+def test_progressive_tools_helpers_raise_without_live_tools():
+    @tool(name="a", approval_mode="never_require")
+    def a(x: int) -> int:
+        return x
+
+    ctx = FunctionInvocationContext(function=a, arguments={})
+    assert ctx.tools is None
+    with pytest.raises(RuntimeError):
+        ctx.add_tools(a)
+    with pytest.raises(RuntimeError):
+        ctx.remove_tools("a")
+
+
+# endregion

python/packages/core/tests/core/test_mcp_observability.py

@@ -0,0 +1,376 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Tests for MCP client span instrumentation per OTel GenAI Semantic Conventions.
+
+See: https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/#client
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+from mcp import types
+from mcp.shared.exceptions import McpError
+from mcp.types import ErrorData
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+from opentelemetry.trace import SpanKind, StatusCode
+
+from agent_framework import MCPStdioTool, MCPStreamableHTTPTool, MCPWebsocketTool
+from agent_framework._mcp import MCPTool
+from agent_framework.exceptions import ToolExecutionException
+from agent_framework.observability import OtelAttr
+
+# region helpers
+
+
+def _make_connected_mcp_tool(
+    name: str = "test-mcp",
+    *,
+    supports_tools: bool = True,
+    supports_prompts: bool = True,
+) -> MCPTool:
+    """Create an MCPTool with a mocked session, ready for testing."""
+    tool = MCPTool(name=name)
+    tool.session = AsyncMock()
+    tool.is_connected = True
+    tool._supports_tools = supports_tools
+    tool._supports_prompts = supports_prompts
+    tool.load_tools_flag = True
+    tool.load_prompts_flag = True
+    return tool
+
+
+def _make_tool_list_result(
+    tools: list[dict[str, Any]] | None = None,
+) -> Mock:
+    """Create a mock ListToolsResult."""
+    if tools is None:
+        tools = [{"name": "get-weather", "description": "Get weather", "inputSchema": {"type": "object"}}]
+    result = Mock()
+    result.tools = [
+        types.Tool(name=t["name"], description=t.get("description", ""), inputSchema=t.get("inputSchema", {}))
+        for t in tools
+    ]
+    result.nextCursor = None
+    return result
+
+
+def _make_prompt_list_result(
+    prompts: list[dict[str, Any]] | None = None,
+) -> Mock:
+    """Create a mock ListPromptsResult."""
+    if prompts is None:
+        prompts = [{"name": "analyze-code", "description": "Analyze code"}]
+    result = Mock()
+    result.prompts = [
+        types.Prompt(name=p["name"], description=p.get("description", ""), arguments=None) for p in prompts
+    ]
+    result.nextCursor = None
+    return result
+
+
+def _make_call_tool_result(text: str = "result", is_error: bool = False) -> Mock:
+    """Create a mock CallToolResult."""
+    result = Mock()
+    result.isError = is_error
+    result.content = [types.TextContent(type="text", text=text)]
+    return result
+
+
+def _make_get_prompt_result(text: str = "prompt result") -> types.GetPromptResult:
+    """Create a mock GetPromptResult."""
+    return types.GetPromptResult(
+        description="test prompt",
+        messages=[
+            types.PromptMessage(
+                role="user",
+                content=types.TextContent(type="text", text=text),
+            )
+        ],
+    )
+
+
+# endregion
+
+
+# region initialize span
+
+
+async def test_mcp_initialize_span(span_exporter: InMemorySpanExporter):
+    """session.initialize() should produce an MCP CLIENT span named 'initialize'."""
+    tool = MCPTool(name="test-server")
+
+    mock_session_cls = AsyncMock()
+    init_result = Mock()
+    init_result.capabilities = None
+    init_result.protocolVersion = "2025-06-18"
+    mock_session_cls.initialize = AsyncMock(return_value=init_result)
+
+    # Create a mock transport context manager
+    mock_transport = AsyncMock()
+    mock_transport.__aenter__ = AsyncMock(return_value=(Mock(), Mock()))
+    mock_transport.__aexit__ = AsyncMock(return_value=False)
+
+    # Mock get_mcp_client and the session creation
+    tool.session = None
+    tool.load_tools_flag = False
+    tool.load_prompts_flag = False
+
+    span_exporter.clear()
+
+    with pytest.MonkeyPatch.context() as m:
+        m.setattr(tool, "get_mcp_client", lambda: mock_transport)
+
+        async def patched_connect(self_: Any, *, reset: bool = False, load_configured: bool = True) -> None:
+            # Simulate _connect_on_owner: create initialize span and call session.initialize()
+            from agent_framework._mcp import create_mcp_client_span
+            from agent_framework.observability import OtelAttr
+
+            with create_mcp_client_span("initialize", attributes=self_._mcp_base_span_attributes()) as init_span:
+                result = await mock_session_cls.initialize()
+                protocol_version = getattr(result, "protocolVersion", None)
+                if protocol_version:
+                    init_span.set_attribute(OtelAttr.MCP_PROTOCOL_VERSION, protocol_version)
+
+            self_.session = mock_session_cls
+            self_.is_connected = True
+
+        m.setattr(MCPTool, "_connect_on_owner", patched_connect)
+        await tool.connect()
+
+    mock_session_cls.initialize.assert_awaited_once()
+    spans = span_exporter.get_finished_spans()
+    init_spans = [s for s in spans if s.name == "initialize"]
+    assert len(init_spans) == 1
+    span = init_spans[0]
+    assert span.kind == SpanKind.CLIENT
+    assert span.attributes[OtelAttr.MCP_METHOD_NAME] == "initialize"
+    assert span.attributes.get(OtelAttr.MCP_PROTOCOL_VERSION) == "2025-06-18"
+
+
+# endregion
+
+
+# region tools/list span
+
+
+async def test_mcp_tools_list_span(span_exporter: InMemorySpanExporter):
+    """session.list_tools() should produce an MCP CLIENT span named 'tools/list'."""
+    tool = _make_connected_mcp_tool()
+    tool.session.list_tools = AsyncMock(return_value=_make_tool_list_result())
+
+    span_exporter.clear()
+    await tool.load_tools()
+
+    spans = span_exporter.get_finished_spans()
+    list_spans = [s for s in spans if s.name == "tools/list"]
+    assert len(list_spans) == 1
+    span = list_spans[0]
+    assert span.kind == SpanKind.CLIENT
+    assert span.attributes[OtelAttr.MCP_METHOD_NAME] == "tools/list"
+
+
+# endregion
+
+
+# region prompts/list span
+
+
+async def test_mcp_prompts_list_span(span_exporter: InMemorySpanExporter):
+    """session.list_prompts() should produce an MCP CLIENT span named 'prompts/list'."""
+    tool = _make_connected_mcp_tool()
+    tool.session.list_prompts = AsyncMock(return_value=_make_prompt_list_result())
+
+    span_exporter.clear()
+    await tool.load_prompts()
+
+    spans = span_exporter.get_finished_spans()
+    list_spans = [s for s in spans if s.name == "prompts/list"]
+    assert len(list_spans) == 1
+    span = list_spans[0]
+    assert span.kind == SpanKind.CLIENT
+    assert span.attributes[OtelAttr.MCP_METHOD_NAME] == "prompts/list"
+
+
+# endregion
+
+
+# region tools/call span
+
+
+async def test_mcp_tools_call_creates_client_span_when_no_parent(span_exporter: InMemorySpanExporter):
+    """Direct call_tool() without FunctionTool wrapper creates new MCP CLIENT span."""
+    tool = _make_connected_mcp_tool()
+    tool.session.call_tool = AsyncMock(return_value=_make_call_tool_result("hello"))
+
+    span_exporter.clear()
+    result = await tool.call_tool("get-weather", city="Seattle")
+
+    assert result is not None
+    spans = span_exporter.get_finished_spans()
+    call_spans = [s for s in spans if "tools/call" in s.name]
+    assert len(call_spans) == 1
+    span = call_spans[0]
+    assert span.kind == SpanKind.CLIENT
+    assert span.name == "tools/call get-weather"
+    assert span.attributes[OtelAttr.MCP_METHOD_NAME] == "tools/call"
+    assert span.attributes[OtelAttr.TOOL_NAME] == "get-weather"
+
+
+async def test_mcp_tools_call_tool_error_sets_error_type(span_exporter: InMemorySpanExporter):
+    """When CallToolResult.isError is true, error.type should be 'tool_error' per MCP spec."""
+    tool = _make_connected_mcp_tool()
+    tool.session.call_tool = AsyncMock(return_value=_make_call_tool_result("bad input", is_error=True))
+
+    span_exporter.clear()
+    with pytest.raises(ToolExecutionException):
+        await tool.call_tool("get-weather", city="invalid")
+
+    spans = span_exporter.get_finished_spans()
+    call_spans = [s for s in spans if "tools/call" in s.name]
+    assert len(call_spans) == 1
+    span = call_spans[0]
+    assert span.attributes.get(OtelAttr.ERROR_TYPE) == "tool_error"
+    assert span.status.status_code == StatusCode.ERROR
+
+
+async def test_mcp_tools_call_mcp_error_sets_error_type(span_exporter: InMemorySpanExporter):
+    """When session.call_tool() raises McpError, error.type should be the exception class name."""
+    tool = _make_connected_mcp_tool()
+    tool.session.call_tool = AsyncMock(side_effect=McpError(ErrorData(code=-32600, message="invalid request")))
+
+    span_exporter.clear()
+    with pytest.raises(ToolExecutionException):
+        await tool.call_tool("get-weather")
+
+    spans = span_exporter.get_finished_spans()
+    call_spans = [s for s in spans if "tools/call" in s.name]
+    assert len(call_spans) == 1
+    span = call_spans[0]
+    assert span.attributes.get(OtelAttr.ERROR_TYPE) == "McpError"
+    assert span.status.status_code == StatusCode.ERROR
+
+
+# endregion
+
+
+# region prompts/get span
+
+
+async def test_mcp_prompts_get_creates_client_span(span_exporter: InMemorySpanExporter):
+    """get_prompt() should always create a new MCP CLIENT span (not enrich execute_tool)."""
+    tool = _make_connected_mcp_tool()
+    tool.session.get_prompt = AsyncMock(return_value=_make_get_prompt_result("code analysis"))
+
+    span_exporter.clear()
+    result = await tool.get_prompt("analyze-code", language="python")
+
+    assert "code analysis" in result
+    spans = span_exporter.get_finished_spans()
+    prompt_spans = [s for s in spans if "prompts/get" in s.name]
+    assert len(prompt_spans) == 1
+    span = prompt_spans[0]
+    assert span.kind == SpanKind.CLIENT
+    assert span.name == "prompts/get analyze-code"
+    assert span.attributes[OtelAttr.MCP_METHOD_NAME] == "prompts/get"
+    assert span.attributes[OtelAttr.PROMPT_NAME] == "analyze-code"
+
+
+async def test_mcp_prompts_get_mcp_error_sets_error_type(span_exporter: InMemorySpanExporter):
+    """When session.get_prompt() raises McpError, the span should have error.type and ERROR status."""
+    tool = _make_connected_mcp_tool()
+    tool.session.get_prompt = AsyncMock(
+        side_effect=McpError(ErrorData(code=-32602, message="prompt not found"))
+    )
+
+    span_exporter.clear()
+    with pytest.raises(ToolExecutionException):
+        await tool.get_prompt("missing-prompt")
+
+    spans = span_exporter.get_finished_spans()
+    prompt_spans = [s for s in spans if "prompts/get" in s.name]
+    assert len(prompt_spans) == 1
+    span = prompt_spans[0]
+    assert span.attributes.get(OtelAttr.ERROR_TYPE) == "McpError"
+    assert span.status.status_code == StatusCode.ERROR
+
+
+# endregion
+
+
+# region transport attributes
+
+
+def test_mcp_stdio_tool_transport_attributes():
+    """MCPStdioTool should have network.transport='pipe'."""
+    tool = MCPStdioTool(name="test", command="python")
+    attrs = tool._mcp_base_span_attributes()
+    assert attrs[OtelAttr.NETWORK_TRANSPORT] == "pipe"
+    assert OtelAttr.ADDRESS not in attrs
+
+
+def test_mcp_http_tool_transport_attributes():
+    """MCPStreamableHTTPTool should have tcp transport and URL-based server address/port."""
+    tool = MCPStreamableHTTPTool(name="test", url="https://api.example.com:8443/mcp")
+    attrs = tool._mcp_base_span_attributes()
+    assert attrs[OtelAttr.NETWORK_TRANSPORT] == "tcp"
+    assert attrs[OtelAttr.NETWORK_PROTOCOL_NAME] == "http"
+    assert attrs[OtelAttr.ADDRESS] == "api.example.com"
+    assert attrs[OtelAttr.PORT] == 8443
+
+
+def test_mcp_http_tool_default_port():
+    """MCPStreamableHTTPTool should default to 443 for https."""
+    tool = MCPStreamableHTTPTool(name="test", url="https://api.example.com/mcp")
+    attrs = tool._mcp_base_span_attributes()
+    assert attrs[OtelAttr.PORT] == 443
+
+
+def test_mcp_http_tool_http_default_port():
+    """MCPStreamableHTTPTool should default to 80 for http."""
+    tool = MCPStreamableHTTPTool(name="test", url="http://localhost/mcp")
+    attrs = tool._mcp_base_span_attributes()
+    assert attrs[OtelAttr.PORT] == 80
+
+
+def test_mcp_websocket_tool_transport_attributes():
+    """MCPWebsocketTool should have tcp transport and URL-based server address/port."""
+    tool = MCPWebsocketTool(name="test", url="wss://ws.example.com:9090/mcp")
+    attrs = tool._mcp_base_span_attributes()
+    assert attrs[OtelAttr.NETWORK_TRANSPORT] == "tcp"
+    assert attrs[OtelAttr.NETWORK_PROTOCOL_NAME] == "websocket"
+    assert attrs[OtelAttr.ADDRESS] == "ws.example.com"
+    assert attrs[OtelAttr.PORT] == 9090
+
+
+def test_mcp_websocket_tool_default_port():
+    """MCPWebsocketTool should default to 443 for wss."""
+    tool = MCPWebsocketTool(name="test", url="wss://ws.example.com/mcp")
+    attrs = tool._mcp_base_span_attributes()
+    assert attrs[OtelAttr.PORT] == 443
+
+
+# endregion
+
+
+# region observability disabled
+
+
+@pytest.mark.parametrize("enable_instrumentation", [False], indirect=True)
+async def test_mcp_spans_not_created_when_observability_disabled(span_exporter: InMemorySpanExporter):
+    """No MCP spans should be created when observability is disabled."""
+    tool = _make_connected_mcp_tool()
+    tool.session.list_tools = AsyncMock(return_value=_make_tool_list_result())
+    tool.session.call_tool = AsyncMock(return_value=_make_call_tool_result("ok"))
+
+    span_exporter.clear()
+    await tool.load_tools()
+    await tool.call_tool("get-weather", city="Seattle")
+
+    spans = span_exporter.get_finished_spans()
+    assert len(spans) == 0
+
+
+# endregion

python/packages/core/tests/core/test_mcp_skills.py

@@ -0,0 +1,667 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Tests for MCP-based skills (MCPSkillsSource, MCPSkill, MCPSkillResource)."""
+
+from __future__ import annotations
+
+import base64
+import json
+from unittest.mock import AsyncMock
+
+import pytest
+from mcp.shared.exceptions import McpError
+from mcp.types import (
+    BlobResourceContents,
+    ErrorData,
+    ReadResourceResult,
+    TextResourceContents,
+)
+from pydantic import AnyUrl
+
+from agent_framework import MCPSkill, MCPSkillResource, MCPSkillsSource
+from agent_framework._skills import _parse_mcp_skill_index
+
+# ---------------------------------------------------------------------------
+# Fixtures & helpers
+# ---------------------------------------------------------------------------
+
+SAMPLE_SKILL_MD = """\
+---
+name: unit-converter
+description: Convert between common units.
+---
+# Unit Converter
+
+Body content here.
+"""
+
+SAMPLE_SKILL_INDEX = json.dumps(
+    {
+        "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
+        "skills": [
+            {
+                "name": "unit-converter",
+                "type": "skill-md",
+                "description": "Convert between common units.",
+                "url": "skill://unit-converter/SKILL.md",
+            }
+        ],
+    }
+)
+
+
+def _make_text_result(text: str, uri: str = "skill://test") -> ReadResourceResult:
+    """Create a ReadResourceResult with a single TextResourceContents."""
+    return ReadResourceResult(
+        contents=[TextResourceContents(uri=AnyUrl(uri), text=text, mimeType="text/markdown")]
+    )
+
+
+def _make_blob_result(
+    data: bytes,
+    uri: str = "skill://test",
+    mime_type: str = "application/octet-stream",
+) -> ReadResourceResult:
+    """Create a ReadResourceResult with a single BlobResourceContents."""
+    return ReadResourceResult(
+        contents=[BlobResourceContents(uri=AnyUrl(uri), blob=base64.b64encode(data).decode(), mimeType=mime_type)]
+    )
+
+
+def _make_empty_result() -> ReadResourceResult:
+    """Create a ReadResourceResult with no contents."""
+    return ReadResourceResult(contents=[])
+
+
+def _make_client(**read_resource_responses: ReadResourceResult) -> AsyncMock:
+    """Create a mock ClientSession whose read_resource returns different results per URI.
+
+    Args:
+        **read_resource_responses: Mapping of URI string to ReadResourceResult.
+            Any URI not in this mapping raises McpError with the MCP-spec
+            "Resource not found" code (-32002).
+    """
+    client = AsyncMock()
+
+    async def _read_resource(uri: AnyUrl) -> ReadResourceResult:
+        uri_str = str(uri)
+        if uri_str in read_resource_responses:
+            return read_resource_responses[uri_str]
+        raise McpError(error=ErrorData(code=-32002, message=f"Resource not found: {uri_str}"))
+
+    client.read_resource = AsyncMock(side_effect=_read_resource)
+    return client
+
+
+# ---------------------------------------------------------------------------
+# _parse_mcp_skill_index tests
+# ---------------------------------------------------------------------------
+
+
+class TestParseMCPSkillIndex:
+    """Tests for the _parse_mcp_skill_index helper."""
+
+    def test_parses_valid_index(self) -> None:
+        index = _parse_mcp_skill_index(SAMPLE_SKILL_INDEX)
+        assert index.schema == "https://schemas.agentskills.io/discovery/0.2.0/schema.json"
+        assert len(index.skills) == 1
+        assert index.skills[0].name == "unit-converter"
+        assert index.skills[0].type == "skill-md"
+        assert index.skills[0].url == "skill://unit-converter/SKILL.md"
+
+    def test_parses_empty_skills_array(self) -> None:
+        index = _parse_mcp_skill_index('{"$schema": "test", "skills": []}')
+        assert index.skills == []
+
+    def test_parses_missing_skills_key(self) -> None:
+        index = _parse_mcp_skill_index('{"$schema": "test"}')
+        assert index.skills == []
+
+    def test_raises_on_non_object(self) -> None:
+        with pytest.raises(ValueError, match="must be a JSON object"):
+            _parse_mcp_skill_index("[]")
+
+    def test_raises_on_invalid_json(self) -> None:
+        with pytest.raises(json.JSONDecodeError):
+            _parse_mcp_skill_index("not json")
+
+    def test_skips_non_dict_entries(self) -> None:
+        index = _parse_mcp_skill_index('{"skills": ["not-a-dict", {"name": "ok", "type": "skill-md"}]}')
+        assert len(index.skills) == 1
+        assert index.skills[0].name == "ok"
+
+
+# ---------------------------------------------------------------------------
+# MCPSkillResource tests
+# ---------------------------------------------------------------------------
+
+
+class TestMCPSkillResource:
+    """Tests for MCPSkillResource."""
+
+    @pytest.mark.asyncio
+    async def test_read_text_content(self) -> None:
+        result = _make_text_result("hello world")
+        resource = MCPSkillResource(name="test.md", result=result)
+        content = await resource.read()
+        assert content == "hello world"
+
+    @pytest.mark.asyncio
+    async def test_read_binary_content(self) -> None:
+        data = bytes([0x01, 0x02, 0x03, 0x04])
+        result = _make_blob_result(data)
+        resource = MCPSkillResource(name="icon.bin", result=result)
+        content = await resource.read()
+        assert content == data
+
+    @pytest.mark.asyncio
+    async def test_read_empty_returns_none(self) -> None:
+        result = _make_empty_result()
+        resource = MCPSkillResource(name="empty", result=result)
+        content = await resource.read()
+        assert content is None
+
+    @pytest.mark.asyncio
+    async def test_read_multiple_text_contents_joined(self) -> None:
+        result = ReadResourceResult(
+            contents=[
+                TextResourceContents(uri=AnyUrl("skill://a"), text="line1", mimeType="text/plain"),
+                TextResourceContents(uri=AnyUrl("skill://b"), text="line2", mimeType="text/plain"),
+            ]
+        )
+        resource = MCPSkillResource(name="multi", result=result)
+        content = await resource.read()
+        assert content == "line1\nline2"
+
+    @pytest.mark.asyncio
+    async def test_binary_takes_precedence_over_text(self) -> None:
+        data = b"\xff\xfe"
+        result = ReadResourceResult(
+            contents=[
+                TextResourceContents(uri=AnyUrl("skill://a"), text="text", mimeType="text/plain"),
+                BlobResourceContents(
+                    uri=AnyUrl("skill://b"),
+                    blob=base64.b64encode(data).decode(),
+                    mimeType="application/octet-stream",
+                ),
+            ]
+        )
+        resource = MCPSkillResource(name="mixed", result=result)
+        content = await resource.read()
+        # The implementation iterates all contents checking for BlobResourceContents
+        # first, so when both text and binary are present, binary is returned.
+        assert content == data
+
+
+# ---------------------------------------------------------------------------
+# MCPSkill tests
+# ---------------------------------------------------------------------------
+
+
+class TestMCPSkill:
+    """Tests for MCPSkill."""
+
+    @pytest.mark.asyncio
+    async def test_get_content_fetches_and_caches(self) -> None:
+        client = _make_client(**{"skill://unit-converter/SKILL.md": _make_text_result(SAMPLE_SKILL_MD)})
+        from agent_framework import SkillFrontmatter
+
+        fm = SkillFrontmatter(name="unit-converter", description="Convert between common units.")
+        skill = MCPSkill(frontmatter=fm, skill_md_uri="skill://unit-converter/SKILL.md", client=client)
+
+        content1 = await skill.get_content()
+        content2 = await skill.get_content()
+
+        assert "Body content here." in content1
+        assert content1 == content2
+        # Only one MCP call should be made (cached)
+        assert client.read_resource.call_count == 1
+
+    @pytest.mark.asyncio
+    async def test_get_content_raises_on_empty(self) -> None:
+        client = _make_client(**{"skill://empty/SKILL.md": _make_empty_result()})
+        from agent_framework import SkillFrontmatter
+
+        fm = SkillFrontmatter(name="empty-skill", description="Empty skill.")
+        skill = MCPSkill(frontmatter=fm, skill_md_uri="skill://empty/SKILL.md", client=client)
+
+        with pytest.raises(ValueError, match="no text content"):
+            await skill.get_content()
+
+    @pytest.mark.asyncio
+    async def test_get_resource_text(self) -> None:
+        client = _make_client(
+            **{
+                "skill://unit-converter/SKILL.md": _make_text_result(SAMPLE_SKILL_MD),
+                "skill://unit-converter/references/checklist.md": _make_text_result("- check thing 1\n- check thing 2"),
+            }
+        )
+        from agent_framework import SkillFrontmatter
+
+        fm = SkillFrontmatter(name="unit-converter", description="Convert between common units.")
+        skill = MCPSkill(frontmatter=fm, skill_md_uri="skill://unit-converter/SKILL.md", client=client)
+
+        resource = await skill.get_resource("references/checklist.md")
+        assert resource is not None
+        content = await resource.read()
+        assert content == "- check thing 1\n- check thing 2"
+
+    @pytest.mark.asyncio
+    async def test_get_resource_binary(self) -> None:
+        data = bytes([0x01, 0x02, 0x03, 0x04])
+        client = _make_client(
+            **{
+                "skill://unit-converter/SKILL.md": _make_text_result(SAMPLE_SKILL_MD),
+                "skill://unit-converter/assets/icon.bin": _make_blob_result(data),
+            }
+        )
+        from agent_framework import SkillFrontmatter
+
+        fm = SkillFrontmatter(name="unit-converter", description="Convert between common units.")
+        skill = MCPSkill(frontmatter=fm, skill_md_uri="skill://unit-converter/SKILL.md", client=client)
+
+        resource = await skill.get_resource("assets/icon.bin")
+        assert resource is not None
+        content = await resource.read()
+        assert content == data
+
+    @pytest.mark.asyncio
+    async def test_get_resource_unknown_returns_none(self) -> None:
+        client = _make_client(**{"skill://unit-converter/SKILL.md": _make_text_result(SAMPLE_SKILL_MD)})
+        from agent_framework import SkillFrontmatter
+
+        fm = SkillFrontmatter(name="unit-converter", description="Convert between common units.")
+        skill = MCPSkill(frontmatter=fm, skill_md_uri="skill://unit-converter/SKILL.md", client=client)
+
+        resource = await skill.get_resource("references/does-not-exist.md")
+        assert resource is None
+
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize(
+        "name",
+        [
+            "../escape.md",
+            "references/../../escape.md",
+            "..",
+            "..\\escape.md",
+            "/etc/passwd",
+            "http://attacker.example.com/payload",
+        ],
+    )
+    async def test_get_resource_path_traversal_returns_none(self, name: str) -> None:
+        # Register a permissive mock that would happily return content for any URI,
+        # so the test fails unless the client-side validation rejects the name
+        # before issuing the read.
+        client = AsyncMock()
+        client.read_resource = AsyncMock(return_value=_make_text_result("should never be returned"))
+
+        from agent_framework import SkillFrontmatter
+
+        fm = SkillFrontmatter(name="unit-converter", description="Convert between common units.")
+        skill = MCPSkill(frontmatter=fm, skill_md_uri="skill://unit-converter/SKILL.md", client=client)
+
+        resource = await skill.get_resource(name)
+        assert resource is None
+        client.read_resource.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_get_resource_empty_name_returns_none(self) -> None:
+        client = _make_client()
+        from agent_framework import SkillFrontmatter
+
+        fm = SkillFrontmatter(name="test-skill", description="Test.")
+        skill = MCPSkill(frontmatter=fm, skill_md_uri="skill://test/SKILL.md", client=client)
+
+        assert await skill.get_resource("") is None
+        assert await skill.get_resource("   ") is None
+
+    @pytest.mark.asyncio
+    async def test_get_script_returns_none(self) -> None:
+        client = _make_client()
+        from agent_framework import SkillFrontmatter
+
+        fm = SkillFrontmatter(name="test-skill", description="Test.")
+        skill = MCPSkill(frontmatter=fm, skill_md_uri="skill://test/SKILL.md", client=client)
+
+        assert await skill.get_script("anything") is None
+
+    def test_compute_skill_root_uri_strips_suffix(self) -> None:
+        assert MCPSkill._compute_skill_root_uri("skill://unit-converter/SKILL.md") == "skill://unit-converter/"
+
+    def test_compute_skill_root_uri_trailing_slash(self) -> None:
+        assert MCPSkill._compute_skill_root_uri("skill://unit-converter/") == "skill://unit-converter/"
+
+    def test_compute_skill_root_uri_no_suffix_adds_slash(self) -> None:
+        assert MCPSkill._compute_skill_root_uri("skill://unit-converter") == "skill://unit-converter/"
+
+
+# ---------------------------------------------------------------------------
+# MCPSkillsSource tests
+# ---------------------------------------------------------------------------
+
+
+class TestMCPSkillsSource:
+    """Tests for MCPSkillsSource."""
+
+    @pytest.mark.asyncio
+    async def test_index_based_discovery_returns_skill(self) -> None:
+        client = _make_client(
+            **{
+                "skill://index.json": _make_text_result(SAMPLE_SKILL_INDEX, uri="skill://index.json"),
+                "skill://unit-converter/SKILL.md": _make_text_result(SAMPLE_SKILL_MD),
+            }
+        )
+        source = MCPSkillsSource(client=client)
+        skills = await source.get_skills()
+
+        assert len(skills) == 1
+        assert skills[0].frontmatter.name == "unit-converter"
+        assert skills[0].frontmatter.description == "Convert between common units."
+
+        # Content is fetched on demand, not during discovery
+        content = await skills[0].get_content()
+        assert "Body content here." in content
+
+    @pytest.mark.asyncio
+    async def test_no_index_returns_empty(self) -> None:
+        client = _make_client()  # No resources at all
+        source = MCPSkillsSource(client=client)
+        skills = await source.get_skills()
+        assert skills == []
+
+    @pytest.mark.asyncio
+    async def test_does_not_read_skill_md_during_discovery(self) -> None:
+        # Index points to a skill, but SKILL.md is not registered on the server.
+        # Discovery should succeed because it only reads the index.
+        client = _make_client(
+            **{"skill://index.json": _make_text_result(SAMPLE_SKILL_INDEX, uri="skill://index.json")}
+        )
+        source = MCPSkillsSource(client=client)
+        skills = await source.get_skills()
+
+        assert len(skills) == 1
+        assert skills[0].frontmatter.name == "unit-converter"
+
+    @pytest.mark.asyncio
+    async def test_invalid_name_is_skipped(self) -> None:
+        index_json = json.dumps(
+            {
+                "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
+                "skills": [
+                    {
+                        "name": "UnitConverter",  # Invalid: uppercase
+                        "type": "skill-md",
+                        "description": "Convert between common units.",
+                        "url": "skill://UnitConverter/SKILL.md",
+                    }
+                ],
+            }
+        )
+        client = _make_client(**{"skill://index.json": _make_text_result(index_json, uri="skill://index.json")})
+        source = MCPSkillsSource(client=client)
+        skills = await source.get_skills()
+        assert skills == []
+
+    @pytest.mark.asyncio
+    async def test_missing_required_fields_is_skipped(self) -> None:
+        index_json = json.dumps(
+            {
+                "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
+                "skills": [
+                    {
+                        "name": "unit-converter",
+                        "type": "skill-md",
+                        # Missing description and url
+                    }
+                ],
+            }
+        )
+        client = _make_client(**{"skill://index.json": _make_text_result(index_json, uri="skill://index.json")})
+        source = MCPSkillsSource(client=client)
+        skills = await source.get_skills()
+        assert skills == []
+
+    @pytest.mark.asyncio
+    async def test_unsupported_type_is_skipped(self) -> None:
+        index_json = json.dumps(
+            {
+                "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
+                "skills": [
+                    {
+                        "name": "some-skill",
+                        "type": "archive",
+                        "description": "Packaged skill.",
+                        "url": "skill://some-skill.tar.gz",
+                    }
+                ],
+            }
+        )
+        client = _make_client(**{"skill://index.json": _make_text_result(index_json, uri="skill://index.json")})
+        source = MCPSkillsSource(client=client)
+        skills = await source.get_skills()
+        assert skills == []
+
+    @pytest.mark.asyncio
+    async def test_template_type_is_skipped(self) -> None:
+        index_json = json.dumps(
+            {
+                "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
+                "skills": [
+                    {
+                        "type": "mcp-resource-template",
+                        "description": "Per-product documentation skill",
+                        "url": "skill://docs/{product}/SKILL.md",
+                    }
+                ],
+            }
+        )
+        client = _make_client(**{"skill://index.json": _make_text_result(index_json, uri="skill://index.json")})
+        source = MCPSkillsSource(client=client)
+        skills = await source.get_skills()
+        assert skills == []
+
+    @pytest.mark.asyncio
+    async def test_empty_index_returns_empty(self) -> None:
+        client = _make_client(
+            **{"skill://index.json": _make_text_result('{"skills": []}', uri="skill://index.json")}
+        )
+        source = MCPSkillsSource(client=client)
+        skills = await source.get_skills()
+        assert skills == []
+
+    @pytest.mark.asyncio
+    async def test_malformed_index_json_returns_empty(self) -> None:
+        client = _make_client(
+            **{"skill://index.json": _make_text_result("not valid json", uri="skill://index.json")}
+        )
+        source = MCPSkillsSource(client=client)
+        skills = await source.get_skills()
+        assert skills == []
+
+    @pytest.mark.asyncio
+    async def test_sibling_text_resource(self) -> None:
+        client = _make_client(
+            **{
+                "skill://index.json": _make_text_result(SAMPLE_SKILL_INDEX, uri="skill://index.json"),
+                "skill://unit-converter/SKILL.md": _make_text_result(SAMPLE_SKILL_MD),
+                "skill://unit-converter/references/checklist.md": _make_text_result("- check thing 1\n- check thing 2"),
+            }
+        )
+        source = MCPSkillsSource(client=client)
+        skill = (await source.get_skills())[0]
+        resource = await skill.get_resource("references/checklist.md")
+        assert resource is not None
+        content = await resource.read()
+        assert content == "- check thing 1\n- check thing 2"
+
+    @pytest.mark.asyncio
+    async def test_sibling_binary_resource(self) -> None:
+        data = bytes([0x01, 0x02, 0x03, 0x04])
+        client = _make_client(
+            **{
+                "skill://index.json": _make_text_result(SAMPLE_SKILL_INDEX, uri="skill://index.json"),
+                "skill://unit-converter/SKILL.md": _make_text_result(SAMPLE_SKILL_MD),
+                "skill://unit-converter/assets/icon.bin": _make_blob_result(data),
+            }
+        )
+        source = MCPSkillsSource(client=client)
+        skill = (await source.get_skills())[0]
+        resource = await skill.get_resource("assets/icon.bin")
+        assert resource is not None
+        content = await resource.read()
+        assert content == data
+
+
+# ---------------------------------------------------------------------------
+# McpError code branching tests
+# ---------------------------------------------------------------------------
+
+
+class TestMCPSkillsSourceErrorCodeBranching:
+    """Tests that MCPSkillsSource and MCPSkill branch on McpError.error.code.
+
+    Only "not found" codes (RESOURCE_NOT_FOUND -32002, METHOD_NOT_FOUND -32601)
+    should be silently swallowed as "no skills available." Other McpError codes
+    and non-McpError exceptions must propagate so that auth failures, server
+    crashes, and connection drops are visible.
+    """
+
+    @pytest.mark.asyncio
+    async def test_index_method_not_found_returns_empty(self) -> None:
+        """METHOD_NOT_FOUND (-32601) -> server doesn't support resources/read."""
+        client = AsyncMock()
+        client.read_resource = AsyncMock(side_effect=McpError(error=ErrorData(code=-32601, message="Method not found")))
+        source = MCPSkillsSource(client=client)
+        skills = await source.get_skills()
+        assert skills == []
+
+    @pytest.mark.asyncio
+    async def test_index_resource_not_found_returns_empty(self) -> None:
+        """MCP-spec "Resource not found" (-32002) -> server has no index."""
+        client = AsyncMock()
+        client.read_resource = AsyncMock(
+            side_effect=McpError(error=ErrorData(code=-32002, message="Resource not found"))
+        )
+        source = MCPSkillsSource(client=client)
+        skills = await source.get_skills()
+        assert skills == []
+
+    @pytest.mark.asyncio
+    async def test_index_invalid_params_propagates(self) -> None:
+        """INVALID_PARAMS (-32602) is a real bug, must propagate (not "not found")."""
+        client = AsyncMock()
+        client.read_resource = AsyncMock(side_effect=McpError(error=ErrorData(code=-32602, message="Invalid params")))
+        source = MCPSkillsSource(client=client)
+        with pytest.raises(McpError):
+            await source.get_skills()
+
+    @pytest.mark.asyncio
+    async def test_index_internal_error_propagates(self) -> None:
+        """INTERNAL_ERROR (-32603) must propagate, not silently return empty."""
+        client = AsyncMock()
+        client.read_resource = AsyncMock(side_effect=McpError(error=ErrorData(code=-32603, message="Internal error")))
+        source = MCPSkillsSource(client=client)
+        with pytest.raises(McpError):
+            await source.get_skills()
+
+    @pytest.mark.asyncio
+    async def test_index_connection_closed_propagates(self) -> None:
+        """CONNECTION_CLOSED (-32000) must propagate."""
+        client = AsyncMock()
+        client.read_resource = AsyncMock(
+            side_effect=McpError(error=ErrorData(code=-32000, message="Connection closed"))
+        )
+        source = MCPSkillsSource(client=client)
+        with pytest.raises(McpError):
+            await source.get_skills()
+
+    @pytest.mark.asyncio
+    async def test_index_generic_error_code_propagates(self) -> None:
+        """Generic handler error (code 0) must propagate."""
+        client = AsyncMock()
+        client.read_resource = AsyncMock(side_effect=McpError(error=ErrorData(code=0, message="Some handler error")))
+        source = MCPSkillsSource(client=client)
+        with pytest.raises(McpError):
+            await source.get_skills()
+
+    @pytest.mark.asyncio
+    async def test_index_non_mcp_error_propagates(self) -> None:
+        """Non-McpError exceptions (connection drop, timeout) must propagate."""
+        client = AsyncMock()
+        client.read_resource = AsyncMock(side_effect=ConnectionError("connection lost"))
+        source = MCPSkillsSource(client=client)
+        with pytest.raises(ConnectionError):
+            await source.get_skills()
+
+    @pytest.mark.asyncio
+    async def test_get_resource_internal_error_propagates(self) -> None:
+        """McpError with INTERNAL_ERROR on get_resource must propagate."""
+        from agent_framework import SkillFrontmatter
+
+        client = AsyncMock()
+        client.read_resource = AsyncMock(side_effect=McpError(error=ErrorData(code=-32603, message="Server crashed")))
+        fm = SkillFrontmatter(name="test-skill", description="Test.")
+        skill = MCPSkill(frontmatter=fm, skill_md_uri="skill://test/SKILL.md", client=client)
+        with pytest.raises(McpError):
+            await skill.get_resource("references/file.md")
+
+    @pytest.mark.asyncio
+    async def test_get_resource_not_found_returns_none(self) -> None:
+        """McpError with RESOURCE_NOT_FOUND (-32002) on get_resource returns None."""
+        from agent_framework import SkillFrontmatter
+
+        client = AsyncMock()
+        client.read_resource = AsyncMock(
+            side_effect=McpError(error=ErrorData(code=-32002, message="Resource not found"))
+        )
+        fm = SkillFrontmatter(name="test-skill", description="Test.")
+        skill = MCPSkill(frontmatter=fm, skill_md_uri="skill://test/SKILL.md", client=client)
+        result = await skill.get_resource("references/file.md")
+        assert result is None
+
+    @pytest.mark.asyncio
+    async def test_get_resource_connection_error_propagates(self) -> None:
+        """A plain ConnectionError on get_resource must propagate, not return None."""
+        from agent_framework import SkillFrontmatter
+
+        client = AsyncMock()
+        client.read_resource = AsyncMock(side_effect=ConnectionError("connection lost"))
+        fm = SkillFrontmatter(name="test-skill", description="Test.")
+        skill = MCPSkill(frontmatter=fm, skill_md_uri="skill://test/SKILL.md", client=client)
+        with pytest.raises(ConnectionError):
+            await skill.get_resource("references/file.md")
+
+    @pytest.mark.asyncio
+    async def test_get_resource_timeout_error_propagates(self) -> None:
+        """A TimeoutError on get_resource must propagate, not return None."""
+        from agent_framework import SkillFrontmatter
+
+        client = AsyncMock()
+        client.read_resource = AsyncMock(side_effect=TimeoutError("read timed out"))
+        fm = SkillFrontmatter(name="test-skill", description="Test.")
+        skill = MCPSkill(frontmatter=fm, skill_md_uri="skill://test/SKILL.md", client=client)
+        with pytest.raises(TimeoutError):
+            await skill.get_resource("references/file.md")
+
+    @pytest.mark.asyncio
+    async def test_get_resource_generic_mcp_error_propagates(self) -> None:
+        """McpError with a generic code (0) on get_resource must propagate."""
+        from agent_framework import SkillFrontmatter
+
+        client = AsyncMock()
+        client.read_resource = AsyncMock(
+            side_effect=McpError(error=ErrorData(code=0, message="Handler error"))
+        )
+        fm = SkillFrontmatter(name="test-skill", description="Test.")
+        skill = MCPSkill(frontmatter=fm, skill_md_uri="skill://test/SKILL.md", client=client)
+        with pytest.raises(McpError):
+            await skill.get_resource("references/file.md")
+
+    @pytest.mark.asyncio
+    async def test_index_timeout_error_propagates(self) -> None:
+        """A TimeoutError reading skill://index.json must propagate."""
+        client = AsyncMock()
+        client.read_resource = AsyncMock(side_effect=TimeoutError("read timed out"))
+        source = MCPSkillsSource(client=client)
+        with pytest.raises(TimeoutError):
+            await source.get_skills()

python/packages/core/tests/core/test_observability.py

@@ -25,6 +25,7 @@ from agent_framework import (
     prepend_agent_framework_to_user_agent,
     tool,
 )
+from agent_framework._serialization import make_json_safe
 from agent_framework.observability import (
     ROLE_EVENT_MAP,
     AgentTelemetryLayer,
@@ -3195,17 +3196,15 @@ def test_capture_messages_with_prepared_request_info_function_call_arguments(spa
 
     from opentelemetry import trace
 
-    from agent_framework import WorkflowAgent
-
     @dataclasses.dataclass
     class HandoffRequest:
         target_agent: str
         reason: str
 
-    arguments = WorkflowAgent.RequestInfoFunctionArgs(
-        request_id="call_dc",
-        data=HandoffRequest(target_agent="helper", reason="overflow"),
-    ).to_dict()
+    arguments = {
+        "request_id": "call_dc",
+        "data": make_json_safe(HandoffRequest(target_agent="helper", reason="overflow")),
+    }
     msg = Message(
         role="assistant",
         contents=[

python/packages/core/tests/core/test_tools.py

@@ -1,4 +1,6 @@
 # Copyright (c) Microsoft. All rights reserved.
+import asyncio
+import threading
 from typing import Annotated, Any, Literal, get_args, get_origin
 from unittest.mock import Mock
 
@@ -1346,6 +1348,45 @@ async def test_invoke_skip_parsing_awaits_async_functions() -> None:
     assert raw == 42
 
 
+async def test_invoke_sync_tool_does_not_block_event_loop() -> None:
+    release_tool = threading.Event()
+    tool_thread_ids: list[int] = []
+    event_loop_thread_id = threading.get_ident()
+
+    @tool
+    def wait_for_release() -> str:
+        tool_thread_ids.append(threading.get_ident())
+        return "released" if release_tool.wait(timeout=0.2) else "timed out"
+
+    async def release_soon() -> None:
+        await asyncio.sleep(0.01)
+        release_tool.set()
+
+    tool_task = asyncio.create_task(wait_for_release.invoke(skip_parsing=True))
+    release_task = asyncio.create_task(release_soon())
+
+    assert await asyncio.wait_for(tool_task, timeout=1) == "released"
+    await release_task
+    assert tool_thread_ids
+    assert tool_thread_ids[0] != event_loop_thread_id
+
+
+async def test_invoke_sync_tool_can_stay_on_event_loop() -> None:
+    event_loop_thread_id = threading.get_ident()
+    tool_thread_ids: list[int] = []
+
+    @tool
+    def needs_event_loop() -> str:
+        tool_thread_ids.append(threading.get_ident())
+        asyncio.get_running_loop()
+        return "ok"
+
+    needs_event_loop._invoke_sync_on_event_loop = True
+
+    assert await needs_event_loop.invoke(skip_parsing=True) == "ok"
+    assert tool_thread_ids == [event_loop_thread_id]
+
+
 async def test_invoke_skip_parsing_bypasses_configured_result_parser() -> None:
     """The tool's own result_parser is bypassed when skip_parsing=True is requested."""
     parser_calls: list[Any] = []

python/packages/core/tests/workflow/test_agent_executor.py

@@ -699,3 +699,171 @@ async def test_resolve_executor_kwargs_empty_per_executor_does_not_fallback_to_g
     resolved = {"exec_a": {}, GLOBAL_KWARGS_KEY: {"global_key": "global_val"}}
     result = executor._resolve_executor_kwargs(resolved)  # pyright: ignore[reportPrivateUsage]
     assert result == {}
+
+
+# region Tool approval emission
+
+
+class _ApprovalEmittingAgent(BaseAgent):
+    """Agent that returns a single ``function_approval_request`` Content.
+
+    Used to verify that ``AgentExecutor`` does *not* surface the approval
+    payload via both an ``output`` event and a ``request_info`` event in the
+    same superstep — only the ``request_info`` event must carry it.
+    """
+
+    def __init__(
+        self,
+        *,
+        approval_request_id: str = "apr_1",
+        tool_name: str = "delete_file",
+        tool_arguments: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ):
+        super().__init__(**kwargs)
+        self._approval_request_id = approval_request_id
+        self._tool_name = tool_name
+        self._tool_arguments: dict[str, Any] = tool_arguments or {"path": "/tmp/secret.txt"}
+        self.run_count = 0
+
+    def _build_approval_content(self) -> Content:
+        function_call = Content.from_function_call(
+            call_id=self._approval_request_id,
+            name=self._tool_name,
+            arguments=self._tool_arguments,
+        )
+        return Content.from_function_approval_request(id=self._approval_request_id, function_call=function_call)
+
+    @overload
+    def run(
+        self,
+        messages: AgentRunInputs | None = ...,
+        *,
+        stream: Literal[False] = ...,
+        session: AgentSession | None = ...,
+        **kwargs: Any,
+    ) -> Awaitable[AgentResponse[Any]]: ...
+
+    @overload
+    def run(
+        self,
+        messages: AgentRunInputs | None = ...,
+        *,
+        stream: Literal[True],
+        session: AgentSession | None = ...,
+        **kwargs: Any,
+    ) -> ResponseStream[AgentResponseUpdate, AgentResponse[Any]]: ...
+
+    def run(
+        self,
+        messages: AgentRunInputs | None = None,
+        *,
+        stream: bool = False,
+        session: AgentSession | None = None,
+        **kwargs: Any,
+    ) -> Awaitable[AgentResponse[Any]] | ResponseStream[AgentResponseUpdate, AgentResponse[Any]]:
+        self.run_count += 1
+        approval = self._build_approval_content()
+
+        if stream:
+
+            async def _stream() -> AsyncIterable[AgentResponseUpdate]:
+                yield AgentResponseUpdate(contents=[approval], role="assistant")
+
+            return ResponseStream(_stream(), finalizer=AgentResponse.from_updates)
+
+        async def _run() -> AgentResponse:
+            return AgentResponse(messages=[Message("assistant", [approval])])
+
+        return _run()
+
+
+def _has_approval_payload(event: WorkflowEvent[Any]) -> bool:
+    """Return True if the event's data carries a ``function_approval_request`` content."""
+    data: Any = event.data
+
+    def _contents_of(value: Any) -> list[Content]:
+        if isinstance(value, AgentResponseUpdate):
+            return list(value.contents)
+        if isinstance(value, AgentResponse):
+            return [c for m in value.messages for c in m.contents]
+        if isinstance(value, AgentExecutorResponse):
+            return [c for m in value.agent_response.messages for c in m.contents]
+        if isinstance(value, Message):
+            return list(value.contents)
+        if isinstance(value, Content):
+            return [value]
+        return []
+
+    return any(c.type == "function_approval_request" for c in _contents_of(data))
+
+
+async def test_agent_executor_does_not_double_emit_approval_non_streaming() -> None:
+    """Non-streaming: approval payload must only appear in the ``request_info`` event.
+
+    Regression test for the bug where ``AgentExecutor._run_agent`` first
+    ``yield_output``-ed the response (carrying the approval Content) and then
+    additionally emitted a ``request_info`` event for the same payload.
+    """
+    agent = _ApprovalEmittingAgent(id="approve_agent", name="ApproveAgent", approval_request_id="apr_ns_1")
+    executor = AgentExecutor(agent, id="approve_exec")
+    workflow = WorkflowBuilder(start_executor=executor).build()
+
+    request_info_events: list[WorkflowEvent[Any]] = []
+    output_events: list[WorkflowEvent[Any]] = []
+
+    for event in await workflow.run("please delete it"):
+        if event.type == "request_info":
+            request_info_events.append(event)
+        elif event.type == "output":
+            output_events.append(event)
+
+    assert len(request_info_events) == 1
+    assert _has_approval_payload(request_info_events[0])
+    # The approval payload must not also be surfaced as a workflow output.
+    assert not any(_has_approval_payload(e) for e in output_events)
+    assert agent.run_count == 1
+
+
+async def test_agent_executor_does_not_double_emit_approval_streaming() -> None:
+    """Streaming: per-update approval payload must not be ``yield_output``-ed."""
+    agent = _ApprovalEmittingAgent(id="approve_agent_s", name="ApproveAgentS", approval_request_id="apr_st_1")
+    executor = AgentExecutor(agent, id="approve_exec_s")
+    workflow = WorkflowBuilder(start_executor=executor).build()
+
+    request_info_events: list[WorkflowEvent[Any]] = []
+    output_events: list[WorkflowEvent[Any]] = []
+
+    async for event in workflow.run("please delete it", stream=True):
+        if event.type == "request_info":
+            request_info_events.append(event)
+        elif event.type == "output":
+            output_events.append(event)
+
+    assert len(request_info_events) == 1
+    assert _has_approval_payload(request_info_events[0])
+    assert not any(_has_approval_payload(e) for e in output_events)
+    assert agent.run_count == 1
+
+
+async def test_agent_executor_request_info_uses_user_input_request_id() -> None:
+    """``ctx.request_info`` must register the request under the agent's approval id.
+
+    This makes the workflow's pending-request id round-trip with the
+    ``function_approval_response.id`` the caller echoes back, so
+    ``Workflow._send_responses_internal`` can look it up directly.
+    """
+    agent = _ApprovalEmittingAgent(id="approve_agent_id", name="ApproveAgentId", approval_request_id="apr_match")
+    executor = AgentExecutor(agent, id="approve_exec_id")
+    workflow = WorkflowBuilder(start_executor=executor).build()
+
+    request_info_events: list[WorkflowEvent[Any]] = []
+    async for event in workflow.run("please delete it", stream=True):
+        if event.type == "request_info":
+            request_info_events.append(event)
+
+    assert len(request_info_events) == 1
+    assert request_info_events[0].request_id == "apr_match"
+
+
+# endregion Tool approval emission

python/packages/core/tests/workflow/test_workflow_agent.py

@@ -1,6 +1,5 @@
 # Copyright (c) Microsoft. All rights reserved.
 
-import json
 import uuid
 from collections.abc import Awaitable, Sequence
 from dataclasses import dataclass
@@ -30,6 +29,20 @@ from agent_framework import (
     handler,
     response_handler,
 )
+from agent_framework._workflows._typing_utils import deserialize_type
+
+
+@dataclass
+class HandoffRequest:
+    """Module-level dataclass used by request_info tests.
+
+    Defined at module scope (not nested inside a test method) so
+    ``serialize_type``/``deserialize_type`` can round-trip the request_type via
+    the importable qualified name ``tests.workflow.test_workflow_agent.HandoffRequest``.
+    """
+
+    target_agent: str
+    reason: str
 
 
 class SimpleExecutor(Executor):
@@ -240,52 +253,45 @@ class TestWorkflowAgent:
         # Should have received an approval request for the request info
         assert len(updates) > 0
 
-        approval_update: AgentResponseUpdate | None = None
+        request_update: AgentResponseUpdate | None = None
         for update in updates:
-            if any(content.type == "function_approval_request" for content in update.contents):
-                approval_update = update
+            if any(content.type == "function_call" for content in update.contents):
+                request_update = update
                 break
 
-        assert approval_update is not None, "Should have received a request_info approval request"
+        assert request_update is not None, "Should have received a request_info wrapped in a function_call content"
 
-        function_call = next(content for content in approval_update.contents if content.type == "function_call")
-        approval_request = next(
-            content for content in approval_update.contents if content.type == "function_approval_request"
-        )
+        request_function_call = next(content for content in request_update.contents if content.type == "function_call")
+        assert request_function_call.call_id is not None
 
         # Verify the function call has expected structure
-        assert function_call.call_id is not None
-        assert function_call.name == "request_info"
-        assert isinstance(function_call.arguments, dict)
-        assert function_call.arguments.get("request_id") == approval_request.id
+        assert request_function_call.name == WorkflowAgent.REQUEST_INFO_FUNCTION_NAME
+        assert isinstance(request_function_call.arguments, dict)
+        assert request_function_call.arguments.get("request_id") is not None
+        assert request_function_call.arguments.get("request_event") is not None
+        request_event = request_function_call.arguments["request_event"]
+        assert request_event.get("type") == "request_info"
+        assert deserialize_type(request_event.get("response_type")) is str
 
-        # Approval request should reference the same function call
-        assert approval_request.id is not None
-        assert approval_request.function_call is not None
-        assert approval_request.function_call.call_id == function_call.call_id
-        assert approval_request.function_call.name == function_call.name
+        deserialized_args = WorkflowAgent.RequestInfoFunctionArgs.from_dict(request_function_call.arguments)
+        assert deserialized_args.request_id == request_function_call.call_id
+        assert isinstance(deserialized_args.request_event, WorkflowEvent)
+        assert deserialized_args.request_event.type == "request_info"
+        assert deserialized_args.request_event.data == "Mock request data"
+        assert deserialized_args.request_event.response_type is str
 
         # Verify the request is tracked in pending_requests
-        assert len(agent.pending_requests) == 1
-        assert function_call.call_id in agent.pending_requests
+        pending_requests = await workflow._runner_context.get_pending_request_info_events()
+        assert len(pending_requests) == 1
+        assert request_function_call.call_id in pending_requests
 
-        # Now provide an approval response with updated arguments to test continuation
-        response_args = WorkflowAgent.RequestInfoFunctionArgs(
-            request_id=approval_request.id,
-            data="User provided answer",
-        ).to_dict()
-
-        approval_response = Content.from_function_approval_response(
-            approved=True,
-            id=approval_request.id,
-            function_call=Content.from_function_call(
-                call_id=function_call.call_id,
-                name=function_call.name,
-                arguments=response_args,
-            ),
+        # Now provide a function result response with updated arguments to test continuation
+        function_result = Content.from_function_result(
+            call_id=request_function_call.call_id,
+            result="Mock response to request info",
         )
 
-        response_message = Message(role="user", contents=[approval_response])
+        response_message = Message(role="user", contents=[function_result])
 
         # Continue the workflow with the response
         continuation_result = await agent.run(response_message)
@@ -294,16 +300,11 @@ class TestWorkflowAgent:
         assert isinstance(continuation_result, AgentResponse)
 
         # Verify cleanup - pending requests should be cleared after function response handling
-        assert len(agent.pending_requests) == 0
+        pending_requests = await workflow._runner_context.get_pending_request_info_events()
+        assert len(pending_requests) == 0
 
     def test_request_info_dataclass_arguments_are_serialized_when_content_is_created(self) -> None:
         """Test WorkflowAgent prepares request_info arguments before observability captures messages."""
-
-        @dataclass
-        class HandoffRequest:
-            target_agent: str
-            reason: str
-
         executor = SimpleExecutor(id="executor1", response_text="Response")
         workflow = WorkflowBuilder(start_executor=executor).build()
         agent = WorkflowAgent(workflow=workflow, name="Request Test Agent")
@@ -314,14 +315,367 @@ class TestWorkflowAgent:
             response_type=str,
         )
 
-        function_call, approval_request = agent._process_request_info_event(event)  # pyright: ignore[reportPrivateUsage]
+        request_function_call = agent._process_request_info_event(event)  # pyright: ignore[reportPrivateUsage]
 
-        assert function_call.arguments == {
-            "request_id": "request_123",
-            "data": {"target_agent": "helper", "reason": "overflow"},
-        }
-        assert approval_request.function_call is function_call
-        assert json.loads(json.dumps(function_call.arguments)) == function_call.arguments
+        assert request_function_call.call_id == "request_123"
+        assert isinstance(request_function_call.arguments, dict)
+        assert request_function_call.arguments.get("request_event") is not None
+        request_event = request_function_call.arguments["request_event"]
+        assert request_event.get("type") == "request_info"
+        assert request_event.get("request_id") == "request_123"
+        assert request_event.get("source_executor_id") == "executor1"
+        assert deserialize_type(request_event.get("response_type")) is str
+        assert request_event.get("data") == HandoffRequest(target_agent="helper", reason="overflow")
+
+        deserialized_args = WorkflowAgent.RequestInfoFunctionArgs.from_dict(request_function_call.arguments)
+        assert deserialized_args.request_id == "request_123"
+        assert isinstance(deserialized_args.request_event, WorkflowEvent)
+        assert deserialized_args.request_event.type == "request_info"
+        assert deserialized_args.request_event.data == HandoffRequest(target_agent="helper", reason="overflow")
+        assert deserialized_args.request_event.response_type is str
+
+    def test_process_request_info_event_passes_through_function_approval_request(self) -> None:
+        """If the event data is already a function approval request, it is forwarded unchanged.
+
+        Tool-approval requests emitted by an inner agent surface as ``Content``
+        objects with ``user_input_request=True``. ``WorkflowAgent`` must not
+        re-wrap these inside a synthesized ``request_info`` function call;
+        instead it should return the original content as-is so callers can
+        respond with a matching ``function_approval_response``.
+        """
+        executor = SimpleExecutor(id="executor1", response_text="Response")
+        workflow = WorkflowBuilder(start_executor=executor).build()
+        agent = WorkflowAgent(workflow=workflow, name="Approval Passthrough Agent")
+
+        approval_id = "approval-passthrough-1"
+        inner_function_call = Content.from_function_call(
+            call_id="tool-call-1",
+            name="delete_file",
+            arguments={"path": "/tmp/x"},
+        )
+        approval_request = Content.from_function_approval_request(
+            id=approval_id,
+            function_call=inner_function_call,
+        )
+        event = WorkflowEvent.request_info(
+            request_id=approval_id,
+            source_executor_id="executor1",
+            request_data=approval_request,
+            response_type=Content,
+        )
+
+        result = agent._process_request_info_event(event)  # pyright: ignore[reportPrivateUsage]
+
+        # The original FunctionApprovalRequestContent is returned as-is — same
+        # instance, with the original tool name preserved (NOT replaced by the
+        # synthesized REQUEST_INFO_FUNCTION_NAME).
+        assert result is approval_request
+        assert result.type == "function_approval_request"
+        assert result.id == approval_id
+        assert result.user_input_request is True
+        assert result.function_call is inner_function_call  # type: ignore[attr-defined]
+        assert result.function_call.name == "delete_file"  # type: ignore[attr-defined]
+        assert result.function_call.name != WorkflowAgent.REQUEST_INFO_FUNCTION_NAME  # type: ignore[attr-defined]
+
+    def test_extract_function_responses_passes_through_approval_response_approved(self) -> None:
+        """A function_approval_response with approved=True is keyed by content.id and forwarded as-is.
+
+        After the refactor, ``WorkflowAgent`` no longer unwraps a synthesized
+        ``request_info`` function call from approval responses — the response
+        content is routed straight back to the workflow under its own ``id``,
+        which matches the pending request id surfaced by
+        ``_process_request_info_event``.
+        """
+        executor = SimpleExecutor(id="executor1", response_text="Response")
+        workflow = WorkflowBuilder(start_executor=executor).build()
+        agent = WorkflowAgent(workflow=workflow, name="Approval Response Agent")
+
+        approval_id = "approval-response-approved-1"
+        inner_function_call = Content.from_function_call(
+            call_id="tool-call-1",
+            name="delete_file",
+            arguments={"path": "/tmp/x"},
+        )
+        approval_request = Content.from_function_approval_request(
+            id=approval_id,
+            function_call=inner_function_call,
+        )
+        approval_response = approval_request.to_function_approval_response(approved=True)  # type: ignore[attr-defined]
+        message = Message(role="user", contents=[approval_response])
+
+        responses = agent._extract_function_responses([message])  # pyright: ignore[reportPrivateUsage]
+
+        assert set(responses.keys()) == {approval_id}
+        assert responses[approval_id] is approval_response
+        assert responses[approval_id].approved is True  # type: ignore[attr-defined]
+
+    def test_extract_function_responses_passes_through_approval_response_denied(self) -> None:
+        """A function_approval_response with approved=False is forwarded the same way as an approval.
+
+        Only the ``approved`` flag changes — routing back to the workflow is
+        identical for accept and reject paths.
+        """
+        executor = SimpleExecutor(id="executor1", response_text="Response")
+        workflow = WorkflowBuilder(start_executor=executor).build()
+        agent = WorkflowAgent(workflow=workflow, name="Approval Response Agent")
+
+        approval_id = "approval-response-denied-1"
+        inner_function_call = Content.from_function_call(
+            call_id="tool-call-2",
+            name="send_email",
+            arguments={"to": "alice@example.com"},
+        )
+        approval_request = Content.from_function_approval_request(
+            id=approval_id,
+            function_call=inner_function_call,
+        )
+        approval_response = approval_request.to_function_approval_response(approved=False)  # type: ignore[attr-defined]
+        message = Message(role="user", contents=[approval_response])
+
+        responses = agent._extract_function_responses([message])  # pyright: ignore[reportPrivateUsage]
+
+        assert set(responses.keys()) == {approval_id}
+        assert responses[approval_id] is approval_response
+        assert responses[approval_id].approved is False  # type: ignore[attr-defined]
+
+    async def test_function_approval_request_flows_end_to_end_approved(self) -> None:
+        """End-to-end: an executor emits a function_approval_request, the agent
+        forwards it unchanged, and an ``approved=True`` response resumes the workflow.
+
+        This exercises the full pass-through path:
+        ``ctx.request_info(approval_content, ...)`` -> ``WorkflowAgent`` surfaces
+        the original ``FunctionApprovalRequestContent`` -> caller responds with a
+        ``FunctionApprovalResponseContent`` -> ``WorkflowAgent`` routes it back
+        to the workflow which delivers it to the executor's ``@response_handler``.
+        """
+        approval_id = "e2e-approval-1"
+        inner_function_call = Content.from_function_call(
+            call_id="tool-call-e2e-1",
+            name="delete_file",
+            arguments={"path": "/tmp/x"},
+        )
+        approval_request = Content.from_function_approval_request(
+            id=approval_id,
+            function_call=inner_function_call,
+        )
+
+        class ApprovalRequestingExecutor(Executor):
+            @handler
+            async def handle_message(self, _: list[Message], ctx: WorkflowContext) -> None:
+                await ctx.request_info(approval_request, Content, request_id=approval_id)
+
+            @response_handler
+            async def handle_response(
+                self,
+                original_request: Content,
+                response: Content,
+                ctx: WorkflowContext[Never, AgentResponse],
+            ) -> None:
+                assert response.type == "function_approval_response"
+                assert response.id == approval_id  # type: ignore[attr-defined]
+                approved = bool(response.approved)  # type: ignore[attr-defined]
+                tool_name = original_request.function_call.name  # type: ignore[attr-defined]
+                await ctx.yield_output(
+                    AgentResponse(
+                        messages=[
+                            Message(
+                                role="assistant",
+                                contents=[Content.from_text(text=f"{tool_name} approved={approved}")],
+                            )
+                        ]
+                    )
+                )
+
+        executor = ApprovalRequestingExecutor(id="approval_requester")
+        workflow = WorkflowBuilder(start_executor=executor).build()
+        agent = WorkflowAgent(workflow=workflow, name="E2E Approval Agent")
+
+        # First run: workflow pauses with the approval request.
+        first = await agent.run("please delete it")
+        assert isinstance(first, AgentResponse)
+
+        forwarded = next(
+            (
+                c
+                for m in first.messages
+                for c in m.contents
+                if c.type == "function_approval_request" and c.id == approval_id
+            ),
+            None,
+        )
+        assert forwarded is approval_request, "Approval request must surface unchanged"
+
+        pending = await workflow._runner_context.get_pending_request_info_events()
+        assert approval_id in pending
+
+        # Respond with approved=True.
+        approval_response = approval_request.to_function_approval_response(approved=True)  # type: ignore[attr-defined]
+        final = await agent.run(Message(role="user", contents=[approval_response]))
+
+        assert isinstance(final, AgentResponse)
+        final_text = " ".join(m.text or "" for m in final.messages)
+        assert "delete_file approved=True" in final_text
+
+        pending = await workflow._runner_context.get_pending_request_info_events()
+        assert approval_id not in pending
+
+    async def test_function_approval_request_flows_end_to_end_denied(self) -> None:
+        """End-to-end denied path: ``approved=False`` is delivered to the executor's
+        response handler so the workflow can branch on the rejection."""
+        approval_id = "e2e-approval-deny-1"
+        inner_function_call = Content.from_function_call(
+            call_id="tool-call-e2e-deny-1",
+            name="send_email",
+            arguments={"to": "alice@example.com"},
+        )
+        approval_request = Content.from_function_approval_request(
+            id=approval_id,
+            function_call=inner_function_call,
+        )
+
+        class ApprovalRequestingExecutor(Executor):
+            @handler
+            async def handle_message(self, _: list[Message], ctx: WorkflowContext) -> None:
+                await ctx.request_info(approval_request, Content, request_id=approval_id)
+
+            @response_handler
+            async def handle_response(
+                self,
+                original_request: Content,
+                response: Content,
+                ctx: WorkflowContext[Never, AgentResponse],
+            ) -> None:
+                assert response.type == "function_approval_response"
+                assert response.id == approval_id  # type: ignore[attr-defined]
+                approved = bool(response.approved)  # type: ignore[attr-defined]
+                tool_name = original_request.function_call.name  # type: ignore[attr-defined]
+                await ctx.yield_output(
+                    AgentResponse(
+                        messages=[
+                            Message(
+                                role="assistant",
+                                contents=[Content.from_text(text=f"{tool_name} approved={approved}")],
+                            )
+                        ]
+                    )
+                )
+
+        executor = ApprovalRequestingExecutor(id="approval_requester_deny")
+        workflow = WorkflowBuilder(start_executor=executor).build()
+        agent = WorkflowAgent(workflow=workflow, name="E2E Approval Deny Agent")
+
+        first = await agent.run("please send")
+        assert isinstance(first, AgentResponse)
+        forwarded = next(
+            (
+                c
+                for m in first.messages
+                for c in m.contents
+                if c.type == "function_approval_request" and c.id == approval_id
+            ),
+            None,
+        )
+        assert forwarded is approval_request
+
+        # Respond with approved=False.
+        approval_response = approval_request.to_function_approval_response(approved=False)  # type: ignore[attr-defined]
+        final = await agent.run(Message(role="user", contents=[approval_response]))
+
+        assert isinstance(final, AgentResponse)
+        final_text = " ".join(m.text or "" for m in final.messages)
+        assert "send_email approved=False" in final_text
+
+        pending = await workflow._runner_context.get_pending_request_info_events()
+        assert approval_id not in pending
+
+    async def test_request_info_non_approval_flows_end_to_end(self) -> None:
+        """End-to-end: when request data is not a function approval content, the
+        agent surfaces a synthesized ``function_call`` (name=REQUEST_INFO_FUNCTION_NAME)
+        and routes a matching ``function_result`` back to the executor.
+        """
+        captured: dict[str, Any] = {}
+
+        class HandoffRequestingExecutor(Executor):
+            @handler
+            async def handle_message(self, _: list[Message], ctx: WorkflowContext) -> None:
+                await ctx.request_info(
+                    HandoffRequest(target_agent="helper", reason="overflow"),
+                    str,
+                )
+
+            @response_handler
+            async def handle_response(
+                self,
+                original_request: HandoffRequest,
+                response: str,
+                ctx: WorkflowContext[Never, AgentResponse],
+            ) -> None:
+                captured["original"] = original_request
+                captured["response"] = response
+                await ctx.yield_output(
+                    AgentResponse(
+                        messages=[
+                            Message(
+                                role="assistant",
+                                contents=[
+                                    Content.from_text(text=f"handoff to {original_request.target_agent}: {response}")
+                                ],
+                            )
+                        ]
+                    )
+                )
+
+        executor = HandoffRequestingExecutor(id="handoff_requester")
+        workflow = WorkflowBuilder(start_executor=executor).build()
+        agent = WorkflowAgent(workflow=workflow, name="E2E Handoff Agent")
+
+        # First run: workflow pauses with a synthesized request_info function_call.
+        first = await agent.run("start handoff")
+        assert isinstance(first, AgentResponse)
+
+        function_call = next(
+            (
+                c
+                for m in first.messages
+                for c in m.contents
+                if c.type == "function_call" and c.name == WorkflowAgent.REQUEST_INFO_FUNCTION_NAME
+            ),
+            None,
+        )
+        assert function_call is not None, "Expected a synthesized request_info function_call"
+        assert function_call.call_id is not None
+        assert isinstance(function_call.arguments, dict)
+        request_id = function_call.arguments["request_id"]
+        assert function_call.call_id == request_id
+        request_payload = function_call.arguments["request_event"]
+        assert request_payload.get("type") == "request_info"
+        assert request_payload.get("data") == HandoffRequest(target_agent="helper", reason="overflow")
+
+        deserialized_args = WorkflowAgent.RequestInfoFunctionArgs.from_dict(function_call.arguments)
+        assert deserialized_args.request_id == request_id
+        assert isinstance(deserialized_args.request_event, WorkflowEvent)
+        assert deserialized_args.request_event.type == "request_info"
+        assert deserialized_args.request_event.data == HandoffRequest(target_agent="helper", reason="overflow")
+        assert deserialized_args.request_event.response_type is str
+
+        pending = await workflow._runner_context.get_pending_request_info_events()
+        assert request_id in pending
+
+        # Respond with a function_result keyed by the call_id.
+        function_result = Content.from_function_result(call_id=request_id, result="ok-do-it")
+        final = await agent.run(Message(role="user", contents=[function_result]))
+
+        assert isinstance(final, AgentResponse)
+        final_text = " ".join(m.text or "" for m in final.messages)
+        assert "handoff to helper: ok-do-it" in final_text
+
+        # The executor's response handler received the original request and the response.
+        assert isinstance(captured.get("original"), HandoffRequest)
+        assert captured["original"].target_agent == "helper"
+        assert captured["response"] == "ok-do-it"
+
+        pending = await workflow._runner_context.get_pending_request_info_events()
+        assert request_id not in pending
 
     def test_workflow_as_agent_method(self) -> None:
         """Test that Workflow.as_agent() creates a properly configured WorkflowAgent."""
@@ -1592,3 +1946,406 @@ class TestWorkflowAgentMergeUpdates:
 
         # Order: text (user), text (assistant), function_result (orphan at end)
         assert content_types == ["text", "text", "function_result"]
+
+
+class _ToolApprovalMockAgent(SupportsAgentRun):
+    """Mock agent whose first run returns a FunctionApprovalRequestContent.
+
+    Subsequent runs (after receiving an approval response in the input messages)
+    return a final assistant text response that echoes the approved arguments.
+
+    This mirrors a real agent whose tool invocation requires user approval.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        tool_name: str = "delete_file",
+        tool_arguments: dict[str, Any] | None = None,
+        approval_request_ids: Sequence[str] | None = None,
+    ) -> None:
+        self.id = str(uuid.uuid4())
+        self.name = name
+        self.description: str | None = None
+        self._tool_name = tool_name
+        self._tool_arguments = tool_arguments or {"path": "/tmp/example"}
+        # Pre-allocated request ids so the test can verify what the WorkflowAgent forwards.
+        self._approval_request_ids: list[str] = list(approval_request_ids) if approval_request_ids else []
+        self.run_count = 0
+        # Inputs received on the most recent (continuation) run, for assertions.
+        self.last_run_messages: list[Message] = []
+
+    def create_session(self, **kwargs: Any) -> AgentSession:
+        return AgentSession()
+
+    def get_session(self, *, service_session_id: str, **kwargs: Any) -> AgentSession:
+        return AgentSession()
+
+    def _next_request_id(self) -> str:
+        if self._approval_request_ids:
+            return self._approval_request_ids.pop(0)
+        return str(uuid.uuid4())
+
+    def _build_approval_request(self) -> Content:
+        request_id = self._next_request_id()
+        function_call = Content.from_function_call(
+            call_id=request_id,
+            name=self._tool_name,
+            arguments=self._tool_arguments,
+        )
+        return Content.from_function_approval_request(id=request_id, function_call=function_call)
+
+    @overload
+    def run(
+        self,
+        messages: str | Content | Message | Sequence[str | Content | Message] | None = ...,
+        *,
+        stream: Literal[False] = ...,
+        session: AgentSession | None = ...,
+        **kwargs: Any,
+    ) -> Awaitable[AgentResponse[Any]]: ...
+
+    @overload
+    def run(
+        self,
+        messages: str | Content | Message | Sequence[str | Content | Message] | None = ...,
+        *,
+        stream: Literal[True],
+        session: AgentSession | None = ...,
+        **kwargs: Any,
+    ) -> ResponseStream[AgentResponseUpdate, AgentResponse[Any]]: ...
+
+    def run(
+        self,
+        messages: str | Content | Message | Sequence[str | Content | Message] | None = None,
+        *,
+        stream: bool = False,
+        session: AgentSession | None = None,
+        **kwargs: Any,
+    ) -> Awaitable[AgentResponse] | ResponseStream[AgentResponseUpdate, AgentResponse]:
+        if stream:
+            return self._run_stream(messages=messages, session=session, **kwargs)
+        return self._run(messages=messages, session=session, **kwargs)
+
+    def _normalize(
+        self,
+        messages: str | Content | Message | Sequence[str | Content | Message] | None,
+    ) -> list[Message]:
+        if messages is None:
+            return []
+        if isinstance(messages, str):
+            return [Message(role="user", contents=[Content.from_text(text=messages)])]
+        if isinstance(messages, Message):
+            return [messages]
+        if isinstance(messages, Content):
+            return [Message(role="user", contents=[messages])]
+        result: list[Message] = []
+        for item in messages:
+            if isinstance(item, Message):
+                result.append(item)
+            elif isinstance(item, Content):
+                result.append(Message(role="user", contents=[item]))
+            else:
+                result.append(Message(role="user", contents=[Content.from_text(text=item)]))
+        return result
+
+    def _approval_responses_in(self, messages: list[Message]) -> list[Content]:
+        approvals: list[Content] = []
+        for msg in messages:
+            for content in msg.contents:
+                if content.type == "function_approval_response":
+                    approvals.append(content)
+        return approvals
+
+    async def _run(
+        self,
+        messages: str | Content | Message | Sequence[str | Content | Message] | None = None,
+        *,
+        session: AgentSession | None = None,
+        **kwargs: Any,
+    ) -> AgentResponse:
+        normalized = self._normalize(messages)
+        self.last_run_messages = normalized
+        self.run_count += 1
+
+        approvals = self._approval_responses_in(normalized)
+        if approvals:
+            # Continuation: reflect approved arguments in the final response text.
+            approved_text = "; ".join(
+                f"approved={a.approved} id={a.id}"  # type: ignore[attr-defined]
+                for a in approvals
+            )
+            return AgentResponse(messages=[Message("assistant", [Content.from_text(text=f"done ({approved_text})")])])
+
+        # First run: ask for tool approval.
+        approval = self._build_approval_request()
+        return AgentResponse(messages=[Message("assistant", [approval])])
+
+    def _run_stream(
+        self,
+        messages: str | Content | Message | Sequence[str | Content | Message] | None = None,
+        *,
+        session: AgentSession | None = None,
+        **kwargs: Any,
+    ) -> ResponseStream[AgentResponseUpdate, AgentResponse]:
+        normalized = self._normalize(messages)
+        self.last_run_messages = normalized
+        self.run_count += 1
+        approvals = self._approval_responses_in(normalized)
+
+        async def _iter():
+            if approvals:
+                approved_text = "; ".join(
+                    f"approved={a.approved} id={a.id}"  # type: ignore[attr-defined]
+                    for a in approvals
+                )
+                yield AgentResponseUpdate(
+                    contents=[Content.from_text(text=f"done ({approved_text})")],
+                    role="assistant",
+                    author_name=self.name,
+                )
+                return
+            approval = self._build_approval_request()
+            yield AgentResponseUpdate(
+                contents=[approval],
+                role="assistant",
+                author_name=self.name,
+            )
+
+        return ResponseStream(_iter(), finalizer=AgentResponse.from_updates)
+
+
+class TestWorkflowAgentToolApproval:
+    """Tests for tool-approval requests bubbling through WorkflowAgent.
+
+    Covers the case where a workflow contains an AgentExecutor whose underlying
+    agent emits a FunctionApprovalRequestContent (tool needing user approval).
+    The WorkflowAgent must:
+      * forward the original FunctionApprovalRequestContent unchanged (no
+        wrapping inside a synthesized 'request_info' function call), and
+      * route a subsequent FunctionApprovalResponseContent back to the
+        AgentExecutor so the agent can resume.
+    """
+
+    def _find_approval_request(
+        self,
+        contents: Sequence[Content],
+        tool_name: str,
+    ) -> Content | None:
+        for content in contents:
+            if (
+                content.type == "function_approval_request"
+                and getattr(content.function_call, "name", None) == tool_name  # type: ignore[attr-defined]
+            ):
+                return content
+        return None
+
+    async def test_tool_approval_request_forwarded_unchanged(self) -> None:
+        """The agent's FunctionApprovalRequestContent surfaces verbatim (not re-wrapped)."""
+        approval_id = "approval-abc-123"
+        mock_agent = _ToolApprovalMockAgent(
+            name="approval-agent",
+            tool_name="delete_file",
+            tool_arguments={"path": "/tmp/secret.txt"},
+            approval_request_ids=[approval_id],
+        )
+
+        @executor
+        async def start(messages: list[Message], ctx: WorkflowContext[AgentExecutorRequest]) -> None:
+            await ctx.send_message(AgentExecutorRequest(messages=messages, should_respond=True))
+
+        workflow = WorkflowBuilder(start_executor=start).add_edge(start, mock_agent).build()
+        agent = WorkflowAgent(workflow=workflow, name="Approval Test Agent")
+
+        result = await agent.run("please delete the file")
+
+        assert isinstance(result, AgentResponse)
+
+        # Locate the approval request emitted by the WorkflowAgent.
+        all_contents: list[Content] = [c for m in result.messages for c in m.contents]
+        approval = self._find_approval_request(all_contents, tool_name="delete_file")
+        assert approval is not None, "WorkflowAgent did not forward the tool approval request"
+
+        # The id and inner function_call must match what the underlying agent produced
+        # — i.e. the WorkflowAgent must NOT have re-wrapped it inside a synthesized
+        # 'request_info' approval request.
+        assert approval.id == approval_id
+        function_call = approval.function_call  # type: ignore[attr-defined]
+        assert function_call is not None
+        assert function_call.name == "delete_file"
+        assert function_call.name != WorkflowAgent.REQUEST_INFO_FUNCTION_NAME
+        assert function_call.arguments == {"path": "/tmp/secret.txt"}
+
+        # The agent must be paused awaiting the approval response.
+        pending = await workflow._runner_context.get_pending_request_info_events()
+        assert approval_id in pending
+
+    async def test_tool_approval_request_forwarded_unchanged_streaming(self) -> None:
+        """Streaming variant: the approval request is forwarded as-is in updates."""
+        approval_id = "approval-stream-1"
+        mock_agent = _ToolApprovalMockAgent(
+            name="approval-agent-stream",
+            tool_name="send_email",
+            tool_arguments={"to": "alice@example.com"},
+            approval_request_ids=[approval_id],
+        )
+
+        @executor
+        async def start(messages: list[Message], ctx: WorkflowContext[AgentExecutorRequest]) -> None:
+            await ctx.send_message(AgentExecutorRequest(messages=messages, should_respond=True))
+
+        workflow = WorkflowBuilder(start_executor=start).add_edge(start, mock_agent).build()
+        agent = WorkflowAgent(workflow=workflow, name="Approval Stream Agent")
+
+        updates: list[AgentResponseUpdate] = []
+        async for update in agent.run("hi", stream=True):
+            updates.append(update)
+
+        approval_updates = [u for u in updates if any(c.type == "function_approval_request" for c in u.contents)]
+        assert approval_updates, "Streaming did not surface a tool approval request"
+
+        approval = self._find_approval_request(approval_updates[-1].contents, tool_name="send_email")
+        assert approval is not None
+        assert approval.id == approval_id
+        function_call = approval.function_call  # type: ignore[attr-defined]
+        assert function_call is not None
+        assert function_call.name == "send_email"
+        assert function_call.name != WorkflowAgent.REQUEST_INFO_FUNCTION_NAME
+        assert function_call.arguments == {"to": "alice@example.com"}
+
+    async def test_tool_approval_response_resumes_agent(self) -> None:
+        """Sending the approval response back resumes the agent and clears pending requests."""
+        approval_id = "approval-resume-1"
+        mock_agent = _ToolApprovalMockAgent(
+            name="approval-resume-agent",
+            tool_name="delete_file",
+            tool_arguments={"path": "/tmp/x"},
+            approval_request_ids=[approval_id],
+        )
+
+        @executor
+        async def start(messages: list[Message], ctx: WorkflowContext[AgentExecutorRequest]) -> None:
+            await ctx.send_message(AgentExecutorRequest(messages=messages, should_respond=True))
+
+        workflow = WorkflowBuilder(start_executor=start).add_edge(start, mock_agent).build()
+        agent = WorkflowAgent(workflow=workflow, name="Approval Resume Agent")
+
+        first_result = await agent.run("delete it")
+        approval = self._find_approval_request(
+            [c for m in first_result.messages for c in m.contents],
+            tool_name="delete_file",
+        )
+        assert approval is not None
+        assert mock_agent.run_count == 1
+
+        # Build the approval response. NOTE: the inner function_call's name is the
+        # original tool name ('delete_file'), NOT 'request_info'. This exercises the
+        # branch in WorkflowAgent._extract_function_responses that routes raw
+        # tool-approval responses straight through using content.id.
+        approval_response = approval.to_function_approval_response(approved=True)  # type: ignore[attr-defined]
+        response_message = Message(role="user", contents=[approval_response])
+
+        final_result = await agent.run(response_message)
+        assert isinstance(final_result, AgentResponse)
+
+        # The mock agent should have been invoked a second time and seen the
+        # approval response in its inputs.
+        assert mock_agent.run_count == 2
+        approvals_seen = [
+            c for m in mock_agent.last_run_messages for c in m.contents if c.type == "function_approval_response"
+        ]
+        assert len(approvals_seen) == 1
+        assert approvals_seen[0].id == approval_id  # type: ignore[attr-defined]
+        assert approvals_seen[0].approved is True  # type: ignore[attr-defined]
+
+        # The pending approval should now be cleared.
+        pending = await workflow._runner_context.get_pending_request_info_events()
+        assert approval_id not in pending
+
+        # The final assistant message reflects the resumption.
+        final_text = " ".join(m.text or "" for m in final_result.messages)
+        assert "done" in final_text
+        assert approval_id in final_text
+
+    async def test_tool_approval_response_rejected_resumes_agent(self) -> None:
+        """Rejection path: ``approved=False`` is forwarded to the inner agent and clears the pending request.
+
+        The WorkflowAgent must route a rejection response back to the paused
+        ``AgentExecutor`` exactly the same way as an approval — only the
+        ``approved`` flag differs. The inner agent decides what to do with it.
+        """
+        approval_id = "approval-reject-1"
+        mock_agent = _ToolApprovalMockAgent(
+            name="approval-reject-agent",
+            tool_name="delete_file",
+            tool_arguments={"path": "/tmp/x"},
+            approval_request_ids=[approval_id],
+        )
+
+        @executor
+        async def start(messages: list[Message], ctx: WorkflowContext[AgentExecutorRequest]) -> None:
+            await ctx.send_message(AgentExecutorRequest(messages=messages, should_respond=True))
+
+        workflow = WorkflowBuilder(start_executor=start).add_edge(start, mock_agent).build()
+        agent = WorkflowAgent(workflow=workflow, name="Approval Reject Agent")
+
+        first_result = await agent.run("delete it")
+        approval = self._find_approval_request(
+            [c for m in first_result.messages for c in m.contents],
+            tool_name="delete_file",
+        )
+        assert approval is not None
+        assert mock_agent.run_count == 1
+
+        # Reject the tool invocation.
+        approval_response = approval.to_function_approval_response(approved=False)  # type: ignore[attr-defined]
+        response_message = Message(role="user", contents=[approval_response])
+
+        final_result = await agent.run(response_message)
+        assert isinstance(final_result, AgentResponse)
+
+        # The inner agent must have been resumed and seen ``approved=False``.
+        assert mock_agent.run_count == 2
+        approvals_seen = [
+            c for m in mock_agent.last_run_messages for c in m.contents if c.type == "function_approval_response"
+        ]
+        assert len(approvals_seen) == 1
+        assert approvals_seen[0].id == approval_id  # type: ignore[attr-defined]
+        assert approvals_seen[0].approved is False  # type: ignore[attr-defined]
+
+        # Pending approval cleared regardless of approve/reject.
+        pending = await workflow._runner_context.get_pending_request_info_events()
+        assert approval_id not in pending
+
+        # The final assistant message reflects the rejection.
+        final_text = " ".join(m.text or "" for m in final_result.messages)
+        assert "approved=False" in final_text
+        assert approval_id in final_text
+
+    async def test_tool_approval_request_id_matches_pending_request(self) -> None:
+        """The approval request id surfaced by WorkflowAgent matches the workflow's pending request id.
+
+        This guards the AgentExecutor change that forwards
+        request_id=user_input_request.id to ctx.request_info(...), which is what
+        allows the response routed back via WorkflowAgent to resolve the pending
+        request without an id-mismatch error.
+        """
+        approval_id = "approval-id-match-1"
+        mock_agent = _ToolApprovalMockAgent(
+            name="approval-id-match-agent",
+            approval_request_ids=[approval_id],
+        )
+
+        @executor
+        async def start(messages: list[Message], ctx: WorkflowContext[AgentExecutorRequest]) -> None:
+            await ctx.send_message(AgentExecutorRequest(messages=messages, should_respond=True))
+
+        workflow = WorkflowBuilder(start_executor=start).add_edge(start, mock_agent).build()
+        agent = WorkflowAgent(workflow=workflow, name="Approval Id Agent")
+
+        await agent.run("go")
+
+        pending = await workflow._runner_context.get_pending_request_info_events()
+        # The agent's approval id is used as the workflow's pending request id.
+        assert list(pending.keys()) == [approval_id]

python/packages/core/tests/workflow/test_workflow_status.py

@@ -0,0 +1,149 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Tests for the ``Workflow.status`` property."""
+
+from dataclasses import dataclass
+
+import pytest
+
+from agent_framework import (
+    Executor,
+    Workflow,
+    WorkflowBuilder,
+    WorkflowContext,
+    WorkflowEvent,
+    WorkflowRunState,
+    handler,
+    response_handler,
+)
+from agent_framework._workflows._executor import Executor as _Executor
+from agent_framework._workflows._request_info_mixin import RequestInfoMixin
+
+
+class PassThroughExecutor(Executor):
+    """Executor that yields its input as a workflow output and stops."""
+
+    @handler
+    async def passthrough(self, msg: str, ctx: WorkflowContext[str, str]) -> None:
+        await ctx.yield_output(msg)
+
+
+class FailingExecutor(Executor):
+    """Executor that raises at runtime to drive the FAILED status."""
+
+    @handler
+    async def fail(self, msg: int, ctx: WorkflowContext) -> None:  # pragma: no cover - invoked via workflow
+        raise RuntimeError("boom")
+
+
+@dataclass
+class _ApprovalRequest:
+    prompt: str
+    request_id: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.request_id:
+            import uuid
+
+            self.request_id = str(uuid.uuid4())
+
+
+class ApprovalExecutor(_Executor, RequestInfoMixin):
+    """Executor that issues a single request_info call and finalizes on response."""
+
+    def __init__(self, id: str = "approval"):
+        super().__init__(id=id)
+
+    @handler
+    async def start(self, message: str, ctx: WorkflowContext[str, str]) -> None:
+        await ctx.request_info(_ApprovalRequest(prompt=message), bool)
+
+    @response_handler
+    async def on_response(
+        self, original_request: _ApprovalRequest, approved: bool, ctx: WorkflowContext[str, str]
+    ) -> None:
+        await ctx.yield_output(f"approved={approved}")
+
+
+def _build_passthrough_workflow() -> Workflow:
+    executor = PassThroughExecutor(id="p")
+    return WorkflowBuilder(start_executor=executor, output_from=[executor]).build()
+
+
+def _build_failing_workflow() -> Workflow:
+    # FailingExecutor has no workflow_output_types, so we leave designation
+    # implicit; the deprecation warning is filtered at call sites that need it.
+    return WorkflowBuilder(start_executor=FailingExecutor(id="f")).build()
+
+
+def _build_approval_workflow() -> Workflow:
+    executor = ApprovalExecutor(id="approval")
+    return WorkflowBuilder(start_executor=executor, output_from=[executor]).build()
+
+
+async def test_status_default_is_idle_before_first_run():
+    wf = _build_passthrough_workflow()
+    assert wf.status is WorkflowRunState.IDLE
+
+
+async def test_status_is_idle_after_successful_run():
+    wf = _build_passthrough_workflow()
+    await wf.run("hello")
+    assert wf.status is WorkflowRunState.IDLE
+
+
+async def test_status_is_failed_after_failure():
+    wf = _build_failing_workflow()
+    with pytest.raises(RuntimeError, match="boom"):
+        await wf.run(0)
+    assert wf.status is WorkflowRunState.FAILED
+
+
+async def test_status_transitions_during_streaming_run():
+    """Workflow.status mirrors the most recent emitted status event."""
+    wf = _build_passthrough_workflow()
+    observed: list[WorkflowRunState] = []
+
+    async for event in wf.run("hi", stream=True):
+        if isinstance(event, WorkflowEvent) and event.type == "status":
+            # By the time a status event surfaces to the consumer, the property
+            # must already reflect that state (updated in lockstep with emission).
+            assert wf.status == event.state
+            observed.append(event.state)  # type: ignore
+
+    # IN_PROGRESS must precede IDLE; both must appear.
+    assert WorkflowRunState.IN_PROGRESS in observed
+    assert observed[-1] is WorkflowRunState.IDLE
+    assert wf.status is WorkflowRunState.IDLE
+
+
+async def test_status_idle_with_pending_requests_then_resolves_to_idle():
+    wf = _build_approval_workflow()
+
+    request_event: WorkflowEvent | None = None
+    async for event in wf.run("please approve", stream=True):
+        if isinstance(event, WorkflowEvent) and event.type == "request_info":
+            request_event = event
+
+    assert request_event is not None
+    assert wf.status is WorkflowRunState.IDLE_WITH_PENDING_REQUESTS
+
+    async for _ in wf.run(stream=True, responses={request_event.request_id: True}):
+        pass
+
+    assert wf.status is WorkflowRunState.IDLE
+
+
+async def test_status_in_progress_pending_requests_observed_mid_run():
+    """While streaming, status reaches IN_PROGRESS_PENDING_REQUESTS after a request_info event."""
+    wf = _build_approval_workflow()
+    seen_states: list[WorkflowRunState] = []
+
+    async for event in wf.run("please approve", stream=True):
+        if isinstance(event, WorkflowEvent) and event.type == "status":
+            seen_states.append(event.state)  # type: ignore
+
+    assert WorkflowRunState.IN_PROGRESS in seen_states
+    assert WorkflowRunState.IN_PROGRESS_PENDING_REQUESTS in seen_states
+    assert seen_states[-1] is WorkflowRunState.IDLE_WITH_PENDING_REQUESTS
+    assert wf.status is WorkflowRunState.IDLE_WITH_PENDING_REQUESTS

python/packages/foundry/agent_framework_foundry/_agent.py

@@ -191,6 +191,7 @@ class RawFoundryAgentChatClient(  # type: ignore[misc]
         compaction_strategy: CompactionStrategy | None = None,
         tokenizer: TokenizerProtocol | None = None,
         additional_properties: dict[str, Any] | None = None,
+        timeout: float | None = None,
     ) -> None:
         """Initialize a raw Foundry Agent client.
 
@@ -211,6 +212,8 @@ class RawFoundryAgentChatClient(  # type: ignore[misc]
             compaction_strategy: Optional per-client compaction override.
             tokenizer: Optional tokenizer for compaction strategies.
             additional_properties: Additional properties stored on the client instance.
+            timeout: HTTP timeout in seconds for requests. When not provided, the
+                OpenAI SDK default is used (connect: 5s, total: 600s).
         """
         settings = load_settings(
             FoundryAgentSettings,
@@ -260,8 +263,11 @@ class RawFoundryAgentChatClient(  # type: ignore[misc]
             openai_client_kwargs["default_headers"] = dict(default_headers)
         if allow_preview:
             openai_client_kwargs["agent_name"] = self.agent_name
+        openai_client = self.project_client.get_openai_client(**openai_client_kwargs)
+        if timeout is not None:
+            openai_client = openai_client.with_options(timeout=timeout)
         super().__init__(
-            async_client=self.project_client.get_openai_client(**openai_client_kwargs),
+            async_client=openai_client,
             default_headers=default_headers,
             instruction_role=instruction_role,
             compaction_strategy=compaction_strategy,
@@ -537,6 +543,7 @@ class _FoundryAgentChatClient(  # type: ignore[misc]
         additional_properties: dict[str, Any] | None = None,
         middleware: (Sequence[ChatAndFunctionMiddlewareTypes] | None) = None,
         function_invocation_configuration: FunctionInvocationConfiguration | None = None,
+        timeout: float | None = None,
     ) -> None:
         """Initialize a Foundry Agent client with full middleware support.
 
@@ -556,6 +563,8 @@ class _FoundryAgentChatClient(  # type: ignore[misc]
             additional_properties: Additional properties stored on the client instance.
             middleware: Optional sequence of middleware.
             function_invocation_configuration: Optional function invocation configuration.
+            timeout: HTTP timeout in seconds for requests. When not provided, the
+                OpenAI SDK default is used (connect: 5s, total: 600s).
         """
         super().__init__(
             project_endpoint=project_endpoint,
@@ -573,6 +582,7 @@ class _FoundryAgentChatClient(  # type: ignore[misc]
             additional_properties=additional_properties,
             middleware=middleware,
             function_invocation_configuration=function_invocation_configuration,
+            timeout=timeout,
         )
 
 
@@ -625,6 +635,7 @@ class RawFoundryAgent(  # type: ignore[misc]
         compaction_strategy: CompactionStrategy | None = None,
         tokenizer: TokenizerProtocol | None = None,
         additional_properties: Mapping[str, Any] | None = None,
+        timeout: float | None = None,
     ) -> None:
         """Initialize a Foundry Agent.
 
@@ -657,6 +668,8 @@ class RawFoundryAgent(  # type: ignore[misc]
             compaction_strategy: Optional agent-level in-run compaction override.
             tokenizer: Optional agent-level tokenizer override.
             additional_properties: Additional properties stored on the local agent wrapper.
+            timeout: HTTP timeout in seconds for requests. When not provided, the
+                OpenAI SDK default is used (connect: 5s, total: 600s).
         """
         # Create the client
         actual_client_type = client_type or _FoundryAgentChatClient
@@ -675,6 +688,7 @@ class RawFoundryAgent(  # type: ignore[misc]
             "default_headers": default_headers,
             "env_file_path": env_file_path,
             "env_file_encoding": env_file_encoding,
+            "timeout": timeout,
         }
         if function_invocation_configuration is not None:
             if not issubclass(actual_client_type, FunctionInvocationLayer):
@@ -912,6 +926,7 @@ class FoundryAgent(  # type: ignore[misc]
         compaction_strategy: CompactionStrategy | None = None,
         tokenizer: TokenizerProtocol | None = None,
         additional_properties: Mapping[str, Any] | None = None,
+        timeout: float | None = None,
     ) -> None:
         """Initialize a Foundry Agent with full middleware and telemetry.
 
@@ -958,6 +973,8 @@ class FoundryAgent(  # type: ignore[misc]
             compaction_strategy: Optional agent-level in-run compaction override.
             tokenizer: Optional agent-level tokenizer override.
             additional_properties: Additional properties stored on the local agent wrapper.
+            timeout: HTTP timeout in seconds for requests. When not provided, the
+                OpenAI SDK default is used (connect: 5s, total: 600s).
         """
         super().__init__(
             project_endpoint=project_endpoint,
@@ -983,4 +1000,5 @@ class FoundryAgent(  # type: ignore[misc]
             compaction_strategy=compaction_strategy,
             tokenizer=tokenizer,
             additional_properties=additional_properties,
+            timeout=timeout,
         )

python/packages/foundry/pyproject.toml

@@ -4,7 +4,7 @@ description = "Microsoft Foundry integrations for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.7.0"
+version = "1.8.0"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,10 +23,10 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.7.0,<2",
-    "agent-framework-openai>=1.7.0,<2",
+    "agent-framework-core>=1.8.0,<2",
+    "agent-framework-openai>=1.8.0,<2",
     "azure-ai-inference>=1.0.0b9,<1.0.0b10",
-    "azure-ai-projects>=2.1.0,<3.0",
+    "azure-ai-projects>=2.2.0,<3.0",
 ]
 
 [tool.uv]

python/packages/foundry/tests/foundry/test_foundry_agent.py

@@ -109,9 +109,67 @@ def test_raw_foundry_agent_chat_client_init_uses_explicit_parameters() -> None:
     assert "compaction_strategy" in signature.parameters
     assert "tokenizer" in signature.parameters
     assert "additional_properties" in signature.parameters
+    assert "timeout" in signature.parameters
     assert all(parameter.kind != inspect.Parameter.VAR_KEYWORD for parameter in signature.parameters.values())
 
 
+def test_raw_foundry_agent_chat_client_init_applies_timeout_to_openai_client() -> None:
+    """Test that timeout is applied via with_options without mutating the shared OpenAI client."""
+
+    mock_project = MagicMock()
+    openai_client_mock = MagicMock()
+    openai_client_mock.timeout = 5.0
+    mock_project.get_openai_client.return_value = openai_client_mock
+
+    client = RawFoundryAgentChatClient(
+        project_client=mock_project,
+        agent_name="test-agent",
+        timeout=60.0,
+    )
+
+    openai_client_mock.with_options.assert_called_once_with(timeout=60.0)
+    assert openai_client_mock.timeout == 5.0, "Original shared client must not be mutated"
+    assert client.client is openai_client_mock.with_options.return_value
+
+
+def test_raw_foundry_agent_chat_client_init_timeout_none_leaves_client_unchanged() -> None:
+    """Test that timeout=None does not call with_options and leaves the shared client intact."""
+
+    mock_project = MagicMock()
+    openai_client_mock = MagicMock()
+    openai_client_mock.timeout = 5.0
+    mock_project.get_openai_client.return_value = openai_client_mock
+
+    RawFoundryAgentChatClient(
+        project_client=mock_project,
+        agent_name="test-agent",
+        timeout=None,
+    )
+
+    openai_client_mock.with_options.assert_not_called()
+    assert openai_client_mock.timeout == 5.0
+
+
+def test_raw_foundry_agent_chat_client_init_applies_timeout_with_preview_enabled() -> None:
+    """Test that timeout uses with_options even when allow_preview=True (hosted agent path)."""
+
+    mock_project = MagicMock()
+    openai_client_mock = MagicMock()
+    openai_client_mock.timeout = 5.0
+    mock_project.get_openai_client.return_value = openai_client_mock
+
+    client = RawFoundryAgentChatClient(
+        project_client=mock_project,
+        agent_name="hosted-agent",
+        allow_preview=True,
+        timeout=120.0,
+    )
+
+    openai_client_mock.with_options.assert_called_once_with(timeout=120.0)
+    assert openai_client_mock.timeout == 5.0, "Original shared client must not be mutated"
+    assert client.client is openai_client_mock.with_options.return_value
+
+
 def test_raw_foundry_agent_chat_client_as_agent_preserves_client_type() -> None:
     """Test that as_agent() wraps the client in FoundryAgent using the same client class."""
 
@@ -552,9 +610,29 @@ def test_foundry_agent_chat_client_init_uses_explicit_parameters() -> None:
     assert "compaction_strategy" in signature.parameters
     assert "tokenizer" in signature.parameters
     assert "additional_properties" in signature.parameters
+    assert "timeout" in signature.parameters
     assert all(parameter.kind != inspect.Parameter.VAR_KEYWORD for parameter in signature.parameters.values())
 
 
+def test_foundry_agent_chat_client_init_propagates_timeout() -> None:
+    """Test that _FoundryAgentChatClient calls with_options instead of mutating the shared client."""
+
+    mock_project = MagicMock()
+    openai_client_mock = MagicMock()
+    openai_client_mock.timeout = 5.0
+    mock_project.get_openai_client.return_value = openai_client_mock
+
+    client = _FoundryAgentChatClient(
+        project_client=mock_project,
+        agent_name="test-agent",
+        timeout=45.0,
+    )
+
+    openai_client_mock.with_options.assert_called_once_with(timeout=45.0)
+    assert openai_client_mock.timeout == 5.0, "Original shared client must not be mutated"
+    assert client.client is openai_client_mock.with_options.return_value
+
+
 def test_raw_foundry_agent_init_creates_client() -> None:
     """Test that RawFoundryAgent creates a client internally."""
 
@@ -629,6 +707,7 @@ def test_raw_foundry_agent_init_uses_explicit_parameters() -> None:
     assert "compaction_strategy" in signature.parameters
     assert "tokenizer" in signature.parameters
     assert "additional_properties" in signature.parameters
+    assert "timeout" in signature.parameters
     assert all(parameter.kind != inspect.Parameter.VAR_KEYWORD for parameter in signature.parameters.values())
 
 
@@ -641,9 +720,47 @@ def test_foundry_agent_init_uses_explicit_parameters() -> None:
     assert "compaction_strategy" in signature.parameters
     assert "tokenizer" in signature.parameters
     assert "additional_properties" in signature.parameters
+    assert "timeout" in signature.parameters
     assert all(parameter.kind != inspect.Parameter.VAR_KEYWORD for parameter in signature.parameters.values())
 
 
+def test_foundry_agent_init_propagates_timeout_to_openai_client() -> None:
+    """Test that FoundryAgent uses with_options instead of mutating the shared OpenAI client."""
+
+    mock_project = MagicMock()
+    openai_client_mock = MagicMock()
+    openai_client_mock.timeout = 5.0
+    mock_project.get_openai_client.return_value = openai_client_mock
+
+    agent = FoundryAgent(
+        project_client=mock_project,
+        agent_name="test-agent",
+        timeout=90.0,
+    )
+
+    openai_client_mock.with_options.assert_called_once_with(timeout=90.0)
+    assert openai_client_mock.timeout == 5.0, "Original shared client must not be mutated"
+    assert agent.client.client is openai_client_mock.with_options.return_value
+
+
+def test_foundry_agent_init_timeout_none_leaves_client_default() -> None:
+    """Test that FoundryAgent with timeout=None does not call with_options or mutate the client."""
+
+    mock_project = MagicMock()
+    openai_client_mock = MagicMock()
+    openai_client_mock.timeout = 5.0
+    mock_project.get_openai_client.return_value = openai_client_mock
+
+    FoundryAgent(
+        project_client=mock_project,
+        agent_name="test-agent",
+        timeout=None,
+    )
+
+    openai_client_mock.with_options.assert_not_called()
+    assert openai_client_mock.timeout == 5.0
+
+
 def test_raw_foundry_agent_init_rejects_invalid_client_type() -> None:
     """Test that invalid client_type raises TypeError."""
 

python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses.py

@@ -11,7 +11,7 @@ import tempfile
 import threading
 from collections.abc import AsyncIterable, AsyncIterator, Generator, Mapping, Sequence
 from contextlib import AbstractAsyncContextManager, AsyncExitStack, suppress
-from dataclasses import asdict, is_dataclass
+from dataclasses import asdict, dataclass, is_dataclass
 from pathlib import Path
 from typing import Protocol, cast
 
@@ -264,28 +264,73 @@ def _checkpoint_storage_for_context(root: str, context_id: str) -> FileCheckpoin
 
 # Foundry Toolbox Auth integration
 # Consent-URL error code returned by the Foundry MCP gateway when calling `/list`
-CONSENT_ERROR_CODE = -32007
+CONSENT_ERROR_CODE = -32006
 
 
-def consent_url_from_error(exc: BaseException) -> str | None:
-    """Return the consent URL when ``exc`` wraps a Foundry MCP gateway consent error.
+@dataclass
+class ConsentError:
+    name: str
+    consent_url: str
 
-    The Agent Framework MCP layer surfaces gateway consent failures by wrapping the underlying
-    ``McpError`` inside an :class:`AgentFrameworkException` (typically a ``ToolExecutionException``
-    raised from ``MCPStreamableHTTPTool.__aenter__``). This helper inspects ``exc.args`` for a
-    wrapped ``McpError`` whose ``error.code`` is :data:`CONSENT_ERROR_CODE`; when found, the
-    consent link the gateway returned in ``error.message`` is returned. Returns ``None`` for
-    anything else, so callers can do ``if (url := consent_url_from_error(ex)) is None: raise``.
+
+def consent_url_from_error(exc: BaseException) -> list[ConsentError] | None:
+    """Return the consent URLs when ``exc`` wraps Foundry MCP gateway consent errors.
 
     Args:
         exc: The exception to inspect.
 
     Returns:
-        The consent URL if ``exc`` wraps a consent ``McpError``, otherwise ``None``.
+        The consent URL(s) extracted from the error, or ``None`` if no consent error was found.
     """
     inner_exception = next((arg for arg in exc.args if isinstance(arg, McpError)), None)
     if inner_exception is not None and inner_exception.error.code == CONSENT_ERROR_CODE:
-        return inner_exception.error.message
+        # Parse the error message
+        # The error message is structured with the following format:
+        # "tools/list failed for 1 tool source(s), succeeded for 0 tool source(s) {"errors":[{"name": ..."
+        # where the second part is a JSON string that can be deserialized into an object with the following shape:
+        # ruff: disable[ERA001]
+        # {
+        #   "errors" : [
+        #       {
+        #           "name": "Name of the MCP tool that requires consent",
+        #           "type" : "mcp",
+        #           "error": {
+        #               "code": "CONSENT_REQUIRED",
+        #               "message": consent_url,
+        #           }
+        #       }
+        #   ]
+        # }
+        # ruff: enable[ERA001]
+        try:
+            consent_errors: list[ConsentError] = []
+            error_message_start = inner_exception.error.message.find("{")
+            if error_message_start == -1:
+                logger.warning("Consent error message does not contain JSON: %s", inner_exception.error.message)
+                return None
+            consent_details_json = inner_exception.error.message[error_message_start:]
+            consent_details = json.loads(consent_details_json)
+            if "errors" not in consent_details or not isinstance(consent_details["errors"], list):
+                logger.warning("Consent error message JSON does not contain 'errors' list: %s", consent_details_json)
+                return None
+            for error in consent_details["errors"]:
+                if (
+                    isinstance(error, dict)
+                    and error.get("type") == "mcp"  # type: ignore
+                    and "error" in error
+                    and isinstance(error["error"], dict)
+                    and error["error"].get("code") == "CONSENT_REQUIRED"  # type: ignore
+                    and "message" in error["error"]
+                ):
+                    consent_url = error["error"]["message"]  # type: ignore
+                    if isinstance(consent_url, str):
+                        consent_errors.append(ConsentError(name=error.get("name", "Unknown"), consent_url=consent_url))  # type: ignore
+                    else:
+                        logger.warning("Consent URL in error message is not a valid URL: %s", consent_url)  # type: ignore
+            if consent_errors:
+                return consent_errors
+        except json.JSONDecodeError:
+            logger.warning("Failed to parse consent details JSON: %s", inner_exception.error.message)
     return None
 
 
@@ -448,18 +493,19 @@ class ResponsesHostServer(ResponsesAgentServerHost):
         try:
             await self._ensure_agent_ready()
         except AgentFrameworkException as ex:
-            consent_url = consent_url_from_error(ex)
-            if consent_url is None:
+            consent_errors = consent_url_from_error(ex)
+            if consent_errors is None:
                 raise
-            logger.warning("OAuth consent required for Foundry MCP gateway.")
-            oauth_item = OAuthConsentRequestOutputItem(
-                id=IdGenerator.new_id("oacr"),
-                consent_link=consent_url,
-                server_label="Foundry Toolbox",
-            )
-            builder = response_event_stream.add_output_item(oauth_item.id)
-            yield builder.emit_added(oauth_item)
-            yield builder.emit_done(oauth_item)
+            for consent_error in consent_errors:
+                logger.warning("Consent URL for tool '%s': %s", consent_error.name, consent_error.consent_url)
+                oauth_item = OAuthConsentRequestOutputItem(
+                    id=IdGenerator.new_id("oacr"),
+                    consent_link=consent_error.consent_url,
+                    server_label=consent_error.name,
+                )
+                builder = response_event_stream.add_output_item(oauth_item.id)
+                yield builder.emit_added(oauth_item)
+                yield builder.emit_done(oauth_item)
             yield response_event_stream.emit_completed()
             return
 
@@ -521,7 +567,7 @@ class ResponsesHostServer(ResponsesAgentServerHost):
         by the hosting infrastructure or files will be preserved upon deactivation.
         """
         input_items = await context.get_input_items()
-        input_messages = await _items_to_messages(input_items)
+        input_messages = await _items_to_messages(input_items, approval_storage=self._approval_storage)
         is_streaming_request = request.stream is not None and request.stream is True
 
         _, are_options_set = _to_chat_options(request)
@@ -618,7 +664,11 @@ class ResponsesHostServer(ResponsesAgentServerHost):
                 checkpoint_storage=write_storage,
             )
 
-            async for item in _to_outputs_for_messages(response_event_stream, response.messages):
+            async for item in _to_outputs_for_messages(
+                response_event_stream,
+                response.messages,
+                approval_storage=self._approval_storage,
+            ):
                 yield item
 
             await self._delete_not_latest_checkpoints(write_storage, self._agent.workflow.name)
@@ -639,7 +689,9 @@ class ResponsesHostServer(ResponsesAgentServerHost):
                 for event in tracker.handle(content):
                     yield event
                 if tracker.needs_async:
-                    async for item in _to_outputs(response_event_stream, content):
+                    async for item in _to_outputs(
+                        response_event_stream, content, approval_storage=self._approval_storage
+                    ):
                         yield item
                     tracker.needs_async = False