Merge branch 'main' into shkr/workflow_return_value

.github/scripts/check_team_membership.js

@@ -0,0 +1,61 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+/**
+ * Resolve the issue author and check their team membership.
+ *
+ * @param {object} opts
+ * @param {object} opts.github - Octokit REST client from actions/github-script
+ * @param {object} opts.context - GitHub Actions context
+ * @param {object} opts.core - GitHub Actions core toolkit
+ * @param {string} opts.teamSlug - Team slug to check membership against
+ * @param {string|number} opts.issueNumber - Issue number to resolve author for
+ * @returns {Promise<{author: string|null, isTeamMember: boolean}>}
+ */
+async function checkTeamMembership({ github, context, core, teamSlug, issueNumber }) {
+  let author = context.payload.issue?.user?.login;
+  if (!author) {
+    const { data: issue } = await github.rest.issues.get({
+      owner: context.repo.owner,
+      repo: context.repo.repo,
+      issue_number: Number(issueNumber),
+    });
+    author = issue.user?.login;
+  }
+
+  if (!author) {
+    core.setFailed('Could not determine issue author (user may be deleted).');
+    return { author: null, isTeamMember: false };
+  }
+
+  try {
+    await github.rest.teams.getByName({
+      org: context.repo.owner,
+      team_slug: teamSlug,
+    });
+  } catch (error) {
+    core.setFailed(`Team lookup failed for ${teamSlug}: ${error.message}`);
+    throw error;
+  }
+
+  let isTeamMember = false;
+  try {
+    const teamMembership = await github.rest.teams.getMembershipForUserInOrg({
+      org: context.repo.owner,
+      team_slug: teamSlug,
+      username: author,
+    });
+    isTeamMember = teamMembership.data.state === 'active';
+  } catch (error) {
+    if (error.status === 404) {
+      core.info(`Author ${author} is not a member of team ${teamSlug}.`);
+      isTeamMember = false;
+    } else {
+      core.setFailed(`Team membership lookup failed for ${author}: ${error.message}`);
+      throw error;
+    }
+  }
+
+  return { author, isTeamMember };
+}
+
+module.exports = checkTeamMembership;

.github/tests/test_check_team_membership.js

@@ -0,0 +1,178 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+/**
+ * Tests for check_team_membership.js.
+ *
+ * Run with: node --test .github/tests/test_check_team_membership.js
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+
+const checkTeamMembership = require('../scripts/check_team_membership.js');
+
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createMocks({ payloadIssue = undefined, apiUser = 'api-user', teamState = 'active' } = {}) {
+  const core = {
+    _infoMessages: [],
+    _failedMessages: [],
+    info(msg) { this._infoMessages.push(msg); },
+    setFailed(msg) { this._failedMessages.push(msg); },
+  };
+
+  const context = {
+    payload: { issue: payloadIssue },
+    repo: { owner: 'test-org', repo: 'test-repo' },
+  };
+
+  const github = {
+    rest: {
+      issues: {
+        get: async () => ({
+          data: { user: apiUser ? { login: apiUser } : null },
+        }),
+      },
+      teams: {
+        getByName: async () => ({}),
+        getMembershipForUserInOrg: async () => ({
+          data: { state: teamState },
+        }),
+      },
+    },
+  };
+
+  return { core, context, github };
+}
+
+const BASE_OPTS = { teamSlug: 'my-team', issueNumber: '123' };
+
+
+// ---------------------------------------------------------------------------
+// Author resolution
+// ---------------------------------------------------------------------------
+
+describe('author resolution', () => {
+  it('resolves author from event payload', async () => {
+    const { github, context, core } = createMocks({
+      payloadIssue: { user: { login: 'payload-user' } },
+    });
+    const result = await checkTeamMembership({ github, context, core, ...BASE_OPTS });
+    assert.equal(result.author, 'payload-user');
+  });
+
+  it('resolves author via API when payload issue is absent', async () => {
+    const { github, context, core } = createMocks({ apiUser: 'api-user' });
+    const result = await checkTeamMembership({ github, context, core, ...BASE_OPTS });
+    assert.equal(result.author, 'api-user');
+  });
+
+  it('resolves author via API when payload issue user is null (deleted account)', async () => {
+    const { github, context, core } = createMocks({
+      payloadIssue: { user: null },
+      apiUser: 'fetched-user',
+    });
+    const result = await checkTeamMembership({ github, context, core, ...BASE_OPTS });
+    assert.equal(result.author, 'fetched-user');
+  });
+
+  it('handles deleted account when API also returns null user', async () => {
+    const { github, context, core } = createMocks({ apiUser: null });
+    const result = await checkTeamMembership({ github, context, core, ...BASE_OPTS });
+    assert.equal(result.author, null);
+    assert.equal(result.isTeamMember, false);
+    assert.ok(core._failedMessages.some(m => m.includes('deleted')));
+  });
+});
+
+
+// ---------------------------------------------------------------------------
+// Team lookup
+// ---------------------------------------------------------------------------
+
+describe('team lookup', () => {
+  it('fails the job when team lookup errors', async () => {
+    const { github, context, core } = createMocks({
+      payloadIssue: { user: { login: 'user1' } },
+    });
+    const error = new Error('Bad credentials');
+    github.rest.teams.getByName = async () => { throw error; };
+
+    await assert.rejects(
+      () => checkTeamMembership({ github, context, core, ...BASE_OPTS }),
+      (err) => err === error,
+    );
+    assert.ok(core._failedMessages.some(m => m.includes('Team lookup failed')));
+  });
+});
+
+
+// ---------------------------------------------------------------------------
+// Team membership
+// ---------------------------------------------------------------------------
+
+describe('team membership', () => {
+  it('returns true for active team member', async () => {
+    const { github, context, core } = createMocks({
+      payloadIssue: { user: { login: 'member' } },
+      teamState: 'active',
+    });
+    const result = await checkTeamMembership({ github, context, core, ...BASE_OPTS });
+    assert.equal(result.isTeamMember, true);
+  });
+
+  it('returns false for pending team member', async () => {
+    const { github, context, core } = createMocks({
+      payloadIssue: { user: { login: 'pending-user' } },
+      teamState: 'pending',
+    });
+    const result = await checkTeamMembership({ github, context, core, ...BASE_OPTS });
+    assert.equal(result.isTeamMember, false);
+  });
+
+  it('treats 404 membership response as non-member without failing', async () => {
+    const { github, context, core } = createMocks({
+      payloadIssue: { user: { login: 'outsider' } },
+    });
+    const notFoundError = new Error('Not Found');
+    notFoundError.status = 404;
+    github.rest.teams.getMembershipForUserInOrg = async () => { throw notFoundError; };
+
+    const result = await checkTeamMembership({ github, context, core, ...BASE_OPTS });
+    assert.equal(result.isTeamMember, false);
+    assert.equal(core._failedMessages.length, 0);
+    assert.ok(core._infoMessages.some(m => m.includes('not a member')));
+  });
+
+  it('fails the job on non-404 membership errors', async () => {
+    const { github, context, core } = createMocks({
+      payloadIssue: { user: { login: 'user1' } },
+    });
+    const serverError = new Error('Internal Server Error');
+    serverError.status = 500;
+    github.rest.teams.getMembershipForUserInOrg = async () => { throw serverError; };
+
+    await assert.rejects(
+      () => checkTeamMembership({ github, context, core, ...BASE_OPTS }),
+      (err) => err === serverError,
+    );
+    assert.ok(core._failedMessages.some(m => m.includes('membership lookup failed')));
+  });
+
+  it('fails the job on membership errors without status code', async () => {
+    const { github, context, core } = createMocks({
+      payloadIssue: { user: { login: 'user1' } },
+    });
+    const networkError = new Error('ECONNREFUSED');
+    github.rest.teams.getMembershipForUserInOrg = async () => { throw networkError; };
+
+    await assert.rejects(
+      () => checkTeamMembership({ github, context, core, ...BASE_OPTS }),
+      (err) => err === networkError,
+    );
+    assert.ok(core._failedMessages.some(m => m.includes('membership lookup failed')));
+  });
+});

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

@@ -0,0 +1,165 @@
+name: DevFlow PR Review
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - reopened
+      - ready_for_review
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: Pull request number to review
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+concurrency:
+  group: devflow-pr-review-${{ github.repository }}-${{ github.event.pull_request.number || inputs.pr_number || github.run_id }}
+  cancel-in-progress: true
+
+env:
+  DEVFLOW_REPOSITORY: ${{ vars.DF_REPO }}
+  DEVFLOW_REF: main
+  TARGET_REPO_PATH: ${{ github.workspace }}/target-repo
+  DEVFLOW_PATH: ${{ github.workspace }}/devflow
+
+jobs:
+  team_check:
+    runs-on: ubuntu-latest
+    outputs:
+      is_team_member: ${{ steps.check.outputs.is_team_member }}
+      pr_number: ${{ steps.pr.outputs.pr_number }}
+      pr_url: ${{ steps.pr.outputs.pr_url }}
+      repo: ${{ steps.pr.outputs.repo }}
+    steps:
+      - name: Resolve PR metadata
+        id: pr
+        shell: bash
+        env:
+          PR_HTML_URL: ${{ github.event.pull_request.html_url }}
+          PR_NUMBER_EVENT: ${{ github.event.pull_request.number }}
+          PR_NUMBER_INPUT: ${{ inputs.pr_number }}
+        run: |
+          set -euo pipefail
+
+          if [[ "${GITHUB_EVENT_NAME}" == "pull_request_target" ]]; then
+            pr_number="${PR_NUMBER_EVENT}"
+            pr_url="${PR_HTML_URL}"
+          else
+            pr_number="${PR_NUMBER_INPUT}"
+            pr_url="https://github.com/${GITHUB_REPOSITORY}/pull/${pr_number}"
+          fi
+
+          if [[ ! "$pr_number" =~ ^[1-9][0-9]*$ ]]; then
+            echo "Could not determine PR number; for workflow_dispatch runs, the 'pr_number' input is required when not running on pull_request_target." >&2
+            exit 1
+          fi
+
+          echo "pr_url=${pr_url}" >> "$GITHUB_OUTPUT"
+          echo "pr_number=${pr_number}" >> "$GITHUB_OUTPUT"
+          echo "repo=${GITHUB_REPOSITORY}" >> "$GITHUB_OUTPUT"
+
+      - name: Check PR author team membership
+        id: check
+        uses: actions/github-script@v8
+        env:
+          TEAM_NAME: ${{ secrets.DEVELOPER_TEAM }}
+          PR_NUMBER: ${{ steps.pr.outputs.pr_number }}
+        with:
+          github-token: ${{ secrets.GH_ACTIONS_PR_WRITE }}
+          script: |
+            let author = context.payload.pull_request?.user?.login;
+            if (!author) {
+              const { data: pr } = await github.rest.pulls.get({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                pull_number: Number(process.env.PR_NUMBER),
+              });
+              author = pr.user.login;
+            }
+
+            let isTeamMember = false;
+            try {
+              const teamMembership = await github.rest.teams.getMembershipForUserInOrg({
+                org: context.repo.owner,
+                team_slug: process.env.TEAM_NAME,
+                username: author,
+              });
+              isTeamMember = teamMembership.data.state === 'active';
+            } catch (error) {
+              console.log(`Team membership lookup failed for ${author}: ${error.message}`);
+              isTeamMember = false;
+            }
+
+            core.setOutput('is_team_member', isTeamMember ? 'true' : 'false');
+            if (isTeamMember) {
+              core.info(`Author ${author} is a team member; proceeding with review.`);
+            } else {
+              core.info(`Author ${author} is not a member of ${process.env.TEAM_NAME}; skipping review.`);
+            }
+
+  review:
+    runs-on: ubuntu-latest
+    needs: team_check
+    if: ${{ needs.team_check.outputs.is_team_member == 'true' }}
+    timeout-minutes: 60
+    # Advisory check: failures here should not block the PR. The reviewer
+    # posts comments as a best-effort signal; if the pipeline breaks, the
+    # PR author should still be able to merge without a red required check.
+    continue-on-error: true
+
+    steps:
+      # Safe checkout: base repo only, not the untrusted PR head.
+      - name: Checkout target repo base
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event_name == 'pull_request_target' && github.event.pull_request.base.sha || github.sha }}
+          fetch-depth: 0
+          persist-credentials: false
+          path: target-repo
+
+      # Private DevFlow checkout: the PAT/token grants access to this repo's code.
+      - name: Checkout DevFlow
+        uses: actions/checkout@v6
+        with:
+          repository: ${{ env.DEVFLOW_REPOSITORY }}
+          ref: ${{ env.DEVFLOW_REF }}
+          token: ${{ secrets.DEVFLOW_TOKEN }}
+          fetch-depth: 1
+          persist-credentials: false
+          path: devflow
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "0.11.x"
+          enable-cache: true
+
+      - name: Install DevFlow dependencies
+        working-directory: ${{ env.DEVFLOW_PATH }}
+        run: uv sync --frozen
+
+      - name: Run PR review
+        id: review
+        working-directory: ${{ env.DEVFLOW_PATH }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_COPILOT_TOKEN: ${{ secrets.GH_COPILOT_TOKEN }}
+          SK_REPO_PATH: ${{ env.TARGET_REPO_PATH }}
+          AGENT_REPO_PATH: ${{ env.TARGET_REPO_PATH }}
+          PR_URL: ${{ needs.team_check.outputs.pr_url }}
+        run: |
+          uv run python scripts/trigger_pr_review.py \
+            --pr-url "$PR_URL" \
+            --github-username "$GITHUB_ACTOR" \
+            --no-require-comment-selection

.github/workflows/issue-triage.yml

@@ -0,0 +1,199 @@
+name: Issue Triage
+
+on:
+  workflow_dispatch:
+    inputs:
+      issue_number:
+        description: Issue number to triage
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  issues: write
+  id-token: write
+
+concurrency:
+  group: issue-triage-${{ github.repository }}-${{ github.event.issue.number || inputs.issue_number || github.run_id }}
+  cancel-in-progress: true
+
+env:
+  DEVFLOW_REPOSITORY: ${{ vars.DF_REPO }}
+  DEVFLOW_REF: main
+  TARGET_REPO_PATH: ${{ github.workspace }}/target-repo
+  DEVFLOW_PATH: ${{ github.workspace }}/devflow
+
+jobs:
+  team_check:
+    runs-on: ubuntu-latest
+    outputs:
+      is_team_member: ${{ steps.check.outputs.is_team_member }}
+      issue_number: ${{ steps.issue.outputs.issue_number }}
+      repo: ${{ steps.issue.outputs.repo }}
+    steps:
+      - name: Resolve issue metadata
+        id: issue
+        shell: bash
+        env:
+          ISSUE_NUMBER_EVENT: ${{ github.event.issue.number }}
+          ISSUE_NUMBER_INPUT: ${{ inputs.issue_number }}
+        run: |
+          set -euo pipefail
+
+          if [[ "${GITHUB_EVENT_NAME}" == "issues" ]]; then
+            issue_number="${ISSUE_NUMBER_EVENT}"
+          else
+            issue_number="${ISSUE_NUMBER_INPUT}"
+          fi
+
+          if [[ ! "$issue_number" =~ ^[1-9][0-9]*$ ]]; then
+            echo "Could not determine issue number; for workflow_dispatch runs, the 'issue_number' input is required." >&2
+            exit 1
+          fi
+
+          echo "issue_number=${issue_number}" >> "$GITHUB_OUTPUT"
+          echo "repo=${GITHUB_REPOSITORY}" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout scripts
+        uses: actions/checkout@v6
+        with:
+          sparse-checkout: .github/scripts
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: Check issue author team membership
+        id: check
+        uses: actions/github-script@v8
+        env:
+          TEAM_NAME: ${{ secrets.DEVELOPER_TEAM }}
+          ISSUE_NUMBER: ${{ steps.issue.outputs.issue_number }}
+        with:
+          github-token: ${{ secrets.GH_ACTIONS_PR_WRITE }}
+          script: |
+            const checkTeamMembership = require('./.github/scripts/check_team_membership.js');
+            const { author, isTeamMember } = await checkTeamMembership({
+              github,
+              context,
+              core,
+              teamSlug: process.env.TEAM_NAME,
+              issueNumber: process.env.ISSUE_NUMBER,
+            });
+            core.setOutput('is_team_member', isTeamMember ? 'true' : 'false');
+            if (isTeamMember) {
+              core.info(`Author ${author} is a team member; skipping auto-triage.`);
+            } else {
+              core.info(`Author ${author} is not a team member; proceeding with triage.`);
+            }
+
+  triage:
+    runs-on: ubuntu-latest
+    needs: team_check
+    if: ${{ needs.team_check.outputs.is_team_member == 'false' }}
+    environment: integration
+    timeout-minutes: 60
+
+    steps:
+      # Safe checkout: base repo only.
+      - name: Checkout target repo base
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+          path: target-repo
+
+      # Private DevFlow (maf-dashboard) checkout.
+      - name: Checkout DevFlow
+        uses: actions/checkout@v6
+        with:
+          repository: ${{ env.DEVFLOW_REPOSITORY }}
+          ref: ${{ env.DEVFLOW_REF }}
+          token: ${{ secrets.DEVFLOW_TOKEN }}
+          fetch-depth: 1
+          persist-credentials: false
+          path: devflow
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "0.11.x"
+          enable-cache: true
+
+      - name: Install DevFlow dependencies
+        working-directory: ${{ env.DEVFLOW_PATH }}
+        run: uv sync --frozen
+
+      - name: Azure CLI Login
+        uses: azure/login@v2
+        with:
+          client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+
+      - name: Classify issue relevance
+        id: spam
+        working-directory: ${{ env.DEVFLOW_PATH }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SK_REPO_PATH: ${{ env.TARGET_REPO_PATH }}
+          AGENT_REPO_PATH: ${{ env.TARGET_REPO_PATH }}
+          ISSUE_REPO: ${{ needs.team_check.outputs.repo }}
+          ISSUE_NUMBER: ${{ needs.team_check.outputs.issue_number }}
+        run: |
+          uv run python scripts/classify_issue_spam.py \
+            --repo "$ISSUE_REPO" \
+            --issue-number "$ISSUE_NUMBER" \
+            --repo-path "${TARGET_REPO_PATH}" \
+            --apply-labels
+
+      - name: Stop after spam gate
+        if: ${{ steps.spam.outputs.decision != 'allow' }}
+        shell: bash
+        env:
+          SPAM_DECISION: ${{ steps.spam.outputs.decision }}
+        run: |
+          echo "Stopping: spam gate decided: ${SPAM_DECISION}"
+          exit 1
+
+      - name: Reproduce reported issue
+        if: ${{ steps.spam.outputs.decision == 'allow' }}
+        id: repro
+        working-directory: ${{ env.DEVFLOW_PATH }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_COPILOT_TOKEN: ${{ secrets.GH_COPILOT_TOKEN }}
+          SK_REPO_PATH: ${{ env.TARGET_REPO_PATH }}
+          AGENT_REPO_PATH: ${{ env.TARGET_REPO_PATH }}
+          ISSUE_REPO: ${{ needs.team_check.outputs.repo }}
+          ISSUE_NUMBER: ${{ needs.team_check.outputs.issue_number }}
+          # Model-provider settings for generated repro code. Never enter the
+          # agent prompt; consumed by SDK constructors via os.environ. Azure
+          # OpenAI and Foundry auth via AAD from the azure/login step above.
+          OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
+          OPENAI_CHAT_COMPLETION_MODEL: ${{ vars.OPENAI__CHATMODELID }}
+          OPENAI_CHAT_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
+          OPENAI_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
+          OPENAI_EMBEDDING_MODEL: ${{ vars.OPENAI_EMBEDDING_MODEL_ID }}
+          AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+          AZURE_OPENAI_CHAT_COMPLETION_MODEL: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+          AZURE_OPENAI_CHAT_MODEL: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+          AZURE_OPENAI_MODEL: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+          AZURE_OPENAI_EMBEDDING_MODEL: ${{ vars.AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME }}
+          FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
+          FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL }}
+          FOUNDRY_AGENT_NAME: ${{ vars.FOUNDRY_AGENT_NAME }}
+          FOUNDRY_AGENT_VERSION: ${{ vars.FOUNDRY_AGENT_VERSION }}
+          FOUNDRY_MODELS_ENDPOINT: ${{ vars.FOUNDRY_MODELS_ENDPOINT || '' }}
+          FOUNDRY_MODELS_API_KEY: ${{ secrets.FOUNDRY_MODELS_API_KEY || '' }}
+          FOUNDRY_EMBEDDING_MODEL: ${{ vars.FOUNDRY_EMBEDDING_MODEL || '' }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          ANTHROPIC_CHAT_MODEL: ${{ vars.ANTHROPIC_CHAT_MODEL_ID }}
+        run: |
+          uv run python scripts/trigger_issue_repro.py \
+            --repo "$ISSUE_REPO" \
+            --issue-number "$ISSUE_NUMBER" \
+            --github-username "$GITHUB_ACTOR"

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

@@ -87,6 +87,14 @@ jobs:
           -n logical --dist worksteal
           --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@v7
+        with:
+          name: test-results-openai
+          path: ./python/pytest.xml
+          if-no-files-found: ignore
 
   # Azure OpenAI integration tests
   python-tests-azure-openai:
@@ -130,8 +138,16 @@ jobs:
           -n logical --dist worksteal
           --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@v7
+        with:
+          name: test-results-azure-openai
+          path: ./python/pytest.xml
+          if-no-files-found: ignore
 
-  # Misc integration tests (Anthropic, Ollama, MCP)
+  # Misc integration tests (Anthropic, Hyperlight, Ollama, MCP)
   python-tests-misc-integration:
     name: Python Integration Tests - Misc
     runs-on: ubuntu-latest
@@ -162,16 +178,25 @@ jobs:
           fallback_url: ${{ env.LOCAL_MCP_URL }}
       - name: Prefer local MCP URL when available
         run: echo "LOCAL_MCP_URL=${{ steps.local-mcp.outputs.effective_url }}" >> "$GITHUB_ENV"
-      - name: Test with pytest (Anthropic, Ollama, MCP integration)
+      - name: Test with pytest (Anthropic, Hyperlight, Ollama, MCP integration)
         run: >
           uv run pytest --import-mode=importlib
           packages/anthropic/tests
+          packages/hyperlight/tests
           packages/ollama/tests
           packages/core/tests/core/test_mcp.py
           -m integration
           -n logical --dist worksteal
           --timeout=120 --session-timeout=900 --timeout_method thread
           --retries 2 --retry-delay 30
+          --junitxml=pytest.xml
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: test-results-misc
+          path: ./python/pytest.xml
+          if-no-files-found: ignore
       - name: Stop local MCP server
         if: always()
         shell: bash
@@ -248,6 +273,14 @@ jobs:
           -x
           --timeout=360 --session-timeout=900 --timeout_method thread
           --retries 2 --retry-delay 5
+          --junitxml=pytest.xml
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: test-results-functions
+          path: ./python/pytest.xml
+          if-no-files-found: ignore
 
   # Foundry integration tests
   python-tests-foundry:
@@ -294,6 +327,14 @@ jobs:
           -n logical --dist worksteal
           --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@v7
+        with:
+          name: test-results-foundry
+          path: ./python/pytest.xml
+          if-no-files-found: ignore
 
   # Azure Cosmos integration tests
   python-tests-cosmos:
@@ -338,7 +379,80 @@ jobs:
           echo "Cosmos DB emulator did not become ready in time." >&2
           exit 1
       - name: Test with pytest (Cosmos integration)
-        run: uv run --directory packages/azure-cosmos poe integration-tests -n logical --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
+        run: uv run --directory packages/azure-cosmos poe integration-tests -n logical --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5 --junitxml=${{ github.workspace }}/python/pytest.xml
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: test-results-cosmos
+          path: ./python/pytest.xml
+          if-no-files-found: ignore
+
+  # Flaky test trend report (aggregates per-job JUnit XML results)
+  python-flaky-test-report:
+    name: Flaky Test Report
+    if: >
+      always() &&
+      (contains(join(needs.*.result, ','), 'success') ||
+       contains(join(needs.*.result, ','), 'failure'))
+    needs:
+      [
+        python-tests-openai,
+        python-tests-azure-openai,
+        python-tests-misc-integration,
+        python-tests-functions,
+        python-tests-foundry,
+        python-tests-cosmos,
+      ]
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
+          persist-credentials: false
+      - name: Set up python and install the project
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Download all test results from current run
+        uses: actions/download-artifact@v4
+        with:
+          pattern: test-results-*
+          path: test-results/
+      - name: Restore flaky report history cache
+        uses: actions/cache/restore@v4
+        with:
+          path: python/flaky-report-history.json
+          key: flaky-report-history-integration-${{ github.run_id }}
+          restore-keys: |
+            flaky-report-history-integration-
+      - name: Generate trend report
+        run: >
+          uv run python scripts/flaky_report/aggregate.py
+          ../test-results/
+          flaky-report-history.json
+          flaky-test-report.md
+      - name: Post to Job Summary
+        if: always()
+        run: cat flaky-test-report.md >> $GITHUB_STEP_SUMMARY
+      - name: Save flaky report history cache
+        if: always()
+        uses: actions/cache/save@v4
+        with:
+          path: python/flaky-report-history.json
+          key: flaky-report-history-integration-${{ github.run_id }}
+      - name: Upload unified trend report
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: flaky-test-report
+          path: |
+            python/flaky-test-report.md
+            python/flaky-report-history.json
 
   python-integration-tests-check:
     if: always()

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

@@ -65,6 +65,7 @@ jobs:
               - 'python/samples/**/providers/azure/**'
             misc:
               - 'python/packages/anthropic/**'
+              - 'python/packages/hyperlight/**'
               - 'python/packages/ollama/**'
               - 'python/packages/core/agent_framework/_mcp.py'
               - 'python/packages/core/tests/core/test_mcp.py'
@@ -180,6 +181,13 @@ jobs:
           display-options: fEX
           fail-on-empty: false
           title: OpenAI integration test results
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: test-results-openai
+          path: ./python/pytest.xml
+          if-no-files-found: ignore
 
   # Azure OpenAI integration tests
   python-tests-azure-openai:
@@ -243,6 +251,13 @@ jobs:
           display-options: fEX
           fail-on-empty: false
           title: Azure OpenAI integration test results
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: test-results-azure-openai
+          path: ./python/pytest.xml
+          if-no-files-found: ignore
 
   # Misc integration tests (Anthropic, Ollama, MCP)
   python-tests-misc-integration:
@@ -278,10 +293,11 @@ jobs:
           fallback_url: ${{ env.LOCAL_MCP_URL }}
       - name: Prefer local MCP URL when available
         run: echo "LOCAL_MCP_URL=${{ steps.local-mcp.outputs.effective_url }}" >> "$GITHUB_ENV"
-      - name: Test with pytest (Anthropic, Ollama, MCP integration)
+      - name: Test with pytest (Anthropic, Hyperlight, Ollama, MCP integration)
         run: >
           uv run pytest --import-mode=importlib
           packages/anthropic/tests
+          packages/hyperlight/tests
           packages/ollama/tests
           packages/core/tests/core/test_mcp.py
           -m integration
@@ -319,6 +335,13 @@ jobs:
           display-options: fEX
           fail-on-empty: false
           title: Misc integration test results
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: test-results-misc
+          path: ./python/pytest.xml
+          if-no-files-found: ignore
 
   # Azure Functions + Durable Task integration tests
   python-tests-functions:
@@ -390,6 +413,13 @@ jobs:
           display-options: fEX
           fail-on-empty: false
           title: Functions integration test results
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: test-results-functions
+          path: ./python/pytest.xml
+          if-no-files-found: ignore
 
   python-tests-foundry:
     name: Python Integration Tests - Foundry
@@ -407,6 +437,10 @@ jobs:
       FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL }}
       FOUNDRY_AGENT_NAME: ${{ vars.FOUNDRY_AGENT_NAME }}
       FOUNDRY_AGENT_VERSION: ${{ vars.FOUNDRY_AGENT_VERSION }}
+      FOUNDRY_MODELS_ENDPOINT: ${{ vars.FOUNDRY_MODELS_ENDPOINT || '' }}
+      FOUNDRY_MODELS_API_KEY: ${{ secrets.FOUNDRY_MODELS_API_KEY || '' }}
+      FOUNDRY_EMBEDDING_MODEL: ${{ vars.FOUNDRY_EMBEDDING_MODEL || '' }}
+      FOUNDRY_IMAGE_EMBEDDING_MODEL: ${{ vars.FOUNDRY_IMAGE_EMBEDDING_MODEL || '' }}
       LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
     defaults:
       run:
@@ -446,6 +480,13 @@ jobs:
           display-options: fEX
           fail-on-empty: false
           title: Test results
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: test-results-foundry
+          path: ./python/pytest.xml
+          if-no-files-found: ignore
 
   # TODO: Add python-tests-lab
 
@@ -495,7 +536,7 @@ jobs:
           echo "Cosmos DB emulator did not become ready in time." >&2
           exit 1
       - name: Test with pytest (Cosmos integration)
-        run: uv run --directory packages/azure-cosmos poe integration-tests -n logical --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5 --junitxml=pytest.xml
+        run: uv run --directory packages/azure-cosmos poe integration-tests -n logical --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5 --junitxml=${{ github.workspace }}/python/pytest.xml
         working-directory: ./python
       - name: Surface failing tests
         if: always()
@@ -506,6 +547,76 @@ jobs:
           display-options: fEX
           fail-on-empty: false
           title: Cosmos integration test results
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: test-results-cosmos
+          path: ./python/pytest.xml
+          if-no-files-found: ignore
+
+  # Flaky test trend report (aggregates per-job JUnit XML results)
+  python-flaky-test-report:
+    name: Flaky Test Report
+    if: >
+      always() &&
+      (contains(join(needs.*.result, ','), 'success') ||
+       contains(join(needs.*.result, ','), 'failure'))
+    needs:
+      [
+        python-tests-openai,
+        python-tests-azure-openai,
+        python-tests-misc-integration,
+        python-tests-functions,
+        python-tests-foundry,
+        python-tests-cosmos,
+      ]
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up python and install the project
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Download all test results from current run
+        uses: actions/download-artifact@v4
+        with:
+          pattern: test-results-*
+          path: test-results/
+      - name: Restore flaky report history cache
+        uses: actions/cache/restore@v4
+        with:
+          path: python/flaky-report-history.json
+          key: flaky-report-history-merge-${{ github.run_id }}
+          restore-keys: |
+            flaky-report-history-merge-
+      - name: Generate trend report
+        run: >
+          uv run python scripts/flaky_report/aggregate.py
+          ../test-results/
+          flaky-report-history.json
+          flaky-test-report.md
+      - name: Post to Job Summary
+        if: always()
+        run: cat flaky-test-report.md >> $GITHUB_STEP_SUMMARY
+      - name: Save flaky report history cache
+        if: always()
+        uses: actions/cache/save@v4
+        with:
+          path: python/flaky-report-history.json
+          key: flaky-report-history-merge-${{ github.run_id }}
+      - name: Upload unified trend report
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: flaky-test-report
+          path: |
+            python/flaky-test-report.md
+            python/flaky-report-history.json
 
   python-integration-tests-check:
     if: always()

.gitignore

@@ -136,6 +136,10 @@ celerybeat.pid
 .venv
 env/
 venv/
+
+# Foundry agent CLI (contains secrets, auto-generated)
+.foundry-agent.json
+.foundry-agent-build.log
 ENV/
 env.bak/
 venv.bak/
@@ -203,6 +207,8 @@ temp*/
 
 # AI
 .claude/
+.omc/
+.omx/
 WARP.md
 **/memory-bank/
 **/projectBrief.md
@@ -235,3 +241,4 @@ python/dotnet-ref
 
 # Generated filtered solution files (created by eng/scripts/New-FilteredSolution.ps1)
 dotnet/filtered-*.slnx
+**/*.lscache

docs/decisions/0024-codeact-integration.md

@@ -0,0 +1,233 @@
+---
+status: proposed
+contact: eavanvalkenburg
+date: 2026-04-07
+deciders: TBD
+consulted:
+informed:
+---
+
+# CodeAct integration through backend-specific context providers and an `execute_code` tool
+
+## Introduction
+
+**CodeAct** is a pattern in which the model writes executable code — rather than emitting a fixed function-call JSON schema — to plan, transform data, and orchestrate tool calls inside a single sandbox invocation. Instead of requiring a separate model round-trip for every tool call, conditional branch, or data transformation, the model produces a short program that runs in a controlled runtime, calls host-provided tools through a `call_tool(...)` bridge, and returns structured results. This reduces latency, lowers token cost, and lets the model express richer multi-step logic that is difficult to capture in a flat tool-call sequence.
+
+Throughout this ADR, **CodeAct** is the primary term. **Code mode** and **programmatic tool calling** refer to the same capability.
+
+## Context and Problem Statement
+
+We need an architecture design that supports CodeAct in both Python and .NET. This is a necessary capability for the current generation of long-running agents, which need to plan, iterate, transform tool outputs, and execute bounded code inside a controlled runtime — for example, filtering a large result set, computing derived values, or chaining several tool calls with conditional logic — instead of requiring a separate model round-trip for each of those steps. The design should preserve the same behavioral contract across SDKs, but it does not need to use the same internal extension point in each runtime. We also want to standardize on Hyperlight as the initial backend, using the existing Python package and an anticipated .NET binding package once it is available.
+
+Throughout this ADR, **CodeAct** is the primary term. **Code mode** and **programmatic tool calling** refer to the same capability. This ADR uses **CodeAct** consistently.
+
+Model-generated code is treated as untrusted relative to the host process. This ADR assumes the selected backend provides the primary isolation boundary, while the framework is responsible for configuring approvals and capabilities, integrating telemetry, and translating outputs and failures into framework-native shapes. If a backend cannot provide isolation appropriate for its trust model, it is not a suitable CodeAct backend.
+
+The core design question is: **where should CodeAct integrate into the agent pipeline so that both SDKs can offer the same functionality without invasive changes to their core function-calling loops?**
+
+## Decision Drivers
+
+- CodeAct must shape the model-facing surface before model invocation, not only after the model has already chosen tools.
+- The design should let users control which tools are available through CodeAct and which remain regular tools only.
+- The design must preserve existing session, approval, telemetry, and tool invocation behavior as much as possible.
+- The design should define the minimum cross-SDK telemetry and failure semantics for `execute_code`, so Python and .NET do not diverge on basic observability or error handling.
+- The design must fit naturally into the extension points that already exist in each SDK.
+- The design must be safe for concurrent runs and must not rely on mutating shared agent configuration during invocation.
+- The chosen structure should allow multiple backend-specific providers to fit under the same conceptual design over time, even though Hyperlight is the initial target.
+- The abstraction should not assume that every backend is a VM-style sandbox; alternative execution models such as Pydantic's Monty should also fit.
+- The design should allow `execute_code` to be reused both as a tool-enabled CodeAct runtime and as a standard code interpreter tool implementation.
+- The design should remain open to alternative language/runtime modes, such as JavaScript on Hyperlight, rather than baking the abstraction to Python only.
+- The design should provide a portable way to configure sandbox capabilities such as file access and network access, including allow-listed outbound domains.
+- Using CodeAct should be optional, and installing its runtime or backend dependencies should also be optional.
+- Backend-specific dependencies should be isolated behind a small adapter so SDK code is not tightly coupled to an unstable package surface.
+
+## Considered Options
+
+- **Option 1**: Standardize on context provider-based CodeAct with a shared cross-SDK contract and backend-specific public types
+- **Option 2**: Implement CodeAct as a dedicated chat-client decorator/wrapper
+- **Option 3**: Integrate CodeAct directly into the function invocation layer/FunctionInvokingChatClient
+
+## Pros and Cons of the Options
+
+### Option 1: Standardize on context provider-based CodeAct with a shared cross-SDK contract and backend-specific public types
+
+This option uses `ContextProvider` in Python and `AIContextProvider` in .NET, but standardizes the public concept and behavior.
+In this option, the CodeAct tool set is provider-owned: only tools explicitly configured on the concrete CodeAct provider instance are available inside CodeAct, and the provider exposes direct CRUD-style management for tools, file mounts, and outbound network allow-list configuration rather than requiring a separate runtime setup object.
+The agent's direct tool surface remains separate. If a tool should be available both through CodeAct and as a normal direct tool, it is configured in both places.
+
+- Good, because both SDKs already have first-class provider concepts intended for per-invocation context shaping.
+- Good, because providers operate before model invocation, which is where CodeAct must add instructions and reshape tools.
+- Good, because this lets us preserve existing function invocation behavior rather than rewriting it.
+- Good, because slightly different internals are acceptable while the public behavior remains aligned.
+- Good, because convenience builder/decorator helpers can still be added later on top of the provider model without changing the core design.
+- Good, because backend-specific runtime logic can stay inside concrete provider implementations or internal helpers instead of being forced into a lowest-common-denominator public abstraction.
+- Good, because the same provider structure can support either an all-or-nothing tool surface or a mixed side-by-side tool surface.
+- Good, because users can keep some tools direct-only while allowing other tools to be used from inside CodeAct.
+- Good, because a provider-owned CodeAct tool registry avoids mutating or inferring the agent's direct tool surface and can work consistently in both SDKs.
+- Good, because the same conceptual design can remain open to `HyperlightCodeActProvider`, a future `MontyCodeActProvider`, and other backend-specific providers over time.
+- Good, because `execute_code` can evolve into multiple backend-specific runtime modes rather than being hard-wired to one Python-plus-tools mode.
+- Bad, because the provider indirection adds per-run overhead — snapshotting the tool registry, dispatching lifecycle hooks, and building instructions — that a deeper integration point could skip. In practice this overhead is negligible relative to model inference latency and sandbox startup cost.
+
+### Option 2: Implement CodeAct as a dedicated chat-client decorator/wrapper
+
+This option would introduce a CodeAct-specific chat-client decorator that injects instructions and tools directly into the chat request pipeline.
+
+- Good, because this is a natural fit for .NET's `DelegatingChatClient` pipeline.
+- Good, because it can also support advanced custom chat-client stacks.
+- Good, because backend-specific runtime selection could be hidden inside the decorator implementation.
+- Good, because the decorator could also encapsulate mode-specific instruction shaping for tool-enabled versus standalone interpreter behavior.
+- Good, because the decorator can decide per request whether the tool surface is exclusive or mixed.
+- Bad, because Python can support this by building a custom layering stack on top of a `Raw...Client` and swapping in a different `FunctionInvocationLayer`, but that composition path is more manual than the .NET `DelegatingChatClient` pipeline.
+- Bad, because it duplicates responsibilities already handled by provider abstractions.
+- Bad, because it makes CodeAct look more transport-specific than it really is.
+- Bad, because swappable backends and reusable interpreter or language modes become coupled to chat-client composition rather than modeled as first-class CodeAct concepts.
+
+### Option 3: Integrate CodeAct directly into the function invocation layer/FunctionInvokingChatClient
+
+This option would push CodeAct into Python's `FunctionInvocationLayer` and .NET's `FunctionInvokingChatClient` or related middleware.
+
+- Good, because it is close to tool execution and can observe concrete tool invocation behavior.
+- Good, because function middleware may still be useful later for auxiliary auditing or policy around sandbox-originated tool calls.
+- Bad, because this is the wrong layer for constructing the model-facing tool surface and prompt instructions.
+- Bad, because it does not naturally control whether the model sees an exclusive CodeAct tool surface or a mixed side-by-side tool surface.
+- Bad, because it would still require a second mechanism for hiding normal tools and advertising `execute_code`.
+- Bad, because it is a weak fit for standalone interpreter modes where no tool-calling loop is needed.
+- Bad, because backend selection and CodeAct mode behavior are orthogonal concerns that do not belong in the function invocation layer.
+- Bad, because `.NET` would become more tightly coupled to `FunctionInvokingChatClient`, which sits below the agent framework abstraction and is not the natural cross-SDK design seam.
+
+## Approval Model Options
+
+- **Option A**: Bundled approval for the `execute_code` invocation
+- **Option B**: Pre-execution inspection of `call_tool(...)` references before approving `execute_code`
+- **Option C**: Nested per-tool approvals during `execute_code`
+
+## Pros and Cons of the Approval Options
+
+### Option A: Bundled approval for the `execute_code` invocation
+
+This option grants approval once, before `execute_code` starts. Provider-owned tool calls made from inside that execution run under the same approval. The effective approval of `execute_code` is determined up front from the provider configuration rather than from inspecting which tools are actually called during execution.
+
+- Good, because it is the simplest model to explain and implement consistently in both SDKs.
+- Good, because it fits naturally with long-running CodeAct loops where repeated approval interruptions would be disruptive.
+- Good, because it does not require static code analysis before execution begins.
+- Good, because it keeps the first release focused on the provider integration rather than a more complex approval engine.
+- Bad, because approval is coarse-grained and may cover more activity than the user expected.
+- Bad, because it provides less visibility into which provider-owned tools or capabilities will be exercised during the run.
+
+### Option B: Pre-execution inspection of `call_tool(...)` references before approving `execute_code`
+
+This option inspects submitted code for statically discoverable `call_tool("tool_name", ...)` references before execution starts and uses that information to shape the approval request.
+
+- Good, because it can show users more detail up front while still keeping approval at a single pre-execution moment.
+- Good, because it matches the common case where tool names are spelled out directly in the generated code.
+- Good, because it can coexist with bundled approval as a more informative variant of the same UX.
+- Bad, because the analysis is inherently best-effort and cannot reliably predict dynamic behavior.
+- Bad, because it requires duplicated parsing or inspection logic that does not replace runtime enforcement.
+
+### Option C: Nested per-tool approvals during `execute_code`
+
+This option requests approval when sandboxed code actually attempts to invoke a provider-owned tool that requires approval.
+
+- Good, because it aligns approval with real behavior rather than predicted behavior.
+- Good, because it gives precise visibility into which provider-owned tools are being used.
+- Good, because it can allow some tool calls while rejecting others within the same execution.
+- Bad, because it interrupts long-running CodeAct flows and can degrade the user experience significantly.
+- Bad, because it requires more complex runtime plumbing and approval UX in both SDKs.
+- Bad, because repeated approval pauses may make CodeAct less useful for the exact long-running scenarios that motivate this feature.
+
+## Decision Outcomes
+
+### Decision 1: Integration seam and public structure
+
+Chosen option: **Option 1: Standardize on provider-based CodeAct with a shared cross-SDK contract and backend-specific public types**, because it is the only option that maps cleanly to both SDKs, lets us reshape instructions and tools before model invocation, and avoids invasive changes to the existing function invocation loops while still allowing multiple backend-specific providers and multiple runtime modes to fit under the same structure later.
+
+### Decision 2: Initial approval model
+
+Chosen option: **Option A: Bundled approval for the `execute_code` invocation**, because it is the smallest approval model that fits both SDKs, works well for long-running CodeAct flows, and does not force us to standardize a more complex inspection or policy engine in the first release.
+
+This follows the spirit of the current Python tool approval flow, where `FunctionTool` uses `approval_mode="always_require" | "never_require"` and the auto-invocation loop escalates the whole batch when any called tool requires approval.
+
+### Design summary
+
+We standardize the **public concept** of CodeAct across SDKs while allowing each SDK to use the extension point that fits it best.
+
+- Python uses a `ContextProvider`.
+- .NET uses an `AIContextProvider`.
+- The term **CodeAct context provider** is used throughout this ADR as a design concept, not as a required public base type. Public SDK APIs should prefer concrete backend-specific types such as `HyperlightCodeActProvider` rather than a public abstract `CodeActContextProvider` or a public `CodeActExecutor` parameter.
+- CodeAct support should ship as an optional package in each SDK rather than as part of the core package, so users who do not need CodeAct do not take on its installation and dependency footprint. That optional package may still depend on a few small, backward-compatible hooks in the host SDK's core agent pipeline.
+- There is no separate runtime setup object in the chosen design. Concrete providers manage their provider-owned CodeAct tool registry, file mounts, and outbound network allow-list configuration directly through CRUD-style methods on the provider itself.
+- At a high level, CodeAct is exposed through backend-specific context providers that contribute an `execute_code` tool, own the CodeAct-specific tool registry, and carry backend capability configuration such as filesystem and network access.
+- The initial approval model is bundled approval for `execute_code`, using the same `approval_mode="always_require" | "never_require"` vocabulary as regular tools.
+- The CodeAct provider exposes a default `approval_mode` for `execute_code`. If the provider default is `always_require`, `execute_code` is always treated as `always_require` regardless of the provider-owned tool registry. If the provider default is `never_require`, the effective approval for `execute_code` is derived from the provider-owned CodeAct tool registry captured for the run.
+- If every provider-owned CodeAct tool in that registry has `approval_mode="never_require"`, `execute_code` is treated as `never_require`. If any provider-owned CodeAct tool in that registry has `approval_mode="always_require"`, `execute_code` is treated as `always_require`, even if the generated code may not end up calling that tool.
+- Approval is granted before `execute_code` starts, and provider-owned tool calls made from inside that execution run under the same approval.
+- Direct-only agent tools do not affect the approval of `execute_code`; only the provider-owned CodeAct tool registry participates in that calculation.
+- This approval model is intentionally conservative. If one sensitive provider-owned tool forces `execute_code` to require approval more often than desired, the mitigation is to keep that tool direct-only or split it into a different provider/tool surface rather than trying to infer per-run tool usage up front.
+- Configuring filesystem and network capability state on the provider, including adding file mounts or outbound network allow-list entries, is itself the approval for those capabilities in the initial model.
+- Each `execute_code` invocation must start from a clean execution state; in-memory variables and other ephemeral interpreter/runtime state must not persist across separate calls. When a provider exposes a workspace, mounted files, or a writable artifact/output area, those files are the supported persistence mechanism across calls and are treated as external state rather than interpreter state.
+- Mutating the provider's tool registry or capability configuration while a run is in flight is allowed, but it only affects subsequent runs. Provider implementations must snapshot the effective state for each run and synchronize concurrent access so shared provider instances remain safe across concurrent runs.
+- The minimum cross-SDK telemetry contract is that `execute_code` is traced as a normal tool invocation nested inside the surrounding agent run, and provider-owned tool calls made from inside CodeAct continue to emit ordinary tool-invocation telemetry. Backend-specific resource metrics are optional extensions, not a required new top-level cross-SDK event model.
+- Timeout, out-of-memory, backend crash, and similar sandbox failures are all execution failures of `execute_code` and should surface as structured error results rather than backend-specific public DTOs. Partial textual or file outputs may be returned only when the backend can report them unambiguously; callers must not rely on partial-output recovery as a portable guarantee.
+- The provider-based structure preserves room for future pre-execution inspection and nested per-tool approvals if later experience shows they are needed.
+- Concrete backend-specific providers may still use small SDK-local helpers or adapters internally, but that split is an implementation detail rather than a public API requirement.
+
+Detailed language-specific implementation notes are specified in:
+
+- [Python implementation](../features/code_act/python-implementation.md)
+- [.NET implementation](../features/code_act/dotnet-implementation.md)
+
+### Minimal core hooks required by the optional package
+
+CodeAct remains optional at the package level, but the optional package depends on a small number of hooks that must live in the host SDK because the agent pipeline owns model invocation and per-run tool resolution.
+
+- Python depends on the existing `ContextProvider` lifecycle, `SessionContext.extend_instructions(...)`, `SessionContext.extend_tools(...)`, per-run runtime tool access via `SessionContext.options["tools"]`, and the shared `ApprovalMode` vocabulary used by `FunctionTool`.
+- .NET depends on the existing `AIContextProvider` seam, agent/runtime support for applying providers before model invocation, and the existing chat-client or function-invocation seams that concrete implementations use to contribute `execute_code`.
+
+These hooks are backward-compatible because they only expose or forward per-run state that core already owns. Behavior changes only when a concrete CodeAct provider opts in and uses them.
+
+### Concrete provider implementation contract
+
+The design does not require a public abstract `CodeActContextProvider` base class, but it does require a stable implementation contract for concrete providers.
+
+- Concrete providers should expose a standard capability surface at construction time, with SDK-appropriate naming for:
+  - approval mode
+  - workspace root
+  - file mounts
+  - allowed outbound targets plus any per-target method or policy restrictions needed by the backend
+- Separate public `filesystem_mode` / `network_mode` flags are not required by the cross-SDK contract. Filesystem access may be disabled implicitly until a workspace or file mounts are configured, and outbound network may be disabled implicitly until an allow-list or equivalent outbound policy entry is configured.
+- Concrete providers should expose direct CRUD-style methods for managing the provider-owned CodeAct tool registry, file mounts, and outbound network allow-list configuration, rather than requiring callers to construct a separate runtime setup object.
+- Concrete providers should implement their host SDK's provider lifecycle hooks to:
+  - build CodeAct instructions,
+  - add `execute_code`,
+  - snapshot the effective CodeAct tool registry and capability settings for the run,
+  - compute the effective approval requirement for `execute_code`,
+  - configure file access and network access for the backend,
+  - prepare or restore execution state,
+  - execute code,
+  - and translate backend output into framework-native content.
+- Any internal abstract/helper surface shared by multiple concrete providers should standardize responsibilities for:
+  - instruction construction,
+  - file-access configuration,
+  - network-access configuration,
+  - environment preparation/restoration,
+  - code execution,
+  - and output-to-content conversion.
+- Backend execution output should reuse existing framework-native content/message primitives rather than introducing backend-specific public result DTOs.
+
+## More Information
+
+### Related artifacts
+
+- Python implementation: [`docs/features/code_act/python-implementation.md`](../features/code_act/python-implementation.md)
+- .NET implementation: [`docs/features/code_act/dotnet-implementation.md`](../features/code_act/dotnet-implementation.md)
+- Python provider/session APIs: [`python/packages/core/agent_framework/_sessions.py`](../../python/packages/core/agent_framework/_sessions.py)
+- Python function invocation loop: [`python/packages/core/agent_framework/_tools.py`](../../python/packages/core/agent_framework/_tools.py)
+- .NET context provider abstraction: [`dotnet/src/Microsoft.Agents.AI.Abstractions/AIContextProvider.cs`](../../dotnet/src/Microsoft.Agents.AI.Abstractions/AIContextProvider.cs)
+- .NET agent integration for context providers: [`dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs`](../../dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs)
+- Optional .NET chat-client provider decorator: [`dotnet/src/Microsoft.Agents.AI/AIContextProviderDecorators/AIContextProviderChatClient.cs`](../../dotnet/src/Microsoft.Agents.AI/AIContextProviderDecorators/AIContextProviderChatClient.cs)
+- .NET function invocation middleware seam: [`dotnet/src/Microsoft.Agents.AI/FunctionInvocationDelegatingAgentBuilderExtensions.cs`](../../dotnet/src/Microsoft.Agents.AI/FunctionInvocationDelegatingAgentBuilderExtensions.cs)
+
+### Related decisions
+
+- [0015-agent-run-context](0015-agent-run-context.md)
+- [0016-python-context-middleware](0016-python-context-middleware.md)

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

@@ -0,0 +1,454 @@
+---
+status: proposed
+contact: evmattso
+date: 2026-04-10
+deciders: evmattso
+---
+
+# Foundry Toolbox Support in FoundryChatClient
+
+## What is the goal of this feature?
+
+Enable Agent Framework users to consume Foundry **toolboxes** — named, versioned bundles of tool definitions stored server-side in an Azure AI Foundry project — directly from `FoundryChatClient`, without dropping to the raw `azure-ai-projects` SDK.
+
+A user who has configured a toolbox in the Foundry portal (or via the raw SDK) should be able to load it into an agent with a single call:
+
+```python
+toolbox = await client.get_toolbox("research_tools")
+agent = Agent(client=client, instructions="...", tools=toolbox)
+```
+
+**Success metric:** an agent can consume a toolbox with no manual handling of version-resolution logic on the user's side.
+
+## What is the problem being solved?
+
+`azure-ai-projects==2.1.0a20260409002` ships a new `BetaToolboxesOperations` surface, reachable as `AIProjectClient.beta.toolboxes` on the raw SDK client (and therefore as `FoundryChatClient.project_client.beta.toolboxes` through our wrapper), that lets teams:
+- Group related hosted tools (code interpreter, file search, MCP, web search, etc.) under a named toolbox
+- Version toolboxes immutably, so agents can pin to a specific configuration for production stability
+- Share toolboxes across multiple agents in a project
+
+However, consuming a toolbox from the framework today requires:
+1. Knowing the raw SDK accessor path (`client.project_client.beta.toolboxes`)
+2. Making two calls for the common case — `.get(name)` to find the default version, then `.get_version(name, version)` to actually retrieve tools
+3. Manually unpacking `toolbox.tools` before passing them to `Agent(tools=...)`
+
+None of this is hard, but it's the kind of boilerplate that should live in the client. Every other hosted tool in `FoundryChatClient` (code interpreter, file search, web search, image generation, MCP) already has a factory method (`get_code_interpreter_tool()`, etc.). Toolbox support should fit the same shape on the chat-client composition surface.
+
+## API Changes
+
+### One new method on the FoundryChatClient surface
+
+The public toolbox-consumption surface lands on:
+
+- `RawFoundryChatClient` (inherited by `FoundryChatClient`) in `_chat_client.py`
+
+The implementation delegates to shared helper functions in `_tools.py` so there is a single source of truth for the SDK calls.
+
+**Scope note:** `FoundryAgent` is intentionally not part of this design. `FoundryAgent` is the runtime surface for invoking an already-configured server-side Foundry agent; if that agent should use a toolbox, the toolbox/tools should already be configured on the Foundry side (UI or `azure-ai-projects` authoring flow) before MAF connects to it.
+
+**Scope note:** Authoring a server-side agent whose definition references a toolbox (via `PromptAgentDefinition(tools=toolbox.tools, ...)` + `client.agents.create_version(...)`) is deliberately outside MAF scope. That is an `azure-ai-projects` / service-resource authoring concern, not a future MAF feature. Users who need it should use the raw Azure SDK directly.
+
+```python
+async def get_toolbox(
+    self,
+    name: str,
+    *,
+    version: str | None = None,
+) -> ToolboxVersionObject:
+    """Fetch a Foundry toolbox by name.
+
+    If ``version`` is ``None``, resolves the toolbox's current default version
+    (two requests). If ``version`` is specified, fetches that version directly
+    (single request).
+
+    :param name: The name of the toolbox.
+    :param version: Optional immutable version identifier to pin to.
+    :return: A ``ToolboxVersionObject``. Pass its ``tools`` attribute to
+        ``Agent(tools=toolbox.tools)``.
+    :raises azure.core.exceptions.ResourceNotFoundError: If the toolbox or
+        version does not exist.
+    """
+
+```
+
+### Return types: raw SDK models, no custom wrappers
+
+Methods return the `azure.ai.projects.models` types directly:
+
+- `get_toolbox()` → `ToolboxVersionObject` (has `.name`, `.version`, `.tools`, `.id`, `.created_at`, `.description`, `.metadata`, `.policies`)
+
+No custom wrapper classes are defined. Returning the SDK types directly:
+- Eliminates maintenance overhead of keeping a custom wrapper aligned with SDK changes
+- Matches the existing convention — `get_code_interpreter_tool()` returns the raw `CodeInterpreterTool` SDK type
+- Means any new fields the SDK adds to these types flow through automatically
+
+`Agent(..., tools=...)` will accept the fetched toolbox object directly by flattening to `toolbox.tools` internally.
+
+### Design decisions
+
+**Instance methods, not `@staticmethod` factories.** Existing `get_code_interpreter_tool()` / `get_mcp_tool()` / etc. are `@staticmethod` because they're pure factories with no network I/O. Toolbox fetching requires the project client, so these new methods must be instance methods. This is a deliberate departure from the existing-factory pattern, justified by the async-with-I/O nature of the operation.
+
+**Raw SDK type passthrough (no custom wrappers).** There is only one toolbox type in the Foundry SDK and maintaining a shadow wrapper would create alignment risk as the SDK evolves. The raw `ToolboxVersionObject` and `ToolboxObject` carry all the fields users need. Individual tools inside `toolbox.tools` are the same `azure.ai.projects.models.Tool` subclasses returned by other factory methods.
+
+**Two-request default-version path.** When `version=None`, implementation calls `.get(name)` to find `default_version`, then `.get_version(name, default_version)` for the tools. Caching the default-version mapping was considered and rejected — default versions can change server-side via `update(default_version=...)`, and a stale cache would silently give callers the wrong tools. Two requests at agent setup is acceptable.
+
+**No discovery/listing surface in MAF.** Discovery is intentionally left to the raw `azure-ai-projects` client. MAF does not currently expose project-resource listing surfaces for many other Foundry resources (deployments, vector stores, agents, etc.), so the toolbox design stays narrowly focused on explicit retrieval by name/version.
+
+**Shared helpers in `_tools.py`.** The SDK-call helper function (`fetch_toolbox`) lives in a shared module so the chat-client surface stays thin and the request logic remains centralized.
+
+**`tools=toolbox` convenience, not a new wrapper type.** Although `get_toolbox()` returns the raw `ToolboxVersionObject`, Agent Framework can still support `tools=toolbox` / `tools=[toolbox]` by flattening the toolbox's `.tools` internally. That matches existing SDK ergonomics where some higher-level objects can be placed directly in `tools=` and unpacked underneath, without introducing a public `FoundryToolbox` wrapper.
+
+**Errors pass through unchanged.** `ResourceNotFoundError`, `HttpResponseError`, etc. from the SDK propagate as-is. No framework-specific exception hierarchy.
+
+## E2E Code Samples
+
+### Primary sample
+
+New file: `samples/02-agents/providers/foundry/foundry_chat_client_with_toolbox.py`
+
+```python
+import asyncio
+
+from agent_framework import Agent
+from agent_framework.foundry import FoundryChatClient
+from azure.identity import AzureCliCredential
+
+
+async def main() -> None:
+    client = FoundryChatClient(credential=AzureCliCredential())
+
+    toolbox = await client.get_toolbox("research_tools")
+    print(f"Loaded toolbox {toolbox.name}@{toolbox.version} ({len(toolbox.tools)} tools)")
+
+    agent = Agent(
+        client=client,
+        instructions="You are a research assistant.",
+        tools=toolbox,
+    )
+
+    result = await agent.run("What are the latest developments in quantum error correction?")
+    print(f"Result: {result}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Version pinning
+
+```python
+toolbox = await client.get_toolbox("research_tools", version="v3")
+```
+
+### Combining multiple toolboxes
+
+```python
+toolbox_a = await client.get_toolbox("research_tools")
+toolbox_b = await client.get_toolbox("some_other_tools", version="v3")
+
+agent = Agent(
+    client=client,
+    instructions="...",
+    tools=[toolbox_a, toolbox_b],
+)
+```
+
+### Combining toolbox tools with locally defined tools
+
+```python
+toolbox = await client.get_toolbox("research_tools")
+
+def get_internal_metrics(metric_name: str) -> dict:
+    """Custom tool that reads from an internal dashboard."""
+    ...
+
+agent = Agent(
+    client=client,
+    instructions="...",
+    tools=[get_internal_metrics, toolbox],
+)
+```
+
+### Selecting only some tools from a toolbox
+
+Developers will not always want to pass the entire toolbox through unchanged. A
+small helper in the Foundry package provides local post-fetch selection without
+changing the raw return type of `get_toolbox()`.
+
+```python
+from agent_framework.foundry import select_toolbox_tools
+
+toolbox = await client.get_toolbox("research_tools")
+
+selected_tools = select_toolbox_tools(
+    toolbox,
+    include_names=["githubmcp", "code_interpreter"],
+)
+
+agent = Agent(
+    client=client,
+    instructions="Use only the selected toolbox tools.",
+    tools=selected_tools,
+)
+```
+
+Supported filters:
+
+```python
+from agent_framework.foundry import FoundryHostedToolType, select_toolbox_tools
+
+selected_tools = select_toolbox_tools(
+    toolbox,
+    include_types=["mcp", "code_interpreter"],  # type: Collection[FoundryHostedToolType]
+    exclude_names=["internal_admin_tool"],
+)
+```
+
+Helper signature:
+
+```python
+type FoundryHostedToolType = Literal[
+    "code_interpreter",
+    "file_search",
+    "image_generation",
+    "mcp",
+    "web_search",
+] | str
+
+def select_toolbox_tools(
+    tools: ToolboxVersionObject | Sequence[Tool | dict[str, Any]],
+    *,
+    include_names: Collection[str] | None = None,
+    exclude_names: Collection[str] | None = None,
+    include_types: Collection[FoundryHostedToolType] | None = None,
+    exclude_types: Collection[FoundryHostedToolType] | None = None,
+    predicate: Callable[[Tool | dict[str, Any]], bool] | None = None,
+) -> list[Tool | dict[str, Any]]:
+    ...
+```
+
+Normalized name precedence for `include_names` / `exclude_names`:
+
+1. MCP `server_label`
+2. generic tool `name`
+3. fallback tool `type`
+
+This keeps `get_toolbox()` as a thin fetch API and makes selection an explicit,
+local post-processing step, while still allowing the ergonomic
+`select_toolbox_tools(toolbox, ...)` call shape.
+
+## Native vs MCP consumption of a Foundry toolbox
+
+A Foundry toolbox can be consumed two ways. This design adds new implementation work only for the first:
+
+1. **Native consumption (in scope).** Tools execute inside Foundry's agent runtime. `get_toolbox()` returns the `ToolboxVersionObject` whose `.tools` attribute carries typed tool configs that the runtime interprets server-side. This design is specifically for `FoundryChatClient`-backed local agent composition.
+
+2. **MCP consumption (already supported through existing MCP abstractions).** A Foundry toolbox can also be exposed as an MCP server. In that case, use the existing `MCPStreamableHTTPTool(name=..., url=...)` — it already handles this path with any chat client (Foundry, OpenAI, Anthropic, etc.). No new Foundry-specific API is needed for MCP-exposed toolboxes in this design.
+
+### MCPStreamableHTTPTool example for a Foundry toolbox endpoint
+
+If Foundry gives you an MCP endpoint for the toolbox (for example from the
+toolbox details UI / endpoint surface), the existing MCP client path is:
+
+```python
+from agent_framework import Agent, MCPStreamableHTTPTool
+from agent_framework.openai import OpenAIChatClient
+
+toolbox_mcp = MCPStreamableHTTPTool(
+    name="research_tools",
+    url="https://<foundry-toolbox-mcp-endpoint>",
+)
+
+agent = Agent(
+    client=OpenAIChatClient(),
+    instructions="You are a research assistant.",
+    tools=[toolbox_mcp],
+)
+```
+
+This is a different integration shape than `get_toolbox(...).tools`:
+
+- `get_toolbox(...).tools` = **native Foundry hosted-tool configs** interpreted by the
+  Foundry runtime
+- `MCPStreamableHTTPTool(name=..., url=...)` = **live MCP server connection** to a
+  toolbox endpoint
+
+The design in this spec adds first-class support only for the native hosted-tool
+path. The MCP path is already served by the framework's existing MCP abstractions.
+
+These paths are not unified because they have fundamentally different execution models. Native toolbox tools are declarative configs the Foundry runtime executes; MCP consumption is a live wire protocol to a running server.
+
+**MCP authentication inside a toolbox** is handled server-side via `project_connection_id` on individual `MCPTool` entries (OAuth connection objects configured in the Foundry project). The client never holds bearer tokens. Consent flow handling (`CONSENT_REQUIRED` → user-visible consent URL) happens during `agent.run()`, not during toolbox fetching — see Non-goals.
+
+## Testing Strategy
+
+Unit tests in `packages/foundry/tests/test_toolbox.py` with mocked `project_client.beta.toolboxes`. A single opt-in live round-trip, `test_integration_get_toolbox_round_trip_against_real_project`, is marked `@pytest.mark.integration`; it is skipped by default and only runs when the required Foundry credentials are available.
+
+Coverage:
+
+- `get_toolbox(name, version="v3")` — explicit version, single request. Assert `.get` not called, `.get_version` awaited once, returns `ToolboxVersionObject`.
+- `get_toolbox(name)` — default-version resolution. Assert `.get` then `.get_version` called in order with correct args.
+- Error propagation — `ResourceNotFoundError` from `.get` propagates unchanged.
+- Tool passthrough — heterogeneous tool list (`CodeInterpreterTool`, `MCPTool(project_connection_id=...)`) passes through unchanged. Asserts `project_connection_id` survives.
+- Agent integration smoke — `tools=toolbox` / `tools=[toolbox]` flatten to the underlying toolbox tools.
+- Multiple toolbox composition smoke — `tools=[toolbox_a, toolbox_b]` flattens into a single agent tool list.
+- `get_toolbox_tool_name()` — selection-name precedence is MCP `server_label`, then `name`, then `type`.
+- `select_toolbox_tools(toolbox, include_names=...)` — selects by normalized tool names directly from a fetched toolbox object.
+- `select_toolbox_tools(toolbox, include_types=...)` — selects by tool types with `Literal`-guided IDE completion.
+- `select_toolbox_tools(..., exclude_names=..., predicate=...)` — supports exclusion + custom predicates.
+
+Deliberately **not** covered:
+- Runtime consent-flow handling for OAuth MCP tools (see Non-goals).
+- Toolbox discovery/listing (`list_toolboxes`, `list_toolbox_versions`) — deliberately left to the raw Azure SDK.
+- Full CRUD (`create_version`, `update`, `delete`) and server-side agent authoring — see Non-goals.
+
+Live Foundry API integration is exercised only through the opt-in `@pytest.mark.integration` round-trip noted above; it is not part of the default test run.
+
+## Framework dependency: `normalize_tools` flattening
+
+The core `normalize_tools` function in `packages/core/agent_framework/_tools.py` already supports flattening composite tool inputs. Toolbox support extends that behavior so a fetched `ToolboxVersionObject` is treated as a composite tool source and flattened to its `.tools`.
+
+That enables:
+
+- `tools=toolbox`
+- `tools=[toolbox]`
+- `tools=[local_tool, toolbox]`
+- `tools=[toolbox_a, toolbox_b]`
+
+while still keeping `select_toolbox_tools(toolbox.tools, ...)` available for partial selection before the final agent construction step.
+
+## Telemetry
+
+Telemetry for toolbox support has two separate goals:
+
+1. **Observe toolbox API access** — `get_toolbox()`
+2. **Observe toolbox usage during agent runs** — when users pass toolbox-derived tools into `Agent(..., tools=...)`
+
+### Request telemetry for toolbox API access
+
+When Agent Framework constructs the `AIProjectClient` internally for `FoundryChatClient`, it already sets:
+
+```python
+user_agent=AGENT_FRAMEWORK_USER_AGENT
+```
+
+That means toolbox API requests made through:
+
+- `project_client.beta.toolboxes.get(...)`
+- `project_client.beta.toolboxes.get_version(...)`
+
+carry the standard MAF user-agent marker and can be queried in backend request logs the same way as other Foundry SDK calls made through framework-owned clients.
+
+Important constraint: if the caller passes an already-constructed `project_client`, Agent Framework does **not** mutate it to inject the MAF user-agent. In that case, toolbox API request telemetry reflects whatever user-agent behavior that external client was configured with.
+
+### Runtime telemetry for toolbox usage on agent runs
+
+Tool-level telemetry already captures which hosted Foundry tools are available / invoked during agent execution. The remaining gap is **toolbox provenance**: once the user writes `tools=toolbox` (or otherwise flattens the toolbox into tool configs), the framework sees only raw tool configs and no longer knows which toolbox name/version supplied them.
+
+The design for closing the **client-side** observability gap is **internal provenance tracking**, not user-supplied metadata and not a new public wrapper type.
+
+#### Provenance model
+
+Note: this section is still under investigation.
+
+When `get_toolbox()` or `list_toolbox_versions()` returns a `ToolboxVersionObject`, Agent Framework will attach private provenance metadata to:
+
+- the returned toolbox object
+- each tool inside `toolbox.tools`
+
+Recommended shape (private, internal-only):
+
+```python
+tool._maf_toolbox_sources = [
+    {
+        "id": toolbox.id,
+        "name": toolbox.name,
+        "version": toolbox.version,
+    }
+]
+```
+
+Key properties of this approach:
+
+- **No new public API surface** — users still work with raw `ToolboxVersionObject` / `ToolboxObject`
+- **No user burden** — callers do not need to stamp metadata manually
+- **Provenance follows the tool objects** — works with:
+  - `tools=toolbox.tools`
+  - `tools=[toolbox_a.tools, toolbox_b.tools]`
+  - `tools=[*toolbox_a.tools, *toolbox_b.tools]`
+- **Private attributes are not serialized** into the actual request payload sent to the model/service, so this metadata does not leak into the tool definition body
+
+This is intentionally preferred over introducing a new public `FoundryToolbox` wrapper purely for telemetry, and preferred over a separate global provenance registry. The provenance lives on the existing tool objects so list-copying and chat-option merging naturally preserve it.
+
+#### Span enrichment
+
+When Agent / chat telemetry computes span attributes for a run, it should inspect the final tool list and aggregate the private toolbox provenance from any tool objects that carry it. The aggregated values are then emitted as attributes on the existing run/chat spans.
+
+Suggested custom attributes:
+
+- `agent_framework.foundry.toolbox.ids`
+- `agent_framework.foundry.toolbox.names`
+- `agent_framework.foundry.toolbox.versions`
+- or a single compact attribute such as `agent_framework.foundry.toolbox.sources=["research_tools@1","some_other_tools@3"]`
+
+The single compact `toolbox.sources` form is preferred for initial implementation because it is easy to query and easy to render from combined tool lists.
+
+#### Scope of telemetry changes
+
+This design does **not** require new spans. It enriches existing telemetry:
+
+- toolbox API access continues to rely on request logs + Azure SDK distributed tracing + MAF user-agent
+- agent/chat execution spans gain toolbox provenance attributes when toolbox-derived tools are present
+
+Implementation-wise, this design most likely touches:
+
+- `packages/foundry/agent_framework_foundry/_tools.py` — to stamp provenance on fetched toolbox objects / tools
+- `packages/core/agent_framework/observability.py` — to aggregate provenance into span attributes
+
+#### Important limitation: no server-side toolbox telemetry solution yet
+
+Private provenance attached to tool objects is only useful on the client side. It
+does **not** go over the wire to the Foundry service because those private fields
+are intentionally not serialized into the request payload.
+
+That means this design can support:
+
+- local OpenTelemetry / exporter spans emitted by Agent Framework
+- local attribution of a run to one or more fetched toolboxes
+
+but it does **not** solve:
+
+- server-side request-log attribution of a model/tool run back to a toolbox
+- backend/database queries that need the service itself to know "this tool came from toolbox X"
+
+At the moment, we do not have a satisfactory design for server-side toolbox
+telemetry. The service would require additional structured information on the
+request, and there is no accepted mechanism in this design yet for projecting
+toolbox provenance into a server-visible field/header/metadata shape.
+
+So the telemetry story in this spec is explicitly limited to **client-side
+toolbox telemetry**. Server-side toolbox attribution remains an open question and
+requires either:
+
+- new service/API support, or
+- a later framework design for emitting additional server-visible request metadata.
+
+#### Deliberate non-goals for telemetry
+
+- No requirement for users to pass explicit toolbox metadata in `default_options["metadata"]` or `run(..., options=...)`
+- No new public `FoundryToolbox` wrapper type just to preserve attribution
+- No attempted server-side attribution mechanism in this design (for example a custom request header or request metadata field) until there is a validated end-to-end contract for it
+
+## Non-goals / Future Work
+
+Explicitly out of scope for this design. Each is a separate design and PR when needed.
+
+1. **Create/update/delete toolboxes from code.** CRUD is rare in agent consumption flows. Users who need it drop to `client.project_client.beta.toolboxes.create_version(...)`, `.update(...)`, `.delete(...)` directly.
+
+2. **Server-side agent authoring from toolbox.** Creating a `PromptAgentDefinition(tools=toolbox.tools)` + `client.agents.create_version(...)` is a future feature covering agent authoring from code. The toolbox read API provides the building blocks; the authoring helpers are a separate design.
+
+3. **OAuth consent-flow runtime handling.** When a toolbox contains MCP tools with `project_connection_id` pointing to an OAuth connection, the runtime may return `CONSENT_REQUIRED` mid-run. This is a runtime concern separate from toolbox fetching.
+
+4. **Live integration tests.** This PR ships unit tests only.
+
+5. **Toolbox caching or refresh APIs.** Each `get_toolbox()` call hits the network. Users who want caching wrap the call themselves.

docs/features/code_act/dotnet-implementation.md

@@ -0,0 +1,625 @@
+# CodeAct .NET implementation
+
+This document describes the .NET realization of the CodeAct design in
+[`docs/decisions/0024-codeact-integration.md`](../../decisions/0024-codeact-integration.md).
+
+This document is intentionally focused on the .NET design and public API surface.
+The initial public .NET type described here is `HyperlightCodeActProvider`. Future .NET backends, such as Monty, should follow the same conceptual model with their own concrete provider types rather than through a public abstract base class or a public executor parameter.
+
+## What is the goal of this feature?
+
+Goals:
+- .NET developers can enable CodeAct through an `AIContextProvider`-based integration.
+- Developers can configure a provider-owned CodeAct tool set that is separate from the agent's direct tool surface.
+- Developers can use the same `execute_code` concept for both tool-enabled CodeAct and a standard code interpreter tool implementation.
+- Developers can swap execution backends over time, starting with Hyperlight while keeping room for alternatives.
+- Developers can configure execution capabilities such as workspace mounts and outbound network allow lists in a portable way.
+
+Success Metric:
+- .NET samples exist for both a tool-enabled CodeAct mode and a standard interpreter mode.
+
+Implementation-free outcome:
+- A .NET developer can attach a backend-specific CodeAct provider, choose which tools are available inside CodeAct, and configure execution capabilities without rewriting the function invocation loop or ChatClient pipeline.
+
+## What is the problem being solved?
+
+The cross-SDK problem statement and decision rationale live in the [ADR](../../decisions/0024-codeact-integration.md). The items below narrow that statement to .NET-specific design concerns:
+
+- Today, the easiest way to prototype CodeAct in .NET is to manually configure an `AIFunction` and wire instructions — this is fragile and requires understanding internal sandbox lifecycle details.
+- There is no first-class .NET design that simultaneously covers Hyperlight-backed CodeAct now, future backend-specific providers, and both tool-enabled and interpreter modes.
+- Sandbox capabilities such as mounted file access and outbound network access need a portable configuration model instead of ad hoc backend-specific wiring.
+- Approval behavior needs to be explicit and configurable, mapping to .NET's existing `ApprovalRequiredAIFunction` wrapper mechanism.
+
+## API Changes
+
+### CodeAct contract
+
+#### Terminology
+
+- **CodeAct** is the primary term.
+- `execute_code` is the model-facing tool name used by the initial .NET provider in this spec.
+- Tool-enabled versus interpreter behavior is derived from the presence of CodeAct-managed tools, not from a separate public profile object.
+
+#### Provider-owned CodeAct tool registry
+
+A concrete .NET CodeAct provider owns the set of tools available through `call_tool(...)` inside CodeAct.
+
+Rules:
+- Only tools explicitly configured on the concrete provider instance are available inside CodeAct.
+- The provider must not infer its CodeAct-managed tool set from the agent's direct tool configuration (`ChatClientAgentOptions.Tools` or `AIContext.Tools`).
+- Exclusive versus mixed behavior is achieved by where tools are configured, not by rewriting the agent's direct tool list.
+
+Implications:
+- **CodeAct-only tool**: configured on the concrete CodeAct provider only.
+- **Direct-only tool**: configured on the agent only.
+- **Tool available both ways**: configured on both the agent and the concrete CodeAct provider.
+
+#### Managing tools and capabilities after provider construction
+
+There is no separate runtime setup object in the .NET design. CodeAct tools, file mounts, and outbound network allow-list state are managed directly on the provider through CRUD-style registry methods.
+
+Preferred pattern:
+- `AddTools(params AIFunction[] tools) -> void`
+- `GetTools() -> IReadOnlyList<AIFunction>`
+- `RemoveTools(params string[] names) -> void`
+- `ClearTools() -> void`
+- `AddFileMounts(params FileMount[] mounts) -> void`
+- `GetFileMounts() -> IReadOnlyList<FileMount>`
+- `RemoveFileMounts(params string[] mountPaths) -> void`
+- `ClearFileMounts() -> void`
+- `AddAllowedDomains(params AllowedDomain[] domains) -> void`
+- `GetAllowedDomains() -> IReadOnlyList<AllowedDomain>`
+- `RemoveAllowedDomains(params string[] targets) -> void`
+- `ClearAllowedDomains() -> void`
+
+Requirements:
+- The provider-owned CodeAct tool registry is keyed by tool name (from `AIFunction.Name`).
+- `AddTools(...)` adds new tools and replaces an existing provider-owned registration when the same tool name is added again.
+- `GetTools()` returns the provider's current configured CodeAct tool registry.
+- `RemoveTools(...)` removes provider-owned CodeAct tools by name.
+- `ClearTools()` removes all provider-owned CodeAct tools.
+- File mounts are keyed by sandbox mount path.
+- `AddFileMounts(...)` adds new file mounts and replaces an existing mount when the same mount path is added again.
+- `GetFileMounts()` returns the provider's current configured file mounts.
+- `RemoveFileMounts(...)` removes file mounts by mount path.
+- `ClearFileMounts()` removes all configured file mounts.
+- Allowed domains are keyed by normalized target string.
+- `AddAllowedDomains(...)` adds allow-list entries and replaces an existing entry when the same target is added again.
+- `GetAllowedDomains()` returns the current outbound allow-list entries.
+- `RemoveAllowedDomains(...)` removes allow-list entries by target.
+- `ClearAllowedDomains()` removes all configured allow-list entries.
+- Tool, file-mount, and network-allow-list mutations affect subsequent runs only; runs already in progress keep the snapshot captured at run start.
+- The provider must snapshot its effective tool registry and capability state at the start of each run so concurrent execution remains deterministic.
+
+#### Approval model
+
+The initial .NET design follows the ADR's bundled approval decision and maps to the existing `ApprovalRequiredAIFunction` wrapper from `Microsoft.Extensions.AI.Abstractions`:
+
+- The provider exposes a default `ApprovalMode` for `execute_code` (enum: `CodeActApprovalMode.AlwaysRequire` / `CodeActApprovalMode.NeverRequire`).
+
+Effective `execute_code` approval is computed as follows:
+
+- If the provider default is `AlwaysRequire`, `execute_code` requires approval.
+- If the provider default is `NeverRequire`, the provider evaluates the provider-owned CodeAct tool registry snapshot for that run.
+  - If every provider-owned CodeAct tool in that snapshot is not an `ApprovalRequiredAIFunction`, `execute_code` does not require approval.
+  - If any provider-owned CodeAct tool in that snapshot is an `ApprovalRequiredAIFunction`, `execute_code` requires approval, even if the generated code may not call that tool.
+- When the effective approval resolves to `AlwaysRequire`, the generated `execute_code` function is wrapped in `ApprovalRequiredAIFunction` before being added to the `AIContext.Tools`.
+- Provider-owned tool calls made through `call_tool(...)` during that execution run use the approval already determined for `execute_code`.
+- Direct-only agent tools are excluded from this calculation.
+- File and network capabilities do not create a separate runtime approval check in the initial model; configuring them on the provider is itself the approval for those capabilities.
+
+This is intentionally conservative and matches the shape of the existing .NET function-tool approval flow, where `ApprovalRequiredAIFunction` signals to the `ChatClientAgent` that user approval is needed before invocation.
+
+#### Shared execution flow
+
+On each run:
+1. `ProvideAIContextAsync(...)` snapshots the current CodeAct-managed tool registry and capability settings.
+2. Computes the effective approval requirement for `execute_code` from the provider default plus the snapshotted tool registry.
+3. Builds provider-defined instructions.
+4. Builds a run-scoped `execute_code` `AIFunction` from the snapshot (optionally wrapped in `ApprovalRequiredAIFunction`).
+5. Returns an `AIContext` containing the instructions and `execute_code` tool.
+6. When `execute_code` is invoked by the model, the run-scoped function creates or reuses an execution environment.
+7. If the current provider mode exposes host tools, `call_tool(...)` is bound only to the provider-owned tool registry snapshot.
+8. Code is executed and results converted to a JSON result string.
+
+Caching rules:
+- The Hyperlight backend supports snapshots: the provider caches a reusable clean snapshot after the first sandbox initialization.
+- No mutable per-run execution state may be shared across concurrent runs.
+- In-memory interpreter state does not persist across separate `execute_code` calls.
+- Configured workspace files, mounted files, and any writable artifact/output area are the supported persistence mechanism across calls when the backend exposes them.
+
+### .NET public API
+
+#### Core types
+
+```csharp
+/// <summary>
+/// Represents a host-to-sandbox file mount configuration.
+/// </summary>
+/// <param name="HostPath">Absolute or relative path on the host filesystem.</param>
+/// <param name="MountPath">Path inside the sandbox (e.g. "/input/data.csv").</param>
+public sealed record FileMount(string HostPath, string MountPath);
+
+/// <summary>
+/// Represents an outbound network allow-list entry.
+/// </summary>
+/// <param name="Target">URL or domain (e.g. "https://api.github.com").</param>
+/// <param name="Methods">
+/// Optional HTTP methods to allow (e.g. ["GET", "POST"]).
+/// Null allows all methods supported by the backend.
+/// </param>
+public sealed record AllowedDomain(string Target, IReadOnlyList<string>? Methods = null);
+
+/// <summary>
+/// Controls the approval behavior for execute_code invocations.
+/// </summary>
+public enum CodeActApprovalMode
+{
+    /// <summary>execute_code always requires user approval.</summary>
+    AlwaysRequire,
+
+    /// <summary>
+    /// Approval is derived from the provider-owned tool registry:
+    /// if any tool is an ApprovalRequiredAIFunction, execute_code requires approval.
+    /// </summary>
+    NeverRequire,
+}
+```
+
+#### HyperlightCodeActProvider
+
+```csharp
+/// <summary>
+/// An AIContextProvider that enables CodeAct execution through the
+/// Hyperlight sandbox backend.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This provider injects an <c>execute_code</c> tool into the model-facing
+/// tool surface and builds CodeAct guidance instructions. Guest code executed
+/// through <c>execute_code</c> runs in an isolated Hyperlight sandbox with
+/// snapshot/restore for clean state per invocation.
+/// </para>
+/// <para>
+/// If no CodeAct-managed tools are configured, the provider uses
+/// interpreter-style behavior. If one or more CodeAct-managed tools are
+/// configured, the provider uses tool-enabled behavior and exposes
+/// <c>call_tool(...)</c> inside the sandbox bound to the configured tools.
+/// </para>
+/// </remarks>
+public sealed class HyperlightCodeActProvider : AIContextProvider, IDisposable
+{
+    /// <summary>
+    /// Initializes a new HyperlightCodeActProvider.
+    /// </summary>
+    /// <param name="options">Configuration options for the provider.</param>
+    public HyperlightCodeActProvider(HyperlightCodeActProviderOptions options);
+
+    // ----- Tool registry -----
+
+    /// <summary>Adds tools to the provider-owned CodeAct tool registry.</summary>
+    public void AddTools(params AIFunction[] tools);
+
+    /// <summary>Returns the current CodeAct-managed tools.</summary>
+    public IReadOnlyList<AIFunction> GetTools();
+
+    /// <summary>Removes tools by name from the CodeAct tool registry.</summary>
+    public void RemoveTools(params string[] names);
+
+    /// <summary>Removes all CodeAct-managed tools.</summary>
+    public void ClearTools();
+
+    // ----- File mounts -----
+
+    /// <summary>Adds file mount configurations.</summary>
+    public void AddFileMounts(params FileMount[] mounts);
+
+    /// <summary>Returns the current file mount configurations.</summary>
+    public IReadOnlyList<FileMount> GetFileMounts();
+
+    /// <summary>Removes file mounts by sandbox mount path.</summary>
+    public void RemoveFileMounts(params string[] mountPaths);
+
+    /// <summary>Removes all file mount configurations.</summary>
+    public void ClearFileMounts();
+
+    // ----- Network allow-list -----
+
+    /// <summary>Adds outbound network allow-list entries.</summary>
+    public void AddAllowedDomains(params AllowedDomain[] domains);
+
+    /// <summary>Returns the current outbound allow-list entries.</summary>
+    public IReadOnlyList<AllowedDomain> GetAllowedDomains();
+
+    /// <summary>Removes allow-list entries by target.</summary>
+    public void RemoveAllowedDomains(params string[] targets);
+
+    /// <summary>Removes all outbound allow-list entries.</summary>
+    public void ClearAllowedDomains();
+
+    // ----- Lifecycle -----
+
+    /// <summary>Releases the sandbox and all associated native resources.</summary>
+    public void Dispose();
+}
+```
+
+#### HyperlightCodeActProviderOptions
+
+```csharp
+/// <summary>
+/// Configuration options for <see cref="HyperlightCodeActProvider"/>.
+/// </summary>
+public sealed class HyperlightCodeActProviderOptions
+{
+    /// <summary>
+    /// The sandbox backend to use. Default is <c>Wasm</c>.
+    /// </summary>
+    public SandboxBackend Backend { get; set; } = SandboxBackend.Wasm;
+
+    /// <summary>
+    /// Path to the guest module (.wasm or .aot file).
+    /// Required for the Wasm backend; not needed for JavaScript.
+    /// When null, the provider attempts to locate the default packaged
+    /// Python guest module.
+    /// </summary>
+    public string? ModulePath { get; set; }
+
+    /// <summary>
+    /// Guest heap size. Accepts human-readable strings ("50Mi", "2Gi")
+    /// or raw byte values. Null uses the backend default.
+    /// </summary>
+    public string? HeapSize { get; set; }
+
+    /// <summary>
+    /// Guest stack size. Accepts human-readable strings ("35Mi")
+    /// or raw byte values. Null uses the backend default.
+    /// </summary>
+    public string? StackSize { get; set; }
+
+    /// <summary>
+    /// Initial set of CodeAct-managed tools available inside the sandbox.
+    /// </summary>
+    public IEnumerable<AIFunction>? Tools { get; set; }
+
+    /// <summary>
+    /// Default approval mode for the execute_code tool.
+    /// Default is <see cref="CodeActApprovalMode.NeverRequire"/>.
+    /// </summary>
+    public CodeActApprovalMode ApprovalMode { get; set; } = CodeActApprovalMode.NeverRequire;
+
+    /// <summary>
+    /// Optional workspace root directory on the host.
+    /// When set, it is exposed as the sandbox's input directory.
+    /// </summary>
+    public string? WorkspaceRoot { get; set; }
+
+    /// <summary>
+    /// Initial file mount configurations.
+    /// </summary>
+    public IEnumerable<FileMount>? FileMounts { get; set; }
+
+    /// <summary>
+    /// Initial outbound network allow-list entries.
+    /// </summary>
+    public IEnumerable<AllowedDomain>? AllowedDomains { get; set; }
+
+    /// <summary>
+    /// State key used to store provider state in AgentSession.StateBag.
+    /// Defaults to "HyperlightCodeActProvider". Override when using
+    /// multiple provider instances on the same agent.
+    /// </summary>
+    public string? StateKey { get; set; }
+}
+```
+
+#### Provider implementation contract
+
+The concrete provider plugs into the existing .NET `AIContextProvider` surface from `Microsoft.Agents.AI.Abstractions`.
+
+Required override:
+- `ProvideAIContextAsync(InvokingContext, CancellationToken) -> ValueTask<AIContext>`
+
+`ProvideAIContextAsync(...)` is responsible for:
+- snapshotting the current CodeAct-managed tool registry and capability settings for the run,
+- computing the effective approval requirement for `execute_code` from the provider default and the snapshotted tool registry,
+- building a short CodeAct guidance instruction string,
+- building a run-scoped `execute_code` `AIFunction` from the snapshot,
+- optionally wrapping it in `ApprovalRequiredAIFunction` when approval is required,
+- and returning an `AIContext` with `Instructions` and `Tools` set.
+
+These steps run on every invocation rather than once at construction time because the provider supports CRUD mutations between runs, concurrent runs need independent snapshots, and the effective approval and instructions depend on the tool registry state captured at run start.
+
+The provider overrides `StateKeys` to return the configured `StateKey` from options, enabling multiple provider instances on the same agent without key collisions.
+
+Mutating the provider after `ProvideAIContextAsync(...)` has captured a run-scoped snapshot is allowed, but it affects subsequent runs only. Provider implementations synchronize state capture and CRUD operations so shared provider instances remain safe across concurrent runs.
+
+#### AIFunction-to-sandbox tool bridging
+
+The Hyperlight sandbox's `RegisterTool(name, Func<string, string>)` accepts a synchronous JSON-in / JSON-out delegate. Provider-owned CodeAct tools are `AIFunction` instances that are async and cancellation-aware.
+
+Bridging strategy:
+- At sandbox initialization time, the provider registers each CodeAct-managed tool with the sandbox using the raw JSON overload: `RegisterTool(name, Func<string, string>)`.
+- When the sandbox guest calls `call_tool("name", ...)`, the bridge delegate:
+  1. Deserializes the JSON arguments.
+  2. Invokes `AIFunction.InvokeAsync(...)` synchronously (via `GetAwaiter().GetResult()`) since the sandbox FFI callback is inherently synchronous.
+  3. Serializes the result back to JSON.
+- This sync-over-async bridge is a known pragmatic trade-off constrained by the Hyperlight FFI boundary. It is safe because:
+  - Sandbox execution already runs on the thread pool (via `Task.Run`).
+  - The FFI callback runs on a worker thread with no synchronization context.
+- If the Hyperlight .NET SDK later adds async tool registration, the bridge should migrate to that.
+
+#### Runtime behavior
+
+- `ProvideAIContextAsync(...)` adds a short CodeAct guidance block through `AIContext.Instructions`.
+- `ProvideAIContextAsync(...)` adds `execute_code` through `AIContext.Tools`.
+- The detailed `call_tool(...)`, sandbox-tool, and capability guidance is carried by the `execute_code` function's `Description`.
+- `execute_code` invokes the configured Hyperlight sandbox guest.
+- If the current CodeAct tool registry snapshot is non-empty, the runtime injects `call_tool(...)` bound to the provider-owned tool registry.
+- The provider does not inspect or mutate the agent's `ChatClientAgentOptions.Tools` or the incoming `AIContext.Tools` to determine its CodeAct tool set.
+- The provider snapshots the current CodeAct tool registry and capability state at run start, so later registry and allow-list mutations only affect future runs.
+- Interpreter versus tool-enabled behavior is derived from the presence of CodeAct-managed tools.
+- `execute_code` is traced like a normal tool invocation within the surrounding agent run.
+
+#### Backend integration
+
+Initial public provider:
+- `HyperlightCodeActProvider`
+
+Backend-specific notes:
+- **Hyperlight**
+  - The provider internally creates a `SandboxBuilder` from the options and uses the `Sandbox` API from `HyperlightSandbox.Api`.
+  - The provider uses snapshot/restore to ensure clean execution state per `execute_code` invocation: a "warm" snapshot is taken after the first no-op initialization run, and restored before each subsequent execution.
+  - File access maps to Hyperlight Sandbox's `WithInputDir()` / `WithOutputDir()` / `WithTempOutput()` capability model.
+  - Network access is denied by default and is enabled through `Sandbox.AllowDomain(...)` per-target allow-list entries.
+  - Guest module resolution: if `ModulePath` is null for the Wasm backend, the provider attempts to locate a packaged Python guest module (equivalent to the Python SDK's `python_guest.path` resolution).
+
+#### Capability handling
+
+Capabilities are first-class `HyperlightCodeActProviderOptions` properties and provider-managed CRUD surfaces:
+- `WorkspaceRoot`
+- `FileMounts`
+- `AllowedDomains`
+
+Enabling access means:
+- Configuring `WorkspaceRoot` or any `FileMounts` enables the sandbox filesystem surface exposed through `/input` and `/output`.
+- Leaving both `WorkspaceRoot` and `FileMounts` unset means no filesystem surface is configured.
+- Adding any `AllowedDomains` entry enables outbound access only for the configured targets; leaving it empty means network access is disabled without a separate network mode flag.
+
+Backends may implement stricter semantics than these top-level settings.
+
+#### Execution output representation
+
+Backend execution output maps to a JSON result string returned from the `execute_code` `AIFunction`:
+
+```json
+{
+  "stdout": "Hello world\n",
+  "stderr": "",
+  "exit_code": 0,
+  "success": true
+}
+```
+
+Execution failures should surface readable error text in the `stderr` field and a non-zero `exit_code`. Timeouts, out-of-memory conditions, backend crashes, and similar sandbox failures are all `execute_code` failures and should surface as structured error results. Partial textual or file outputs may be returned only when the backend can report them unambiguously.
+
+#### `execute_code` input contract
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "code": {
+      "type": "string",
+      "description": "Code to execute using the provider's configured backend/runtime behavior."
+    }
+  },
+  "required": ["code"]
+}
+```
+
+#### Thread safety and concurrency
+
+- All CRUD methods (`AddTools`, `RemoveTools`, `AddFileMounts`, etc.) are synchronized via an internal lock.
+- `ProvideAIContextAsync(...)` acquires the lock to snapshot current state, then releases it before building the run-scoped function. The run-scoped function closes over the immutable snapshot, not mutable provider state.
+- Concurrent `execute_code` invocations from different runs use independent sandbox instances or synchronized access to a shared sandbox with snapshot/restore.
+- Workspace directories (`WorkspaceRoot`, `FileMounts`) are external shared state: concurrent runs against the same workspace can race on files. This is the user's responsibility to manage (e.g., by using per-run output directories or separate provider instances).
+
+### HyperlightExecuteCodeFunction
+
+The provider package also exports a standalone `HyperlightExecuteCodeFunction` for direct-tool scenarios where a provider lifecycle is not needed. This is the .NET equivalent of the Python `HyperlightExecuteCodeTool`.
+
+```csharp
+/// <summary>
+/// A standalone execute_code AIFunction backed by a Hyperlight sandbox.
+/// Use this for manual/static wiring when the AIContextProvider lifecycle
+/// is not needed.
+/// </summary>
+public sealed class HyperlightExecuteCodeFunction : IDisposable
+{
+    /// <summary>
+    /// Creates a new standalone code execution function.
+    /// </summary>
+    /// <param name="options">Configuration options.</param>
+    public HyperlightExecuteCodeFunction(HyperlightCodeActProviderOptions options);
+
+    /// <summary>
+    /// Returns this as an AIFunction for direct registration on an agent.
+    /// When approval is required, the returned function is wrapped in
+    /// ApprovalRequiredAIFunction.
+    /// </summary>
+    public AIFunction AsAIFunction();
+
+    /// <summary>
+    /// Builds a CodeAct instruction string describing the available
+    /// tools and capabilities.
+    /// </summary>
+    /// <param name="toolsVisibleToModel">
+    /// When false, the instructions include full tool descriptions
+    /// (for use when tools are only accessible through CodeAct).
+    /// When true, instructions are abbreviated (tools are already
+    /// visible to the model as direct tools).
+    /// </param>
+    public string BuildInstructions(bool toolsVisibleToModel = false);
+
+    /// <summary>Releases sandbox resources.</summary>
+    public void Dispose();
+}
+```
+
+### Internal implementation structure
+
+The provider and standalone function share internal helpers:
+
+```
+Microsoft.Agents.AI.Hyperlight/
+├── HyperlightCodeActProvider.cs        // AIContextProvider implementation
+├── HyperlightCodeActProviderOptions.cs // Options record
+├── HyperlightExecuteCodeFunction.cs    // Standalone AIFunction for manual wiring
+├── FileMount.cs                        // File mount record
+├── AllowedDomain.cs                    // Network allow-list record
+├── CodeActApprovalMode.cs              // Approval enum
+├── Internal/
+│   ├── SandboxExecutor.cs              // Manages sandbox lifecycle, snapshot/restore
+│   ├── InstructionBuilder.cs           // Builds CodeAct instruction strings
+│   └── ToolBridge.cs                   // AIFunction ↔ Sandbox.RegisterTool adapter
+```
+
+`SandboxExecutor` encapsulates:
+- Creating and configuring a `Sandbox` from options.
+- Performing the initial no-op warm-up and snapshot.
+- Registering bridged tools via `ToolBridge`.
+- Restoring to the clean snapshot before each execution.
+- Translating `ExecutionResult` to a JSON string.
+
+`InstructionBuilder` generates:
+- A short CodeAct guidance block for `AIContext.Instructions`.
+- A detailed `execute_code` description including `call_tool(...)` signatures and capability documentation.
+
+`ToolBridge` handles:
+- Reflecting `AIFunction` metadata to build the sandbox tool registration.
+- The sync-over-async invocation bridge.
+
+## E2E Code Samples
+
+### Tool-enabled CodeAct mode
+
+```csharp
+var fetchDocs = AIFunctionFactory.Create(FetchDocs, name: "fetch_docs");
+var queryData = AIFunctionFactory.Create(QueryData, name: "query_data");
+var lookupUser = AIFunctionFactory.Create(LookupUser, name: "lookup_user");
+
+var codeact = new HyperlightCodeActProvider(new HyperlightCodeActProviderOptions
+{
+    Tools = [fetchDocs, queryData],
+    WorkspaceRoot = "./workdir",
+    AllowedDomains = [new AllowedDomain("api.github.com", ["GET"])],
+});
+codeact.AddTools(lookupUser);
+
+var sendEmail = AIFunctionFactory.Create(SendEmail, name: "send_email");
+
+var agent = chatClient.AsAIAgent(
+    instructions: "You are a helpful assistant.",
+    options: new ChatClientAgentOptions
+    {
+        Tools = [sendEmail],  // direct-only tool
+        AIContextProviders = [codeact],
+    });
+
+await using var session = await agent.CreateSessionAsync();
+var response = await agent.InvokeAsync("Analyze the latest docs", session);
+```
+
+### Standard code interpreter mode
+
+```csharp
+var codeact = new HyperlightCodeActProvider(new HyperlightCodeActProviderOptions
+{
+    WorkspaceRoot = "./data",
+});
+
+var agent = chatClient.AsAIAgent(
+    instructions: "You are a code interpreter.",
+    options: new ChatClientAgentOptions
+    {
+        AIContextProviders = [codeact],
+    });
+```
+
+### Manual static wiring (no provider lifecycle)
+
+When the tool registry and capability configuration are fixed, the provider lifecycle can be skipped entirely. Build the `execute_code` function and instructions once and pass them directly to the agent:
+
+```csharp
+using var executeCode = new HyperlightExecuteCodeFunction(
+    new HyperlightCodeActProviderOptions
+    {
+        Tools = [fetchDocs, queryData],
+        WorkspaceRoot = "./workdir",
+        AllowedDomains = [new AllowedDomain("api.github.com", ["GET"])],
+    });
+
+var codeactInstructions = executeCode.BuildInstructions(toolsVisibleToModel: false);
+
+var agent = chatClient.AsAIAgent(
+    instructions: $"You are a helpful assistant.\n\n{codeactInstructions}",
+    options: new ChatClientAgentOptions
+    {
+        Tools = [sendEmail, executeCode.AsAIFunction()],
+    });
+```
+
+### With approval required
+
+```csharp
+var sensitiveAction = new ApprovalRequiredAIFunction(
+    AIFunctionFactory.Create(DeleteRecords, name: "delete_records"));
+
+var codeact = new HyperlightCodeActProvider(new HyperlightCodeActProviderOptions
+{
+    Tools = [fetchDocs, sensitiveAction],  // sensitiveAction triggers approval
+});
+
+// execute_code will be wrapped in ApprovalRequiredAIFunction because
+// at least one managed tool (delete_records) requires approval.
+var agent = chatClient.AsAIAgent(
+    instructions: "You are a helpful assistant.",
+    options: new ChatClientAgentOptions
+    {
+        AIContextProviders = [codeact],
+    });
+```
+
+## Relationship to hyperlight-sandbox .NET SDK
+
+This design depends on the .NET SDK being added in [hyperlight-dev/hyperlight-sandbox#46](https://github.com/hyperlight-dev/hyperlight-sandbox/pull/46). Key types consumed from that SDK:
+
+| hyperlight-sandbox type | Used for |
+|---|---|
+| `Sandbox` | Core sandbox lifecycle: `Run()`, `RegisterTool()`, `AllowDomain()`, `Snapshot()`, `Restore()` |
+| `SandboxBuilder` | Fluent sandbox construction from provider options |
+| `SandboxBackend` | Backend selection (Wasm, JavaScript) |
+| `ExecutionResult` | Capturing stdout, stderr, exit code from guest execution |
+| `SandboxSnapshot` | Checkpoint/restore for clean state per execution |
+
+The provider package (`Microsoft.Agents.AI.Hyperlight`) takes a NuGet dependency on `Hyperlight.HyperlightSandbox.Api` and `Microsoft.Extensions.AI.Abstractions`. It does **not** depend on `HyperlightSandbox.Extensions.AI` (`CodeExecutionTool`) — the provider implements its own sandbox lifecycle management with run-scoped snapshots to support concurrent invocations safely.
+
+## Package structure
+
+The CodeAct Hyperlight provider ships as an optional NuGet package:
+- **Package**: `Microsoft.Agents.AI.Hyperlight`
+- **Dependencies**:
+  - `Microsoft.Agents.AI.Abstractions` (for `AIContextProvider`, `AIContext`)
+  - `Microsoft.Extensions.AI.Abstractions` (for `AIFunction`, `ApprovalRequiredAIFunction`)
+  - `Hyperlight.HyperlightSandbox.Api` (for sandbox API)
+- **Target framework**: `net8.0`
+
+This keeps CodeAct and its native sandbox dependencies optional — users who do not need CodeAct do not take on the Hyperlight installation and dependency footprint.
+
+## Open questions
+
+1. **Guest module distribution**: How should the default Python guest module (`.aot` file) be distributed for .NET consumers? Options include a separate NuGet package with native assets, a runtime download, or requiring users to build/provide their own.
+2. **Async tool registration**: If the Hyperlight .NET SDK adds async tool callback support in a future release, the sync-over-async bridge should be replaced. This is tracked as a known technical debt item.
+3. **Output file access**: The Hyperlight sandbox exposes `GetOutputFiles()` and `OutputPath` for retrieving files written by guest code. The initial design returns these as part of the JSON result. A future iteration could surface output files as framework-native content (e.g., `DataContent` or URI references).
+4. **Multiple sandbox instances for concurrency**: The current design uses synchronized access to a single sandbox with snapshot/restore. An alternative pooling strategy (one sandbox per concurrent run) could improve throughput at the cost of memory. This is deferred to implementation time.

docs/features/code_act/python-implementation.md

@@ -0,0 +1,385 @@
+# CodeAct Python implementation
+
+This document describes the Python realization of the CodeAct design in
+[`docs/decisions/0024-codeact-integration.md`](../../decisions/0024-codeact-integration.md).
+
+This document is intentionally focused on the Python design and public API surface.
+The initial public Python type described here is `HyperlightCodeActProvider`. Future Python backends, such as Monty, should follow the same conceptual model with their own concrete provider types rather than through a public abstract base class or a public executor parameter.
+
+## What is the goal of this feature?
+
+Goals:
+- Python developers can enable CodeAct through a `ContextProvider`-based integration.
+- Developers can configure a provider-owned CodeAct tool set that is separate from the agent's direct `tools=` surface.
+- Developers can use the same `execute_code` concept for both tool-enabled CodeAct and a standard code interpreter tool implementation.
+- Developers can swap execution backends over time, starting with Hyperlight while keeping room for alternatives such as Pydantic's Monty.
+- Developers can configure execution capabilities such as workspace mounts and outbound network allow lists in a portable way.
+
+Success Metric:
+- Python samples exist for both a tool-enabled CodeAct mode and a standard interpreter mode.
+
+Implementation-free outcome:
+- A Python developer can attach a backend-specific CodeAct provider, choose which tools are available inside CodeAct, and configure execution capabilities without rewriting the function invocation loop.
+
+## What is the problem being solved?
+
+The cross-SDK problem statement and decision rationale live in the [ADR](../../decisions/0024-codeact-integration.md). The items below narrow that statement to Python-specific design concerns:
+
+- Today, the easiest way to prototype CodeAct is to infer or reshape the agent's direct tool surface, which is fragile and hard to reason about.
+- In Python, inferring a CodeAct tool surface from generic agent tool configuration is fragile and hard to reason about.
+- There is no first-class Python design that simultaneously covers Hyperlight-backed CodeAct now, future backend-specific providers such as Monty, and both tool-enabled and interpreter modes.
+- Sandbox capabilities such as mounted file access and outbound network access need a portable configuration model instead of ad hoc backend-specific wiring.
+- Approval behavior needs to be explicit and configurable, especially when CodeAct and direct tool calling may both be available.
+
+## API Changes
+
+### CodeAct contract
+
+#### Terminology
+
+- **CodeAct** is the primary term.
+- **Code mode**, **codemode**, and **programmatic tool calling** refer to the same concept in this document.
+- `execute_code` is the model-facing tool name used by the initial Python providers in this spec.
+
+#### Provider-owned CodeAct tool registry
+
+A concrete Python CodeAct provider owns the set of tools available through `call_tool(...)` inside CodeAct.
+
+Rules:
+- Only tools explicitly configured on the concrete provider instance are available inside CodeAct.
+- The provider must not infer its CodeAct-managed tool set from the agent's direct `tools=` configuration.
+- Exclusive versus mixed behavior is achieved by where tools are configured, not by rewriting the agent's direct tool list.
+
+Implications:
+- **CodeAct-only tool**: configured on the concrete CodeAct provider only.
+- **Direct-only tool**: configured on the agent only.
+- **Tool available both ways**: configured on both the agent and the concrete CodeAct provider.
+
+#### Managing tools and capabilities after provider construction
+
+There is no separate runtime setup object in the Python design. CodeAct tools, file mounts, and outbound network allow-list state are managed directly on the provider through CRUD-style registry methods.
+
+Preferred pattern:
+- `add_tools(...) -> None`
+- `get_tools() -> Sequence[ToolTypes]`
+- `remove_tool(...) -> None`
+- `clear_tools() -> None`
+- `add_file_mounts(...) -> None`
+- `get_file_mounts() -> Sequence[FileMount]`
+- `remove_file_mount(...) -> None`
+- `clear_file_mounts() -> None`
+- `add_allowed_domains(...) -> None`
+- `get_allowed_domains() -> Sequence[AllowedDomain]`
+- `remove_allowed_domain(...) -> None`
+- `clear_allowed_domains() -> None`
+
+Requirements:
+- The provider-owned CodeAct tool registry is keyed by tool name.
+- `add_tools(...)` adds new tools and replaces an existing provider-owned registration when the same tool name is added again.
+- `get_tools()` returns the provider's current configured CodeAct tool registry.
+- `remove_tool(...)` removes provider-owned CodeAct tools by name.
+- `clear_tools()` removes all provider-owned CodeAct tools.
+- File mounts are keyed by sandbox mount path.
+- `add_file_mounts(...)` adds new file mounts and replaces an existing mount when the same mount path is added again.
+- `get_file_mounts()` returns the provider's current configured file mounts.
+- `remove_file_mount(...)` removes file mounts by mount path.
+- `clear_file_mounts()` removes all configured file mounts.
+- Allowed domains are keyed by normalized target string.
+- `add_allowed_domains(...)` adds allow-list entries and replaces an existing entry when the same target is added again.
+- `get_allowed_domains()` returns the current outbound allow-list entries.
+- `remove_allowed_domain(...)` removes allow-list entries by target.
+- `clear_allowed_domains()` removes all configured allow-list entries.
+- Tool, file-mount, and network-allow-list mutations affect subsequent runs only; runs already in progress keep the snapshot captured at run start.
+- The provider must snapshot its effective tool registry and capability state at the start of each run so concurrent execution remains deterministic.
+
+#### Approval model
+
+The initial Python design follows the ADR's initial approval decision and reuses the existing tool approval vocabulary from `agent_framework._tools`:
+
+- `approval_mode="always_require"`
+- `approval_mode="never_require"`
+
+The provider exposes a default `approval_mode` for `execute_code`.
+
+Effective `execute_code` approval is computed as follows:
+
+- If the provider default is `always_require`, `execute_code` requires approval.
+- If the provider default is `never_require`, the provider evaluates the provider-owned CodeAct tool registry snapshot for that run.
+- If every provider-owned CodeAct tool in that snapshot is `never_require`, `execute_code` is `never_require`.
+- If any provider-owned CodeAct tool in that snapshot is `always_require`, `execute_code` is `always_require`, even if the generated code may not call that tool.
+- Provider-owned tool calls made through `call_tool(...)` during that execution run use the approval already determined for `execute_code`.
+- Direct-only agent tools are excluded from this calculation.
+- File and network capabilities do not create a separate runtime approval check in the initial model; configuring them on the provider, including adding file mounts or outbound network allow-list entries, is itself the approval for those capabilities.
+
+This is intentionally conservative and matches the shape of the current function-tool approval flow, where `FunctionTool` uses `always_require` / `never_require` and the auto-invocation loop escalates the whole batch if any called tool requires approval.
+
+If one sensitive provider-owned tool causes `execute_code` to require approval more often than desired, the mitigation is to keep that tool direct-only or expose it through a different CodeAct provider/tool surface. The initial model does not try to infer whether generated code will actually call that tool before approval.
+
+If the framework later standardizes pre-execution inspection or nested per-tool approvals, the Python provider surface can grow to expose that explicitly. The initial design does not assume that those extra modes are required.
+
+#### Shared execution flow
+
+On each run:
+1. Resolve the provider's backend/runtime behavior, capabilities, provider default `approval_mode`, and provider-owned tool registry.
+2. Compute the effective approval requirement for `execute_code` from the provider default plus the provider-owned tool registry snapshot.
+3. Build provider-defined instructions.
+4. Add `execute_code` to the model-facing tool surface.
+5. Invoke the underlying model.
+6. When `execute_code` is called, create or reuse an execution environment keyed by provider type, backend setup identity, capability configuration, and provider-owned tool signature.
+7. If the current provider mode exposes host tools, expose `call_tool(...)` bound only to the provider-owned tool registry.
+8. Execute code and convert results to framework-native content objects.
+
+Caching rules:
+- Backends that support snapshots may cache a reusable clean snapshot.
+- Backends that do not support snapshots may still cache warm initialization artifacts.
+- No mutable per-run execution state may be shared across concurrent runs.
+- In-memory interpreter state does not persist across separate `execute_code` calls.
+- Configured workspace files, mounted files, and any writable artifact/output area are the supported persistence mechanism across calls when the backend exposes them.
+
+### Python public API
+
+#### Core types
+
+```python
+class FileMount(NamedTuple):
+    host_path: str | Path
+    mount_path: str
+
+FileMountInput = str | tuple[str | Path, str] | FileMount
+
+
+class AllowedDomain(NamedTuple):
+    target: str
+    methods: tuple[str, ...] | None = None
+
+
+AllowedDomainInput = str | tuple[str, str | Sequence[str]] | AllowedDomain
+
+
+class HyperlightCodeActProvider(ContextProvider):
+    def __init__(
+        self,
+        source_id: str = "hyperlight_codeact",
+        *,
+        backend: str = "wasm",
+        module: str | None = "python_guest.path",
+        module_path: str | None = None,
+        tools: ToolTypes | None = None,
+        approval_mode: Literal["always_require", "never_require"] = "never_require",
+        workspace_root: Path | None = None,
+        file_mounts: Sequence[FileMountInput] = (),
+        allowed_domains: Sequence[AllowedDomainInput] = (),
+    ) -> None: ...
+
+    def add_tools(self, tools: ToolTypes | Sequence[ToolTypes]) -> None: ...
+    def get_tools(self) -> Sequence[ToolTypes]: ...
+    def remove_tool(self, name: str) -> None: ...
+    def clear_tools(self) -> None: ...
+    def add_file_mounts(self, mounts: FileMountInput | Sequence[FileMountInput]) -> None: ...
+    def get_file_mounts(self) -> Sequence[FileMount]: ...
+    def remove_file_mount(self, mount_path: str) -> None: ...
+    def clear_file_mounts(self) -> None: ...
+    def add_allowed_domains(self, domains: AllowedDomainInput | Sequence[AllowedDomainInput]) -> None: ...
+    def get_allowed_domains(self) -> Sequence[AllowedDomain]: ...
+    def remove_allowed_domain(self, domain: str) -> None: ...
+    def clear_allowed_domains(self) -> None: ...
+```
+
+`file_mounts` accepts three equivalent input forms:
+- `"data/report.csv"` uses the same relative path on the host and in the sandbox.
+- `("fixtures/users.json", "data/users.json")` or `(Path("fixtures/users.json"), "data/users.json")` uses distinct host and sandbox paths.
+- `FileMount(Path("fixtures/users.json"), "data/users.json")` is the named-tuple form of the explicit pair.
+
+`allowed_domains` accepts three equivalent input forms:
+- `"github.com"` allows that target with all backend-supported methods.
+- `("github.com", "GET")` or `("github.com", ["GET", "HEAD"])` uses an explicit per-target method list.
+- `AllowedDomain("github.com", ("GET", "HEAD"))` is the named-tuple form of the explicit entry.
+
+No public abstract `CodeActContextProvider` base or public `executor=` parameter is required for the initial Python API.
+
+The initial alpha package also exports a standalone `HyperlightExecuteCodeTool`
+for direct-tool scenarios where a provider is not needed. That standalone tool
+should advertise `call_tool(...)`, the registered sandbox tools, and capability
+state through its own `description` rather than requiring separate agent
+instructions.
+
+Provider modes:
+- If no CodeAct-managed tools are configured, `HyperlightCodeActProvider` uses interpreter-style behavior.
+- If one or more CodeAct-managed tools are configured, `HyperlightCodeActProvider` uses tool-enabled behavior.
+
+#### Python provider implementation contract
+
+The concrete provider plugs into the existing Python `ContextProvider` surface from `agent_framework._sessions`.
+
+The Hyperlight package also depends on a small set of core hooks that must remain available from `agent-framework-core`:
+- `ContextProvider.before_run(...)`
+- `SessionContext.extend_instructions(...)`
+- `SessionContext.extend_tools(...)`
+- per-run runtime tool access via `SessionContext.options["tools"]`
+- the shared `ApprovalMode` vocabulary used by `FunctionTool`
+
+Required lifecycle hook:
+- `before_run(*, agent, session, context, state) -> None`
+
+Optional lifecycle hook:
+- `after_run(*, agent, session, context, state) -> None`
+
+`before_run(...)` is responsible for:
+- snapshotting the current CodeAct-managed tool registry and capability settings for the run,
+- computing the effective approval requirement for `execute_code` from the provider default and the snapshotted tool registry,
+- adding a short CodeAct guidance block,
+- adding `execute_code` to the run through `SessionContext.extend_tools(...)`,
+- and wiring any backend-specific execution state needed for the run.
+
+These steps run on every invocation rather than once at construction time because the provider supports CRUD mutations between runs, concurrent runs need independent snapshots, and the effective approval and instructions depend on the tool registry state captured at run start. When the tool registry and capability configuration are fixed for the lifetime of the agent, the manual wiring pattern (see `codeact_manual_wiring.py`) can be used instead, which passes the tool and instructions directly to the `Agent` constructor and avoids the per-run provider lifecycle entirely.
+
+If the provider stores anything in `state`, that value must stay JSON-serializable.
+
+Mutating the provider after `before_run(...)` has captured a run-scoped snapshot is allowed, but it affects subsequent runs only. Provider implementations should synchronize state capture and CRUD operations so shared provider instances remain safe across concurrent runs.
+
+`after_run(...)` is responsible for any backend-specific cleanup or post-processing that must happen after the model invocation completes.
+
+If shared internal helpers are introduced later for multiple concrete providers, they should standardize responsibilities for:
+- building instructions,
+- computing effective approval,
+- configuring file access,
+- configuring network access,
+- preparing or restoring execution state,
+- executing code,
+- and converting backend output into framework-native `Content`.
+
+#### Runtime behavior
+
+- `before_run(...)` adds a short CodeAct guidance block through `SessionContext.extend_instructions(...)`.
+- `before_run(...)` adds `execute_code` through `SessionContext.extend_tools(...)`.
+- The detailed `call_tool(...)`, sandbox-tool, and capability guidance is carried by `execute_code.description`.
+- `execute_code` invokes the configured Hyperlight sandbox guest.
+- If the current CodeAct tool registry is non-empty, the runtime injects `call_tool(...)` bound to the provider-owned tool registry.
+- The provider does not inspect or mutate `Agent.default_options["tools"]` or `context.options["tools"]` to determine its CodeAct tool set.
+- The provider snapshots the current CodeAct tool registry and capability state at run start, so later registry and allow-list mutations only affect future runs.
+- Interpreter versus tool-enabled behavior is derived from the concrete provider and the presence of CodeAct-managed tools, not from a separate public profile object.
+- `execute_code` should be traced like a normal tool invocation within the surrounding agent run, and provider-owned tool calls executed through `call_tool(...)` should continue to emit ordinary tool invocation telemetry.
+
+#### Backend integration
+
+Initial public provider:
+- `HyperlightCodeActProvider`
+
+Backend-specific notes:
+- **Hyperlight**
+  - Provider construction needs a guest artifact via `module`, which may be a packaged guest module name or a path to a compiled guest artifact.
+  - File access maps naturally to Hyperlight Sandbox's read-only `/input` and writable `/output` capability model.
+  - Network access is denied by default and is enabled through per-target allow-list entries.
+- **Monty**
+  - A future `MontyCodeActProvider` should be a separate public type rather than a `HyperlightCodeActProvider` mode.
+  - Monty does not expose built-in filesystem or network access directly inside the interpreter.
+  - File and URL access are mediated through host-provided external functions, so a Monty provider would need to translate provider settings into virtual files and allow-checked callbacks.
+  - Monty setup may also include backend-specific inputs such as `script_name`, optional type-check stubs, or restored snapshots.
+
+#### Capability handling
+
+Capabilities are first-class `HyperlightCodeActProvider` init parameters and provider-managed CRUD surfaces:
+- `workspace_root`
+- `file_mounts`
+- `allowed_domains`
+
+Concrete providers should normalize these settings internally. Hyperlight can map them directly to sandbox capabilities, while Monty must enforce them through host-mediated file and network functions and may apply stricter URL-level checks than the public provider surface expresses.
+
+Expected management split:
+- `workspace_root` remains a direct configuration value on the provider,
+- file mounts are managed through provider CRUD methods,
+- outbound allow-list entries are managed through provider CRUD methods.
+
+Enabling access means:
+- Configuring `workspace_root` or any `file_mounts` enables the sandbox filesystem surface exposed through `/input` and `/output`.
+- Leaving both `workspace_root` and `file_mounts` unset means no filesystem surface is configured.
+- Adding any `allowed_domains` entry enables outbound access only for the configured targets; leaving it empty means network access is disabled without a separate `network_mode` flag.
+- A string target allows all backend-supported methods for that target; an explicit tuple or `AllowedDomain` entry narrows the methods for that target.
+
+Backends may implement stricter semantics than these top-level settings. For example, Hyperlight naturally maps file access to `/input` and `/output`, while Monty would enforce equivalent policy through host-provided callbacks rather than direct interpreter I/O.
+
+#### Execution output representation
+
+Backend execution output should be translated into existing AF `Content` values rather than a custom `CodeActExecutionResult` type.
+
+Use the existing content model from `agent_framework._types`, for example:
+- `Content.from_code_interpreter_tool_result(outputs=[...])` to surface the overall result of sandboxed code execution,
+- `Content.from_text(...)` for plain textual output,
+- `Content.from_data(...)` or `Content.from_uri(...)` for generated files or binary artifacts,
+- `Content.from_error(...)` for execution failures,
+- and `Content.from_function_result(..., result=list[Content])` when surfacing the final result of `execute_code` through the normal tool result path.
+
+#### `execute_code` input contract
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "code": {
+      "type": "string",
+      "description": "Code to execute using the provider's configured backend/runtime behavior."
+    }
+  },
+  "required": ["code"]
+}
+```
+
+Execution failures should surface readable error text and structured error `Content`, not a custom backend result object.
+
+Timeouts, out-of-memory conditions, backend crashes, and similar sandbox failures are all `execute_code` failures and should surface as structured error content. Partial textual or file outputs may be returned only when the backend can report them unambiguously; callers should not rely on partial-output recovery as a portable contract.
+
+## E2E Code Samples
+
+### Tool-enabled CodeAct mode
+
+```python
+codeact = HyperlightCodeActProvider(
+    tools=[fetch_docs, query_data],
+    workspace_root="./workdir",
+    allowed_domains=[("api.github.com", "GET")],
+)
+codeact.add_tools([lookup_user])
+
+agent = Agent(
+    client=client,
+    name="assistant",
+    tools=[send_email],  # direct-only tool
+    context_providers=[codeact],
+)
+```
+
+### Standard code interpreter mode
+
+```python
+codeact = HyperlightCodeActProvider(
+    workspace_root="./data",
+)
+
+agent = Agent(
+    client=client,
+    name="interpreter",
+    context_providers=[codeact],
+)
+```
+
+### Manual static wiring (no per-run provider lifecycle)
+
+When the tool registry and capability configuration are fixed, the provider lifecycle can be skipped entirely. Build the `execute_code` tool and instructions once and pass them directly to the agent:
+
+```python
+execute_code = HyperlightExecuteCodeTool(
+    tools=[fetch_docs, query_data],
+    workspace_root="./workdir",
+    allowed_domains=[("api.github.com", "GET")],
+    approval_mode="never_require",
+)
+
+codeact_instructions = execute_code.build_instructions(tools_visible_to_model=False)
+
+agent = Agent(
+    client=client,
+    name="assistant",
+    instructions=f"You are a helpful assistant.\n\n{codeact_instructions}",
+    tools=[send_email, execute_code],
+)
+```

dotnet/.gitignore

@@ -402,4 +402,11 @@ FodyWeavers.xsd
 *.msp
 
 # JetBrains Rider
-*.sln.iml
+*.sln.iml
+
+# Foundry agent CLI config (contains secrets, auto-generated)
+.foundry-agent.json
+.foundry-agent-build.log
+
+# Pre-published output for Docker builds
+out/

dotnet/Directory.Packages.props

@@ -7,23 +7,31 @@
   </PropertyGroup>
   <PropertyGroup>
     <!-- Aspire -->
-    <AspireAppHostSdkVersion>13.0.2</AspireAppHostSdkVersion>
+    <AspireAppHostSdkVersion>13.1.0</AspireAppHostSdkVersion>
   </PropertyGroup>
   <ItemGroup>
     <!-- Aspire.* -->
     <PackageVersion Include="Anthropic" Version="12.13.0" />
     <PackageVersion Include="Anthropic.Foundry" Version="0.5.0" />
+    <PackageVersion Include="Aspire.Hosting" Version="$(AspireAppHostSdkVersion)" />
     <PackageVersion Include="Aspire.Azure.AI.OpenAI" Version="13.0.0-preview.1.25560.3" />
+    <PackageVersion Include="Aspire.Azure.AI.Inference" Version="13.1.0-preview.1.25616.3" />
+    <PackageVersion Include="Aspire.Hosting.Azure.AIFoundry" Version="13.1.0-preview.1.25616.3" />
     <PackageVersion Include="Aspire.Hosting.AppHost" Version="$(AspireAppHostSdkVersion)" />
     <PackageVersion Include="Aspire.Hosting.Azure.CognitiveServices" Version="$(AspireAppHostSdkVersion)" />
     <PackageVersion Include="Aspire.Microsoft.Azure.Cosmos" Version="$(AspireAppHostSdkVersion)" />
     <PackageVersion Include="CommunityToolkit.Aspire.OllamaSharp" Version="13.0.0" />
     <!-- Azure.* -->
+    <PackageVersion Include="Azure.AI.AgentServer.Core" Version="1.0.0-beta.23" />
+    <PackageVersion Include="Azure.AI.AgentServer.Invocations" Version="1.0.0-beta.3" />
+    <PackageVersion Include="Azure.AI.AgentServer.Responses" Version="1.0.0-beta.4" />
     <PackageVersion Include="Azure.AI.Projects" Version="2.0.0" />
     <PackageVersion Include="Azure.AI.Agents.Persistent" Version="1.2.0-beta.10" />
     <PackageVersion Include="Azure.AI.OpenAI" Version="2.9.0-beta.1" />
-    <PackageVersion Include="Azure.Identity" Version="1.20.0" />
-    <PackageVersion Include="Azure.Monitor.OpenTelemetry.Exporter" Version="1.4.0" />
+    <PackageVersion Include="Azure.Core" Version="1.53.0" />
+    <PackageVersion Include="Azure.Identity" Version="1.21.0" />
+    <PackageVersion Include="DotNetEnv" Version="3.1.1" />
+    <PackageVersion Include="Azure.Monitor.OpenTelemetry.Exporter" Version="1.5.0" />
     <!-- Google Gemini  -->
     <PackageVersion Include="Google.GenAI" Version="1.6.0" />
     <PackageVersion Include="Mscc.GenerativeAI.Microsoft" Version="2.9.3" />
@@ -34,29 +42,29 @@
     <!-- System.* -->
     <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.6" />
     <PackageVersion Include="Microsoft.Bcl.HashCode" Version="6.0.0" />
-    <PackageVersion Include="Microsoft.Bcl.Memory" Version="10.0.4" />
+    <PackageVersion Include="Microsoft.Bcl.Memory" Version="10.0.5" />
     <PackageVersion Include="System.ClientModel" Version="1.10.0" />
     <PackageVersion Include="System.CodeDom" Version="10.0.0" />
     <PackageVersion Include="System.Collections.Immutable" Version="10.0.1" />
     <PackageVersion Include="System.CommandLine" Version="2.0.0-rc.2.25502.107" />
     <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="10.0.6" />
-    <PackageVersion Include="System.Linq.AsyncEnumerable" Version="10.0.4" />
+    <PackageVersion Include="System.Linq.AsyncEnumerable" Version="10.0.5" />
     <PackageVersion Include="System.Net.Http.Json" Version="10.0.0" />
-    <PackageVersion Include="System.Net.ServerSentEvents" Version="10.0.4" />
+    <PackageVersion Include="System.Net.ServerSentEvents" Version="10.0.5" />
     <PackageVersion Include="System.Text.Json" Version="10.0.6" />
     <PackageVersion Include="System.Threading.Channels" Version="10.0.6" />
     <PackageVersion Include="System.Threading.Tasks.Extensions" Version="4.6.3" />
     <PackageVersion Include="System.Net.Security" Version="4.3.2" />
     <!-- OpenTelemetry -->
-    <PackageVersion Include="OpenTelemetry" Version="1.13.1" />
-    <PackageVersion Include="OpenTelemetry.Api" Version="1.13.1" />
-    <PackageVersion Include="OpenTelemetry.Exporter.Console" Version="1.13.1" />
-    <PackageVersion Include="OpenTelemetry.Exporter.InMemory" Version="1.13.1" />
-    <PackageVersion Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.13.1" />
-    <PackageVersion Include="OpenTelemetry.Extensions.Hosting" Version="1.13.1" />
-    <PackageVersion Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.13.0" />
-    <PackageVersion Include="OpenTelemetry.Instrumentation.Http" Version="1.13.0" />
-    <PackageVersion Include="OpenTelemetry.Instrumentation.Runtime" Version="1.13.0" />
+    <PackageVersion Include="OpenTelemetry" Version="1.15.0" />
+    <PackageVersion Include="OpenTelemetry.Api" Version="1.15.0" />
+    <PackageVersion Include="OpenTelemetry.Exporter.Console" Version="1.15.0" />
+    <PackageVersion Include="OpenTelemetry.Exporter.InMemory" Version="1.15.0" />
+    <PackageVersion Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.15.0" />
+    <PackageVersion Include="OpenTelemetry.Extensions.Hosting" Version="1.14.0" />
+    <PackageVersion Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.14.0" />
+    <PackageVersion Include="OpenTelemetry.Instrumentation.Http" Version="1.14.0" />
+    <PackageVersion Include="OpenTelemetry.Instrumentation.Runtime" Version="1.14.0" />
     <!-- Microsoft.AspNetCore.* -->
     <PackageVersion Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.0" />
     <PackageVersion Include="Microsoft.AspNetCore.Authentication.OpenIdConnect" Version="10.0.0" />
@@ -71,18 +79,18 @@
     <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.5.0" />
     <PackageVersion Include="Microsoft.Extensions.Caching.Memory" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Compliance.Abstractions" Version="10.5.0" />
-    <PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Configuration.Binder" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Configuration.Json" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.1" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration.Binder" Version="10.0.1" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="10.0.1" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration.Json" Version="10.0.1" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.1" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.1" />
     <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.6" />
-    <PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.1" />
     <PackageVersion Include="Microsoft.Extensions.Http.Resilience" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Logging" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Logging" Version="10.0.1" />
     <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.6" />
-    <PackageVersion Include="Microsoft.Extensions.Logging.Console" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Logging.Console" Version="10.0.1" />
     <PackageVersion Include="Microsoft.Extensions.ServiceDiscovery" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.VectorData.Abstractions" Version="9.7.0" />
     <!-- Vector Stores -->
@@ -96,8 +104,8 @@
     <PackageVersion Include="Microsoft.Agents.Authentication.Msal" Version="1.3.171-beta" />
     <PackageVersion Include="Microsoft.Agents.Hosting.AspNetCore" Version="1.3.171-beta" />
     <!-- A2A -->
-    <PackageVersion Include="A2A" Version="0.3.4-preview" />
-    <PackageVersion Include="A2A.AspNetCore" Version="0.3.4-preview" />
+    <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" />
     <!-- Inference SDKs -->
@@ -180,4 +188,4 @@
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
   </ItemGroup>
-</Project>
+</Project>

dotnet/agent-framework-dotnet.slnx

@@ -1,4 +1,4 @@
-<Solution>
+<Solution>
   <Configurations>
     <BuildType Name="Debug" />
     <BuildType Name="Publish" />
@@ -37,6 +37,12 @@
     <Project Path="samples/02-agents/AgentProviders/Agent_With_OpenAIChatCompletion/Agent_With_OpenAIChatCompletion.csproj" />
     <Project Path="samples/02-agents/AgentProviders/Agent_With_OpenAIResponses/Agent_With_OpenAIResponses.csproj" />
   </Folder>
+  <Folder Name="/Samples/05-end-to-end/DevUIAspireIntegration/">
+    <Project Path="samples/05-end-to-end/DevUIAspireIntegration/DevUIIntegration.AppHost/DevUIIntegration.AppHost.csproj" />
+    <Project Path="samples/05-end-to-end/DevUIAspireIntegration/DevUIIntegration.ServiceDefaults/DevUIIntegration.ServiceDefaults.csproj" />
+    <Project Path="samples/05-end-to-end/DevUIAspireIntegration/EditorAgent/EditorAgent.csproj" />
+    <Project Path="samples/05-end-to-end/DevUIAspireIntegration/WriterAgent/WriterAgent.csproj" />
+  </Folder>
   <Folder Name="/Samples/02-agents/Agents/">
     <File Path="samples/02-agents/Agents/README.md" />
     <Project Path="samples/02-agents/Agents/Agent_Step01_UsingFunctionToolsWithApprovals/Agent_Step01_UsingFunctionToolsWithApprovals.csproj" />
@@ -58,6 +64,7 @@
     <Project Path="samples/02-agents/Agents/Agent_Step17_AdditionalAIContext/Agent_Step17_AdditionalAIContext.csproj" />
     <Project Path="samples/02-agents/Agents/Agent_Step18_CompactionPipeline/Agent_Step18_CompactionPipeline.csproj" />
     <Project Path="samples/02-agents/Agents/Agent_Step19_InFunctionLoopCheckpointing/Agent_Step19_InFunctionLoopCheckpointing.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step20_DynamicFunctionTools/Agent_Step20_DynamicFunctionTools.csproj" />
   </Folder>
   <Folder Name="/Samples/02-agents/DeclarativeAgents/">
     <Project Path="samples/02-agents/DeclarativeAgents/ChatClient/DeclarativeChatClientAgents.csproj" />
@@ -152,6 +159,8 @@
     <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step21_WebSearch/Agent_Step21_WebSearch.csproj" />
     <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step22_MemorySearch/Agent_Step22_MemorySearch.csproj" />
     <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step23_LocalMCP/Agent_Step23_LocalMCP.csproj" />
+    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step24_CodeInterpreterFileDownload/Agent_Step24_CodeInterpreterFileDownload.csproj" />
+    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step25_ToolboxServerSideTools/Agent_Step25_ToolboxServerSideTools.csproj" />
   </Folder>
   <Folder Name="/Samples/02-agents/Evaluation/">
     <Project Path="samples/02-agents/Evaluation/Evaluation_SimpleEval/Evaluation_SimpleEval.csproj" />
@@ -173,6 +182,7 @@
     <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step03_CreateFromChatClient/Agent_OpenAI_Step03_CreateFromChatClient.csproj" />
     <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient.csproj" />
     <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step05_Conversation/Agent_OpenAI_Step05_Conversation.csproj" />
+    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step06_CodeInterpreterFileDownload/Agent_OpenAI_Step06_CodeInterpreterFileDownload.csproj" />
   </Folder>
   <Folder Name="/Samples/02-agents/AgentWithRAG/">
     <File Path="samples/02-agents/AgentWithRAG/README.md" />
@@ -272,7 +282,44 @@
   <Folder Name="/Samples/03-workflows/Evaluation/">
     <Project Path="samples/03-workflows/Evaluation/Evaluation_WorkflowEval/Evaluation_WorkflowEval.csproj" />
   </Folder>
-  <Folder Name="/Samples/04-hosting/" />
+  <Folder Name="/Samples/04-hosting/">
+  </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/" />
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/invocations/" />
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/invocations/Hosted-Invocations-EchoAgent/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/invocations/Hosted-Invocations-EchoAgent/Hosted-Invocations-EchoAgent.csproj" />
+  </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/invocations/Using-Samples/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/invocations/Using-Samples/SimpleInvocationsAgent/SimpleInvocationsAgent.csproj" />
+  </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/" />
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/HostedChatClientAgent.csproj" />
+  </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-FoundryAgent/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-FoundryAgent/HostedFoundryAgent.csproj" />
+  </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalTools/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalTools/HostedLocalTools.csproj" />
+  </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-McpTools/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-McpTools/HostedMcpTools.csproj" />
+  </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox/HostedToolbox.csproj" />
+  </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-TextRag/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-TextRag/HostedTextRag.csproj" />
+  </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Simple/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Simple/HostedWorkflowSimple.csproj" />
+  </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent/SimpleAgent.csproj" />
+  </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Handoff/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Handoff/HostedWorkflowHandoff.csproj" />
+  </Folder>
   <Folder Name="/Samples/04-hosting/DurableAgents/" />
   <Folder Name="/Samples/04-hosting/DurableAgents/AzureFunctions/">
     <File Path="samples/04-hosting/DurableAgents/AzureFunctions/.editorconfig" />
@@ -296,11 +343,13 @@
     <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/06_LongRunningTools/06_LongRunningTools.csproj" />
     <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/07_ReliableStreaming/07_ReliableStreaming.csproj" />
   </Folder>
-  <Folder Name="/Samples/04-hosting/A2A/">
-    <File Path="samples/04-hosting/A2A/README.md" />
-    <Project Path="samples/04-hosting/A2A/A2AAgent_AsFunctionTools/A2AAgent_AsFunctionTools.csproj" />
-    <Project Path="samples/04-hosting/A2A/A2AAgent_PollingForTaskCompletion/A2AAgent_PollingForTaskCompletion.csproj" />
-  </Folder>
+  <Folder Name="/Samples/02-agents/A2A/">
+    <File Path="samples/02-agents/A2A/README.md" />
+    <Project Path="samples/02-agents/A2A/A2AAgent_AsFunctionTools/A2AAgent_AsFunctionTools.csproj" />
+    <Project Path="samples/02-agents/A2A/A2AAgent_PollingForTaskCompletion/A2AAgent_PollingForTaskCompletion.csproj" />
+    <Project Path="samples/02-agents/A2A/A2AAgent_StreamReconnection/A2AAgent_StreamReconnection.csproj" />
+    <Project Path="samples/02-agents/A2A/A2AAgent_ProtocolSelection/A2AAgent_ProtocolSelection.csproj" />
+  </Folder>  
   <Folder Name="/Samples/05-end-to-end/">
     <Project Path="samples/05-end-to-end/AgentWithPurview/AgentWithPurview.csproj" />
     <Project Path="samples/05-end-to-end/M365Agent/M365Agent.csproj" />
@@ -327,15 +376,6 @@
     <Project Path="samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/AGUIDojoServer.csproj" />
     <Project Path="samples/05-end-to-end/AGUIClientServer/AGUIServer/AGUIServer.csproj" />
   </Folder>
-  <Folder Name="/Samples/05-end-to-end/HostedAgents/">
-    <Project Path="samples/05-end-to-end/HostedAgents/AgentsInWorkflows/AgentsInWorkflows.csproj" />
-    <Project Path="samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/AgentThreadAndHITL.csproj" />
-    <Project Path="samples/05-end-to-end/HostedAgents/AgentWithHostedMCP/AgentWithHostedMCP.csproj" />
-    <Project Path="samples/05-end-to-end/HostedAgents/AgentWithLocalTools/AgentWithLocalTools.csproj" />
-    <Project Path="samples/05-end-to-end/HostedAgents/AgentWithTextSearchRag/AgentWithTextSearchRag.csproj" />
-    <Project Path="samples/05-end-to-end/HostedAgents/FoundryMultiAgent/FoundryMultiAgent.csproj" />
-    <Project Path="samples/05-end-to-end/HostedAgents/FoundrySingleAgent/FoundrySingleAgent.csproj" />
-  </Folder>
   <Folder Name="/Samples/05-end-to-end/AspNetAgentAuthorization/">
     <File Path="samples/05-end-to-end/AspNetAgentAuthorization/docker-compose.yml" />
     <File Path="samples/05-end-to-end/AspNetAgentAuthorization/README.md" />
@@ -492,18 +532,19 @@
     <File Path="tests/Directory.Build.props" />
   </Folder>
   <Folder Name="/src/">
+    <Project Path="src/Aspire.Hosting.AgentFramework.DevUI/Aspire.Hosting.AgentFramework.DevUI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.A2A/Microsoft.Agents.AI.A2A.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Abstractions/Microsoft.Agents.AI.Abstractions.csproj" />
     <Project Path="src/Microsoft.Agents.AI.AGUI/Microsoft.Agents.AI.AGUI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Anthropic/Microsoft.Agents.AI.Anthropic.csproj" />
     <Project Path="src/Microsoft.Agents.AI.AzureAI.Persistent/Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
-    <Project Path="src/Microsoft.Agents.AI.Foundry/Microsoft.Agents.AI.Foundry.csproj" />
     <Project Path="src/Microsoft.Agents.AI.CopilotStudio/Microsoft.Agents.AI.CopilotStudio.csproj" />
     <Project Path="src/Microsoft.Agents.AI.CosmosNoSql/Microsoft.Agents.AI.CosmosNoSql.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Declarative/Microsoft.Agents.AI.Declarative.csproj" />
     <Project Path="src/Microsoft.Agents.AI.DevUI/Microsoft.Agents.AI.DevUI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.DurableTask/Microsoft.Agents.AI.DurableTask.csproj" />
-
+    <Project Path="src/Microsoft.Agents.AI.Foundry/Microsoft.Agents.AI.Foundry.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Foundry.Hosting/Microsoft.Agents.AI.Foundry.Hosting.csproj" />
     <Project Path="src/Microsoft.Agents.AI.GitHub.Copilot/Microsoft.Agents.AI.GitHub.Copilot.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.A2A.AspNetCore/Microsoft.Agents.AI.Hosting.A2A.AspNetCore.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.A2A/Microsoft.Agents.AI.Hosting.A2A.csproj" />
@@ -525,11 +566,10 @@
   <Folder Name="/Tests/IntegrationTests/">
     <Project Path="tests/AgentConformance.IntegrationTests/AgentConformance.IntegrationTests.csproj" />
     <Project Path="tests/AnthropicChatCompletion.IntegrationTests/AnthropicChatCompletion.IntegrationTests.csproj" />
-    <Project Path="tests/Foundry.IntegrationTests/Foundry.IntegrationTests.csproj" />
     <Project Path="tests/AzureAIAgentsPersistent.IntegrationTests/AzureAIAgentsPersistent.IntegrationTests.csproj" />
     <Project Path="tests/CopilotStudio.IntegrationTests/CopilotStudio.IntegrationTests.csproj" />
+    <Project Path="tests/Foundry.IntegrationTests/Foundry.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.DurableTask.IntegrationTests/Microsoft.Agents.AI.DurableTask.IntegrationTests.csproj" />
-
     <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.IntegrationTests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests.csproj" />
@@ -540,17 +580,17 @@
     <Project Path="tests/OpenAIResponse.IntegrationTests/OpenAIResponse.IntegrationTests.csproj" />
   </Folder>
   <Folder Name="/Tests/UnitTests/">
+    <Project Path="tests/Aspire.Hosting.AgentFramework.DevUI.UnitTests/Aspire.Hosting.AgentFramework.DevUI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.A2A.UnitTests/Microsoft.Agents.AI.A2A.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Abstractions.UnitTests/Microsoft.Agents.AI.Abstractions.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.AGUI.UnitTests/Microsoft.Agents.AI.AGUI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Anthropic.UnitTests/Microsoft.Agents.AI.Anthropic.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.AzureAI.Persistent.UnitTests/Microsoft.Agents.AI.AzureAI.Persistent.UnitTests.csproj" />
-    <Project Path="tests/Microsoft.Agents.AI.Foundry.UnitTests/Microsoft.Agents.AI.Foundry.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.CosmosNoSql.UnitTests/Microsoft.Agents.AI.CosmosNoSql.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Declarative.UnitTests/Microsoft.Agents.AI.Declarative.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.DevUI.UnitTests/Microsoft.Agents.AI.DevUI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.DurableTask.UnitTests/Microsoft.Agents.AI.DurableTask.UnitTests.csproj" />
-
+    <Project Path="tests/Microsoft.Agents.AI.Foundry.UnitTests/Microsoft.Agents.AI.Foundry.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.A2A.UnitTests/Microsoft.Agents.AI.Hosting.A2A.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests.csproj" />

dotnet/agent-framework-release.slnf

@@ -9,6 +9,7 @@
       "src\\Microsoft.Agents.AI.GitHub.Copilot\\Microsoft.Agents.AI.GitHub.Copilot.csproj",
       "src\\Microsoft.Agents.AI.AzureAI.Persistent\\Microsoft.Agents.AI.AzureAI.Persistent.csproj",
       "src\\Microsoft.Agents.AI.Foundry\\Microsoft.Agents.AI.Foundry.csproj",
+      "src\\Microsoft.Agents.AI.Foundry.Hosting\\Microsoft.Agents.AI.Foundry.Hosting.csproj",
       "src\\Microsoft.Agents.AI.CopilotStudio\\Microsoft.Agents.AI.CopilotStudio.csproj",
       "src\\Microsoft.Agents.AI.CosmosNoSql\\Microsoft.Agents.AI.CosmosNoSql.csproj",
       "src\\Microsoft.Agents.AI.Declarative\\Microsoft.Agents.AI.Declarative.csproj",
@@ -28,7 +29,8 @@
       "src\\Microsoft.Agents.AI.Workflows.Declarative\\Microsoft.Agents.AI.Workflows.Declarative.csproj",
       "src\\Microsoft.Agents.AI.Workflows.Generators\\Microsoft.Agents.AI.Workflows.Generators.csproj",
       "src\\Microsoft.Agents.AI.Workflows\\Microsoft.Agents.AI.Workflows.csproj",
-      "src\\Microsoft.Agents.AI\\Microsoft.Agents.AI.csproj"
+      "src\\Microsoft.Agents.AI\\Microsoft.Agents.AI.csproj",
+      "src\\Aspire.Hosting.AgentFramework.DevUI\\Aspire.Hosting.AgentFramework.DevUI.csproj"
     ]
   }
 }

dotnet/nuget.config

@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="utf-8"?>
+<?xml version="1.0" encoding="utf-8"?>
 <configuration>
   <packageSources>
     <clear />
@@ -9,4 +9,4 @@
       <package pattern="*" />
     </packageSource>
   </packageSourceMapping>
-</configuration>
+</configuration>

dotnet/nuget/nuget-package.props

@@ -1,13 +1,14 @@
 <Project>
   <PropertyGroup>
     <!-- Central version prefix - applies to all nuget packages. -->
-    <VersionPrefix>1.1.0</VersionPrefix>
+    <VersionPrefix>1.3.0</VersionPrefix>
     <RCNumber>1</RCNumber>
+    <DateSuffix>260423</DateSuffix>
     <PackageVersion Condition="'$(IsReleaseCandidate)' == 'true'">$(VersionPrefix)-rc$(RCNumber)</PackageVersion>
-    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).260410.1</PackageVersion>
-    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' == ''">$(VersionPrefix)-preview.260410.1</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.1.0</GitTag>
+    <GitTag>1.3.0</GitTag>
 
     <Configurations>Debug;Release;Publish</Configurations>
     <IsPackable>true</IsPackable>
@@ -29,7 +30,8 @@
 
     <!-- Report low, moderate, high and critical advisories -->
     <NuGetAuditLevel>low</NuGetAuditLevel>
-    
+
+
     <!-- Default description and tags. Packages can override. -->
     <Authors>Microsoft</Authors>
     <Company>Microsoft</Company>

dotnet/samples/02-agents/A2A/A2AAgent_PollingForTaskCompletion/A2AAgent_PollingForTaskCompletion.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net10.0</TargetFramework>
+    <TargetFrameworks>net10.0</TargetFrameworks>
 
     <Nullable>enable</Nullable>
     <ImplicitUsings>enable</ImplicitUsings>
@@ -13,7 +13,6 @@
     <PackageReference Include="Azure.AI.OpenAI" />
     <PackageReference Include="Azure.Identity" />
     <PackageReference Include="Microsoft.Extensions.Hosting" />
-    <PackageReference Include="System.Net.ServerSentEvents" />
   </ItemGroup>
 
   <ItemGroup>

dotnet/samples/02-agents/A2A/A2AAgent_PollingForTaskCompletion/Program.cs

@@ -18,8 +18,12 @@ AIAgent agent = agentCard.AsAIAgent();
 
 AgentSession session = await agent.CreateSessionAsync();
 
+// AllowBackgroundResponses must be true so the server returns immediately with a continuation token
+// instead of blocking until the task is complete.
+AgentRunOptions options = new() { AllowBackgroundResponses = true };
+
 // Start the initial run with a long-running task.
-AgentResponse response = await agent.RunAsync("Conduct a comprehensive analysis of quantum computing applications in cryptography, including recent breakthroughs, implementation challenges, and future roadmap. Please include diagrams and visual representations to illustrate complex concepts.", session);
+AgentResponse response = await agent.RunAsync("Conduct a comprehensive analysis of quantum computing applications in cryptography, including recent breakthroughs, implementation challenges, and future roadmap. Please include diagrams and visual representations to illustrate complex concepts.", session, options: options);
 
 // Poll until the response is complete.
 while (response.ContinuationToken is { } token)

dotnet/samples/02-agents/A2A/A2AAgent_ProtocolSelection/A2AAgent_ProtocolSelection.csproj

@@ -0,0 +1,19 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="A2A" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.A2A\Microsoft.Agents.AI.A2A.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/02-agents/A2A/A2AAgent_ProtocolSelection/Program.cs

@@ -0,0 +1,36 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to select the A2A protocol binding (HTTP+JSON vs JSON-RPC) when
+// creating an AIAgent from an A2A agent card using A2AClientOptions.PreferredBindings.
+
+using A2A;
+using Microsoft.Agents.AI;
+
+var a2aAgentHost = Environment.GetEnvironmentVariable("A2A_AGENT_HOST") ?? throw new InvalidOperationException("A2A_AGENT_HOST is not set.");
+
+// Initialize an A2ACardResolver to get an A2A agent card.
+A2ACardResolver agentCardResolver = new(new Uri(a2aAgentHost));
+
+// Get the agent card
+AgentCard agentCard = await agentCardResolver.GetAgentCardAsync();
+
+// Use A2AClientOptions to explicitly select the HTTP+JSON protocol binding.
+// This tells the A2A client factory to prefer the HTTP+JSON interface when the agent card
+// advertises multiple supported interfaces.
+A2AClientOptions options = new()
+{
+    PreferredBindings = [ProtocolBindingNames.HttpJson]
+};
+
+// To prefer JSON-RPC instead, use:
+// A2AClientOptions options = new()
+// {
+//     PreferredBindings = [ProtocolBindingNames.JsonRpc]
+// };
+
+// Create an instance of the AIAgent for an existing A2A agent, using the specified protocol binding.
+AIAgent agent = agentCard.AsAIAgent(options: options);
+
+// Invoke the agent and output the text result.
+AgentResponse response = await agent.RunAsync("Tell me a joke about a pirate.");
+Console.WriteLine(response);

dotnet/samples/02-agents/A2A/A2AAgent_ProtocolSelection/README.md

@@ -0,0 +1,27 @@
+# A2A Agent Protocol Selection
+
+This sample demonstrates how to select the A2A protocol binding when creating an `AIAgent` from an A2A agent card.
+
+A2A agents can expose multiple interfaces with different protocol bindings (e.g., HTTP+JSON, JSON-RPC). By default, `AsAIAgent()` prefers HTTP+JSON with JSON-RPC as a fallback. This sample shows how to use `A2AClientOptions.PreferredBindings` to explicitly control which protocol binding is used.
+
+The sample:
+
+- Connects to an A2A agent server specified in the `A2A_AGENT_HOST` environment variable
+- Configures `A2AClientOptions` to prefer the HTTP+JSON protocol binding
+- Creates an `AIAgent` from the resolved agent card using the specified binding
+- Sends a message to the agent and displays the response
+
+## Prerequisites
+
+Before you begin, ensure you have the following prerequisites:
+
+- .NET 10.0 SDK or later
+- An A2A agent server running and accessible via HTTP
+
+**Note**: These samples need to be run against a valid A2A server. If no A2A server is available, they can be run against the echo-agent that can be spun up locally by following the guidelines at: https://github.com/a2aproject/a2a-dotnet/blob/main/samples/AgentServer/README.md
+
+Set the following environment variable:
+
+```powershell
+$env:A2A_AGENT_HOST="http://localhost:5000"  # Replace with your A2A agent server host
+```

dotnet/samples/02-agents/A2A/A2AAgent_StreamReconnection/A2AAgent_StreamReconnection.csproj

@@ -0,0 +1,23 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="A2A" />
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.Hosting" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.A2A\Microsoft.Agents.AI.A2A.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/02-agents/A2A/A2AAgent_StreamReconnection/Program.cs

@@ -0,0 +1,55 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to reconnect to an A2A agent's streaming response using continuation tokens,
+// allowing recovery from stream interruptions without losing progress.
+
+using A2A;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+var a2aAgentHost = Environment.GetEnvironmentVariable("A2A_AGENT_HOST") ?? throw new InvalidOperationException("A2A_AGENT_HOST is not set.");
+
+// Initialize an A2ACardResolver to get an A2A agent card.
+A2ACardResolver agentCardResolver = new(new Uri(a2aAgentHost));
+
+// Get the agent card
+AgentCard agentCard = await agentCardResolver.GetAgentCardAsync();
+
+// Create an instance of the AIAgent for an existing A2A agent specified by the agent card.
+AIAgent agent = agentCard.AsAIAgent();
+
+AgentSession session = await agent.CreateSessionAsync();
+
+ResponseContinuationToken? continuationToken = null;
+
+await foreach (var update in agent.RunStreamingAsync("Conduct a comprehensive analysis of quantum computing applications in cryptography, including recent breakthroughs, implementation challenges, and future roadmap. Please include diagrams and visual representations to illustrate complex concepts.", session))
+{
+    // Saving the continuation token to be able to reconnect to the same response stream later.
+    // Note: Continuation tokens are only returned for long-running tasks. If the underlying A2A agent
+    // returns a message instead of a task, the continuation token will not be initialized.
+    // A2A agents do not support stream resumption from a specific point in the stream,
+    // but only reconnection to obtain the same response stream from the beginning.
+    // So, A2A agents will return an initialized continuation token in the first update
+    // representing the beginning of the stream, and it will be null in all subsequent updates.
+    if (update.ContinuationToken is { } token)
+    {
+        continuationToken = token;
+    }
+
+    // Imitating stream interruption
+    break;
+}
+
+// Reconnect to the same response stream using the continuation token obtained from the previous run.
+// As a first update, the agent will return an update representing the current state of the response at the moment of calling
+// RunStreamingAsync with the same continuation token, followed by other updates until the end of the stream is reached.
+if (continuationToken is not null)
+{
+    await foreach (var update in agent.RunStreamingAsync(session, options: new() { ContinuationToken = continuationToken }))
+    {
+        if (!string.IsNullOrEmpty(update.Text))
+        {
+            Console.WriteLine(update.Text);
+        }
+    }
+}

dotnet/samples/02-agents/A2A/A2AAgent_StreamReconnection/README.md

@@ -0,0 +1,29 @@
+# A2A Agent Stream Reconnection
+
+This sample demonstrates how to reconnect to an A2A agent's streaming response using continuation tokens, allowing recovery from stream interruptions without losing progress.
+
+The sample:
+
+- Connects to an A2A agent server specified in the `A2A_AGENT_HOST` environment variable
+- Sends a request to the agent and begins streaming the response
+- Captures a continuation token from the stream for later reconnection
+- Simulates a stream interruption by breaking out of the streaming loop
+- Reconnects to the same response stream using the captured continuation token
+- Displays the response received after reconnection
+
+This pattern is useful when network interruptions or other failures may disrupt an ongoing streaming response, and you need to recover and continue processing.
+
+> **Note:** Continuation tokens are only available when the underlying A2A agent returns a task. If the agent returns a message instead, the continuation token will not be initialized and stream reconnection is not applicable.
+
+# Prerequisites
+
+Before you begin, ensure you have the following prerequisites:
+
+- .NET 10.0 SDK or later
+- An A2A agent server running and accessible via HTTP
+
+Set the following environment variable:
+
+```powershell
+$env:A2A_AGENT_HOST="http://localhost:5000"  # Replace with your A2A agent server host
+```

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

@@ -3,7 +3,7 @@
 These samples demonstrate how to work with Agent-to-Agent (A2A) specific features in the Agent Framework.
 
 For other samples that demonstrate how to use AIAgent instances,
-see the [Getting Started With Agents](../../02-agents/Agents/README.md) samples.
+see the [Getting Started With Agents](../Agents/README.md) samples.
 
 ## Prerequisites
 
@@ -15,6 +15,8 @@ See the README.md for each sample for the prerequisites for that sample.
 |---|---|
 |[A2A Agent As Function Tools](./A2AAgent_AsFunctionTools/)|This sample demonstrates how to represent an A2A agent as a set of function tools, where each function tool corresponds to a skill of the A2A agent, and register these function tools with another AI agent so it can leverage the A2A agent's skills.|
 |[A2A Agent Polling For Task Completion](./A2AAgent_PollingForTaskCompletion/)|This sample demonstrates how to poll for long-running task completion using continuation tokens with an A2A agent.|
+|[A2A Agent Stream Reconnection](./A2AAgent_StreamReconnection/)|This sample demonstrates how to reconnect to an A2A agent's streaming response using continuation tokens, allowing recovery from stream interruptions.|
+|[A2A Agent Protocol Selection](./A2AAgent_ProtocolSelection/)|This sample demonstrates how to select the A2A protocol binding (HTTP+JSON vs JSON-RPC) when creating an AIAgent from an A2A agent card using A2AClientOptions.|
 
 ## Running the samples from the console
 

dotnet/samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step06_CodeInterpreterFileDownload/Agent_OpenAI_Step06_CodeInterpreterFileDownload.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step06_CodeInterpreterFileDownload/Program.cs

@@ -0,0 +1,89 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to download files generated by Code Interpreter using the Containers API.
+// Code Interpreter generates files inside containers (cfile_ / cntr_ IDs) which cannot be
+// downloaded via the standard Files API. Use ContainerClient instead.
+
+#pragma warning disable OPENAI001
+
+using System.ClientModel;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using OpenAI;
+using OpenAI.Containers;
+using OpenAI.Responses;
+
+string apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY") ?? throw new InvalidOperationException("OPENAI_API_KEY is not set.");
+string model = Environment.GetEnvironmentVariable("OPENAI_CHAT_MODEL_NAME") ?? "gpt-4o-mini";
+
+var openAIClient = new OpenAIClient(new ApiKeyCredential(apiKey));
+
+// Create an agent with Code Interpreter tool enabled
+AIAgent agent = openAIClient
+    .GetResponsesClient()
+    .AsAIAgent(
+        model: model,
+        instructions: "You are a helpful assistant that can generate files using code.",
+        name: "CodeInterpreterAgent",
+        tools: [new HostedCodeInterpreterTool()]);
+
+// Ask the agent to generate a file
+AgentResponse response = await agent.RunAsync(
+    "Create a CSV file with the multiplication times tables from 1 to 12. Include headers.");
+
+// Display the text response
+foreach (TextContent textContent in response.Messages.SelectMany(x => x.Contents).OfType<TextContent>())
+{
+    Console.WriteLine(textContent.Text);
+}
+
+// Extract container file citations from response annotations and download
+ContainerClient containerClient = openAIClient.GetContainerClient();
+
+HashSet<string> downloadedFiles = [];
+bool foundContainerFiles = false;
+
+foreach (AIContent content in response.Messages.SelectMany(x => x.Contents))
+{
+    if (content.Annotations is null)
+    {
+        continue;
+    }
+
+    foreach (AIAnnotation annotation in content.Annotations)
+    {
+        // Container files from Code Interpreter have ContainerFileCitationMessageAnnotation as raw representation
+        if (annotation is CitationAnnotation citation
+            && citation.RawRepresentation is ContainerFileCitationMessageAnnotation containerCitation)
+        {
+            foundContainerFiles = true;
+
+            // Deduplicate by container+file ID in case the same file is cited multiple times
+            string key = $"{containerCitation.ContainerId}/{containerCitation.FileId}";
+            if (!downloadedFiles.Add(key))
+            {
+                continue;
+            }
+
+            Console.WriteLine($"\nDownloading container file: {containerCitation.Filename}");
+            Console.WriteLine($"  Container ID: {containerCitation.ContainerId}");
+            Console.WriteLine($"  File ID:      {containerCitation.FileId}");
+
+            BinaryData fileData = await containerClient.DownloadContainerFileAsync(
+                containerCitation.ContainerId,
+                containerCitation.FileId);
+
+            // Sanitize filename to prevent path traversal
+            string safeFilename = Path.GetFileName(containerCitation.Filename);
+            string outputPath = Path.Combine(Directory.GetCurrentDirectory(), safeFilename);
+            await File.WriteAllBytesAsync(outputPath, fileData.ToArray());
+            Console.WriteLine($"  Saved to:     {outputPath}");
+        }
+    }
+}
+
+if (!foundContainerFiles)
+{
+    Console.WriteLine("\nNo container file citations found in the response.");
+    Console.WriteLine("The model may not have generated a downloadable file for this prompt.");
+}

dotnet/samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step06_CodeInterpreterFileDownload/README.md

@@ -0,0 +1,51 @@
+# Code Interpreter File Download (OpenAI)
+
+This sample demonstrates how to download files generated by Code Interpreter when using the OpenAI Responses API.
+
+## What this sample demonstrates
+
+- Creating an agent with Code Interpreter tool using `ResponsesClient.AsAIAgent()`
+- Generating files through Code Interpreter (e.g., CSV, Excel, images)
+- Extracting container file citations from agent response annotations
+- Downloading container files using the `ContainerClient` API
+
+## Container files vs regular files
+
+When Code Interpreter generates a file, the file is stored inside a **container** with a `cntr_` prefixed ID. The file itself gets a `cfile_` prefixed ID.
+
+These container files **cannot** be downloaded using the standard Files API (`GetOpenAIFileClient`), which returns 404 for `cfile_` IDs. Instead, you must use the **Containers API** (`GetContainerClient`) to download them:
+
+```csharp
+// ❌ This does NOT work for container files
+var filesClient = openAIClient.GetOpenAIFileClient();
+await filesClient.DownloadFileAsync("cfile_...");  // Returns 404
+
+// ✅ Use ContainerClient instead
+var containerClient = openAIClient.GetContainerClient();
+await containerClient.DownloadContainerFileAsync("cntr_...", "cfile_...");
+```
+
+The container ID and file ID are available from the `ContainerFileCitationMessageAnnotation` annotation in the response, accessible via `CitationAnnotation.RawRepresentation`.
+
+## Prerequisites
+
+- .NET 10 SDK or later
+- OpenAI API key with access to a model that supports Code Interpreter
+
+Set the following environment variables:
+
+```powershell
+$env:OPENAI_API_KEY="sk-..."
+$env:OPENAI_CHAT_MODEL_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
+```
+
+## Run the sample
+
+```powershell
+dotnet run
+```
+
+## See also
+
+- [Code Interpreter File Download with Foundry](../../../02-agents/AgentsWithFoundry/Agent_Step24_CodeInterpreterFileDownload/) — same scenario using Microsoft Foundry
+- [Code Interpreter](../../../02-agents/AgentsWithFoundry/Agent_Step14_CodeInterpreter/) — Code Interpreter without file download

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

@@ -14,4 +14,5 @@ Agent Framework provides additional support to allow OpenAI developers to use th
 |[Using Reasoning Capabilities](./Agent_OpenAI_Step02_Reasoning/)|This sample demonstrates how to create an AI agent with reasoning capabilities using OpenAI's reasoning models and response types.|
 |[Creating an Agent from a ChatClient](./Agent_OpenAI_Step03_CreateFromChatClient/)|This sample demonstrates how to create an AI agent directly from an OpenAI.Chat.ChatClient instance using OpenAIChatClientAgent.|
 |[Creating an Agent from an OpenAIResponseClient](./Agent_OpenAI_Step04_CreateFromOpenAIResponseClient/)|This sample demonstrates how to create an AI agent directly from an OpenAI.Responses.OpenAIResponseClient instance using OpenAIResponseClientAgent.|
-|[Managing Conversation State](./Agent_OpenAI_Step05_Conversation/)|This sample demonstrates how to maintain conversation state across multiple turns using the AgentSession for context continuity.|
+|[Managing Conversation State](./Agent_OpenAI_Step05_Conversation/)|This sample demonstrates how to maintain conversation state across multiple turns using the AgentSession for context continuity.|
+|[Code Interpreter File Download](./Agent_OpenAI_Step06_CodeInterpreterFileDownload/)|This sample demonstrates how to download files generated by Code Interpreter using the Containers API (`cfile_`/`cntr_` IDs).|

dotnet/samples/02-agents/Agents/Agent_Step20_DynamicFunctionTools/Agent_Step20_DynamicFunctionTools.csproj

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

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

@@ -0,0 +1,281 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to dynamically expand the set of function tools available to an
+// agent during a function-calling loop. The agent starts with a single "RequestTools" function.
+// When the model calls RequestTools with a description of the capabilities needed, the function
+// uses the ambient FunctionInvocationContext to add new tools to ChatOptions.Tools. The agent
+// can then use the newly added tools in subsequent iterations of the same function-calling loop.
+
+using System.ComponentModel;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+
+// Pre-defined tool implementations that can be loaded on demand.
+[Description("Get the current weather for a city.")]
+static string GetWeather([Description("The city name.")] string city) =>
+    city.ToUpperInvariant() switch
+    {
+        "SEATTLE" => "Seattle: 55°F, cloudy with light rain.",
+        "NEW YORK" => "New York: 72°F, sunny and warm.",
+        "LONDON" => "London: 48°F, overcast with fog.",
+        _ => $"{city}: weather data not available, please provide one of the following city names: 'Seattle', 'New York', 'London'."
+    };
+
+[Description("Get the current local time for a city.")]
+static string GetTime([Description("The city name.")] string city) =>
+    city.ToUpperInvariant() switch
+    {
+        "SEATTLE" => "Seattle: 9:00 AM PST",
+        "NEW YORK" => "New York: 12:00 PM EST",
+        "LONDON" => "London: 5:00 PM GMT",
+        _ => $"{city}: time data not available, please provide one of the following city names: 'Seattle', 'New York', 'London'."
+    };
+
+[Description("Convert a temperature from Fahrenheit to Celsius.")]
+static string ConvertFahrenheitToCelsius([Description("The temperature in Fahrenheit.")] double fahrenheit) =>
+    $"{fahrenheit}°F = {(fahrenheit - 32) * 5 / 9:F1}°C";
+
+// A registry of tool sets that can be loaded by description keyword.
+Dictionary<string, List<AITool>> toolCatalog = new(StringComparer.OrdinalIgnoreCase)
+{
+    ["weather"] = [AIFunctionFactory.Create(GetWeather, name: "GetWeather")],
+    ["time"] = [AIFunctionFactory.Create(GetTime, name: "GetTime")],
+    ["temperature"] = [AIFunctionFactory.Create(ConvertFahrenheitToCelsius, name: "ConvertFahrenheitToCelsius")],
+};
+
+// The RequestTools function uses the ambient FunctionInvocationContext to add tools dynamically.
+AIFunction requestToolsFunction = AIFunctionFactory.Create(
+    [Description("Request additional tools to be loaded based on a description of the functionality needed. " +
+                 "Call this when you need capabilities that are not yet available in your current tool set.")] (
+        [Description("A description of the functionality required, e.g. 'weather', 'time', or 'temperature conversion'.")] string description
+    ) =>
+    {
+        // Access the ambient FunctionInvocationContext provided by FunctionInvokingChatClient.
+        var context = FunctionInvokingChatClient.CurrentContext
+            ?? throw new InvalidOperationException("No ambient FunctionInvocationContext available.");
+
+        var tools = context.Options?.Tools;
+        if (tools is null)
+        {
+            return "Unable to register new tools: ChatOptions.Tools is not available.";
+        }
+
+        // Find matching tool sets from the catalog.
+        List<string> addedToolNames = [];
+        foreach (var kvp in toolCatalog)
+        {
+            var keyword = kvp.Key;
+            var catalogTools = kvp.Value;
+            if (description.Contains(keyword, StringComparison.OrdinalIgnoreCase))
+            {
+                foreach (var tool in catalogTools)
+                {
+                    // Avoid adding duplicates.
+                    if (tool is AIFunction fn && !tools.Any(t => t is AIFunction existing && existing.Name == fn.Name))
+                    {
+                        tools.Add(tool);
+                        addedToolNames.Add(fn.Name);
+                    }
+                }
+            }
+        }
+
+        return addedToolNames.Count > 0
+            ? "Successfully loaded tools"
+            : $"No tools matched the description '{description}'. Available categories: {string.Join(", ", toolCatalog.Keys)}.";
+    },
+    name: "RequestTools");
+
+// Create the agent with only the RequestTools function initially.
+// Insert chat client middleware that logs the tools available on each LLM call,
+// making the dynamic expansion visible in the console output.
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+AIAgent agent = new AzureOpenAIClient(
+    new Uri(endpoint),
+    new DefaultAzureCredential())
+    .GetChatClient(deploymentName)
+    .AsIChatClient()
+    .AsBuilder()
+    .Use(getResponseFunc: ToolLoggingMiddleware, getStreamingResponseFunc: ToolLoggingStreamingMiddleware)
+    .BuildAIAgent(
+        instructions: """
+            You are a helpful assistant. You start with limited tools.
+            When you need functionality that you don't currently have, call RequestTools with a description
+            of what you need. After new tools are loaded, use them to answer the user's question.
+            """,
+        tools: [requestToolsFunction]);
+
+// Run a conversation that triggers dynamic tool expansion.
+Console.WriteLine("=== Dynamic Function Tools Sample ===\n");
+
+string[] prompts =
+[
+    "What's the weather like in Seattle and London?",
+    "What time is it in New York?",
+    "Can you convert those temperatures to Celsius?"
+];
+
+// --- Non-Streaming Mode ---
+Console.ForegroundColor = ConsoleColor.Yellow;
+Console.WriteLine("=== Non-Streaming Mode ===");
+Console.ResetColor();
+Console.WriteLine();
+
+AgentSession session = await agent.CreateSessionAsync();
+
+foreach (var prompt in prompts)
+{
+    Console.ForegroundColor = ConsoleColor.Green;
+    Console.Write("[User] ");
+    Console.ResetColor();
+    Console.WriteLine(prompt);
+
+    var response = await agent.RunAsync(prompt, session);
+
+    // Print all message contents including tool calls, tool results, and text.
+    foreach (var message in response.Messages)
+    {
+        foreach (var content in message.Contents)
+        {
+            switch (content)
+            {
+                case FunctionCallContent functionCall:
+                    Console.ForegroundColor = ConsoleColor.Yellow;
+                    Console.WriteLine($"  [Tool Call] {functionCall.Name}({string.Join(", ", functionCall.Arguments?.Select(a => $"{a.Key}: {a.Value}") ?? [])})");
+                    Console.ResetColor();
+                    break;
+
+                case FunctionResultContent functionResult:
+                    Console.ForegroundColor = ConsoleColor.DarkYellow;
+                    Console.WriteLine($"  [Tool Result] {functionResult.CallId} => {functionResult.Result}");
+                    Console.ResetColor();
+                    break;
+
+                case TextContent textContent when !string.IsNullOrWhiteSpace(textContent.Text):
+                    Console.ForegroundColor = ConsoleColor.Cyan;
+                    Console.Write("[Agent] ");
+                    Console.ResetColor();
+                    Console.WriteLine(textContent.Text);
+                    break;
+            }
+        }
+    }
+
+    Console.WriteLine();
+}
+
+// --- Streaming Mode ---
+Console.ForegroundColor = ConsoleColor.Yellow;
+Console.WriteLine("=== Streaming Mode ===");
+Console.ResetColor();
+Console.WriteLine();
+
+AgentSession streamingSession = await agent.CreateSessionAsync();
+
+foreach (var prompt in prompts)
+{
+    Console.ForegroundColor = ConsoleColor.Green;
+    Console.Write("[User] ");
+    Console.ResetColor();
+    Console.WriteLine(prompt);
+
+    bool inAgentText = false;
+
+    await foreach (var update in agent.RunStreamingAsync(prompt, streamingSession))
+    {
+        foreach (var content in update.Contents)
+        {
+            switch (content)
+            {
+                case FunctionCallContent functionCall:
+                    if (inAgentText)
+                    {
+                        Console.WriteLine();
+                        inAgentText = false;
+                    }
+
+                    Console.ForegroundColor = ConsoleColor.Yellow;
+                    Console.WriteLine($"  [Tool Call] {functionCall.Name}({string.Join(", ", functionCall.Arguments?.Select(a => $"{a.Key}: {a.Value}") ?? [])})");
+                    Console.ResetColor();
+                    break;
+
+                case FunctionResultContent functionResult:
+                    Console.ForegroundColor = ConsoleColor.DarkYellow;
+                    Console.WriteLine($"  [Tool Result] {functionResult.CallId} => {functionResult.Result}");
+                    Console.ResetColor();
+                    break;
+
+                case TextContent textContent when !string.IsNullOrWhiteSpace(textContent.Text):
+                    if (!inAgentText)
+                    {
+                        Console.ForegroundColor = ConsoleColor.Cyan;
+                        Console.Write("[Agent] ");
+                        Console.ResetColor();
+                        inAgentText = true;
+                    }
+
+                    Console.Write(textContent.Text);
+                    break;
+            }
+        }
+    }
+
+    if (inAgentText)
+    {
+        Console.WriteLine();
+    }
+
+    Console.WriteLine();
+}
+
+// Chat client middleware that logs the number and names of tools on each LLM request.
+async Task<ChatResponse> ToolLoggingMiddleware(
+    IEnumerable<ChatMessage> messages,
+    ChatOptions? options,
+    IChatClient innerChatClient,
+    CancellationToken cancellationToken)
+{
+    LogTools(options);
+
+    return await innerChatClient.GetResponseAsync(messages, options, cancellationToken);
+}
+
+// Streaming version of the tool logging middleware.
+async IAsyncEnumerable<ChatResponseUpdate> ToolLoggingStreamingMiddleware(
+    IEnumerable<ChatMessage> messages,
+    ChatOptions? options,
+    IChatClient innerChatClient,
+    [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken)
+{
+    LogTools(options);
+
+    await foreach (var update in innerChatClient.GetStreamingResponseAsync(messages, options, cancellationToken))
+    {
+        yield return update;
+    }
+}
+
+// Shared helper to log the current tool set.
+void LogTools(ChatOptions? options)
+{
+    if (options?.Tools is { Count: > 0 } tools)
+    {
+        var toolNames = tools.OfType<AIFunction>().Select(t => t.Name);
+        Console.ForegroundColor = ConsoleColor.DarkGray;
+        Console.WriteLine($"  [Middleware] LLM call with {tools.Count} tool(s): {string.Join(", ", toolNames)}");
+        Console.ResetColor();
+    }
+    else
+    {
+        Console.ForegroundColor = ConsoleColor.DarkGray;
+        Console.WriteLine("  [Middleware] LLM call with 0 tools");
+        Console.ResetColor();
+    }
+}

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

@@ -0,0 +1,38 @@
+# Dynamic Function Tools
+
+This sample demonstrates how to dynamically expand the set of function tools available to an agent during a function-calling loop.
+
+## What it demonstrates
+
+- The agent starts with only a single `RequestTools` function
+- When the model needs capabilities it doesn't have, it calls `RequestTools` with a description of the functionality needed
+- The `RequestTools` function uses the ambient `FunctionInvokingChatClient.CurrentContext` to access `ChatOptions.Tools` and add new tools at runtime
+- The agent then uses the newly added tools in subsequent iterations of the same function-calling loop
+
+## How it works
+
+1. A tool catalog maps keywords (e.g. "weather", "time", "temperature") to pre-built `AIFunction` instances
+2. The `RequestTools` function matches the description against catalog keywords and adds matching tools to `ChatOptions.Tools`
+3. `FunctionInvokingChatClient` automatically picks up the new tools on the next iteration of its loop
+
+## Prerequisites
+
+- .NET 10 SDK or later
+- Azure OpenAI service endpoint and deployment configured
+- Azure CLI installed and authenticated (for Azure credential authentication)
+- User has the `Cognitive Services OpenAI Contributor` role for the Azure OpenAI resource
+
+## Running the sample
+
+Set the required environment variables:
+
+```powershell
+$env:AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
+$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-5.4-mini"  # Optional, defaults to gpt-5.4-mini
+```
+
+Run the sample:
+
+```powershell
+dotnet run
+```

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

@@ -46,6 +46,7 @@ Before you begin, ensure you have the following prerequisites:
 |[Providing additional AI Context to an agent using multiple AIContextProviders](./Agent_Step17_AdditionalAIContext/)|This sample demonstrates how to inject additional AI context into a ChatClientAgent using multiple custom AIContextProvider components that are attached to the agent.|
 |[Using compaction pipeline with an agent](./Agent_Step18_CompactionPipeline/)|This sample demonstrates how to use a compaction pipeline to efficiently limit the size of the conversation history for an agent.|
 |[In-function-loop checkpointing](./Agent_Step19_InFunctionLoopCheckpointing/)|This sample demonstrates how to persist chat history after each service call during a tool-calling loop, enabling crash recovery and mid-run observability.|
+|[Dynamic function tools](./Agent_Step20_DynamicFunctionTools/)|This sample demonstrates how to dynamically expand the set of function tools available to an agent during a function-calling loop using the ambient FunctionInvocationContext.|
 
 ## Running the samples from the console
 

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

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

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

@@ -0,0 +1,91 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to download files generated by Code Interpreter using Microsoft Foundry.
+// Code Interpreter generates files inside containers (cfile_ / cntr_ IDs) which cannot be
+// downloaded via the standard Files API. Use ContainerClient from the project's OpenAI client instead.
+
+#pragma warning disable OPENAI001
+
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using OpenAI.Responses;
+
+string endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());
+
+// Create an agent with Code Interpreter tool enabled
+AIAgent agent = aiProjectClient.AsAIAgent(
+    deploymentName,
+    instructions: "You are a helpful assistant that can generate files using code.",
+    name: "CodeInterpreterAgent",
+    tools: [new HostedCodeInterpreterTool()]);
+
+// Ask the agent to generate a file
+AgentResponse response = await agent.RunAsync(
+    "Create a CSV file with the multiplication times tables from 1 to 12. Include headers.");
+
+// Display the text response
+foreach (TextContent textContent in response.Messages.SelectMany(x => x.Contents).OfType<TextContent>())
+{
+    Console.WriteLine(textContent.Text);
+}
+
+// Extract container file citations from response annotations and download.
+// AIProjectClient.GetProjectOpenAIClient() returns a ProjectOpenAIClient (inherits from OpenAI.OpenAIClient)
+// which supports GetContainerClient(), unlike AzureOpenAIClient which does not.
+var containerClient = aiProjectClient.GetProjectOpenAIClient().GetContainerClient();
+
+HashSet<string> downloadedFiles = [];
+bool foundContainerFiles = false;
+
+foreach (AIContent content in response.Messages.SelectMany(x => x.Contents))
+{
+    if (content.Annotations is null)
+    {
+        continue;
+    }
+
+    foreach (AIAnnotation annotation in content.Annotations)
+    {
+        // Container files from Code Interpreter have ContainerFileCitationMessageAnnotation as raw representation
+        if (annotation is CitationAnnotation citation
+            && citation.RawRepresentation is ContainerFileCitationMessageAnnotation containerCitation)
+        {
+            foundContainerFiles = true;
+
+            // Deduplicate by container+file ID in case the same file is cited multiple times
+            string key = $"{containerCitation.ContainerId}/{containerCitation.FileId}";
+            if (!downloadedFiles.Add(key))
+            {
+                continue;
+            }
+
+            Console.WriteLine($"\nDownloading container file: {containerCitation.Filename}");
+            Console.WriteLine($"  Container ID: {containerCitation.ContainerId}");
+            Console.WriteLine($"  File ID:      {containerCitation.FileId}");
+
+            BinaryData fileData = await containerClient.DownloadContainerFileAsync(
+                containerCitation.ContainerId,
+                containerCitation.FileId);
+
+            // Sanitize filename to prevent path traversal
+            string safeFilename = Path.GetFileName(containerCitation.Filename);
+            string outputPath = Path.Combine(Directory.GetCurrentDirectory(), safeFilename);
+            await File.WriteAllBytesAsync(outputPath, fileData.ToArray());
+            Console.WriteLine($"  Saved to:     {outputPath}");
+        }
+    }
+}
+
+if (!foundContainerFiles)
+{
+    Console.WriteLine("\nNo container file citations found in the response.");
+    Console.WriteLine("The model may not have generated a downloadable file for this prompt.");
+}

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

@@ -0,0 +1,56 @@
+# Code Interpreter File Download (Microsoft Foundry)
+
+This sample demonstrates how to download files generated by Code Interpreter when using Microsoft Foundry.
+
+## What this sample demonstrates
+
+- Creating an agent with Code Interpreter tool using `AIProjectClient.AsAIAgent()`
+- Generating files through Code Interpreter (e.g., CSV, Excel, images)
+- Extracting container file citations from agent response annotations
+- Downloading container files using the `ContainerClient` via `AIProjectClient.GetProjectOpenAIClient()`
+
+## Container files vs regular files
+
+When Code Interpreter generates a file, the file is stored inside a **container** with a `cntr_` prefixed ID. The file itself gets a `cfile_` prefixed ID.
+
+These container files **cannot** be downloaded using the standard Files API (`GetOpenAIFileClient`), which returns 404 for `cfile_` IDs. Instead, you must use the **Containers API** to download them.
+
+### Getting the ContainerClient with Foundry
+
+`AzureOpenAIClient.GetContainerClient()` is not supported and throws `InvalidOperationException`. Instead, use the project's OpenAI client which inherits directly from `OpenAI.OpenAIClient`:
+
+```csharp
+// ❌ AzureOpenAIClient does not support ContainerClient
+var azureClient = new AzureOpenAIClient(endpoint, credential);
+azureClient.GetContainerClient();  // Throws InvalidOperationException
+
+// ✅ Use AIProjectClient's project OpenAI client
+var containerClient = aiProjectClient.GetProjectOpenAIClient().GetContainerClient();
+await containerClient.DownloadContainerFileAsync("cntr_...", "cfile_...");
+```
+
+The container ID and file ID are available from the `ContainerFileCitationMessageAnnotation` annotation in the response, accessible via `CitationAnnotation.RawRepresentation`.
+
+## Prerequisites
+
+- .NET 10 SDK or later
+- Microsoft Foundry service endpoint and deployment configured
+- Azure CLI installed and authenticated (`az login`)
+
+Set the following environment variables:
+
+```powershell
+$env:AZURE_AI_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project"
+$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
+```
+
+## Run the sample
+
+```powershell
+dotnet run
+```
+
+## See also
+
+- [Code Interpreter File Download with OpenAI](../../../02-agents/AgentWithOpenAI/Agent_OpenAI_Step06_CodeInterpreterFileDownload/) — same scenario using Public OpenAI
+- [Code Interpreter](../Agent_Step14_CodeInterpreter/) — Code Interpreter without file download

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

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

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

@@ -0,0 +1,148 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to load a Foundry toolbox and pass its tools as server-side
+// tools when creating an agent. The Foundry platform handles tool execution — the agent
+// process does not invoke tools locally.
+
+using System.ClientModel;
+using System.ClientModel.Primitives;
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using OpenAI.Responses;
+
+#pragma warning disable OPENAI001 // Experimental API
+#pragma warning disable AAIP001  // AgentToolboxes is experimental
+#pragma warning disable CS8321   // Local functions may be commented-out alternatives
+
+// Replace with your own Foundry toolbox name.
+const string ToolboxName = "research_toolbox";
+// Used only by CombineToolboxes — swap in a second toolbox you own.
+const string SecondToolboxName = "analysis_toolbox";
+// Replace with any question that exercises the tools configured in your toolbox.
+const string Query = "Introduce yourself and briefly describe the tools you can use to help me.";
+
+string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("Set FOUNDRY_PROJECT_ENDPOINT to your Foundry project endpoint.");
+string model = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
+
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+var projectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential());
+
+await Main(projectClient, model, endpoint);
+// await CombineToolboxes(projectClient, model, endpoint);
+
+// ---------------------------------------------------------------------------
+// Main: single toolbox
+// ---------------------------------------------------------------------------
+static async Task Main(AIProjectClient projectClient, string model, string endpoint)
+{
+    Console.WriteLine("=== Foundry Toolbox Server-Side Tools Example ===");
+
+    // Comment out if the toolbox already exists in your Foundry project.
+    await CreateSampleToolboxAsync(ToolboxName, endpoint);
+
+    // Omit the version to resolve the toolbox's current default version at runtime.
+    var tools = await projectClient.GetToolboxToolsAsync(ToolboxName);
+
+    AIAgent agent = projectClient
+        .AsAIAgent(
+            model: model,
+            instructions: "You are a research assistant. Use the available tools to answer questions.",
+            tools: tools.ToList());
+
+    Console.WriteLine($"User: {Query}");
+    Console.WriteLine($"Result: {await agent.RunAsync(Query)}\n");
+}
+
+// ---------------------------------------------------------------------------
+// Alternative: combine tools from multiple toolboxes
+// ---------------------------------------------------------------------------
+static async Task CombineToolboxes(AIProjectClient projectClient, string model, string endpoint)
+{
+    Console.WriteLine("=== Combine Toolboxes Example ===");
+
+    // Comment out if the toolboxes already exist in your Foundry project.
+    await CreateSampleToolboxAsync(ToolboxName, endpoint);
+    await CreateSampleToolboxAsync(SecondToolboxName, endpoint);
+
+    var toolboxA = await projectClient.GetToolboxToolsAsync(ToolboxName);
+    var toolboxB = await projectClient.GetToolboxToolsAsync(SecondToolboxName);
+
+    var allTools = toolboxA.Concat(toolboxB).ToList();
+
+    AIAgent agent = projectClient
+        .AsAIAgent(
+            model: model,
+            instructions: "You are a research assistant. Use all available tools to answer questions.",
+            tools: allTools);
+
+    Console.WriteLine($"User: {Query}");
+    Console.WriteLine($"Combined-toolbox result: {await agent.RunAsync(Query)}\n");
+}
+
+// ---------------------------------------------------------------------------
+// Helper: create (or replace) a sample toolbox so the sample works out-of-the-box
+// ---------------------------------------------------------------------------
+static async Task CreateSampleToolboxAsync(string name, string endpoint)
+{
+    // Toolboxes are normally configured in the Foundry portal or a deployment
+    // script, not the application itself. This helper exists so the sample can
+    // be run end-to-end without first setting a toolbox up by hand.
+
+    // The Foundry-Features header is currently required for toolbox CRUD operations.
+    var options = new AgentAdministrationClientOptions();
+    options.AddPolicy(new FoundryFeaturesPolicy("Toolboxes=V1Preview"), PipelinePosition.PerCall);
+    var adminClient = new AgentAdministrationClient(
+        new Uri(endpoint),
+        new DefaultAzureCredential(),
+        options);
+    var toolboxClient = adminClient.GetAgentToolboxes();
+
+    // Delete existing toolbox if present (ignore 404).
+    try
+    {
+        await toolboxClient.DeleteToolboxAsync(name);
+        Console.WriteLine($"Deleted existing toolbox '{name}'");
+    }
+    catch (ClientResultException ex) when (ex.Status == 404)
+    {
+        // Toolbox does not exist — nothing to delete.
+    }
+
+    // Create a fresh version with a single MCP tool.
+    ProjectsAgentTool mcpTool = ProjectsAgentTool.AsProjectTool(ResponseTool.CreateMcpTool(
+        serverLabel: "api-specs",
+        serverUri: new Uri("https://gitmcp.io/Azure/azure-rest-api-specs"),
+        toolCallApprovalPolicy: new McpToolCallApprovalPolicy(GlobalMcpToolCallApprovalPolicy.NeverRequireApproval)));
+
+    var created = (await toolboxClient.CreateToolboxVersionAsync(
+        name: name,
+        tools: [mcpTool],
+        description: "Sample toolbox with an MCP tool — created by Agent_Step25 sample.")).Value;
+
+    Console.WriteLine($"Created toolbox '{created.Name}' v{created.Version} ({created.Tools.Count} tool(s))");
+}
+
+// ---------------------------------------------------------------------------
+// Pipeline policy that adds the Foundry-Features header for toolbox CRUD
+// ---------------------------------------------------------------------------
+internal sealed class FoundryFeaturesPolicy(string feature) : PipelinePolicy
+{
+    private const string FeatureHeader = "Foundry-Features";
+
+    public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+    {
+        message.Request.Headers.Add(FeatureHeader, feature);
+        ProcessNext(message, pipeline, currentIndex);
+    }
+
+    public override ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+    {
+        message.Request.Headers.Add(FeatureHeader, feature);
+        return ProcessNextAsync(message, pipeline, currentIndex);
+    }
+}

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

@@ -0,0 +1,46 @@
+# Agent_Step25_ToolboxServerSideTools
+
+This sample demonstrates loading a named Foundry toolbox and passing its tools as
+**server-side tools** when creating an agent via `AsAIAgent()`.
+
+When tools from a toolbox are passed this way, they are sent as tool definitions in
+the Responses API request. The Foundry platform handles tool execution — the agent
+process does not invoke tools locally.
+
+This is the dotnet equivalent of the Python sample:
+`python/samples/02-agents/providers/foundry/foundry_chat_client_with_toolbox.py`
+
+## Prerequisites
+
+- A Microsoft Foundry project
+- `AZURE_AI_PROJECT_ENDPOINT` environment variable set to your Foundry project endpoint
+- `AZURE_AI_MODEL_DEPLOYMENT_NAME` environment variable set (defaults to `gpt-5.4-mini`)
+
+The sample recreates the toolbox on each run, replacing any existing toolbox with
+the same name. Comment out the `CreateSampleToolboxAsync` call if you want to keep
+an existing toolbox unchanged.
+
+## How it works
+
+1. `projectClient.GetToolboxVersionAsync(name)` fetches the toolbox definition from the
+   Foundry project API (resolving the default version if none is specified)
+2. `ToolboxVersion.ToAITools()` converts each tool definition to an `AITool` instance
+3. The tools are passed to `AsAIAgent(tools: ...)` which includes them in the Responses
+   API request as server-side tool definitions
+
+For a one-liner, use `projectClient.GetToolboxToolsAsync(name)` to fetch and convert in one call.
+
+## Sample flows
+
+| Flow | Description |
+|------|-------------|
+| `Main` (default) | Loads a single toolbox and runs an agent with its tools |
+| `CombineToolboxes` | Loads two toolboxes and merges their tools into one agent |
+
+Uncomment the desired flow in the top-level statements to try each one.
+
+## Running the sample
+
+```bash
+dotnet run
+```

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

@@ -72,6 +72,7 @@ Some samples require extra tool-specific environment variables. See each sample
 | [Web search](./Agent_Step21_WebSearch/) | Web search tool |
 | [Memory search](./Agent_Step22_MemorySearch/) | Memory search tool |
 | [Local MCP](./Agent_Step23_LocalMCP/) | Local MCP client with HTTP transport |
+| [Code interpreter file download](./Agent_Step24_CodeInterpreterFileDownload/) | Download container files generated by code interpreter |
 
 ## Running the samples
 

dotnet/samples/02-agents/README.md

@@ -19,3 +19,4 @@ The getting started samples demonstrate the fundamental concepts and functionali
 | [Declarative Agents](./DeclarativeAgents) | Loading and executing AI agents from YAML configuration files |
 | [AG-UI](./AGUI/README.md) | Getting started with AG-UI (Agent UI Protocol) servers and clients |
 | [Dev UI](./DevUI/README.md) | Interactive web interface for testing and debugging AI agents during development |
+| [A2A Agents](./A2A/README.md) | Working with Agent-to-Agent (A2A) specific features |

dotnet/samples/04-hosting/.gitignore

@@ -0,0 +1 @@
+**/Properties/launchSettings.json

dotnet/samples/04-hosting/FoundryHostedAgents/invocations/Hosted-Invocations-EchoAgent/.env.example

@@ -0,0 +1,2 @@
+ASPNETCORE_URLS=http://+:8088
+ASPNETCORE_ENVIRONMENT=Development

dotnet/samples/04-hosting/FoundryHostedAgents/invocations/Hosted-Invocations-EchoAgent/Dockerfile

@@ -0,0 +1,17 @@
+# Use the official .NET 10.0 ASP.NET runtime as a parent image
+FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
+WORKDIR /app
+
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /src
+COPY . .
+RUN dotnet restore
+RUN dotnet publish -c Release -o /app/publish
+
+# Final stage
+FROM base AS final
+WORKDIR /app
+COPY --from=build /app/publish .
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+ENTRYPOINT ["dotnet", "HostedInvocationsEchoAgent.dll"]

dotnet/samples/04-hosting/FoundryHostedAgents/invocations/Hosted-Invocations-EchoAgent/Dockerfile.contributor

@@ -0,0 +1,19 @@
+# Dockerfile for contributors building from the agent-framework repository source.
+#
+# This project uses ProjectReference to the local Microsoft.Agents.AI.Abstractions source,
+# which means a standard multi-stage Docker build cannot resolve dependencies outside
+# this folder. Instead, pre-publish the app targeting the container runtime and copy
+# the output into the container:
+#
+#   dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+#   docker build -f Dockerfile.contributor -t hosted-invocations-echo-agent .
+#   docker run --rm -p 8088:8088 hosted-invocations-echo-agent
+#
+# For end-users consuming the NuGet package (not ProjectReference), use the standard
+# Dockerfile which performs a full dotnet restore + publish inside the container.
+FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final
+WORKDIR /app
+COPY out/ .
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+ENTRYPOINT ["dotnet", "HostedInvocationsEchoAgent.dll"]

dotnet/samples/04-hosting/FoundryHostedAgents/invocations/Hosted-Invocations-EchoAgent/EchoAIAgent.cs

@@ -0,0 +1,85 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Runtime.CompilerServices;
+using System.Text.Json;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// A minimal <see cref="AIAgent"/> that echoes the user's input text back as the response.
+/// No LLM or external service is required.
+/// </summary>
+public sealed class EchoAIAgent : AIAgent
+{
+    /// <inheritdoc/>
+    public override string Name => "echo-agent";
+
+    /// <inheritdoc/>
+    public override string Description => "An agent that echoes back the input message.";
+
+    /// <inheritdoc/>
+    protected override Task<AgentResponse> RunCoreAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        var inputText = GetInputText(messages);
+        var response = new AgentResponse(new ChatMessage(ChatRole.Assistant, $"Echo: {inputText}"));
+        return Task.FromResult(response);
+    }
+
+    /// <inheritdoc/>
+    protected override async IAsyncEnumerable<AgentResponseUpdate> RunCoreStreamingAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        var inputText = GetInputText(messages);
+        yield return new AgentResponseUpdate
+        {
+            Role = ChatRole.Assistant,
+            Contents = [new TextContent($"Echo: {inputText}")],
+        };
+
+        await Task.CompletedTask;
+    }
+
+    /// <inheritdoc/>
+    protected override ValueTask<AgentSession> CreateSessionCoreAsync(CancellationToken cancellationToken = default)
+        => new(new EchoAgentSession());
+
+    /// <inheritdoc/>
+    protected override ValueTask<JsonElement> SerializeSessionCoreAsync(
+        AgentSession session,
+        JsonSerializerOptions? jsonSerializerOptions = null,
+        CancellationToken cancellationToken = default)
+        => new(JsonSerializer.SerializeToElement(new { }, jsonSerializerOptions));
+
+    /// <inheritdoc/>
+    protected override ValueTask<AgentSession> DeserializeSessionCoreAsync(
+        JsonElement serializedState,
+        JsonSerializerOptions? jsonSerializerOptions = null,
+        CancellationToken cancellationToken = default)
+        => new(new EchoAgentSession());
+
+    private static string GetInputText(IEnumerable<ChatMessage> messages)
+    {
+        foreach (var message in messages)
+        {
+            if (message.Role == ChatRole.User)
+            {
+                return message.Text ?? string.Empty;
+            }
+        }
+
+        return string.Empty;
+    }
+
+    /// <summary>
+    /// Minimal session for the echo agent. No state is persisted.
+    /// </summary>
+    private sealed class EchoAgentSession : AgentSession;
+}

dotnet/samples/04-hosting/FoundryHostedAgents/invocations/Hosted-Invocations-EchoAgent/EchoInvocationHandler.cs

@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.AgentServer.Invocations;
+using Microsoft.Agents.AI;
+
+namespace HostedInvocationsEchoAgent;
+
+/// <summary>
+/// An <see cref="InvocationHandler"/> that reads the request body as plain text,
+/// passes it to the <see cref="EchoAIAgent"/>, and writes the response back.
+/// </summary>
+public sealed class EchoInvocationHandler(EchoAIAgent agent) : InvocationHandler
+{
+    /// <inheritdoc/>
+    public override async Task HandleAsync(
+        HttpRequest request,
+        HttpResponse response,
+        InvocationContext context,
+        CancellationToken cancellationToken)
+    {
+        // Read the raw text from the request body.
+        using var reader = new StreamReader(request.Body);
+        var input = await reader.ReadToEndAsync(cancellationToken);
+
+        // Run the echo agent with the input text.
+        var agentResponse = await agent.RunAsync(input, cancellationToken: cancellationToken);
+
+        // Write the agent response text back to the HTTP response.
+        response.ContentType = "text/plain";
+        await response.WriteAsync(agentResponse.Text, cancellationToken);
+    }
+}

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

@@ -0,0 +1,30 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <CentralPackageTransitivePinningEnabled>false</CentralPackageTransitivePinningEnabled>
+    <RootNamespace>HostedInvocationsEchoAgent</RootNamespace>
+    <AssemblyName>HostedInvocationsEchoAgent</AssemblyName>
+    <NoWarn>$(NoWarn);</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.AgentServer.Invocations" />
+    <PackageReference Include="DotNetEnv" />
+  </ItemGroup>
+
+  <!-- For contributors: uses ProjectReference to build against local source -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Abstractions\Microsoft.Agents.AI.Abstractions.csproj" />
+  </ItemGroup>
+
+  <!-- For end-users: uncomment the PackageReference below and remove the ProjectReference above
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.Abstractions" Version="1.0.0" />
+    <PackageReference Include="Azure.AI.AgentServer.Invocations" />
+  </ItemGroup>
+  -->
+
+</Project>

dotnet/samples/04-hosting/FoundryHostedAgents/invocations/Hosted-Invocations-EchoAgent/Program.cs

@@ -0,0 +1,28 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.AgentServer.Invocations;
+using DotNetEnv;
+using HostedInvocationsEchoAgent;
+using Microsoft.Agents.AI;
+
+// Load .env file if present (for local development)
+Env.TraversePath().Load();
+
+var builder = WebApplication.CreateBuilder(args);
+
+// Register the echo agent as a singleton (no LLM needed).
+builder.Services.AddSingleton<EchoAIAgent>();
+
+// Register the Invocations SDK services and wire the handler.
+builder.Services.AddInvocationsServer();
+builder.Services.AddScoped<InvocationHandler, EchoInvocationHandler>();
+
+var app = builder.Build();
+
+// Map the Invocations protocol endpoints:
+//   POST /invocations              — invoke the agent
+//   GET  /invocations/{id}         — get result (not used by this sample)
+//   POST /invocations/{id}/cancel  — cancel (not used by this sample)
+app.MapInvocationsServer();
+
+app.Run();

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

@@ -0,0 +1,76 @@
+# Hosted-Invocations-EchoAgent
+
+A minimal echo agent hosted as a Foundry Hosted Agent using the **Invocations protocol**. The agent reads the request body as plain text, passes it through a custom `EchoAIAgent`, and writes the echoed text back in the response. No LLM or Azure credentials are required.
+
+## Prerequisites
+
+- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
+
+## Configuration
+
+Copy the template:
+
+```bash
+cp .env.example .env
+```
+
+> **Note:** `.env` is gitignored. The `.env.example` template is checked in as a reference.
+
+## Running directly (contributors)
+
+This project uses `ProjectReference` to build against the local Agent Framework source.
+
+```bash
+cd dotnet/samples/04-hosting/FoundryHostedAgents/invocations/Hosted-Invocations-EchoAgent
+dotnet run
+```
+
+The agent will start on `http://localhost:8088`.
+
+### Test it
+
+```bash
+curl -X POST http://localhost:8088/invocations \
+  -H "Content-Type: text/plain" \
+  -d "Hello, world!"
+```
+
+Expected response:
+
+```
+Echo: Hello, world!
+```
+
+## Running with Docker
+
+Since this project uses `ProjectReference`, the standard `Dockerfile` cannot resolve dependencies outside this folder. Use `Dockerfile.contributor` which takes a pre-published output.
+
+### 1. Publish for the container runtime (Linux Alpine)
+
+```bash
+dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+```
+
+### 2. Build the Docker image
+
+```bash
+docker build -f Dockerfile.contributor -t hosted-invocations-echo-agent .
+```
+
+### 3. Run the container
+
+```bash
+docker run --rm -p 8088:8088 hosted-invocations-echo-agent
+```
+
+### 4. Test it
+
+```bash
+curl -X POST http://localhost:8088/invocations \
+  -H "Content-Type: text/plain" \
+  -d "Hello from Docker!"
+```
+
+## NuGet package users
+
+If you are consuming the Agent Framework as a NuGet package (not building from source), use the standard `Dockerfile` instead of `Dockerfile.contributor`. See the commented section in `Hosted-Invocations-EchoAgent.csproj` for the `PackageReference` alternative.

dotnet/samples/04-hosting/FoundryHostedAgents/invocations/Hosted-Invocations-EchoAgent/agent.manifest.yaml

@@ -0,0 +1,27 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/AgentManifest.yaml
+name: hosted-invocations-echo-agent
+displayName: "Hosted Invocations Echo Agent"
+
+description: >
+  A minimal echo agent hosted as a Foundry Hosted Agent using the Invocations
+  protocol. Reads the request body as plain text, echoes it back in the response.
+
+metadata:
+  tags:
+    - AI Agent Hosting
+    - Azure AI AgentServer
+    - Invocations Protocol
+    - Agent Framework
+
+template:
+  name: hosted-invocations-echo-agent
+  kind: hosted
+  protocols:
+    - protocol: invocations
+      version: 1.0.0
+  resources:
+    cpu: "0.25"
+    memory: 0.5Gi
+parameters:
+  properties: []
+resources: []

dotnet/samples/04-hosting/FoundryHostedAgents/invocations/Hosted-Invocations-EchoAgent/agent.yaml

@@ -0,0 +1,9 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml
+kind: hosted
+name: hosted-invocations-echo-agent
+protocols:
+  - protocol: invocations
+    version: 1.0.0
+resources:
+  cpu: "0.25"
+  memory: 0.5Gi

dotnet/samples/04-hosting/FoundryHostedAgents/invocations/Using-Samples/SimpleInvocationsAgent/InvocationsAIAgent.cs

@@ -0,0 +1,129 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Runtime.CompilerServices;
+using System.Text.Json;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// An <see cref="AIAgent"/> that invokes a remote agent hosted with the Invocations protocol
+/// by sending plain-text HTTP POST requests to the <c>/invocations</c> endpoint.
+/// </summary>
+public sealed class InvocationsAIAgent : AIAgent
+{
+    private readonly HttpClient _httpClient;
+    private readonly Uri _invocationsUri;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="InvocationsAIAgent"/> class.
+    /// </summary>
+    /// <param name="agentEndpoint">
+    /// The base URI of the hosted agent (e.g., <c>http://localhost:8089</c>).
+    /// The <c>/invocations</c> path is appended automatically.
+    /// </param>
+    /// <param name="httpClient">Optional <see cref="HttpClient"/> to use. If <see langword="null"/>, a new instance is created.</param>
+    /// <param name="name">Optional name for the agent.</param>
+    /// <param name="description">Optional description for the agent.</param>
+    public InvocationsAIAgent(
+        Uri agentEndpoint,
+        HttpClient? httpClient = null,
+        string? name = null,
+        string? description = null)
+    {
+        ArgumentNullException.ThrowIfNull(agentEndpoint);
+
+        this._httpClient = httpClient ?? new HttpClient();
+
+        // Ensure the base URI ends with a slash so that combining works correctly.
+        var baseUri = agentEndpoint.AbsoluteUri.EndsWith('/')
+            ? agentEndpoint
+            : new Uri(agentEndpoint.AbsoluteUri + "/");
+        this._invocationsUri = new Uri(baseUri, "invocations");
+
+        this.Name = name ?? "invocations-agent";
+        this.Description = description ?? "An agent that calls a remote Invocations protocol endpoint.";
+    }
+
+    /// <inheritdoc/>
+    public override string? Name { get; }
+
+    /// <inheritdoc/>
+    public override string? Description { get; }
+
+    /// <inheritdoc/>
+    protected override async Task<AgentResponse> RunCoreAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        var inputText = GetLastUserText(messages);
+        var responseText = await this.SendInvocationAsync(inputText, cancellationToken).ConfigureAwait(false);
+        return new AgentResponse(new ChatMessage(ChatRole.Assistant, responseText));
+    }
+
+    /// <inheritdoc/>
+    protected override async IAsyncEnumerable<AgentResponseUpdate> RunCoreStreamingAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        // The Invocations protocol returns a complete response (no SSE streaming),
+        // so we yield a single update with the full text.
+        var inputText = GetLastUserText(messages);
+        var responseText = await this.SendInvocationAsync(inputText, cancellationToken).ConfigureAwait(false);
+
+        yield return new AgentResponseUpdate
+        {
+            Role = ChatRole.Assistant,
+            Contents = [new TextContent(responseText)],
+        };
+    }
+
+    /// <inheritdoc/>
+    protected override ValueTask<AgentSession> CreateSessionCoreAsync(CancellationToken cancellationToken = default)
+        => new(new InvocationsAgentSession());
+
+    /// <inheritdoc/>
+    protected override ValueTask<JsonElement> SerializeSessionCoreAsync(
+        AgentSession session,
+        JsonSerializerOptions? jsonSerializerOptions = null,
+        CancellationToken cancellationToken = default)
+        => new(JsonSerializer.SerializeToElement(new { }, jsonSerializerOptions));
+
+    /// <inheritdoc/>
+    protected override ValueTask<AgentSession> DeserializeSessionCoreAsync(
+        JsonElement serializedState,
+        JsonSerializerOptions? jsonSerializerOptions = null,
+        CancellationToken cancellationToken = default)
+        => new(new InvocationsAgentSession());
+
+    private async Task<string> SendInvocationAsync(string input, CancellationToken cancellationToken)
+    {
+        using var content = new StringContent(input, System.Text.Encoding.UTF8, "text/plain");
+        using var response = await this._httpClient.PostAsync(this._invocationsUri, content, cancellationToken).ConfigureAwait(false);
+        response.EnsureSuccessStatusCode();
+        return await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
+    }
+
+    private static string GetLastUserText(IEnumerable<ChatMessage> messages)
+    {
+        string? lastUserText = null;
+        foreach (var message in messages)
+        {
+            if (message.Role == ChatRole.User)
+            {
+                lastUserText = message.Text;
+            }
+        }
+
+        return lastUserText ?? string.Empty;
+    }
+
+    /// <summary>
+    /// Minimal session for the invocations agent. No state is persisted.
+    /// </summary>
+    private sealed class InvocationsAgentSession : AgentSession;
+}

dotnet/samples/04-hosting/FoundryHostedAgents/invocations/Using-Samples/SimpleInvocationsAgent/Program.cs

@@ -0,0 +1,61 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using DotNetEnv;
+using Microsoft.Agents.AI;
+
+// Load .env file if present (for local development)
+Env.TraversePath().Load();
+
+Uri agentEndpoint = new(Environment.GetEnvironmentVariable("AGENT_ENDPOINT")
+    ?? "http://localhost:8088");
+
+// Create an agent that calls the remote Invocations endpoint.
+InvocationsAIAgent agent = new(agentEndpoint);
+
+// REPL
+Console.ForegroundColor = ConsoleColor.Cyan;
+Console.WriteLine($"""
+    ══════════════════════════════════════════════════════════
+    Simple Invocations Agent Sample
+    Connected to: {agentEndpoint}
+    Type a message or 'quit' to exit
+    ══════════════════════════════════════════════════════════
+    """);
+Console.ResetColor();
+Console.WriteLine();
+
+while (true)
+{
+    Console.ForegroundColor = ConsoleColor.Green;
+    Console.Write("You> ");
+    Console.ResetColor();
+
+    string? input = Console.ReadLine();
+
+    if (string.IsNullOrWhiteSpace(input)) { continue; }
+    if (input.Equals("quit", StringComparison.OrdinalIgnoreCase)) { break; }
+
+    try
+    {
+        Console.ForegroundColor = ConsoleColor.Yellow;
+        Console.Write("Agent> ");
+        Console.ResetColor();
+
+        await foreach (var update in agent.RunStreamingAsync(input))
+        {
+            Console.Write(update);
+        }
+
+        Console.WriteLine();
+    }
+    catch (Exception ex)
+    {
+        Console.ForegroundColor = ConsoleColor.Red;
+        Console.WriteLine($"Error: {ex.Message}");
+        Console.ResetColor();
+    }
+
+    Console.WriteLine();
+}
+
+Console.WriteLine("Goodbye!");

dotnet/samples/04-hosting/FoundryHostedAgents/invocations/Using-Samples/SimpleInvocationsAgent/SimpleInvocationsAgent.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <CentralPackageTransitivePinningEnabled>false</CentralPackageTransitivePinningEnabled>
+    <RootNamespace>SimpleInvocationsAgentClient</RootNamespace>
+    <AssemblyName>simple-invocations-agent-client</AssemblyName>
+    <NoWarn>$(NoWarn);NU1605</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="DotNetEnv" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\..\src\Microsoft.Agents.AI.Abstractions\Microsoft.Agents.AI.Abstractions.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/.env.example

@@ -0,0 +1,6 @@
+AZURE_AI_PROJECT_ENDPOINT=<your-azure-ai-project-endpoint>
+ASPNETCORE_URLS=http://+:8088
+ASPNETCORE_ENVIRONMENT=Development
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+AGENT_NAME=hosted-chat-client-agent
+AZURE_BEARER_TOKEN=DefaultAzureCredential

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/Dockerfile

@@ -0,0 +1,17 @@
+# Use the official .NET 10.0 ASP.NET runtime as a parent image
+FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
+WORKDIR /app
+
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /src
+COPY . .
+RUN dotnet restore
+RUN dotnet publish -c Release -o /app/publish
+
+# Final stage
+FROM base AS final
+WORKDIR /app
+COPY --from=build /app/publish .
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+ENTRYPOINT ["dotnet", "HostedChatClientAgent.dll"]

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/Dockerfile.contributor

@@ -0,0 +1,19 @@
+# Dockerfile for contributors building from the agent-framework repository source.
+#
+# This project uses ProjectReference to the local Microsoft.Agents.AI.Foundry source,
+# which means a standard multi-stage Docker build cannot resolve dependencies outside
+# this folder. Instead, pre-publish the app targeting the container runtime and copy
+# the output into the container:
+#
+#   dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+#   docker build -f Dockerfile.contributor -t hosted-chat-client-agent .
+#   docker run --rm -p 8088:8088 -e AGENT_NAME=hosted-chat-client-agent --env-file .env hosted-chat-client-agent
+#
+# For end-users consuming the NuGet package (not ProjectReference), use the standard
+# Dockerfile which performs a full dotnet restore + publish inside the container.
+FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final
+WORKDIR /app
+COPY out/ .
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+ENTRYPOINT ["dotnet", "HostedChatClientAgent.dll"]

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/HostedChatClientAgent.csproj

@@ -0,0 +1,32 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <CentralPackageTransitivePinningEnabled>false</CentralPackageTransitivePinningEnabled>
+    <RootNamespace>HostedChatClientAgent</RootNamespace>
+    <AssemblyName>HostedChatClientAgent</AssemblyName>
+    <NoWarn>$(NoWarn);</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="DotNetEnv" />
+  </ItemGroup>
+
+  <!-- For contributors: uses ProjectReference to build against local source -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry.Hosting\Microsoft.Agents.AI.Foundry.Hosting.csproj" />
+  </ItemGroup>
+
+  <!-- For end-users: uncomment the PackageReference below and remove the ProjectReference above
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.Foundry" Version="1.0.0" />
+    <PackageReference Include="Microsoft.Agents.AI.Foundry.Hosting" Version="1.0.0" />
+    <PackageReference Include="Azure.AI.Projects" />
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+  -->
+
+</Project>

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/Program.cs

@@ -0,0 +1,98 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.Projects;
+using Azure.Core;
+using Azure.Identity;
+using DotNetEnv;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry.Hosting;
+
+// Load .env file if present (for local development)
+Env.TraversePath().Load();
+
+var projectEndpoint = new Uri(Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set."));
+
+var agentName = Environment.GetEnvironmentVariable("AGENT_NAME")
+    ?? throw new InvalidOperationException("AGENT_NAME is not set.");
+
+var deployment = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";
+
+// Use a chained credential: try a temporary dev token first (for local Docker debugging),
+// then fall back to DefaultAzureCredential (for local dev via dotnet run / managed identity running in foundry).
+TokenCredential credential = new ChainedTokenCredential(
+    new DevTemporaryTokenCredential(),
+    new DefaultAzureCredential());
+
+// Create the agent via the AI project client using the Responses API.
+AIAgent agent = new AIProjectClient(projectEndpoint, credential)
+    .AsAIAgent(
+        model: deployment,
+        instructions: """
+            You are a helpful AI assistant hosted as a Foundry Hosted Agent.
+            You can help with a wide range of tasks including answering questions,
+            providing explanations, brainstorming ideas, and offering guidance.
+            Be concise, clear, and helpful in your responses.
+            """,
+        name: agentName,
+        description: "A simple general-purpose AI assistant");
+
+// Host the agent as a Foundry Hosted Agent using the Responses API.
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddFoundryResponses(agent);
+
+var app = builder.Build();
+app.MapFoundryResponses();
+
+// In Development, also map the OpenAI-compatible route that AIProjectClient uses.
+if (app.Environment.IsDevelopment())
+{
+    app.MapFoundryResponses("openai/v1");
+}
+
+app.Run();
+
+/// <summary>
+/// A <see cref="TokenCredential"/> for local Docker debugging only.
+///
+/// When debugging and testing a hosted agent in a local Docker container, Azure CLI
+/// and other interactive credentials are not available. This credential reads a
+/// pre-fetched bearer token from the <c>AZURE_BEARER_TOKEN</c> environment variable.
+///
+/// This should NOT be used in production — tokens expire (~1 hour) and cannot be refreshed.
+/// In production, the Foundry platform injects a managed identity automatically.
+///
+/// Generate a token on your host and pass it to the container:
+///   export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
+///   docker run -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN ...
+/// </summary>
+internal sealed class DevTemporaryTokenCredential : TokenCredential
+{
+    private const string EnvironmentVariable = "AZURE_BEARER_TOKEN";
+    private readonly string? _token;
+
+    public DevTemporaryTokenCredential()
+    {
+        this._token = Environment.GetEnvironmentVariable(EnvironmentVariable);
+    }
+
+    public override AccessToken GetToken(TokenRequestContext requestContext, CancellationToken cancellationToken)
+    {
+        return this.GetAccessToken();
+    }
+
+    public override ValueTask<AccessToken> GetTokenAsync(TokenRequestContext requestContext, CancellationToken cancellationToken)
+    {
+        return new ValueTask<AccessToken>(this.GetAccessToken());
+    }
+
+    private AccessToken GetAccessToken()
+    {
+        if (string.IsNullOrEmpty(this._token) || this._token == "DefaultAzureCredential")
+        {
+            throw new CredentialUnavailableException($"{EnvironmentVariable} environment variable is not set.");
+        }
+
+        return new AccessToken(this._token, DateTimeOffset.UtcNow.AddHours(1));
+    }
+}

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/README.md

@@ -0,0 +1,109 @@
+# Hosted-ChatClientAgent
+
+A simple general-purpose AI assistant hosted as a Foundry Hosted Agent using the Agent Framework instance hosting pattern. The agent is created inline via `AIProjectClient.AsAIAgent(model, instructions)` and served using the Responses protocol.
+
+## Prerequisites
+
+- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
+- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- Azure CLI logged in (`az login`)
+
+## Configuration
+
+Copy the template and fill in your project endpoint:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` and set your Azure AI Foundry project endpoint:
+
+```env
+AZURE_AI_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>
+ASPNETCORE_URLS=http://+:8088
+ASPNETCORE_ENVIRONMENT=Development
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+```
+
+> **Note:** `.env` is gitignored. The `.env.example` template is checked in as a reference.
+
+## Running directly (contributors)
+
+This project uses `ProjectReference` to build against the local Agent Framework source.
+
+```bash
+cd dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent
+dotnet run
+```
+
+The agent will start on `http://localhost:8088`.
+
+### Test it
+
+Using the Azure Developer CLI:
+
+```bash
+azd ai agent invoke --local "Hello!"
+```
+
+Or with curl (specifying the agent name explicitly):
+
+```bash
+curl -X POST http://localhost:8088/responses \
+  -H "Content-Type: application/json" \
+  -d '{"input": "Hello!", "model": "hosted-chat-client-agent"}'
+```
+
+## Running with Docker
+
+Since this project uses `ProjectReference`, the standard `Dockerfile` cannot resolve dependencies outside this folder. Use `Dockerfile.contributor` which takes a pre-published output.
+
+### 1. Publish for the container runtime (Linux Alpine)
+
+```bash
+dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+```
+
+### 2. Build the Docker image
+
+```bash
+docker build -f Dockerfile.contributor -t hosted-chat-client-agent .
+```
+
+### 3. Run the container
+
+Generate a bearer token on your host and pass it to the container:
+
+```bash
+# Generate token (expires in ~1 hour)
+export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
+
+# Run with token
+docker run --rm -p 8088:8088 \
+  -e AGENT_NAME=hosted-chat-client-agent \
+  -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN \
+  --env-file .env \
+  hosted-chat-client-agent
+```
+
+> **Note:** `AGENT_NAME` is passed via `-e` to simulate the platform injection. `AZURE_BEARER_TOKEN` provides Azure credentials to the container (tokens expire after ~1 hour). The `.env` file provides the remaining configuration.
+
+### 4. Test it
+
+Using the Azure Developer CLI:
+
+```bash
+azd ai agent invoke --local "Hello!"
+```
+
+Or with curl (specifying the agent name explicitly):
+
+```bash
+curl -X POST http://localhost:8088/responses \
+  -H "Content-Type: application/json" \
+  -d '{"input": "Hello!", "model": "hosted-chat-client-agent"}'
+```
+
+## NuGet package users
+
+If you are consuming the Agent Framework as a NuGet package (not building from source), use the standard `Dockerfile` instead of `Dockerfile.contributor` — it performs a full `dotnet restore` and `dotnet publish` inside the container. See the commented section in `HostedChatClientAgent.csproj` for the `PackageReference` alternative.

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/agent.manifest.yaml

@@ -0,0 +1,28 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/AgentManifest.yaml
+name: hosted-chat-client-agent
+displayName: "Hosted Chat Client Agent"
+
+description: >
+  A simple general-purpose AI assistant hosted as a Foundry Hosted Agent
+  using the Agent Framework instance hosting pattern.
+
+metadata:
+  tags:
+    - AI Agent Hosting
+    - Azure AI AgentServer
+    - Responses Protocol
+    - Streaming
+    - Agent Framework
+
+template:
+  name: hosted-chat-client-agent
+  kind: hosted
+  protocols:
+    - protocol: responses
+      version: 1.0.0
+  resources:
+    cpu: "0.25"
+    memory: 0.5Gi
+parameters:
+  properties: []
+resources: []

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/agent.yaml

@@ -0,0 +1,9 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml
+kind: hosted
+name: hosted-chat-client-agent
+protocols:
+  - protocol: responses
+    version: 1.0.0
+resources:
+  cpu: "0.25"
+  memory: 0.5Gi

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-FoundryAgent/.env.example

@@ -0,0 +1,5 @@
+AZURE_AI_PROJECT_ENDPOINT=<your-azure-ai-project-endpoint>
+ASPNETCORE_URLS=http://+:8088
+ASPNETCORE_ENVIRONMENT=Development
+AGENT_NAME=<your-foundry-agent-name>
+AZURE_BEARER_TOKEN=DefaultAzureCredential

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-FoundryAgent/Dockerfile

@@ -0,0 +1,17 @@
+# Use the official .NET 10.0 ASP.NET runtime as a parent image
+FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
+WORKDIR /app
+
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /src
+COPY . .
+RUN dotnet restore
+RUN dotnet publish -c Release -o /app/publish
+
+# Final stage
+FROM base AS final
+WORKDIR /app
+COPY --from=build /app/publish .
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+ENTRYPOINT ["dotnet", "HostedFoundryAgent.dll"]

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-FoundryAgent/Dockerfile.contributor

@@ -0,0 +1,19 @@
+# Dockerfile for contributors building from the agent-framework repository source.
+#
+# This project uses ProjectReference to the local Microsoft.Agents.AI.Foundry source,
+# which means a standard multi-stage Docker build cannot resolve dependencies outside
+# this folder. Instead, pre-publish the app targeting the container runtime and copy
+# the output into the container:
+#
+#   dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+#   docker build -f Dockerfile.contributor -t hosted-foundry-agent .
+#   docker run --rm -p 8088:8088 -e AGENT_NAME=<your-agent> -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN --env-file .env hosted-foundry-agent
+#
+# For end-users consuming the NuGet package (not ProjectReference), use the standard
+# Dockerfile which performs a full dotnet restore + publish inside the container.
+FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final
+WORKDIR /app
+COPY out/ .
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+ENTRYPOINT ["dotnet", "HostedFoundryAgent.dll"]

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-FoundryAgent/HostedFoundryAgent.csproj

@@ -0,0 +1,32 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <CentralPackageTransitivePinningEnabled>false</CentralPackageTransitivePinningEnabled>
+    <RootNamespace>HostedFoundryAgent</RootNamespace>
+    <AssemblyName>HostedFoundryAgent</AssemblyName>
+    <NoWarn>$(NoWarn);</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="DotNetEnv" />
+  </ItemGroup>
+
+  <!-- For contributors: uses ProjectReference to build against local source -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry.Hosting\Microsoft.Agents.AI.Foundry.Hosting.csproj" />
+  </ItemGroup>
+
+  <!-- For end-users: uncomment the PackageReference below and remove the ProjectReference above
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.Foundry" Version="1.0.0" />
+    <PackageReference Include="Microsoft.Agents.AI.Foundry.Hosting" Version="1.0.0" />
+    <PackageReference Include="Azure.AI.Projects" />
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+  -->
+
+</Project>

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-FoundryAgent/Program.cs

@@ -0,0 +1,91 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Azure.Core;
+using Azure.Identity;
+using DotNetEnv;
+using Microsoft.Agents.AI.Foundry;
+using Microsoft.Agents.AI.Foundry.Hosting;
+
+// Load .env file if present (for local development)
+Env.TraversePath().Load();
+
+var projectEndpoint = new Uri(Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set."));
+var agentName = Environment.GetEnvironmentVariable("AGENT_NAME")
+    ?? throw new InvalidOperationException("AGENT_NAME is not set.");
+
+// Use a chained credential: try a temporary dev token first (for local Docker debugging),
+// then fall back to DefaultAzureCredential (for local dev via dotnet run / managed identity running in foundry).
+TokenCredential credential = new ChainedTokenCredential(
+    new DevTemporaryTokenCredential(),
+    new DefaultAzureCredential());
+
+var aiProjectClient = new AIProjectClient(projectEndpoint, credential);
+
+// Retrieve the Foundry-managed agent by name (latest version).
+ProjectsAgentRecord agentRecord = await aiProjectClient
+    .AgentAdministrationClient.GetAgentAsync(agentName);
+
+FoundryAgent agent = aiProjectClient.AsAIAgent(agentRecord);
+
+// Host the agent as a Foundry Hosted Agent using the Responses API.
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddFoundryResponses(agent);
+
+var app = builder.Build();
+app.MapFoundryResponses();
+
+// In Development, also map the OpenAI-compatible route that AIProjectClient uses.
+if (app.Environment.IsDevelopment())
+{
+    app.MapFoundryResponses("openai/v1");
+}
+
+app.Run();
+
+/// <summary>
+/// A <see cref="TokenCredential"/> for local Docker debugging only.
+///
+/// When debugging and testing a hosted agent in a local Docker container, Azure CLI
+/// and other interactive credentials are not available. This credential reads a
+/// pre-fetched bearer token from the <c>AZURE_BEARER_TOKEN</c> environment variable.
+///
+/// This should NOT be used in production — tokens expire (~1 hour) and cannot be refreshed.
+/// In production, the Foundry platform injects a managed identity automatically.
+///
+/// Generate a token on your host and pass it to the container:
+///   export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
+///   docker run -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN ...
+/// </summary>
+internal sealed class DevTemporaryTokenCredential : TokenCredential
+{
+    private const string EnvironmentVariable = "AZURE_BEARER_TOKEN";
+    private readonly string? _token;
+
+    public DevTemporaryTokenCredential()
+    {
+        this._token = Environment.GetEnvironmentVariable(EnvironmentVariable);
+    }
+
+    public override AccessToken GetToken(TokenRequestContext requestContext, CancellationToken cancellationToken)
+    {
+        return this.GetAccessToken();
+    }
+
+    public override ValueTask<AccessToken> GetTokenAsync(TokenRequestContext requestContext, CancellationToken cancellationToken)
+    {
+        return new ValueTask<AccessToken>(this.GetAccessToken());
+    }
+
+    private AccessToken GetAccessToken()
+    {
+        if (string.IsNullOrEmpty(this._token) || this._token == "DefaultAzureCredential")
+        {
+            throw new CredentialUnavailableException($"{EnvironmentVariable} environment variable is not set.");
+        }
+
+        return new AccessToken(this._token, DateTimeOffset.UtcNow.AddHours(1));
+    }
+}

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-FoundryAgent/README.md

@@ -0,0 +1,121 @@
+# Hosted-FoundryAgent
+
+A hosted agent that delegates to a **Foundry-managed agent definition**. Instead of defining the model, instructions, and tools inline in code, this sample retrieves an existing agent registered in the Foundry platform via `AIProjectClient.AsAIAgent(agentRecord)` and hosts it using the Responses protocol.
+
+This is the **Foundry hosting** pattern — the agent's behavior is configured in the platform (via Foundry UI, CLI, or API), and this server simply wraps and serves it.
+
+## Prerequisites
+
+- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
+- An Azure AI Foundry project with a **registered agent** (created via Foundry UI, CLI, or API)
+- Azure CLI logged in (`az login`)
+
+## Configuration
+
+Copy the template and fill in your project endpoint:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` and set your Azure AI Foundry project endpoint:
+
+```env
+AZURE_AI_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>
+ASPNETCORE_URLS=http://+:8088
+ASPNETCORE_ENVIRONMENT=Development
+```
+
+> **Note:** `.env` is gitignored. The `.env.example` template is checked in as a reference.
+
+You also need to set `AGENT_NAME` — the name of the Foundry-managed agent to host. This is injected automatically by the Foundry platform when deployed. For local development, pass it as an environment variable.
+
+## Running directly (contributors)
+
+This project uses `ProjectReference` to build against the local Agent Framework source.
+
+```bash
+cd dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-FoundryAgent
+AGENT_NAME=<your-agent-name> dotnet run
+```
+
+The agent will start on `http://localhost:8088`.
+
+### Test it
+
+Using the Azure Developer CLI:
+
+```bash
+azd ai agent invoke --local "Hello!"
+```
+
+Or with curl (specifying the agent name explicitly):
+
+```bash
+curl -X POST http://localhost:8088/responses \
+  -H "Content-Type: application/json" \
+  -d '{"input": "Hello!", "model": "<your-agent-name>"}'
+```
+
+## Running with Docker
+
+Since this project uses `ProjectReference`, the standard `Dockerfile` cannot resolve dependencies outside this folder. Use `Dockerfile.contributor` which takes a pre-published output.
+
+### 1. Publish for the container runtime (Linux Alpine)
+
+```bash
+dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+```
+
+### 2. Build the Docker image
+
+```bash
+docker build -f Dockerfile.contributor -t hosted-foundry-agent .
+```
+
+### 3. Run the container
+
+Generate a bearer token on your host and pass it to the container:
+
+```bash
+# Generate token (expires in ~1 hour)
+export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
+
+# Run with token
+docker run --rm -p 8088:8088 \
+  -e AGENT_NAME=<your-agent-name> \
+  -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN \
+  --env-file .env \
+  hosted-foundry-agent
+```
+
+> **Note:** `AGENT_NAME` is passed via `-e` to simulate the platform injection. `AZURE_BEARER_TOKEN` provides Azure credentials to the container (tokens expire after ~1 hour). The `.env` file provides the remaining configuration.
+
+### 4. Test it
+
+Using the Azure Developer CLI:
+
+```bash
+azd ai agent invoke --local "Hello!"
+```
+
+Or with curl (specifying the agent name explicitly):
+
+```bash
+curl -X POST http://localhost:8088/responses \
+  -H "Content-Type: application/json" \
+  -d '{"input": "Hello!", "model": "<your-agent-name>"}'
+```
+
+## NuGet package users
+
+If you are consuming the Agent Framework as a NuGet package (not building from source), use the standard `Dockerfile` instead of `Dockerfile.contributor` — it performs a full `dotnet restore` and `dotnet publish` inside the container. See the commented section in `HostedFoundryAgent.csproj` for the `PackageReference` alternative.
+
+## How it differs from Hosted-ChatClientAgent
+
+| | Hosted-ChatClientAgent | Hosted-FoundryAgent |
+|---|---|---|
+| **Agent definition** | Inline in code (`AsAIAgent(model, instructions)`) | Managed in Foundry platform (`AsAIAgent(agentRecord)`) |
+| **Model/instructions** | Set in `Program.cs` | Set in Foundry UI/CLI/API |
+| **Tools** | Defined in code | Configured in the platform |
+| **Use case** | Full control over agent behavior | Platform-managed agent with centralized config |

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-FoundryAgent/agent.manifest.yaml

@@ -0,0 +1,28 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/AgentManifest.yaml
+name: hosted-foundry-agent
+displayName: "Hosted Foundry Agent"
+
+description: >
+  A simple general-purpose AI assistant hosted as a Foundry Hosted Agent,
+  backed by a Foundry-managed agent definition.
+
+metadata:
+  tags:
+    - AI Agent Hosting
+    - Azure AI AgentServer
+    - Responses Protocol
+    - Streaming
+    - Agent Framework
+
+template:
+  name: hosted-foundry-agent
+  kind: hosted
+  protocols:
+    - protocol: responses
+      version: 1.0.0
+  resources:
+    cpu: "0.25"
+    memory: 0.5Gi
+parameters:
+  properties: []
+resources: []

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-FoundryAgent/agent.yaml

@@ -0,0 +1,9 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml
+kind: hosted
+name: hosted-foundry-agent
+protocols:
+  - protocol: responses
+    version: 1.0.0
+resources:
+  cpu: "0.25"
+  memory: 0.5Gi

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalTools/.env.example

@@ -0,0 +1,5 @@
+AZURE_AI_PROJECT_ENDPOINT=<your-azure-ai-project-endpoint>
+ASPNETCORE_URLS=http://+:8088
+ASPNETCORE_ENVIRONMENT=Development
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+AZURE_BEARER_TOKEN=DefaultAzureCredential

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalTools/Dockerfile

@@ -0,0 +1,17 @@
+# Use the official .NET 10.0 ASP.NET runtime as a parent image
+FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
+WORKDIR /app
+
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /src
+COPY . .
+RUN dotnet restore
+RUN dotnet publish -c Release -o /app/publish
+
+# Final stage
+FROM base AS final
+WORKDIR /app
+COPY --from=build /app/publish .
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+ENTRYPOINT ["dotnet", "HostedLocalTools.dll"]

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalTools/Dockerfile.contributor

@@ -0,0 +1,19 @@
+# Dockerfile for contributors building from the agent-framework repository source.
+#
+# This project uses ProjectReference to the local Microsoft.Agents.AI.Foundry source,
+# which means a standard multi-stage Docker build cannot resolve dependencies outside
+# this folder. Instead, pre-publish the app targeting the container runtime and copy
+# the output into the container:
+#
+#   dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+#   docker build -f Dockerfile.contributor -t hosted-local-tools .
+#   docker run --rm -p 8088:8088 -e AGENT_NAME=hosted-local-tools -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN --env-file .env hosted-local-tools
+#
+# For end-users consuming the NuGet package (not ProjectReference), use the standard
+# Dockerfile which performs a full dotnet restore + publish inside the container.
+FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final
+WORKDIR /app
+COPY out/ .
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+ENTRYPOINT ["dotnet", "HostedLocalTools.dll"]

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalTools/HostedLocalTools.csproj

@@ -0,0 +1,32 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <CentralPackageTransitivePinningEnabled>false</CentralPackageTransitivePinningEnabled>
+    <RootNamespace>HostedLocalTools</RootNamespace>
+    <AssemblyName>HostedLocalTools</AssemblyName>
+    <NoWarn>$(NoWarn);</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="DotNetEnv" />
+  </ItemGroup>
+
+  <!-- For contributors: uses ProjectReference to build against local source -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry.Hosting\Microsoft.Agents.AI.Foundry.Hosting.csproj" />
+  </ItemGroup>
+
+  <!-- For end-users: uncomment the PackageReference below and remove the ProjectReference above
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.Foundry" Version="1.0.0" />
+    <PackageReference Include="Microsoft.Agents.AI.Foundry.Hosting" Version="1.0.0" />
+  </ItemGroup>
+  -->
+
+</Project>

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalTools/Program.cs

@@ -0,0 +1,164 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// Seattle Hotel Agent - A hosted agent with local C# function tools.
+// Demonstrates how to define and wire local tools that the LLM can invoke,
+// a key advantage of code-based hosted agents over prompt agents.
+
+using System.ComponentModel;
+using System.Globalization;
+using System.Text;
+using Azure.AI.Projects;
+using Azure.Core;
+using Azure.Identity;
+using DotNetEnv;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry.Hosting;
+using Microsoft.Extensions.AI;
+
+// Load .env file if present (for local development)
+Env.TraversePath().Load();
+
+string endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";
+
+// Use a chained credential: try a temporary dev token first (for local Docker debugging),
+// then fall back to DefaultAzureCredential (for local dev via dotnet run / managed identity in production).
+TokenCredential credential = new ChainedTokenCredential(
+    new DevTemporaryTokenCredential(),
+    new DefaultAzureCredential());
+
+// ── Hotel data ───────────────────────────────────────────────────────────────
+
+Hotel[] seattleHotels =
+[
+    new("Contoso Suites", 189, 4.5, "Downtown"),
+    new("Fabrikam Residences", 159, 4.2, "Pike Place Market"),
+    new("Alpine Ski House", 249, 4.7, "Seattle Center"),
+    new("Margie's Travel Lodge", 219, 4.4, "Waterfront"),
+    new("Northwind Inn", 139, 4.0, "Capitol Hill"),
+    new("Relecloud Hotel", 99, 3.8, "University District"),
+];
+
+// ── Tool: GetAvailableHotels ─────────────────────────────────────────────────
+
+[Description("Get available hotels in Seattle for the specified dates.")]
+string GetAvailableHotels(
+    [Description("Check-in date in YYYY-MM-DD format")] string checkInDate,
+    [Description("Check-out date in YYYY-MM-DD format")] string checkOutDate,
+    [Description("Maximum price per night in USD (optional, defaults to 500)")] int maxPrice = 500)
+{
+    if (!DateTime.TryParseExact(checkInDate, "yyyy-MM-dd", CultureInfo.InvariantCulture, DateTimeStyles.None, out var checkIn))
+    {
+        return "Error parsing check-in date. Please use YYYY-MM-DD format.";
+    }
+
+    if (!DateTime.TryParseExact(checkOutDate, "yyyy-MM-dd", CultureInfo.InvariantCulture, DateTimeStyles.None, out var checkOut))
+    {
+        return "Error parsing check-out date. Please use YYYY-MM-DD format.";
+    }
+
+    if (checkOut <= checkIn)
+    {
+        return "Error: Check-out date must be after check-in date.";
+    }
+
+    int nights = (checkOut - checkIn).Days;
+    List<Hotel> availableHotels = seattleHotels.Where(h => h.PricePerNight <= maxPrice).ToList();
+
+    if (availableHotels.Count == 0)
+    {
+        return $"No hotels found in Seattle within your budget of ${maxPrice}/night.";
+    }
+
+    StringBuilder result = new();
+    result.AppendLine($"Available hotels in Seattle from {checkInDate} to {checkOutDate} ({nights} nights):");
+    result.AppendLine();
+
+    foreach (Hotel hotel in availableHotels)
+    {
+        int totalCost = hotel.PricePerNight * nights;
+        result.AppendLine($"**{hotel.Name}**");
+        result.AppendLine($"   Location: {hotel.Location}");
+        result.AppendLine($"   Rating: {hotel.Rating}/5");
+        result.AppendLine($"   ${hotel.PricePerNight}/night (Total: ${totalCost})");
+        result.AppendLine();
+    }
+
+    return result.ToString();
+}
+
+// ── Create and host the agent ────────────────────────────────────────────────
+
+AIAgent agent = new AIProjectClient(new Uri(endpoint), credential)
+    .AsAIAgent(
+        model: deploymentName,
+        instructions: """
+            You are a helpful travel assistant specializing in finding hotels in Seattle, Washington.
+
+            When a user asks about hotels in Seattle:
+            1. Ask for their check-in and check-out dates if not provided
+            2. Ask about their budget preferences if not mentioned
+            3. Use the GetAvailableHotels tool to find available options
+            4. Present the results in a friendly, informative way
+            5. Offer to help with additional questions about the hotels or Seattle
+
+            Be conversational and helpful. If users ask about things outside of Seattle hotels,
+            politely let them know you specialize in Seattle hotel recommendations.
+            """,
+        name: Environment.GetEnvironmentVariable("AGENT_NAME") ?? "hosted-local-tools",
+        description: "Seattle hotel search agent with local function tools",
+        tools: [AIFunctionFactory.Create(GetAvailableHotels)]);
+
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddFoundryResponses(agent);
+
+var app = builder.Build();
+app.MapFoundryResponses();
+
+if (app.Environment.IsDevelopment())
+{
+    app.MapFoundryResponses("openai/v1");
+}
+
+app.Run();
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+internal sealed record Hotel(string Name, int PricePerNight, double Rating, string Location);
+
+/// <summary>
+/// A <see cref="TokenCredential"/> for local Docker debugging only.
+/// Reads a pre-fetched bearer token from the <c>AZURE_BEARER_TOKEN</c> environment variable
+/// once at startup. This should NOT be used in production.
+///
+/// Generate a token on your host and pass it to the container:
+///   export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
+///   docker run -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN ...
+/// </summary>
+internal sealed class DevTemporaryTokenCredential : TokenCredential
+{
+    private const string EnvironmentVariable = "AZURE_BEARER_TOKEN";
+    private readonly string? _token;
+
+    public DevTemporaryTokenCredential()
+    {
+        this._token = Environment.GetEnvironmentVariable(EnvironmentVariable);
+    }
+
+    public override AccessToken GetToken(TokenRequestContext requestContext, CancellationToken cancellationToken)
+        => this.GetAccessToken();
+
+    public override ValueTask<AccessToken> GetTokenAsync(TokenRequestContext requestContext, CancellationToken cancellationToken)
+        => new(this.GetAccessToken());
+
+    private AccessToken GetAccessToken()
+    {
+        if (string.IsNullOrEmpty(this._token) || this._token == "DefaultAzureCredential")
+        {
+            throw new CredentialUnavailableException($"{EnvironmentVariable} environment variable is not set.");
+        }
+
+        return new AccessToken(this._token, DateTimeOffset.UtcNow.AddHours(1));
+    }
+}

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalTools/README.md

@@ -0,0 +1,113 @@
+# Hosted-LocalTools
+
+A hosted agent with **local C# function tools** for hotel search. Demonstrates how to define and wire local tools that the LLM can invoke — a key advantage of code-based hosted agents over prompt agents.
+
+The agent specializes in finding hotels in Seattle, with a `GetAvailableHotels` tool that searches a mock hotel database by dates and budget.
+
+## Prerequisites
+
+- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
+- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- Azure CLI logged in (`az login`)
+
+## Configuration
+
+Copy the template and fill in your project endpoint:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` and set your Azure AI Foundry project endpoint:
+
+```env
+AZURE_AI_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>
+ASPNETCORE_URLS=http://+:8088
+ASPNETCORE_ENVIRONMENT=Development
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+```
+
+> **Note:** `.env` is gitignored. The `.env.example` template is checked in as a reference.
+
+## Running directly (contributors)
+
+This project uses `ProjectReference` to build against the local Agent Framework source.
+
+```bash
+cd dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalTools
+AGENT_NAME=hosted-local-tools dotnet run
+```
+
+The agent will start on `http://localhost:8088`.
+
+### Test it
+
+Using the Azure Developer CLI:
+
+```bash
+azd ai agent invoke --local "Find me a hotel in Seattle for Dec 20-25 under $200/night"
+```
+
+Or with curl:
+
+```bash
+curl -X POST http://localhost:8088/responses \
+  -H "Content-Type: application/json" \
+  -d '{"input": "Find me a hotel in Seattle for Dec 20-25 under $200/night", "model": "hosted-local-tools"}'
+```
+
+## Running with Docker
+
+Since this project uses `ProjectReference`, use `Dockerfile.contributor` which takes a pre-published output.
+
+### 1. Publish for the container runtime (Linux Alpine)
+
+```bash
+dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+```
+
+### 2. Build the Docker image
+
+```bash
+docker build -f Dockerfile.contributor -t hosted-local-tools .
+```
+
+### 3. Run the container
+
+Generate a bearer token on your host and pass it to the container:
+
+```bash
+# Generate token (expires in ~1 hour)
+export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
+
+# Run with token
+docker run --rm -p 8088:8088 \
+  -e AGENT_NAME=hosted-local-tools \
+  -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN \
+  --env-file .env \
+  hosted-local-tools
+```
+
+### 4. Test it
+
+Using the Azure Developer CLI:
+
+```bash
+azd ai agent invoke --local "What hotels are available in Seattle for next weekend?"
+```
+
+## How local tools work
+
+The agent has a single tool `GetAvailableHotels` defined as a C# method with `[Description]` attributes. The LLM decides when to call it based on the user's request:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `checkInDate` | string | Check-in date (YYYY-MM-DD) |
+| `checkOutDate` | string | Check-out date (YYYY-MM-DD) |
+| `maxPrice` | int | Max price per night in USD (default: 500) |
+
+The tool searches a mock database of 6 Seattle hotels and returns formatted results with name, location, rating, and pricing.
+
+## NuGet package users
+
+If you are consuming the Agent Framework as a NuGet package (not building from source), use the standard `Dockerfile` instead of `Dockerfile.contributor`. See the commented section in `HostedLocalTools.csproj` for the `PackageReference` alternative.

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalTools/agent.manifest.yaml

@@ -0,0 +1,29 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/AgentManifest.yaml
+name: hosted-local-tools
+displayName: "Seattle Hotel Agent with Local Tools"
+
+description: >
+  A travel assistant agent that helps users find hotels in Seattle.
+  Demonstrates local C# tool execution — a key advantage of code-based
+  hosted agents over prompt agents.
+
+metadata:
+  tags:
+    - AI Agent Hosting
+    - Azure AI AgentServer
+    - Responses Protocol
+    - Local Tools
+    - Agent Framework
+
+template:
+  name: hosted-local-tools
+  kind: hosted
+  protocols:
+    - protocol: responses
+      version: 1.0.0
+  resources:
+    cpu: "0.25"
+    memory: 0.5Gi
+parameters:
+  properties: []
+resources: []

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalTools/agent.yaml

@@ -0,0 +1,9 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml
+kind: hosted
+name: hosted-local-tools
+protocols:
+  - protocol: responses
+    version: 1.0.0
+resources:
+  cpu: "0.25"
+  memory: 0.5Gi

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-McpTools/.env.example

@@ -0,0 +1,5 @@
+AZURE_AI_PROJECT_ENDPOINT=<your-azure-ai-project-endpoint>
+ASPNETCORE_URLS=http://+:8088
+ASPNETCORE_ENVIRONMENT=Development
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+AZURE_BEARER_TOKEN=DefaultAzureCredential

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-McpTools/Dockerfile

@@ -0,0 +1,17 @@
+# Use the official .NET 10.0 ASP.NET runtime as a parent image
+FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
+WORKDIR /app
+
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /src
+COPY . .
+RUN dotnet restore
+RUN dotnet publish -c Release -o /app/publish
+
+# Final stage
+FROM base AS final
+WORKDIR /app
+COPY --from=build /app/publish .
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+ENTRYPOINT ["dotnet", "HostedMcpTools.dll"]

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-McpTools/Dockerfile.contributor

@@ -0,0 +1,18 @@
+# Dockerfile for contributors building from the agent-framework repository source.
+#
+# This project uses ProjectReference to the local source, which means a standard
+# multi-stage Docker build cannot resolve dependencies outside this folder.
+# Pre-publish the app targeting the container runtime and copy the output:
+#
+#   dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+#   docker build -f Dockerfile.contributor -t hosted-mcp-tools .
+#   docker run --rm -p 8088:8088 -e AGENT_NAME=mcp-tools -e GITHUB_PAT=$GITHUB_PAT -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN --env-file .env hosted-mcp-tools
+#
+# For end-users consuming the NuGet package (not ProjectReference), use the standard
+# Dockerfile which performs a full dotnet restore + publish inside the container.
+FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final
+WORKDIR /app
+COPY out/ .
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+ENTRYPOINT ["dotnet", "HostedMcpTools.dll"]

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

@@ -0,0 +1,33 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <CentralPackageTransitivePinningEnabled>false</CentralPackageTransitivePinningEnabled>
+    <RootNamespace>HostedMcpTools</RootNamespace>
+    <AssemblyName>HostedMcpTools</AssemblyName>
+    <NoWarn>$(NoWarn);</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="ModelContextProtocol" VersionOverride="1.2.0" />
+    <PackageReference Include="DotNetEnv" />
+  </ItemGroup>
+
+  <!-- For contributors: uses ProjectReference to build against local source -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry.Hosting\Microsoft.Agents.AI.Foundry.Hosting.csproj" />
+  </ItemGroup>
+
+  <!-- For end-users: uncomment the PackageReference below and remove the ProjectReference above
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.Foundry" Version="1.0.0" />
+    <PackageReference Include="Microsoft.Agents.AI.Foundry.Hosting" Version="1.0.0" />
+  </ItemGroup>
+  -->
+
+</Project>

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-McpTools/Program.cs

@@ -0,0 +1,130 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates a hosted agent with two layers of MCP (Model Context Protocol) tools:
+//
+// 1. CLIENT-SIDE MCP: The agent connects to the Microsoft Learn MCP server directly via
+//    McpClient, discovers tools, and handles tool invocations locally within the agent process.
+//
+// 2. SERVER-SIDE MCP: The agent declares a HostedMcpServerTool for the same MCP server which
+//    delegates tool discovery and invocation to the LLM provider (Azure OpenAI Responses API).
+//    The provider calls the MCP server on behalf of the agent — no local connection needed.
+//
+// Both patterns use the Microsoft Learn MCP server to illustrate the architectural difference:
+// client-side tools are resolved and invoked by the agent, while server-side tools are resolved
+// and invoked by the LLM provider.
+
+#pragma warning disable MEAI001 // HostedMcpServerTool is experimental
+
+using Azure.AI.Projects;
+using Azure.Core;
+using Azure.Identity;
+using DotNetEnv;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry.Hosting;
+using Microsoft.Extensions.AI;
+using ModelContextProtocol.Client;
+
+// Load .env file if present (for local development)
+Env.TraversePath().Load();
+
+var projectEndpoint = new Uri(Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set."));
+var deployment = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";
+
+// Use a chained credential: try a temporary dev token first (for local Docker debugging),
+// then fall back to DefaultAzureCredential (for local dev via dotnet run / managed identity in production).
+TokenCredential credential = new ChainedTokenCredential(
+    new DevTemporaryTokenCredential(),
+    new DefaultAzureCredential());
+
+// ── Client-side MCP: Microsoft Learn (local resolution) ──────────────────────
+// Connect directly to the MCP server. The agent discovers and invokes tools locally.
+Console.WriteLine("Connecting to Microsoft Learn MCP server (client-side)...");
+
+await using var learnMcp = await McpClient.CreateAsync(new HttpClientTransport(new()
+{
+    Endpoint = new Uri("https://learn.microsoft.com/api/mcp"),
+    Name = "Microsoft Learn (client)",
+}));
+
+var clientTools = await learnMcp.ListToolsAsync();
+Console.WriteLine($"Client-side MCP tools: {string.Join(", ", clientTools.Select(t => t.Name))}");
+
+// ── Server-side MCP: Microsoft Learn (provider resolution) ───────────────────
+// Declare a HostedMcpServerTool — the LLM provider (Responses API) handles tool
+// invocations directly. No local MCP connection needed for this pattern.
+AITool serverTool = new HostedMcpServerTool(
+    serverName: "microsoft_learn_hosted",
+    serverAddress: "https://learn.microsoft.com/api/mcp")
+{
+    AllowedTools = ["microsoft_docs_search"],
+    ApprovalMode = HostedMcpServerToolApprovalMode.NeverRequire
+};
+Console.WriteLine("Server-side MCP tool: microsoft_docs_search (via HostedMcpServerTool)");
+
+// ── Combine both tool types into a single agent ──────────────────────────────
+// The agent has access to tools from both MCP patterns simultaneously.
+List<AITool> allTools = [.. clientTools.Cast<AITool>(), serverTool];
+
+AIAgent agent = new AIProjectClient(projectEndpoint, credential)
+    .AsAIAgent(
+        model: deployment,
+        instructions: """
+            You are a helpful developer assistant with access to Microsoft Learn documentation.
+            Use the available tools to search and retrieve documentation.
+            Be concise and provide direct answers with relevant links.
+            """,
+        name: "mcp-tools",
+        description: "Developer assistant with dual-layer MCP tools (client-side and server-side)",
+        tools: allTools);
+
+// Host the agent as a Foundry Hosted Agent using the Responses API.
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddFoundryResponses(agent);
+
+var app = builder.Build();
+app.MapFoundryResponses();
+
+// In Development, also map the OpenAI-compatible route that AIProjectClient uses.
+if (app.Environment.IsDevelopment())
+{
+    app.MapFoundryResponses("openai/v1");
+}
+
+app.Run();
+
+/// <summary>
+/// A <see cref="TokenCredential"/> for local Docker debugging only.
+/// Reads a pre-fetched bearer token from the <c>AZURE_BEARER_TOKEN</c> environment variable
+/// once at startup. This should NOT be used in production.
+///
+/// Generate a token on your host and pass it to the container:
+///   export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
+///   docker run -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN ...
+/// </summary>
+internal sealed class DevTemporaryTokenCredential : TokenCredential
+{
+    private const string EnvironmentVariable = "AZURE_BEARER_TOKEN";
+    private readonly string? _token;
+
+    public DevTemporaryTokenCredential()
+    {
+        this._token = Environment.GetEnvironmentVariable(EnvironmentVariable);
+    }
+
+    public override AccessToken GetToken(TokenRequestContext requestContext, CancellationToken cancellationToken)
+        => this.GetAccessToken();
+
+    public override ValueTask<AccessToken> GetTokenAsync(TokenRequestContext requestContext, CancellationToken cancellationToken)
+        => new(this.GetAccessToken());
+
+    private AccessToken GetAccessToken()
+    {
+        if (string.IsNullOrEmpty(this._token) || this._token == "DefaultAzureCredential")
+        {
+            throw new CredentialUnavailableException($"{EnvironmentVariable} environment variable is not set.");
+        }
+
+        return new AccessToken(this._token, DateTimeOffset.UtcNow.AddHours(1));
+    }
+}

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-McpTools/README.md

@@ -0,0 +1,83 @@
+# Hosted-McpTools
+
+A hosted agent demonstrating **two layers of MCP (Model Context Protocol) tool integration**:
+
+1. **Client-side MCP (Microsoft Learn)** — The agent connects directly to the Microsoft Learn MCP server via `McpClient`, discovers tools, and handles tool invocations locally within the agent process.
+
+2. **Server-side MCP (Microsoft Learn)** — The agent declares a `HostedMcpServerTool` which delegates tool discovery and invocation to the LLM provider (Azure OpenAI Responses API). The provider calls the MCP server on behalf of the agent with no local connection needed.
+
+## How the two MCP patterns differ
+
+| | Client-side MCP | Server-side MCP |
+|---|---|---|
+| **Connection** | Agent connects to MCP server directly | LLM provider connects to MCP server |
+| **Tool invocation** | Handled by the agent process | Handled by the Responses API |
+| **Auth** | Agent manages credentials | Provider manages credentials |
+| **Use case** | Custom/private MCP servers, fine-grained control | Public MCP servers, simpler setup |
+| **Example** | Microsoft Learn (`McpClient` + `HttpClientTransport`) | Microsoft Learn (`HostedMcpServerTool`) |
+
+## Prerequisites
+
+- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
+- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- Azure CLI logged in (`az login`)
+
+## Configuration
+
+Copy the template and fill in your values:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env`:
+
+```env
+AZURE_AI_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+```
+
+## Running directly (contributors)
+
+```bash
+cd dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-McpTools
+dotnet run
+```
+
+### Test it
+
+Using the Azure Developer CLI:
+
+```bash
+# Uses GitHub MCP (client-side)
+azd ai agent invoke --local "Search for the agent-framework repository on GitHub"
+
+# Uses Microsoft Learn MCP (server-side)
+azd ai agent invoke --local "How do I create an Azure storage account using az cli?"
+```
+
+## Running with Docker
+
+### 1. Publish for the container runtime
+
+```bash
+dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+```
+
+### 2. Build and run
+
+```bash
+docker build -f Dockerfile.contributor -t hosted-mcp-tools .
+
+export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
+
+docker run --rm -p 8088:8088 \
+  -e AGENT_NAME=mcp-tools \
+  -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN \
+  --env-file .env \
+  hosted-mcp-tools
+```
+
+## NuGet package users
+
+Use the standard `Dockerfile` instead of `Dockerfile.contributor`. See the commented section in `HostedMcpTools.csproj` for the `PackageReference` alternative.

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-McpTools/agent.manifest.yaml

@@ -0,0 +1,30 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/AgentManifest.yaml
+name: mcp-tools
+displayName: "MCP Tools Agent"
+
+description: >
+  A developer assistant demonstrating dual-layer MCP integration:
+  client-side GitHub MCP tools handled by the agent and server-side
+  Microsoft Learn MCP tools delegated to the LLM provider.
+
+metadata:
+  tags:
+    - AI Agent Hosting
+    - Azure AI AgentServer
+    - Responses Protocol
+    - Agent Framework
+    - MCP
+    - Model Context Protocol
+
+template:
+  name: mcp-tools
+  kind: hosted
+  protocols:
+    - protocol: responses
+      version: 1.0.0
+  resources:
+    cpu: "0.25"
+    memory: 0.5Gi
+parameters:
+  properties: []
+resources: []

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-McpTools/agent.yaml

@@ -0,0 +1,9 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml
+kind: hosted
+name: mcp-tools
+protocols:
+  - protocol: responses
+    version: 1.0.0
+resources:
+  cpu: "0.25"
+  memory: 0.5Gi

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-TextRag/.env.example

@@ -0,0 +1,5 @@
+AZURE_AI_PROJECT_ENDPOINT=<your-azure-ai-project-endpoint>
+ASPNETCORE_URLS=http://+:8088
+ASPNETCORE_ENVIRONMENT=Development
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+AZURE_BEARER_TOKEN=DefaultAzureCredential

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-TextRag/Dockerfile

@@ -0,0 +1,17 @@
+# Use the official .NET 10.0 ASP.NET runtime as a parent image
+FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
+WORKDIR /app
+
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /src
+COPY . .
+RUN dotnet restore
+RUN dotnet publish -c Release -o /app/publish
+
+# Final stage
+FROM base AS final
+WORKDIR /app
+COPY --from=build /app/publish .
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+ENTRYPOINT ["dotnet", "HostedTextRag.dll"]

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-TextRag/Dockerfile.contributor

@@ -0,0 +1,19 @@
+# Dockerfile for contributors building from the agent-framework repository source.
+#
+# This project uses ProjectReference to the local Microsoft.Agents.AI.Foundry source,
+# which means a standard multi-stage Docker build cannot resolve dependencies outside
+# this folder. Instead, pre-publish the app targeting the container runtime and copy
+# the output into the container:
+#
+#   dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+#   docker build -f Dockerfile.contributor -t hosted-text-rag .
+#   docker run --rm -p 8088:8088 -e AGENT_NAME=hosted-text-rag -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN --env-file .env hosted-text-rag
+#
+# For end-users consuming the NuGet package (not ProjectReference), use the standard
+# Dockerfile which performs a full dotnet restore + publish inside the container.
+FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final
+WORKDIR /app
+COPY out/ .
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+ENTRYPOINT ["dotnet", "HostedTextRag.dll"]

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-TextRag/HostedTextRag.csproj

@@ -0,0 +1,34 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <CentralPackageTransitivePinningEnabled>false</CentralPackageTransitivePinningEnabled>
+    <RootNamespace>HostedTextRag</RootNamespace>
+    <AssemblyName>HostedTextRag</AssemblyName>
+    <NoWarn>$(NoWarn);</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="DotNetEnv" />
+  </ItemGroup>
+
+  <!-- For contributors: uses ProjectReference to build against local source -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry.Hosting\Microsoft.Agents.AI.Foundry.Hosting.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+  <!-- For end-users: uncomment the PackageReference below and remove the ProjectReferences above
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.Foundry" Version="1.0.0" />
+    <PackageReference Include="Microsoft.Agents.AI.Foundry.Hosting" Version="1.0.0" />
+    <PackageReference Include="Microsoft.Agents.AI.OpenAI" Version="1.0.0" />
+  </ItemGroup>
+  -->
+
+</Project>

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-TextRag/Program.cs

@@ -0,0 +1,130 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to use TextSearchProvider to add retrieval augmented generation (RAG)
+// capabilities to a hosted agent. The provider runs a search against an external knowledge base
+// before each model invocation and injects the results into the model context.
+
+using Azure.AI.Projects;
+using Azure.Core;
+using Azure.Identity;
+using DotNetEnv;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry.Hosting;
+using Microsoft.Extensions.AI;
+using OpenAI.Chat;
+
+// Load .env file if present (for local development)
+Env.TraversePath().Load();
+
+string endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";
+
+// Use a chained credential: try a temporary dev token first (for local Docker debugging),
+// then fall back to DefaultAzureCredential (for local dev via dotnet run / managed identity in production).
+TokenCredential credential = new ChainedTokenCredential(
+    new DevTemporaryTokenCredential(),
+    new DefaultAzureCredential());
+
+TextSearchProviderOptions textSearchOptions = new()
+{
+    SearchTime = TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke,
+    RecentMessageMemoryLimit = 6,
+};
+
+AIAgent agent = new AIProjectClient(new Uri(endpoint), credential)
+    .AsAIAgent(new ChatClientAgentOptions
+    {
+        Name = Environment.GetEnvironmentVariable("AGENT_NAME") ?? "hosted-text-rag",
+        ChatOptions = new ChatOptions
+        {
+            ModelId = deploymentName,
+            Instructions = "You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available.",
+        },
+        AIContextProviders = [new TextSearchProvider(MockSearchAsync, textSearchOptions)]
+    });
+
+// Host the agent as a Foundry Hosted Agent using the Responses API.
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddFoundryResponses(agent);
+
+var app = builder.Build();
+app.MapFoundryResponses();
+
+if (app.Environment.IsDevelopment())
+{
+    app.MapFoundryResponses("openai/v1");
+}
+
+app.Run();
+
+// ── Mock search function ─────────────────────────────────────────────────────
+// In production, replace this with a real search provider (e.g., Azure AI Search).
+
+static Task<IEnumerable<TextSearchProvider.TextSearchResult>> MockSearchAsync(string query, CancellationToken cancellationToken)
+{
+    List<TextSearchProvider.TextSearchResult> results = [];
+
+    if (query.Contains("return", StringComparison.OrdinalIgnoreCase) || query.Contains("refund", StringComparison.OrdinalIgnoreCase))
+    {
+        results.Add(new()
+        {
+            SourceName = "Contoso Outdoors Return Policy",
+            SourceLink = "https://contoso.com/policies/returns",
+            Text = "Customers may return any item within 30 days of delivery. Items should be unused and include original packaging. Refunds are issued to the original payment method within 5 business days of inspection."
+        });
+    }
+
+    if (query.Contains("shipping", StringComparison.OrdinalIgnoreCase))
+    {
+        results.Add(new()
+        {
+            SourceName = "Contoso Outdoors Shipping Guide",
+            SourceLink = "https://contoso.com/help/shipping",
+            Text = "Standard shipping is free on orders over $50 and typically arrives in 3-5 business days within the continental United States. Expedited options are available at checkout."
+        });
+    }
+
+    if (query.Contains("tent", StringComparison.OrdinalIgnoreCase) || query.Contains("fabric", StringComparison.OrdinalIgnoreCase))
+    {
+        results.Add(new()
+        {
+            SourceName = "TrailRunner Tent Care Instructions",
+            SourceLink = "https://contoso.com/manuals/trailrunner-tent",
+            Text = "Clean the tent fabric with lukewarm water and a non-detergent soap. Allow it to air dry completely before storage and avoid prolonged UV exposure to extend the lifespan of the waterproof coating."
+        });
+    }
+
+    return Task.FromResult<IEnumerable<TextSearchProvider.TextSearchResult>>(results);
+}
+
+/// <summary>
+/// A <see cref="TokenCredential"/> for local Docker debugging only.
+/// Reads a pre-fetched bearer token from the <c>AZURE_BEARER_TOKEN</c> environment variable.
+/// This should NOT be used in production — tokens expire (~1 hour) and cannot be refreshed.
+///
+/// Generate a token on your host and pass it to the container:
+///   export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
+///   docker run -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN ...
+/// </summary>
+internal sealed class DevTemporaryTokenCredential : TokenCredential
+{
+    private const string EnvironmentVariable = "AZURE_BEARER_TOKEN";
+
+    public override AccessToken GetToken(TokenRequestContext requestContext, CancellationToken cancellationToken)
+        => GetAccessToken();
+
+    public override ValueTask<AccessToken> GetTokenAsync(TokenRequestContext requestContext, CancellationToken cancellationToken)
+        => new(GetAccessToken());
+
+    private static AccessToken GetAccessToken()
+    {
+        var token = Environment.GetEnvironmentVariable(EnvironmentVariable);
+        if (string.IsNullOrEmpty(token) || token == "DefaultAzureCredential")
+        {
+            throw new CredentialUnavailableException($"{EnvironmentVariable} environment variable is not set.");
+        }
+
+        return new AccessToken(token, DateTimeOffset.UtcNow.AddHours(1));
+    }
+}

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-TextRag/README.md

@@ -0,0 +1,116 @@
+# Hosted-TextRag
+
+A hosted agent with **Retrieval Augmented Generation (RAG)** capabilities using `TextSearchProvider`. The agent grounds its answers in product documentation by running a search before each model invocation, then citing the source in its response.
+
+This sample demonstrates how to add knowledge grounding to a hosted agent without requiring an external search index — using a mock search function that can be replaced with Azure AI Search or any other provider.
+
+## Prerequisites
+
+- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
+- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- Azure CLI logged in (`az login`)
+
+## Configuration
+
+Copy the template and fill in your project endpoint:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` and set your Azure AI Foundry project endpoint:
+
+```env
+AZURE_AI_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>
+ASPNETCORE_URLS=http://+:8088
+ASPNETCORE_ENVIRONMENT=Development
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+AZURE_BEARER_TOKEN=
+```
+
+> **Note:** `.env` is gitignored. The `.env.example` template is checked in as a reference.
+
+## Running directly (contributors)
+
+This project uses `ProjectReference` to build against the local Agent Framework source.
+
+```bash
+cd dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-TextRag
+AGENT_NAME=hosted-text-rag dotnet run
+```
+
+The agent will start on `http://localhost:8088`.
+
+### Test it
+
+Using the Azure Developer CLI:
+
+```bash
+azd ai agent invoke --local "What is your return policy?"
+azd ai agent invoke --local "How long does shipping take?"
+azd ai agent invoke --local "How do I clean my tent?"
+```
+
+Or with curl:
+
+```bash
+curl -X POST http://localhost:8088/responses \
+  -H "Content-Type: application/json" \
+  -d '{"input": "What is your return policy?", "model": "hosted-text-rag"}'
+```
+
+## Running with Docker
+
+Since this project uses `ProjectReference`, use `Dockerfile.contributor` which takes a pre-published output.
+
+### 1. Publish for the container runtime (Linux Alpine)
+
+```bash
+dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+```
+
+### 2. Build the Docker image
+
+```bash
+docker build -f Dockerfile.contributor -t hosted-text-rag .
+```
+
+### 3. Run the container
+
+Generate a bearer token on your host and pass it to the container:
+
+```bash
+# Generate token (expires in ~1 hour)
+export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
+
+# Run with token
+docker run --rm -p 8088:8088 \
+  -e AGENT_NAME=hosted-text-rag \
+  -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN \
+  --env-file .env \
+  hosted-text-rag
+```
+
+### 4. Test it
+
+Using the Azure Developer CLI:
+
+```bash
+azd ai agent invoke --local "What is your return policy?"
+```
+
+## How RAG works in this sample
+
+The `TextSearchProvider` runs a mock search **before each model invocation**:
+
+| User query contains | Search result injected |
+|---|---|
+| "return" or "refund" | Contoso Outdoors Return Policy |
+| "shipping" | Contoso Outdoors Shipping Guide |
+| "tent" or "fabric" | TrailRunner Tent Care Instructions |
+
+The model receives the search results as additional context and cites the source in its response. In production, replace `MockSearchAsync` with a call to Azure AI Search or your preferred search provider.
+
+## NuGet package users
+
+If you are consuming the Agent Framework as a NuGet package (not building from source), use the standard `Dockerfile` instead of `Dockerfile.contributor`. See the commented section in `HostedTextRag.csproj` for the `PackageReference` alternative.

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-TextRag/agent.manifest.yaml

@@ -0,0 +1,30 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/AgentManifest.yaml
+name: hosted-text-rag
+displayName: "Hosted Text RAG Agent"
+
+description: >
+  A support specialist agent for Contoso Outdoors with RAG capabilities.
+  Uses TextSearchProvider to ground answers in product documentation
+  before each model invocation.
+
+metadata:
+  tags:
+    - AI Agent Hosting
+    - Azure AI AgentServer
+    - Responses Protocol
+    - RAG
+    - Text Search
+    - Agent Framework
+
+template:
+  name: hosted-text-rag
+  kind: hosted
+  protocols:
+    - protocol: responses
+      version: 1.0.0
+  resources:
+    cpu: "0.25"
+    memory: 0.5Gi
+parameters:
+  properties: []
+resources: []

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-TextRag/agent.yaml

@@ -0,0 +1,9 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml
+kind: hosted
+name: hosted-text-rag
+protocols:
+  - protocol: responses
+    version: 1.0.0
+resources:
+  cpu: "0.25"
+  memory: 0.5Gi