Use Actions tokens for Copilot test workflows

Remove Copilot PAT secrets from integration and sample validation workflows, grant Copilot request permission at the required caller and job boundaries, and preserve the environment variable expected by the tests.

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

Copilot-Session: d9fa4e9c-c32d-42fb-8ee4-4772473e6479

.github/scripts/check_team_membership.js

@@ -9,12 +9,14 @@
  * @param {object} opts.core - GitHub Actions core toolkit
  * @param {string} opts.teamSlug - Team slug to check membership against
  * @param {string|number} opts.issueNumber - Issue or pull request number to resolve author for
+ * @param {string} [opts.username] - Explicit user to check instead of the issue or pull request author
  * @returns {Promise<{author: string|null, isTeamMember: boolean}>}
  */
-async function checkTeamMembership({ github, context, core, teamSlug, issueNumber }) {
-  let author =
+async function checkTeamMembership({ github, context, core, teamSlug, issueNumber, username = '' }) {
+  let author = username.trim() || (
     context.payload.issue?.user?.login ??
-    context.payload.pull_request?.user?.login;
+    context.payload.pull_request?.user?.login
+  );
 
   if (!author) {
     const number = Number(issueNumber);

.github/tests/test_check_team_membership.js

@@ -74,6 +74,28 @@ const BASE_OPTS = { teamSlug: 'my-team', issueNumber: '123' };
 // ---------------------------------------------------------------------------
 
 describe('author resolution', () => {
+  it('uses an explicit username instead of the issue author', async () => {
+    const { github, context, core } = createMocks({
+      payloadIssue: { user: { login: 'issue-author' } },
+    });
+    let issuesGetCalled = false;
+    github.rest.issues.get = async () => {
+      issuesGetCalled = true;
+      return { data: { user: { login: 'api-user' } } };
+    };
+
+    const result = await checkTeamMembership({
+      github,
+      context,
+      core,
+      ...BASE_OPTS,
+      username: 'comment-author',
+    });
+
+    assert.equal(result.author, 'comment-author');
+    assert.equal(issuesGetCalled, false);
+  });
+
   it('resolves author from event payload', async () => {
     const { github, context, core } = createMocks({
       payloadIssue: { user: { login: 'payload-user' } },

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

@@ -6,6 +6,9 @@ on:
       - opened
       - reopened
       - ready_for_review
+  issue_comment:
+    types:
+      - created
   workflow_dispatch:
     inputs:
       pr_number:
@@ -20,7 +23,7 @@ permissions:
   pull-requests: write
 
 concurrency:
-  group: devflow-pr-review-${{ github.repository }}-${{ github.event.pull_request.number || inputs.pr_number || github.run_id }}
+  group: devflow-pr-review-${{ github.repository }}-${{ github.event.pull_request.number || github.event.issue.number || inputs.pr_number || github.run_id }}
   cancel-in-progress: true
 
 env:
@@ -28,9 +31,20 @@ env:
   DEVFLOW_REF: main
   TARGET_REPO_PATH: ${{ github.workspace }}/target-repo
   DEVFLOW_PATH: ${{ github.workspace }}/devflow
+  MODEL_CONFIG_PATH: ${{ github.workspace }}/devflow/config.ci.yaml
 
 jobs:
   team_check:
+    if: >-
+      github.event_name != 'issue_comment' ||
+      (
+        github.event.issue.pull_request &&
+        github.event.comment.body == '@devflow /review' &&
+        (
+          github.event.comment.author_association == 'MEMBER' ||
+          github.event.comment.author_association == 'OWNER'
+        )
+      )
     runs-on: ubuntu-latest
     environment: github-app-auth
     outputs:
@@ -44,6 +58,7 @@ jobs:
         shell: bash
         env:
           PR_HTML_URL: ${{ github.event.pull_request.html_url }}
+          PR_NUMBER_COMMENT: ${{ github.event.issue.number }}
           PR_NUMBER_EVENT: ${{ github.event.pull_request.number }}
           PR_NUMBER_INPUT: ${{ inputs.pr_number }}
         run: |
@@ -52,6 +67,9 @@ jobs:
           if [[ "${GITHUB_EVENT_NAME}" == "pull_request_target" ]]; then
             pr_number="${PR_NUMBER_EVENT}"
             pr_url="${PR_HTML_URL}"
+          elif [[ "${GITHUB_EVENT_NAME}" == "issue_comment" ]]; then
+            pr_number="${PR_NUMBER_COMMENT}"
+            pr_url="https://github.com/${GITHUB_REPOSITORY}/pull/${pr_number}"
           else
             pr_number="${PR_NUMBER_INPUT}"
             pr_url="https://github.com/${GITHUB_REPOSITORY}/pull/${pr_number}"
@@ -91,10 +109,11 @@ jobs:
           repository: ${{ github.repository }}
           fallback-token: ${{ secrets.GH_ACTIONS_PR_WRITE }}
 
-      - name: Check PR author team membership
+      - name: Check review requester team membership
         id: check
         uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
         env:
+          MEMBERSHIP_USER: ${{ github.event_name == 'issue_comment' && github.event.comment.user.login || '' }}
           TEAM_NAME: ${{ secrets.DEVELOPER_TEAM }}
           PR_NUMBER: ${{ steps.pr.outputs.pr_number }}
         with:
@@ -107,19 +126,33 @@ jobs:
               core,
               teamSlug: process.env.TEAM_NAME,
               issueNumber: process.env.PR_NUMBER,
+              username: process.env.MEMBERSHIP_USER,
             });
             core.setOutput('is_team_member', isTeamMember ? 'true' : 'false');
             if (isTeamMember) {
-              core.info(`Author ${author} is a team member; proceeding with review.`);
+              core.info(`User ${author} is a team member; proceeding with review.`);
             } else {
-              core.info(`Author ${author} is not a member of ${process.env.TEAM_NAME}; skipping review.`);
+              core.info(`User ${author} is not a member of ${process.env.TEAM_NAME}; skipping review.`);
             }
 
+      - name: React to authorized review command
+        if: ${{ github.event_name == 'issue_comment' && steps.check.outputs.is_team_member == 'true' }}
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
+        with:
+          github-token: ${{ steps.github-auth.outputs.token }}
+          script: |
+            await github.rest.reactions.createForIssueComment({
+              ...context.repo,
+              comment_id: context.payload.comment.id,
+              content: 'eyes',
+            });
+
   review:
     runs-on: ubuntu-latest
     needs: team_check
     if: ${{ needs.team_check.outputs.is_team_member == 'true' }}
     permissions:
+      copilot-requests: write
       contents: read
       issues: write
       pull-requests: write
@@ -169,8 +202,8 @@ jobs:
         id: review
         working-directory: ${{ env.DEVFLOW_PATH }}
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          GH_COPILOT_TOKEN: ${{ secrets.GH_COPILOT_TOKEN }}
+          DEVFLOW_TOKEN: ${{ secrets.DEVFLOW_TOKEN }}
+          GITHUB_TOKEN: ${{ github.token }}
           SK_REPO_PATH: ${{ env.TARGET_REPO_PATH }}
           AGENT_REPO_PATH: ${{ env.TARGET_REPO_PATH }}
           PR_URL: ${{ needs.team_check.outputs.pr_url }}
@@ -178,4 +211,5 @@ jobs:
           uv run python scripts/trigger_pr_review.py \
             --pr-url "$PR_URL" \
             --github-username "$GITHUB_ACTOR" \
+            --review-compare \
             --no-require-comment-selection

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

@@ -21,8 +21,6 @@ on:
         required: true
       AZUREAI__ENDPOINT:
         required: true
-      COPILOT_GITHUB_TOKEN:
-        required: true
       OPENAI__APIKEY:
         required: true
 
@@ -32,6 +30,7 @@ permissions:
 jobs:
   dotnet-integration-tests:
     permissions:
+      copilot-requests: write
       contents: read
       id-token: write
     strategy:
@@ -103,7 +102,7 @@ jobs:
         env:
           COSMOSDB_ENDPOINT: https://localhost:8081
           COSMOSDB_KEY: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
-          COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+          COPILOT_GITHUB_TOKEN: ${{ github.token }}
           OpenAI__ApiKey: ${{ secrets.OPENAI__APIKEY }}
           OpenAI__ChatModelId: ${{ vars.OPENAI__CHATMODELID }}
           OpenAI__ChatReasoningModelId: ${{ vars.OPENAI__CHATREASONINGMODELID }}

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

@@ -102,6 +102,7 @@ jobs:
     needs: resolve-ref
     if: needs.resolve-ref.outputs.dotnet-changes == 'true'
     permissions:
+      copilot-requests: write
       contents: read
       id-token: write
     uses: ./.github/workflows/dotnet-integration-tests.yml
@@ -112,7 +113,6 @@ jobs:
       AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
       AZURE_SUBSCRIPTION_ID: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
       AZUREAI__ENDPOINT: ${{ secrets.AZUREAI__ENDPOINT }}
-      COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
       OPENAI__APIKEY: ${{ secrets.OPENAI__APIKEY }}
 
   python-integration-tests:
@@ -120,6 +120,7 @@ jobs:
     needs: resolve-ref
     if: needs.resolve-ref.outputs.python-changes == 'true'
     permissions:
+      copilot-requests: write
       contents: read
       id-token: write
     uses: ./.github/workflows/python-integration-tests.yml
@@ -130,6 +131,5 @@ jobs:
       AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
       AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
       AZURE_SUBSCRIPTION_ID: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-      COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
       FOUNDRY_MODELS_API_KEY: ${{ secrets.FOUNDRY_MODELS_API_KEY }}
       OPENAI__APIKEY: ${{ secrets.OPENAI__APIKEY }}

.github/workflows/issue-triage.yml

@@ -29,6 +29,7 @@ env:
   DEVFLOW_REF: main
   TARGET_REPO_PATH: ${{ github.workspace }}/target-repo
   DEVFLOW_PATH: ${{ github.workspace }}/devflow
+  MODEL_CONFIG_PATH: ${{ github.workspace }}/devflow/config.ci.yaml
 
 jobs:
   team_check:
@@ -125,6 +126,7 @@ jobs:
       }}
     environment: integration
     permissions:
+      copilot-requests: write
       contents: read
       id-token: write
       issues: write
@@ -176,7 +178,7 @@ jobs:
         id: spam
         working-directory: ${{ env.DEVFLOW_PATH }}
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ github.token }}
           DEVFLOW_TOKEN: ${{ secrets.DEVFLOW_TOKEN }}
           SK_REPO_PATH: ${{ env.TARGET_REPO_PATH }}
           AGENT_REPO_PATH: ${{ env.TARGET_REPO_PATH }}
@@ -201,8 +203,7 @@ jobs:
         id: repro
         working-directory: ${{ env.DEVFLOW_PATH }}
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          GH_COPILOT_TOKEN: ${{ secrets.GH_COPILOT_TOKEN }}
+          GITHUB_TOKEN: ${{ github.token }}
           # Not seen by the agent prompt; used only to push a paper-trail
           # branch back to maf-dashboard at run end.
           DEVFLOW_TOKEN: ${{ secrets.DEVFLOW_TOKEN }}

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

@@ -25,8 +25,6 @@ on:
         required: true
       AZURE_SUBSCRIPTION_ID:
         required: true
-      COPILOT_GITHUB_TOKEN:
-        required: true
       FOUNDRY_MODELS_API_KEY:
         required: false
       OPENAI__APIKEY:
@@ -506,9 +504,12 @@ jobs:
     name: Python Integration Tests - GitHub Copilot
     runs-on: ubuntu-latest
     environment: integration
+    permissions:
+      copilot-requests: write
+      contents: read
     timeout-minutes: 60
     env:
-      COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+      COPILOT_GITHUB_TOKEN: ${{ github.token }}
       GITHUB_COPILOT_TIMEOUT: "120"
     defaults:
       run:

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

@@ -675,9 +675,12 @@ jobs:
        needs.paths-filter.outputs.coreChanged == 'true')
     runs-on: ubuntu-latest
     environment: integration
+    permissions:
+      copilot-requests: write
+      contents: read
     timeout-minutes: 60
     env:
-      COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+      COPILOT_GITHUB_TOKEN: ${{ github.token }}
       GITHUB_COPILOT_TIMEOUT: "120"
     defaults:
       run:

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

@@ -8,9 +8,6 @@ on:
 env:
   # Configure a constant location for the uv cache
   UV_CACHE_DIR: /tmp/.uv-cache
-  # GitHub Copilot configuration
-  GITHUB_COPILOT_MODEL: claude-opus-4.6
-  COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
 
 permissions:
   contents: read
@@ -238,6 +235,13 @@ jobs:
     name: Validate 02-agents/providers/github_copilot
     runs-on: ubuntu-latest
     environment: integration
+    permissions:
+      copilot-requests: write
+      contents: read
+      id-token: write
+    env:
+      COPILOT_GITHUB_TOKEN: ${{ github.token }}
+      GITHUB_COPILOT_MODEL: claude-opus-4.6
     defaults:
       run:
         working-directory: python

docs/decisions/0033-feature-usage-bitmask-user-agent.md

@@ -0,0 +1,642 @@
+---
+status: accepted
+contact: eavanvalkenburg
+date: 2026-07-22
+deciders: eavanvalkenburg, chetantoshniwal
+consulted: TaoChenOSU, moonbox3, peibekwe, rogerbarreto, westey-m
+informed:
+---
+
+# Feature-usage bitmask in the User-Agent
+
+## Context and Problem Statement
+
+We can see which Agent Framework packages are installed and that *some* framework
+call happened (via the existing `agent-framework-python/{version}` User-Agent),
+but we have no usage-based signal about **which features are actually exercised**
+at runtime, nor which are used *together* (e.g. workflows + MCP + Foundry). How
+can we collect a lightweight, privacy-respecting signal of feature usage for the
+traffic we can actually read, without standing up new event pipelines?
+
+The detailed mechanism is in [SPEC-004](../specs/004-feature-usage-telemetry.md);
+the per-language bit tables are in
+[feature-usage-bit-registry.md](../specs/feature-usage-bit-registry.md).
+
+## Decision Drivers
+
+- **Transparency** — openly documented, human-decodable, user-controllable. No
+  hidden or obfuscated telemetry.
+- **First-party scope / no third-party leakage** — emission requires both an
+  explicitly approved client/pipeline family and an approved actual HTTPS origin
+  on every request (including redirects). Credentials or an Azure setting alone
+  never approve a custom gateway/origin.
+- **Live signal** — read the process's observed-feature set *so far* at request
+  send time, rather than freezing it at client construction.
+- **Low cost / few moving parts** — reuse telemetry already in the request path;
+  bounded fixed-width processing; as little machinery as the job needs.
+- **Privacy** — encode only coarse "observed at least once" Boolean feature
+  state, never counts; no identifiers, arguments, prompts, payloads,
+  model/deployment names, endpoints, or customer-defined names.
+- **Use, not presence** — package-level indexes mean a capability reached its
+  first meaningful activation, not that a package was installed/imported or a
+  DI container constructed an unused service.
+- **Versioning discipline** — v1 is a point-in-time decision. Adding bits later is
+  easier than removing or redefining them, so the initial table should lean toward
+  fewer bits and avoid forcing v2 shortly after launch.
+- **Allocation discipline** — each bit represents a stable framework-owned
+  capability with a concrete product/support question and an actual-use mark
+  point; implementation detail and speculative distinctions stay out.
+
+## Considered Options
+
+The options below are grouped by the decisions that matter: the **transport**,
+the **granularity**, and the **registry sharing model**.
+
+### Transport
+
+#### A. User-Agent token, first-party only, per request (chosen)
+
+Stamp a `(feat=...)` comment onto the UA, but only on approved Azure/Foundry
+client pipelines, and re-evaluate it per request.
+
+- Good, reuses telemetry already sent to approved backends we can read.
+- Good, request-time stamping reflects the live mask (not frozen at construction).
+- Good, first-party scoping means no fingerprint leaks to third-party providers.
+- Good, two-factor destination approval (pipeline + actual origin) denies custom
+  `base_url` gateways and strips the token on unapproved redirect hops.
+- Good, maps onto .NET's existing per-request UA pipeline policies unchanged.
+- Neutral, v1 stamps only pipelines the framework creates or can configure
+  through supported public hooks. It does not mutate caller-owned clients or
+  reach into private SDK pipelines.
+- Bad, no signal for traffic that never hits a first-party endpoint (accepted —
+  we couldn't read it anyway).
+
+#### B. User-Agent token on all clients
+
+- Good, simplest to wire (one static header).
+- Bad, sends a deployment fingerprint to OpenAI/Anthropic/AWS/Google logs we
+  cannot read — privacy leak for zero benefit.
+- Bad, baked into static `default_headers`, so it freezes at client construction
+  and reports a near-empty mask.
+
+#### C. OpenTelemetry span/resource attribute
+
+- Good, precise per-call usage; no UA change.
+- Bad (**privacy — the main reason to hold it**), a span attribute broadcasts the
+  feature-combination fingerprint into the user's **general** telemetry pipeline,
+  which is typically exported to third-party APM vendors (Datadog, Honeycomb, …).
+  That re-introduces exactly the fingerprint leakage the first-party-only UA
+  scoping (A) was chosen to avoid — just into a different set of third parties.
+- Bad (secondary), also a cardinality footgun (a growing, combinatorial value
+  must never become a metric dimension).
+- Neutral, for the team's own goal it reaches us only if the user exports to
+  Azure Monitor and we query it.
+- **Deferred, not rejected.** The version prefix lets us add it later **if** the
+  User-Agent path cannot answer a concrete query and there is an acceptable
+  scoped/redacted variant.
+
+#### D. Bespoke usage events
+
+- Good, richest detail and flexibility.
+- Bad, new data flow and cost; larger privacy surface; heavy to build and review;
+  overkill for a coarse "which features" signal.
+
+#### E. Install/import-time signal only (status quo-ish)
+
+- Good, zero new runtime work.
+- Bad, measures installation, not usage; cannot capture feature combinations —
+  does not solve the problem.
+
+### Accumulation scope
+
+#### S1. Process-global, monotonic mask (chosen)
+
+A single mask per process; bits are OR-ed in as features are first used and never
+cleared. The token reflects "what this process has used so far."
+
+- **Binary interpretation:** a set bit means the feature was observed at least
+  once in this process before the request was sent. A bit repeated on later
+  requests is the same Boolean observation, not another feature use. It cannot be
+  summed into invocation, request, agent, user, or tenant counts.
+- Good, fits our **mixed feature lifecycle**: many features are *not* bound to an
+  outbound service request — an agent/workflow may first run or build, a
+  context/history provider may first participate in a session, and a host may
+  start serving before the request that later emits the token. A process-wide
+  mask can carry those activations forward.
+- Good, trivial and cheap: one OR under a lock (Python) / one atomic OR into one
+  of two 64-bit lanes (.NET); no per-request state plumbing.
+- Good, deliberately coarse for privacy: it avoids emitting a sequence of exact
+  per-call feature combinations that could reconstruct a workload's behavioral
+  trace.
+- Neutral, coarser than per-call — early requests carry fewer bits than later
+  ones, and the token says "this process used X", not "this call used X" or "X
+  was used this many times."
+
+For example, at time 1 Agent A can use MCP and a Foundry chat client. At time 2,
+Agent B in the same worker can make a normal Foundry chat call without MCP. The
+time-2 request still carries the MCP bit because MCP was previously observed in
+that process. It does **not** say Agent B used MCP, nor count a second MCP use.
+
+#### S2. Per-request set, reset between calls (botocore's model — rejected)
+
+AWS botocore scopes its `m/` feature codes to a `contextvars` set that is reset
+between requests, giving exact per-call attribution (and it deliberately no-ops
+when called outside a request context to avoid features bleeding across requests).
+See [Prior art](#prior-art).
+
+- Good, exact per-call attribution directly in the User-Agent.
+- Bad, **assumes every feature is exercised inside a single service request** —
+  true for botocore (an SDK natively bound to AWS service calls), but *not* for
+  us. Our features split into request-scoped ones (a chat call, an MCP tool
+  invocation) and decidedly non-request ones (workflow build/start, provider
+  participation, hosting startup). The latter have no service request to attach to, so a
+  per-request set would simply miss them.
+- Bad, needs `contextvars` propagation through every async/threaded path and a
+  reset discipline, plus enable/disable calls around every scoped operation; the
+  bleed-guard botocore documents is the warning sign.
+- Bad, creates a more detailed per-call behavioral trace, increasing the privacy
+  sensitivity and review burden compared with a coarse process-lifetime Boolean.
+- Note, per-call attribution for the request-scoped subset is better served by
+  the deferred OTel span path (option C) than by reshaping the UA token.
+
+### Granularity
+
+The mechanism can support several granularities. The remaining decision before
+implementation is how detailed v1 should be. The estimates below are
+intentionally rough; v1 uses a fixed 128-bit bound to leave useful headroom
+without making the registry unbounded.
+
+#### F0. Package-level bits
+
+One bit per package, set on first use of a package-owned public API, client,
+provider, or tool. It is **not** set on install, import, or assembly load.
+
+Examples that get bits:
+
+- `agent-framework-core` when `Agent`, `AgentSession`, `Workflow`, etc. is used.
+- `agent-framework-tools` when a `LocalShellTool` or `DockerShellTool` first
+  executes/probes its shell capability.
+- `agent-framework-foundry` when a `FoundryChatClient`, `FoundryAgent`, etc.
+  performs its first Foundry operation.
+- `agent-framework-openai` when `OpenAIChatClient`,
+  `OpenAIEmbeddingClient`, etc. performs its first provider operation.
+- `agent-framework-azure-ai-search` when `AzureAISearchContextProvider` is used.
+- `agent-framework-azure-cosmos` when `CosmosHistoryProvider` is used.
+- `agent-framework-redis` when `RedisContextProvider` or `RedisHistoryProvider`
+  is used.
+
+Examples that do **not** get separate bits: merely installed dependencies;
+imports or DI construction with no activation; `Agent` vs `AgentSession` vs
+`InMemoryHistoryProvider`; `FunctionTool` vs `MCPStdioTool` vs `LocalShellTool`
+vs `DockerShellTool`; `FoundryChatClient` vs `FoundryAgent`; `OpenAIChatClient`
+vs `OpenAIEmbeddingClient`.
+
+Rough estimate: Python ~25-35 bits; .NET ~15-25 bits.
+
+- Good, lowest specificity and simplest registry.
+- Good, clearly measures usage rather than dependency inventory if bits are set
+  only at package-owned public API/client/provider/tool use sites.
+- Bad, does not answer which major capability within a package is used.
+
+#### F1. Package + major capability bits
+
+Package bits plus selected major capabilities that are product-distinct and stable
+across implementations.
+
+Examples that get bits:
+
+- `agent-framework-core` plus `Agent`.
+- `AgentSession` plus `InMemoryHistoryProvider` / `FileHistoryProvider` as one
+  history capability.
+- `Workflow` / `FunctionalWorkflow` as one workflow capability.
+- `FunctionTool`; MCP transports as one MCP capability; shell tools as one shell
+  capability.
+- Skills provider plus stable source types: file, in-memory/programmatic, and
+  MCP-backed skills (with .NET inline/class skill distinctions).
+- Foundry chat/agent/embedding capabilities; OpenAI chat/embedding capabilities.
+
+Examples that do **not** get separate bits: `InMemoryHistoryProvider` vs
+`FileHistoryProvider`; `WorkflowBuilder`, `AgentExecutor`, `FunctionExecutor`, or
+`FanOutEdgeGroup`; `MCPStdioTool` vs `MCPStreamableHTTPTool` vs
+`MCPWebsocketTool`; `LocalShellTool` vs `DockerShellTool` vs
+`ShellEnvironmentProvider` vs `ShellPolicy`; `OpenAIChatClient` vs
+`OpenAIChatCompletionClient`; skill-source decorators such as caching, filtering,
+deduplication, and aggregation.
+
+Rough estimate: Python ~60-70 indexes; .NET ~45-55 indexes. The current candidate
+registry is at 63 Python / 52 .NET assigned indexes.
+
+- Good, likely answers the first product adoption questions while staying compact.
+- Good, fits comfortably within 128 bits while leaving room for additive package
+  and feature growth.
+- Neutral, some provider internals remain collapsed until a later additive bit is
+  justified.
+
+#### F2. Public construct / concrete type bits
+
+One bit per public construct that users intentionally instantiate or configure.
+
+Examples that get bits:
+
+- `Agent`, `AgentSession`, `InMemoryHistoryProvider`, `FileHistoryProvider`.
+- `Workflow`, `WorkflowBuilder`, `FunctionalWorkflow`.
+- `FunctionTool`, `MCPStdioTool`, `MCPStreamableHTTPTool`, `MCPWebsocketTool`.
+- `LocalShellTool`, `DockerShellTool`, `ShellEnvironmentProvider`, `ShellPolicy`.
+- `FoundryChatClient`, `FoundryAgent`, `OpenAIChatClient`,
+  `OpenAIChatCompletionClient`, `OpenAIEmbeddingClient`.
+
+Examples that do **not** get separate bits: `Agent.run` vs
+`Agent.run_streamed`; workflow edge/executor internals such as `AgentExecutor`,
+`FunctionExecutor`, or `FanOutEdgeGroup`; `LocalShellTool` persistent vs
+stateless mode; `ShellPolicy` allowlist vs denylist configuration; `FunctionTool`
+approval mode or result parser choices.
+
+Rough estimate: Python ~70-100 bits; .NET ~55-80 bits.
+
+- Good, concrete and directly tied to public API use.
+- Neutral, fits within 128 bits at the current estimate, but consumes much of the
+  deliberate growth reserve.
+- Bad, adds many call sites and more fingerprint specificity for v1.
+
+#### F3. Construct subtype / configuration bits
+
+Split important constructs by mode, transport, storage, or workflow primitive
+when that distinction matters.
+
+Examples that get bits:
+
+- `InMemoryHistoryProvider` and `FileHistoryProvider` separately.
+- `FunctionalWorkflow`, `WorkflowBuilder`, `AgentExecutor`, `FunctionExecutor`.
+- `FanOutEdgeGroup`, `FanInEdgeGroup`, `SwitchCaseEdgeGroup`.
+- `LocalShellTool` persistent, `LocalShellTool` stateless, `DockerShellTool`.
+- `MCPStdioTool`, `MCPStreamableHTTPTool`, `MCPWebsocketTool`;
+  `OpenAIChatClient` vs `OpenAIChatCompletionClient`.
+
+Examples that do **not** get separate bits: exact session id or persisted history
+file path; exact shell command, workdir, timeout, or output cap; exact MCP server
+command, URL, or tool names from the server; exact workflow graph shape or edge
+count; model/deployment names, prompts, tool arguments, payloads.
+
+Rough estimate: Python ~110-150 bits; .NET ~85-125 bits.
+
+- Good, useful where mode-level distinctions are decision-relevant.
+- Bad, trades simplicity for precision, increases fingerprint specificity, and
+  may exhaust or exceed 128 bits in Python.
+
+#### F4. Option / behavior flag bits
+
+The most detailed framework-owned option: bits for specific modes and behavior
+switches, still excluding customer/runtime values.
+
+Examples that get bits:
+
+- Agent streaming used vs non-streaming used.
+- `FunctionTool` `approval_mode="always_require"` vs `"never_require"`.
+- `FunctionTool` `SKIP_PARSING` / result-parser path used.
+- MCP sampling configured; MCP long-running task support used.
+- `LocalShellTool` `clean_env` / `confine_workdir`; `DockerShellTool` container
+  mode.
+
+Examples that do **not** get separate bits: function names wrapped by
+`FunctionTool`; approval rule arguments or approval decisions; MCP remote tool
+names or schemas; shell command text or policy regex patterns; prompt/message
+content, model names, URLs, tenant/user/session identifiers.
+
+Rough estimate: Python 150+ bits; .NET 120+ bits.
+
+- Good, maximum framework-owned detail.
+- Bad, exceeds or nearly exhausts 128 bits and is too detailed for v1 without a
+  concrete decision that requires it.
+
+### Registry sharing model
+
+#### H. Per-language bit lists (chosen)
+
+Each SDK owns an independent list; the decoder picks the list using the language
+already present in the UA product token.
+
+- Good, **no cross-language coordination**: each SDK numbers and evolves its
+  features independently; adding a Python feature never touches .NET numbering.
+- Good, no null placeholders for one-SDK features, no "same bit, same meaning"
+  rule, no SDK-aware decode caveats.
+- Good, decoding is trivial: language (from UA) + version -> list -> AND.
+- Neutral, two small lists to maintain instead of one (but they were going to
+  diverge anyway — the packages differ).
+
+#### I. Single shared cross-language registry
+
+- Good, one list, one number space.
+- Bad, forces synchronized numbering and null placeholders for features that
+  exist in only one SDK, plus SDK-aware decode rules.
+- Bad, the synchronization is pure accidental complexity — **the language is
+  already in the User-Agent**, so sharing the number space buys nothing.
+
+### Registry maintenance
+
+#### J. Package-local indexes + parity/no-overlap test (chosen)
+
+- Good, each package owns private `FeatureIndex` declarations only for its own
+  rows; adding an optional-provider index does not require a core release after
+  the marker API exists.
+- Good, one repository test compares the package-local declarations with the
+  per-language table and rejects missing rows, wrong ids, out-of-range indexes,
+  and any duplicate/overlapping index.
+- Good, no build step, no generator to own.
+
+#### K. Code-generate the enums from the registry
+
+- Bad, a generator + drift test + schema test to maintain a short list of
+  integer constants; likely justified only if v1 deliberately chooses the most
+  detailed L3/L4 granularities.
+
+### Representation (how the mask is rendered as text)
+
+All examples below encode the same mask — bits 0, 2, 32, 48, 56 set
+(agent + workflow + sequential-orchestration + foundry.chat_client + openai, in
+the Python v1 list) = decimal `72339073309605893`.
+
+#### L. Decimal — `feat=v1.72339073309605893`
+
+- Good, human-familiar; trivial to parse.
+- Neutral, no visual alignment to four-bit groups; slightly longer than hex for
+  large masks. No advantage over hex.
+
+#### M. Hex (chosen) — `feat=v1.101000100000005`
+
+- Good, compact (≤32 chars for a 128-bit mask).
+- Good, decodes with one stdlib call in every language (`int(x, 16)` /
+  two 64-bit lane parses in .NET); each hex character corresponds to four
+  consecutive bit positions.
+- Good, lowercase, no `0x` prefix, no leading zeros — unambiguous and stable.
+
+A grouped variant such as `feat=v1.101.0001.0000.0005` was also considered.
+Separators make the value longer and must be removed before `int(x, 16)` can
+parse it, while the ordinary hex digits already preserve fixed four-bit groups.
+
+#### N. Binary — `feat=v1.100000001000000000000000100000000000000000000000000000101`
+
+- Good, directly shows every zero/one position.
+- Bad, grows to 128 payload characters and is difficult to scan reliably.
+
+#### O. Bit-list — `feat=v1.0,2,32,48,56`
+
+- Good, most directly human-readable ("which bits").
+- Bad, needs delimiter handling and grows with the number of set bits; a full
+  128-bit list is substantially larger than every fixed-width representation.
+
+#### P. Alphabet / base-N (e.g. Crockford base32 `feat=v1.208004000005`, base62 `feat=v1.5LJRx1i6xJ`)
+
+- Good, shortest representation.
+- Bad, needs a custom alphabet + decode table on both ends; base62 is
+  case-sensitive (fragile through case-normalizing intermediaries); not
+  directly readable. Premature optimization for a value that is already ≤32
+  chars in hex.
+
+All forms are ASCII. The table shows total bytes added to the existing
+User-Agent, including the leading space and `(feat=v1.)` wrapper:
+
+| Representation | Example (5 bits) | All current Python rows (63) | All current .NET rows (52) | Full 128-bit v1 |
+| --- | ---: | ---: | ---: | ---: |
+| Hex | 26 | 34 | 30 | 43 |
+| Grouped hex | 29 | 39 | 34 | 50 |
+| Decimal | 28 | 38 | 34 | 50 |
+| Binary | 68 | 100 | 86 | 139 |
+| Bit-list | 23 | 189 | 156 | 412 |
+| Crockford base32 | 23 | 29 | 26 | 37 |
+| Base62 | 21 | 26 | 24 | 33 |
+
+There is no defensible average before rollout, and the design does not depend on
+one: a process-global mask may eventually contain every assigned row. There is
+no smaller per-request bit budget because the bits are not request-scoped; the
+registry allocation tenet controls how many distinctions v1 assigns. Client
+processing is bounded by the fixed 128-bit width: marking performs one
+lock/atomic OR, and request-time stamping reads the mask, formats at most 32 hex
+characters, and replaces one User-Agent comment. It performs no registry scan,
+network call, or per-feature enable/disable bookkeeping.
+
+## Decision Outcome
+
+Chosen: **a request-time-stamped, first-party-only User-Agent `(feat=...)` token (A),
+with a 128-bit process-global monotonic accumulator (S1), per-language bit lists
+(H), package-local index enums kept honest by parity and no-overlap tests (J),
+rendered as lowercase hex (M).**
+
+This is a bounded design with enough v1 headroom. A 128-bit
+**process-global, monotonic** mask accumulates from universal
+`mark_feature_used()` calls (so it spans build/start/participation activations
+that aren't bound to any service request — the per-request set model (S2) can't);
+the token is **stamped per request** only when both the client/pipeline and the
+actual HTTPS origin are approved, so custom origins and cross-origin redirects
+cannot inherit the fingerprint; each
+SDK owns an independent bit list selected by the language already in the UA; the
+mask is rendered as hex (`feat=v1.101000100000005`). The dedicated
+`AGENT_FRAMEWORK_FEATURE_MASK_DISABLED` opt-out drops only the mask while
+keeping the base SDK identity/version User-Agent. Python's existing
+`AGENT_FRAMEWORK_USER_AGENT_DISABLED` continues to suppress its entire
+contribution, including the mask; this decision does not introduce a matching
+whole-User-Agent switch in .NET. OTel (C) is deferred — mainly because a
+broadly-emitted span attribute would leak the fingerprint into the user's
+general telemetry, against the first-party-only stance and would require
+user-side OTel setup that may still not make the data available to us — but left
+open behind the version prefix. Per-request scoping (S2), a shared registry (I),
+codegen for the initial registry (K), and the decimal/grouped-hex/binary/bit-list/
+base-N representations (L, M variant, N, O, P) are rejected as complexity or
+length the problem does not require.
+
+The remaining choice before implementation is the **v1 granularity level** among
+F0-F4. This is a point-in-time decision: adding new bits later is easier than
+removing or redefining them, because removals/redefinitions require a new
+registry version and historical decode tables. For v1, prefer the least detailed
+level that answers the known product/support questions so we do not force a v2
+shortly after launch. The refreshed candidate registry uses **63 Python indexes and
+52 .NET indexes**, leaving 65 and 76 positions respectively. That headroom supports
+normal growth; it does not waive the registry's
+[allocation tenet](../specs/feature-usage-bit-registry.md#allocation-tenet).
+
+### Consequences
+
+- Good, adds a bounded-cost usage signal with no new data flow and few moving
+  parts.
+- Good, transparent (public registry, human-decodable token) and disabled by a
+  dedicated `AGENT_FRAMEWORK_FEATURE_MASK_DISABLED` mask-only opt-out. Python's
+  existing whole-User-Agent opt-out also suppresses the mask.
+- Good, first-party-only + request-time stamping gives a live mask and no
+  third-party fingerprint leak.
+- Good, 128 bits leaves useful v1 headroom; .NET remains lock-free by storing two
+  independently atomic 64-bit lanes; per-language lists remove all cross-language
+  sync; package-local enums avoid both codegen and provider→core release coupling.
+- Neutral, the token's reach equals eligible framework-configured first-party
+  traffic; broader per-call signal (OTel) can be added later if needed.
+- Neutral, every set bit is a repeated Boolean observation after first use;
+  request rows carrying it are not feature invocation counts.
+- Neutral, v1 granularity is intentionally a separate choice; the registry should
+  start with fewer bits unless a more detailed bit answers a concrete question.
+- Bad, each feature must add an activation mark, first-party clients need a
+  per-request destination-aware hook, and the registry validator must scan all
+  package-local index declarations.
+
+## Prior art
+
+SDK telemetry-in-the-User-Agent is well-established; this design is closest to
+AWS's, and conventional in the rest. Summary of what comparable SDKs do:
+
+| SDK | What's in the UA / headers | Usage-based? | Opt-out | Closest to ours? |
+| --- | --- | --- | --- | --- |
+| **AWS botocore** | structured UA with an `m/` token: a per-request set of **short feature codes** for features actually exercised (`WAITER`→`B`, `PAGINATOR`→`C`, retry mode, checksums, credential source, …) | **Yes** — registered at call time via `register_feature_id`, contextvar-scoped per request | `AWS_SDK_UA_APP_ID` sets app id (no opt-out for `m/`) | **Yes — direct analog** |
+| **OpenAI / Anthropic** (Stainless) | sidecar `X-Stainless-*` headers: lang, package version, OS, arch, runtime, runtime version; plus per-request `x-stainless-retry-count`, `x-stainless-read-timeout` | Mostly static identity (retry/timeout are per-request) | none | No (static identity) |
+| **Azure SDK** (`azure-core`) | `User-Agent: azsdk-python-{pkg}/{ver} Python/{pyver} ({platform})` | No | `AZURE_TELEMETRY_DISABLED` (tracing spans only, **not** the UA) | No |
+| **Google API core** | `x-goog-api-client: gl-python/… grpc/… gax/… gapic/…` | No | none | No |
+| **LangSmith** | `User-Agent: langsmith-py/{ver}`; usage lives in trace payloads | No (header) | opt-in via `LANGSMITH_TRACING_V2`/`LANGCHAIN_TRACING_V2`; `…HIDE_INPUTS/OUTPUTS` | No |
+
+Takeaways that shaped (or validate) our choices:
+
+- **AWS `m/` is the precedent for usage-based feature flags in a first-party
+  User-Agent.** It validates the core idea. Its key *difference* is the encoding:
+  AWS uses a **comma-separated set of 1–2 char short codes** (open-ended, no bit
+  coordination, but variable length), whereas we use a fixed-width **hex
+  bitmask** (compact, bounded, decode-by-AND, but needs per-language bit
+  allocation). We keep the bitmask for boundedness and trivial AND-decoding;
+  AWS's short-code set is recorded as a viable alternative if bit-position
+  coordination ever becomes painful (it would also drop the fixed 128-bit bound).
+- **A fixed-width bitmask gives bounded token size for free.** botocore must cap
+  the `m/` component at 1024 bytes and truncate at delimiter boundaries (with a
+  fallback log) precisely *because* its short-code set is unbounded. Our 128-bit
+  hex is ≤32 chars by construction — no size cap, no truncation logic.
+- **Scope is where we diverge most — and deliberately.** botocore collects
+  features into a per-request `contextvars` set that is **reset between
+  requests**, and no-ops outside a request context to prevent cross-request
+  bleed. That works because every botocore feature is exercised *inside* an AWS
+  service request. We are more general: some features are request-scoped (a chat
+  call, an MCP tool invocation) but many are **not bound to any request**
+  (workflow build/start, provider participation, hosting startup). So we use a
+  **process-global, monotonic** mask (option S1), which is the only scope that can
+  represent the non-request features. Our mask therefore intentionally "bleeds"
+  (accumulates) for the life of the process — the opposite of botocore's reset —
+  and that is the intended semantic, not the bug botocore guards against.
+- **The mechanism is private; the wire format is the contract.** botocore marks
+  its whole user-agent module private and "subject to abrupt breaking changes."
+  Same for us: the Python/.NET helpers are internal, and only the emitted token +
+  the per-language registry tables are the stable, decodable contract.
+- **First-party-only emission** is stricter than any of the above; the closest in
+  spirit is Stainless headers, which only reach the owning API. We make the
+  client/pipeline allowlist explicit (initially Foundry/Azure OpenAI) rather than
+  attempting to infer safety from arbitrary request URLs. Other Azure clients
+  join only after telemetry access is confirmed.
+- **Opt-out naming.** `AZURE_TELEMETRY_DISABLED` is the family precedent for our
+  `AGENT_FRAMEWORK_*_DISABLED` names. Separately, the cross-tool `DO_NOT_TRACK`
+  convention (honored by e.g. HuggingFace Hub) is worth considering — see Open
+  Questions.
+
+Sources: botocore [`useragent.py`](https://github.com/boto/botocore/blob/develop/botocore/useragent.py)
+(`_USERAGENT_FEATURE_MAPPINGS`, `register_feature_id`, `_build_feature_metadata`);
+openai-python [`_base_client.py` `platform_headers()`](https://github.com/openai/openai-python/blob/main/src/openai/_base_client.py);
+anthropic-sdk-python [`_base_client.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/_base_client.py);
+azure-core [`_universal.py` `UserAgentPolicy`](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/azure/core/pipeline/policies/_universal.py);
+google-api-core [`client_info.py`](https://github.com/googleapis/python-api-core/blob/main/google/api_core/client_info.py);
+langsmith-sdk [`client.py`](https://github.com/langchain-ai/langsmith-sdk/blob/main/python/langsmith/client.py) /
+[`utils.py`](https://github.com/langchain-ai/langsmith-sdk/blob/main/python/langsmith/utils.py);
+huggingface_hub [`constants.py`](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/constants.py).
+
+## Registry versioning and migration (v1 → v2)
+
+The token carries a **per-language** version (`feat=v1.<hex>`); a version bump is
+independent for Python and .NET.
+
+- **Additive growth stays on v1 — no bump.** Allocating a new feature to a
+  reserved/unused bit is backward-compatible: an older decoder simply sees an
+  unknown bit and ignores it. Normal package growth never needs a new
+  version.
+- **A bump (v2) is required only for breaking changes:** renumbering or
+  re-partitioning existing bits, changing the *meaning* of an already-assigned
+  index, or widening beyond 128-bit. Within a version an index is **never** reused or
+  reassigned — that invariant is what lets old decoders stay correct.
+- **The draft 64→128 change is still v1.** No v1 token or enum has shipped, so
+  this pre-implementation repartition establishes the initial contract rather
+  than migrating an existing one.
+- **Mixed-version coexistence is the norm.** A fleet runs many SDK releases at
+  once, so `v1` and `v2` tokens appear simultaneously for a long time (old SDKs
+  keep emitting `v1`). The decoder keeps **every** published `(language,
+  version)` table and selects by the token's version; the `v1` table is retained
+  indefinitely for historical decode.
+- **Unknown version → do not guess.** A decoder without the `vN` table must
+  record "unknown registry version" rather than decode against an older table —
+  bit meanings may differ across versions, so mis-attribution is worse than
+  no data.
+- **Producing v2:** publish the v2 table alongside v1, update the affected
+  package-local `FeatureIndex` declarations and SDK version constant, and emit
+  `v2` from the release that ships them. Prefer staying on v1 (additive) and
+  reserving a clean v2 for an eventual deliberate re-partition.
+
+## Limitations
+
+| Limitation | Caused by (choice) | Why we accepted it |
+| --- | --- | --- |
+| **No signal for self-hosted or third-party-only traffic.** If a process never calls Azure/Foundry, we see nothing. | First-party-only emission (A) | We can't read third-party logs anyway, and must not leak a fingerprint into them. Reach traded for privacy. |
+| **Not every first-party client is stampable.** Caller-supplied `AIProjectClient` / OpenAI clients and toolkit-owned clients may not expose a supported per-request policy hook. | Supported-hook-only emission (A) | V1 does not mutate caller-owned clients or private SDK pipelines. Those features may still appear on another eligible request from the same process-global mask. |
+| **Custom origins intentionally receive no feature token.** A customer gateway may use Azure credentials or Azure-named settings but route to a non-approved origin. | Two-factor destination classification (A) | Credentials and configuration names are not proof of telemetry ownership. Unknown/custom origins and cross-origin redirects are denied by default. |
+| **No OTel / per-call signal in v1.** | OTel deferred (C) — primarily on **privacy** and availability grounds | A broadly-emitted span attribute would push the fingerprint into the user's general telemetry / third-party APM vendors, undoing the first-party-only scoping. It also requires customer/user OTel setup, and even Foundry users may not export data where we can query it. Left open only if there is a compelling reason to add. |
+| **Mask reflects "usage so far," not the whole session.** Early requests carry fewer bits than later ones. | Process-global accumulator + request-time stamping | Honest and still useful as a Boolean process-lifetime observation. Repeated request rows must not be summed as additional uses. Reading the mask at request time makes it *grow* rather than freeze. |
+| **No per-agent / per-call attribution.** The mask is one process-wide value — "this process used X", not "this agent/call used X". | Process-global monotonic scope (S1) | A deliberate choice, not a transport limit: botocore *does* per-call attribution in the UA via a per-request `contextvars` set, but many AF activations (workflow build/start, provider participation, hosting startup) occur outside the service request that later emits the token. Per-call detail remains deferred to OTel. |
+| **Shared processes intentionally carry usage across agents and tenants.** A request can include bits first set by another workload in the same worker. | Process-global monotonic scope (S1) | The token must be interpreted only as process-level "used so far," never as request/user/tenant attribution. Privacy review must explicitly accept this. |
+| **Bits are binary, sticky observations — not countable events.** Once set, a bit appears on every later eligible request from that process, so raw request counts repeat the same observation and long-lived/high-traffic processes dominate. | Monotonic mask stamped at request time | The signal supports coarse observed-feature and co-occurrence questions only. It cannot provide first-use counts, unique-process counts, request attribution, or feature invocation frequency. |
+| **Granularity may be too coarse or too detailed.** The chosen level may miss useful distinctions or create more specificity than needed. | v1 granularity choice (F0-F4) | This is the main remaining decision. Adding bits later is easier than removing/redefining them, so v1 should lean toward fewer bits that answer known questions. |
+| **.NET snapshots span two atomic lanes.** A bit can be marked between the low/high reads, so one request may omit that just-added bit. | 128-bit width without a global lock | The mask is monotonic: the snapshot cannot invent or clear a bit, and the next request includes the addition. This matches the existing "usage so far" timing semantics. |
+| **Fingerprinting risk is reduced, not eliminated.** A feature-combination mask is still a deployment signature, and it transits intermediaries (proxies/CDNs) even when first-party-scoped. | Emitting any feature-combination value | Scope + opt-out + coarse granularity mitigate it; v1 should avoid unnecessary detailed bits. |
+
+## Open Questions (for decider discussion)
+
+These are unresolved and should be decided before implementation:
+
+1. **Which v1 granularity level (F0-F4)?** This is the primary remaining choice.
+   Adding bits later is easier than removing or redefining bits, so v1 should
+   choose the least detailed level that answers known questions and avoids a quick
+   v2.
+2. **Privacy approval for the v1 User-Agent signal.** Before implementation,
+   confirm that a transparent, opt-out, first-party-only feature-combination
+   fingerprint is acceptable, including the exact client allowlist, retention,
+   access, and permitted product queries. This is a rollout precondition.
+3. **When (if ever) to add the OTel path?** Held back mainly for **privacy** and
+   data availability: a span attribute broadcasts the fingerprint into the user's
+   general telemetry and onward to third-party APM vendors, contradicting the
+   first-party-only stance, and it requires user-side OTel setup that may not make
+   the data available to us even for Foundry users. It also carries a
+   metric-cardinality hazard. Revisit only if the User-Agent path cannot answer a
+   concrete question.
+4. **Honor the cross-tool `DO_NOT_TRACK` convention?** Several ecosystems treat
+   `DO_NOT_TRACK=1` as a universal telemetry opt-out (HuggingFace Hub honors it;
+   see [Prior art](#prior-art)). Should our mask opt-out also respect
+   `DO_NOT_TRACK` (in addition to `AGENT_FRAMEWORK_FEATURE_MASK_DISABLED` and
+   Python's pre-existing whole-UA flag)? Cheap to add and
+   community-friendly, but it widens the opt-out surface and needs a clear
+   precedence rule. Recommend yes; confirm with the deciders.
+
+### Decided
+
+- **Dedicated opt-out flag — included.** In addition to the existing
+  Python `AGENT_FRAMEWORK_USER_AGENT_DISABLED` (drops the whole UA), v1 ships
+  `AGENT_FRAMEWORK_FEATURE_MASK_DISABLED`, which drops **only** the feature mask
+  while keeping the base SDK identity/version User-Agent. This lets a
+  privacy-conscious user withhold the usage signal without losing the
+  support/compat value of the SDK-version header. .NET adopts the dedicated
+  mask-only flag; adding a .NET whole-User-Agent switch is outside this decision.
+- **Caller-owned clients are not modified.** V1 stamps only framework-created
+  clients or clients with a supported public policy/hook registration point. It
+  does not patch private pipelines; injected clients are an explicit coverage
+  limitation.
+- **Destination approval is explicit and redirect-aware.** An eligible pipeline
+  still emits only to a reviewed HTTPS origin. Custom origins are default-deny,
+  and the token is removed on an unapproved redirect hop.
+- **Telemetry does not replace transport defaults.** Framework-created OpenAI
+  clients use the SDK's default async HTTP client with the request hook added,
+  preserving redirect, timeout, connection-limit, and pooling behavior.
+- **Marking uses activation, not DI construction.** Operational surfaces mark on
+  first real use; a constructor marks only when construction itself exercises or
+  registers the capability.
+
+## More Information
+
+- Mechanism & API: [SPEC-004](../specs/004-feature-usage-telemetry.md)
+- Per-language bit tables, encoding, opt-out, governance: [feature-usage-bit-registry.md](../specs/feature-usage-bit-registry.md)
+- Existing accumulator pattern: `python/packages/core/agent_framework/_telemetry.py`
+- .NET emission policies: `dotnet/src/Microsoft.Agents.AI.Foundry/AgentFrameworkUserAgentPolicy.cs`,
+  `dotnet/src/Microsoft.Agents.AI.Foundry.Hosting/HostedAgentUserAgentPolicy.cs`

docs/specs/004-feature-usage-telemetry.md

@@ -0,0 +1,500 @@
+---
+status: proposed
+contact: eavanvalkenburg
+date: 2026-07-22
+deciders: eavanvalkenburg
+consulted:
+informed:
+---
+
+# Feature-usage telemetry via an accumulating bitmask
+
+> Companion design for [ADR-0033](../decisions/0033-feature-usage-bitmask-user-agent.md).
+> The per-language bit tables, encoding, opt-out, and governance live in
+> [feature-usage-bit-registry.md](feature-usage-bit-registry.md). The registry
+> allocates indexes; package-local `FeatureIndex` declarations implement them.
+
+## What is the goal of this feature?
+
+Give the Agent Framework team a lightweight signal about **which framework
+features are actually exercised** at runtime (not merely installed), so we can
+prioritise investment based on real usage. We emit a single small number — a
+*feature mask* — on the User-Agent that already goes out with each request.
+
+**Reach is deliberately bounded.** The mask accumulates from *all* feature usage,
+but the `feat=` token is only stamped through an explicit allowlist of
+**first-party Azure/Foundry client pipelines** whose User-Agent telemetry the
+team can ingest (initially Foundry/Azure OpenAI). We do **not** send the token to
+third-party providers (OpenAI direct, Anthropic, Bedrock, Gemini, Ollama,
+Mistral), or to an Azure service merely because its hostname is first-party;
+doing so would leak a deployment fingerprint into logs we cannot read (see
+[Emission](#emission)).
+
+The current candidate uses package-level bits plus selected major capabilities:
+one bit per orchestration pattern (sequential / concurrent / group-chat /
+magentic / handoff), **one bit per built-in context/history provider**, selected
+skill source types, and separate Foundry chat/agent/memory/evals/toolbox bits
+(plus embedding in Python).
+See the
+[registry](feature-usage-bit-registry.md). ADR-0033 still leaves final v1
+granularity open. The refreshed candidate assigns 63 Python indexes and 52 .NET
+indexes. V1 uses 128 bits, leaving 65 Python and 76 .NET positions for additive
+growth.
+
+Success metric: within one release after rollout, ≥80% of **eligible,
+framework-created** first-party (Foundry) requests carry a **non-empty** feature
+token whose mask reflects features activated **after** client construction (i.e.
+the token is live, not frozen — see the request-time stamping requirement
+below). This measures transport coverage, not feature invocation volume.
+Secondary: ability to describe which process-lifetime feature bits are observed
+together in eligible traffic (e.g. "requests observed from processes that have
+used workflows"). Repeated requests carrying a bit are not additional uses.
+
+This is done **transparently**: the bit registry is public, the emitted value is
+human-decodable, and a dedicated `AGENT_FRAMEWORK_FEATURE_MASK_DISABLED`
+disables the mask while preserving the base User-Agent. Python's existing
+`AGENT_FRAMEWORK_USER_AGENT_DISABLED` continues to suppress its entire
+User-Agent contribution, mask included.
+
+## What is the problem being solved?
+
+Today we only know which packages are *installed* (from package telemetry) or
+that *some* Agent Framework call happened (the existing
+`agent-framework-python/{version}` User-Agent). We have no usage-based signal
+about feature combinations, and no way to tell that, say, a process uses
+workflows + MCP + Foundry together. Collecting this through bespoke events would
+add cost and new data flows; folding a tiny accumulating integer into telemetry
+we already send is far cheaper and easier to reason about for privacy.
+
+## Mechanism
+
+### Process-global accumulator in `core`
+
+The accumulator and its helpers live in the existing
+`agent_framework/_telemetry.py` (alongside `get_user_agent()` /
+`prepend_agent_framework_to_user_agent()`), so the User-Agent machinery stays in
+one module. It owns a process-global 128-bit accumulator. Python's arbitrary-size
+`int` stores it directly. A **dedicated**
+`AGENT_FRAMEWORK_FEATURE_MASK_DISABLED` that drops **only** the feature mask
+while keeping the base `agent-framework-python/{version}` User-Agent is
+introduced by this design. The existing Python
+`AGENT_FRAMEWORK_USER_AGENT_DISABLED` continues to drop the whole User-Agent
+contribution, mask included:
+
+```python
+# agent_framework/_telemetry.py (same module as get_user_agent)
+# IS_TELEMETRY_ENABLED already defined here (AGENT_FRAMEWORK_USER_AGENT_DISABLED)
+
+FEATURE_MASK_DISABLED_ENV_VAR = "AGENT_FRAMEWORK_FEATURE_MASK_DISABLED"
+REGISTRY_VERSION = 1
+
+_feature_mask = 0
+_feature_mask_lock = threading.Lock()
+
+
+def _feature_mask_enabled() -> bool:
+    """Mask is on unless the UA is disabled or the dedicated flag is set."""
+    if not IS_TELEMETRY_ENABLED:
+        return False
+    return os.environ.get(FEATURE_MASK_DISABLED_ENV_VAR, "false").lower() not in ("true", "1")
+
+
+def mark_feature_used(index: int) -> None:
+    """OR a feature bit into the process-global mask.
+
+    Called the first time a feature is exercised. Cheap and idempotent;
+    a no-op when the feature mask is disabled.
+    """
+    global _feature_mask
+    if not _feature_mask_enabled():
+        return
+    if not 0 <= index < 128:
+        raise ValueError(f"Feature index must be in range 0..127, got {index}")
+    with _feature_mask_lock:
+        _feature_mask |= 1 << index
+
+
+def get_feature_token() -> str | None:
+    """Return ``v<version>.<hex_mask>`` for the accumulated mask, or None."""
+    if not _feature_mask_enabled() or _feature_mask == 0:
+        return None
+    return f"v{REGISTRY_VERSION}.{_feature_mask:x}"
+```
+
+- **Per package/feature, usage-based:** `mark_feature_used()` is called at the
+  feature's first meaningful activation, never at import/install time. For
+  operational clients, tools, providers, and hosts, activation is the first
+  public operation that exercises the capability. Construction is a valid mark
+  point only when construction itself performs the capability (for example,
+  registering/starting runtime resources), not merely because a DI container
+  instantiated an otherwise-unused object.
+- **Process-global and monotonic — intentionally never reset.** Unlike a
+  per-request scheme (e.g. botocore's `contextvars` feature set that resets
+  between calls), our mask spans the whole process because many features are not
+  bound to any service request — an agent or workflow may first run, a provider
+  may first participate in a session, and a host may start serving independently
+  of the later request that emits the token. The single global
+  mask is the only scope that can represent them, and its monotonic "usage so
+  far" growth is the intended semantic, not a bleed bug. Concurrency-safe via the
+  module lock (Python) / two atomic 64-bit lanes in .NET.
+- **Binary and non-countable.** A set bit means "this feature was observed at
+  least once in this process before this request." Repeating that bit on every
+  later eligible request does not represent additional uses and must not be
+  interpreted as request, invocation, agent, user, or tenant counts.
+- **No scoped enable/disable bookkeeping.** Making the mask exact per operation
+  would add hot-path state changes, context propagation, and reset/error-path
+  handling. It would also produce a more detailed behavioral trace and therefore
+  increase privacy sensitivity. V1 deliberately keeps the coarser process-level
+  Boolean.
+- **Token is safe by construction.** The emitted value is `v{int}.{hex}` —
+  characters limited to `[0-9a-fv.]` — so no header-injection sanitization is
+  required. A 128-bit mask is at most 32 hex characters (contrast botocore,
+  which must sanitize and cap arbitrary component strings).
+- **Private API.** `mark_feature_used`, `get_feature_token`, `apply_feature_token`
+  and the mask itself are internal helpers; only the emitted token and the
+  per-language registry tables are the stable, decodable contract.
+- **No import cycles:** the accumulator lives in core, while each package owns
+  private index constants for its own features and calls the core marker. Core
+  never imports optional packages.
+
+### Interpretation contract
+
+At time 1, Agent A in a worker can use MCP and a Foundry chat client. At time 2,
+Agent B in the same worker can make a normal Foundry chat call without MCP. The
+time-2 request still carries the MCP bit because MCP was observed earlier in the
+process.
+
+That request means only "this process has used MCP." It does not mean Agent B
+used MCP, that MCP was used on the time-2 request, or that two requests carrying
+the bit equal two MCP uses. Without a separate stable process identifier, the
+signal also cannot produce unique-process counts. Supported analysis is limited
+to coarse observed-feature prevalence and feature co-occurrence, with the
+request-weighting limitation called out explicitly.
+
+### Bit constants
+
+The registry is the allocation authority. Each package defines a private,
+hand-written `FeatureIndex` IntEnum (or equivalent constants) containing only
+the rows it owns. Core owns core indexes plus the accumulator; optional packages
+can allocate and ship new indexes without requiring a core release after the
+marker API exists.
+
+```python
+# agent_framework_foundry/_feature_usage.py
+from enum import IntEnum
+
+from agent_framework._telemetry import mark_feature_used  # pyright: ignore[reportAttributeAccessIssue]
+
+
+class FeatureIndex(IntEnum):
+    FOUNDRY_CHAT_CLIENT = 48
+
+
+class RawFoundryChatClient:
+    async def _send_request(self) -> None:
+        mark_feature_used(FeatureIndex.FOUNDRY_CHAT_CLIENT)
+        ...
+```
+
+A repository validation test reads every package-local declaration and the
+matching language/version table. It fails when an index is out of range, missing
+from the registry, duplicated/overlapping across packages, or mapped to the wrong
+id. For reference, in v1 `FoundryChatClient` → index 48,
+`FoundryAgent` → index 49, Foundry memory → index 50.
+
+### Usage activation points
+
+- **Clients/embeddings/evals:** first outbound operation.
+- **Tools/MCP:** first connection, discovery, or invocation that exercises the
+  tool surface.
+- **Context/history providers:** first provider hook or load/save operation, not
+  constructor-only registration.
+- **Agents/workflows/orchestrations:** first run/build/start operation that
+  activates the defined runtime.
+- **Hosting:** first serve/start/route activation.
+- **Constructor marking:** allowed only when construction itself performs one of
+  those activations or acquires/registers the runtime resource.
+
+## Emission
+
+**One path in v1: the User-Agent `feat=` token, stamped at request time on an
+explicit allowlist of first-party Azure/Foundry client pipelines only.**
+
+Marking (`mark_feature_used`) is **universal** — every feature sets its index
+regardless of provider. Only **emission** is scoped. A user who never calls a
+first-party endpoint emits no token; this is the honest, intended behaviour (no
+third-party leakage, no signal we couldn't read anyway).
+
+The existing base User-Agent behavior (`agent-framework-python/{version}` plus
+any dynamically detected hosting prefix) is unchanged; packages continue using
+their current `default_headers`, `user_agent`, suffix, or policy mechanisms.
+`get_user_agent()` stays base-only (no `feat=`). The `feat=` token is
+**separate**, added **only** by eligible Azure/Foundry clients, and
+**re-evaluated on each request** so it reflects the mask accumulated so far. A
+helper stamps it:
+
+This request-time read does not make the signal request-scoped. The payload
+remains the process-global Boolean history described above.
+
+```python
+# agent_framework/_telemetry.py
+def apply_feature_token(user_agent: str) -> str:
+    """Append/refresh the live ``(feat=v<ver>.<hex>)`` comment on a UA string.
+
+    Re-reads the current mask on every call, so newly accumulated bits are
+    reflected immediately. Idempotent: replaces an existing ``(feat=...)``
+    comment rather than appending a second.
+    """
+    token = get_feature_token()  # None when disabled or mask == 0
+    base = _strip_feature_comment(user_agent)
+    return f"{base} (feat={token})" if token else base
+```
+
+Emission requires **both**:
+
+1. an explicitly approved framework client/pipeline family; and
+2. the actual request's normalized HTTPS origin matching that family's reviewed
+   first-party origin allowlist.
+
+Credentials, `use_azure`, or an Azure-named setting alone do not approve a
+destination. Approval depends on the **resolved origin**: customer-specific
+subdomains on reviewed Azure/Foundry suffixes remain eligible even when supplied
+through `base_url` / `AZURE_OPENAI_BASE_URL`, while customer gateways and unknown
+OpenAI-compatible origins are denied by default. The check runs on every actual
+request, including redirect hops; a cross-origin or otherwise unapproved redirect
+removes `(feat=...)` before sending.
+
+Eligible first-party clients install a **request hook** that performs this
+classification and calls `apply_feature_token()`:
+
+- **OpenAI-SDK clients created by Agent Framework**: construct the underlying
+  client with
+  `http_client=DefaultAsyncHttpxClient(event_hooks={"request": [_stamp_feat_hook]})`.
+  Using OpenAI's `DefaultAsyncHttpxClient` preserves the SDK's redirect,
+  connection-limit, and timeout defaults; a plain `httpx.AsyncClient` must not
+  replace them. The hook adds or removes the token based on the approved pipeline
+  plus actual-origin classification. Caller-supplied clients/transports are not
+  replaced or patched.
+- **azure-core pipeline clients**: start with `AIProjectClient` paths whose
+  telemetry is confirmed ingestible. When Agent Framework constructs/configures
+  an approved pipeline, add a separate per-call `SansIOHTTPPolicy` whose
+  `on_request` performs the same actual-origin check and calls
+  `apply_feature_token()` on
+  `request.http_request.headers["User-Agent"]`. Do not stamp `SearchClient`,
+  `CosmosClient`, or another Azure client merely because it is first-party; add
+  it to the allowlist only after confirming the data path. This mirrors .NET's
+  request-time `PipelinePolicy` exactly.
+
+This fixes the frozen-at-construction problem: the token is materialised at
+**send time**, not client-init time, so it carries features activated after the
+client was created. It also confines the token to first-party endpoints. Caller-owned
+clients are not patched, and toolkit-owned clients without a supported public
+hook are outside v1 coverage.
+
+Encoding uses the RFC 7231 **comment** form `(feat=v1.<hex>)` (metadata, not a
+product token), placed after the agent-framework product token, e.g.:
+
+```text
+foundry-hosting/agent-framework-python/1.2.3 (feat=v1.2a)
+```
+
+### OpenTelemetry — not in v1
+
+An OTel span attribute carrying the same value was considered but **deferred —
+primarily for privacy, not complexity**. Unlike the first-party-only UA token, a
+span attribute broadcasts the feature-combination fingerprint into the user's
+**general** telemetry pipeline, which is commonly exported to third-party APM
+vendors (Datadog, Honeycomb, …) — re-introducing exactly the leakage the
+first-party scoping was chosen to avoid. (It also carries a cardinality footgun:
+a monotonically-growing, combinatorial value must never become a metric
+dimension.) The version prefix leaves the door open to add it later **if** the
+User-Agent path cannot answer a concrete query and there is an acceptable
+scoped/redacted variant; v1 ships the UA path only. See
+[ADR-0033 → option C](../decisions/0033-feature-usage-bitmask-user-agent.md#considered-options).
+
+## API Changes
+
+New **internal cross-package** surface in
+`agent_framework._telemetry` (not exported from `agent_framework`):
+
+- `mark_feature_used(index: int) -> None`
+- `get_feature_token() -> str | None` — returns `v<ver>.<hex>` or `None`.
+- `apply_feature_token(user_agent: str) -> str` — live, idempotent UA stamper
+  used by first-party request hooks.
+- `FEATURE_MASK_DISABLED_ENV_VAR` constant — the dedicated mask-only opt-out env
+  var name (`AGENT_FRAMEWORK_FEATURE_MASK_DISABLED`).
+
+Each package also adds a private package-local `FeatureIndex` declaration for
+the rows it owns. The dedicated mask-only opt-out and Python's existing
+whole-User-Agent opt-out gate the Python mask; see [Opt-out](#opt-out).
+
+Behavioural change to existing API:
+
+- `get_user_agent()` / `prepend_agent_framework_to_user_agent()` are
+  **unchanged** — they keep returning the base UA with no `feat=` token. The
+  token is added only by first-party request hooks via
+  `apply_feature_token()`.
+
+No breaking changes: when the mask is empty or disabled, for any non-first-party
+client, or for an injected client outside the supported-hook set, output is
+byte-for-byte identical to today.
+
+## Opt-out
+
+The dedicated mask-only opt-out is shared by both SDKs. Python also retains its
+pre-existing whole-User-Agent opt-out:
+
+| Env var | SDKs | Effect |
+| --- | --- | --- |
+| `AGENT_FRAMEWORK_FEATURE_MASK_DISABLED` | Python and .NET | disables **only** the feature mask; the base `agent-framework-<lang>/{version}` User-Agent is still sent |
+| `AGENT_FRAMEWORK_USER_AGENT_DISABLED` | Python (existing behavior) | disables the **entire** Python AF User-Agent contribution, mask included |
+
+The flags accept `true`/`1` (case-insensitive). The dedicated flag lets a
+privacy-conscious user keep contributing the SDK identity/version (useful for
+support and compat triage) while withholding the feature-usage signal. The mask
+is also disabled implicitly whenever Python's whole User-Agent is disabled. A
+new whole-User-Agent opt-out for .NET is outside this design.
+
+## E2E example
+
+```python
+from agent_framework import Agent
+from agent_framework_foundry import FoundryChatClient
+from agent_framework_openai import OpenAIChatClient
+
+# First-party (Foundry) client: request hook stamps the live feat token.
+agent = Agent(client=FoundryChatClient(...), instructions="...")
+# Agent use marks bit 0; FoundryChatClient marks bit 48
+await agent.run("Hello")
+# Outgoing request to Foundry carries:
+#   User-Agent: agent-framework-python/1.2.3 (feat=v1.<mask-at-send-time>)
+
+# Third-party client: NO feat token is added (no first-party hook).
+other = Agent(client=OpenAIChatClient(...), instructions="...")
+await other.run("Hi")
+# Outgoing request to OpenAI carries only:
+#   User-Agent: agent-framework-python/1.2.3
+```
+
+Drop only the feature mask (keep the base User-Agent):
+
+```bash
+AGENT_FRAMEWORK_FEATURE_MASK_DISABLED=true python app.py
+# Foundry request User-Agent: agent-framework-python/1.2.3   (no (feat=...) comment)
+```
+
+Python only: use the existing flag to drop its entire User-Agent contribution
+(mask included):
+
+```bash
+AGENT_FRAMEWORK_USER_AGENT_DISABLED=true python app.py
+```
+
+## .NET mapping
+
+- Core owns `FeatureUsage.MarkUsed(int index)` plus the core package's private
+  index declaration. Each optional assembly owns a private `FeatureIndex` enum
+  containing only its allocated rows. These are index positions `0..127`, not
+  `[Flags]` values; `MarkUsed` performs the shift.
+- Store the 128-bit mask as **two `long` lanes** (`low` for bits 0–63, `high`
+  for 64–127). Marking touches one lane with `Interlocked.Or` where available
+  and a small `Interlocked.CompareExchange` loop on `netstandard2.0` / `net472`.
+  Read each lane atomically. Since bits only move from zero to one, a concurrent
+  two-lane snapshot may miss a just-added bit but can never invent or clear one;
+  the next request includes it.
+- Format without depending on `UInt128`: if `high == 0`, emit `low` as lowercase
+  hex; otherwise emit `high` without leading zeros followed by `low:x16`. Cast
+  each signed lane to `ulong` before formatting so bits 63 and 127 are preserved.
+  Reject indexes outside `0..127`.
+- **Emission is stamped at request time and first-party-scoped**, matching
+  Python. The
+  existing `AgentFrameworkUserAgentPolicy` / `HostedAgentUserAgentPolicy`
+  pipeline policies already run per request — extend them to apply the same
+  approved-pipeline + actual-origin classifier, append/refresh the `(feat=...)`
+  comment only for approved destinations, and remove it on unapproved redirect
+  hops. Do not register it on third-party `IChatClient`s.
+- Same **wire format** (`v<version>.<hex>` comment, hex encoding) and the same
+  dedicated mask-only opt-out (`AGENT_FRAMEWORK_FEATURE_MASK_DISABLED`). The
+  **mask is decoded per language**: indexes are not shared, so a decoder must
+  read the language from the UA product token and select that language's table
+  before decoding. (.NET's policy was already request-time, so there is no
+  Python/.NET timing asymmetry.) Adding a .NET whole-User-Agent opt-out is
+  outside this design.
+
+## Keeping the bitmap in sync
+
+[feature-usage-bit-registry.md](feature-usage-bit-registry.md) is the published
+allocation contract. Package-local `FeatureIndex` declarations are the runtime
+implementation. There is deliberately **no shared numbering across languages**
+and **no machine-readable registry file**.
+
+One repository validation test gathers every package-local declaration for one
+language/version and parses the matching Markdown table. It asserts:
+
+1. every declared index is within `0..127`;
+2. every `(index, id)` exactly matches one registry row;
+3. the union of declarations has no duplicate/overlapping indexes;
+4. every non-reserved registry row is declared exactly once.
+
+Adding an optional-package feature therefore changes that package and the
+registry, not core. If a programmatic decoder is built later, export the table
+to JSON then.
+
+### Decoding
+
+```
+UA: agent-framework-python/1.2.3 (feat=v1.2a)
+        │                          │   └ hex mask
+        │                          └ version
+        └ language → pick the Python table (version 1)
+```
+
+Read language → pick the table; read `vN` → pick that version; `AND` the hex mask
+against each bit. Unknown bits (from a newer SDK than the decoder's copy of the
+table) are ignored.
+
+## Implementation plan (post-approval)
+
+1. **Privacy approval** — confirm the first-party-only feature-combination
+   signal, retention, access, allowed queries, and opt-out behavior before code
+   ships.
+2. **Core accumulator** — in `agent_framework/_telemetry.py` add the 128-bit
+   mask, lock, `mark_feature_used(index)`, `get_feature_token`, and
+   `apply_feature_token`; `get_user_agent()` stays base-only.
+3. **Package-local indexes + validation** — add private `FeatureIndex`
+   declarations to packages and a repository test for exact registry parity,
+   complete coverage, range, and zero overlap.
+4. **First-party request-time hooks** — use OpenAI's
+   `DefaultAsyncHttpxClient` for framework-created clients and the separate
+   azure-core `SansIOHTTPPolicy`. Require approved pipeline **and** approved
+   actual origin on every request/redirect hop. Verify custom origins and
+   cross-origin redirects never carry the token.
+5. **Mark feature usage** — call `mark_feature_used(FeatureIndex.X)` at the
+   first meaningful activation. Operational clients/providers/tools mark on
+   their first real operation; build/start points mark compositional features.
+   Constructor-only marking requires construction itself to exercise the
+   capability.
+6. **.NET parity** — package-local index enums plus the two atomic 64-bit lanes
+   with `Interlocked.Or` / compare-exchange fallback; extend existing request-time
+   Foundry UA policies through the shared destination classifier and formatter.
+7. **Docs & tests** — update package `AGENTS.md`/skills; tests for **both**
+   Python opt-out paths (dedicated mask-only and existing whole-UA), the
+   dedicated .NET mask-only opt-out, first-party scoping, and the live
+   (non-frozen) UA.
+
+## Limitations & open questions
+
+The decision-level limitations and unresolved trade-offs — reach, per-process
+(not per-call) attribution, v1 granularity, fingerprinting residue, and the OTel
+question — are owned by the ADR (the dedicated mask-only opt-out is now decided
+and included). See
+**[ADR-0033 → Limitations](../decisions/0033-feature-usage-bitmask-user-agent.md#limitations)**
+and **[Open Questions](../decisions/0033-feature-usage-bitmask-user-agent.md#open-questions-for-decider-discussion)**.
+This spec is the implementation reference; it does not re-litigate those choices.
+
+Implementation-only note:
+
+- **Per-request hook overhead is negligible** (a flag check, one Python integer
+  snapshot or two atomic .NET lane reads, and a string concat per first-party
+  request), but benchmark the hot path once if a high-QPS Foundry scenario is in
+  scope.

docs/specs/004-python-function-calling-loop.md

@@ -0,0 +1,543 @@
+---
+status: proposed
+contact: eavanvalkenburg
+date: 2026-07-27
+deciders: eavanvalkenburg
+---
+
+# Python function-calling loop contract and validation matrix
+
+## Scope
+
+This specification defines the required behavior and validation coverage for the Python function-calling loop.
+It covers:
+
+- normal local function execution;
+- streaming and non-streaming response aggregation;
+- tool approval request and resume;
+- approved, rejected, mixed, and replayed approval rounds;
+- reasoning content and opaque reasoning signatures bound to function calls;
+- history persistence and service-side continuation;
+- error, user-input, middleware-termination, and loop-limit paths;
+- provider and transport serialization of function calls and results.
+
+The primary implementation is in `python/packages/core/agent_framework/_tools.py`. History replay behavior in
+`python/packages/core/agent_framework/_sessions.py`, provider serializers, hosting packages, and UI transports are
+part of the same contract when they carry function-call loop content.
+
+## Change sensitivity
+
+This code is high risk. Small changes can produce duplicate side effects, orphaned calls or results, invalid
+provider histories, invisible streaming results, stale approval authority, or loops that never terminate.
+Dropping reasoning content that a service binds to a tool call can also make an otherwise balanced call/result
+transcript invalid.
+
+Any change to the function-calling loop or its approval/history/serialization paths must:
+
+1. identify every affected row in the scenario matrix below;
+2. add or update the corresponding regression tests;
+3. validate streaming updates, streaming finalization, and non-streaming output where applicable;
+4. validate both model-bound history and caller-visible responses;
+5. run the full core package tests plus every affected provider or transport package;
+6. run source typing, test typing, and syntax checks for every affected package;
+7. receive extra review focused on call/result pairing, exactly-once execution, and history replay.
+
+A passing narrow regression test is not sufficient evidence for changes in this area.
+
+### Contribution ownership
+
+Issues involving this code must not be picked up by external contributors without first checking with the Agent
+Framework core team. The core team must confirm the intended behavior, affected scenario-matrix rows, ownership
+across core/providers/transports, and the required validation scope before implementation starts.
+
+## Flow diagrams and code map
+
+### Main function-calling flow
+
+The main control flow deliberately has separate streaming and non-streaming methods. They share policy helpers, but
+their output mechanics differ: one returns an aggregated `ChatResponse`; the other yields `ChatResponseUpdate`
+items and is finalized by `ResponseStream`.
+
+The diagrams use only the generic distinction between **local tools**, which Agent Framework executes, and
+**hosted-service tools**, whose calls and approval decisions are owned by a remote service. Provider-specific wire
+formats and regression tests appear later in the scenario matrix.
+
+```mermaid
+flowchart TD
+    Entry["FunctionInvocationLayer.get_response(...)"]
+    Setup["Prepare middleware, options, session, budget state,<br/>and execute_function_calls partial"]
+    Enabled{"Function invocation enabled?"}
+    Direct["Delegate directly to super().get_response(...)"]
+    Mode{"stream?"}
+    NonStream["_get_response_with_function_invocation(...)"]
+    Stream["_stream_response_with_function_invocation(...)"]
+    Resolve["_resolve_approval_responses(...)<br/>runs once before the model-iteration loop"]
+    ApprovalAction{"approval action"}
+    Immediate["Return/yield terminal result or user-input request<br/>without another model call"]
+    ApprovalPolicy["Record approval executions;<br/>apply stop/function-call-limit policy"]
+    Model["Call super_get_response(...)<br/>response may contain reasoning + function_call"]
+    Process["_process_model_function_calls(...)"]
+    FunctionAction{"function-processing action"}
+    Execute["_execute_function_calls(...)"]
+    Try["_try_execute_function_calls(...)"]
+    Single["_execute_single_function_call(...)"]
+    Handle["_handle_function_call_results(...)"]
+    PostCallPolicy["Record executions; apply error/function-call-limit policy;<br/>reset required tool choice"]
+    Advance["_prepare_messages_for_next_iteration(...)"]
+    More{"iteration budget remains?"}
+    Final["Final model call with tool_choice = none<br/>and deterministic fallback if needed"]
+    Output["Return ChatResponse or complete ResponseStream"]
+
+    Entry --> Setup --> Enabled
+    Enabled -- no --> Direct
+    Enabled -- yes --> Mode
+    Mode -- no --> NonStream
+    Mode -- yes --> Stream
+    NonStream --> Resolve
+    Stream --> Resolve
+    Resolve --> ApprovalAction
+    ApprovalAction -- return --> Immediate --> Output
+    ApprovalAction -- stop --> ApprovalPolicy
+    ApprovalAction -- continue --> ApprovalPolicy
+    ApprovalPolicy --> More
+    Model --> Process
+    Process --> Execute --> Try --> Single --> Handle --> FunctionAction
+    FunctionAction -- return --> Output
+    FunctionAction -- stop --> PostCallPolicy
+    FunctionAction -- continue --> PostCallPolicy
+    PostCallPolicy --> Advance
+    Advance --> More
+    More -- yes --> Model
+    More -- no --> Final --> Output
+```
+
+Code-reading landmarks:
+
+- `get_response(...)` owns setup and selects the response mode.
+- `_get_response_with_function_invocation(...)` owns non-streaming aggregation.
+- `_stream_response_with_function_invocation(...)` owns streamed emission/finalization.
+- `_resolve_approval_responses(...)` handles only inbound approval decisions.
+- `_process_model_function_calls(...)` handles only calls from a completed model response.
+- `_try_execute_function_calls(...)` decides approval/declaration/execution behavior for a batch.
+- `_replace_approval_contents_with_results(...)` is the occurrence-aware approval transcript normalizer.
+
+### Approval pause and resume
+
+```mermaid
+sequenceDiagram
+    participant Caller
+    participant History as HistoryProvider
+    participant Layer as FunctionInvocationLayer
+    participant Tool
+    participant Model
+
+    Caller->>Layer: Initial user request
+    Layer->>Model: Messages + tools
+    Model-->>Layer: reasoning content + function_call
+    Layer->>Layer: Tool requires approval
+    Layer-->>Caller: function_call + function_approval_request
+
+    Caller->>Layer: function_approval_response
+    Layer->>Layer: Copy caller-owned messages
+    Layer->>Layer: _resolve_approval_responses(...)
+
+    alt approved
+        Layer->>Tool: Execute exactly once
+        Tool-->>Layer: result or exception
+        Layer->>Layer: Create terminal function_result
+    else rejected
+        Layer->>Layer: Create synthetic rejection function_result
+    end
+
+    Layer-->>Caller: Terminal result message/update
+
+    alt tool requests more user input
+        Layer-->>Caller: User-input request with assistant role
+    else middleware terminates
+        Layer-->>Caller: Termination result
+    else error limit reached
+        Layer->>Model: Normalized reasoning/call/result history, tools disabled
+        Model-->>Layer: Final assistant response
+        Layer-->>Caller: Final assistant response
+    else continue normally
+        Layer->>Model: Normalized reasoning/call/result history
+        Model-->>Layer: Final assistant response or another function_call
+        Layer-->>Caller: Final assistant response / continued loop
+    end
+
+    Layer-->>History: Persist caller input + returned response
+    Note over History: Later model replay filters approval request/response wrappers
+```
+
+The terminal result is caller-visible in both modes. The private normalized message copy is model-visible. The
+original caller input and earlier response remain unchanged.
+
+### Reasoning-bound function-call groups
+
+Some hosted services bind reasoning content or an opaque reasoning signature to the function call that follows it.
+For those services, reasoning is not optional decoration; it is part of the provider-valid function-call group.
+
+```mermaid
+flowchart TD
+    Response["Assistant response:<br/>reasoning content + function_call"]
+    Group["One logical reasoning/function-call group"]
+    Owner{"local or hosted-service tool?"}
+    Local["Local execution"]
+    Hosted["Hosted service owns tool execution/state"]
+    Result["Terminal function_result or hosted result"]
+    Continuation{"continuation mode"}
+    Stateless["Stateless or framework-history replay"]
+    Replayable{"reasoning payload/signature<br/>is replayable?"}
+    Replay["Replay reasoning + call + result atomically"]
+    Reject["Fail before the service call;<br/>do not send a lossy transcript"]
+    Service["Hosted-service continuation"]
+    Reference["Reference service-stored reasoning/call;<br/>send only the new result or approval decision"]
+    Compact{"compaction needed?"}
+    Atomic["Keep or exclude the complete<br/>reasoning/call/result group"]
+    Caller["Caller-visible response retains reasoning<br/>with the function-call turn"]
+
+    Response --> Group --> Owner
+    Group --> Caller
+    Owner -- local --> Local --> Result
+    Owner -- hosted service --> Hosted --> Result
+    Result --> Compact
+    Compact -- yes --> Atomic --> Continuation
+    Compact -- no --> Continuation
+    Continuation -- stateless / local history --> Stateless --> Replayable
+    Replayable -- yes --> Replay
+    Replayable -- no --> Reject
+    Continuation -- service-managed --> Service --> Reference
+```
+
+The generic contract is:
+
+- reasoning content remains ordered immediately before or alongside the function call it explains;
+- a terminal result does not replace or discard the reasoning/call portion of the active group;
+- stateless replay includes the service-required reasoning payload or opaque signature;
+- if required reasoning cannot be reconstructed, the adapter fails before sending invalid or lossy history;
+- service-managed continuation may rely on the hosted service's stored reasoning/call items and send only new
+  outputs or approval decisions;
+- compaction keeps or removes the entire reasoning/call/result group atomically.
+
+In the code, core response aggregation preserves reasoning `Content` items, compaction annotations bind reasoning to
+the tool-call group, and provider adapters serialize or reconstruct the provider-specific reasoning representation.
+
+### Approval correlation, replay, and reused ids
+
+`call_id` is not globally unique forever. The normalizer therefore tracks open logical occurrences in transcript
+order instead of keeping one global result per id.
+
+```mermaid
+flowchart TD
+    Scan["Scan normalized messages in order"]
+    Kind{"content type"}
+    Call["function_call:<br/>open a call occurrence"]
+    Request["function_approval_request"]
+    Bind{"unbound call occurrence<br/>with same call_id?"}
+    BindExisting["Bind request id to existing occurrence<br/>and remove wrapper"]
+    Duplicate{"same request identity<br/>already restored?"}
+    DropDuplicate["Remove replayed duplicate wrapper"]
+    Restore["Restore embedded function_call<br/>as a new occurrence"]
+    Placeholder["function_result with APPROVAL_PENDING:<br/>attach placeholder to open occurrence"]
+    Completed["terminal function_result:<br/>close earliest open occurrence"]
+    Response["function_approval_response"]
+    Pending{"response still pending?"}
+    RemoveOld["Remove already-resolved historical response"]
+    Decision{"approved?"}
+    Approved["Pop next execution result for this call_id"]
+    Rejected["Create synthetic rejection result"]
+    HasPlaceholder{"occurrence has placeholder?"}
+    Replace["Replace placeholder and remove response wrapper"]
+    ReplaceResponse["Replace response wrapper with terminal content"]
+    Close["Close occurrence; append terminal content<br/>to resumed response"]
+    Next["Continue scan"]
+
+    Scan --> Kind
+    Kind -- function_call --> Call --> Next
+    Kind -- approval request --> Request --> Bind
+    Bind -- yes --> BindExisting --> Next
+    Bind -- no --> Duplicate
+    Duplicate -- yes --> DropDuplicate --> Next
+    Duplicate -- no --> Restore --> Next
+    Kind -- pending placeholder --> Placeholder --> Next
+    Kind -- terminal result --> Completed --> Next
+    Kind -- approval response --> Response --> Pending
+    Pending -- no --> RemoveOld --> Next
+    Pending -- yes --> Decision
+    Decision -- yes --> Approved --> HasPlaceholder
+    Decision -- no --> Rejected --> HasPlaceholder
+    HasPlaceholder -- yes --> Replace --> Close --> Next
+    HasPlaceholder -- no --> ReplaceResponse --> Close --> Next
+    Next --> Kind
+```
+
+This flow corresponds to `_ApprovalCallOccurrence`, `_collect_approval_responses(...)`, and
+`_replace_approval_contents_with_results(...)`.
+
+### History and service-side continuation
+
+```mermaid
+flowchart LR
+    Store["History backing store<br/>(may retain approval wrappers for audit)"]
+    Load{"HistoryProvider.load_messages?"}
+    Filter["_filter_approval_control_messages(...)"]
+    Context["SessionContext model history:<br/>function_call + terminal function_result"]
+    Current["Current caller input:<br/>new function_approval_response"]
+    Layer["FunctionInvocationLayer private copy"]
+    Local{"local or hosted-service approval?"}
+    LocalResult["Execute locally and normalize to function_result"]
+    Hosted["Hosted-service adapter"]
+    StoredRequest["Prior service-issued approval request"]
+    NewResponse["Current hosted approval decision"]
+    Skip["Do not replay the stored request inline"]
+    Send["Send the approval decision exactly once"]
+    Later["Later turn"]
+    Manual["Manual-history caller"]
+
+    Store --> Load
+    Load -- yes --> Filter --> Context --> Layer
+    Load -- no --> Layer
+    Current --> Layer
+    Layer --> Local
+    Local -- local --> LocalResult --> Later
+    Local -- hosted service --> Hosted
+    StoredRequest --> Hosted --> Skip
+    NewResponse --> Hosted --> Send --> Later
+    Later --> Store
+    Manual -. owns equivalent filtering .-> Layer
+```
+
+When `load_messages=False`, no history is replayed and the history filter is intentionally not invoked. Callers
+that manually replay messages own the equivalent rule: do not resend an approval response after its terminal result.
+
+## Normative contract
+
+### Function calls and results
+
+- Every actionable local `function_call` produces exactly one terminal `function_result`, unless execution pauses
+  for a new user-input request.
+- Parallel calls retain model order in the returned transcript.
+- Reused `call_id` values are correlated by logical occurrence, not one global value per id.
+- A completed function call/result pair is inert on later turns.
+- Informational-only and declaration-only calls are not executed as local tools.
+
+### Reasoning-bound calls
+
+- Reasoning content or opaque reasoning metadata that a service binds to a function call is part of the same logical
+  group as that call and its terminal result.
+- Active function loops preserve the reasoning content, function call, function result, and final assistant output
+  in caller-visible responses.
+- Framework-managed/stateless replay includes the service-required reasoning representation before the paired call.
+- Service-managed continuation may omit inline reasoning/call items only when the hosted service already owns them.
+- Missing non-reconstructable reasoning fails explicitly before a provider request instead of silently dropping the
+  content.
+- Compaction preserves or excludes the complete reasoning/call/result group atomically.
+
+### Approval request and resume
+
+- A tool that requires approval does not execute before an approved response.
+- An approved tool executes exactly once.
+- A rejected tool executes zero times and produces one synthetic rejection `function_result` using the original
+  function `call_id`.
+- The resumed response contains the newly resolved approved and rejected terminal results before any final assistant
+  message.
+- Streaming yields the same logical result content and ordering as non-streaming output and
+  `ResponseStream.get_final_response()`.
+- The function invocation layer normalizes a private copy of caller messages. It must not mutate the caller's
+  approval `Message`, approval `Content`, or an earlier returned response.
+- Approval-time `UserInputRequiredException` and `MiddlewareTermination` return immediately without another model
+  call.
+
+### Approval control content
+
+- `function_approval_request` and `function_approval_response` are control-plane contents, not durable model
+  transcript items.
+- A current hosted approval response must be sent once on the immediate resume request.
+- A server-issued approval request must not be replayed inline during service-side continuation.
+- History providers may retain approval control contents in their backing store for audit, but base history replay
+  filters them before later model calls.
+- Callers that manually own and replay message history without a loading `HistoryProvider` must likewise omit a
+  previously submitted approval response from later continuation requests.
+
+### History and continuation
+
+- Model-bound history contains one function call/result pair per completed logical occurrence.
+- Append-only history must not replay stale approval request/response wrappers to the model.
+- Framework-managed and service-managed continuation must preserve the same logical call/result transcript.
+- A terminal result consumes the corresponding approval authority in explicit stateless replay.
+
+## Scenario-to-test matrix
+
+### Normal function invocation
+
+| Scenario | Required invariant | Primary regression test |
+|---|---|---|
+| Single non-streaming call | Call, result, and final assistant message are returned in order. | `packages/core/tests/core/test_function_invocation_logic.py::test_base_client_with_function_calling` |
+| String input | Flexible string input follows the same loop behavior. | `test_base_client_with_function_calling_string_input` |
+| Multiple sequential rounds | Each round retains one call/result pair. | `test_base_client_with_function_calling_resets` |
+| Streaming call | Call chunks, one result update, and final text are emitted in order. | `test_base_client_with_streaming_function_calling` |
+| Reasoning-bound call | Finalized output retains reasoning, function call, function result, and final text. | `test_streaming_function_calling_response_includes_reasoning_and_tool_results` |
+| Calls across response messages | Every actionable call is executed once. | `test_base_client_executes_function_calls_across_multiple_response_messages` |
+| Parallel calls | Results retain the corresponding call ids and execution count. | `test_max_function_calls_limits_parallel_invocations`, `test_streaming_multiple_function_calls_parallel_execution` |
+| Informational-only call | The call is returned but not executed or approved. | `test_informational_only_function_call_is_not_invoked`, `test_informational_only_function_call_does_not_request_approval`, `test_streaming_informational_only_function_call_is_not_invoked` |
+| Declaration-only call | The call is surfaced as user input and is not executed. | `test_declaration_only_tool` |
+| Function invocation disabled | The client bypasses the invocation loop without losing invocation kwargs. | `test_function_invocation_config_enabled_false`, `test_function_invocation_config_enabled_false_preserves_invocation_kwargs`, `test_streaming_function_invocation_config_enabled_false` |
+| Runtime tool changes | Added tools become available on the next iteration and retain approval behavior. | `test_add_tools_available_next_iteration`, `test_add_tools_with_approval_required_tool` |
+
+### Approval pause and resume
+
+| Scenario | Required invariant | Primary regression test |
+|---|---|---|
+| Initial approval request | Assistant response contains the original call and approval request; tool does not execute. | `test_approval_requests_in_assistant_message`, `test_streaming_approval_request_generated`, `test_streaming_approval_requests_in_assistant_message` |
+| Approved non-streaming resume | Result precedes final text; tool executes once; inputs remain unchanged. | `packages/core/tests/core/test_harness_tool_approval.py::test_approval_resume_returns_result_without_mutating_inputs[non-streaming-approved]` |
+| Rejected non-streaming resume | Rejection result precedes final text; tool executes zero times; inputs remain unchanged. | `test_approval_resume_returns_result_without_mutating_inputs[non-streaming-rejected]` |
+| Approved streaming resume | Result update precedes final text and final response matches non-streaming shape. | `test_approval_resume_returns_result_without_mutating_inputs[streaming-approved]`, `test_streaming_approval_resume_yields_terminal_result_before_model_text[approved]` |
+| Rejected streaming resume | Rejection result update precedes final text and tool executes zero times. | `test_approval_resume_returns_result_without_mutating_inputs[streaming-rejected]`, `test_streaming_approval_resume_yields_terminal_result_before_model_text[rejected]` |
+| Mixed approved/rejected batch | Every call gets one correctly correlated terminal result. | `packages/core/tests/core/test_function_invocation_logic.py::test_rejected_approval` |
+| Persisted approval replay | Resume executes with the prior call available. | `test_persisted_approval_messages_replay_correctly` |
+| Hosted approval pass-through | Hosted requests/responses are not processed as local calls. | `test_hosted_tool_approval_response`, `test_hosted_mcp_approval_response_passthrough`, `test_mixed_local_and_hosted_approval_flow` |
+| Approval-time user input | Every user-input request from one approved execution returns in order with assistant role and no extra model call; the execution consumes one call-budget unit. | `packages/core/tests/core/test_harness_tool_approval.py::test_approval_resume_returns_all_user_input_requests_without_another_model_call`, `packages/core/tests/core/test_function_invocation_logic.py::test_approval_resume_user_input_counts_toward_function_call_budget` |
+| Mixed terminal result and follow-up input | Completed siblings remain tool-role while only follow-up input requests use assistant-role messages/updates. | `packages/core/tests/core/test_function_invocation_logic.py::test_approval_resume_separates_terminal_results_from_follow_up_requests`, `packages/openai/tests/openai/test_openai_chat_completion_client.py::test_mixed_approval_resume_roles_serialize_function_result_as_tool` |
+| Approval-time middleware termination | Terminal result returns with no extra model call in either response mode. | `packages/core/tests/core/test_function_invocation_logic.py::test_approval_resume_honors_middleware_termination` |
+| Approval re-entry after iteration budget | Pending approved calls resolve once even when prior model calls consumed `max_iterations`. | `packages/core/tests/core/test_harness_tool_approval.py::test_auto_approval_resolves_after_iteration_budget_is_exhausted` |
+| Approval resume with reasoning | Model-bound resume history retains reasoning before the call and terminal result in both modes. | `packages/core/tests/core/test_harness_tool_approval.py::test_approval_resume_replays_reasoning_with_function_call_group` |
+
+### Approval correlation and replay
+
+| Scenario | Required invariant | Primary regression test |
+|---|---|---|
+| Result matching without placeholders | Results match calls by id even when the result list is reordered. | `test_replace_approval_contents_with_results_uses_result_call_ids_without_placeholders` |
+| Reused id after completion | A later round with the same id creates a second valid pair. | `test_replace_approval_contents_with_results_allows_reused_call_id_after_completion` |
+| Replayed approval wrapper | A duplicated wrapper does not restore another function call. | `test_replace_approval_contents_with_results_deduplicates_replayed_approval_request` |
+| Historical resolved response plus new round | The old response is removed from normalized input and is not converted into a rejection result. | `test_replace_approval_contents_with_results_ignores_already_resolved_response` |
+| Multiple reused-id rounds | Approved and rejected rounds retain separate call/result occurrences. | `test_replace_approval_contents_with_results_correlates_reused_call_id_occurrences` |
+| Multi-content result with reused id | Every content produced by one execution stays with that approval occurrence and cannot bleed into the next reused-id round. | `test_replace_approval_contents_with_results_keeps_multi_content_group_with_reused_call_id` |
+| Follow-up request closes one occurrence | A user-input follow-up consumes only the preceding approval authority and leaves a later reused-id response pending. | `test_collect_approval_responses_consumes_matching_follow_up_request_occurrence` |
+| Reused-id placeholders | Placeholder results consume approved results by occurrence. | `test_replace_approval_contents_with_results_correlates_reused_call_id_placeholders` |
+| Rejected placeholder | Rejection replaces the pending placeholder instead of adding a second result. | `test_replace_approval_contents_with_results_replaces_rejected_placeholder` |
+| Results reordered with placeholders | Results still match the correct call ids. | `test_replace_approval_contents_with_results_uses_result_call_ids_for_placeholders` |
+| Missing result call id | A malformed result does not steal another approval's result. | `test_replace_approval_contents_with_results_skips_results_without_call_id` |
+| Empty approval message cleanup | Fully consumed approval messages are removed from normalized model input. | `test_replace_approval_contents_with_results_prunes_emptied_messages` |
+| Later stateless turn | A prior terminal approval response cannot execute again. | `test_resolved_approval_response_is_inert_on_later_stateless_turn` |
+| Pending history turn | An unresolved approval batch is omitted atomically from unrelated model input while a later decision can still resume it once. | `packages/core/tests/core/test_harness_tool_approval.py::test_pending_approval_from_file_history_stays_resumable_without_model_orphan` |
+| Duplicate function-call prevention | Approval normalization does not create a second call for one round. | `test_no_duplicate_function_calls_after_approval_processing` |
+| Rejection call id | Rejection result uses the function call id, not only the approval id. | `test_rejection_result_uses_function_call_id` |
+
+### Mixed batches and approval middleware
+
+| Scenario | Required invariant | Primary regression test |
+|---|---|---|
+| Safe and approval-required calls in one batch | Hidden safe calls replay only with the matching visible approval. | `packages/core/tests/core/test_harness_tool_approval.py::test_mixed_batch_hides_already_approved_request_until_approval_replay` |
+| Restored approval state | Serialized `ToolApprovalState` restores mixed-batch behavior. | `test_mixed_batch_accepts_restored_tool_approval_state` |
+| Unrelated turn before approval | Hidden calls do not execute on an unrelated turn. | `test_hidden_mixed_batch_requests_do_not_replay_on_unrelated_turn` |
+| Multiple abandoned batches | Hidden calls replay only for the matching batch. | `test_hidden_mixed_batch_requests_replay_only_for_matching_visible_approval` |
+| Queued approvals | One unresolved approval is surfaced per run without premature execution. | `test_tool_approval_middleware_queues_multiple_approval_requests`, `test_tool_approval_middleware_queues_streamed_approval_requests` |
+| Middleware state plus hidden core state | State saves do not discard hidden mixed-batch calls. | `test_tool_approval_middleware_preserves_hidden_mixed_batch_requests` |
+| Auto-approval callback | Callback receives the original function call and executes the approved set once. | `test_tool_approval_middleware_auto_approval_rule_receives_function_call` |
+| Shared call budget | Auto-approved re-entry does not reset `max_function_calls`, and every executed approval group counts even when it pauses for input. | `test_tool_approval_middleware_auto_approved_loops_share_function_call_budget`, `test_approval_resume_user_input_counts_toward_function_call_budget` |
+| Standing tool rule | Tool-level approval applies only to later matching tools. | `test_tool_approval_middleware_always_approve_tool_rule` |
+| Hosted server boundary | Standing approval does not cross `server_label`. | `test_tool_approval_middleware_standing_rules_include_hosted_server_boundary` |
+| Argument-scoped rule | Exact arguments are required; empty arguments are not tool-wide. | `test_tool_approval_middleware_always_approve_tool_with_arguments_rule`, `test_tool_approval_middleware_empty_arguments_rule_is_not_tool_wide` |
+
+### Errors, control flow, and limits
+
+| Scenario | Required invariant | Primary regression test |
+|---|---|---|
+| Rejected execution | Rejection is a normal terminal result, not an exception to the caller. | `test_unapproved_tool_execution_raises_exception` |
+| Approved tool exception | Generic and detailed error modes preserve one result and one execution. | `test_approved_function_call_with_error_without_detailed_errors`, `test_approved_function_call_with_error_with_detailed_errors` |
+| Approved validation error | Validation failure returns one result without invoking the function body. | `test_approved_function_call_with_validation_error` |
+| Approved success | Successful approved execution returns one result. | `test_approved_function_call_successful_execution` |
+| Consecutive error cap | Error threshold stops repeated failures, submits collected results, and makes only the required final no-tool model call. | `test_function_invocation_config_max_consecutive_errors`, `test_streaming_function_invocation_config_max_consecutive_errors`, `test_approval_resume_error_limit_forces_final_no_tool_response` |
+| Unknown call handling | Configured false returns an error result; configured true raises. | `test_function_invocation_config_terminate_on_unknown_calls_false`, `test_function_invocation_config_terminate_on_unknown_calls_true`, streaming equivalents |
+| Middleware termination | Normal non-approval loop stops without a second model call. | `test_terminate_loop_single_function_call`, `test_terminate_loop_multiple_function_calls_one_terminates`, `test_terminate_loop_streaming_single_function_call` |
+| Maximum iterations | No orphan calls; a final no-tool response or deterministic fallback is returned. | `test_max_iterations_limit`, `test_max_iterations_no_orphaned_function_calls`, `test_max_iterations_makes_final_toolchoice_none_call`, `test_max_iterations_blank_final_fallback_synthesizes_message`, streaming equivalents |
+| Maximum function calls | Parallel overshoot is bounded after the batch; every executed result group counts even without a `function_result`; blank final responses get fallback content. | `test_max_function_calls_limits_parallel_invocations`, `test_max_function_calls_single_calls_per_iteration`, `test_user_input_request_multiple_contents_propagate`, `test_approval_resume_user_input_counts_toward_function_call_budget`, `test_max_function_calls_blank_final_fallback_synthesizes_message`, streaming equivalent |
+| Conversation continuation | Conversation id updates between iterations and is cleared on stop where required. | `test_conversation_id_updated_in_options_between_tool_iterations`, `test_function_invocation_stop_clears_conversation_id_non_stream`, `test_streaming_function_invocation_stop_clears_conversation_id` |
+
+### History and provider serialization
+
+| Scenario | Required invariant | Primary regression test |
+|---|---|---|
+| Append-only history replay | Resolved approval wrappers do not reach a later model call; one call/result pair remains. | `packages/core/tests/core/test_harness_tool_approval.py::test_approval_resume_filters_resolved_control_items_from_file_history` |
+| Pending placeholder history | An approval response remains replayable while its only result is `[APPROVAL_PENDING]`. | `packages/core/tests/core/test_sessions.py::test_filter_approval_controls_keeps_response_for_pending_placeholder` |
+| Pending hosted history replay | Stateless hosted approval requests remain replayable until a response is recorded, then both controls become inert. | `packages/openai/tests/openai/test_openai_chat_client.py::test_stateless_history_preserves_pending_hosted_approval_request_until_response` |
+| Non-history provider plus session | Local history is still auto-injected for approval resume. | `packages/core/tests/core/test_agents.py::test_non_history_context_provider_still_injects_inmemory` |
+| OpenAI approval serialization | Approval id and decision serialize to `mcp_approval_response`. | `test_prepare_message_for_openai_with_function_approval_response`, `test_prepare_content_for_opentool_approval_response`, `test_function_approval_response_with_mcp_tool_call` |
+| OpenAI end-to-end hosted approval | Hosted request parses, response sends, and continuation completes. | `test_end_to_end_mcp_approval_flow` |
+| Stored function call/result | Service-side storage drops server-issued calls but keeps new outputs. | `test_prepare_options_with_conversation_id_strips_server_issued_items`, `test_prepare_messages_for_openai_full_conversation_with_reasoning` |
+| Stateless reasoning replay | Replay reconstructs reasoning, call, and result together; missing required reasoning fails before the request. | `test_tool_loop_store_false_replays_encrypted_reasoning_group`, `test_stateless_request_rejects_non_replayable_reasoning_bound_mcp_output`, `test_prepare_messages_for_openai_full_conversation_with_reasoning` |
+| Opaque reasoning signature replay | Provider-specific opaque reasoning metadata is captured and restored on reconstructed calls. | `packages/gemini/tests/test_gemini_client.py::test_function_call_part_captures_thought_signature_as_reasoning_content`, `test_reconstructed_function_call_replays_thought_signature_from_reasoning_content` |
+| Chat Completions approval wrappers | Framework approval wrappers are not sent as chat messages. | `packages/openai/tests/openai/test_openai_chat_completion_client.py` approval serialization tests |
+| AG-UI approval result event | Approved result emits once with content and persists in snapshot. | `packages/ag-ui/tests/ag_ui/test_approval_result_event.py::test_approval_resume_emits_tool_call_result`, `test_approval_resume_result_has_content`, `test_approval_resume_snapshot_replaces_approval_payload_with_tool_result`, `test_approval_resume_zero_updates_emits_tool_result` |
+| AG-UI rejection/mixed decision | Transport emits only the events defined for approved and rejected calls without duplicates. | `test_rejection_does_not_emit_tool_call_result`, `test_mixed_approve_reject_emits_only_approved_tool_result`, `test_resolve_approval_responses_returns_only_approved` |
+| AG-UI approval-time follow-up | The full grouped user-input pause remains in message history and emits no synthetic `TOOL_CALL_RESULT`. | `test_resolve_approval_responses_preserves_follow_up_user_input_group` |
+| AG-UI approval execution failure | A grouped executor failure becomes one deterministic terminal error result for the approved call. | `test_resolve_approval_responses_returns_failure_when_grouped_execution_raises` |
+| AG-UI no-approval path | Ordinary tool results do not gain an extra approval result event. | `test_no_approval_no_extra_tool_result` |
+| Compaction pair integrity | Function call/result groups remain atomic. | `packages/core/tests/core/test_compaction.py::test_group_annotations_keep_tool_call_and_tool_result_atomic`, `test_group_annotations_include_reasoning_in_tool_call_group` |
+
+## Required coverage gaps
+
+These scenarios are required but are not fully covered by merged tests on `main`:
+
+| Gap | Tracking |
+|---|---|
+| Non-adjacent and reused-id call/result occurrences remain atomic during compaction. | #7212 |
+| Provider-injected approval-required tools defer until `before_run` tools exist and still emit one result. | #7043 |
+| Service-side storage sends the current approval response while omitting the stored request. | #7125 |
+| Service-owned `previous_response_id` continuation cannot execute a terminal approval again on a later turn. | #6851 |
+| A provider that ignores `tool_choice="none"` after an invocation limit cannot expose an unanswered call. | #7045 |
+| Declaration-only streaming preserves request metadata without duplicating arguments. | #6973 |
+| AG-UI `confirm_changes` cleanup correlates one result by original function call id when several results exist. | #6828 |
+
+Do not mark these rows covered by nearby tests; each needs a dedicated regression at the owning layer.
+
+## Minimum validation commands
+
+Run from `python/` for any core function-loop change:
+
+```bash
+uv run poe test -P core
+uv run poe syntax -P core
+uv run poe pyright -P core
+uv run poe test-typing -P core
+```
+
+Also run every affected package. Common approval-loop changes require:
+
+```bash
+uv run poe test -P openai
+uv run poe syntax -P openai
+uv run poe pyright -P openai
+uv run poe test-typing -P openai
+uv run poe test -P ag-ui
+uv run --directory packages/foundry_hosting poe test
+```
+
+Run focused regression files first while iterating, but do not substitute them for the full package commands above.
+
+## Review checklist
+
+Before accepting an update, reviewers must confirm:
+
+- the changed behavior is represented in this specification;
+- the matrix names a regression test for every affected scenario;
+- approved tools cannot execute twice;
+- rejected tools cannot execute;
+- no call or result becomes orphaned or duplicated;
+- call/result matching does not assume `call_id` is globally unique forever;
+- reasoning content or opaque signatures remain in the same logical group as the paired call/result, or replay fails
+  explicitly before sending a lossy provider request;
+- caller messages and previous responses remain immutable;
+- streaming updates and final response agree with non-streaming output;
+- history replay does not reintroduce approval authority;
+- full package, syntax, source typing, and test typing checks were run.
+
+## Related issues
+
+- #7241 — approval-resolution result streaming
+- #7267 / #7271 and #7304 — replayed calls and reused ids
+- #6851 — duplicate side effects after approval continuation
+- #7383 — bind approval responses to framework-issued requests after this foundation merges
+- #6963 / #7095 — opaque reasoning-signature replay
+- #6074 / #7233 — reasoning-paired tool-call replay
+- #6450 / #6794 — provider message and tool-result serialization

docs/specs/feature-usage-bit-registry.md

@@ -0,0 +1,282 @@
+# Feature-usage bit registry (per-language)
+
+> **Status:** draft, accompanies [ADR-0033](../decisions/0033-feature-usage-bitmask-user-agent.md)
+> and [SPEC-004](004-feature-usage-telemetry.md).
+> **Version:** `1` per language · **Width:** 128-bit
+
+This document is the proposed human-readable registry for the feature-usage
+mask. Until ADR-0033 is accepted and the index declarations ship, these tables
+are a **candidate mapping**, not a stable wire contract. The table is the
+allocation authority and published decoder contract; package-local private
+`FeatureIndex` declarations implement the rows they own. There is no generated
+artifact.
+
+This telemetry is intentionally **transparent**: this registry is public, the
+emitted value is human-decodable, and a dedicated env var disables the mask
+without removing the base User-Agent. Python's existing whole-User-Agent opt-out
+also suppresses its mask; see [Opt-out](#opt-out).
+
+## What is collected
+
+A single 128-bit integer (the *feature mask*) describing **which Agent Framework
+features were exercised** in a process — not which packages are installed. The
+candidate below uses package-level bits plus selected major capabilities: core
+agent/workflow/MCP features, stable skill source types, each orchestration
+pattern, each individual built-in context/history provider, and distinct Foundry
+surfaces. ADR-0033 still leaves the final v1 granularity open. A feature sets its
+index at first meaningful activation; the SDK shifts that index, ORs the mask,
+and emits the value.
+
+No identifiers, arguments, prompts, payloads, or user data are encoded — only the
+coarse Boolean \"this feature was observed at least once in this process\" per
+registered bit. A repeated bit on later requests is the same observation, not
+another use and not a count.
+
+## Allocation tenet
+
+**An index represents a stable, framework-owned capability whose adoption answers a
+concrete product or support question.** It has a clear actual-use mark point in a
+public entry path, and the privacy review covers the resulting distinction.
+
+Keep imports, installation state, aliases, wrappers, internal helpers, and
+implementation decorators such as caching/filtering/deduplication within their
+own capability bit. Customer/runtime values — names, prompts, arguments, URLs,
+identifiers, configuration choices — never become bits. A proposed distinction
+without a concrete query and named decision owner waits.
+
+Operational clients, tools, providers, and hosts mark on their first real public
+operation/participation. Constructor marking is reserved for cases where
+construction itself activates or registers the capability; DI instantiation
+alone is not usage.
+
+Ids use the package/integration name for a package-level signal and add a
+capability suffix only when the row tracks a narrower surface. They describe the
+registered feature, not an inheritance hierarchy: for example, Python
+`hosting` is the base `agent-framework-hosting` package, while `hosting.a2a` is
+the separate hosting-A2A integration.
+
+## Per-language, not shared
+
+The two tables below are **independent**. Feature indexes are **not** shared across
+languages — Python bit 13 and .NET bit 13 do not mean the same thing. This is
+deliberate: the User-Agent product token already names the language
+(`agent-framework-python` vs `agent-framework-dotnet`), so a decoder selects the
+right table from the UA and decodes against it. Each SDK numbers and evolves its
+features independently — no cross-language synchronization, no null placeholders,
+no \"same bit, same meaning\" rule.
+
+## Encoding
+
+- **Width:** 128-bit unsigned integer per language.
+- **Versioning:** the emission carries the version so a decoder knows the bit
+  mapping in effect (version is per language).
+- **User-Agent:** the mask is an RFC 7231 **comment** (metadata, not a product
+  token), placed after the agent-framework product token:
+
+  ```text
+  agent-framework-python/1.2.3 (feat=v1.<hex_mask>)
+  ```
+
+  where `<hex_mask>` is lowercase hex, no leading zeros, no `0x` prefix. Example
+  for bits 0, 1, 5 set (`0b100011 = 0x23`):
+
+  ```text
+  agent-framework-python/1.2.3 (feat=v1.23)
+  ```
+
+- **Decoding:** read the **language** from the product token, pick that table;
+  read `vN`, pick that version; test `mask & (1 << index)` for each row. Unknown indexes
+  (newer SDK than the decoder's copy) are ignored.
+
+## Emission scope (where the mask is sent)
+
+- **Marking is universal:** every feature sets its index at first meaningful
+  activation, regardless of provider.
+- **User-Agent `(feat=...)` comment — approved first-party clients only,
+  stamped at request time.** Added only when both the **Azure / Foundry**
+  client/pipeline family and the actual HTTPS origin are approved, re-evaluated
+  on every request and redirect hop. Custom origins are default-deny and an
+  unapproved redirect removes the token. It is
+  **never** sent to third-party providers — a feature fingerprint must not leak
+  into logs we cannot read. See [SPEC-004](004-feature-usage-telemetry.md#emission).
+- **OpenTelemetry: not in v1.** Deferred primarily for privacy (a span attribute
+  would broadcast the fingerprint into the user's general telemetry / third-party
+  APM vendors). Left open behind the version prefix; see
+  [ADR-0033](../decisions/0033-feature-usage-bitmask-user-agent.md#considered-options).
+
+## Index table — Python (`agent-framework-python`, version 1)
+
+Layout: core features 0–31, orchestration patterns 32–47, and
+provider/integration packages from 48.
+
+The provider/integration block is intentionally **not** partitioned by vendor
+ownership. Some packages span first- and third-party services, ownership can
+change, and protocols/storage integrations do not fit a stable first/third-party
+taxonomy. Index ranges are allocation space, not privacy or emission policy;
+the explicit destination allowlist independently ensures that the mask is sent
+only to approved first-party endpoints.
+
+| Index | Id | Feature | Activated at (representative) |
+| --- | --- | --- | --- |
+| 0 | `core.agent` | Agent | `agent_framework.Agent` |
+| 1 | `core.harness_agent` | Harness agent | `agent_framework.create_harness_agent` |
+| 2 | `core.workflow` | Workflow engine (custom graphs) | `agent_framework.WorkflowBuilder` |
+| 3 | `core.mcp` | MCP tool (any transport) | `agent_framework.MCPStdioTool` |
+| 4 | `core.tool_approval` | Tool-approval harness | `agent_framework.ToolApprovalMiddleware` |
+| 5 | `core.memory_provider` | Memory context provider | `agent_framework.MemoryContextProvider` |
+| 6 | `core.skills_provider` | Skills provider | `agent_framework.SkillsProvider` |
+| 7 | `core.file_access_provider` | File-access provider | `agent_framework.FileAccessProvider` |
+| 8 | `core.compaction_provider` | Context compaction provider | `agent_framework.CompactionProvider` |
+| 9 | `core.todo_provider` | Todo provider | `agent_framework.TodoProvider` |
+| 10 | `core.agent_mode_provider` | Agent-mode provider | `agent_framework.AgentModeProvider` |
+| 11 | `core.background_agents_provider` | Background-agents provider | `agent_framework.BackgroundAgentsProvider` |
+| 12 | `core.in_memory_history_provider` | In-memory history provider | `agent_framework.InMemoryHistoryProvider` |
+| 13 | `core.file_history_provider` | File history provider | `agent_framework.FileHistoryProvider` |
+| 14 | `core.file_skills_source` | File-backed skills | `agent_framework.FileSkillsSource` |
+| 15 | `core.in_memory_skills_source` | In-memory / programmatic skills | `agent_framework.InMemorySkillsSource` |
+| 16 | `core.mcp_skills_source` | MCP-backed skills | `agent_framework.MCPSkillsSource` |
+| 17–31 | _reserved_ | core growth | — |
+| 32 | `orchestration.sequential` | Sequential orchestration | `agent_framework_orchestrations.SequentialBuilder` |
+| 33 | `orchestration.concurrent` | Concurrent orchestration | `agent_framework_orchestrations.ConcurrentBuilder` |
+| 34 | `orchestration.group_chat` | Group-chat orchestration | `agent_framework_orchestrations.GroupChatBuilder` |
+| 35 | `orchestration.magentic` | Magentic orchestration | `agent_framework_orchestrations.MagenticBuilder` |
+| 36 | `orchestration.handoff` | Handoff orchestration | `agent_framework_orchestrations.HandoffBuilder` |
+| 37–47 | _reserved_ | orchestration growth | — |
+| 48 | `foundry.chat_client` | Foundry chat client | `agent_framework_foundry.RawFoundryChatClient` |
+| 49 | `foundry.agent` | Foundry agent | `agent_framework_foundry.FoundryAgent` |
+| 50 | `foundry.memory` | Foundry memory provider | `agent_framework_foundry.FoundryMemoryProvider` |
+| 51 | `foundry.embedding` | Foundry embedding client | `agent_framework_foundry.RawFoundryEmbeddingClient` |
+| 52 | `foundry.evals` | Foundry evaluations | `agent_framework_foundry.FoundryEvals` |
+| 53 | `foundry.toolbox` | Foundry Toolbox MCP tool | `agent_framework_foundry_hosting.FoundryToolbox` |
+| 54 | `foundry_local` | Foundry Local client | `agent_framework_foundry_local.FoundryLocalClient` |
+| 55 | `foundry_hosting` | Foundry hosting layer | `agent_framework_foundry_hosting.ResponsesHostServer` / `InvocationsHostServer` |
+| 56 | `openai` | OpenAI clients | `agent_framework_openai` |
+| 57 | `anthropic` | Anthropic clients | `agent_framework_anthropic` |
+| 58 | `bedrock` | AWS Bedrock clients | `agent_framework_bedrock` |
+| 59 | `gemini` | Gemini chat client | `agent_framework_gemini` |
+| 60 | `mistral` | Mistral embedding client | `agent_framework_mistral` |
+| 61 | `ollama` | Ollama clients | `agent_framework_ollama` |
+| 62 | `claude` | Claude Agent SDK agent | `agent_framework_claude` |
+| 63 | `copilotstudio` | Copilot Studio agent | `agent_framework_copilotstudio` |
+| 64 | `github_copilot` | GitHub Copilot agent | `agent_framework_github_copilot` |
+| 65 | `azure_ai_search` | Azure AI Search context provider | `agent_framework_azure_ai_search` |
+| 66 | `azure_cosmos` | Azure Cosmos history / checkpoint store | `agent_framework_azure_cosmos` |
+| 67 | `azure_contentunderstanding` | Azure Content Understanding context provider | `agent_framework_azure_contentunderstanding.ContentUnderstandingContextProvider` |
+| 68 | `redis` | Redis context / history provider | `agent_framework_redis` |
+| 69 | `mem0` | Mem0 memory provider | `agent_framework_mem0.Mem0ContextProvider` |
+| 70 | `purview` | Purview client | `agent_framework_purview.PurviewClient` |
+| 71 | `a2a` | A2A agent / executor | `agent_framework_a2a.A2AAgent` / `A2AExecutor` |
+| 72 | `ag_ui` | AG-UI chat client / agent | `agent_framework_ag_ui` |
+| 73 | `chatkit` | ChatKit integration | `agent_framework_chatkit` |
+| 74 | `devui` | DevUI served | `agent_framework_devui.serve` |
+| 75 | `declarative.agent` | Declarative agent definitions | `agent_framework_declarative.AgentFactory` |
+| 76 | `declarative.workflow` | Declarative workflow definitions | `agent_framework_declarative.WorkflowFactory` |
+| 77 | `durabletask` | Durable task runtime | `agent_framework_durabletask` |
+| 78 | `azurefunctions` | Azure Functions agent host | `agent_framework_azurefunctions` |
+| 79 | `tools.shell` | Shell tools | `agent_framework_tools.shell.LocalShellTool` / `DockerShellTool` |
+| 80 | `monty` | Monty CodeAct provider | `agent_framework_monty.MontyCodeActProvider` |
+| 81 | `hyperlight` | Hyperlight CodeAct provider | `agent_framework_hyperlight.HyperlightCodeActProvider` |
+| 82 | `azure_cosmos_memory` | Azure Cosmos DB semantic-memory provider | `agent_framework_azure_cosmos_memory.CosmosMemoryContextProvider` |
+| 83 | `hosting` | App-owned agent/workflow hosting state | `agent_framework_hosting.AgentState` / `WorkflowState` |
+| 84 | `hosting.a2a` | A2A hosting converters | `agent_framework_hosting_a2a.a2a_to_run` / `a2a_from_run` |
+| 85 | `hosting.mcp` | MCP hosting adapters | `agent_framework_hosting_mcp.AgentMCPTool` / `WorkflowMCPTool` |
+| 86 | `hosting.responses` | OpenAI Responses hosting converters | `agent_framework_hosting_responses.responses_to_run` |
+| 87 | `hosting.telegram` | Telegram hosting converters | `agent_framework_hosting_telegram.telegram_to_run` |
+| 88 | `lab` | Experimental Agent Framework Lab features | `agent_framework.lab` feature entry points |
+| 89–127 | _reserved_ | future packages | — |
+
+## Index table — .NET (`agent-framework-dotnet`, version 1)
+
+| Index | Id | Feature | Activated at (representative) |
+| --- | --- | --- | --- |
+| 0 | `core.agent` | Agent | `Microsoft.Agents.AI.ChatClientAgent` |
+| 1 | `core.harness_agent` | Harness agent | `Microsoft.Agents.AI.HarnessAgent` |
+| 2 | `core.workflow` | Workflow engine (custom graphs) | `Microsoft.Agents.AI.Workflows.WorkflowBuilder` |
+| 3 | `core.tool_approval` | Tool-approval agent | `Microsoft.Agents.AI.ToolApprovalAgent` |
+| 4 | `core.chat_history_memory_provider` | Chat-history memory provider | `Microsoft.Agents.AI.ChatHistoryMemoryProvider` |
+| 5 | `core.file_memory_provider` | File memory provider | `Microsoft.Agents.AI.FileMemoryProvider` |
+| 6 | `core.text_search_provider` | Text-search provider | `Microsoft.Agents.AI.TextSearchProvider` |
+| 7 | `core.file_access_provider` | File-access provider | `Microsoft.Agents.AI.FileAccessProvider` |
+| 8 | `core.skills_provider` | Skills provider | `Microsoft.Agents.AI.AgentSkillsProviderBuilder` |
+| 9 | `core.compaction_provider` | Context compaction provider | `Microsoft.Agents.AI.Compaction.CompactionProvider` |
+| 10 | `core.todo_provider` | Todo provider | `Microsoft.Agents.AI.TodoProvider` |
+| 11 | `core.agent_mode_provider` | Agent-mode provider | `Microsoft.Agents.AI.AgentModeProvider` |
+| 12 | `core.background_agents_provider` | Background-agents provider | `Microsoft.Agents.AI.BackgroundAgentsProvider` |
+| 13 | `core.in_memory_history_provider` | In-memory history provider | `Microsoft.Agents.AI.InMemoryChatHistoryProvider` |
+| 14 | `core.mcp` | MCP tasks / skills integration | `Microsoft.Agents.AI.Mcp.McpClientTaskExtensions` |
+| 15 | `core.file_skills_source` | File-backed skills | `Microsoft.Agents.AI.AgentFileSkillsSource` |
+| 16 | `core.in_memory_skills_source` | In-memory skills | `Microsoft.Agents.AI.AgentInMemorySkillsSource` |
+| 17 | `core.inline_skill` | Inline programmatic skill | `Microsoft.Agents.AI.AgentInlineSkill` |
+| 18 | `core.class_skill` | Class-based programmatic skill | `Microsoft.Agents.AI.AgentClassSkill` |
+| 19 | `core.mcp_skills_source` | MCP-backed skills | `Microsoft.Agents.AI.AgentSkillsProviderBuilderMcpExtensions.UseMcpSkills` |
+| 20–31 | _reserved_ | core growth | — |
+| 32 | `orchestration.sequential` | Sequential orchestration | `Microsoft.Agents.AI.Workflows.SequentialWorkflowBuilder` |
+| 33 | `orchestration.concurrent` | Concurrent orchestration | `Microsoft.Agents.AI.Workflows.ConcurrentWorkflowBuilder` |
+| 34 | `orchestration.group_chat` | Group-chat orchestration | `Microsoft.Agents.AI.Workflows.GroupChatWorkflowBuilder` |
+| 35 | `orchestration.magentic` | Magentic orchestration | `Microsoft.Agents.AI.Workflows.MagenticWorkflowBuilder` |
+| 36 | `orchestration.handoff` | Handoff orchestration | `Microsoft.Agents.AI.Workflows.HandoffWorkflowBuilder` |
+| 37–47 | _reserved_ | orchestration growth | — |
+| 48 | `foundry.chat_client` | Foundry chat client | `Microsoft.Agents.AI.Foundry.FoundryChatClient` |
+| 49 | `foundry.agent` | Foundry agent | `Microsoft.Agents.AI.Foundry.FoundryAgent` |
+| 50 | `foundry.memory` | Foundry memory provider | `Microsoft.Agents.AI.Foundry.FoundryMemoryProvider` |
+| 51 | `foundry.evals` | Foundry evaluations | `Microsoft.Agents.AI.Foundry.FoundryEvals` |
+| 52 | `foundry.toolbox` | Foundry Toolbox MCP tool | `Microsoft.Agents.AI.Foundry.HostedMcpToolboxAITool` |
+| 53 | `foundry_hosting` | Foundry hosting layer | `Microsoft.Agents.AI.Foundry.Hosting.FoundryHostingExtensions.AddFoundryResponses` |
+| 54 | `openai` | OpenAI integration | `Microsoft.Agents.AI.OpenAI` |
+| 55 | `anthropic` | Anthropic integration | `Microsoft.Agents.AI.Anthropic` |
+| 56 | `copilotstudio` | Copilot Studio agent | `Microsoft.Agents.AI.CopilotStudio.CopilotStudioAgent` |
+| 57 | `github_copilot` | GitHub Copilot agent | `Microsoft.Agents.AI.GitHub.Copilot.GitHubCopilotAgent` |
+| 58 | `azure_cosmos` | Cosmos history / checkpoint store | `Microsoft.Agents.AI.CosmosChatHistoryProvider` |
+| 59 | `valkey` | Valkey chat-history provider | `Microsoft.Agents.AI.Valkey.ValkeyChatHistoryProvider` |
+| 60 | `mem0` | Mem0 memory provider | `Microsoft.Agents.AI.Mem0.Mem0Provider` |
+| 61 | `purview` | Purview integration | `Microsoft.Agents.AI.Purview` |
+| 62 | `a2a` | A2A agent | `Microsoft.Agents.AI.A2A.A2AAgent` |
+| 63 | `hosting.ag_ui` | AG-UI hosting endpoint | `Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.AGUIEndpointRouteBuilderExtensions.MapAGUIServer` |
+| 64 | `devui` | DevUI served | `Microsoft.Agents.AI.DevUI` |
+| 65 | `declarative.agent` | Declarative agent definitions | `Microsoft.Agents.AI.PromptAgentFactory.CreateAsync` |
+| 66 | `declarative.workflow` | Declarative workflow definitions | `Microsoft.Agents.AI.Workflows.Declarative.DeclarativeWorkflowBuilder.Build` |
+| 67 | `durabletask` | Durable task runtime | `Microsoft.Agents.AI.DurableTask` |
+| 68 | `azurefunctions` | Azure Functions agent host | `Microsoft.Agents.AI.Hosting.AzureFunctions` |
+| 69 | `tools.shell` | Shell tools | `Microsoft.Agents.AI.Tools.Shell.ShellExecutor` |
+| 70 | `hyperlight` | Hyperlight CodeAct provider | `Microsoft.Agents.AI.Hyperlight.HyperlightCodeActProvider` |
+| 71 | `hosting.agent` | Hosted AF agent wrapper | `Microsoft.Agents.AI.Hosting.AIHostAgent` |
+| 72 | `local_codeact` | Local Python CodeAct provider | `Microsoft.Agents.AI.LocalCodeAct.LocalCodeActProvider` |
+| 73 | `hosting.a2a` | A2A hosting endpoints | `Microsoft.AspNetCore.Builder.A2AEndpointRouteBuilderExtensions.MapA2AJsonRpc` |
+| 74 | `hosting.openai` | OpenAI-compatible hosting endpoints | `Microsoft.AspNetCore.Builder.MicrosoftAgentAIHostingOpenAIEndpointRouteBuilderExtensions.MapOpenAIResponses` |
+| 75–127 | _reserved_ | future packages | — |
+
+## Opt-out
+
+The dedicated mask-only environment variable is shared by both SDKs:
+
+- `AGENT_FRAMEWORK_FEATURE_MASK_DISABLED=true|1` — drops **only** the feature
+  mask; the base `agent-framework-<lang>/{version}` User-Agent is still sent.
+
+The dedicated flag lets a privacy-conscious user keep contributing SDK
+identity/version (useful for support and compatibility triage) while withholding
+the feature-usage signal. Python's existing
+`AGENT_FRAMEWORK_USER_AGENT_DISABLED=true|1` also suppresses its entire Agent
+Framework User-Agent contribution, mask included. Adding a matching .NET
+whole-User-Agent opt-out is outside this design.
+
+## Governance
+
+1. One index per package/feature, **numbered independently per language**, in the
+   table for that language. New indexes are added by editing this file in a reviewed
+   PR; indexes are never reused within a `(language, version)`.
+2. Each package owns a private `FeatureIndex` declaration containing only its
+   rows. Core owns the accumulator API and core indexes, but never imports
+   optional packages. Adding a new optional-package index therefore does not
+   require a core release once the marker API exists.
+3. Adding a feature: apply the [allocation tenet](#allocation-tenet), name the
+   concrete query/decision owner, add the package-local index and table row, and mark the
+   stable public entry point where actual use begins.
+4. Widening beyond 128-bit or re-partitioning bumps that language's version; old
+   decoders keep working because the version prefix disambiguates the mapping.
+5. A repository validation test gathers all package-local declarations for each
+   `(language, version)` and asserts exact table parity, complete non-reserved
+   coverage, `0..127` range, and **no duplicate/overlapping indexes**.
+
+> **No machine-readable registry file ships today.** Nothing consumes one at
+> runtime (packages own private declarations). If/when a programmatic decoder is built, this
+> table is the contract to export to JSON for it then.

dotnet/Directory.Packages.props

@@ -60,7 +60,7 @@
     <PackageVersion Include="AGUI.Client" Version="0.0.3" />
     <PackageVersion Include="AGUI.Server" Version="0.0.3" />
     <PackageVersion Include="System.Text.Json" Version="10.0.9" />
-    <PackageVersion Include="System.Threading.Channels" Version="10.0.8" />
+    <PackageVersion Include="System.Threading.Channels" Version="10.0.9" />
     <PackageVersion Include="System.Threading.Tasks.Extensions" Version="4.6.3" />
     <PackageVersion Include="System.Net.Security" Version="4.3.2" />
     <!-- OpenTelemetry -->
@@ -80,11 +80,11 @@
     <PackageVersion Include="Microsoft.OpenApi" Version="2.7.5" /> <!-- Pin patched OpenAPI.NET to remediate GHSA-v5pm-xwqc-g5wc -->
     <PackageVersion Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.0.0" />
     <!-- Microsoft.Extensions.* -->
-    <PackageVersion Include="Microsoft.Extensions.AI" Version="10.6.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="10.6.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation" Version="10.6.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation.Quality" Version="10.6.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation.Safety" Version="10.6.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI" Version="10.7.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="10.7.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation" Version="10.7.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation.Quality" Version="10.7.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation.Safety" Version="10.7.0" />
     <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.6.0" />
     <PackageVersion Include="Microsoft.Extensions.Caching.Memory" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Compliance.Abstractions" Version="10.5.0" />
@@ -102,10 +102,10 @@
     <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.9" />
     <PackageVersion Include="Microsoft.Extensions.Logging.Console" Version="10.0.1" />
     <PackageVersion Include="Microsoft.Extensions.ServiceDiscovery" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.VectorData.Abstractions" Version="9.7.0" />
+    <PackageVersion Include="Microsoft.Extensions.VectorData.Abstractions" Version="10.7.0" />
     <!-- Vector Stores -->
-    <PackageVersion Include="Microsoft.SemanticKernel.Connectors.InMemory" Version="1.67.0-preview" />
-    <PackageVersion Include="Microsoft.SemanticKernel.Connectors.Qdrant" Version="1.67.0-preview" />
+    <PackageVersion Include="CommunityToolkit.VectorData.InMemory" Version="1.0.0" />
+    <PackageVersion Include="CommunityToolkit.VectorData.Qdrant" Version="1.0.0" />
     <!-- Agent SDKs -->
     <PackageVersion Include="GitHub.Copilot.SDK" Version="1.0.5" />
     <PackageVersion Include="Microsoft.Agents.CopilotStudio.Client" Version="1.3.171-beta" />

dotnet/agent-framework-dotnet.slnx

@@ -31,6 +31,7 @@
     <Project Path="samples/02-agents/AgentProviders/custom/Agent_With_CustomImplementation/Agent_With_CustomImplementation.csproj" />
     <Project Path="samples/02-agents/AgentProviders/dapr/Agent_With_Dapr/Agent_With_Dapr.csproj" />
     <Project Path="samples/02-agents/AgentProviders/github-copilot/Agent_With_GitHubCopilot/Agent_With_GitHubCopilot.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/github-copilot/Agent_With_GitHubCopilot_BYOK/Agent_With_GitHubCopilot_BYOK.csproj" />
     <Project Path="samples/02-agents/AgentProviders/google-gemini/Agent_With_GoogleGemini/Agent_With_GoogleGemini.csproj" />
     <Project Path="samples/02-agents/AgentProviders/ollama/Agent_With_Ollama/Agent_With_Ollama.csproj" />
     <Project Path="samples/02-agents/AgentProviders/onnx/Agent_With_ONNX/Agent_With_ONNX.csproj" />
@@ -66,6 +67,8 @@
     <Project Path="samples/02-agents/Agents/Agent_Step19_InFunctionLoopCheckpointing/Agent_Step19_InFunctionLoopCheckpointing.csproj" />
     <Project Path="samples/02-agents/Agents/Agent_Step20_DynamicFunctionTools/Agent_Step20_DynamicFunctionTools.csproj" />
     <Project Path="samples/02-agents/Agents/Agent_Step21_ShellWithEnvironment/Agent_Step21_ShellWithEnvironment.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step22_AgentMode/Agent_Step22_AgentMode.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step23_TodoList/Agent_Step23_TodoList.csproj" />
   </Folder>
   <Folder Name="/Samples/02-agents/DeclarativeAgents/">
     <Project Path="samples/02-agents/DeclarativeAgents/ChatClient/DeclarativeChatClientAgents.csproj" />
@@ -341,6 +344,9 @@
   <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-ChatClientAgent-Dockerfile/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent-Dockerfile/HostedChatClientAgentDocker.csproj" />
+  </Folder>
   <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-FoundryAgent/">
     <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-FoundryAgent/HostedFoundryAgent.csproj" />
   </Folder>

dotnet/agent-framework-release.slnf

@@ -23,6 +23,7 @@
       "src\\Microsoft.Agents.AI.Hosting.AzureFunctions\\Microsoft.Agents.AI.Hosting.AzureFunctions.csproj",      
       "src\\Microsoft.Agents.AI.Hosting.OpenAI\\Microsoft.Agents.AI.Hosting.OpenAI.csproj",
       "src\\Microsoft.Agents.AI.Hosting\\Microsoft.Agents.AI.Hosting.csproj",
+      "src\\Microsoft.Agents.AI.LocalCodeAct\\Microsoft.Agents.AI.LocalCodeAct.csproj",
       "src\\Microsoft.Agents.AI.Mcp\\Microsoft.Agents.AI.Mcp.csproj",
       "src\\Microsoft.Agents.AI.Mem0\\Microsoft.Agents.AI.Mem0.csproj",
       "src\\Microsoft.Agents.AI.OpenAI\\Microsoft.Agents.AI.OpenAI.csproj",

dotnet/eng/verify-samples/AgentsSamples.cs

@@ -329,6 +329,80 @@ internal static class AgentsSamples
             ],
         },
 
+        new SampleDefinition
+        {
+            Name = "Agent_Step20_DynamicFunctionTools",
+            ProjectPath = "samples/02-agents/Agents/Agent_Step20_DynamicFunctionTools",
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
+            MustContain =
+            [
+                "=== Dynamic Function Tools Sample ===",
+                "=== Non-Streaming Mode ===",
+                "=== Streaming Mode ===",
+                "[User]",
+                "[Agent]",
+            ],
+            ExpectedOutputDescription =
+            [
+                "The output should show the agent starting with only a RequestTools function and dynamically loading additional tools (weather, time, temperature) as needed.",
+                "The output should contain weather information for Seattle and London, the current time in New York, and a Fahrenheit-to-Celsius temperature conversion.",
+                "The output should demonstrate both non-streaming and streaming modes.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Agent_Step21_ShellWithEnvironment",
+            ProjectPath = "samples/02-agents/Agents/Agent_Step21_ShellWithEnvironment",
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
+            MustContain =
+            [
+                "### Stateless mode",
+                "### Persistent mode",
+                "--- Captured environment snapshot ---",
+            ],
+            ExpectedOutputDescription =
+            [
+                "The output should show an agent using a shell tool to print the current working directory.",
+                "The output should demonstrate that in stateless mode side effects (such as changing directory) do not carry between calls, while in persistent mode the working directory and an environment variable (DEMO_TOKEN set to 'hello-world') carry across calls.",
+                "The output should include a captured environment snapshot describing the OS, shell, and working directory.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Agent_Step22_AgentMode",
+            ProjectPath = "samples/02-agents/Agents/Agent_Step22_AgentMode",
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
+            SkipReason = "Interactive sample that reads console input in a loop and does not exit on its own.",
+        },
+
+        new SampleDefinition
+        {
+            Name = "Agent_Step23_TodoList",
+            ProjectPath = "samples/02-agents/Agents/Agent_Step23_TodoList",
+            RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["FOUNDRY_MODEL"],
+            MustContain =
+            [
+                "User:",
+                "Agent:",
+                "--- Current todo list ---",
+            ],
+            ExpectedOutputDescription =
+            [
+                "The output should show an agent planning a team offsite by breaking the work into a todo list.",
+                "The output should show the todo list being updated as progress is reported (for example marking items complete after the venue is booked and invites are sent) and adjusted when the plan changes to skip catering and add a group hike.",
+                "The current todo list should be printed after each turn, showing item status.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
         // ── AgentSkills ─────────────────────────────────────────────────────
 
         new SampleDefinition
@@ -762,6 +836,19 @@ internal static class AgentsSamples
             ],
         },
 
+        new SampleDefinition
+        {
+            Name = "Agent_With_GitHubCopilot_BYOK",
+            ProjectPath = "samples/02-agents/AgentProviders/github-copilot/Agent_With_GitHubCopilot_BYOK",
+            RequiredEnvironmentVariables = ["BYOK_BASE_URL", "BYOK_API_KEY"],
+            OptionalEnvironmentVariables = ["BYOK_PROVIDER_TYPE", "BYOK_MODEL_ID"],
+            ExpectedOutputDescription =
+            [
+                "The output should contain a user prompt and a response about the benefits of BYOK.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
         new SampleDefinition
         {
             Name = "Agent_With_GoogleGemini",

dotnet/global.json

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

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

@@ -60,6 +60,7 @@ covering basics, function tools, structured output, middleware, MCP, code interp
 | Sample | Description |
 | --- | --- |
 | [GitHub Copilot](./github-copilot/Agent_With_GitHubCopilot/) | Create an AIAgent using GitHub Copilot SDK |
+| [GitHub Copilot BYOK](./github-copilot/Agent_With_GitHubCopilot_BYOK/) | Route GitHub Copilot agent requests through your own endpoint (Bring Your Own Key) |
 
 ### [Google Gemini](./google-gemini/)
 

dotnet/samples/02-agents/AgentProviders/github-copilot/Agent_With_GitHubCopilot_BYOK/Agent_With_GitHubCopilot_BYOK.csproj

@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <NoWarn>$(NoWarn);GHCP001</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="GitHub.Copilot.SDK" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.GitHub.Copilot\Microsoft.Agents.AI.GitHub.Copilot.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/02-agents/AgentProviders/github-copilot/Agent_With_GitHubCopilot_BYOK/Program.cs

@@ -0,0 +1,52 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to configure a GitHub Copilot agent with BYOK (Bring Your Own Key),
+// routing requests through your own endpoint (OpenAI, Azure OpenAI, Anthropic, or an
+// OpenAI-compatible service such as vLLM/LiteLLM/Ollama) instead of the GitHub Copilot backend.
+//
+// SECURITY NOTE: BYOK uses static credentials (no automatic token refresh) and usage is tracked
+// by your provider rather than GitHub. Keep API keys out of source control; load them from
+// environment variables or a secret store, as shown here.
+
+using GitHub.Copilot;
+using Microsoft.Agents.AI;
+
+string providerType = Environment.GetEnvironmentVariable("BYOK_PROVIDER_TYPE") ?? "openai";
+string baseUrl = Environment.GetEnvironmentVariable("BYOK_BASE_URL")
+    ?? throw new InvalidOperationException("The BYOK_BASE_URL environment variable is not set.");
+string apiKey = Environment.GetEnvironmentVariable("BYOK_API_KEY")
+    ?? throw new InvalidOperationException("The BYOK_API_KEY environment variable is not set.");
+string modelId = Environment.GetEnvironmentVariable("BYOK_MODEL_ID") ?? "gpt-4o";
+
+// Create and start a Copilot client
+await using CopilotClient copilotClient = new();
+await copilotClient.StartAsync();
+
+// Provider routes the session through a custom endpoint instead of the GitHub Copilot backend.
+// Type is "openai", "azure", or "anthropic". WireApi "completions" is the broadly compatible
+// choice; use "responses" for providers that support the OpenAI Responses API. BYOK also
+// requires Model to be set at the session level.
+SessionConfig sessionConfig = new()
+{
+    Model = modelId,
+    Provider = new ProviderConfig
+    {
+        Type = providerType,
+        WireApi = "completions",
+        BaseUrl = baseUrl,
+        ApiKey = apiKey,
+        ModelId = modelId,
+    },
+};
+
+AIAgent agent = copilotClient.AsAIAgent(sessionConfig, ownsClient: true);
+
+string prompt = "What are the benefits of using your own API keys with an agent framework?";
+Console.WriteLine($"User: {prompt}\n");
+
+await foreach (AgentResponseUpdate update in agent.RunStreamingAsync(prompt))
+{
+    Console.Write(update);
+}
+
+Console.WriteLine();

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

@@ -0,0 +1,76 @@
+# About BYOK (Bring Your Own Key)
+
+BYOK lets you route model requests through your own API keys and infrastructure instead of the
+GitHub Copilot backend — useful for enterprise deployments, custom hosting, or direct billing
+arrangements. See [GitHub's BYOK documentation](https://docs.github.com/en/copilot/how-tos/copilot-sdk/auth/byok)
+for the full list of supported providers and configuration options.
+
+# Prerequisites
+
+Before you begin, ensure you have the following prerequisites:
+
+- .NET 10 SDK or later
+- GitHub Copilot CLI installed and available in your PATH (or provide a custom path)
+- An OpenAI, Azure OpenAI, Anthropic, or OpenAI-compatible endpoint and API key (e.g. vLLM,
+  LiteLLM, or Ollama)
+
+## Setting up GitHub Copilot CLI
+
+To use this sample, you need to have the GitHub Copilot CLI installed. You can install it by
+following the instructions at:
+https://github.com/github/copilot-sdk
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `BYOK_PROVIDER_TYPE` | Provider type (`openai`, `azure`, `anthropic`) | `openai` |
+| `BYOK_BASE_URL` | Base URL of your provider endpoint | *(required)* |
+| `BYOK_API_KEY` | API key for that endpoint | *(required)* |
+| `BYOK_MODEL_ID` | Model name to request (e.g. "gpt-4o") | `gpt-4o` |
+
+## Running the Sample
+
+```powershell
+dotnet run
+```
+
+The sample will:
+
+1. Create a GitHub Copilot client with default options
+2. Configure a session with a `Provider` (BYOK) pointing at your own endpoint instead of the
+   default GitHub Copilot backend
+3. Send a message to the agent
+4. Stream the response
+
+## Advanced Usage
+
+```csharp
+using GitHub.Copilot;
+using Microsoft.Agents.AI;
+
+await using CopilotClient copilotClient = new();
+await copilotClient.StartAsync();
+
+SessionConfig sessionConfig = new()
+{
+    // BYOK requires Model to also be set at the session level.
+    Model = "gpt-4o",
+    Provider = new ProviderConfig
+    {
+        Type = "azure", // or "openai", "anthropic"
+        WireApi = "completions", // or "responses"
+        BaseUrl = "https://api.example.com/v1",
+        ApiKey = "your-api-key",
+        ModelId = "your-model-id", // "deployment-name"
+    },
+};
+
+AIAgent agent = copilotClient.AsAIAgent(sessionConfig, ownsClient: true);
+AgentResponse response = await agent.RunAsync("Hello!");
+Console.WriteLine(response);
+```
+
+> **Note:** BYOK uses static credentials only — dynamic token refresh is not automatic, and
+> model availability depends entirely on your provider's offerings. Usage is tracked through
+> your provider rather than GitHub.

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

@@ -10,7 +10,7 @@
 
   <ItemGroup>
     <PackageReference Include="Azure.Identity" />
-    <PackageReference Include="Microsoft.SemanticKernel.Connectors.InMemory" />
+    <PackageReference Include="CommunityToolkit.VectorData.InMemory" />
   </ItemGroup>
 
   <ItemGroup>

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

@@ -5,10 +5,10 @@
 
 using Azure.AI.Projects;
 using Azure.Identity;
+using CommunityToolkit.VectorData.InMemory;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 using Microsoft.Extensions.VectorData;
-using Microsoft.SemanticKernel.Connectors.InMemory;
 
 var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
 var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";

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

@@ -10,7 +10,7 @@
 
   <ItemGroup>
     <PackageReference Include="Azure.Identity" />
-    <PackageReference Include="Microsoft.SemanticKernel.Connectors.InMemory" />
+    <PackageReference Include="CommunityToolkit.VectorData.InMemory" />
   </ItemGroup>
 
   <ItemGroup>

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

@@ -7,10 +7,10 @@
 
 using Azure.AI.Projects;
 using Azure.Identity;
+using CommunityToolkit.VectorData.InMemory;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 using Microsoft.Extensions.VectorData;
-using Microsoft.SemanticKernel.Connectors.InMemory;
 using SampleApp;
 
 var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");

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

@@ -10,7 +10,7 @@
 
   <ItemGroup>
     <PackageReference Include="Azure.Identity" />
-    <PackageReference Include="Microsoft.SemanticKernel.Connectors.InMemory" />
+    <PackageReference Include="CommunityToolkit.VectorData.InMemory" />
   </ItemGroup>
 
   <ItemGroup>

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

@@ -7,11 +7,11 @@
 
 using Azure.AI.Projects;
 using Azure.Identity;
+using CommunityToolkit.VectorData.InMemory;
 using Microsoft.Agents.AI;
 using Microsoft.Agents.AI.Samples;
 using Microsoft.Extensions.AI;
 using Microsoft.Extensions.VectorData;
-using Microsoft.SemanticKernel.Connectors.InMemory;
 
 var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
 var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";

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

@@ -10,7 +10,7 @@
 
   <ItemGroup>
     <PackageReference Include="Azure.Identity" />
-    <PackageReference Include="Microsoft.SemanticKernel.Connectors.Qdrant" />
+    <PackageReference Include="CommunityToolkit.VectorData.Qdrant" />
   </ItemGroup>
 
   <ItemGroup>

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

@@ -6,10 +6,10 @@
 
 using Azure.AI.Projects;
 using Azure.Identity;
+using CommunityToolkit.VectorData.Qdrant;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 using Microsoft.Extensions.VectorData;
-using Microsoft.SemanticKernel.Connectors.Qdrant;
 using Qdrant.Client;
 
 var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
@@ -134,6 +134,6 @@ internal sealed class DocumentationChunk
     public string SourceName { get; set; } = string.Empty;
     [VectorStoreData]
     public string Text { get; set; } = string.Empty;
-    [VectorStoreVector(Dimensions: 3072)]
+    [VectorStoreVector(dimensions: 3072)]
     public string Embedding => this.Text;
 }

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

@@ -10,7 +10,7 @@
 
   <ItemGroup>
     <PackageReference Include="Azure.Identity" />
-    <PackageReference Include="Microsoft.SemanticKernel.Connectors.InMemory" />
+    <PackageReference Include="CommunityToolkit.VectorData.InMemory" />
   </ItemGroup>
 
   <ItemGroup>

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

@@ -12,10 +12,10 @@ using System.Text.Json;
 using Azure.AI.Extensions.OpenAI;
 using Azure.AI.Projects;
 using Azure.Identity;
+using CommunityToolkit.VectorData.InMemory;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 using Microsoft.Extensions.VectorData;
-using Microsoft.SemanticKernel.Connectors.InMemory;
 using SampleApp;
 using ChatMessage = Microsoft.Extensions.AI.ChatMessage;
 

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

@@ -0,0 +1,16 @@
+<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" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+  </ItemGroup>
+
+</Project>

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

@@ -0,0 +1,153 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// Agent Mode — Switch an agent's operating mode at runtime with AgentModeProvider
+//
+// This sample shows how to use the AgentModeProvider, an AIContextProvider that tracks the
+// agent's current operating "mode" in the session state and exposes tools (mode_get / mode_set)
+// so the agent can query and switch modes as its work progresses. The mode is folded into the
+// instructions sent to the model on every turn, so different modes can drive different behavior.
+//
+// The sample demonstrates two things:
+//   1. The built-in default modes ("plan" and "execute") that ship with the provider.
+//   2. How to customize the available modes via AgentModeProviderOptions.
+//
+// It runs a simple interactive loop. In addition to chatting with the agent, you can switch the
+// agent's mode yourself using a slash command:
+//   /mode            — show the current mode
+//   /mode <name>     — switch to the named mode
+//   /help            — list the available commands and modes
+//   /exit            — quit
+//
+// When you switch modes with /mode, the provider injects a notification on the next turn so the
+// agent clearly sees the change and adjusts its behavior accordingly.
+
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var model = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
+
+// Set AGENT_MODE_USE_CUSTOM=true to run the sample with the custom modes defined below instead of
+// the provider's built-in "plan" / "execute" defaults.
+bool useCustomModes = string.Equals(Environment.GetEnvironmentVariable("AGENT_MODE_USE_CUSTOM"), "true", StringComparison.OrdinalIgnoreCase);
+
+// <create_mode_provider>
+AgentModeProvider modeProvider;
+string[] availableModes;
+
+if (useCustomModes)
+{
+    // Customize the set of modes by supplying AgentModeProviderOptions. Each mode has a name and a
+    // block of instructions describing how the agent should behave while operating in that mode.
+    // DefaultMode selects the mode new sessions start in (defaults to the first mode when omitted).
+    modeProvider = new AgentModeProvider(new AgentModeProviderOptions
+    {
+        DefaultMode = "concise",
+        Modes =
+        [
+            new AgentModeProviderOptions.AgentMode(
+                "concise",
+                "Answer in a single short sentence. Do not elaborate unless the user explicitly asks for more detail."),
+            new AgentModeProviderOptions.AgentMode(
+                "detailed",
+                "Answer thoroughly. Explain your reasoning, provide examples, and cover relevant edge cases."),
+        ],
+    });
+
+    availableModes = ["concise", "detailed"];
+}
+else
+{
+    // Use the provider's built-in modes: "plan" (interactive planning) and "execute" (autonomous
+    // execution). No options are required.
+    modeProvider = new AgentModeProvider();
+    availableModes = ["plan", "execute"];
+}
+// </create_mode_provider>
+
+// Create the agent and attach the mode provider as an AIContextProvider.
+// 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 AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
+    .AsAIAgent(new ChatClientAgentOptions
+    {
+        Name = "ModeAwareAssistant",
+        ChatOptions = new ChatOptions
+        {
+            ModelId = model,
+            Instructions = "You are a helpful assistant. Follow the process and behavior required by your current operating mode.",
+        },
+        AIContextProviders = [modeProvider],
+    });
+
+using var providerToDispose = modeProvider;
+
+AgentSession session = await agent.CreateSessionAsync();
+
+Console.WriteLine("Agent Mode sample. Type a message to chat, or use a slash command.");
+Console.WriteLine($"Available modes: {string.Join(", ", availableModes)}");
+Console.WriteLine($"Current mode: {await modeProvider.GetModeAsync(session)}");
+PrintHelp(availableModes);
+Console.WriteLine();
+
+while (true)
+{
+    Console.Write("> ");
+    string? input = Console.ReadLine()?.Trim();
+
+    // Treat empty input or end-of-stream (Ctrl+D / Ctrl+Z) as a request to exit.
+    if (string.IsNullOrWhiteSpace(input) || input.Equals("/exit", StringComparison.OrdinalIgnoreCase))
+    {
+        break;
+    }
+
+    if (input.Equals("/help", StringComparison.OrdinalIgnoreCase))
+    {
+        PrintHelp(availableModes);
+        continue;
+    }
+
+    // Handle the /mode slash command: "/mode" shows the current mode, "/mode <name>" switches to it.
+    if (input.Equals("/mode", StringComparison.OrdinalIgnoreCase) || input.StartsWith("/mode ", StringComparison.OrdinalIgnoreCase))
+    {
+        string[] parts = input.Split(' ', 2, StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+        if (parts.Length < 2)
+        {
+            Console.WriteLine($"Current mode: {await modeProvider.GetModeAsync(session)}");
+            continue;
+        }
+
+        try
+        {
+            await modeProvider.SetModeAsync(session, parts[1]);
+            Console.WriteLine($"Switched to \"{parts[1]}\" mode.");
+        }
+        catch (ArgumentException ex)
+        {
+            // SetModeAsync throws when the requested mode is not one of the configured modes.
+            Console.WriteLine(ex.Message);
+        }
+
+        continue;
+    }
+
+    // Anything else is a message for the agent. The mode provider injects the current mode (and any
+    // pending mode-change notification) into the context for this turn.
+    Console.WriteLine(await agent.RunAsync(input, session));
+
+    // Print the mode after the turn: the agent may have switched it itself via the mode_set tool as
+    // its work progressed, so this reflects any change the agent made during the turn.
+    Console.WriteLine($"Current mode: {await modeProvider.GetModeAsync(session)}");
+}
+
+static void PrintHelp(string[] availableModes)
+{
+    Console.WriteLine("Commands:");
+    Console.WriteLine("  /mode            Show the current mode");
+    Console.WriteLine($"  /mode <name>     Switch mode ({string.Join(" | ", availableModes)})");
+    Console.WriteLine("  /help            Show this help");
+    Console.WriteLine("  /exit            Quit");
+}

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

@@ -0,0 +1,62 @@
+# Agent Mode
+
+This sample demonstrates how to use the `AgentModeProvider` to track and switch an agent's
+operating **mode** at runtime, and drive different agent behavior depending on the active mode.
+
+The `AgentModeProvider` is an `AIContextProvider` that stores the current mode in the session
+state and injects it into the instructions sent to the model on every turn. It also exposes
+`mode_get` and `mode_set` tools so the agent can query and switch modes on its own as its work
+progresses.
+
+## What it demonstrates
+
+- Attaching an `AgentModeProvider` to an agent via `ChatClientAgentOptions.AIContextProviders`.
+- The provider's **built-in** modes: `plan` (interactive planning) and `execute` (autonomous execution).
+- **Customizing** the available modes with `AgentModeProviderOptions` (set the
+  `AGENT_MODE_USE_CUSTOM` environment variable to `true` to switch to a simple `concise` /
+  `detailed` mode set).
+- Reading and changing the mode from application code with `GetModeAsync` / `SetModeAsync`.
+- A simple interactive input loop that lets the user switch mode with a slash command. When the
+  mode changes this way, the provider injects a notification on the next turn so the agent adjusts
+  its behavior.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `/mode` | Show the current mode |
+| `/mode <name>` | Switch to the named mode |
+| `/help` | List the available commands and modes |
+| `/exit` | Quit (an empty line also exits) |
+
+Any other input is sent to the agent as a message.
+
+## Prerequisites
+
+- .NET 10 SDK or later
+- Microsoft Foundry project endpoint and model configured
+- Azure CLI installed and authenticated (run `az login`)
+- User has the required role to invoke models in the Foundry project
+
+## Running the sample
+
+Set the required environment variables:
+
+```powershell
+$env:FOUNDRY_PROJECT_ENDPOINT="https://your-project-endpoint"
+$env:FOUNDRY_MODEL="gpt-5.4-mini"  # Optional, defaults to gpt-5.4-mini
+```
+
+Run the sample:
+
+```powershell
+dotnet run
+```
+
+To try the custom modes instead of the built-in `plan` / `execute` modes, set the
+`AGENT_MODE_USE_CUSTOM` environment variable to `true` and re-run:
+
+```powershell
+$env:AGENT_MODE_USE_CUSTOM="true"
+dotnet run
+```

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

@@ -0,0 +1,16 @@
+<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" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+  </ItemGroup>
+
+</Project>

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

@@ -0,0 +1,83 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// Todo List — Track work items across turns with TodoProvider
+//
+// This sample shows how to use the TodoProvider, an AIContextProvider that gives an agent a set of
+// tools for managing a todo list (todos_add, todos_complete, todos_remove, todos_get_remaining,
+// todos_get_all) along with instructions on how to use them. The todo list is stored in the
+// session state and persists across turns, so the agent can plan multi-step work, track progress,
+// and adjust the list as the conversation evolves.
+//
+// This is a scripted, non-interactive walkthrough: it sends a sequence of messages to the agent
+// and, after each turn, prints the agent's reply followed by the current todo list (read directly
+// from the provider via GetAllTodosAsync). This lets you watch the todo state evolve as the agent
+// adds, completes, and removes items.
+
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var model = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
+
+// <create_todo_provider>
+// Create the TodoProvider and attach it to the agent as an AIContextProvider. The provider
+// contributes the todo-management tools and instructions to every agent invocation.
+using var todoProvider = new TodoProvider();
+
+// 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 AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
+    .AsAIAgent(new ChatClientAgentOptions
+    {
+        Name = "PlanningAssistant",
+        ChatOptions = new ChatOptions
+        {
+            ModelId = model,
+            Instructions = "You are a helpful planning assistant. Use your todo list to plan and track multi-step work.",
+        },
+        AIContextProviders = [todoProvider],
+    });
+// </create_todo_provider>
+
+AgentSession session = await agent.CreateSessionAsync();
+
+// A scripted set of turns that exercises the provider end-to-end: the agent should add todos for a
+// multi-step request, mark items complete as progress is reported, and adjust the list on a change
+// of plan.
+string[] userMessages =
+[
+    "I'm organizing a small team offsite. Can you help me plan it? Break the work into a todo list.",
+    "I've booked the venue and sent out the invites. Please update the list.",
+    "Actually, let's skip catering and instead plan a group hike. Update the plan accordingly.",
+];
+
+foreach (string userMessage in userMessages)
+{
+    Console.WriteLine($"User: {userMessage}");
+    Console.WriteLine($"Agent: {await agent.RunAsync(userMessage, session)}");
+
+    // Read the current todo list straight from the provider and print it so the state is visible.
+    await PrintTodoListAsync(todoProvider, session);
+    Console.WriteLine();
+}
+
+static async Task PrintTodoListAsync(TodoProvider todoProvider, AgentSession session)
+{
+    IReadOnlyList<TodoItem> todos = await todoProvider.GetAllTodosAsync(session);
+
+    Console.WriteLine("--- Current todo list ---");
+    if (todos.Count == 0)
+    {
+        Console.WriteLine("  (empty)");
+        return;
+    }
+
+    foreach (TodoItem todo in todos)
+    {
+        string status = todo.IsComplete ? "x" : " ";
+        Console.WriteLine($"  [{status}] {todo.Id}. {todo.Title}");
+    }
+}

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

@@ -0,0 +1,47 @@
+# Todo List
+
+This sample demonstrates how to use the `TodoProvider` to let an agent plan and track multi-step
+work using a todo list that persists across turns within a session.
+
+The `TodoProvider` is an `AIContextProvider` that contributes todo-management tools and instructions
+to the agent, and stores the todo list in the session state. The provider exposes the following
+tools to the agent:
+
+- `todos_add` — add one or more todo items (title + optional description).
+- `todos_complete` — mark one or more items complete, with a reason.
+- `todos_remove` — remove one or more items by ID.
+- `todos_get_remaining` — retrieve the incomplete items.
+- `todos_get_all` — retrieve all items (complete and incomplete).
+
+## What it demonstrates
+
+- Attaching a `TodoProvider` to an agent via `ChatClientAgentOptions.AIContextProviders`.
+- The agent breaking a complex request into trackable todo items, marking items complete as
+  progress is reported, and adjusting the list when the plan changes.
+- Reading the todo list from application code with `TodoProvider.GetAllTodosAsync`.
+
+This is a **scripted, non-interactive** walkthrough: it sends a fixed sequence of messages and,
+after each turn, prints the agent's reply followed by the current todo list so you can watch the
+state evolve.
+
+## Prerequisites
+
+- .NET 10 SDK or later
+- Microsoft Foundry project endpoint and model configured
+- Azure CLI installed and authenticated (run `az login`)
+- User has the required role to invoke models in the Foundry project
+
+## Running the sample
+
+Set the required environment variables:
+
+```powershell
+$env:FOUNDRY_PROJECT_ENDPOINT="https://your-project-endpoint"
+$env:FOUNDRY_MODEL="gpt-5.4-mini"  # Optional, defaults to gpt-5.4-mini
+```
+
+Run the sample:
+
+```powershell
+dotnet run
+```

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

@@ -47,6 +47,9 @@ Before you begin, ensure you have the following prerequisites:
 |[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.|
+|[Shell tool with environment-aware system prompt](./Agent_Step21_ShellWithEnvironment/)|This sample demonstrates how to use the shell tool together with the ShellEnvironmentProvider to run commands in stateless and persistent modes, injecting environment-aware instructions so the agent emits commands in the right shell idiom.|
+|[Switching agent operating mode](./Agent_Step22_AgentMode/)|This sample demonstrates how to use the AgentModeProvider to track and switch an agent's operating mode at runtime, including the built-in plan/execute modes and custom modes, with a simple input loop that switches mode using a slash command.|
+|[Tracking work with a todo list](./Agent_Step23_TodoList/)|This sample demonstrates how to use the TodoProvider to let an agent plan and track multi-step work using a todo list that persists across turns, printing the evolving todo list after each turn.|
 
 ## Running the samples from the console
 

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

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

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

@@ -65,6 +65,17 @@ public static class Program
             .AddParticipants([researcherAgent, coderAgent])
             .WithName("Magentic Orchestration Workflow")
             .WithDescription("Coordinates a researcher and coder to solve a complex analytical task.")
+            // By default the manager's internally generated messages (task ledger, progress ledger, final answer)
+            // use the built-in English prompts. To have them written in another language, pin a concrete language:
+            //     .WithResponseLanguage("French")
+            // For full control you can also override any of the internal prompt templates (placeholders such as
+            // {task}, {team}, and - for the progress ledger - {schema} are substituted by the framework):
+            //     .WithPromptOverrides(new MagenticPromptOverrides
+            //     {
+            //         FinalAnswerPrompt = "Rédige la réponse finale à la demande suivante en français :\n{task}",
+            //     })
+            // The built-in English templates you can copy and translate are published on MagenticDefaultPrompts
+            // (e.g. MagenticDefaultPrompts.ProgressLedgerPrompt) - use them as a starting point for your overrides.
             .RequirePlanSignoff(false)
             .WithMaxRounds(10)
             .WithMaxStalls(3)

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

@@ -205,3 +205,17 @@ For end-to-end hosted agent deployment guidance, see the [official deployment gu
 ## 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 `HostedAzureSearchRag.csproj` for the `PackageReference` alternative.
+
+## Troubleshooting
+
+**`azd ai agent invoke` fails with `404 not_found: Conversation '<id>' not found`**
+
+`azd` saves the session and conversation per agent and reuses them on the next invoke. Once the
+agent is redeployed, deleted, or restarted, that saved conversation no longer exists on the server,
+so every following invoke fails even though the agent itself is healthy. Start a fresh one:
+
+```
+azd ai agent invoke --new-conversation "Hello!"
+```
+
+Add `--new-session` as well if the failure persists.

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

@@ -0,0 +1,20 @@
+# Keeps local-only files out of the image build context. Without this, `COPY . .` in the Dockerfile
+# would copy the local .env into a build layer, so local credentials would ship inside the image.
+.env
+.env.*
+.azure/
+.git/
+
+# Build output: the image builds from source, so shipping host binaries only bloats the context and
+# risks copying binaries built for a different platform into the container.
+bin/
+obj/
+*.user
+*.suo
+.vs/
+
+# Agent session state written during local runs.
+.checkpoints/
+
+# Note: local-feed/ and nuget.config are deliberately NOT excluded. When present (contributor mode)
+# the `dotnet restore` inside the image build resolves the Agent Framework from them.

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

@@ -0,0 +1,17 @@
+# Foundry project endpoint (shape: https://<host>/api/projects/<project>)
+FOUNDRY_PROJECT_ENDPOINT=<your-azure-ai-project-endpoint>
+
+# Model deployment name in your Foundry project.
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+
+# Local development only. Bind the app to the port Foundry probes for readiness, which is the
+# port the Using-Samples REPLs expect. The Dockerfile sets this for the container; a plain
+# `dotnet run` on the host does not go through the Dockerfile, so set it here too.
+ASPNETCORE_URLS=http://+:8088
+
+# Local development only. Restrict DefaultAzureCredential to developer credentials
+# (Azure CLI, Visual Studio, azd) and skip the Managed Identity probe. Without this,
+# on a machine with no managed identity DefaultAzureCredential hangs for a long time
+# probing the IMDS endpoint (169.254.169.254) before every model call. Not set in
+# Foundry, where the platform-injected managed identity is used.
+AZURE_TOKEN_CREDENTIALS=dev

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

@@ -0,0 +1,19 @@
+# Foundry builds this image and runs it as the hosted agent. The build restores and publishes the
+# project inside the container, so a contributor feed dropped into this folder (local-feed/ plus
+# nuget.config) is picked up by the `dotnet restore` below without any change here.
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /src
+COPY . .
+RUN dotnet restore
+RUN dotnet publish -c Release -o /app/publish
+
+FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS final
+WORKDIR /app
+COPY --from=build /app/publish .
+
+# Foundry probes port 8088 for readiness. The .NET base image defaults ASPNETCORE_URLS to port 80,
+# so without this the probe never succeeds and every invoke fails with HTTP 424 session_not_ready.
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+
+ENTRYPOINT ["dotnet", "HostedChatClientAgentDocker.dll"]

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

@@ -0,0 +1,46 @@
+<Project>
+
+  <!--
+    Container deploy sample. Foundry builds the Dockerfile in this folder and runs the resulting
+    image, so unlike the source (ZIP) path there is no server-side `dotnet restore` on a bare
+    folder: the restore happens inside the container build.
+
+    ImportDirectoryPackagesProps has to be set before the SDK props are imported, hence the explicit
+    Sdk imports below instead of the usual Sdk attribute on the Project element. It stops MSBuild
+    from walking up to the repository's dotnet/Directory.Packages.props, which does two things this
+    sample must avoid: it turns on central package management, and it injects analyzer
+    PackageReference items whose versions it also supplies. Neither exists inside the container
+    build context, so without this the in-repo build would resolve differently from the image build.
+  -->
+
+  <PropertyGroup>
+    <ImportDirectoryPackagesProps>false</ImportDirectoryPackagesProps>
+  </PropertyGroup>
+
+  <Import Project="Sdk.props" Sdk="Microsoft.NET.Sdk.Web" />
+
+  <PropertyGroup>
+    <!-- Single target: the Dockerfile publishes without -f, so the project must not multi-target.
+         The empty TargetFrameworks clears the value inherited from the repo's samples
+         Directory.Build.props for in-repo builds. -->
+    <TargetFramework>net10.0</TargetFramework>
+    <TargetFrameworks></TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <RootNamespace>HostedChatClientAgentDocker</RootNamespace>
+    <AssemblyName>HostedChatClientAgentDocker</AssemblyName>
+    <UserSecretsId>7b1c3f04-24a1-4f0e-9a5e-0d2f6b8c1e57</UserSecretsId>
+    <AgentFrameworkVersion>1.15.0-preview.260722.1</AgentFrameworkVersion>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.Foundry" Version="$(AgentFrameworkVersion)" />
+    <PackageReference Include="Microsoft.Agents.AI.Foundry.Hosting" Version="$(AgentFrameworkVersion)" />
+    <PackageReference Include="Azure.AI.Projects" Version="2.1.0-beta.4" />
+    <PackageReference Include="Azure.Identity" Version="1.21.0" />
+    <PackageReference Include="DotNetEnv" Version="3.1.1" />
+  </ItemGroup>
+
+  <Import Project="Sdk.targets" Sdk="Microsoft.NET.Sdk.Web" />
+
+</Project>

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

@@ -0,0 +1,61 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// Sample: a minimal general-purpose AI assistant hosted as a Foundry Hosted Agent
+// using the Responses protocol. It is deployed to Foundry as a container image built
+// from the Dockerfile in this folder.
+//
+// The sibling Hosted-ChatClientAgent sample is the same agent deployed the other way,
+// straight from source with no container image. Compare the two folders to see exactly
+// what the container path adds.
+
+using Azure.AI.Projects;
+using Azure.Identity;
+using DotNetEnv;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry.Hosting;
+
+// Load a local .env file when present (local development only). In Foundry the
+// platform injects the required environment variables at runtime.
+Env.TraversePath().Load();
+
+var projectEndpoint = new Uri(System.Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set."));
+
+// Environment variables can arrive set but blank: azd substitutes an empty string when the azd
+// environment does not define the variable referenced from azure.yaml. An empty string is not
+// null, so a plain ?? chain would pass the blank straight through and fail deep inside the SDK.
+var model = FirstNonBlank(
+    System.Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME"),
+    System.Environment.GetEnvironmentVariable("FOUNDRY_MODEL"),
+    "gpt-4o");
+
+var agentName = System.Environment.GetEnvironmentVariable("AGENT_NAME") ?? "hosted-chat-client-agent-docker";
+
+// WARNING: DefaultAzureCredential is convenient for development but requires careful
+// consideration in production. Consider a specific credential (for example
+// ManagedIdentityCredential) to avoid latency, unintended credential probing, and
+// fallback security risks.
+AIAgent agent = new AIProjectClient(projectEndpoint, new DefaultAzureCredential())
+    .AsAIAgent(
+        model: model,
+        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 using the Responses protocol.
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddFoundryResponses(agent);
+
+var app = builder.Build();
+app.MapFoundryResponses();
+
+app.Run();
+
+// Returns the first candidate that has an actual value, ignoring null and blank entries.
+static string FirstNonBlank(params string?[] candidates) =>
+    Array.Find(candidates, c => !string.IsNullOrWhiteSpace(c))!;

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

@@ -0,0 +1,327 @@
+# Hosted-ChatClientAgent-Dockerfile
+
+A minimal general-purpose AI assistant hosted as a Foundry Hosted Agent using the Responses protocol. The agent is created inline via `AIProjectClient.AsAIAgent(model, instructions)` and served with `AddFoundryResponses` / `MapFoundryResponses`.
+
+This sample deploys to Foundry as a **container image** built from the `Dockerfile` in this folder.
+
+The sibling [`Hosted-ChatClientAgent`](../Hosted-ChatClientAgent/) sample is the same agent deployed the other way, straight from source with no container image. That is the default for .NET and needs no Docker, so prefer it unless you need control over the runtime image.
+
+| | Source (ZIP) | Container (this sample) |
+|---|---|---|
+| Deploy mode | `code`, the default for .NET | `container`, opt in with `--deploy-mode container` |
+| Extra files | none | `Dockerfile`, `.dockerignore` |
+| Who builds | Foundry runs `dotnet restore` + `dotnet publish` on the upload | Foundry builds the `Dockerfile` |
+| Docker required | no | no, `azd` builds remotely in Azure Container Registry |
+| Listen port | the package binds it, or `env` in `azure.yaml` | `ENV ASPNETCORE_URLS` in the `Dockerfile` |
+| Extra Azure resource | none | an Azure Container Registry |
+
+## Prerequisites
+
+- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
+- An **existing** Foundry project with an **existing** model deployment (for example `gpt-4o`).
+  This sample's `azure.yaml` declares no `deployments:` block, so `azd` connects to a project and
+  a deployment you already have rather than creating them. `azd ai agent init` prompts you to pick
+  the project, and takes the deployment name as the `-d` argument.
+- Azure CLI logged in (`az login`)
+- Azure Developer CLI (`azd`) with the AI agents extension: `azd extension install azure.ai.agents`
+- Docker Desktop **only** if you switch to local image builds by setting `remoteBuild: false` under
+  the `docker:` block in `azure.yaml`. By default `azd` builds the image in Azure Container
+  Registry, so no local Docker is needed.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `Program.cs` | The agent: builds the agent, hosts it with the Responses protocol. |
+| `Dockerfile` | Builds the image Foundry runs. Restores and publishes the project inside the container, and pins the listen port to 8088. |
+| `.dockerignore` | Keeps local-only files (notably `.env`) out of the image build context. |
+| `azure.yaml` | The unified `azd` project file. Declares the Foundry project and the hosted agent with `language: docker` and no `codeConfiguration`, which is what selects the container path. |
+| `HostedChatClientAgentDocker.csproj` | Self-contained project: single target framework and explicit package versions. It also opts out of the repository's central package management, which does not travel inside the image build context. |
+| `.env.example` | Template for local configuration. |
+
+## Configuration
+
+Copy the template and fill in your project endpoint:
+
+PowerShell:
+
+```powershell
+copy .env.example .env
+```
+
+Bash:
+
+```bash
+cp .env.example .env
+```
+
+```env
+FOUNDRY_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+ASPNETCORE_URLS=http://+:8088
+AZURE_TOKEN_CREDENTIALS=dev
+```
+
+> `.env` is gitignored, and `.dockerignore` keeps it out of the image. The `.env.example` template
+> is checked in as a reference.
+
+> **Windows note:** write `.env` as UTF-8 **without** a byte order mark. `azd` reads the file
+> during `azd ai agent init` and fails with `unexpected character "»" in variable name` when a mark
+> is present. PowerShell's `Set-Content -Encoding UTF8BOM` adds one; use `-Encoding utf8NoBOM`.
+
+> **Local development on a machine without a managed identity:** set `AZURE_TOKEN_CREDENTIALS=dev`.
+> `Program.cs` authenticates with `DefaultAzureCredential` (the pattern the hosted platform
+> expects, where a managed identity is injected). On a developer machine with no managed identity,
+> `DefaultAzureCredential` probes the Azure Instance Metadata Service (IMDS, `169.254.169.254`) and
+> blocks for a long time on the network timeout before every model call, so requests appear to
+> hang. Setting `AZURE_TOKEN_CREDENTIALS=dev` restricts `DefaultAzureCredential` to developer
+> credentials (Azure CLI, Visual Studio, `azd`) and skips the managed-identity probe. This variable
+> is only for local runs; the deployed agent in Foundry uses the platform-injected managed identity.
+
+## Run and test locally
+
+Local runs use two terminals: one hosts the agent, the other is a code-first client that talks to it
+using Agent Framework components, see the sibling [`Using-Samples`](../Using-Samples/) REPLs.
+
+**Terminal 1 — host the agent:**
+
+```
+cd dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent-Dockerfile
+az login
+dotnet run
+```
+
+The agent starts on `http://localhost:8088`.
+
+**Terminal 2 — chat with it (code-first REPL):**
+
+PowerShell:
+
+```powershell
+cd dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent
+$env:AZURE_AI_AGENT_NAME = "hosted-chat-client-agent-docker"
+dotnet run -- --local
+```
+
+Bash:
+
+```bash
+cd dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent
+export AZURE_AI_AGENT_NAME="hosted-chat-client-agent-docker"
+dotnet run -- --local
+```
+
+To exercise the image instead of the host build, build and run the container directly:
+
+```
+docker build -t hosted-chat-client-agent-docker .
+docker run --rm -p 8088:8088 --env-file .env hosted-chat-client-agent-docker
+```
+
+## Deploy to Foundry (container)
+
+`azd` scaffolds the project into a working folder, so every step below runs from an **empty
+directory outside the repository**, and `-m` points at this sample's `azure.yaml`.
+
+### Step 1: create the working directory and enter it
+
+PowerShell:
+
+```powershell
+$work = Join-Path $env:TEMP "hosted-chat-docker-work"
+mkdir $work
+cd $work
+```
+
+Bash:
+
+```bash
+WORK="${TMPDIR:-/tmp}/hosted-chat-docker-work"
+mkdir -p "$WORK"
+cd "$WORK"
+```
+
+### Step 2: scaffold the project
+
+`--deploy-mode container` is the argument that selects the container path. Without it `azd`
+defaults to `code` for .NET, which ignores the `Dockerfile` and deploys the source as a ZIP.
+
+`azd ai agent init` copies the sample into a subfolder named after the top-level `name:` in
+`azure.yaml`, which is `hosted-chat-client-agent-docker`. It also writes the adopted `azure.yaml`
+and the `azd` environment there.
+
+`azd ai agent init` prompts you to pick the Foundry project, so no project argument is needed.
+`-d` is the name of an existing model deployment in that project; omit it and `azd` prompts for
+that too.
+
+> Pick an **existing** project at the prompt. The prompt needs an interactive terminal: run
+> non-interactively (in CI, for example) and `azd` skips it and provisions a brand new Foundry
+> project and resource group instead. Pass `-p <project-resource-id>` when you need that to be
+> unattended.
+
+`azure.yaml` passes the model deployment to the container by reading it from the `azd` environment.
+Confirm it landed there, and set it yourself if it did not:
+
+```
+azd env get-values
+azd env set AZURE_AI_MODEL_DEPLOYMENT_NAME <model-deployment>
+```
+
+PowerShell:
+
+```powershell
+$sample = "<repo>/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent-Dockerfile/azure.yaml"
+
+azd auth login
+azd ai agent init -m $sample -d <model-deployment> --deploy-mode container
+```
+
+Bash:
+
+```bash
+SAMPLE="<repo>/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent-Dockerfile/azure.yaml"
+
+azd auth login
+azd ai agent init -m "$SAMPLE" -d <model-deployment> --deploy-mode container
+```
+
+### Step 3: provision and deploy
+
+Contributors: if you are changing the Agent Framework source in this repository and want the
+deployed agent to run **your** build rather than the published packages, do the extra step in
+[Deploy your local framework changes](#deploy-your-local-framework-changes-contributors) now,
+before the commands below. Everyone else can ignore it.
+
+```
+cd hosted-chat-client-agent-docker
+azd provision
+azd deploy
+azd ai agent invoke "Hello!"
+```
+
+`azd provision` creates the Azure Container Registry the image is pushed to, alongside the rest of
+the environment. `azd deploy` builds the image (remotely in that registry by default), pushes it,
+and creates the agent version.
+
+To build the image on your own machine instead, flip `remoteBuild` to `false` in `azure.yaml`:
+
+```yaml
+        docker:
+            remoteBuild: false
+```
+
+That requires Docker Desktop, and on Apple Silicon or other ARM machines you must produce an
+x86_64 image, since the hosting platform only runs `linux/amd64`.
+
+You can also test the deployed agent with the REPL:
+
+PowerShell:
+
+```powershell
+cd <repo>/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent
+$env:FOUNDRY_PROJECT_ENDPOINT = "https://<your-account>.services.ai.azure.com/api/projects/<your-project>"
+$env:AZURE_AI_AGENT_NAME      = "hosted-chat-client-agent-docker"
+dotnet run -- --remote
+```
+
+Bash:
+
+```bash
+cd <repo>/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent
+export FOUNDRY_PROJECT_ENDPOINT="https://<your-account>.services.ai.azure.com/api/projects/<your-project>"
+export AZURE_AI_AGENT_NAME="hosted-chat-client-agent-docker"
+dotnet run -- --remote
+```
+
+### Step 4: clean up
+
+```
+azd down
+```
+
+Then delete the working directory.
+
+## Deploy your local framework changes (contributors)
+
+**Skip this section unless you are changing the Agent Framework itself.** Everything above is the
+complete flow for using the sample. This section only applies when you are working on the framework
+source in this repository, or when you otherwise need a build of it that is not published on
+nuget.org.
+
+The reason it exists: the project restores the **published** Agent Framework packages, and the
+`dotnet restore` inside the image build pulls them from nuget.org. So editing framework source in
+this repository changes nothing about the deployed agent, no matter how many times you rebuild
+locally. The image build context is self-contained and knows nothing about your working tree.
+
+The extra step packs your local framework source into NuGet packages and puts them **inside the
+build context**, together with a `nuget.config` that points the restore at them. The restore inside
+the image build then resolves the framework from the packages you shipped instead of from
+nuget.org.
+
+Run it in the flow above, **between step 2 and step 3**. Nothing else changes, and it is the same
+script the source-deploy sample uses: the `Dockerfile` copies the whole folder before restoring, so
+a feed dropped in this folder is picked up with no change to the `Dockerfile`.
+
+Run it from `$work`, the working directory created in step 1, which now holds the
+`hosted-chat-client-agent-docker` folder that `azd ai agent init` scaffolded:
+
+PowerShell:
+
+```powershell
+cd $work
+<repo>/dotnet/samples/04-hosting/FoundryHostedAgents/scripts/Add-LocalFrameworkFeed.ps1 -Path ./hosted-chat-client-agent-docker
+```
+
+Bash:
+
+```bash
+cd "$WORK"
+<repo>/dotnet/samples/04-hosting/FoundryHostedAgents/scripts/add-local-framework-feed.sh ./hosted-chat-client-agent-docker
+```
+
+Then continue with step 3. The path argument is optional: called without it, the script uses the
+current directory, so you can also run it from inside `hosted-chat-client-agent-docker`.
+
+The script changes three things in the scaffolded folder:
+
+| Change | Detail |
+|--------|--------|
+| Creates `local-feed/` | The Agent Framework packed from your local source, stamped with a version like `1.15.0-preview-local.<timestamp>` |
+| Creates `nuget.config` | Resolves `Microsoft.Agents.AI*` from that folder and everything else from nuget.org |
+| Edits the `.csproj` | Repoints its `AgentFrameworkVersion` property at the version just packed |
+
+Neither generated file is excluded by `.dockerignore`, so both reach the image build context and
+the restore inside the build uses them. The scaffolded folder is a throwaway copy, so the
+repository is left untouched.
+
+Two details worth knowing:
+
+- The version carries a timestamp because NuGet caches by package id and version. Reusing a version
+  would silently restore the previously packed bits instead of the build you just made.
+- The whole package closure is packed, not just the two packages the sample references. Packing
+  only the leaf packages lets NuGet fill the rest from nuget.org, mixing a published core with a
+  locally built host, which fails to compile.
+
+Before spending a deploy, build the scaffolded folder locally. A restore problem surfaces in
+seconds instead of after the image build:
+
+```
+cd hosted-chat-client-agent-docker
+dotnet build -c Debug --tl:off
+```
+
+## Troubleshooting
+
+**`azd ai agent invoke` fails with `404 not_found: Conversation '<id>' not found`**
+
+`azd` saves the session and conversation per agent and reuses them on the next invoke. Once the
+agent is redeployed, deleted, or restarted, that saved conversation no longer exists on the server,
+so every following invoke fails even though the agent itself is healthy. Start a fresh one:
+
+```
+azd ai agent invoke --new-conversation "Hello!"
+```
+
+Add `--new-session` as well if the failure persists.
+
+For the full hosted-agent deployment guide, see the [official container deployment doc](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent).

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

@@ -0,0 +1,44 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json
+
+name: hosted-chat-client-agent-docker
+services:
+    ai-project:
+        host: azure.ai.project
+    hosted-chat-client-agent-docker:
+        project: .
+        host: azure.ai.agent
+        # `docker` selects the container build path: Foundry builds the Dockerfile in this folder
+        # instead of restoring a plain source folder. There is no codeConfiguration block here,
+        # which is what tells the tooling this is a container deploy rather than a source deploy.
+        language: docker
+        docker:
+            # azd builds the image in Azure Container Registry by default. Set this to false to
+            # build on your own machine instead, which requires Docker Desktop.
+            remoteBuild: true
+        uses:
+            - ai-project
+        # ${AZURE_AI_MODEL_DEPLOYMENT_NAME} reads the model deployment `azd ai agent init` recorded
+        # in the active azd environment. Without it the container falls back to the default model
+        # name hardcoded in Program.cs, which may not exist in the target project.
+        #
+        # The listen port is not set here: the Dockerfile already sets ASPNETCORE_URLS.
+        env:
+            AZURE_AI_MODEL_DEPLOYMENT_NAME: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
+        container:
+            resources:
+                cpu: "0.5"
+                memory: 1Gi
+        description: |
+            A simple general-purpose AI assistant hosted as a Foundry Hosted Agent, deployed as a container image.
+        kind: hosted
+        metadata:
+            tags:
+                - AI Agent Hosting
+                - Azure AI AgentServer
+                - Responses Protocol
+                - Streaming
+                - Agent Framework
+        name: hosted-chat-client-agent-docker
+        protocols:
+            - protocol: responses
+              version: 2.0.0

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/.agentignore

@@ -0,0 +1,30 @@
+# Controls which files are excluded from the code-deploy ZIP upload (.gitignore syntax).
+# Note: only the root .agentignore is read; subdirectory files are not supported.
+#
+# To include a file that is excluded by default, use negation: !filename
+
+# azd tooling files
+azure.yaml
+.agentignore
+
+# Security / secrets
+.env
+.env.*
+.azure/
+.git/
+
+# .NET build output
+bin/
+obj/
+*.user
+*.suo
+.vs/
+
+# Agent session state written by FileSystemAgentSessionStore during local runs. The hosted
+# runtime writes its own under the container's home directory, so uploading the local copy
+# would ship stale sessions with the agent.
+.checkpoints/
+
+# Contributor mode (scripts/Add-LocalFrameworkFeed.ps1) generates local-feed/ and nuget.config.
+# Those are deliberately NOT excluded: the server-side restore needs them to resolve the Agent
+# Framework from the packages shipped in this upload instead of nuget.org.

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

@@ -1,6 +1,17 @@
+# Foundry project endpoint (shape: https://<host>/api/projects/<project>)
 FOUNDRY_PROJECT_ENDPOINT=<your-azure-ai-project-endpoint>
+
+# Model deployment name in your Foundry project.
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+
+# Local development only. Bind the app to the port Foundry probes for readiness, which is the
+# port the Using-Samples REPLs expect. Recent Microsoft.Agents.AI.Foundry.Hosting versions bind
+# it themselves, so this only matters while the project is pinned to an older published package.
 ASPNETCORE_URLS=http://+:8088
-ASPNETCORE_ENVIRONMENT=Development
-FOUNDRY_MODEL=gpt-4o
-AGENT_NAME=hosted-chat-client-agent
-AZURE_BEARER_TOKEN=DefaultAzureCredential
+
+# Local development only. Restrict DefaultAzureCredential to developer credentials
+# (Azure CLI, Visual Studio, azd) and skip the Managed Identity probe. Without this,
+# on a machine with no managed identity DefaultAzureCredential hangs for a long time
+# probing the IMDS endpoint (169.254.169.254) before every model call. Not set in
+# Foundry, where the platform-injected managed identity is used.
+AZURE_TOKEN_CREDENTIALS=dev

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

@@ -1,17 +0,0 @@
-# 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

@@ -1,19 +0,0 @@
-# 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

@@ -1,33 +1,47 @@
-<Project Sdk="Microsoft.NET.Sdk.Web">
+<Project>
+
+  <!--
+    Source (ZIP) deploy sample. The code-deploy upload is a flat folder with no repo-level props,
+    so this project is intentionally self-contained: a single target framework and explicit package
+    versions. Foundry runs `dotnet restore` + `dotnet publish` on it during provisioning
+    (dependencyResolution: remote_build in azure.yaml).
+
+    ImportDirectoryPackagesProps has to be set before the SDK props are imported, hence the explicit
+    Sdk imports below instead of the usual Sdk attribute on the Project element. It stops MSBuild
+    from walking up to the repository's dotnet/Directory.Packages.props, which does two things this
+    sample must avoid: it turns on central package management, and it injects analyzer
+    PackageReference items whose versions it also supplies. Neither exists inside the ZIP, so
+    without this the in-repo build would resolve differently from the server-side build.
+  -->
 
   <PropertyGroup>
-    <TargetFrameworks>net10.0</TargetFrameworks>
+    <ImportDirectoryPackagesProps>false</ImportDirectoryPackagesProps>
+  </PropertyGroup>
+
+  <Import Project="Sdk.props" Sdk="Microsoft.NET.Sdk.Web" />
+
+  <PropertyGroup>
+    <!-- Single target: the Foundry dotnet_10 runtime publishes without -f, so the
+         project must not multi-target. The empty TargetFrameworks clears the value
+         inherited from the repo's samples Directory.Build.props for in-repo builds. -->
+    <TargetFramework>net10.0</TargetFramework>
+    <TargetFrameworks></TargetFrameworks>
     <Nullable>enable</Nullable>
     <ImplicitUsings>enable</ImplicitUsings>
-    <CentralPackageTransitivePinningEnabled>false</CentralPackageTransitivePinningEnabled>
     <RootNamespace>HostedChatClientAgent</RootNamespace>
     <AssemblyName>HostedChatClientAgent</AssemblyName>
-    <NoWarn>$(NoWarn);</NoWarn>
+    <UserSecretsId>222d2622-da26-4da0-99b4-0507fb8d41b0</UserSecretsId>
+    <AgentFrameworkVersion>1.15.0-preview.260722.1</AgentFrameworkVersion>
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="DotNetEnv" />
+    <PackageReference Include="Microsoft.Agents.AI.Foundry" Version="$(AgentFrameworkVersion)" />
+    <PackageReference Include="Microsoft.Agents.AI.Foundry.Hosting" Version="$(AgentFrameworkVersion)" />
+    <PackageReference Include="Azure.AI.Projects" Version="2.1.0-beta.4" />
+    <PackageReference Include="Azure.Identity" Version="1.21.0" />
+    <PackageReference Include="DotNetEnv" Version="3.1.1" />
   </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="..\Hosted_Shared_Contributor_Setup\Hosted_Shared_Contributor_Setup.csproj" />
-  </ItemGroup>
-
-  <!-- For end-users: uncomment the PackageReference below and remove the ProjectReference above
-  <ItemGroup>
-    <PackageReference Include="Microsoft.Agents.AI.Foundry" Version="1.6.1-preview.260514.1" />
-    <PackageReference Include="Microsoft.Agents.AI.Foundry.Hosting" Version="1.6.1-preview.260514.1" />
-    <PackageReference Include="Azure.AI.Projects" />
-    <PackageReference Include="Azure.Identity" />
-  </ItemGroup>
-  -->
+  <Import Project="Sdk.targets" Sdk="Microsoft.NET.Sdk.Web" />
 
 </Project>

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

@@ -1,36 +1,39 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+// Sample: a minimal general-purpose AI assistant hosted as a Foundry Hosted Agent
+// using the Responses protocol. It is deployed to Foundry directly from source
+// (code / ZIP upload), so the platform builds and runs it with no container image.
+
 using Azure.AI.Projects;
-using Azure.Core;
 using Azure.Identity;
 using DotNetEnv;
-using Hosted_Shared_Contributor_Setup;
 using Microsoft.Agents.AI;
 using Microsoft.Agents.AI.Foundry.Hosting;
 
-// Load .env file if present (for local development)
+// Load a local .env file when present (local development only). In Foundry the
+// platform injects the required environment variables at runtime.
 Env.TraversePath().Load();
 
-var projectEndpoint = new Uri(Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
+var projectEndpoint = new Uri(System.Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
     ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set."));
 
-var agentName = Environment.GetEnvironmentVariable("AGENT_NAME") ?? "hosted-chat-client-agent";
+// Environment variables can arrive set but blank: azd substitutes an empty string when the azd
+// environment does not define the variable referenced from azure.yaml. An empty string is not
+// null, so a plain ?? chain would pass the blank straight through and fail deep inside the SDK.
+var model = FirstNonBlank(
+    System.Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME"),
+    System.Environment.GetEnvironmentVariable("FOUNDRY_MODEL"),
+    "gpt-4o");
 
-var deployment = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-4o";
+var agentName = System.Environment.GetEnvironmentVariable("AGENT_NAME") ?? "hosted-chat-client-agent";
 
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-// 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)
+// WARNING: DefaultAzureCredential is convenient for development but requires careful
+// consideration in production. Consider a specific credential (for example
+// ManagedIdentityCredential) to avoid latency, unintended credential probing, and
+// fallback security risks.
+AIAgent agent = new AIProjectClient(projectEndpoint, new DefaultAzureCredential())
     .AsAIAgent(
-        model: deployment,
+        model: model,
         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,
@@ -40,16 +43,15 @@ AIAgent agent = new AIProjectClient(projectEndpoint, credential)
         name: agentName,
         description: "A simple general-purpose AI assistant");
 
-// Host the agent as a Foundry Hosted Agent using the Responses API.
+// Host the agent using the Responses protocol.
 var builder = WebApplication.CreateBuilder(args);
 builder.Services.AddFoundryResponses(agent);
 
 var app = builder.Build();
 app.MapFoundryResponses();
 
-// Contributor-only: in Development, also map the per-agent OpenAI route shape that live Foundry uses
-// so a local REPL client can target this server via AIProjectClient.AsAIAgent(Uri agentEndpoint).
-// Do not use this in production. Hosted Foundry agents only support the agent-endpoint path.
-app.MapDevTemporaryLocalAgentEndpoint();
-
 app.Run();
+
+// Returns the first candidate that has an actual value, ignoring null and blank entries.
+static string FirstNonBlank(params string?[] candidates) =>
+    Array.Find(candidates, c => !string.IsNullOrWhiteSpace(c))!;

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

@@ -1,135 +1,303 @@
-# Hosted-ChatClientAgent
+# 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.
+A minimal general-purpose AI assistant hosted as a Foundry Hosted Agent using the Responses protocol. The agent is created inline via `AIProjectClient.AsAIAgent(model, instructions)` and served with `AddFoundryResponses` / `MapFoundryResponses`.
+
+This sample deploys to Foundry **directly from source (code / ZIP upload)**: the platform builds and runs your code with no container image, so there is no Dockerfile to author or container registry to manage.
+
+The sibling [`Hosted-ChatClientAgent-Dockerfile`](../Hosted-ChatClientAgent-Dockerfile/) sample is the same agent deployed the other way, as a container image built from a `Dockerfile`. Source deploy is the default for .NET, so start here and switch only if you need control over the runtime image.
 
 ## Prerequisites
 
 - [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
-- A Foundry project with a deployed model (e.g., `gpt-4o`)
+- An **existing** Foundry project with an **existing** model deployment (for example `gpt-4o`).
+  This sample's `azure.yaml` declares no `deployments:` block, so `azd` connects to a project and
+  a deployment you already have rather than creating them. `azd ai agent init` prompts you to pick
+  the project, and takes the deployment name as the `-d` argument.
 - Azure CLI logged in (`az login`)
+- Azure Developer CLI (`azd`) with the AI agents extension: `azd extension install azure.ai.agents`
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `Program.cs` | The agent: builds the agent, hosts it with the Responses protocol. |
+| `azure.yaml` | The unified `azd` project file. Declares the Foundry project and the hosted agent with `codeConfiguration` (source/ZIP deploy), and passes the listen port and the model deployment name to the container through `env`. |
+| `.agentignore` | Controls which files are excluded from the code-deploy ZIP upload (`.gitignore` syntax). |
+| `HostedChatClientAgent.csproj` | Self-contained project: single target framework and explicit package versions. It also opts out of the repository's central package management, which does not travel inside the ZIP. |
+| `.env.example` | Template for local configuration. |
+| `../../scripts/Add-LocalFrameworkFeed.ps1`, `../../scripts/add-local-framework-feed.sh` | Contributor-only helpers, see [Deploy your local framework changes](#deploy-your-local-framework-changes-contributors). |
 
 ## Configuration
 
 Copy the template and fill in your project endpoint:
 
+PowerShell:
+
+```powershell
+copy .env.example .env
+```
+
+Bash:
+
 ```bash
 cp .env.example .env
 ```
 
-Edit `.env` and set your Foundry project endpoint:
-
 ```env
 FOUNDRY_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
 ASPNETCORE_URLS=http://+:8088
-ASPNETCORE_ENVIRONMENT=Development
-FOUNDRY_MODEL=gpt-4o
+AZURE_TOKEN_CREDENTIALS=dev
 ```
 
-> **Note:** `.env` is gitignored. The `.env.example` template is checked in as a reference.
+> `.env` is gitignored. The `.env.example` template is checked in as a reference.
 
-## Running directly (contributors)
+> `ASPNETCORE_URLS` pins the local run to the port the `Using-Samples` REPLs expect. Recent
+> `Microsoft.Agents.AI.Foundry.Hosting` versions bind that port themselves, so it only matters
+> while this project is pinned to an older published package.
 
-This project uses `ProjectReference` to build against the local Agent Framework source.
+> **Windows note:** write `.env` as UTF-8 **without** a byte order mark. `azd` reads the file
+> during `azd ai agent init` and fails with `unexpected character "»" in variable name` when a mark
+> is present. PowerShell's `Set-Content -Encoding UTF8BOM` adds one; use `-Encoding utf8NoBOM`.
 
-```bash
+> **Local development on a machine without a managed identity:** set `AZURE_TOKEN_CREDENTIALS=dev`.
+> `Program.cs` authenticates with `DefaultAzureCredential` (the pattern the hosted platform
+> expects, where a managed identity is injected). On a developer machine with no managed identity,
+> `DefaultAzureCredential` probes the Azure Instance Metadata Service (IMDS, `169.254.169.254`) and
+> blocks for a long time on the network timeout before every model call, so requests appear to
+> hang. Setting `AZURE_TOKEN_CREDENTIALS=dev` restricts `DefaultAzureCredential` to developer
+> credentials (Azure CLI, Visual Studio, `azd`) and skips the managed-identity probe. This variable
+> is only for local runs; the deployed agent in Foundry uses the platform-injected managed identity.
+
+## Run and test locally
+
+Local runs use two terminals: one hosts the agent, the other is a code-first client that talks to it
+using Agent Framework components, see the sibling [`Using-Samples`](../Using-Samples/) REPLs.
+
+`AddFoundryResponses` binds the app to the port Foundry probes for readiness (8088 by default,
+overridable with the `PORT` environment variable), and `MapFoundryResponses` serves the standard
+`POST /responses` route. That is the same route the platform routes to for a deployed agent, so the
+local server needs no extra wiring: the client just points an OpenAI responses client at
+`http://localhost:8088`.
+
+**Terminal 1 — host the agent:**
+
+```
 cd dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent
+az login
 dotnet run
 ```
 
-The agent will start on `http://localhost:8088`.
+The agent starts on `http://localhost:8088`.
 
-### Test it
+**Terminal 2 — chat with it (code-first REPL):**
 
-Using the Azure Developer CLI:
+PowerShell:
 
-```bash
-azd ai agent invoke --local "Hello!"
+```powershell
+cd dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent
+$env:AZURE_AI_AGENT_NAME = "hosted-chat-client-agent"
+dotnet run -- --local
 ```
 
-Or with curl (specifying the agent name explicitly):
+Bash:
 
 ```bash
-curl -X POST http://localhost:8088/responses \
-  -H "Content-Type: application/json" \
-  -d '{"input": "Hello!", "model": "hosted-chat-client-agent"}'
+cd dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent
+export AZURE_AI_AGENT_NAME="hosted-chat-client-agent"
+dotnet run -- --local
 ```
 
-## Running with Docker
+Without `--local` the REPL asks which agent to chat with; choose **2 (Local)**. Either way it
+points an OpenAI responses client at the local server and streams the reply.
 
-Since this project uses `ProjectReference`, the standard `Dockerfile` cannot resolve dependencies outside this folder. Use `Dockerfile.contributor` which takes a pre-published output.
+## Deploy to Foundry (source / ZIP)
 
-### 1. Publish for the container runtime (Linux Alpine)
+`azd` scaffolds the project into a working folder, so every step below runs from an **empty
+directory outside the repository**, and `-m` points at this sample's `azure.yaml`.
 
-```bash
-dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+### Step 1: create the working directory and enter it
+
+PowerShell:
+
+```powershell
+$work = Join-Path $env:TEMP "hosted-chat-work"
+mkdir $work
+cd $work
 ```
 
-### 2. Build the Docker image
+Bash:
 
 ```bash
-docker build -f Dockerfile.contributor -t hosted-chat-client-agent .
+WORK="${TMPDIR:-/tmp}/hosted-chat-work"
+mkdir -p "$WORK"
+cd "$WORK"
 ```
 
-### 3. Run the container
+### Step 2: scaffold the project
 
-Generate a bearer token on your host and pass it to the container:
+`azd ai agent init` copies the sample into a subfolder named after the top-level `name:` in
+`azure.yaml`, which is `hosted-chat-client-agent`. It also writes the adopted `azure.yaml` and the
+`azd` environment there.
 
-```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)
+`azd ai agent init` prompts you to pick the Foundry project, so no project argument is needed.
+`-d` is the name of an existing model deployment in that project; omit it and `azd` prompts for
+that too.
 
-# 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
+> Pick an **existing** project at the prompt. The prompt needs an interactive terminal: run
+> non-interactively (in CI, for example) and `azd` skips it and provisions a brand new Foundry
+> project and resource group instead. Pass `-p <project-resource-id>` when you need that to be
+> unattended.
+
+`azure.yaml` passes the model deployment to the container by reading it from the `azd` environment.
+Confirm it landed there, and set it yourself if it did not:
+
+```
+azd env get-values
+azd env set AZURE_AI_MODEL_DEPLOYMENT_NAME <model-deployment>
 ```
 
-> **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.
+PowerShell:
 
-### 4. Test it
+```powershell
+$sample = "<repo>/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/azure.yaml"
 
-Using the Azure Developer CLI:
-
-```bash
-azd ai agent invoke --local "Hello!"
+azd auth login
+azd ai agent init -m $sample -d <model-deployment>
 ```
 
-Or with curl (specifying the agent name explicitly):
+Bash:
 
 ```bash
-curl -X POST http://localhost:8088/responses \
-  -H "Content-Type: application/json" \
-  -d '{"input": "Hello!", "model": "hosted-chat-client-agent"}'
+SAMPLE="<repo>/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/azure.yaml"
+
+azd auth login
+azd ai agent init -m "$SAMPLE" -d <model-deployment>
 ```
 
-## Deploying to Foundry (azd spec)
+### Step 3: provision and deploy
 
-This sample includes an `azd` manifest (`agent.manifest.yaml`) and hosted agent spec (`agent.yaml`) for deployment to Foundry.
+Contributors: if you are changing the Agent Framework source in this repository and want the
+deployed agent to run **your** build rather than the published packages, do the extra step in
+[Deploy your local framework changes](#deploy-your-local-framework-changes-contributors) now,
+before the commands below. Everyone else can ignore it.
 
-Initialize an `azd` project from this sample's manifest:
-
-```bash
-mkdir hosted-chat-client-agent && cd hosted-chat-client-agent
-azd ai agent init -m https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/agent.manifest.yaml
 ```
-
-Then deploy:
-
-```bash
+cd hosted-chat-client-agent
+azd provision
 azd deploy
+azd ai agent invoke "Hello!"
 ```
 
-If you need to override defaults, set deployment-time environment variables in the `azd` environment before deploying:
+`azd` packages the source into a ZIP (honoring `.agentignore`), uploads it, and Foundry runs
+`dotnet restore` + `dotnet publish` on it during provisioning (`dependencyResolution: remote_build`
+in `azure.yaml`). No Dockerfile, no container registry.
+
+You can also test the deployed agent with the REPL:
+
+PowerShell:
+
+```powershell
+cd <repo>/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent
+$env:FOUNDRY_PROJECT_ENDPOINT = "https://<your-account>.services.ai.azure.com/api/projects/<your-project>"
+$env:AZURE_AI_AGENT_NAME      = "hosted-chat-client-agent"
+dotnet run -- --remote
+```
+
+Bash:
 
 ```bash
-azd env set AGENT_NAME hosted-chat-client-agent
-azd env set AZURE_AI_MODEL_DEPLOYMENT_NAME gpt-4o
+cd <repo>/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent
+export FOUNDRY_PROJECT_ENDPOINT="https://<your-account>.services.ai.azure.com/api/projects/<your-project>"
+export AZURE_AI_AGENT_NAME="hosted-chat-client-agent"
+dotnet run -- --remote
 ```
 
-For end-to-end hosted agent deployment guidance, see the [official deployment guide](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent).
+### Step 4: clean up
 
-## NuGet package users
+```
+azd down
+```
 
-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.
+Then delete the working directory.
+
+## Deploy your local framework changes (contributors)
+
+**Skip this section unless you are changing the Agent Framework itself.** Everything above is the
+complete flow for using the sample. This section only applies when you are working on the framework
+source in this repository, or when you otherwise need a build of it that is not published on
+nuget.org.
+
+The reason it exists: the project restores the **published** Agent Framework packages, and Foundry
+restores from nuget.org when it builds the upload. So editing framework source in this repository
+changes nothing about the deployed agent, no matter how many times you rebuild locally. The
+uploaded folder is self-contained and knows nothing about your working tree.
+
+The extra step packs your local framework source into NuGet packages and puts them **inside the
+upload**, together with a `nuget.config` that points the restore at them. The server-side restore
+then resolves the framework from the packages you shipped instead of from nuget.org.
+
+Run it in the flow above, **between step 2 and step 3**. Nothing else changes.
+
+Run it from `$work`, the working directory created in step 1, which now holds the
+`hosted-chat-client-agent` folder that `azd ai agent init` scaffolded:
+
+PowerShell:
+
+```powershell
+cd $work
+<repo>/dotnet/samples/04-hosting/FoundryHostedAgents/scripts/Add-LocalFrameworkFeed.ps1 -Path ./hosted-chat-client-agent
+```
+
+Bash:
+
+```bash
+cd "$WORK"
+<repo>/dotnet/samples/04-hosting/FoundryHostedAgents/scripts/add-local-framework-feed.sh ./hosted-chat-client-agent
+```
+
+Then continue with step 3. The path argument is optional: called without it, the script uses the
+current directory, so you can also run it from inside `hosted-chat-client-agent`.
+
+The script changes three things in the scaffolded folder:
+
+| Change | Detail |
+|--------|--------|
+| Creates `local-feed/` | The Agent Framework packed from your local source, stamped with a version like `1.15.0-preview-local.<timestamp>` |
+| Creates `nuget.config` | Resolves `Microsoft.Agents.AI*` from that folder and everything else from nuget.org |
+| Edits the `.csproj` | Repoints its `AgentFrameworkVersion` property at the version just packed |
+
+Both generated files ship inside the ZIP, so the server-side restore resolves the framework from
+the upload. The scaffolded folder is a throwaway copy, so the repository is left untouched.
+
+Two details worth knowing:
+
+- The version carries a timestamp because NuGet caches by package id and version. Reusing a version
+  would silently restore the previously packed bits instead of the build you just made.
+- The whole package closure is packed, not just the two packages the sample references. Packing
+  only the leaf packages lets NuGet fill the rest from nuget.org, mixing a published core with a
+  locally built host, which fails to compile.
+
+Before spending a deploy, build the scaffolded folder locally. A restore problem surfaces in
+seconds instead of after the server-side build:
+
+```
+cd hosted-chat-client-agent
+dotnet build -c Debug --tl:off
+```
+
+## Troubleshooting
+
+**`azd ai agent invoke` fails with `404 not_found: Conversation '<id>' not found`**
+
+`azd` saves the session and conversation per agent and reuses them on the next invoke. Once the
+agent is redeployed, deleted, or restarted, that saved conversation no longer exists on the server,
+so every following invoke fails even though the agent itself is healthy. Start a fresh one:
+
+```
+azd ai agent invoke --new-conversation "Hello!"
+```
+
+Add `--new-session` as well if the failure persists.
+
+For the full hosted-agent deployment guide, see the [official source-code deployment doc](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent-code).

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

@@ -1,28 +0,0 @@
-# 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: 2.0.0
-  resources:
-    cpu: "0.25"
-    memory: 0.5Gi
-parameters:
-  properties: []
-resources: []

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

@@ -1,9 +0,0 @@
-# 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: 2.0.0
-resources:
-  cpu: "0.25"
-  memory: 0.5Gi

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

@@ -0,0 +1,46 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json
+
+name: hosted-chat-client-agent
+services:
+    ai-project:
+        host: azure.ai.project
+    hosted-chat-client-agent:
+        project: .
+        host: azure.ai.agent
+        language: csharp
+        uses:
+            - ai-project
+        codeConfiguration:
+            dependencyResolution: remote_build
+            entryPoint: HostedChatClientAgent.dll
+            runtime: dotnet_10
+        # ASPNETCORE_URLS pins the listen port. Source deploy runs this project as a plain ASP.NET
+        # app, and the .NET base image defaults it to port 80, while Foundry probes port 8088 for
+        # readiness, so without it every invoke fails with HTTP 424 session_not_ready. Recent
+        # Microsoft.Agents.AI.Foundry.Hosting versions bind the port themselves and take precedence
+        # over this value, so it only matters when the project is pinned to an older package.
+        #
+        # ${AZURE_AI_MODEL_DEPLOYMENT_NAME} reads the model deployment `azd ai agent init` recorded
+        # in the active azd environment. Without it the container falls back to the default model
+        # name hardcoded in Program.cs, which may not exist in the target project.
+        env:
+            ASPNETCORE_URLS: http://+:8088
+            AZURE_AI_MODEL_DEPLOYMENT_NAME: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
+        container:
+            resources:
+                cpu: "0.5"
+                memory: 1Gi
+        description: |
+            A simple general-purpose AI assistant hosted as a Foundry Hosted Agent using the Agent Framework instance hosting pattern.
+        kind: hosted
+        metadata:
+            tags:
+                - AI Agent Hosting
+                - Azure AI AgentServer
+                - Responses Protocol
+                - Streaming
+                - Agent Framework
+        name: hosted-chat-client-agent
+        protocols:
+            - protocol: responses
+              version: 2.0.0

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

@@ -145,3 +145,17 @@ If you are consuming the Agent Framework as a NuGet package (not building from s
 | **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 |
+
+## Troubleshooting
+
+**`azd ai agent invoke` fails with `404 not_found: Conversation '<id>' not found`**
+
+`azd` saves the session and conversation per agent and reuses them on the next invoke. Once the
+agent is redeployed, deleted, or restarted, that saved conversation no longer exists on the server,
+so every following invoke fails even though the agent itself is healthy. Start a fresh one:
+
+```
+azd ai agent invoke --new-conversation "Hello!"
+```
+
+Add `--new-session` as well if the failure persists.

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

@@ -157,3 +157,17 @@ 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 `HostedLocalCodeAct.csproj` for the `PackageReference`
 alternative.
+
+## Troubleshooting
+
+**`azd ai agent invoke` fails with `404 not_found: Conversation '<id>' not found`**
+
+`azd` saves the session and conversation per agent and reuses them on the next invoke. Once the
+agent is redeployed, deleted, or restarted, that saved conversation no longer exists on the server,
+so every following invoke fails even though the agent itself is healthy. Start a fresh one:
+
+```
+azd ai agent invoke --new-conversation "Hello!"
+```
+
+Add `--new-session` as well if the failure persists.

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

@@ -139,3 +139,17 @@ For end-to-end hosted agent deployment guidance, see the [official deployment gu
 ## 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.
+
+## Troubleshooting
+
+**`azd ai agent invoke` fails with `404 not_found: Conversation '<id>' not found`**
+
+`azd` saves the session and conversation per agent and reuses them on the next invoke. Once the
+agent is redeployed, deleted, or restarted, that saved conversation no longer exists on the server,
+so every following invoke fails even though the agent itself is healthy. Start a fresh one:
+
+```
+azd ai agent invoke --new-conversation "Hello!"
+```
+
+Add `--new-session` as well if the failure persists.

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

@@ -115,3 +115,16 @@ Use the standard `Dockerfile` instead of `Dockerfile.contributor`. See the comme
 - [`Hosted-Toolbox/`](../Hosted-Toolbox/) — connects to a single Foundry Toolbox via the AF Foundry hosting bridge (`AddFoundryToolboxes` + `FoundryAITool.CreateHostedMcpToolbox`).
 - [`Hosted-Toolbox-AuthPaths/`](../Hosted-Toolbox-AuthPaths/) — same hosting bones as `Hosted-Toolbox/`, but the toolbox bundles three MCP tools each authenticated differently (key, Entra agent identity, inline `Authorization`), driven by the shared `Using-Samples/SimpleAgent/` REPL.
 
+## Troubleshooting
+
+**`azd ai agent invoke` fails with `404 not_found: Conversation '<id>' not found`**
+
+`azd` saves the session and conversation per agent and reuses them on the next invoke. Once the
+agent is redeployed, deleted, or restarted, that saved conversation no longer exists on the server,
+so every following invoke fails even though the agent itself is healthy. Start a fresh one:
+
+```
+azd ai agent invoke --new-conversation "Hello!"
+```
+
+Add `--new-session` as well if the failure persists.

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

@@ -135,3 +135,17 @@ For end-to-end hosted agent deployment guidance, see the [official deployment gu
 ## NuGet package users
 
 If consuming the Agent Framework as a NuGet package, use the standard `Dockerfile` instead of `Dockerfile.contributor`. See the commented section in `HostedObservability.csproj` for the `PackageReference` alternative.
+
+## Troubleshooting
+
+**`azd ai agent invoke` fails with `404 not_found: Conversation '<id>' not found`**
+
+`azd` saves the session and conversation per agent and reuses them on the next invoke. Once the
+agent is redeployed, deleted, or restarted, that saved conversation no longer exists on the server,
+so every following invoke fails even though the agent itself is healthy. Start a fresh one:
+
+```
+azd ai agent invoke --new-conversation "Hello!"
+```
+
+Add `--new-session` as well if the failure persists.

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

@@ -142,3 +142,17 @@ For end-to-end hosted agent deployment guidance, see the [official deployment gu
 ## 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.
+
+## Troubleshooting
+
+**`azd ai agent invoke` fails with `404 not_found: Conversation '<id>' not found`**
+
+`azd` saves the session and conversation per agent and reuses them on the next invoke. Once the
+agent is redeployed, deleted, or restarted, that saved conversation no longer exists on the server,
+so every following invoke fails even though the agent itself is healthy. Start a fresh one:
+
+```
+azd ai agent invoke --new-conversation "Hello!"
+```
+
+Add `--new-session` as well if the failure persists.

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

@@ -190,6 +190,7 @@ Send a test email to myself.                                      # path #4 —
 | **HTTP 404 from a tool call** | Toolbox name mismatch (`TOOLBOX_NAME` vs the name in the portal), or the toolbox was deleted. |
 | **Server logs a warning "Neither FOUNDRY_PROJECT_ENDPOINT nor AZURE_AI_PROJECT_ENDPOINT is set; toolbox support is disabled"** | Local dev without the env var set. The agent will load with zero tools and respond as if it has none. Set `AZURE_AI_PROJECT_ENDPOINT` (local-dev fallback) or `FOUNDRY_PROJECT_ENDPOINT` to your project endpoint. |
 | **Tools appear but model never invokes them** | `instructions:` in `Program.cs` may not surface what each tool is for. Tighten the `allowed_tools` lists and rephrase prompts to mention the upstream service by name. |
+| **`azd ai agent invoke` returns `404 not_found: Conversation '<id>' not found`** | `azd` saves the session and conversation per agent and reuses them on the next invoke. Once the agent is redeployed, deleted, or restarted, that saved conversation no longer exists on the server. Pass `--new-conversation` (and `--new-session` if it persists) to start a fresh one. |
 
 ## Region and model compatibility
 

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

@@ -109,3 +109,17 @@ Use the standard `Dockerfile` instead of `Dockerfile.contributor`. See the comme
 
 - [`Hosted-Toolbox-AuthPaths/`](../Hosted-Toolbox-AuthPaths/) — same hosting bones as this sample, but the toolbox bundles three MCP tools each authenticated differently (key, Entra agent identity, inline `Authorization`), driven by the shared `Using-Samples/SimpleAgent/` REPL.
 - [`Hosted-McpTools/`](../Hosted-McpTools/) — contrasts client-side `McpClient` vs server-side `HostedMcpServerTool` for non-toolbox MCP servers.
+
+## Troubleshooting
+
+**`azd ai agent invoke` fails with `404 not_found: Conversation '<id>' not found`**
+
+`azd` saves the session and conversation per agent and reuses them on the next invoke. Once the
+agent is redeployed, deleted, or restarted, that saved conversation no longer exists on the server,
+so every following invoke fails even though the agent itself is healthy. Start a fresh one:
+
+```
+azd ai agent invoke --new-conversation "Hello!"
+```
+
+Add `--new-session` as well if the failure persists.

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

@@ -129,3 +129,17 @@ For end-to-end hosted agent deployment guidance, see the [official deployment gu
 ## 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 `HostedToolboxMcpSkills.csproj` for the `PackageReference` alternative.
+
+## Troubleshooting
+
+**`azd ai agent invoke` fails with `404 not_found: Conversation '<id>' not found`**
+
+`azd` saves the session and conversation per agent and reuses them on the next invoke. Once the
+agent is redeployed, deleted, or restarted, that saved conversation no longer exists on the server,
+so every following invoke fails even though the agent itself is healthy. Start a fresh one:
+
+```
+azd ai agent invoke --new-conversation "Hello!"
+```
+
+Add `--new-session` as well if the failure persists.

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

@@ -152,3 +152,17 @@ For end-to-end hosted agent deployment guidance, see the [official deployment gu
 ## NuGet package users
 
 Use the standard `Dockerfile` instead of `Dockerfile.contributor`. See the commented section in `HostedWorkflowHandoff.csproj` for the `PackageReference` alternative.
+
+## Troubleshooting
+
+**`azd ai agent invoke` fails with `404 not_found: Conversation '<id>' not found`**
+
+`azd` saves the session and conversation per agent and reuses them on the next invoke. Once the
+agent is redeployed, deleted, or restarted, that saved conversation no longer exists on the server,
+so every following invoke fails even though the agent itself is healthy. Start a fresh one:
+
+```
+azd ai agent invoke --new-conversation "Hello!"
+```
+
+Add `--new-session` as well if the failure persists.

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

@@ -135,3 +135,17 @@ For end-to-end hosted agent deployment guidance, see the [official deployment gu
 ## NuGet package users
 
 Use the standard `Dockerfile` instead of `Dockerfile.contributor`. See the commented section in `HostedWorkflowSimple.csproj` for the `PackageReference` alternative.
+
+## Troubleshooting
+
+**`azd ai agent invoke` fails with `404 not_found: Conversation '<id>' not found`**
+
+`azd` saves the session and conversation per agent and reuses them on the next invoke. Once the
+agent is redeployed, deleted, or restarted, that saved conversation no longer exists on the server,
+so every following invoke fails even though the agent itself is healthy. Start a fresh one:
+
+```
+azd ai agent invoke --new-conversation "Hello!"
+```
+
+Add `--new-session` as well if the failure persists.

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/README.md

@@ -28,10 +28,17 @@ just a matter of changing `AZURE_AI_AGENT_NAME`.
 
 ## Local HTTP dev
 
-When the target is a local `http://localhost:8088` dev server, the REPLs install a small
-`HttpSchemeRewritePolicy`: `AIProjectClient`/`BearerTokenPolicy` require HTTPS, so the client
-presents the endpoint as `https://` to satisfy the TLS check, then rewrites the scheme back to
-`http://` right before the request hits the wire. This is local-development only.
+`AIProjectClient` authenticates with a bearer token, and the client pipeline refuses to attach one
+to a plain `http://` endpoint, failing with `InvalidOperationException: Bearer token authentication
+is not permitted for non TLS protected (https) endpoints.` before the request is even sent. To
+target a local dev server over HTTP, the REPLs install a small `HttpSchemeRewritePolicy`: the
+client is pointed at an `https://` URI to satisfy that check, and the policy puts the scheme back
+to `http://` right before the request hits the wire. This is local-development only.
+
+`SimpleAgent` applies it only on the Foundry path, and only when `FOUNDRY_PROJECT_ENDPOINT` is an
+`http://` URL. Its `--local` path needs nothing of the sort: it points an `OpenAIClient` at the
+server's standard `POST /responses` route with an api key, which carries no bearer token and so
+never hits the TLS check.
 
 ## The clients
 

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent/Program.cs

@@ -1,43 +1,30 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using System.ClientModel;
 using System.ClientModel.Primitives;
 using Azure.AI.Projects;
 using Azure.Identity;
 using DotNetEnv;
 using Microsoft.Agents.AI;
-using Microsoft.Agents.AI.Foundry;
+using OpenAI;
+using OpenAI.Responses;
 
 // Load .env file if present (for local development)
 Env.TraversePath().Load();
 
-// FOUNDRY_PROJECT_ENDPOINT is the Foundry project endpoint. Shape:
-//   https://<host>/api/projects/<project>
-Uri projectEndpoint = new(Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
-    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set."));
+// Port the Hosted-* samples listen on when run locally with `dotnet run`.
+const int LocalAgentPort = 8088;
 
 // AZURE_AI_AGENT_NAME is the registered server-side agent name.
 string agentName = Environment.GetEnvironmentVariable("AZURE_AI_AGENT_NAME")
     ?? throw new InvalidOperationException("AZURE_AI_AGENT_NAME is not set.");
 
-// Derive the per-agent OpenAI endpoint that hosted Foundry agents require.
-Uri agentEndpoint = new($"{projectEndpoint}/agents/{agentName}/endpoint/protocols/openai");
+// Pick the server to talk to. `--local` and `--remote` mirror the flag `azd ai agent invoke`
+// exposes; with neither, ask at startup.
+bool useLocalAgent = ResolveTarget(args);
 
-// ── Create an agent-framework agent backed by the remote agent endpoint ──────
-
-var options = new AIProjectClientOptions();
-
-if (projectEndpoint.Scheme == "http")
-{
-    // For local HTTP dev: tell AIProjectClient the endpoint is HTTPS (to satisfy
-    // BearerTokenPolicy's TLS check), then swap the scheme back to HTTP right
-    // before the request hits the wire.
-    projectEndpoint = new UriBuilder(projectEndpoint) { Scheme = "https" }.Uri;
-    agentEndpoint = new UriBuilder(agentEndpoint) { Scheme = "https" }.Uri;
-    options.AddPolicy(new HttpSchemeRewritePolicy(), PipelinePosition.BeforeTransport);
-}
-
-var aiProjectClient = new AIProjectClient(projectEndpoint, new AzureCliCredential(), options);
-FoundryAgent agent = aiProjectClient.AsAIAgent(agentEndpoint);
+AIAgent agent = useLocalAgent ? CreateLocalAgent() : CreateHostedAgent(agentName);
+string target = useLocalAgent ? $"http://localhost:{LocalAgentPort}" : agentName;
 
 AgentSession session = await agent.CreateSessionAsync();
 
@@ -47,7 +34,7 @@ Console.ForegroundColor = ConsoleColor.Cyan;
 Console.WriteLine($"""
     ══════════════════════════════════════════════════════════
     Simple Agent Sample
-    Connected to: {agentEndpoint}
+    Connected to: {target}
     Type a message or 'quit' to exit
     ══════════════════════════════════════════════════════════
     """);
@@ -90,10 +77,76 @@ while (true)
 
 Console.WriteLine("Goodbye!");
 
+// Returns true when the client should target a locally running agent. `--local` and `--remote`
+// answer the question up front, which is what non-interactive runs need; with neither, ask.
+static bool ResolveTarget(string[] args)
+{
+    if (args.Contains("--local", StringComparer.OrdinalIgnoreCase)) { return true; }
+    if (args.Contains("--remote", StringComparer.OrdinalIgnoreCase)) { return false; }
+
+    return PromptForLocalTarget();
+}
+
+// Asks whether to target a locally running agent or the one deployed to Foundry, and returns
+// true for local. Defaults to remote on an empty answer, matching `azd ai agent invoke`, which
+// targets Foundry unless --local is passed.
+static bool PromptForLocalTarget()
+{
+    Console.ForegroundColor = ConsoleColor.Cyan;
+    Console.WriteLine("Which agent do you want to chat with?");
+    Console.ResetColor();
+    Console.WriteLine("  [1] Foundry (deployed agent)   [default]");
+    Console.WriteLine($"  [2] Local    (dotnet run, http://localhost:{LocalAgentPort})");
+    Console.Write("Choice: ");
+
+    string? choice = Console.ReadLine()?.Trim();
+    Console.WriteLine();
+
+    return choice is "2";
+}
+
+// Builds an agent against a Hosted-* sample running locally. The sample serves the standard
+// Responses route (POST /responses), so an OpenAI responses client pointed at the server reaches
+// it directly. The server hosts its own agent and ignores both the model id and the api key, but
+// the SDK requires them to shape the request.
+static AIAgent CreateLocalAgent()
+{
+    var options = new OpenAIClientOptions { Endpoint = new Uri($"http://localhost:{LocalAgentPort}") };
+
+    return new OpenAIClient(new ApiKeyCredential("not-needed"), options)
+        .GetResponsesClient()
+        .AsAIAgent(model: "hosted-agent", name: "LocalHostedAgent");
+}
+
+// Builds an agent against an agent deployed to Foundry. Hosted agents are reached through their
+// per-agent endpoint, which the platform routes to the container's /responses route.
+static AIAgent CreateHostedAgent(string agentName)
+{
+    Uri projectEndpoint = new(Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
+        ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set."));
+
+    Uri agentEndpoint = new($"{projectEndpoint}/agents/{agentName}/endpoint/protocols/openai");
+
+    var options = new AIProjectClientOptions();
+
+    if (projectEndpoint.Scheme == Uri.UriSchemeHttp)
+    {
+        // For local HTTP dev: the client pipeline refuses to attach a bearer token to a plain
+        // HTTP endpoint, so point the client at an https:// URI to satisfy that check, then swap
+        // the scheme back to http:// right before the request hits the wire.
+        projectEndpoint = new UriBuilder(projectEndpoint) { Scheme = Uri.UriSchemeHttps }.Uri;
+        agentEndpoint = new UriBuilder(agentEndpoint) { Scheme = Uri.UriSchemeHttps }.Uri;
+        options.AddPolicy(new HttpSchemeRewritePolicy(), PipelinePosition.BeforeTransport);
+    }
+
+    return new AIProjectClient(projectEndpoint, new AzureCliCredential(), options).AsAIAgent(agentEndpoint);
+}
+
 /// <summary>
-/// For Local Development Only
-/// Rewrites HTTPS URIs to HTTP right before transport, allowing AIProjectClient
-/// to target a local HTTP dev server while satisfying BearerTokenPolicy's TLS check.
+/// For Local Development Only.
+/// Rewrites HTTPS URIs to HTTP right before transport, allowing <see cref="AIProjectClient"/> to
+/// target a local HTTP dev server while satisfying the pipeline's TLS check: bearer tokens are
+/// only attached to TLS-protected endpoints, so a plain http:// endpoint is rejected outright.
 /// </summary>
 internal sealed class HttpSchemeRewritePolicy : PipelinePolicy
 {
@@ -114,7 +167,7 @@ internal sealed class HttpSchemeRewritePolicy : PipelinePolicy
         var uri = message.Request.Uri!;
         if (uri.Scheme == Uri.UriSchemeHttps)
         {
-            message.Request.Uri = new UriBuilder(uri) { Scheme = "http" }.Uri;
+            message.Request.Uri = new UriBuilder(uri) { Scheme = Uri.UriSchemeHttp }.Uri;
         }
     }
 }

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent/README.md

@@ -1,8 +1,7 @@
 # SimpleAgent
 
 A generic, agent-agnostic chat REPL for any hosted Foundry agent. Point it at a running
-`Hosted-*` agent via `AZURE_AI_AGENT_NAME`, and it builds a `FoundryAgent` against that agent's
-per-agent OpenAI endpoint and streams replies. This is the shared client that `Hosted-Toolbox`,
+`Hosted-*` agent and it streams replies. This is the shared client that `Hosted-Toolbox`,
 `Hosted-Toolbox-AuthPaths`, and `Hosted-McpTools` reference for their end-to-end demos.
 
 It knows nothing about the agent's tools, toolboxes, files, or auth — those are entirely the
@@ -18,29 +17,51 @@ See [`../README.md`](../README.md) for why these client REPLs exist at all.
 ## Configuration
 
 ```env
-FOUNDRY_PROJECT_ENDPOINT=https://<host>/api/projects/<project>
 AZURE_AI_AGENT_NAME=<registered-server-side-agent-name>
+FOUNDRY_PROJECT_ENDPOINT=https://<host>/api/projects/<project>
 ```
 
-Both are required. `FOUNDRY_PROJECT_ENDPOINT` is the Foundry project endpoint URL and
-`AZURE_AI_AGENT_NAME` is the registered server-side agent name. The sample builds the per-agent
-OpenAI endpoint URL (`{FOUNDRY_PROJECT_ENDPOINT}/agents/{AZURE_AI_AGENT_NAME}/endpoint/protocols/openai`)
-from these.
+`AZURE_AI_AGENT_NAME` is always required. `FOUNDRY_PROJECT_ENDPOINT` is the Foundry project
+endpoint URL, required only when you target the deployed agent.
 
 ## Run
 
-Against a local Hosted-Toolbox agent listening on `http://localhost:8088`:
-
 ```powershell
 cd dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent
-$env:FOUNDRY_PROJECT_ENDPOINT = "http://localhost:8088/api/projects/local"
-$env:AZURE_AI_AGENT_NAME = "hosted-toolbox-agent"
+$env:AZURE_AI_AGENT_NAME = "hosted-chat-client-agent"
 dotnet run
 ```
 
-When the project endpoint is `http://`, the client presents it as `https://` to satisfy the
-bearer-token TLS check, then rewrites the scheme back to `http://` right before transport
-(local-development only).
+On startup the client asks which agent to chat with:
+
+```text
+Which agent do you want to chat with?
+  [1] Foundry (deployed agent)   [default]
+  [2] Local    (dotnet run, http://localhost:8088)
+Choice:
+```
+
+Pass `--local` or `--remote` to answer up front and skip the prompt, which is what scripted runs
+need:
+
+```
+dotnet run -- --local
+dotnet run -- --remote
+```
+
+This mirrors the `--local` flag on `azd ai agent invoke`. Use local while a `Hosted-*` sample is
+running with `dotnet run`; use remote to reach the agent deployed to Foundry.
+
+The two choices differ only in how the agent is built:
+
+| Target | How the client reaches it |
+|--------|---------------------------|
+| Local | An `OpenAIClient` pointed at `http://localhost:8088`, then `GetResponsesClient().AsAIAgent(...)`. That hits the standard `POST /responses` route the local server already serves. The model id and api key are placeholders: the server runs its own agent and ignores both, but the SDK requires them to shape the request. |
+| Foundry | An `AIProjectClient` plus the agent's per-agent endpoint (`{projectEndpoint}/agents/{AZURE_AI_AGENT_NAME}/endpoint/protocols/openai`), which the platform routes to the container's `/responses` route. |
+
+The Foundry path also works against a local server that maps the per-agent route: set
+`FOUNDRY_PROJECT_ENDPOINT` to an `http://` URL and the client installs a scheme-rewrite policy so
+the bearer-token pipeline accepts it. See [Local HTTP dev](../README.md#local-http-dev).
 
 ## End-to-end demo
 
@@ -49,7 +70,7 @@ With a hosted agent running:
 ```text
 ══════════════════════════════════════════════════════════
 Simple Agent Sample
-Connected to: https://localhost:8088/api/projects/local/agents/hosted-toolbox-agent/endpoint/protocols/openai
+Connected to: http://localhost:8088
 Type a message or 'quit' to exit
 ══════════════════════════════════════════════════════════
 
@@ -61,3 +82,17 @@ Goodbye!
 ```
 
 The client only sent a chat prompt; the agent resolved its toolbox tools server-side and answered.
+
+## Troubleshooting
+
+**`azd ai agent invoke` fails with `404 not_found: Conversation '<id>' not found`**
+
+`azd` saves the session and conversation per agent and reuses them on the next invoke. Once the
+agent is redeployed, deleted, or restarted, that saved conversation no longer exists on the server,
+so every following invoke fails even though the agent itself is healthy. Start a fresh one:
+
+```
+azd ai agent invoke --new-conversation "Hello!"
+```
+
+Add `--new-session` as well if the failure persists.

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent/SimpleAgent.csproj

@@ -13,14 +13,15 @@
 
   <ItemGroup>
     <PackageReference Include="Azure.AI.Projects" />
-    <PackageReference Include="Azure.Core" />
     <PackageReference Include="Azure.Identity" />
     <PackageReference Include="DotNetEnv" />
+    <PackageReference Include="OpenAI" />
     <PackageReference Include="System.ClientModel" />
   </ItemGroup>
 
   <ItemGroup>
     <ProjectReference Include="..\..\..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
   </ItemGroup>
 
 </Project>

dotnet/samples/04-hosting/FoundryHostedAgents/scripts/Add-LocalFrameworkFeed.ps1

@@ -0,0 +1,157 @@
+#requires -Version 7
+<#
+.SYNOPSIS
+  Rewires an already-scaffolded hosted-agent folder to build against the local Agent Framework
+  source, so `azd deploy` ships your framework changes instead of the published packages.
+.DESCRIPTION
+  Source (ZIP) deploy uploads the agent folder and Foundry runs `dotnet restore` + `dotnet publish`
+  on it in the cloud. That restore pulls the Agent Framework from nuget.org, so a contributor's
+  local framework changes are never exercised.
+
+  Run this after `azd ai agent init` and before `azd provision`. It changes two things in the
+  folder that `init` scaffolded:
+
+    local-feed/    New. The Agent Framework packed from the local source tree, stamped with a
+                   version derived from the repo's current VersionPrefix plus a `-preview-local`
+                   suffix. The whole closure is packed: packing only the leaf packages lets NuGet
+                   fill the rest from nuget.org, mixing a published core with a locally built host.
+    nuget.config   New. Maps Microsoft.Agents.AI* to that folder feed and everything else to
+                   nuget.org.
+    the .csproj    Edited. Its AgentFrameworkVersion property is repointed at the version just
+                   packed.
+
+  Neither generated file is excluded by `.agentignore`, so they travel inside the ZIP and the
+  server-side restore uses them.
+
+  Everything else stays identical to the end-user flow: you create the working directory, run
+  `azd ai agent init`, and finish with `azd provision`, `azd deploy`, and `azd ai agent invoke`.
+  The scaffolded folder is a throwaway copy, so editing its project file leaves the repository
+  untouched.
+.PARAMETER Path
+  The folder `azd ai agent init` scaffolded, for example `./hosted-chat-client-agent`.
+  Defaults to the current directory.
+.EXAMPLE
+  # From the working directory, after azd ai agent init created ./hosted-chat-client-agent
+  <repo>/dotnet/samples/04-hosting/FoundryHostedAgents/scripts/Add-LocalFrameworkFeed.ps1 -Path ./hosted-chat-client-agent
+.EXAMPLE
+  # From inside the scaffolded folder
+  cd hosted-chat-client-agent
+  <repo>/dotnet/samples/04-hosting/FoundryHostedAgents/scripts/Add-LocalFrameworkFeed.ps1
+.NOTES
+  For contributors validating framework changes end to end. End users skip this script entirely and
+  get the published packages.
+#>
+
+[CmdletBinding()]
+param(
+    [string]$Path = '.'
+)
+
+$ErrorActionPreference = 'Stop'
+
+# The Agent Framework closure the hosted samples resolve. Packing only the leaf packages makes
+# NuGet satisfy the rest from nuget.org, producing assembly-reference errors at build time.
+$frameworkProjects = @(
+    'Microsoft.Agents.AI.Abstractions'
+    'Microsoft.Agents.AI'
+    'Microsoft.Agents.AI.Workflows'
+    'Microsoft.Agents.AI.Foundry'
+    'Microsoft.Agents.AI.Foundry.Hosting'
+)
+
+$target = (Resolve-Path $Path).Path
+
+if (-not (Test-Path (Join-Path $target 'azure.yaml'))) {
+    throw "No azure.yaml in '$target'. Point -Path at the folder 'azd ai agent init' scaffolded."
+}
+
+$projectFile = Get-ChildItem $target -Filter *.csproj -File | Select-Object -First 1
+if (-not $projectFile) {
+    throw "No .csproj in '$target'. This script targets .NET hosted agents."
+}
+
+if (-not (Select-String -Path $projectFile.FullName -Pattern '<AgentFrameworkVersion>' -Quiet)) {
+    throw "$($projectFile.Name) has no <AgentFrameworkVersion> property to repoint at a local build."
+}
+
+$hostedRoot = Split-Path -Parent $PSScriptRoot
+$dotnetRoot = (Resolve-Path (Join-Path $hostedRoot '..' '..' '..')).Path
+$srcRoot = Join-Path $dotnetRoot 'src'
+
+# Derive the package version from the repo so the packages track the current release line.
+# The timestamp keeps every run unique: NuGet caches by id and version, so reusing a version would
+# silently restore the previously packed bits instead of the build you just made. It also changes
+# the ZIP contents on every run, which matters because Foundry mints a new agent version only when
+# the uploaded ZIP changes.
+$packagePropsPath = Join-Path $dotnetRoot 'nuget' 'nuget-package.props'
+$versionMatch = Select-String -Path $packagePropsPath -Pattern '<VersionPrefix>(.+?)</VersionPrefix>' | Select-Object -First 1
+if (-not $versionMatch) {
+    throw "Could not read <VersionPrefix> from $packagePropsPath."
+}
+
+$versionPrefix = $versionMatch.Matches[0].Groups[1].Value
+$version = "$versionPrefix-preview-local.$(Get-Date -Format 'yyyyMMddHHmmss')"
+
+$feedPath = Join-Path $target 'local-feed'
+if (Test-Path $feedPath) { Remove-Item $feedPath -Recurse -Force }
+New-Item -ItemType Directory -Path $feedPath -Force | Out-Null
+
+Write-Host "Wiring $(Split-Path -Leaf $target) to the local Agent Framework" -ForegroundColor Cyan
+Write-Host "  version: $version"
+Write-Host ''
+
+foreach ($project in $frameworkProjects) {
+    $projectPath = Join-Path $srcRoot $project "$project.csproj"
+    Write-Host "Packing $project..."
+
+    # Debug, not Release: the Release configuration runs the repo's formatting and analyzer passes,
+    # which rewrite source files and fail the build on style violations. Packing only needs runnable
+    # binaries, so Debug keeps the working tree untouched.
+    #
+    # PackageVersion (not Version) is the property the repo's packaging props use to stamp both the
+    # package version and its dependency ranges, so the packed packages reference each other at this
+    # version instead of the bare VersionPrefix.
+    dotnet build $projectPath -c Debug -p:PackageVersion=$version --tl:off | Out-Null
+    if ($LASTEXITCODE -ne 0) { throw "Build failed for $project." }
+
+    dotnet pack $projectPath -c Debug --no-build -o $feedPath -p:PackageVersion=$version --tl:off | Out-Null
+    if ($LASTEXITCODE -ne 0) { throw "Pack failed for $project." }
+}
+
+$utf8NoBom = [System.Text.UTF8Encoding]::new($false)
+
+$nugetConfig = @'
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generated by Add-LocalFrameworkFeed.ps1: resolves the Agent Framework from this upload. -->
+<configuration>
+  <packageSources>
+    <clear />
+    <add key="local-feed" value="./local-feed" />
+    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
+  </packageSources>
+  <packageSourceMapping>
+    <packageSource key="local-feed">
+      <package pattern="Microsoft.Agents.AI*" />
+    </packageSource>
+    <packageSource key="nuget.org">
+      <package pattern="*" />
+    </packageSource>
+  </packageSourceMapping>
+</configuration>
+'@
+[System.IO.File]::WriteAllText((Join-Path $target 'nuget.config'), ($nugetConfig -replace "`r`n", "`n"), $utf8NoBom)
+
+# The scaffolded copy is disposable, so repointing its project file at the local build is safe and
+# keeps the checked-in sample free of contributor-only scaffolding. Reruns are safe: the pattern
+# matches whatever version is currently there.
+$projectXml = [System.IO.File]::ReadAllText($projectFile.FullName)
+$projectXml = $projectXml -replace '(?<open><AgentFrameworkVersion>)[^<]*(?<close></AgentFrameworkVersion>)', "`${open}$version`${close}"
+[System.IO.File]::WriteAllText($projectFile.FullName, $projectXml, [System.Text.UTF8Encoding]::new($true))
+
+Write-Host ''
+Write-Host 'Done. Continue with the standard flow:' -ForegroundColor Green
+Write-Host ''
+Write-Host "  cd `"$target`""
+Write-Host '  azd provision'
+Write-Host '  azd deploy'
+Write-Host '  azd ai agent invoke "Hello!"'

dotnet/samples/04-hosting/FoundryHostedAgents/scripts/add-local-framework-feed.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+#
+# Rewires an already-scaffolded hosted-agent folder to build against the local Agent Framework
+# source, so `azd deploy` ships your framework changes instead of the published packages.
+#
+# Source (ZIP) deploy uploads the agent folder and Foundry runs `dotnet restore` + `dotnet publish`
+# on it in the cloud. That restore pulls the Agent Framework from nuget.org, so a contributor's
+# local framework changes are never exercised.
+#
+# Run this after `azd ai agent init` and before `azd provision`. It changes two things in the
+# folder that `init` scaffolded:
+#
+#   local-feed/    New. The Agent Framework packed from the local source tree, stamped with a
+#                  version derived from the repo's current VersionPrefix plus a `-preview-local`
+#                  suffix. The whole closure is packed: packing only the leaf packages lets NuGet
+#                  fill the rest from nuget.org, mixing a published core with a locally built host.
+#   nuget.config   New. Maps Microsoft.Agents.AI* to that folder feed and everything else to
+#                  nuget.org.
+#   the .csproj    Edited. Its AgentFrameworkVersion property is repointed at the version just
+#                  packed.
+#
+# Neither generated file is excluded by `.agentignore`, so they travel inside the ZIP and the
+# server-side restore uses them.
+#
+# Everything else stays identical to the end-user flow: you create the working directory, run
+# `azd ai agent init`, and finish with `azd provision`, `azd deploy`, and `azd ai agent invoke`.
+# The scaffolded folder is a throwaway copy, so editing its project file leaves the repository
+# untouched.
+#
+# Usage:
+#   add-local-framework-feed.sh [path-to-scaffolded-folder]
+#
+# The path defaults to the current directory.
+#
+# This is the bash counterpart of Add-LocalFrameworkFeed.ps1. For contributors validating framework
+# changes end to end. End users skip this script entirely and get the published packages.
+
+set -euo pipefail
+
+# The Agent Framework closure the hosted samples resolve. Packing only the leaf packages makes
+# NuGet satisfy the rest from nuget.org, producing assembly-reference errors at build time.
+framework_projects=(
+    Microsoft.Agents.AI.Abstractions
+    Microsoft.Agents.AI
+    Microsoft.Agents.AI.Workflows
+    Microsoft.Agents.AI.Foundry
+    Microsoft.Agents.AI.Foundry.Hosting
+)
+
+target_input="${1:-.}"
+
+if [[ ! -d "$target_input" ]]; then
+    echo "Error: '$target_input' is not a directory." >&2
+    exit 1
+fi
+
+target="$(cd "$target_input" && pwd)"
+
+if [[ ! -f "$target/azure.yaml" ]]; then
+    echo "Error: no azure.yaml in '$target'. Point the path at the folder 'azd ai agent init' scaffolded." >&2
+    exit 1
+fi
+
+project_file="$(find "$target" -maxdepth 1 -name '*.csproj' | head -n 1)"
+
+if [[ -z "$project_file" ]]; then
+    echo "Error: no .csproj in '$target'. This script targets .NET hosted agents." >&2
+    exit 1
+fi
+
+if ! grep -q '<AgentFrameworkVersion>' "$project_file"; then
+    echo "Error: $(basename "$project_file") has no <AgentFrameworkVersion> property to repoint at a local build." >&2
+    exit 1
+fi
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+hosted_root="$(dirname "$script_dir")"
+dotnet_root="$(cd "$hosted_root/../../.." && pwd)"
+src_root="$dotnet_root/src"
+
+# Derive the package version from the repo so the packages track the current release line.
+# The timestamp keeps every run unique: NuGet caches by id and version, so reusing a version would
+# silently restore the previously packed bits instead of the build you just made. It also changes
+# the ZIP contents on every run, which matters because Foundry mints a new agent version only when
+# the uploaded ZIP changes.
+package_props="$dotnet_root/nuget/nuget-package.props"
+version_prefix="$(sed -n 's/.*<VersionPrefix>\([^<]*\)<\/VersionPrefix>.*/\1/p' "$package_props" | head -n 1)"
+
+if [[ -z "$version_prefix" ]]; then
+    echo "Error: could not read VersionPrefix from $package_props." >&2
+    exit 1
+fi
+
+version="$version_prefix-preview-local.$(date +%Y%m%d%H%M%S)"
+
+feed_path="$target/local-feed"
+rm -rf "$feed_path"
+mkdir -p "$feed_path"
+
+echo "Wiring $(basename "$target") to the local Agent Framework"
+echo "  version: $version"
+echo
+
+for project in "${framework_projects[@]}"; do
+    project_path="$src_root/$project/$project.csproj"
+    echo "Packing $project..."
+
+    # Debug, not Release: the Release configuration runs the repo's formatting and analyzer passes,
+    # which rewrite source files and fail the build on style violations. Packing only needs runnable
+    # binaries, so Debug keeps the working tree untouched.
+    #
+    # PackageVersion (not Version) is the property the repo's packaging props use to stamp both the
+    # package version and its dependency ranges, so the packed packages reference each other at this
+    # version instead of the bare VersionPrefix.
+    dotnet build "$project_path" -c Debug "-p:PackageVersion=$version" --tl:off >/dev/null
+    dotnet pack "$project_path" -c Debug --no-build -o "$feed_path" "-p:PackageVersion=$version" --tl:off >/dev/null
+done
+
+cat > "$target/nuget.config" <<'EOF'
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generated by add-local-framework-feed.sh: resolves the Agent Framework from this upload. -->
+<configuration>
+  <packageSources>
+    <clear />
+    <add key="local-feed" value="./local-feed" />
+    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
+  </packageSources>
+  <packageSourceMapping>
+    <packageSource key="local-feed">
+      <package pattern="Microsoft.Agents.AI*" />
+    </packageSource>
+    <packageSource key="nuget.org">
+      <package pattern="*" />
+    </packageSource>
+  </packageSourceMapping>
+</configuration>
+EOF
+
+# The scaffolded copy is disposable, so repointing its project file at the local build is safe and
+# keeps the checked-in sample free of contributor-only scaffolding. Reruns are safe: the pattern
+# matches whatever version is currently there. sed rewrites the line in place, leaving the file's
+# leading byte order mark untouched.
+sed -i.bak "s|<AgentFrameworkVersion>[^<]*</AgentFrameworkVersion>|<AgentFrameworkVersion>$version</AgentFrameworkVersion>|" "$project_file"
+rm -f "$project_file.bak"
+
+echo
+echo "Done. Continue with the standard flow:"
+echo
+echo "  cd \"$target\""
+echo "  azd provision"
+echo "  azd deploy"
+echo "  azd ai agent invoke \"Hello!\""

dotnet/src/Microsoft.Agents.AI.Foundry.Hosting/ServiceCollectionExtensions.cs

@@ -3,13 +3,16 @@
 using System;
 using System.ClientModel.Primitives;
 using System.Diagnostics.CodeAnalysis;
+using System.Globalization;
 using System.Linq;
 using System.Runtime.CompilerServices;
 using Azure.AI.AgentServer.Responses;
 using Azure.Core;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Routing;
+using Microsoft.AspNetCore.Server.Kestrel.Core;
 using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.DependencyInjection.Extensions;
 using Microsoft.Extensions.Diagnostics.HealthChecks;
@@ -54,6 +57,7 @@ public static class FoundryHostingExtensions
         ArgumentNullException.ThrowIfNull(services);
         services.AddResponsesServer();
         services.AddHealthChecks();
+        ConfigureFoundryListenPort(services);
         services.TryAddSingleton<AgentSessionStore>(_ => FileSystemAgentSessionStore.CreateDefault());
         services.TryAddSingleton<ResponseHandler, AgentFrameworkResponseHandler>();
         return services;
@@ -90,6 +94,7 @@ public static class FoundryHostingExtensions
 
         services.AddResponsesServer();
         services.AddHealthChecks();
+        ConfigureFoundryListenPort(services);
         agentSessionStore ??= FileSystemAgentSessionStore.CreateDefault();
 
         if (!string.IsNullOrWhiteSpace(agent.Name))
@@ -249,6 +254,104 @@ public static class FoundryHostingExtensions
         return endpoints;
     }
 
+    /// <summary>
+    /// Configuration key the Foundry hosting platform populates with a non-empty value inside a
+    /// hosted container. It is the documented way for container code to detect a Foundry context.
+    /// </summary>
+    internal const string FoundryHostingEnvironmentKey = "FOUNDRY_HOSTING_ENVIRONMENT";
+
+    /// <summary>
+    /// Configuration key holding the HTTP listen port, matching the Agent Server SDK.
+    /// </summary>
+    internal const string ListenPortKey = "PORT";
+
+    /// <summary>
+    /// Port the Foundry hosted runtime probes and routes to when <see cref="ListenPortKey"/> is
+    /// not set, matching <see cref="FoundryEnvironment.Port"/>.
+    /// </summary>
+    internal const int DefaultListenPort = 8088;
+
+    /// <summary>
+    /// Marker registered once per <see cref="IServiceCollection"/> so the Foundry listen-port
+    /// configuration is applied at most once, even across multiple <c>AddFoundryResponses</c> calls.
+    /// </summary>
+    private sealed class FoundryListenPortMarker;
+
+    /// <summary>
+    /// Binds Kestrel to the port the Foundry hosted runtime probes and routes to, so a plain
+    /// <c>WebApplication.CreateBuilder</c> host (Tier 3) works with no Dockerfile. Mirrors
+    /// <c>AgentHostBuilder</c>, which listens on the <c>PORT</c> value (default 8088).
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// The listener is added only when configuration reports a Foundry container through
+    /// <see cref="FoundryHostingEnvironmentKey"/>. A listener configured in code overrides the
+    /// addresses a host resolves from configuration, so adding it everywhere would silently move
+    /// any non-Foundry app off its configured address.
+    /// </para>
+    /// <para>
+    /// Both values come from <see cref="IConfiguration"/> rather than from
+    /// <see cref="FoundryEnvironment"/>, which caches every value in a static constructor. Reading
+    /// through configuration keeps the decision observable when the host is built, honours the
+    /// host's configuration sources, and lets tests supply values without mutating the process
+    /// environment.
+    /// </para>
+    /// <para>
+    /// Inside a Foundry container the listener cannot be skipped based on <c>ASPNETCORE_URLS</c>:
+    /// the .NET base image always sets it to port 80, so such a guard would always trip and leave
+    /// the container failing the readiness probe with HTTP 424. It cannot key off the presence of
+    /// <c>PORT</c> either, because the platform sets that value only when it needs a port other
+    /// than the default.
+    /// </para>
+    /// <para>
+    /// Idempotent, and harmless when no Kestrel server is present (for example under
+    /// <c>TestServer</c>): the <see cref="KestrelServerOptions"/> callback only runs when Kestrel
+    /// is resolved.
+    /// </para>
+    /// </remarks>
+    private static void ConfigureFoundryListenPort(IServiceCollection services)
+    {
+        if (services.Any(static d => d.ServiceType == typeof(FoundryListenPortMarker)))
+        {
+            return;
+        }
+
+        services.AddSingleton<FoundryListenPortMarker>();
+        services.AddOptions<KestrelServerOptions>()
+            .Configure<IConfiguration>(static (options, configuration) =>
+            {
+                if (string.IsNullOrEmpty(configuration[FoundryHostingEnvironmentKey]))
+                {
+                    return;
+                }
+
+                options.ListenAnyIP(ResolveListenPort(configuration));
+            });
+    }
+
+    /// <summary>
+    /// Reads the listen port from configuration, applying the same contract as
+    /// <see cref="FoundryEnvironment.Port"/>: <see cref="DefaultListenPort"/> when unset, otherwise
+    /// a port number in the range 1-65535.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">The configured value is not a valid port.</exception>
+    private static int ResolveListenPort(IConfiguration configuration)
+    {
+        var value = configuration[ListenPortKey];
+        if (string.IsNullOrEmpty(value))
+        {
+            return DefaultListenPort;
+        }
+
+        if (!int.TryParse(value, NumberStyles.Integer, CultureInfo.InvariantCulture, out var port) || port is < 1 or > 65535)
+        {
+            throw new InvalidOperationException(
+                $"The {ListenPortKey} environment variable value '{value}' is not a valid port number (1-65535).");
+        }
+
+        return port;
+    }
+
     /// <summary>
     /// Maps <c>GET /readiness</c> to the AspNetCore HealthChecks pipeline only when no
     /// route already serves that path. The duplicate guard scans

dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/Microsoft.Agents.AI.GitHub.Copilot.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <IsReleaseCandidate>true</IsReleaseCandidate>
+    <IsReleased>true</IsReleased>
     <!-- GitHub.Copilot.SDK only supports .NET 8.0+ -->
     <TargetFrameworks>$(TargetFrameworksCore)</TargetFrameworks>
     <NoWarn>$(NoWarn);GHCP001</NoWarn>
@@ -14,6 +14,12 @@
 
   <Import Project="$(RepoRoot)/dotnet/nuget/nuget-package.props" />
 
+  <!-- Disable package validation baseline until the first release -->
+  <PropertyGroup>
+    <PackageValidationBaselineVersion />
+    <EnablePackageValidation>false</EnablePackageValidation>
+  </PropertyGroup>
+
   <ItemGroup>
     <ProjectReference Include="..\Microsoft.Agents.AI.Abstractions\Microsoft.Agents.AI.Abstractions.csproj" />
   </ItemGroup>

dotnet/src/Microsoft.Agents.AI.Hosting.A2A/A2AAgentHandler.cs

@@ -20,6 +20,12 @@ namespace Microsoft.Agents.AI.Hosting.A2A;
 [Experimental(DiagnosticIds.Experiments.AIResponseContinuations)]
 internal sealed class A2AAgentHandler : IAgentHandler
 {
+    /// <summary>
+    /// The <see cref="AgentRunOptions.AdditionalProperties"/> key under which the caller supplied
+    /// <c>MessageSendParams.configuration</c> is forwarded to the hosted agent.
+    /// </summary>
+    private const string ConfigurationPropertyKey = "a2a.configuration";
+
     private readonly AIHostAgent _hostAgent;
     private readonly AgentRunMode _runMode;
 
@@ -84,9 +90,7 @@ internal sealed class A2AAgentHandler : IAgentHandler
         var decisionContext = new A2ARunDecisionContext(context);
         var allowBackgroundResponses = await this._runMode.ShouldRunInBackgroundAsync(decisionContext, cancellationToken).ConfigureAwait(false);
 
-        var options = context.Metadata is not { Count: > 0 }
-            ? new AgentRunOptions { AllowBackgroundResponses = allowBackgroundResponses }
-            : new AgentRunOptions { AllowBackgroundResponses = allowBackgroundResponses, AdditionalProperties = context.Metadata.ToAdditionalProperties() };
+        var options = CreateRunOptions(context, allowBackgroundResponses);
 
         AgentResponse response;
         try
@@ -137,9 +141,7 @@ internal sealed class A2AAgentHandler : IAgentHandler
 
         List<ChatMessage> chatMessages = context.Message is not null ? [context.Message.ToChatMessage()] : [];
 
-        var options = context.Metadata is { Count: > 0 }
-            ? new AgentRunOptions { AdditionalProperties = context.Metadata.ToAdditionalProperties() }
-            : null;
+        var options = CreateRunOptions(context);
 
         try
         {
@@ -165,9 +167,7 @@ internal sealed class A2AAgentHandler : IAgentHandler
         var decisionContext = new A2ARunDecisionContext(context);
         var allowBackgroundResponses = await this._runMode.ShouldRunInBackgroundAsync(decisionContext, cancellationToken).ConfigureAwait(false);
 
-        var options = context.Metadata is not { Count: > 0 }
-            ? new AgentRunOptions { AllowBackgroundResponses = allowBackgroundResponses }
-            : new AgentRunOptions { AllowBackgroundResponses = allowBackgroundResponses, AdditionalProperties = context.Metadata.ToAdditionalProperties() };
+        var options = CreateRunOptions(context, allowBackgroundResponses);
 
         AgentResponse response;
         try
@@ -213,6 +213,42 @@ internal sealed class A2AAgentHandler : IAgentHandler
         }
     }
 
+    /// <summary>
+    /// Creates the <see cref="AgentRunOptions"/> for a run, forwarding the caller supplied A2A
+    /// <c>MessageSendParams.metadata</c> and <c>MessageSendParams.configuration</c> to the hosted agent.
+    /// </summary>
+    /// <param name="context">The A2A request context of the incoming request.</param>
+    /// <param name="allowBackgroundResponses">
+    /// The value to assign to <see cref="AgentRunOptions.AllowBackgroundResponses"/>. Defaults to <see langword="null"/>, which leaves it unset.
+    /// </param>
+    /// <returns>
+    /// The run options to invoke the agent with, or <see langword="null"/> when there is nothing to forward.
+    /// </returns>
+    private static AgentRunOptions? CreateRunOptions(RequestContext context, bool? allowBackgroundResponses = null)
+    {
+        AdditionalPropertiesDictionary? additionalProperties = context.Metadata is { Count: > 0 }
+            ? context.Metadata.ToAdditionalProperties()
+            : null;
+
+        // Forward the whole configuration object under a well-known key so that agents can observe
+        // the caller's requested configuration, including fields added to the A2A protocol in the future.
+        if (context.Configuration is { } configuration)
+        {
+            (additionalProperties ??= [])[ConfigurationPropertyKey] = configuration;
+        }
+
+        if (allowBackgroundResponses is null && additionalProperties is null)
+        {
+            return null;
+        }
+
+        return new AgentRunOptions
+        {
+            AllowBackgroundResponses = allowBackgroundResponses,
+            AdditionalProperties = additionalProperties
+        };
+    }
+
     private static Message CreateMessageFromResponse(string contextId, AgentResponse response) =>
         new()
         {

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Extensions/PortableValueExtensions.cs

@@ -48,26 +48,33 @@ internal static class PortableValueExtensions
 
         if (formulaValues[0] is RecordValue recordValue)
         {
-            return FormulaValue.NewTable(ParseRecordType(recordValue), formulaValues.OfType<RecordValue>());
+            return FormulaValue.NewTable(ParseRecordType(recordValue), formulaValues.OfType<RecordValue>().ToArray());
         }
 
-        return
-            formulaValues[0] switch
-            {
-                PrimitiveValue<bool> => NewSingleColumnTable<bool>(),
-                PrimitiveValue<string> => NewSingleColumnTable<string>(),
-                PrimitiveValue<int> => NewSingleColumnTable<int>(),
-                PrimitiveValue<long> => NewSingleColumnTable<long>(),
-                PrimitiveValue<float> => NewSingleColumnTable<float>(),
-                PrimitiveValue<decimal> => NewSingleColumnTable<decimal>(),
-                PrimitiveValue<double> => NewSingleColumnTable<double>(),
-                PrimitiveValue<TimeSpan> => NewSingleColumnTable<TimeSpan>(),
-                PrimitiveValue<DateTime> => NewSingleColumnTable<DateTime>(),
-                _ => throw new DeclarativeModelException($"Unsupported table element type: {formulaValues[0].Type.GetType().Name}"),
-            };
+        FormulaType elementType = formulaValues[0] switch
+        {
+            PrimitiveValue<bool>
+                or PrimitiveValue<string>
+                or PrimitiveValue<int>
+                or PrimitiveValue<long>
+                or PrimitiveValue<decimal>
+                or PrimitiveValue<float>
+                or PrimitiveValue<double>
+                or PrimitiveValue<TimeSpan>
+                or PrimitiveValue<DateTime> => formulaValues[0].Type,
+            _ => throw new DeclarativeModelException($"Unsupported table element type: {formulaValues[0].Type.GetType().Name}"),
+        };
 
-        TableValue NewSingleColumnTable<TValue>() =>
-            FormulaValue.NewSingleColumnTable(formulaValues.OfType<PrimitiveValue<TValue>>());
+        RecordType singleColumnType = RecordType.Empty().Add("Value", elementType);
+        RecordValue[] rows =
+        [
+            .. formulaValues.Select(
+                value =>
+                    FormulaValue.NewRecordFromFields(
+                        singleColumnType,
+                        new NamedValue("Value", value))),
+        ];
+        return FormulaValue.NewTable(singleColumnType, rows);
     }
 
     public static bool IsSystemType<TValue>(this PortableValue value, [NotNullWhen(true)] out TValue? typedValue) where TValue : struct

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

@@ -32,9 +32,23 @@ internal sealed class EditTableExecutor(EditTable model, WorkflowFormulaState st
             case TableChangeType.Add:
                 ValueExpression addItemValue = Throw.IfNull(this.Model.Value, $"{nameof(this.Model)}.{nameof(this.Model.Value)}");
                 EvaluationResult<DataValue> addResult = this.Evaluator.GetValue(addItemValue);
-                RecordValue newRecord = BuildRecord(tableValue.Type.ToRecord(), addResult.Value.ToFormula());
-                await tableValue.AppendAsync(newRecord, cancellationToken).ConfigureAwait(false);
-                await this.AssignAsync(variablePath, newRecord, context).ConfigureAwait(false);
+                FormulaValue addValue = addResult.Value.ToFormula();
+                RecordType recordType = tableValue.Type.ToRecord();
+                RecordValue newRecord;
+                TableValue resultTable;
+                if (!recordType.FieldNames.Any() && !tableValue.Rows.Any())
+                {
+                    newRecord = BuildRecordFromValue(addValue);
+                    resultTable = FormulaValue.NewTable(newRecord.Type, newRecord);
+                }
+                else
+                {
+                    newRecord = BuildRecord(recordType, addValue);
+                    await tableValue.AppendAsync(newRecord, cancellationToken).ConfigureAwait(false);
+                    resultTable = tableValue;
+                }
+                await this.AssignAsync(variablePath, resultTable, context).ConfigureAwait(false);
+                await this.AssignAsync(this.Model.ResultVariable?.Path, newRecord, context).ConfigureAwait(false);
                 break;
             case TableChangeType.Remove:
                 ValueExpression removeItemValue = Throw.IfNull(this.Model.Value, $"{nameof(this.Model)}.{nameof(this.Model.Value)}");
@@ -42,19 +56,26 @@ internal sealed class EditTableExecutor(EditTable model, WorkflowFormulaState st
                 if (removeResult.Value is TableDataValue removeItemTable)
                 {
                     await tableValue.RemoveAsync(removeItemTable?.Values.Select(row => row.ToRecordValue()), all: true, cancellationToken).ConfigureAwait(false);
-                    await this.AssignAsync(variablePath, RecordValue.Empty(), context).ConfigureAwait(false);
+                    await this.AssignAsync(variablePath, tableValue, context).ConfigureAwait(false);
+                    await this.AssignAsync(this.Model.ResultVariable?.Path, RecordValue.Empty(), context).ConfigureAwait(false);
                 }
                 break;
             case TableChangeType.Clear:
                 await tableValue.ClearAsync(cancellationToken).ConfigureAwait(false);
-                await this.AssignAsync(variablePath, FormulaValue.NewBlank(), context).ConfigureAwait(false);
+                await this.AssignAsync(variablePath, tableValue, context).ConfigureAwait(false);
+                await this.AssignAsync(this.Model.ResultVariable?.Path, FormulaValue.NewBlank(), context).ConfigureAwait(false);
                 break;
             case TableChangeType.TakeFirst:
                 RecordValue? firstRow = tableValue.Rows.FirstOrDefault()?.Value;
                 if (firstRow is not null)
                 {
                     await tableValue.RemoveAsync([firstRow], all: true, cancellationToken).ConfigureAwait(false);
-                    await this.AssignAsync(variablePath, firstRow, context).ConfigureAwait(false);
+                    await this.AssignAsync(variablePath, tableValue, context).ConfigureAwait(false);
+                    await this.AssignAsync(this.Model.ResultVariable?.Path, firstRow, context).ConfigureAwait(false);
+                }
+                else
+                {
+                    await this.AssignAsync(this.Model.ResultVariable?.Path, FormulaValue.NewBlank(), context).ConfigureAwait(false);
                 }
                 break;
             case TableChangeType.TakeLast:
@@ -62,13 +83,23 @@ internal sealed class EditTableExecutor(EditTable model, WorkflowFormulaState st
                 if (lastRow is not null)
                 {
                     await tableValue.RemoveAsync([lastRow], all: true, cancellationToken).ConfigureAwait(false);
-                    await this.AssignAsync(variablePath, lastRow, context).ConfigureAwait(false);
+                    await this.AssignAsync(variablePath, tableValue, context).ConfigureAwait(false);
+                    await this.AssignAsync(this.Model.ResultVariable?.Path, lastRow, context).ConfigureAwait(false);
+                }
+                else
+                {
+                    await this.AssignAsync(this.Model.ResultVariable?.Path, FormulaValue.NewBlank(), context).ConfigureAwait(false);
                 }
                 break;
         }
 
         return default;
 
+        static RecordValue BuildRecordFromValue(FormulaValue value) =>
+            value is RecordValue recordValue ?
+                recordValue :
+                FormulaValue.NewRecordFromFields(new NamedValue("Value", value));
+
         static RecordValue BuildRecord(RecordType recordType, FormulaValue value)
         {
             return FormulaValue.NewRecordFromFields(recordType, GetValues());

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

@@ -31,14 +31,26 @@ internal sealed class EditTableV2Executor(EditTableV2 model, WorkflowFormulaStat
         {
             ValueExpression addItemValue = Throw.IfNull(addItemOperation.Value, $"{nameof(this.Model)}.{nameof(this.Model.ChangeType)}");
             EvaluationResult<DataValue> expressionResult = this.Evaluator.GetValue(addItemValue);
-            RecordValue newRecord = BuildRecord(tableValue.Type.ToRecord(), expressionResult.Value.ToFormula());
-            await tableValue.AppendAsync(newRecord, cancellationToken).ConfigureAwait(false);
-            await this.AssignAsync(this.Model.ItemsVariable, newRecord, context).ConfigureAwait(false);
+            FormulaValue addValue = expressionResult.Value.ToFormula();
+            RecordType recordType = tableValue.Type.ToRecord();
+            TableValue resultTable;
+            if (!recordType.FieldNames.Any() && !tableValue.Rows.Any())
+            {
+                RecordValue newRecord = BuildRecordFromValue(addValue);
+                resultTable = FormulaValue.NewTable(newRecord.Type, newRecord);
+            }
+            else
+            {
+                RecordValue newRecord = BuildRecord(recordType, addValue);
+                await tableValue.AppendAsync(newRecord, cancellationToken).ConfigureAwait(false);
+                resultTable = tableValue;
+            }
+            await this.AssignAsync(this.Model.ItemsVariable, resultTable, context).ConfigureAwait(false);
         }
         else if (changeType is ClearItemsOperation)
         {
             await tableValue.ClearAsync(cancellationToken).ConfigureAwait(false);
-            await this.AssignAsync(this.Model.ItemsVariable, FormulaValue.NewBlank(), context).ConfigureAwait(false);
+            await this.AssignAsync(this.Model.ItemsVariable, tableValue, context).ConfigureAwait(false);
         }
         else if (changeType is RemoveItemOperation removeItemOperation)
         {
@@ -47,30 +59,45 @@ internal sealed class EditTableV2Executor(EditTableV2 model, WorkflowFormulaStat
             if (expressionResult.Value.ToFormula() is TableValue removeItemTable)
             {
                 await tableValue.RemoveAsync(removeItemTable.Rows.Select(row => row.Value), all: true, cancellationToken).ConfigureAwait(false);
-                await this.AssignAsync(this.Model.ItemsVariable, FormulaValue.NewBlank(), context).ConfigureAwait(false);
+                await this.AssignAsync(this.Model.ItemsVariable, tableValue, context).ConfigureAwait(false);
             }
         }
-        else if (changeType is TakeLastItemOperation)
+        else if (changeType is TakeLastItemOperation takeLastOperation)
         {
             RecordValue? lastRow = tableValue.Rows.LastOrDefault()?.Value;
             if (lastRow is not null)
             {
                 await tableValue.RemoveAsync([lastRow], all: true, cancellationToken).ConfigureAwait(false);
-                await this.AssignAsync(this.Model.ItemsVariable, lastRow, context).ConfigureAwait(false);
+                await this.AssignAsync(this.Model.ItemsVariable, tableValue, context).ConfigureAwait(false);
+                await this.AssignAsync(takeLastOperation.ResultVariable?.Path, lastRow, context).ConfigureAwait(false);
+            }
+            else
+            {
+                await this.AssignAsync(takeLastOperation.ResultVariable?.Path, FormulaValue.NewBlank(), context).ConfigureAwait(false);
             }
         }
-        else if (changeType is TakeFirstItemOperation)
+        else if (changeType is TakeFirstItemOperation takeFirstOperation)
         {
             RecordValue? firstRow = tableValue.Rows.FirstOrDefault()?.Value;
             if (firstRow is not null)
             {
                 await tableValue.RemoveAsync([firstRow], all: true, cancellationToken).ConfigureAwait(false);
-                await this.AssignAsync(this.Model.ItemsVariable, firstRow, context).ConfigureAwait(false);
+                await this.AssignAsync(this.Model.ItemsVariable, tableValue, context).ConfigureAwait(false);
+                await this.AssignAsync(takeFirstOperation.ResultVariable?.Path, firstRow, context).ConfigureAwait(false);
+            }
+            else
+            {
+                await this.AssignAsync(takeFirstOperation.ResultVariable?.Path, FormulaValue.NewBlank(), context).ConfigureAwait(false);
             }
         }
 
         return default;
 
+        static RecordValue BuildRecordFromValue(FormulaValue value) =>
+            value is RecordValue recordValue ?
+                recordValue :
+                FormulaValue.NewRecordFromFields(new NamedValue("Value", value));
+
         static RecordValue BuildRecord(RecordType recordType, FormulaValue value)
         {
             return FormulaValue.NewRecordFromFields(recordType, GetValues());

dotnet/src/Microsoft.Agents.AI.Workflows/Execution/InputWaiter.cs

@@ -33,10 +33,24 @@ internal sealed class InputWaiter : IDisposable
         }
     }
 
-    public Task WaitForInputAsync(CancellationToken cancellationToken = default) => this.WaitForInputAsync(null, cancellationToken);
+    /// <summary>
+    /// Waits until input is signaled. This wait never expires; it completes only when
+    /// <see cref="SignalInput"/> is called or <paramref name="cancellationToken"/> is cancelled.
+    /// </summary>
+    /// <param name="cancellationToken">A token to cancel the wait.</param>
+    public Task WaitForInputAsync(CancellationToken cancellationToken = default) => this._inputSignal.WaitAsync(cancellationToken);
 
-    public async Task WaitForInputAsync(TimeSpan? timeout = null, CancellationToken cancellationToken = default)
+    /// <summary>
+    /// Waits until input is signaled or <paramref name="timeout"/> expires.
+    /// </summary>
+    /// <param name="timeout">The maximum time to wait for input.</param>
+    /// <param name="cancellationToken">A token to cancel the wait.</param>
+    /// <returns>
+    /// <see langword="true"/> if the wait was released by <see cref="SignalInput"/>;
+    /// <see langword="false"/> if <paramref name="timeout"/> expired first.
+    /// </returns>
+    public async Task<bool> WaitForInputAsync(TimeSpan timeout, CancellationToken cancellationToken = default)
     {
-        await this._inputSignal.WaitAsync(timeout ?? TimeSpan.FromMilliseconds(-1), cancellationToken).ConfigureAwait(false);
+        return await this._inputSignal.WaitAsync(timeout, cancellationToken).ConfigureAwait(false);
     }
 }

dotnet/src/Microsoft.Agents.AI.Workflows/MagenticDefaultPrompts.cs

@@ -0,0 +1,154 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI.Workflows;
+
+/// <summary>
+/// The built-in English prompt templates the Magentic manager uses. These are exposed so callers can read them and
+/// base a <see cref="MagenticPromptOverrides"/> value on the default (for example, translating it or appending a
+/// language instruction) instead of writing a prompt from scratch.
+/// </summary>
+/// <remarks>
+/// Each template uses named single-brace placeholders (e.g. <c>{task}</c>) that the framework substitutes at render
+/// time; the available placeholders per prompt are documented on the corresponding <see cref="MagenticPromptOverrides"/>
+/// property. A progress-ledger override must keep the <c>{schema}</c> placeholder so the JSON schema can be injected.
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public static class MagenticDefaultPrompts
+{
+    /// <summary>The default template for gathering the initial fact sheet. Placeholders: <c>{task}</c>.</summary>
+    public static readonly string TaskLedgerFactsPrompt = """
+Below I will present you a request.
+
+Before we begin addressing the request, please answer the following pre-survey to the best of your ability.
+        Keep in mind that you are Ken Jennings-level with trivia, and Mensa-level with puzzles, so there should be
+        a deep well to draw from.
+
+        Here is the request:
+
+{task}
+
+    Here is the pre-survey:
+
+    1. Please list any specific facts or figures that are GIVEN in the request itself. It is possible that
+       there are none.
+    2. Please list any facts that may need to be looked up, and WHERE SPECIFICALLY they might be found.
+       In some cases, authoritative sources are mentioned in the request itself.
+    3. Please list any facts that may need to be derived (e.g., via logical deduction, simulation, or computation)
+    4. Please list any facts that are recalled from memory, hunches, well-reasoned guesses, etc.
+
+When answering this survey, keep in mind that "facts" will typically be specific names, dates, statistics, etc.
+Your answer should use headings:
+
+    1. GIVEN OR VERIFIED FACTS
+    2. FACTS TO LOOK UP
+    3. FACTS TO DERIVE
+    4. EDUCATED GUESSES
+
+DO NOT include any other headings or sections in your response. DO NOT list next steps or plans until asked to do so.
+""";
+
+    /// <summary>The default template for updating the fact sheet on a replan. Placeholders: <c>{task}</c>, <c>{old_facts}</c>.</summary>
+    public static readonly string TaskLedgerFactsUpdatePrompt = """
+As a reminder, we are working to solve the following task:
+
+{task}
+
+It is clear we are not making as much progress as we would like, but we may have learned something new.
+Please rewrite the following fact sheet, updating it to include anything new we have learned that may be helpful.
+
+Example edits can include (but are not limited to) adding new guesses, moving educated guesses to verified facts
+if appropriate, etc. Updates may be made to any section of the fact sheet, and more than one section of the fact
+sheet can be edited. This is an especially good time to update educated guesses, so please at least add or update
+one educated guess or hunch, and explain your reasoning.
+
+Here is the old fact sheet:
+
+{old_facts}
+""";
+
+    /// <summary>The default template for creating the initial plan. Placeholders: <c>{team}</c>.</summary>
+    public static readonly string TaskLedgerPlanPrompt = """
+Fantastic. To address this request we have assembled the following team:
+
+{team}
+
+Based on the team composition, and known and unknown facts, please devise a short bullet-point plan for addressing the
+original request. Remember, there is no requirement to involve all team members. A team member's particular expertise
+may not be needed for this task.
+""";
+
+    /// <summary>The default template for updating the plan on a replan. Placeholders: <c>{team}</c>.</summary>
+    public static readonly string TaskLedgerPlanUpdatePrompt = """
+Please briefly explain what went wrong on this last run
+(the root cause of the failure), and then come up with a new plan that takes steps and includes hints to overcome prior
+challenges and especially avoids repeating the same mistakes. As before, the new plan should be concise, expressed in
+bullet-point form, and consider the following team composition:
+
+{team}
+""";
+
+    /// <summary>
+    /// The default template for the full task ledger (the plan-event text combining facts and plan).
+    /// Placeholders: <c>{task}</c>, <c>{team}</c>, <c>{facts}</c>, <c>{plan}</c>.
+    /// </summary>
+    public static readonly string TaskLedgerFullPrompt = """
+We are working to address the following user request:
+
+{task}
+
+
+To answer this request we have assembled the following team:
+
+{team}
+
+
+Here is an initial fact sheet to consider:
+
+{facts}
+
+
+Here is the plan to follow as best as possible:
+
+{plan}
+""";
+
+    /// <summary>
+    /// The default progress-ledger template. Placeholders: <c>{task}</c>, <c>{team}</c>, <c>{questions}</c>,
+    /// <c>{schema}</c>. An override must keep <c>{schema}</c> so the JSON schema the response is parsed against can
+    /// be injected.
+    /// </summary>
+    public static readonly string ProgressLedgerPrompt = """
+Recall we are working on the following request:
+
+{task}
+
+And we have assembled the following team:
+
+{team}
+
+To make progress on the request, please answer the following questions, including necessary reasoning:
+
+{questions}
+
+Please output an answer in pure JSON format according to the following schema. The JSON object must be parsable as-is.
+DO NOT OUTPUT ANYTHING OTHER THAN JSON, AND DO NOT DEVIATE FROM THIS SCHEMA:
+
+{schema}
+""";
+
+    /// <summary>The default template for synthesizing the final answer. Placeholders: <c>{task}</c>.</summary>
+    public static readonly string FinalAnswerPrompt = """
+We are working on the following task:
+{task}
+
+We have completed the task.
+
+The above messages contain the conversation that took place to complete the task.
+
+Based on the information gathered, provide the final answer to the original request.
+The answer should be phrased as if you were speaking to the user. 
+""";
+}

dotnet/src/Microsoft.Agents.AI.Workflows/MagenticPromptOverrides.cs

@@ -0,0 +1,72 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI.Workflows;
+
+/// <summary>
+/// Optional overrides for the internal prompt templates the Magentic manager uses to plan, track progress, and
+/// synthesize the final answer. Any property left <see langword="null"/> keeps the built-in English template.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Overrides are supplied to <see cref="MagenticWorkflowBuilder.WithPromptOverrides(MagenticPromptOverrides)"/>.
+/// Each template may contain named single-brace placeholders that the framework substitutes at render time
+/// (e.g. <c>{task}</c>). Unlike Python's <c>str.format</c>, literal braces (such as JSON in the progress-ledger
+/// prompt) do <b>not</b> need to be escaped - only the documented placeholders are replaced.
+/// </para>
+/// <para>
+/// The available placeholders differ per prompt and are documented on each property. A placeholder that is not
+/// available for a given prompt is left untouched.
+/// </para>
+/// <para>
+/// To base an override on a built-in template (for example, to translate it), read the corresponding member on
+/// <see cref="MagenticDefaultPrompts"/>.
+/// </para>
+/// <para>
+/// If <c>MagenticWorkflowBuilder.WithResponseLanguage</c> is also set, its language directive is appended after the
+/// (possibly overridden) template body, so overrides and the language pin compose.
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed record MagenticPromptOverrides
+{
+    /// <summary>
+    /// Overrides the prompt that gathers the initial fact sheet. Placeholders: <c>{task}</c>.
+    /// </summary>
+    public string? TaskLedgerFactsPrompt { get; init; }
+
+    /// <summary>
+    /// Overrides the prompt that creates the initial plan. Placeholders: <c>{team}</c>.
+    /// </summary>
+    public string? TaskLedgerPlanPrompt { get; init; }
+
+    /// <summary>
+    /// Overrides the prompt that renders the full task ledger (the plan-event text combining facts and plan).
+    /// Placeholders: <c>{task}</c>, <c>{team}</c>, <c>{facts}</c>, <c>{plan}</c>.
+    /// </summary>
+    public string? TaskLedgerFullPrompt { get; init; }
+
+    /// <summary>
+    /// Overrides the prompt that updates the fact sheet during a replan. Placeholders: <c>{task}</c>, <c>{old_facts}</c>.
+    /// </summary>
+    public string? TaskLedgerFactsUpdatePrompt { get; init; }
+
+    /// <summary>
+    /// Overrides the prompt that updates the plan during a replan. Placeholders: <c>{team}</c>.
+    /// </summary>
+    public string? TaskLedgerPlanUpdatePrompt { get; init; }
+
+    /// <summary>
+    /// Overrides the progress-ledger prompt. Placeholders: <c>{task}</c>, <c>{team}</c>, <c>{questions}</c>,
+    /// <c>{schema}</c>. The <c>{schema}</c> placeholder is required - the framework injects the JSON schema the
+    /// response is parsed against, so omitting it would break progress-ledger parsing and next-speaker routing.
+    /// </summary>
+    public string? ProgressLedgerPrompt { get; init; }
+
+    /// <summary>
+    /// Overrides the prompt that synthesizes the final answer. Placeholders: <c>{task}</c>.
+    /// </summary>
+    public string? FinalAnswerPrompt { get; init; }
+}

dotnet/src/Microsoft.Agents.AI.Workflows/MagenticWorkflowBuilder.cs

@@ -2,8 +2,10 @@
 
 using System;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 using System.Threading.Tasks;
 using Microsoft.Agents.AI.Workflows.Specialized.Magentic;
+using Microsoft.Shared.DiagnosticIds;
 
 using ExecutorFactoryFunc = System.Func<Microsoft.Agents.AI.Workflows.ExecutorConfig<Microsoft.Agents.AI.Workflows.ExecutorOptions>,
                                         string,
@@ -33,6 +35,8 @@ public class MagenticWorkflowBuilder(AIAgent managerAgent) : OrchestrationBuilde
     private int? _maxRounds;
     private int? _maxResets;
     private bool _requirePlanSignoff = true;
+    private string? _responseLanguage;
+    private MagenticPromptOverrides? _promptOverrides;
 
     /// <inheritdoc cref="GroupChatWorkflowBuilder.AddParticipants(IEnumerable{AIAgent})"/>
     public MagenticWorkflowBuilder AddParticipants(params IEnumerable<AIAgent> agents)
@@ -82,13 +86,72 @@ public class MagenticWorkflowBuilder(AIAgent managerAgent) : OrchestrationBuilde
         return this;
     }
 
+    /// <summary>
+    /// Set the concrete language (e.g. "English", "Chinese") that the Magentic manager's internally generated
+    /// messages - the task ledger, progress ledger, and final answer - must be written in.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// When set, the manager is instructed to write all natural-language content in this exact language. This is more
+    /// reliable than relying on the model to infer and match the request language, which some models fail to do for the
+    /// progress ledger's JSON free-text fields, causing those internal messages to appear in an unexpected language.
+    /// </para>
+    /// <para>
+    /// When left unset (the default), the built-in English prompt templates are used as-is.
+    /// </para>
+    /// <para>
+    /// If a prompt is also overridden via <see cref="WithPromptOverrides(MagenticPromptOverrides)"/>, this language
+    /// directive is appended after that override's body, so the two compose.
+    /// </para>
+    /// <para>
+    /// This option is experimental and may change or be removed in a future release.
+    /// </para>
+    /// </remarks>
+    /// <param name="responseLanguage">
+    /// The language name to use for internally generated messages, or <see langword="null"/> to use the built-in
+    /// English templates as-is.
+    /// </param>
+    /// <returns>This builder instance, for chaining.</returns>
+    [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+    public MagenticWorkflowBuilder WithResponseLanguage(string? responseLanguage = null)
+    {
+        this._responseLanguage = string.IsNullOrWhiteSpace(responseLanguage) ? null : responseLanguage!.Trim();
+        return this;
+    }
+
+    /// <summary>
+    /// Override any of the Magentic manager's internal prompt templates (task ledger, progress ledger, final answer).
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Any property left <see langword="null"/> on <paramref name="promptOverrides"/> keeps the built-in English
+    /// template. Templates use named single-brace placeholders (e.g. <c>{task}</c>) documented on
+    /// <see cref="MagenticPromptOverrides"/>; the framework substitutes them at render time.
+    /// </para>
+    /// <para>
+    /// A progress-ledger override must contain the <c>{schema}</c> placeholder (validated at <see cref="Build"/>) so
+    /// the framework can inject the JSON schema the response is parsed against.
+    /// </para>
+    /// <para>
+    /// This option is experimental and may change or be removed in a future release.
+    /// </para>
+    /// </remarks>
+    /// <param name="promptOverrides">The prompt overrides to apply, or <see langword="null"/> to clear any overrides.</param>
+    /// <returns>This builder instance, for chaining.</returns>
+    [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+    public MagenticWorkflowBuilder WithPromptOverrides(MagenticPromptOverrides? promptOverrides = null)
+    {
+        this._promptOverrides = promptOverrides;
+        return this;
+    }
+
     private WorkflowBuilder ReduceToWorkflowBuilder()
     {
         // Create a copy of the team so that improper modifications by using the builder after .Build() do not affect the
         // workflow in unexpected ways.
         List<AIAgent> team = [.. this._team];
 
-        ExecutorBinding orchestrator = CreateOrchestratorBinding(managerAgent, team, this.Limits, this._requirePlanSignoff);
+        ExecutorBinding orchestrator = CreateOrchestratorBinding(managerAgent, team, this.Limits, this._requirePlanSignoff, this._responseLanguage, this._promptOverrides);
         WorkflowBuilder result = new(orchestrator);
 
         AIAgentHostOptions options = new()
@@ -131,6 +194,13 @@ public class MagenticWorkflowBuilder(AIAgent managerAgent) : OrchestrationBuilde
             throw new InvalidOperationException("At least one participant must be added via AddParticipants() before building the workflow.");
         }
 
+        if (this._promptOverrides?.ProgressLedgerPrompt is { } progressLedgerPrompt && !progressLedgerPrompt.Contains("{schema}"))
+        {
+            throw new InvalidOperationException(
+                "A progress-ledger prompt override must contain the '{schema}' placeholder so the required JSON schema can be injected; " +
+                "otherwise progress-ledger parsing and next-speaker routing would break.");
+        }
+
         return this.ReduceToWorkflowBuilder().Build();
     }
 
@@ -139,14 +209,14 @@ public class MagenticWorkflowBuilder(AIAgent managerAgent) : OrchestrationBuilde
         MaxResetCount: this._maxResets,
         MaxStallCount: this._maxStalls);
 
-    private static ExecutorBinding CreateOrchestratorBinding(AIAgent managerAgent, List<AIAgent> team, TaskLimits limits, bool requirePlanSignoff)
+    private static ExecutorBinding CreateOrchestratorBinding(AIAgent managerAgent, List<AIAgent> team, TaskLimits limits, bool requirePlanSignoff, string? responseLanguage, MagenticPromptOverrides? promptOverrides)
     {
         ExecutorFactoryFunc factory = CreateOrchestratorAsync;
         return factory.BindExecutor(nameof(MagenticOrchestrator));
 
         ValueTask<MagenticOrchestrator> CreateOrchestratorAsync(ExecutorConfig<ExecutorOptions> options, string sessionId)
         {
-            return new(new MagenticOrchestrator(managerAgent, team, limits, requirePlanSignoff));
+            return new(new MagenticOrchestrator(managerAgent, team, limits, requirePlanSignoff, responseLanguage, promptOverrides));
         }
     }
 }

dotnet/src/Microsoft.Agents.AI.Workflows/Microsoft.Agents.AI.Workflows.csproj

@@ -2,11 +2,12 @@
 
   <PropertyGroup>
     <IsReleased>true</IsReleased>
-    <NoWarn>$(NoWarn);MEAI001;MAAIW001</NoWarn>
+    <NoWarn>$(NoWarn);MEAI001;MAAIW001;MAAI001</NoWarn>
   </PropertyGroup>
 
   <PropertyGroup>
     <InjectSharedThrow>true</InjectSharedThrow>
+    <InjectSharedDiagnosticIds>true</InjectSharedDiagnosticIds>
     <InjectIsExternalInitOnLegacy>true</InjectIsExternalInitOnLegacy>
     <InjectExperimentalAttributeOnLegacy>true</InjectExperimentalAttributeOnLegacy>
     <InjectTrimAttributesOnLegacy>true</InjectTrimAttributesOnLegacy>

dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/Magentic/MagenticOrchestrator.cs

@@ -77,7 +77,9 @@ public sealed class MagenticProgressLedgerUpdatedEvent(MagenticProgressLedger pr
 /// <param name="team"></param>
 /// <param name="limits"></param>
 /// <param name="requirePlanSignoff"></param>
-internal class MagenticOrchestrator(AIAgent managerAgent, List<AIAgent> team, TaskLimits limits, bool requirePlanSignoff)
+/// <param name="responseLanguage"></param>
+/// <param name="promptOverrides"></param>
+internal class MagenticOrchestrator(AIAgent managerAgent, List<AIAgent> team, TaskLimits limits, bool requirePlanSignoff, string? responseLanguage = null, MagenticPromptOverrides? promptOverrides = null)
     : ChatProtocolExecutor(nameof(MagenticOrchestrator), s_options, declareCrossRunShareable: false)
 {
     private readonly MagenticManager _manager = new(managerAgent);
@@ -191,7 +193,7 @@ internal class MagenticOrchestrator(AIAgent managerAgent, List<AIAgent> team, Ta
         if (this._taskContext == null)
         {
             // First Turn: Initialize the task context and create the initial plan
-            this._taskContext = new(messages, team, limits, emitEvents, []);
+            this._taskContext = new(messages, team, limits, emitEvents, []) { ResponseLanguage = responseLanguage, PromptOverrides = promptOverrides };
             await this.UpdatePlanAndDelegateAsync(this._taskContext, context, cancellationToken).ConfigureAwait(false);
         }
         else
@@ -384,7 +386,13 @@ internal class MagenticOrchestrator(AIAgent managerAgent, List<AIAgent> team, Ta
 
             if (state != null)
             {
-                this._taskContext = new MagenticTaskContext(state, team, limits, []);
+                // ResponseLanguage and PromptOverrides are build-time configuration supplied by the builder, so they
+                // are re-applied here rather than restored from the checkpoint state.
+                this._taskContext = new MagenticTaskContext(state, team, limits, [])
+                {
+                    ResponseLanguage = responseLanguage,
+                    PromptOverrides = promptOverrides,
+                };
             }
         }
 

dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/Magentic/MagenticTaskContext.cs

@@ -52,6 +52,21 @@ internal class MagenticTaskContext(List<ChatMessage> taskDefinition, List<AIAgen
 
     public List<ChatMessage> ChatHistory { get; internal set; } = new();
 
+    /// <summary>
+    /// Optional concrete language (e.g. "English", "Chinese") that the manager's internally generated messages
+    /// must be written in, configured via <c>MagenticWorkflowBuilder.WithResponseLanguage</c>. When
+    /// <see langword="null"/> the built-in English prompts are used as-is. This is build-time configuration
+    /// (re-applied from the builder after a checkpoint restore), not runtime state.
+    /// </summary>
+    public string? ResponseLanguage { get; internal set; }
+
+    /// <summary>
+    /// Optional user-supplied overrides for the manager's internal prompt templates, configured via
+    /// <c>MagenticWorkflowBuilder.WithPromptOverrides</c>. When <see langword="null"/> the built-in templates
+    /// are used. This is build-time configuration (re-applied from the builder after a checkpoint restore).
+    /// </summary>
+    public MagenticPromptOverrides? PromptOverrides { get; internal set; }
+
     public TaskLedger? TaskLedger { get; internal set; }
 
     public TaskLimits TaskLimits => limits;

dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/Magentic/PromptTemplates.cs

@@ -1,151 +1,118 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-using Microsoft.Extensions.AI;
+using System;
+using System.Text.RegularExpressions;
 
 namespace Microsoft.Agents.AI.Workflows.Specialized.Magentic;
 
 internal static class PromptTemplateExtensions
 {
+    // Matches a single-brace placeholder token, e.g. {task} or {old_facts}. Only {word} sequences are treated as
+    // placeholders, so literal braces in a prompt (such as JSON in an override) are left untouched.
+    private static readonly Regex s_placeholderPattern = new(@"\{(\w+)\}");
+
+    // The built-in English prompt templates live on the public MagenticDefaultPrompts class so callers can read and
+    // base overrides on them. Named single-brace placeholders (e.g. {task}) are substituted at render time.
+    private static string Substitute(string template, params (string Token, string Value)[] values) =>
+        // Single-pass replacement over the template: substituted values are never re-scanned for further
+        // placeholders, so content that happens to contain "{token}" text (e.g. in the task) is not corrupted.
+        s_placeholderPattern.Replace(template, match =>
+        {
+            foreach ((string token, string value) in values)
+            {
+                if (string.Equals(token, match.Groups[1].Value, StringComparison.Ordinal))
+                {
+                    return value;
+                }
+            }
+
+            // Not one of the placeholders available for this prompt - leave the original text untouched.
+            return match.Value;
+        });
+
+    // When a concrete response language is configured via WithResponseLanguage, a directive pinning that language is
+    // appended AFTER the (possibly overridden) prompt body. A concrete language name is followed far more reliably than
+    // a relative "match the request" instruction, especially for the progress ledger's JSON free-text fields (#6987).
+    private static string AppendLanguageDirective(string body, MagenticTaskContext taskContext) =>
+        taskContext.ResponseLanguage is { Length: > 0 } language
+            ? $"{body}\n\n{GeneralLanguageDirective(language)}"
+            : body;
+
+    private static string AppendProgressLedgerLanguageDirective(string body, MagenticTaskContext taskContext) =>
+        taskContext.ResponseLanguage is { Length: > 0 } language
+            ? $"{body}\n\n{ProgressLedgerLanguageDirective(language)}"
+            : body;
+
+    private static string GeneralLanguageDirective(string language) =>
+        $"Write your entire response in {language}, including any section headings or labels. Do not use any other language.";
+
+    private static string ProgressLedgerLanguageDirective(string language) =>
+        $"When filling in the JSON, write every \"reason\" value and the \"instruction_or_question\" answer in {language}. " +
+        "Do not translate the JSON keys - they must remain exactly as shown above. The \"next_speaker\" answer must " +
+        "remain exactly one of the provided team member names and must not be translated.";
+
     public static string ToTaskLedgerFactsPrompt(this MagenticTaskContext taskContext)
     {
-        return $"""
-Below I will present you a request.
+        string body = Substitute(taskContext.PromptOverrides?.TaskLedgerFactsPrompt ?? MagenticDefaultPrompts.TaskLedgerFactsPrompt,
+            ("task", taskContext.Task));
 
-Before we begin addressing the request, please answer the following pre-survey to the best of your ability.
-        Keep in mind that you are Ken Jennings-level with trivia, and Mensa-level with puzzles, so there should be
-        a deep well to draw from.
-
-        Here is the request:
-
-{taskContext.Task}
-
-    Here is the pre-survey:
-
-    1. Please list any specific facts or figures that are GIVEN in the request itself.It is possible that
-       there are none.
-    2. Please list any facts that may need to be looked up, and WHERE SPECIFICALLY they might be found.
-       In some cases, authoritative sources are mentioned in the request itself.
-    3. Please list any facts that may need to be derived(e.g., via logical deduction, simulation, or computation)
-    4. Please list any facts that are recalled from memory, hunches, well-reasoned guesses, etc.
-
-When answering this survey, keep in mind that "facts" will typically be specific names, dates, statistics, etc.
-Your answer should use headings:
-
-    1. GIVEN OR VERIFIED FACTS
-    2. FACTS TO LOOK UP
-    3. FACTS TO DERIVE
-    4. EDUCATED GUESSES
-
-DO NOT include any other headings or sections in your response.DO NOT list next steps or plans until asked to do so.
-""";
+        return AppendLanguageDirective(body, taskContext);
     }
 
     public static string ToTaskLedgerFactsUpdatePrompt(this MagenticTaskContext taskContext)
     {
-        return $"""
-As a reminder, we are working to solve the following task:
+        string body = Substitute(taskContext.PromptOverrides?.TaskLedgerFactsUpdatePrompt ?? MagenticDefaultPrompts.TaskLedgerFactsUpdatePrompt,
+            ("task", taskContext.Task),
+            ("old_facts", taskContext.TaskLedger?.CurrentFacts.Text ?? string.Empty));
 
-{taskContext.Task}
-
-It is clear we are not making as much progress as we would like, but we may have learned something new.
-Please rewrite the following fact sheet, updating it to include anything new we have learned that may be helpful.
-
-Example edits can include (but are not limited to) adding new guesses, moving educated guesses to verified facts
-if appropriate, etc. Updates may be made to any section of the fact sheet, and more than one section of the fact
-sheet can be edited. This is an especially good time to update educated guesses, so please at least add or update
-one educated guess or hunch, and explain your reasoning.
-
-Here is the old fact sheet:
-
-{taskContext.TaskLedger?.CurrentFacts ?? new(ChatRole.Assistant, string.Empty)}
-""";
+        return AppendLanguageDirective(body, taskContext);
     }
 
     public static string ToTaskLedgerPlanPrompt(this MagenticTaskContext taskContext)
     {
-        return $"""
-Fantastic. To address this request we have assembled the following team:
+        string body = Substitute(taskContext.PromptOverrides?.TaskLedgerPlanPrompt ?? MagenticDefaultPrompts.TaskLedgerPlanPrompt,
+            ("team", taskContext.TeamDescription));
 
-{taskContext.TeamDescription}
-
-Based on the team composition, and known and unknown facts, please devise a short bullet-point plan for addressing the
-original request. Remember, there is no requirement to involve all team members. A team member's particular expertise
-may not be needed for this task.
-""";
+        return AppendLanguageDirective(body, taskContext);
     }
 
     public static string ToTaskLedgerPlanUpdatePrompt(this MagenticTaskContext taskContext)
     {
-        return $"""
-Please briefly explain what went wrong on this last run
-(the root cause of the failure), and then come up with a new plan that takes steps and includes hints to overcome prior
-challenges and especially avoids repeating the same mistakes. As before, the new plan should be concise, expressed in
-bullet-point form, and consider the following team composition:
+        string body = Substitute(taskContext.PromptOverrides?.TaskLedgerPlanUpdatePrompt ?? MagenticDefaultPrompts.TaskLedgerPlanUpdatePrompt,
+            ("team", taskContext.TeamDescription));
 
-{taskContext.TeamDescription}
-""";
+        return AppendLanguageDirective(body, taskContext);
     }
 
     public static string ToTaskLedgerFullPrompt(this MagenticTaskContext taskContext)
     {
-        return $"""
-We are working to address the following user request:
-
-{taskContext.Task}
-
-
-To answer this request we have assembled the following team:
-
-{taskContext.TeamDescription}
-
-
-Here is an initial fact sheet to consider:
-
-{taskContext.TaskLedger!.CurrentFacts ?? new(ChatRole.Assistant, string.Empty)}
-
-
-Here is the plan to follow as best as possible:
-
-{taskContext.TaskLedger!.CurrentPlan}
-""";
+        // Assembly-only prompt (emitted as the plan-event text and used as context); no language directive is appended
+        // because nothing is generated from it - its facts/plan are already localized by their own generation prompts.
+        return Substitute(taskContext.PromptOverrides?.TaskLedgerFullPrompt ?? MagenticDefaultPrompts.TaskLedgerFullPrompt,
+            ("task", taskContext.Task),
+            ("team", taskContext.TeamDescription),
+            ("facts", taskContext.TaskLedger!.CurrentFacts.Text),
+            ("plan", taskContext.TaskLedger!.CurrentPlan.Text));
     }
 
     public static string ToProgressLedgerPrompt(this MagenticTaskContext taskContext)
     {
         (string questions, string schema) = taskContext.ProgressLedger.FormatQuestions();
 
-        return $"""
-Recall we are working on the following request:
+        string body = Substitute(taskContext.PromptOverrides?.ProgressLedgerPrompt ?? MagenticDefaultPrompts.ProgressLedgerPrompt,
+            ("task", taskContext.Task),
+            ("team", taskContext.TeamDescription),
+            ("questions", questions),
+            ("schema", schema));
 
-{taskContext.Task}
-
-And we have assembled the following team:
-
-{taskContext.TeamDescription}
-
-To make progress on the request, please answer the following questions, including necessary reasoning:
-
-{questions}
-
-Please output an answer in pure JSON format according to the following schema. The JSON object must be parsable as-is.
-DO NOT OUTPUT ANYTHING OTHER THAN JSON, AND DO NOT DEVIATE FROM THIS SCHEMA:
-
-{schema}
-""";
+        return AppendProgressLedgerLanguageDirective(body, taskContext);
     }
 
     public static string ToFinalAnswerPrompt(this MagenticTaskContext taskContext)
     {
-        return $"""
-We are working on the following task:
-{taskContext.Task}
+        string body = Substitute(taskContext.PromptOverrides?.FinalAnswerPrompt ?? MagenticDefaultPrompts.FinalAnswerPrompt,
+            ("task", taskContext.Task));
 
-We have completed the task.
-
-The above messages contain the conversation that took place to complete the task.
-
-Based on the information gathered, provide the final answer to the original request.
-The answer should be phrased as if you were speaking to the user. 
-""";
+        return AppendLanguageDirective(body, taskContext);
     }
 }

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

@@ -478,7 +478,7 @@ public sealed partial class ChatClientAgent : AIAgent
         ChatOptions? chatOptions,
         CancellationToken cancellationToken)
     {
-        ChatHistoryProvider? chatHistoryProvider = this.ResolveChatHistoryProvider(chatOptions);
+        ChatHistoryProvider? chatHistoryProvider = this.ResolveChatHistoryProvider(session, chatOptions);
 
         if (chatHistoryProvider is not null)
         {
@@ -510,7 +510,7 @@ public sealed partial class ChatClientAgent : AIAgent
         ChatOptions? chatOptions,
         CancellationToken cancellationToken)
     {
-        ChatHistoryProvider? chatHistoryProvider = this.ResolveChatHistoryProvider(chatOptions);
+        ChatHistoryProvider? chatHistoryProvider = this.ResolveChatHistoryProvider(session, chatOptions);
 
         if (chatHistoryProvider is not null)
         {
@@ -980,22 +980,33 @@ public sealed partial class ChatClientAgent : AIAgent
         }
     }
 
-    private ChatHistoryProvider? ResolveChatHistoryProvider(ChatOptions? chatOptions)
+    private ChatHistoryProvider? ResolveChatHistoryProvider(ChatClientAgentSession session, ChatOptions? chatOptions)
     {
-        ChatHistoryProvider? provider =
-            chatOptions?.ConversationId is null || IsAGUIProviderName(this._agentMetadata.ProviderName)
-            ? this.ChatHistoryProvider
-            : null;
+        // A service that manages chat history server-side disengages the chat history provider so that history
+        // is not stored in two places. The service is considered to store history when a conversation id is
+        // present either on the options (explicitly supplied by the caller) or on the session (returned by the
+        // service on a previous or the current run).
+        //
+        // The per-service-call persistence check must remain: PerServiceCallChatHistoryPersistingChatClient
+        // calls back into LoadChatHistoryAsync/NotifyProviders (which reach here) precisely when per-service-call
+        // persistence is active, and in its simulated path it stamps a sentinel onto session.ConversationId.
+        // Without this check that sentinel would be mistaken for service-stored history and wrongly disengage
+        // the provider the decorator depends on.
+        bool serviceStoresHistory =
+            !this.RequiresPerServiceCallChatHistoryPersistence
+            && !IsAGUIProviderName(this._agentMetadata.ProviderName)
+            && (!string.IsNullOrWhiteSpace(chatOptions?.ConversationId)
+                || !string.IsNullOrWhiteSpace(session.ConversationId));
+
+        ChatHistoryProvider? provider = serviceStoresHistory ? null : this.ChatHistoryProvider;
 
         // If someone provided an override ChatHistoryProvider via AdditionalProperties, we should use that instead.
         if (chatOptions?.AdditionalProperties?.TryGetValue(out ChatHistoryProvider? overrideProvider) is true)
         {
-            if (!IsAGUIProviderName(this._agentMetadata.ProviderName) &&
-                this._agentOptions?.ThrowOnChatHistoryProviderConflict is true &&
-                string.IsNullOrWhiteSpace(chatOptions?.ConversationId) is false)
+            if (this._agentOptions?.ThrowOnChatHistoryProviderConflict is true && serviceStoresHistory)
             {
                 throw new InvalidOperationException(
-                    $"Only {nameof(ChatClientAgentSession.ConversationId)} or {nameof(this.ChatHistoryProvider)} may be used, but not both. The current {nameof(ChatClientAgentSession)} has a {nameof(ChatClientAgentSession.ConversationId)} indicating server-side chat history management, but an override {nameof(this.ChatHistoryProvider)} was provided via {nameof(AgentRunOptions.AdditionalProperties)}.");
+                    $"Only {nameof(ChatClientAgentSession.ConversationId)} or {nameof(this.ChatHistoryProvider)} may be used, but not both. A {nameof(ChatClientAgentSession.ConversationId)} indicating server-side chat history management is present (on the {nameof(ChatClientAgentSession)} or the {nameof(this.ChatOptions)}), but an override {nameof(this.ChatHistoryProvider)} was provided via {nameof(AgentRunOptions.AdditionalProperties)}.");
             }
 
             // Validate that the override provider's StateKeys do not clash with any AIContextProvider's StateKeys.
@@ -1030,7 +1041,7 @@ public sealed partial class ChatClientAgent : AIAgent
         ChatOptions? chatOptions,
         CancellationToken cancellationToken)
     {
-        var chatHistoryProvider = this.ResolveChatHistoryProvider(chatOptions);
+        var chatHistoryProvider = this.ResolveChatHistoryProvider(session, chatOptions);
         if (chatHistoryProvider is null)
         {
             return messages;

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

@@ -115,6 +115,13 @@ public sealed class ToolApprovalAgent : DelegatingAIAgent
             return new AgentResponse(new ChatMessage(ChatRole.Assistant, [nextQueuedItem]));
         }
 
+        // When the caller did not supply a session, create one and use it for every inner call.
+        // The auto-approval loop re-invokes the inner agent with only the injected approval
+        // responses; without a session the inner agent has no conversation history to reconstruct
+        // the original request, which produces an empty request to the underlying service. Threading
+        // a session preserves the history across re-invocations.
+        session ??= await this.InnerAgent.CreateSessionAsync(cancellationToken).ConfigureAwait(false);
+
         // 3. Call the inner agent in a loop. If the inner agent returns approval requests
         //    that are ALL auto-approved by standing rules, we immediately re-call with the
         //    collected approval responses injected. This avoids returning empty responses.
@@ -158,6 +165,11 @@ public sealed class ToolApprovalAgent : DelegatingAIAgent
             yield break;
         }
 
+        // When the caller did not supply a session, create one and use it for every inner call so
+        // conversation history is preserved across auto-approval re-invocations. See the non-streaming
+        // RunCoreAsync for details.
+        session ??= await this.InnerAgent.CreateSessionAsync(cancellationToken).ConfigureAwait(false);
+
         // 3. Stream from the inner agent in a loop. If all approval requests from the stream
         //    are auto-approved by standing rules, we immediately re-stream with the collected
         //    approval responses injected. This avoids returning empty streams.

dotnet/tests/Microsoft.Agents.AI.Foundry.Hosting.UnitTests/FoundryListenPortTests.cs

@@ -0,0 +1,184 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections;
+using System.Collections.Generic;
+using System.Net;
+using System.Reflection;
+using Microsoft.AspNetCore.Server.Kestrel.Core;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Options;
+using Moq;
+
+namespace Microsoft.Agents.AI.Foundry.Hosting.UnitTests;
+
+/// <summary>
+/// Verifies that <c>AddFoundryResponses</c> adds a Kestrel listener on the Foundry hosted-runtime
+/// port for a plain <c>WebApplication.CreateBuilder</c> (Tier 3) host, so a source (ZIP) deployed
+/// agent passes the platform readiness probe with no Dockerfile pinning the port, and that it
+/// leaves the addresses of a host running outside Foundry alone.
+/// </summary>
+/// <remarks>
+/// Every case supplies its values through an in-memory <see cref="IConfiguration"/>, so no test
+/// mutates the process environment and the class stays safe to run in parallel.
+/// </remarks>
+public sealed class FoundryListenPortTests
+{
+    private const string AspNetCoreUrlsKey = "ASPNETCORE_URLS";
+
+    [Fact]
+    public void AddFoundryResponses_WhenHosted_ListensOnFoundryPort()
+    {
+        // Arrange
+        var services = CreateServices();
+
+        // Act
+        services.AddFoundryResponses();
+
+        // Assert
+        Assert.Equal([FoundryHostingExtensions.DefaultListenPort], GetCodeBackedPorts(services));
+    }
+
+    [Fact]
+    public void AddFoundryResponses_WithAgentWhenHosted_ListensOnFoundryPort()
+    {
+        // Arrange
+        var services = CreateServices();
+        var mockAgent = new Mock<AIAgent>();
+        mockAgent.SetupGet(a => a.Name).Returns("test-agent");
+
+        // Act
+        services.AddFoundryResponses(mockAgent.Object);
+
+        // Assert
+        Assert.Equal([FoundryHostingExtensions.DefaultListenPort], GetCodeBackedPorts(services));
+    }
+
+    [Fact]
+    public void AddFoundryResponses_WhenNotHosted_LeavesAddressesAlone()
+    {
+        // Arrange: outside a Foundry container the host keeps whatever addresses it resolved from
+        // configuration, so registering the Responses protocol must not add a listener.
+        var services = CreateServices(hosted: false);
+
+        // Act
+        services.AddFoundryResponses();
+
+        // Assert
+        Assert.Empty(GetCodeBackedPorts(services));
+    }
+
+    [Fact]
+    public void AddFoundryResponses_WhenHostedWithAspNetCoreUrlsSet_StillListensOnFoundryPort()
+    {
+        // Arrange: the .NET base image used by source (ZIP) deploy sets ASPNETCORE_URLS to port 80.
+        // Inside Foundry the listener must still be added, because a listener configured in code
+        // takes precedence over that setting. Skipping it here would leave the container on port 80
+        // and fail every invocation with HTTP 424 session_not_ready.
+        var services = CreateServices(settings: new Dictionary<string, string?>
+        {
+            [AspNetCoreUrlsKey] = "http://+:80",
+        });
+
+        // Act
+        services.AddFoundryResponses();
+
+        // Assert
+        Assert.Equal([FoundryHostingExtensions.DefaultListenPort], GetCodeBackedPorts(services));
+    }
+
+    [Fact]
+    public void AddFoundryResponses_WhenHostedWithPortSet_ListensOnConfiguredPort()
+    {
+        // Arrange: the platform sets PORT only when it needs a port other than the default.
+        var services = CreateServices(settings: new Dictionary<string, string?>
+        {
+            [FoundryHostingExtensions.ListenPortKey] = "9099",
+        });
+
+        // Act
+        services.AddFoundryResponses();
+
+        // Assert
+        Assert.Equal([9099], GetCodeBackedPorts(services));
+    }
+
+    [Theory]
+    [InlineData("0")]
+    [InlineData("65536")]
+    [InlineData("not-a-port")]
+    public void AddFoundryResponses_WhenHostedWithInvalidPort_Throws(string port)
+    {
+        // Arrange
+        var services = CreateServices(settings: new Dictionary<string, string?>
+        {
+            [FoundryHostingExtensions.ListenPortKey] = port,
+        });
+        services.AddFoundryResponses();
+
+        // Act & Assert
+        var exception = Assert.Throws<InvalidOperationException>(() => GetCodeBackedPorts(services));
+        Assert.Contains(port, exception.Message, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public void AddFoundryResponses_CalledTwiceWhenHosted_ListensOnFoundryPortOnce()
+    {
+        // Arrange
+        var services = CreateServices();
+
+        // Act
+        services.AddFoundryResponses();
+        services.AddFoundryResponses();
+
+        // Assert: a duplicate ListenAnyIP on the same port fails Kestrel startup with
+        // "address already in use", so the listener must be added exactly once.
+        Assert.Equal([FoundryHostingExtensions.DefaultListenPort], GetCodeBackedPorts(services));
+    }
+
+    /// <summary>
+    /// Builds a service collection whose <see cref="IConfiguration"/> carries the supplied values,
+    /// marking the process as Foundry-hosted unless <paramref name="hosted"/> says otherwise.
+    /// </summary>
+    private static ServiceCollection CreateServices(bool hosted = true, Dictionary<string, string?>? settings = null)
+    {
+        settings ??= [];
+        if (hosted)
+        {
+            settings[FoundryHostingExtensions.FoundryHostingEnvironmentKey] = "foundry";
+        }
+
+        var services = new ServiceCollection();
+        services.AddLogging();
+        services.AddSingleton<IConfiguration>(new ConfigurationBuilder().AddInMemoryCollection(settings).Build());
+        return services;
+    }
+
+    /// <summary>
+    /// Builds the service provider, resolves the applied <see cref="KestrelServerOptions"/>, and
+    /// returns the ports of every code-configured listener (those added via <c>ListenAnyIP</c>).
+    /// </summary>
+    private static List<int> GetCodeBackedPorts(IServiceCollection services)
+    {
+        using var provider = services.BuildServiceProvider();
+        var options = provider.GetRequiredService<IOptions<KestrelServerOptions>>().Value;
+
+        var property = typeof(KestrelServerOptions).GetProperty(
+            "CodeBackedListenOptions",
+            BindingFlags.Instance | BindingFlags.NonPublic);
+        Assert.NotNull(property);
+
+        var listenOptions = (IEnumerable)property!.GetValue(options)!;
+        var ports = new List<int>();
+        foreach (var listenOption in listenOptions)
+        {
+            if (listenOption.GetType().GetProperty("IPEndPoint")?.GetValue(listenOption) is IPEndPoint endpoint)
+            {
+                ports.Add(endpoint.Port);
+            }
+        }
+
+        return ports;
+    }
+}

dotnet/tests/Microsoft.Agents.AI.Hosting.A2A.UnitTests/A2AAgentHandlerTests.cs

@@ -18,6 +18,11 @@ namespace Microsoft.Agents.AI.Hosting.A2A.UnitTests;
 /// </summary>
 public sealed class A2AAgentHandlerTests
 {
+    /// <summary>
+    /// The <see cref="AgentRunOptions.AdditionalProperties"/> key the handler forwards the A2A configuration under.
+    /// </summary>
+    private const string ConfigurationPropertyKey = "a2a.configuration";
+
     /// <summary>
     /// Verifies that when metadata is null, the options passed to RunAsync have
     /// AllowBackgroundResponses disabled and no AdditionalProperties.
@@ -72,6 +77,93 @@ public sealed class A2AAgentHandlerTests
         Assert.Equal("value1", capturedOptions.AdditionalProperties["key1"]?.ToString());
     }
 
+    /// <summary>
+    /// Verifies that when the caller supplies a <c>MessageSendParams.configuration</c>, it is forwarded to the
+    /// agent through <see cref="AgentRunOptions.AdditionalProperties"/>.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_WhenConfigurationIsProvided_ForwardsConfigurationToRunAsync()
+    {
+        // Arrange
+        AgentRunOptions? capturedOptions = null;
+        A2AAgentHandler handler = CreateHandler(CreateAgentMock(options => capturedOptions = options));
+        SendMessageConfiguration configuration = new()
+        {
+            AcceptedOutputModes = ["text/plain", "image/png"],
+            HistoryLength = 10
+        };
+
+        // Act
+        await InvokeExecuteAsync(handler, new RequestContext
+        {
+            TaskId = "", ContextId = "ctx", StreamingResponse = false,
+            Message = new Message { MessageId = "test-id", Role = Role.User, Parts = [new Part { Text = "Hello" }] },
+            Configuration = configuration
+        });
+
+        // Assert
+        Assert.NotNull(capturedOptions);
+        Assert.NotNull(capturedOptions.AdditionalProperties);
+        Assert.Same(configuration, Assert.Single(capturedOptions.AdditionalProperties).Value);
+        Assert.Equal(ConfigurationPropertyKey, Assert.Single(capturedOptions.AdditionalProperties).Key);
+    }
+
+    /// <summary>
+    /// Verifies that the caller supplied configuration and metadata are both forwarded to the agent.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_WhenConfigurationAndMetadataAreProvided_ForwardsBothToRunAsync()
+    {
+        // Arrange
+        AgentRunOptions? capturedOptions = null;
+        A2AAgentHandler handler = CreateHandler(CreateAgentMock(options => capturedOptions = options));
+        SendMessageConfiguration configuration = new() { HistoryLength = 5 };
+
+        // Act
+        await InvokeExecuteAsync(handler, new RequestContext
+        {
+            TaskId = "", ContextId = "ctx", StreamingResponse = false,
+            Message = new Message { MessageId = "test-id", Role = Role.User, Parts = [new Part { Text = "Hello" }] },
+            Metadata = new Dictionary<string, JsonElement>
+            {
+                ["key1"] = JsonSerializer.SerializeToElement("value1")
+            },
+            Configuration = configuration
+        });
+
+        // Assert
+        Assert.NotNull(capturedOptions);
+        Assert.NotNull(capturedOptions.AdditionalProperties);
+        Assert.Equal(2, capturedOptions.AdditionalProperties.Count);
+        Assert.Equal("value1", capturedOptions.AdditionalProperties["key1"]?.ToString());
+        Assert.Same(configuration, capturedOptions.AdditionalProperties[ConfigurationPropertyKey]);
+    }
+
+    /// <summary>
+    /// Verifies that the caller supplied configuration does not override the run mode configured on the server.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_WhenConfigurationRequestsImmediateReturn_DoesNotOverrideRunModeAsync()
+    {
+        // Arrange
+        AgentRunOptions? capturedOptions = null;
+        A2AAgentHandler handler = CreateHandler(
+            CreateAgentMock(options => capturedOptions = options),
+            runMode: AgentRunMode.DisallowBackground);
+
+        // Act
+        await InvokeExecuteAsync(handler, new RequestContext
+        {
+            TaskId = "", ContextId = "ctx", StreamingResponse = false,
+            Message = new Message { MessageId = "test-id", Role = Role.User, Parts = [new Part { Text = "Hello" }] },
+            Configuration = new SendMessageConfiguration { ReturnImmediately = true }
+        });
+
+        // Assert
+        Assert.NotNull(capturedOptions);
+        Assert.False(capturedOptions.AllowBackgroundResponses);
+    }
+
     /// <summary>
     /// Verifies that when the agent response has AdditionalProperties, the returned Message.Metadata contains the converted values.
     /// </summary>
@@ -672,6 +764,36 @@ public sealed class A2AAgentHandlerTests
         Assert.Null(capturedOptions);
     }
 
+    /// <summary>
+    /// Verifies that in streaming mode, when only a configuration is present, options carrying the
+    /// configuration are passed to RunStreamingAsync.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_Streaming_WithConfiguration_PassesOptionsWithConfigurationAsync()
+    {
+        // Arrange
+        AgentRunOptions? capturedOptions = null;
+        A2AAgentHandler handler = CreateHandler(CreateStreamingAgentMockWithOptionsCapture(
+            options => capturedOptions = options));
+        SendMessageConfiguration configuration = new() { AcceptedOutputModes = ["text/plain"] };
+
+        // Act
+        await InvokeExecuteAsync(handler, new RequestContext
+        {
+            StreamingResponse = true,
+            TaskId = "",
+            ContextId = "ctx",
+            Message = new Message { MessageId = "test-id", Role = Role.User, Parts = [new Part { Text = "Hello" }] },
+            Configuration = configuration
+        });
+
+        // Assert
+        Assert.NotNull(capturedOptions);
+        Assert.Null(capturedOptions.AllowBackgroundResponses);
+        Assert.NotNull(capturedOptions.AdditionalProperties);
+        Assert.Same(configuration, capturedOptions.AdditionalProperties[ConfigurationPropertyKey]);
+    }
+
     /// <summary>
     /// Verifies that in streaming mode, ReferenceTaskIds throws NotSupportedException.
     /// </summary>

dotnet/tests/Microsoft.Agents.AI.Hosting.OpenAI.IntegrationTests/AnthropicResponsesHostingLiveTests.cs

@@ -0,0 +1,96 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Linq;
+using System.Text.Json;
+using System.Threading.Tasks;
+using Anthropic;
+using Shared.IntegrationTests;
+
+namespace Microsoft.Agents.AI.Hosting.OpenAI.IntegrationTests;
+
+/// <summary>
+/// Live integration tests for the app-owned routing helper surface (<see cref="OpenAIResponses"/> plus
+/// <see cref="AgentSessionStore"/>) exercised against a real Anthropic model. The helper surface is
+/// provider-agnostic; these tests confirm the same consumption paths — request conversion, an agent run,
+/// response rendering, and multi-turn session continuity — behave correctly end to end when the hosted
+/// agent is backed by a non-OpenAI chat client.
+/// </summary>
+/// <remarks>
+/// Skipped unless the Anthropic configuration is present (<c>ANTHROPIC_API_KEY</c>), so runs without
+/// secrets stay green. The OpenAI-backed variant of these tests lives in
+/// <see cref="OpenAIResponsesHostingLiveTests"/>.
+/// </remarks>
+public sealed class AnthropicResponsesHostingLiveTests
+{
+    private static string? ApiKey => Environment.GetEnvironmentVariable(TestSettings.AnthropicApiKey);
+    private static string ModelName => Environment.GetEnvironmentVariable(TestSettings.AnthropicChatModelName) ?? "claude-haiku-4-5";
+
+    [Fact]
+    public async Task NonStreamingRun_RendersResponsesShapedPayloadAsync()
+    {
+        // Arrange
+        Assert.SkipWhen(string.IsNullOrEmpty(ApiKey), "ANTHROPIC_API_KEY is not configured; skipping live hosting test.");
+        AIAgent agent = CreateAgent();
+        AgentSessionStore sessionStore = new InMemoryAgentSessionStore();
+        JsonElement body = ParseBody("""{ "input": "Reply with exactly the word: apple" }""");
+
+        // Act
+        OpenAIResponsesRunRequest run = OpenAIResponses.ToAgentRunRequest(body);
+        string sessionStoreId = OpenAIResponses.GetSessionStoreId(run) ?? OpenAIResponses.CreateResponseId();
+        AgentSession session = await sessionStore.GetSessionAsync(agent, sessionStoreId);
+        string responseId = OpenAIResponses.CreateResponseId();
+        AgentResponse result = await agent.RunAsync(run.Messages, session, run.Options);
+        JsonElement payload = OpenAIResponses.WriteResponse(result, responseId, responseId);
+
+        // Assert
+        Assert.Equal(responseId, payload.GetProperty("id").GetString());
+        Assert.Equal("response", payload.GetProperty("object").GetString());
+        Assert.Contains("output", payload.EnumerateObject().Select(p => p.Name));
+    }
+
+    [Fact]
+    public async Task MultiTurn_ContinuesSessionAcrossTurnsAsync()
+    {
+        // Arrange
+        Assert.SkipWhen(string.IsNullOrEmpty(ApiKey), "ANTHROPIC_API_KEY is not configured; skipping live hosting test.");
+        AIAgent agent = CreateAgent();
+        AgentSessionStore sessionStore = new InMemoryAgentSessionStore();
+
+        // Act: first turn establishes context, second turn continues from the first response id.
+        string firstResponseId = await RunTurnAsync(agent, sessionStore, """{ "input": "Remember the number 7." }""");
+        JsonElement secondBody = ParseBody($$"""{ "input": "What number did I ask you to remember?", "previous_response_id": "{{firstResponseId}}" }""");
+        OpenAIResponsesRunRequest secondRun = OpenAIResponses.ToAgentRunRequest(secondBody);
+        string secondSessionStoreId = OpenAIResponses.GetSessionStoreId(secondRun)!;
+        AgentSession session = await sessionStore.GetSessionAsync(agent, secondSessionStoreId);
+        AgentResponse secondResult = await agent.RunAsync(secondRun.Messages, session, secondRun.Options);
+
+        // Assert: continuation succeeded and the model produced a textual answer.
+        Assert.Equal(secondSessionStoreId, firstResponseId);
+        Assert.False(string.IsNullOrWhiteSpace(secondResult.Text));
+    }
+
+    private static async Task<string> RunTurnAsync(AIAgent agent, AgentSessionStore sessionStore, string bodyJson)
+    {
+        JsonElement body = ParseBody(bodyJson);
+        OpenAIResponsesRunRequest run = OpenAIResponses.ToAgentRunRequest(body);
+        string sessionStoreId = OpenAIResponses.GetSessionStoreId(run) ?? OpenAIResponses.CreateResponseId();
+        AgentSession session = await sessionStore.GetSessionAsync(agent, sessionStoreId);
+        string responseId = OpenAIResponses.CreateResponseId();
+        _ = await agent.RunAsync(run.Messages, session, run.Options);
+        await sessionStore.SaveSessionAsync(agent, responseId, session);
+        return responseId;
+    }
+
+    private static ChatClientAgent CreateAgent() =>
+        new AnthropicClient { ApiKey = ApiKey }.AsAIAgent(
+            ModelName,
+            instructions: "You are a concise assistant.",
+            name: "assistant");
+
+    private static JsonElement ParseBody(string json)
+    {
+        using JsonDocument doc = JsonDocument.Parse(json);
+        return doc.RootElement.Clone();
+    }
+}

dotnet/tests/Microsoft.Agents.AI.Hosting.OpenAI.IntegrationTests/Microsoft.Agents.AI.Hosting.OpenAI.IntegrationTests.csproj

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

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

@@ -411,6 +411,150 @@ public class ChatClientAgent_ChatHistoryManagementTests
         Assert.Equal("ConvId", session!.ConversationId);
     }
 
+    /// <summary>
+    /// Regression test for https://github.com/microsoft/agent-framework/issues/6120.
+    /// When the service manages chat history server-side (returns a conversation id), the framework's
+    /// default in-memory chat history provider must not persist the messages, even on the first turn.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_DoesNotUseDefaultInMemoryChatHistoryProvider_WhenConversationIdReturnedAsync()
+    {
+        // Arrange
+        Mock<IChatClient> mockService = new();
+        mockService.Setup(
+            s => s.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>())).ReturnsAsync(new ChatResponse([new(ChatRole.Assistant, "response")]) { ConversationId = "ConvId" });
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            ChatOptions = new() { Instructions = "test instructions" },
+        });
+
+        // Act
+        ChatClientAgentSession? session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+        await agent.RunAsync([new(ChatRole.User, "test")], session);
+
+        // Assert
+        Assert.Equal("ConvId", session!.ConversationId);
+        var inMemoryProvider = Assert.IsType<InMemoryChatHistoryProvider>(agent.ChatHistoryProvider);
+        Assert.Empty(inMemoryProvider.GetMessages(session));
+    }
+
+    /// <summary>
+    /// Regression test for https://github.com/microsoft/agent-framework/issues/6120.
+    /// The streaming path must also refrain from populating the default in-memory chat history provider
+    /// when the service returns a conversation id.
+    /// </summary>
+    [Fact]
+    public async Task RunStreamingAsync_DoesNotUseDefaultInMemoryChatHistoryProvider_WhenConversationIdReturnedAsync()
+    {
+        // Arrange
+        ChatResponseUpdate[] returnUpdates =
+            [
+                new ChatResponseUpdate(role: ChatRole.Assistant, content: "response") { ConversationId = "ConvId" },
+            ];
+        Mock<IChatClient> mockService = new();
+        mockService.Setup(
+            s => s.GetStreamingResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>())).Returns(returnUpdates.ToAsyncEnumerable());
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            ChatOptions = new() { Instructions = "test instructions" },
+        });
+
+        // Act
+        ChatClientAgentSession? session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+        await foreach (var _ in agent.RunStreamingAsync([new(ChatRole.User, "test")], session))
+        {
+        }
+
+        // Assert
+        Assert.Equal("ConvId", session!.ConversationId);
+        var inMemoryProvider = Assert.IsType<InMemoryChatHistoryProvider>(agent.ChatHistoryProvider);
+        Assert.Empty(inMemoryProvider.GetMessages(session));
+    }
+
+    /// <summary>
+    /// Regression test for https://github.com/microsoft/agent-framework/issues/6120.
+    /// Across multiple turns backed by service-stored history, the default in-memory chat history provider
+    /// is never populated and prior turns are not replayed to the service (the service owns the history).
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_MultiTurnServiceStoredHistory_DoesNotPopulateDefaultInMemoryProviderAsync()
+    {
+        // Arrange
+        var capturedInputs = new List<List<ChatMessage>>();
+        Mock<IChatClient> mockService = new();
+        mockService.Setup(
+            s => s.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>()))
+            .Returns<IEnumerable<ChatMessage>, ChatOptions?, CancellationToken>((msgs, _, _) =>
+            {
+                capturedInputs.Add(msgs.ToList());
+                return Task.FromResult(new ChatResponse([new(ChatRole.Assistant, "response")]) { ConversationId = "ConvId" });
+            });
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            ChatOptions = new() { Instructions = "test instructions" },
+        });
+
+        // Act
+        ChatClientAgentSession? session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+        await agent.RunAsync([new(ChatRole.User, "first")], session);
+        await agent.RunAsync([new(ChatRole.User, "second")], session);
+
+        // Assert
+        Assert.Equal("ConvId", session!.ConversationId);
+        var inMemoryProvider = Assert.IsType<InMemoryChatHistoryProvider>(agent.ChatHistoryProvider);
+        Assert.Empty(inMemoryProvider.GetMessages(session));
+
+        // The second turn should only send the new user message, since the service owns the history.
+        Assert.Equal(2, capturedInputs.Count);
+        Assert.Single(capturedInputs[1]);
+        Assert.Equal("second", capturedInputs[1][0].Text);
+    }
+
+    /// <summary>
+    /// When the service manages chat history server-side (returns a conversation id), an explicitly-configured
+    /// chat history provider is disengaged just like the default provider, even when all conflict handling is
+    /// disabled. This pins the uniform "service storage disengages any provider" semantics.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_ExplicitChatHistoryProvider_Disengaged_WhenConflictHandlingDisabledAndConversationIdReturnedAsync()
+    {
+        // Arrange
+        Mock<IChatClient> mockService = new();
+        mockService.Setup(
+            s => s.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>())).ReturnsAsync(new ChatResponse([new(ChatRole.Assistant, "response")]) { ConversationId = "ConvId" });
+        var chatHistoryProvider = new InMemoryChatHistoryProvider();
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            ChatOptions = new() { Instructions = "test instructions" },
+            ChatHistoryProvider = chatHistoryProvider,
+            ThrowOnChatHistoryProviderConflict = false,
+            ClearOnChatHistoryProviderConflict = false,
+            WarnOnChatHistoryProviderConflict = false,
+        });
+
+        // Act
+        ChatClientAgentSession? session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+        await agent.RunAsync([new(ChatRole.User, "test")], session);
+
+        // Assert — the provider reference is retained (conflict handling disabled), but it is not persisted to
+        // because the service stores history.
+        Assert.Equal("ConvId", session!.ConversationId);
+        Assert.Same(chatHistoryProvider, agent.ChatHistoryProvider);
+        Assert.Empty(chatHistoryProvider.GetMessages(session));
+    }
+
     #endregion
 
     #region ChatHistoryProvider Override Tests

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

@@ -1962,8 +1962,165 @@ public class ToolApprovalAgentTests
     }
 
     /// <summary>
-    /// Verify that when auto-approval rule does not match, request is surfaced to the caller.
+    /// Verify that when no session is supplied, the agent creates one and threads it to the inner
+    /// agent across auto-approval re-invocations. Without a session, the inner agent would receive
+    /// only the injected approval response (with no history) on the second call, producing an empty
+    /// request to the underlying service (repro for issue #7210).
     /// </summary>
+    [Fact]
+    public async Task RunAsync_AutoApprovalRule_NoSession_CreatesAndThreadsSessionAsync()
+    {
+        // Arrange
+        var createdSession = new ChatClientAgentSession();
+        var approvalRequest = new ToolApprovalRequestContent("req1", new FunctionCallContent("call1", "ReadTool"));
+
+        var capturedSessions = new List<AgentSession?>();
+        var callCount = 0;
+        var innerAgent = new Mock<AIAgent>();
+        innerAgent
+            .Protected()
+            .Setup<ValueTask<AgentSession>>("CreateSessionCoreAsync", ItExpr.IsAny<CancellationToken>())
+            .Returns(new ValueTask<AgentSession>(createdSession));
+        innerAgent
+            .Protected()
+            .Setup<Task<AgentResponse>>("RunCoreAsync",
+                ItExpr.IsAny<IEnumerable<ChatMessage>>(),
+                ItExpr.IsAny<AgentSession?>(),
+                ItExpr.IsAny<AgentRunOptions?>(),
+                ItExpr.IsAny<CancellationToken>())
+            .Callback<IEnumerable<ChatMessage>, AgentSession?, AgentRunOptions?, CancellationToken>(
+                (_, session, _, _) => capturedSessions.Add(session))
+            .ReturnsAsync(() =>
+            {
+                callCount++;
+                if (callCount == 1)
+                {
+                    return new AgentResponse([new ChatMessage(ChatRole.Assistant, [approvalRequest])]);
+                }
+
+                return new AgentResponse([new ChatMessage(ChatRole.Assistant, "Done")]);
+            });
+
+        var options = new ToolApprovalAgentOptions
+        {
+            AutoApprovalRules = [ToolApprovalAgent.AllToolsAutoApprovalRule]
+        };
+        var agent = new ToolApprovalAgent(innerAgent.Object, options);
+
+        // Act — invoke WITHOUT a session.
+        var response = await agent.RunAsync([new ChatMessage(ChatRole.User, "Hi")]);
+
+        // Assert — auto-approval re-invoked the inner agent, and both calls received the same,
+        // non-null session so conversation history is preserved across the re-invocation.
+        Assert.Equal(2, callCount);
+        Assert.Equal("Done", response.Text);
+        Assert.Equal(2, capturedSessions.Count);
+        Assert.All(capturedSessions, s => Assert.Same(createdSession, s));
+    }
+
+    /// <summary>
+    /// Streaming counterpart of <see cref="RunAsync_AutoApprovalRule_NoSession_CreatesAndThreadsSessionAsync"/>:
+    /// when no session is supplied, the streaming path also creates one and threads it to the inner
+    /// agent across auto-approval re-invocations.
+    /// </summary>
+    [Fact]
+    public async Task RunStreamingAsync_AutoApprovalRule_NoSession_CreatesAndThreadsSessionAsync()
+    {
+        // Arrange
+        var createdSession = new ChatClientAgentSession();
+        var approvalRequest = new ToolApprovalRequestContent("req1", new FunctionCallContent("call1", "ReadTool"));
+
+        var capturedSessions = new List<AgentSession?>();
+        var callCount = 0;
+        var innerAgent = new Mock<AIAgent>();
+        innerAgent
+            .Protected()
+            .Setup<ValueTask<AgentSession>>("CreateSessionCoreAsync", ItExpr.IsAny<CancellationToken>())
+            .Returns(new ValueTask<AgentSession>(createdSession));
+        innerAgent
+            .Protected()
+            .Setup<IAsyncEnumerable<AgentResponseUpdate>>("RunCoreStreamingAsync",
+                ItExpr.IsAny<IEnumerable<ChatMessage>>(),
+                ItExpr.IsAny<AgentSession?>(),
+                ItExpr.IsAny<AgentRunOptions?>(),
+                ItExpr.IsAny<CancellationToken>())
+            .Returns<IEnumerable<ChatMessage>, AgentSession?, AgentRunOptions?, CancellationToken>(
+                (_, session, _, ct) =>
+                {
+                    capturedSessions.Add(session);
+                    callCount++;
+                    AgentResponseUpdate[] streamUpdates = callCount == 1
+                        ? [new AgentResponseUpdate(ChatRole.Assistant, [approvalRequest])]
+                        : [new AgentResponseUpdate(ChatRole.Assistant, "Done")];
+                    return ToAsyncEnumerableAsync(streamUpdates, ct);
+                });
+
+        var options = new ToolApprovalAgentOptions
+        {
+            AutoApprovalRules = [ToolApprovalAgent.AllToolsAutoApprovalRule]
+        };
+        var agent = new ToolApprovalAgent(innerAgent.Object, options);
+
+        // Act — invoke WITHOUT a session.
+        var updates = new List<AgentResponseUpdate>();
+        await foreach (var update in agent.RunStreamingAsync([new ChatMessage(ChatRole.User, "Hi")]))
+        {
+            updates.Add(update);
+        }
+
+        // Assert — both inner calls received the same, non-null session.
+        Assert.Equal(2, callCount);
+        Assert.Equal("Done", string.Concat(updates.Select(u => u.Text)));
+        Assert.Equal(2, capturedSessions.Count);
+        Assert.All(capturedSessions, s => Assert.Same(createdSession, s));
+    }
+
+    /// <summary>
+    /// Verify that when no session is supplied, the agent creates exactly one session and threads
+    /// it to the inner agent, even when no approval re-invocation is needed.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_NoApprovalRequest_NoSession_CreatesSingleSessionAsync()
+    {
+        // Arrange
+        var createdSession = new ChatClientAgentSession();
+        var createSessionCallCount = 0;
+        var capturedSessions = new List<AgentSession?>();
+        var innerAgent = new Mock<AIAgent>();
+        innerAgent
+            .Protected()
+            .Setup<ValueTask<AgentSession>>("CreateSessionCoreAsync", ItExpr.IsAny<CancellationToken>())
+            .Returns(() =>
+            {
+                createSessionCallCount++;
+                return new ValueTask<AgentSession>(createdSession);
+            });
+        innerAgent
+            .Protected()
+            .Setup<Task<AgentResponse>>("RunCoreAsync",
+                ItExpr.IsAny<IEnumerable<ChatMessage>>(),
+                ItExpr.IsAny<AgentSession?>(),
+                ItExpr.IsAny<AgentRunOptions?>(),
+                ItExpr.IsAny<CancellationToken>())
+            .Callback<IEnumerable<ChatMessage>, AgentSession?, AgentRunOptions?, CancellationToken>(
+                (_, session, _, _) => capturedSessions.Add(session))
+            .ReturnsAsync(new AgentResponse([new ChatMessage(ChatRole.Assistant, "Done")]));
+
+        var agent = new ToolApprovalAgent(innerAgent.Object, new ToolApprovalAgentOptions
+        {
+            AutoApprovalRules = [ToolApprovalAgent.AllToolsAutoApprovalRule]
+        });
+
+        // Act
+        var response = await agent.RunAsync([new ChatMessage(ChatRole.User, "Hi")]);
+
+        // Assert — a single session was created and threaded to the inner agent.
+        Assert.Equal("Done", response.Text);
+        Assert.Equal(1, createSessionCallCount);
+        Assert.Single(capturedSessions);
+        Assert.Same(createdSession, capturedSessions[0]);
+    }
+
     [Fact]
     public async Task RunAsync_AutoApprovalRule_DoesNotMatchSurfacesToCallerAsync()
     {

dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Extensions/PortableValueExtensionsTests.cs

@@ -4,6 +4,8 @@ using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Net;
+using System.Threading;
+using System.Threading.Tasks;
 using Microsoft.Agents.AI.Workflows.Declarative.Extensions;
 using Microsoft.Agents.AI.Workflows.Declarative.Kit;
 using Microsoft.Agents.AI.Workflows.Declarative.PowerFx;
@@ -84,6 +86,97 @@ public sealed class PortableValueExtensionsTests
         Assert.Equal("input", textValue.Value);
     }
 
+    [Fact]
+    public void TableAsPortableUsesLegacyArrayShape()
+    {
+        // Arrange
+        RecordType recordType = RecordType.Empty().Add("Id", FormulaType.Decimal);
+        RecordValue record =
+            FormulaValue.NewRecordFromFields(
+                recordType,
+                new NamedValue("Id", FormulaValue.New(1)));
+        TableValue source = FormulaValue.NewTable(recordType, record);
+
+        // Act
+        object result = source.AsPortable();
+
+        // Assert
+        Assert.IsType<PortableValue[]>(result);
+    }
+
+    [Fact]
+    public void RecordAsPortableUsesLegacyDictionaryShape()
+    {
+        // Arrange
+        RecordValue source =
+            FormulaValue.NewRecordFromFields(
+                new NamedValue("Id", FormulaValue.New(1)));
+
+        // Act
+        object result = source.AsPortable();
+
+        // Assert
+        Assert.IsAssignableFrom<IDictionary<string, PortableValue>>(result);
+    }
+
+    [Fact]
+    public async Task LegacyRecordTableSupportsAppendAsync()
+    {
+        // Arrange
+        Dictionary<string, decimal>[] source = [new() { ["Id"] = 1 }];
+        TableValue restored = Assert.IsAssignableFrom<TableValue>(new PortableValue(source.AsPortable()).ToFormula());
+        RecordType recordType = restored.Type.ToRecord();
+        RecordValue newRecord =
+            FormulaValue.NewRecordFromFields(
+                recordType,
+                new NamedValue("Id", FormulaValue.New(2)));
+
+        // Act
+        await restored.AppendAsync(newRecord, CancellationToken.None);
+
+        // Assert
+        Assert.Equal(2, restored.Rows.Count());
+    }
+
+    [Fact]
+    public async Task LegacyPrimitiveTableSupportsAppendAsync()
+    {
+        // Arrange
+        string[] source = ["one"];
+        TableValue restored = Assert.IsAssignableFrom<TableValue>(new PortableValue(source.AsPortable()).ToFormula());
+        RecordType recordType = restored.Type.ToRecord();
+        RecordValue newRecord =
+            FormulaValue.NewRecordFromFields(
+                recordType,
+                new NamedValue("Value", FormulaValue.New("two")));
+
+        // Act
+        await restored.AppendAsync(newRecord, CancellationToken.None);
+
+        // Assert
+        string[] values = restored.Rows
+            .Select(row => Assert.IsType<StringValue>(row.Value.GetField("Value")).Value)
+            .ToArray();
+        Assert.Equal(["one", "two"], values);
+    }
+
+    [Theory]
+    [InlineData(false)]
+    [InlineData(true)]
+    public void LegacyDateTablePreservesFormulaType(bool includeTime)
+    {
+        // Arrange
+        DateTime value = new(2026, 7, 27, includeTime ? 12 : 0, 0, 0, DateTimeKind.Utc);
+
+        // Act
+        TableValue restored = Assert.IsAssignableFrom<TableValue>(new PortableValue(new[] { value }.AsPortable()).ToFormula());
+
+        // Assert
+        FormulaType expectedType = includeTime ? FormulaType.DateTime : FormulaType.Date;
+        Assert.Equal(expectedType, restored.Type.GetFieldType("Value"));
+        Assert.Equal(expectedType, Assert.Single(restored.Rows).Value.GetField("Value").Type);
+    }
+
     [Fact]
     public void DictionaryType()
     {

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

@@ -1,9 +1,15 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using System;
+using System.Collections.Generic;
 using System.Linq;
+using System.Text.Json;
 using System.Threading;
 using System.Threading.Tasks;
+using Microsoft.Agents.AI.Workflows.Checkpointing;
+using Microsoft.Agents.AI.Workflows.Declarative.Extensions;
 using Microsoft.Agents.AI.Workflows.Declarative.ObjectModel;
+using Microsoft.Agents.AI.Workflows.Declarative.PowerFx;
 using Microsoft.Agents.ObjectModel;
 using Microsoft.PowerFx.Types;
 
@@ -31,13 +37,47 @@ public sealed class EditTableExecutorTest(ITestOutputHelper output) : WorkflowAc
             displayName: nameof(AddItemToTableAsync),
             variableName: "MyTable",
             changeType: TableChangeType.Add,
-            value: new RecordDataValue([new("id", new NumberDataValue(7))]));
+            value: new RecordDataValue([new("id", new NumberDataValue(7))]),
+            resultVariableName: "Result");
 
-        // Verify the variable now contains the added record
+        // Verify the variable remains a table containing the added record
         FormulaValue resultValue = this.State.Get("MyTable");
-        RecordValue resultRecord = Assert.IsAssignableFrom<RecordValue>(resultValue);
-        DecimalValue idValue = Assert.IsType<DecimalValue>(resultRecord.GetField("id"));
+        TableValue resultTable = Assert.IsAssignableFrom<TableValue>(resultValue);
+        Assert.Equal(2, resultTable.Rows.Count());
+        DecimalValue idValue = Assert.IsType<DecimalValue>(resultTable.Rows.Last().Value.GetField("id"));
         Assert.Equal(7, idValue.Value);
+        Assert.Equal(7, Assert.IsType<DecimalValue>(
+            Assert.IsAssignableFrom<RecordValue>(this.State.Get("Result")).GetField("id")).Value);
+    }
+
+    [Fact]
+    public async Task ConsecutiveAddsPreserveTableAsync()
+    {
+        // Arrange
+        FormulaValue tableValue = this.State.Engine.Eval("[{id: 1}]");
+        this.State.Set("MyTable", tableValue);
+
+        EditTable firstAdd = this.CreateModel(
+            nameof(ConsecutiveAddsPreserveTableAsync),
+            "MyTable",
+            TableChangeType.Add,
+            new RecordDataValue([new("id", new NumberDataValue(2))]));
+        EditTable secondAdd = this.CreateModel(
+            nameof(ConsecutiveAddsPreserveTableAsync),
+            "MyTable",
+            TableChangeType.Add,
+            new RecordDataValue([new("id", new NumberDataValue(3))]));
+
+        // Act
+        await this.ExecuteAsync(new EditTableExecutor(firstAdd, this.State));
+        await this.ExecuteAsync(new EditTableExecutor(secondAdd, this.State));
+
+        // Assert
+        TableValue resultTable = Assert.IsAssignableFrom<TableValue>(this.State.Get("MyTable"));
+        decimal[] ids = resultTable.Rows
+            .Select(row => Assert.IsType<DecimalValue>(row.Value.GetField("id")).Value)
+            .ToArray();
+        Assert.Equal([1, 2, 3], ids);
     }
 
     [Fact]
@@ -57,9 +97,11 @@ public sealed class EditTableExecutorTest(ITestOutputHelper output) : WorkflowAc
                 new("name", new StringDataValue("Second"))
             ]));
 
-        // Verify the variable now contains the added record
+        // Verify the variable remains a table containing the added record
         FormulaValue resultValue = this.State.Get("MyTable");
-        RecordValue resultRecord = Assert.IsAssignableFrom<RecordValue>(resultValue);
+        TableValue resultTable = Assert.IsAssignableFrom<TableValue>(resultValue);
+        Assert.Equal(2, resultTable.Rows.Count());
+        RecordValue resultRecord = resultTable.Rows.Last().Value;
         DecimalValue idValue = Assert.IsType<DecimalValue>(resultRecord.GetField("id"));
         Assert.Equal(2, idValue.Value);
         StringValue nameValue = Assert.IsType<StringValue>(resultRecord.GetField("name"));
@@ -83,9 +125,10 @@ public sealed class EditTableExecutorTest(ITestOutputHelper output) : WorkflowAc
             changeType: TableChangeType.Add,
             value: new RecordDataValue([new("id", new NumberDataValue(1))]));
 
-        // Verify the variable now contains the added record
+        // Verify the variable remains a table containing the added record
         FormulaValue resultValue = this.State.Get("MyTable");
-        RecordValue resultRecord = Assert.IsAssignableFrom<RecordValue>(resultValue);
+        TableValue resultTable = Assert.IsAssignableFrom<TableValue>(resultValue);
+        RecordValue resultRecord = Assert.Single(resultTable.Rows).Value;
         DecimalValue idValue = Assert.IsType<DecimalValue>(resultRecord.GetField("id"));
         Assert.Equal(1, idValue.Value);
     }
@@ -102,13 +145,14 @@ public sealed class EditTableExecutorTest(ITestOutputHelper output) : WorkflowAc
             displayName: nameof(RemoveItemFromTableAsync),
             variableName: "MyTable",
             changeType: TableChangeType.Remove,
-            value: new TableDataValue([new RecordDataValue([new("id", new NumberDataValue(3))])]));
+            value: new TableDataValue([new RecordDataValue([new("id", new NumberDataValue(3))])]),
+            resultVariableName: "Result");
 
-        // Verify the variable now contains an empty record
-        FormulaValue resultValue = this.State.Get("MyTable");
-        RecordValue resultRecord = Assert.IsAssignableFrom<RecordValue>(resultValue);
-        // Empty record should have no fields
-        Assert.Empty(resultRecord.Fields);
+        // Assert
+        TableValue resultTable = Assert.IsAssignableFrom<TableValue>(this.State.Get("MyTable"));
+        DecimalValue idValue = Assert.IsType<DecimalValue>(Assert.Single(resultTable.Rows).Value.GetField("id"));
+        Assert.Equal(7, idValue.Value);
+        Assert.Empty(Assert.IsAssignableFrom<RecordValue>(this.State.Get("Result")).Fields);
     }
 
     [Fact]
@@ -128,11 +172,39 @@ public sealed class EditTableExecutorTest(ITestOutputHelper output) : WorkflowAc
                 new RecordDataValue([new("id", new NumberDataValue(3))])
             ]));
 
-        // Verify the variable now contains an empty record
-        FormulaValue resultValue = this.State.Get("MyTable");
-        RecordValue resultRecord = Assert.IsAssignableFrom<RecordValue>(resultValue);
-        // Empty record should have no fields
-        Assert.Empty(resultRecord.Fields);
+        // Assert
+        TableValue resultTable = Assert.IsAssignableFrom<TableValue>(this.State.Get("MyTable"));
+        DecimalValue idValue = Assert.IsType<DecimalValue>(Assert.Single(resultTable.Rows).Value.GetField("id"));
+        Assert.Equal(2, idValue.Value);
+    }
+
+    [Fact]
+    public async Task RemoveAllThenRestoreThenAddPreservesTableAsync()
+    {
+        // Arrange
+        this.State.Set("MyTable", this.State.Engine.Eval("[{id: 1}, {id: 2}]"));
+        EditTable removeAction = this.CreateModel(
+            nameof(RemoveAllThenRestoreThenAddPreservesTableAsync),
+            "MyTable",
+            TableChangeType.Remove,
+            new TableDataValue([
+                new RecordDataValue([new("id", new NumberDataValue(1))]),
+                new RecordDataValue([new("id", new NumberDataValue(2))])
+            ]));
+        EditTable addAction = this.CreateModel(
+            nameof(RemoveAllThenRestoreThenAddPreservesTableAsync),
+            "MyTable",
+            TableChangeType.Add,
+            new RecordDataValue([new("id", new NumberDataValue(3))]));
+
+        // Act
+        await this.ExecuteAsync(new EditTableExecutor(removeAction, this.State));
+        this.State.Set("MyTable", new PortableValue(this.State.Get("MyTable").AsPortable()).ToFormula());
+        await this.ExecuteAsync(new EditTableExecutor(addAction, this.State));
+
+        // Assert
+        TableValue resultTable = Assert.IsAssignableFrom<TableValue>(this.State.Get("MyTable"));
+        Assert.Equal(3, Assert.IsType<DecimalValue>(Assert.Single(resultTable.Rows).Value.GetField("id")).Value);
     }
 
     [Fact]
@@ -147,11 +219,14 @@ public sealed class EditTableExecutorTest(ITestOutputHelper output) : WorkflowAc
             displayName: nameof(ClearTableAsync),
             variableName: "MyTable",
             changeType: TableChangeType.Clear,
-            value: null);
+            value: null,
+            resultVariableName: "Result");
 
-        // Verify table is cleared
-        FormulaValue resultValue = this.State.Get("MyTable");
-        Assert.IsType<BlankValue>(resultValue);
+        // Assert
+        TableValue resultTable = Assert.IsAssignableFrom<TableValue>(this.State.Get("MyTable"));
+        Assert.Empty(resultTable.Rows);
+        Assert.Equal(FormulaType.Decimal, resultTable.Type.GetFieldType("id"));
+        Assert.IsType<BlankValue>(this.State.Get("Result"));
     }
 
     [Fact]
@@ -171,9 +246,100 @@ public sealed class EditTableExecutorTest(ITestOutputHelper output) : WorkflowAc
             changeType: TableChangeType.Clear,
             value: null);
 
-        // Verify table is blank
-        FormulaValue resultValue = this.State.Get("MyTable");
-        Assert.IsType<BlankValue>(resultValue);
+        // Assert
+        TableValue resultTable = Assert.IsAssignableFrom<TableValue>(this.State.Get("MyTable"));
+        Assert.Empty(resultTable.Rows);
+        Assert.Equal(FormulaType.Decimal, resultTable.Type.GetFieldType("id"));
+    }
+
+    [Fact]
+    public async Task ClearThenRestoreThenAddPreservesTableAsync()
+    {
+        // Arrange
+        this.State.Set("MyTable", this.State.Engine.Eval("[{id: 1}, {id: 2}]"));
+        EditTable clearAction = this.CreateModel(
+            nameof(ClearThenRestoreThenAddPreservesTableAsync),
+            "MyTable",
+            TableChangeType.Clear,
+            value: null);
+        EditTable addAction = this.CreateModel(
+            nameof(ClearThenRestoreThenAddPreservesTableAsync),
+            "MyTable",
+            TableChangeType.Add,
+            new RecordDataValue([new("id", new NumberDataValue(3))]));
+
+        // Act
+        await this.ExecuteAsync(new EditTableExecutor(clearAction, this.State));
+        this.State.Set("MyTable", new PortableValue(this.State.Get("MyTable").AsPortable()).ToFormula());
+        await this.ExecuteAsync(new EditTableExecutor(addAction, this.State));
+
+        // Assert
+        TableValue resultTable = Assert.IsAssignableFrom<TableValue>(this.State.Get("MyTable"));
+        DecimalValue idValue = Assert.IsType<DecimalValue>(Assert.Single(resultTable.Rows).Value.GetField("id"));
+        Assert.Equal(3, idValue.Value);
+    }
+
+    [Fact]
+    public async Task ClearThenCheckpointResumeThenAddPreservesTableAsync()
+    {
+        // Arrange
+        EditTable clearModel = this.CreateModel(
+            nameof(ClearThenCheckpointResumeThenAddPreservesTableAsync),
+            "MyTable",
+            TableChangeType.Clear,
+            value: null);
+        EditTable addModel = this.CreateModel(
+            nameof(ClearThenCheckpointResumeThenAddPreservesTableAsync),
+            "MyTable",
+            TableChangeType.Add,
+            new RecordDataValue([new("id", new NumberDataValue(3))]));
+
+        WorkflowFormulaState firstState = new(RecalcEngineFactory.Create());
+        firstState.Set("MyTable", firstState.Engine.Eval("[{id: 1}, {id: 2}]"));
+        Workflow firstWorkflow = BuildWorkflow(firstState);
+
+        InMemoryJsonStore store = new();
+        CheckpointManager checkpointManager = CheckpointManager.CreateJson(store, DeclarativeWorkflowJsonOptions.Default);
+        List<CheckpointInfo> checkpoints = [];
+
+        await using (StreamingRun run = await InProcessExecution.RunStreamingAsync(firstWorkflow, firstState, checkpointManager))
+        {
+            await foreach (WorkflowEvent evt in run.WatchStreamAsync())
+            {
+                if (evt is SuperStepCompletedEvent { CompletionInfo.Checkpoint: { } checkpoint })
+                {
+                    checkpoints.Add(checkpoint);
+                }
+            }
+        }
+        Assert.True(checkpoints.Count >= 3);
+
+        WorkflowFormulaState resumedState = new(RecalcEngineFactory.Create());
+        Workflow resumedWorkflow = BuildWorkflow(resumedState);
+
+        // Act
+        await using (StreamingRun run = await InProcessExecution.ResumeStreamingAsync(resumedWorkflow, checkpoints[^2], checkpointManager))
+        {
+            await foreach (WorkflowEvent _ in run.WatchStreamAsync())
+            {
+            }
+        }
+
+        // Assert
+        TableValue resultTable = Assert.IsAssignableFrom<TableValue>(resumedState.Get("MyTable"));
+        Assert.Equal(3, Assert.IsType<DecimalValue>(Assert.Single(resultTable.Rows).Value.GetField("id")).Value);
+
+        Workflow BuildWorkflow(WorkflowFormulaState state)
+        {
+            TestWorkflowExecutor root = new();
+            EditTableExecutor clearAction = new(clearModel, state);
+            EditTableExecutor addAction = new(addModel, state);
+            return
+                new WorkflowBuilder(root)
+                    .AddEdge(root, clearAction)
+                    .AddEdge(clearAction, addAction)
+                    .Build();
+        }
     }
 
     [Fact]
@@ -183,18 +349,25 @@ public sealed class EditTableExecutorTest(ITestOutputHelper output) : WorkflowAc
         FormulaValue tableValue = this.State.Engine.Eval("[{id: 10}, {id: 20}, {id: 30}]");
         this.State.Set("MyTable", tableValue);
 
-        // Act, Assert
-        await this.ExecuteTestAsync(
-            displayName: nameof(TakeFirstItemAsync),
+        EditTable model = this.CreateModel(
+            nameof(TakeFirstItemAsync),
             variableName: "MyTable",
             changeType: TableChangeType.TakeFirst,
-            value: null);
+            value: null,
+            resultVariableName: "TakenItem");
 
-        // Verify the variable now contains the first record that was taken
-        FormulaValue resultValue = this.State.Get("MyTable");
-        RecordValue resultRecord = Assert.IsAssignableFrom<RecordValue>(resultValue);
-        DecimalValue idValue = Assert.IsType<DecimalValue>(resultRecord.GetField("id"));
-        Assert.Equal(10, idValue.Value);
+        // Act
+        await this.ExecuteAsync(new EditTableExecutor(model, this.State));
+
+        // Assert
+        TableValue resultTable = Assert.IsAssignableFrom<TableValue>(this.State.Get("MyTable"));
+        decimal[] ids = resultTable.Rows
+            .Select(row => Assert.IsType<DecimalValue>(row.Value.GetField("id")).Value)
+            .ToArray();
+        Assert.Equal([20, 30], ids);
+
+        RecordValue resultRecord = Assert.IsAssignableFrom<RecordValue>(this.State.Get("TakenItem"));
+        Assert.Equal(10, Assert.IsType<DecimalValue>(resultRecord.GetField("id")).Value);
     }
 
     [Fact]
@@ -206,18 +379,23 @@ public sealed class EditTableExecutorTest(ITestOutputHelper output) : WorkflowAc
         // Clear the table to make it empty but preserve schema
         await table.ClearAsync(CancellationToken.None);
         this.State.Set("MyTable", table);
+        this.State.Set("TakenItem", FormulaValue.NewRecordFromFields(new NamedValue("id", FormulaValue.New(99))));
 
-        // Act, Assert
-        await this.ExecuteTestAsync(
-            displayName: nameof(TakeFirstFromEmptyTableAsync),
+        EditTable model = this.CreateModel(
+            nameof(TakeFirstFromEmptyTableAsync),
             variableName: "MyTable",
             changeType: TableChangeType.TakeFirst,
-            value: null);
+            value: null,
+            resultVariableName: "TakenItem");
+
+        // Act
+        await this.ExecuteAsync(new EditTableExecutor(model, this.State));
 
         // Verify table is still empty (nothing was taken, variable remains unchanged)
         FormulaValue resultValue = this.State.Get("MyTable");
         TableValue resultTable = Assert.IsAssignableFrom<TableValue>(resultValue);
         Assert.Empty(resultTable.Rows);
+        Assert.IsType<BlankValue>(this.State.Get("TakenItem"));
     }
 
     [Fact]
@@ -227,18 +405,25 @@ public sealed class EditTableExecutorTest(ITestOutputHelper output) : WorkflowAc
         FormulaValue tableValue = this.State.Engine.Eval("[{id: 10}, {id: 20}, {id: 30}]");
         this.State.Set("MyTable", tableValue);
 
-        // Act, Assert
-        await this.ExecuteTestAsync(
-            displayName: nameof(TakeLastItemAsync),
+        EditTable model = this.CreateModel(
+            nameof(TakeLastItemAsync),
             variableName: "MyTable",
             changeType: TableChangeType.TakeLast,
-            value: null);
+            value: null,
+            resultVariableName: "TakenItem");
 
-        // Verify the variable now contains the last record that was taken
-        FormulaValue resultValue = this.State.Get("MyTable");
-        RecordValue resultRecord = Assert.IsAssignableFrom<RecordValue>(resultValue);
-        DecimalValue idValue = Assert.IsType<DecimalValue>(resultRecord.GetField("id"));
-        Assert.Equal(30, idValue.Value);
+        // Act
+        await this.ExecuteAsync(new EditTableExecutor(model, this.State));
+
+        // Assert
+        TableValue resultTable = Assert.IsAssignableFrom<TableValue>(this.State.Get("MyTable"));
+        decimal[] ids = resultTable.Rows
+            .Select(row => Assert.IsType<DecimalValue>(row.Value.GetField("id")).Value)
+            .ToArray();
+        Assert.Equal([10, 20], ids);
+
+        RecordValue resultRecord = Assert.IsAssignableFrom<RecordValue>(this.State.Get("TakenItem"));
+        Assert.Equal(30, Assert.IsType<DecimalValue>(resultRecord.GetField("id")).Value);
     }
 
     [Fact]
@@ -278,11 +463,9 @@ public sealed class EditTableExecutorTest(ITestOutputHelper output) : WorkflowAc
             changeType: TableChangeType.TakeFirst,
             value: null);
 
-        // Verify variable contains the record that was taken
-        FormulaValue resultValue = this.State.Get("MyTable");
-        RecordValue resultRecord = Assert.IsAssignableFrom<RecordValue>(resultValue);
-        DecimalValue idValue = Assert.IsType<DecimalValue>(resultRecord.GetField("id"));
-        Assert.Equal(100, idValue.Value);
+        // Assert
+        TableValue resultTable = Assert.IsAssignableFrom<TableValue>(this.State.Get("MyTable"));
+        Assert.Empty(resultTable.Rows);
     }
 
     [Fact]
@@ -299,11 +482,40 @@ public sealed class EditTableExecutorTest(ITestOutputHelper output) : WorkflowAc
             changeType: TableChangeType.TakeLast,
             value: null);
 
-        // Verify variable contains the record that was taken
-        FormulaValue resultValue = this.State.Get("MyTable");
-        RecordValue resultRecord = Assert.IsAssignableFrom<RecordValue>(resultValue);
-        DecimalValue idValue = Assert.IsType<DecimalValue>(resultRecord.GetField("id"));
-        Assert.Equal(100, idValue.Value);
+        // Assert
+        TableValue resultTable = Assert.IsAssignableFrom<TableValue>(this.State.Get("MyTable"));
+        Assert.Empty(resultTable.Rows);
+    }
+
+    [Fact]
+    public async Task TakeFirstThenAddPreservesTableAsync()
+    {
+        // Arrange
+        this.State.Set("MyTable", this.State.Engine.Eval("[{id: 1}, {id: 2}]"));
+        EditTable takeAction = this.CreateModel(
+            nameof(TakeFirstThenAddPreservesTableAsync),
+            "MyTable",
+            TableChangeType.TakeFirst,
+            value: null,
+            resultVariableName: "TakenItem");
+        EditTable addAction = this.CreateModel(
+            nameof(TakeFirstThenAddPreservesTableAsync),
+            "MyTable",
+            TableChangeType.Add,
+            new RecordDataValue([new("id", new NumberDataValue(3))]));
+
+        // Act
+        await this.ExecuteAsync(new EditTableExecutor(takeAction, this.State));
+        await this.ExecuteAsync(new EditTableExecutor(addAction, this.State));
+
+        // Assert
+        TableValue resultTable = Assert.IsAssignableFrom<TableValue>(this.State.Get("MyTable"));
+        decimal[] ids = resultTable.Rows
+            .Select(row => Assert.IsType<DecimalValue>(row.Value.GetField("id")).Value)
+            .ToArray();
+        Assert.Equal([2, 3], ids);
+        Assert.Equal(1, Assert.IsType<DecimalValue>(
+            Assert.IsAssignableFrom<RecordValue>(this.State.Get("TakenItem")).GetField("id")).Value);
     }
 
     [Fact]
@@ -345,11 +557,12 @@ public sealed class EditTableExecutorTest(ITestOutputHelper output) : WorkflowAc
         EditTableExecutor action = new(model, this.State);
         await this.ExecuteAsync(action);
 
-        // Assert - Variable should contain the newly added record
+        // Assert - Variable should remain a table containing the newly added record
         VerifyModel(model, action);
         FormulaValue resultValue = this.State.Get("MyTable");
-        RecordValue resultRecord = Assert.IsAssignableFrom<RecordValue>(resultValue);
-        DecimalValue idValue = Assert.IsType<DecimalValue>(resultRecord.GetField("id"));
+        TableValue resultTable = Assert.IsAssignableFrom<TableValue>(resultValue);
+        Assert.Equal(2, resultTable.Rows.Count());
+        DecimalValue idValue = Assert.IsType<DecimalValue>(resultTable.Rows.Last().Value.GetField("id"));
         Assert.Equal(10, idValue.Value);
     }
 
@@ -382,10 +595,11 @@ public sealed class EditTableExecutorTest(ITestOutputHelper output) : WorkflowAc
         string displayName,
         string variableName,
         TableChangeType changeType,
-        DataValue? value)
+        DataValue? value,
+        string? resultVariableName = null)
     {
         // Arrange
-        EditTable model = this.CreateModel(displayName, variableName, changeType, value);
+        EditTable model = this.CreateModel(displayName, variableName, changeType, value, resultVariableName);
 
         // Act
         EditTableExecutor action = new(model, this.State);
@@ -399,7 +613,8 @@ public sealed class EditTableExecutorTest(ITestOutputHelper output) : WorkflowAc
         string displayName,
         string variableName,
         TableChangeType changeType,
-        DataValue? value)
+        DataValue? value,
+        string? resultVariableName = null)
     {
         ValueExpression.Builder? valueExpressionBuilder = value switch
         {
@@ -407,24 +622,26 @@ public sealed class EditTableExecutorTest(ITestOutputHelper output) : WorkflowAc
             _ => new ValueExpression.Builder(ValueExpression.Literal(value))
         };
 
-        return this.CreateModel(displayName, variableName, changeType, valueExpressionBuilder);
+        return this.CreateModel(displayName, variableName, changeType, valueExpressionBuilder, resultVariableName);
     }
 
     private EditTable CreateModel(
         string displayName,
         string variableName,
         TableChangeType changeType,
-        ValueExpression valueExpression)
+        ValueExpression valueExpression,
+        string? resultVariableName = null)
     {
         ValueExpression.Builder valueExpressionBuilder = new(valueExpression);
-        return this.CreateModel(displayName, variableName, changeType, valueExpressionBuilder);
+        return this.CreateModel(displayName, variableName, changeType, valueExpressionBuilder, resultVariableName);
     }
 
     private EditTable CreateModel(
         string displayName,
         string variableName,
         TableChangeType changeType,
-        ValueExpression.Builder? valueExpression)
+        ValueExpression.Builder? valueExpression,
+        string? resultVariableName = null)
     {
         EditTable.Builder actionBuilder = new()
         {
@@ -434,7 +651,31 @@ public sealed class EditTableExecutorTest(ITestOutputHelper output) : WorkflowAc
             ChangeType = TableChangeTypeWrapper.Get(changeType),
             Value = valueExpression,
         };
+        if (resultVariableName is not null)
+        {
+            actionBuilder.ResultVariable = PropertyPath.Create(FormatVariablePath(resultVariableName));
+        }
 
         return AssignParent<EditTable>(actionBuilder);
     }
+
+    private sealed class InMemoryJsonStore : JsonCheckpointStore
+    {
+        private readonly Dictionary<CheckpointInfo, JsonElement> _store = [];
+
+        public override ValueTask<CheckpointInfo> CreateCheckpointAsync(
+            string sessionId, JsonElement value, CheckpointInfo? parent = null)
+        {
+            CheckpointInfo key = new(sessionId, Guid.NewGuid().ToString("N"));
+            this._store[key] = value;
+            return new(key);
+        }
+
+        public override ValueTask<JsonElement> RetrieveCheckpointAsync(string sessionId, CheckpointInfo key) =>
+            new(this._store[key]);
+
+        public override ValueTask<IEnumerable<CheckpointInfo>> RetrieveIndexAsync(
+            string sessionId, CheckpointInfo? withParent = null) =>
+            new(this._store.Keys.Where(key => key.SessionId == sessionId));
+    }
 }