Merge branch 'main' into copilot/5350-implement-repro-unit-test

Agent-Logs-Url: https://github.com/microsoft/agent-framework/sessions/e7100d8a-ca6d-48e6-8210-78ba33dbd53c

Co-authored-by: lokitoth <6936551+lokitoth@users.noreply.github.com>

.github/workflows/issue-triage.yml

@@ -149,16 +149,14 @@ jobs:
             --apply-labels
 
       - name: Stop after spam gate
-        if: ${{ steps.spam.outputs.decision != 'allow' }}
+        if: ${{ steps.spam.outputs.allow_triage != 'true' }}
         shell: bash
-        env:
-          SPAM_DECISION: ${{ steps.spam.outputs.decision }}
         run: |
-          echo "Stopping: spam gate decided: ${SPAM_DECISION}"
+          echo "Stopping: issue triage preflight did not allow automation."
           exit 1
 
       - name: Reproduce reported issue
-        if: ${{ steps.spam.outputs.decision == 'allow' }}
+        if: ${{ steps.spam.outputs.allow_triage == 'true' }}
         id: repro
         working-directory: ${{ env.DEVFLOW_PATH }}
         env:

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

@@ -0,0 +1,84 @@
+---
+status: accepted
+contact: rogerbarreto
+date: 2026-05-07
+deciders: rogerbarreto
+consulted: []
+informed: []
+---
+
+# Hosted session identity context for Foundry Hosting
+
+## Context and Problem Statement
+
+Server-hosted Foundry agents need a way to scope per-user state (most notably `FoundryMemoryProvider` memories) by the end user that initiated the request. The Foundry platform already injects `x-agent-user-isolation-key` and `x-agent-chat-isolation-key` headers on every Responses request, but the agent-framework hosting layer did not surface those values to `AIContextProvider` instances. The provider's `stateInitializer` only received an `AgentSession?` with no identity attached, so per-user scoping was impossible without out-of-band plumbing.
+
+## Decision Drivers
+
+- Memory and any future user-private context must be partitioned per end user without per-sample boilerplate.
+- The identity must be **read-only** from the perspective of `AIContextProvider`s, so a buggy or hostile provider cannot escalate or leak across users.
+- The persisted session must validate against the live request on every resume to defend against session-id leak and in-process tampering.
+- The change must work for every existing hosted-agent type (`ChatClientAgent`, `FoundryAgent`, future ones) without per-type refactoring of cast-heavy code paths in `Microsoft.Agents.AI`.
+- Local Docker debugging must remain possible when the platform headers are absent.
+
+## Considered Options
+
+1. **`HostedSessionContext` stored in `AgentSessionStateBag`, exposed via a public read accessor and an `internal` setter.** Hosting writes once on session creation and validates on every resume.
+2. **Specialised `HostedAgentSession : AgentSession` wrapper** that carries `UserId`/`ChatId` properties, with `GetService<ChatClientAgentSession>()` as the unwrap escape hatch.
+3. **New property on `AgentSession` base class** (`HostedSessionContext? HostedContext { get; internal set; }`).
+4. **AsyncLocal middleware** that reads the headers and stuffs them into a per-request `AsyncLocal<HostedSessionContext>` consumed by the provider.
+
+For the source of identity:
+- A. The platform-injected `IsolationContext` exposed by `ResponseContext.Isolation` (typed `UserIsolationKey`/`ChatIsolationKey`).
+- B. The OpenAI Responses spec's top-level `request.User` field.
+- C. A custom HTTP header `x-client-user`.
+
+## Decision Outcome
+
+**Option 1** was chosen for the storage shape, sourced from **Option A** (`ResponseContext.Isolation`).
+
+Rationale:
+
+- **Wrapper rejected (Option 2).** `ChatClientAgentSession` is `sealed` and `ChatClientAgent` rejects any other session type via direct `is not ChatClientAgentSession` checks at multiple call sites. Wrapping would force non-trivial refactors across `Microsoft.Agents.AI` and a corresponding repeat for every other agent type.
+- **Base-class property rejected (Option 3).** Leaks "hosted" semantics into the universal `AgentSession` abstraction used by Durable, A2A, and CopilotStudio agents that have no notion of a hosted user.
+- **AsyncLocal rejected (Option 4).** Surfaces the concept only locally, requires every consumer to re-implement the bridge, and cannot be enforced as read-only.
+- **`request.User` rejected (Option B).** Set by the caller, not the platform. Forging it client-side trivially defeats per-user partitioning.
+- **`x-client-user` rejected (Option C).** Non-standard, requires custom HTTP plumbing, and duplicates the platform-provided isolation contract.
+
+Implementation summary in `Microsoft.Agents.AI.Foundry.Hosting`:
+
+| Type | Visibility | Purpose |
+|---|---|---|
+| `HostedSessionContext` | public sealed | Captures `UserId` and `ChatId` (both required, non-whitespace). |
+| `HostedSessionContextExtensions.GetHostedContext` | public | Read accessor for `AIContextProvider`s. |
+| `HostedSessionContextExtensions.SetHostedContext` | internal | Writer reserved for the hosting assembly. Backed by `AgentSessionStateBag` under a well-known key for serialisation. |
+| `HostedSessionIsolationKeyProvider` (abstract) | public | DI-resolvable factory. Async signature: `ValueTask<HostedSessionContext?> GetKeysAsync(ResponseContext, CreateResponse, CancellationToken)`. |
+| `PlatformHostedSessionIsolationKeyProvider` | internal sealed | Default implementation. Maps `context.Isolation.UserIsolationKey` and `context.Isolation.ChatIsolationKey`. Returns `null` when either is absent. |
+
+Behaviour added to `AgentFrameworkResponseHandler.CreateAsync`:
+
+1. Resolve `HostedSessionIsolationKeyProvider` from DI; fall back to `PlatformHostedSessionIsolationKeyProvider`.
+2. Call `GetKeysAsync(context, request, cancellationToken)`. A `null` result throws `InvalidOperationException` (becomes 500). A null/whitespace `UserId` or `ChatId` is rejected by `HostedSessionContext`'s constructor.
+3. Branch on the **session's existing context**, not on whether a `conversation_id` was supplied:
+   - **No session (`session is null`):** nothing to stamp; skip.
+   - **Session present but un-stamped (`GetHostedContext() is null`):** treat as fresh. This covers both newly-created sessions and pre-existing sessions whose `conversation_id` was provisioned externally (e.g. via `conversations.CreateProjectConversationAsync()`) before the first hosted-agent request. Stamp the resolved identity now.
+   - **Session present with stamped context:** strict resume. The persisted `UserId` and `ChatId` must equal the resolved values exactly. Mismatch throws `ResponsesApiException` with status 403 and body `Hosted session identity context mismatch`.
+
+## Consequences
+
+Positive:
+
+- Per-user memory partitioning works out of the box for any agent that consumes a `Microsoft.Agents.AI.Foundry.FoundryMemoryProvider` configured to read `session.GetHostedContext().UserId`.
+- Cross-user session-id leak and in-process tampering of the persisted identity both surface as a 403 with a deliberately uninformative body.
+- The identity is opaque to the framework, matching the platform's semantics. The framework never inspects user identity; the `IsolationContext` keys are pre-partitioned per agent.
+
+Negative:
+
+- Every existing hosted sample fails locally without a `HostedSessionIsolationKeyProvider` registered, because the platform headers are absent outside the platform. Mitigated by shipping `Hosted_Shared_Contributor_Setup` with `DevTemporaryLocalSessionIsolationKeyProvider` and `AddDevTemporaryLocalContributorSetup`, and migrating all 9 existing responses samples.
+- An attacker who can plant an un-stamped session under a victim's `conversation_id` *before* the victim's first hosted-agent request would be stamped with the attacker's identity on that first request. This is not a regression vs. behaviour without this contract, and is mitigated in practice because the `conversation_id` namespace is allocated by the platform per project. Once a session is stamped, the strict equality check fully defends the resume path.
+
+## Out of scope
+
+- Per-request `User` field on `CreateResponse` is intentionally not consumed; only the platform `IsolationContext` headers carry trustworthy identity.
+- Generic (non-Foundry) hosting layers can re-define an equivalent type if needed; nothing in this ADR is moved into `Microsoft.Agents.AI.Hosting` because `Microsoft.Agents.AI.Foundry.Hosting` does not depend on it.
+- HMAC tamper signatures over the persisted context are not implemented; comparison against `ResponseContext.Isolation` on every request is sufficient because the platform sets those headers at the trust boundary.

docs/working/issue-5350-root-cause-validation-plan.md

@@ -0,0 +1,173 @@
+# Issue #5350 — Root-cause validation plan
+
+**Issue:** [`.NET: [Bug]: Checkpoint round-trip loses ToolApprovalRequestContent.ToolCall concrete type (FunctionCallContent → base ToolCallContent), breaking FICC approval resume`](https://github.com/microsoft/agent-framework/issues/5350)
+
+**Status of repro:** A focused repro test class
+`dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/ToolApprovalRequestCheckpointReproTests.cs`
+was added covering seven progressively more end-to-end variants of the path the issue
+describes — including a **maximal** end-to-end test that uses a real
+`ChatClientAgent` driven by `FunctionInvokingChatClient` with an
+`ApprovalRequiredAIFunction`. **All seven tests pass** on `main`, consistently across
+5 back-to-back runs, i.e. *the bug as described does not reproduce* at any of the
+layers exercised here:
+
+| # | Test                                                                                | What it exercises                                                                                                                                                  | Result |
+|---|-------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------|
+| 1 | `Repro_5350_ToolApprovalRequestContent_DirectJsonMarshallerRoundtrip_PreservesFunctionCallContent` | `JsonMarshaller.Marshal/Marshal<T>` on `ToolApprovalRequestContent` directly (same options chain as `CheckpointManager.CreateJson`)                                | Pass   |
+| 2 | `Repro_5350_ToolApprovalRequestContent_WrappedInPortableValue_PreservesFunctionCallContent`       | Same, wrapped in a `PortableValue` (as `PortableMessageEnvelope` would store it)                                                                                  | Pass   |
+| 3 | `Repro_5350_ToolApprovalRequestContent_AsExternalRequestData_PreservesFunctionCallContent`        | Same, as the `Data` payload of an `ExternalRequest`                                                                                                                | Pass   |
+| 4 | `Repro_5350_DirectJsonMarshallerRoundtrip_IsDeterministic`                          | 25× repetition of #1 to rule out flakiness / JIT order                                                                                                             | Pass   |
+| 5 | `Repro_5350_CaptureWireFormat_ForInspection`                                        | Captures the on-the-wire shape so we can compare against the OP's SQL row                                                                                          | Pass   |
+| 6 | `Repro_5350_EndToEnd_JsonCheckpointResume_PreservesFunctionCallContentAsync`        | Full `CheckpointManager.CreateJson(InMemoryJsonStore) → RunStreamingAsync → SuperStep checkpoint → ResumeStreamingAsync` cycle with a `RequestPort<TARC, TARR>`    | Pass   |
+| 7 | `Repro_5350_EndToEnd_ChatClientAgent_WithApprovalRequiredTool_JsonCheckpointResume_PreservesFunctionCallContentAndInvokesToolAsync` | **Maximal**: `ChatClientAgent` over a `MockChatClient` with an `ApprovalRequiredAIFunction`, single-agent `WorkflowBuilder` (no orchestration), `CheckpointManager.CreateJson(InMemoryJsonStore)`. Asserts both that the resumed `RequestInfoEvent.Request` still carries a `FunctionCallContent` AND that approving the request actually invokes the underlying `AIFunction` and lets the workflow continue. | Pass   |
+
+This is **consistent with [@lokitoth's second comment](https://github.com/microsoft/agent-framework/issues/5350#issuecomment-4379664401)**:
+
+> Looking at the MEAI types, it does have `[JsonDerivedType(typeof(FunctionCallContent), "functionCall")]` set on it, and has had it that way for some time, so it is unlikely to be the root cause. […] `JsonMarshaller` […] takes an optional `JsonSerializationOptions` provided by the user […] but this is used only if the internal one (via `WorkflowsJsonUtilities`, which chains to `AgentAbstractionsJsonUtilities`, which then chains to the `AIJsonUtilities` class) [is missing the type].
+
+Inspection of the actual wire format produced by `JsonMarshaller` for a
+`ToolApprovalRequestContent` containing a `FunctionCallContent` confirms the
+discriminator is emitted:
+
+```jsonc
+// TARC at top level
+{
+  "toolCall": {
+    "$type": "functionCall",      // ← polymorphism discriminator present
+    "name": "DoTheThing",
+    "arguments": { "x": 42 },
+    "informationalOnly": false,
+    "callId": "call-1"
+  },
+  "requestId": "req-1"
+}
+
+// TARC inside a PortableValue (= shape stored by PortableMessageEnvelope)
+{
+  "typeId": {
+    "assemblyName": "Microsoft.Extensions.AI.Abstractions, Version=10.5.0.0, …",
+    "typeName": "Microsoft.Extensions.AI.ToolApprovalRequestContent"
+  },
+  "value": {
+    "toolCall": {
+      "$type": "functionCall",
+      …
+    },
+    "requestId": "req-1"
+  }
+}
+```
+
+So the OP's stated root-cause hypothesis — *"`AIContent`/`ToolCallContent`/
+`FunctionCallContent` are missing `[JsonPolymorphic]`/`[JsonDerivedType]`, or
+`CheckpointManager.CreateJson` does not pull from `AIJsonUtilities.DefaultOptions`"*
+— is **not** what is producing the failure described in the issue. The annotations
+exist, the resolver chain wires them through, and the discriminator does survive
+both the direct `JsonMarshaller` round-trip and a real `Run → checkpoint → Resume`
+cycle for a `RequestPort` whose request type is `ToolApprovalRequestContent`.
+
+The remaining sections lay out, in priority order, the work needed to identify
+the *actual* root cause. The plan deliberately keeps the failing repro from
+above as the baseline ("this is what works") and walks outward from it toward
+the OP's reported scenario, varying one dimension at a time.
+
+## Plan
+
+### Track A — Reproduce in a configuration closer to the OP's pattern "B"
+
+The OP's repro path differs from the new tests in three concrete ways. Tests #7
+(maximal repro) and #8–#10 (A2 / A3 / A4 below) close all four gaps. The OP's
+specific hypothesis (`TARC.ToolCall is not FunctionCallContent` after resume) does
+not reproduce in any of them; A2 did however uncover a *separate, unrelated* bug.
+
+| Step | Variable that changes vs. the passing tests in this repo                                                                                              | Why it matters                                                                                                                                                                                                       | Outcome                                                                |
+|------|--------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|
+| A1   | ~~Use `ChatClientAgent` + `ApprovalRequiredAIFunction` bound into a `WorkflowBuilder`~~ — **covered by test #7 in this PR; passes.**                  | Was the largest gap to the OP's repro. Closed.                                                                                                                                                                       | OP hypothesis disproved — `TARC.ToolCall is FunctionCallContent` post-resume, and the tool is actually invoked exactly once when the approval response is sent. |
+| A2   | Multi-agent variant: same as #7 but with the agent inside a `GroupChatBuilder` (the OP's actual orchestration) with `RoundRobinGroupChatManager`.     | If group chat re-encodes TARC as part of `ChatMessage.Contents` (`AIContent` polymorphism is two-deep through `ToolApprovalRequestContent`), one branch may resolve and the other not.                              | OP hypothesis disproved — `TARC.ToolCall is FunctionCallContent` post-resume. **But:** sending the approval response surfaces a *different* real bug — `FunctionInvokingChatClient.ExtractAndRemoveApprovalRequestsAndResponses` throws `ArgumentException: An item with the same key has already been added. Key: ficc_call-1`. Pinned by test as documented misbehavior. |
+| A2b  | Same as A2 but using `HandoffWorkflowBuilder` (initial agent has the approval tool, a no-op peer agent makes the handoff graph valid; the mock chat client never emits a `handoff_to_*` call). | If the duplicate-key bug from A2 is broader than `RoundRobinGroupChatManager` and lives in the shared `AIAgentHostExecutor` / `ChatProtocolExecutor` path, the handoff workflow should hit it too. | OP hypothesis disproved — `TARC.ToolCall is FunctionCallContent` post-resume **and** the workflow completes cleanly: tool invoked exactly once, zero errors, zero executor failures. The duplicate-key bug from A2 does **not** occur on the handoff path, narrowing it to the group-chat-specific orchestration. |
+| A3   | Same as #7 but with the checkpoint `JsonElement` round-tripped through `string` + `JsonDocument.Parse` between commit and retrieve (`StringRoundTripJsonStore`), emulating the SQL `nvarchar` hop in the OP's Dapper store.                                                                                | The OP uses Dapper + SQL Server. If the column / driver round-trip preserves ordering, this should be identity-preserving — but if it reorders metadata properties, the `$type` discriminator can be moved out of first position, which then requires `AllowOutOfOrderMetadataProperties = true`. | OP hypothesis disproved — byte-preserving string round-trip is identity-preserving for the relevant payload; `TARC.ToolCall is FunctionCallContent` post-resume; tool invoked exactly once. The OP's storage layer would have to *perturb* the JSON (e.g. reorder metadata) for this to reproduce. |
+| A4   | Same as #7 but with non-default `JsonSerializerOptions` (`JsonSerializerDefaults.Web`, no AIJsonUtilities resolver) passed as `customOptions` to `CheckpointManager.CreateJson`.                                                                                                                          | `JsonMarshaller.LookupTypeInfo` only goes to the external options when the internal chain doesn't know about the type. For most cases this won't trigger, but it's worth confirming that supplying a custom `JsonSerializerOptions` does not silently displace the internal chain.                            | OP hypothesis disproved — custom external options that DO NOT know about `AIContent` types are correctly ignored for known types; the internal `WorkflowsJsonUtilities.DefaultOptions` chain wins. `TARC.ToolCall is FunctionCallContent` post-resume; tool invoked exactly once. |
+
+### Track B — Validate the wire format the OP actually persists
+
+Once Track A has reproduced (or has clearly failed to reproduce) the symptom,
+ask the OP for one of the following, in order of preference:
+
+1. The raw `JsonElement.GetRawText()` they pass to their SQL store on commit,
+   and the raw string they read back on `RetrieveCheckpointAsync` — for the
+   exact checkpoint that contains the failing `ToolApprovalRequestContent`.
+   This tells us in a single round-trip whether:
+   - the `$type` discriminator is present on commit (rules out write-side bug),
+   - the `$type` discriminator survives the SQL round-trip (rules out store bug),
+   - the discriminator is in metadata-first position (rules out the
+     `AllowOutOfOrderMetadataProperties` story).
+2. A repro PR/gist that runs against `CheckpointManager.CreateJson(...)` with
+   an in-memory `JsonCheckpointStore` shim that mirrors how their SQL subclass
+   passes bytes through. The OP already offered this in the issue body
+   (*"I can produce a minimal standalone repro against a fake `IChatClient` if useful — let me know."*) — taking them up on it short-circuits a lot of guessing.
+
+### Track C — Defense-in-depth fixes worth landing regardless of root cause
+
+These are addressed in the OP's "Asks" section (asks 2–4) and are useful
+documentation/ergonomics improvements even if the root cause turns out to be in
+the OP's store implementation:
+
+1. **Doc-only**: in the XML docs for `CheckpointManager.CreateJson` and on the
+   `JsonCheckpointStore` base class, explicitly state that the internal options
+   chain through `WorkflowsJsonUtilities → AgentAbstractionsJsonUtilities →
+   AIJsonUtilities`, and that user-supplied `customOptions` are consulted only
+   when the internal chain has no `TypeInfo` for a requested type.
+2. **Doc-only**: document the contract that any user `JsonCheckpointStore`
+   subclass MUST preserve the exact byte sequence of the `JsonElement` it is
+   given. If the underlying store reorders JSON metadata, the consumer must opt
+   in by setting `AllowOutOfOrderMetadataProperties = true` on a
+   `JsonSerializerOptions` passed as `customOptions` to
+   `CheckpointManager.CreateJson(...)`.
+3. **Optional, only if Track A reproduces**: add a regression test mirroring
+   the failing path under `dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests`
+   so the fix is locked in.
+
+### Track D — Reject the OP's hypothesis (if not already done)
+
+The combination of:
+
+- the polymorphism annotations existing in `Microsoft.Extensions.AI` for some time
+  (per @lokitoth),
+- the resolver chain in `WorkflowsJsonUtilities.CreateDefaultOptions()` already
+  putting `AgentAbstractionsJsonUtilities.DefaultOptions.TypeInfoResolver` first
+  (which itself puts `AIJsonUtilities.DefaultOptions.TypeInfoResolver` first),
+- the wire format captured above showing `"$type": "functionCall"` is present,
+- the full `Run → checkpoint → Resume` test in this PR passing for a plain
+  `RequestPort<TARC, ToolApprovalResponseContent>` workflow, **and**
+- the maximal `ChatClientAgent` + `FunctionInvokingChatClient` +
+  `ApprovalRequiredAIFunction` test in this PR also passing — including the
+  assertion that the wrapped `AIFunction` is actually invoked exactly once after
+  approval and that the workflow then receives the resulting
+  `FunctionResultContent` and produces a final assistant message,
+
+is sufficient to **disprove** the OP's stated hypothesis. Once Track A or
+Track B identifies the actual cause, the issue should be updated with a brief
+explanation of why the original guess was incorrect, so future readers don't
+re-tread it.
+
+## Pointers for the next investigator
+
+- Repro tests:
+  `dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/ToolApprovalRequestCheckpointReproTests.cs`
+- Marshaller under test:
+  `dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/JsonMarshaller.cs`
+- Where `CheckpointManager.CreateJson` enters that path:
+  `dotnet/src/Microsoft.Agents.AI.Workflows/CheckpointManager.cs`
+- Options chain (TARC ⇒ resolver):
+  `dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowsJsonUtilities.cs`
+  → `dotnet/src/Microsoft.Agents.AI.Abstractions/AgentAbstractionsJsonUtilities.cs`
+  → `Microsoft.Extensions.AI.AIJsonUtilities.DefaultOptions`
+- `PortableValue`-side serialization (this is where `value.Value.GetType()` is
+  used on write, which is the most plausible *internal* place a polymorphism
+  bug could hide, but the wire capture above shows it is not the cause in the
+  TARC-as-RequestPort scenario):
+  `dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/PortableValueConverter.cs`
+- Likely next code to inspect for Track A1/A2 (agent-host serialization path):
+  `dotnet/src/Microsoft.Agents.AI.Workflows/AIAgentHostExecutor*.cs` and
+  whatever turns the FICC-generated TARC into something
+  `AIAgentHostExecutor` stores in its state bag.

dotnet/Directory.Packages.props

@@ -26,10 +26,10 @@
     <PackageVersion Include="Azure.AI.AgentServer.Invocations" Version="1.0.0-beta.3" />
     <PackageVersion Include="Azure.AI.AgentServer.Responses" Version="1.0.0-beta.4" />
     <PackageVersion Include="Azure.Search.Documents" Version="12.0.0" />
-    <PackageVersion Include="Azure.AI.Projects" Version="2.1.0-beta.1" />
+    <PackageVersion Include="Azure.AI.Projects" Version="2.1.0-beta.2" />
     <PackageVersion Include="Azure.AI.Agents.Persistent" Version="1.2.0-beta.10" />
     <PackageVersion Include="Azure.AI.OpenAI" Version="2.9.0-beta.1" />
-    <PackageVersion Include="Azure.Core" Version="1.53.0" />
+    <PackageVersion Include="Azure.Core" Version="1.55.0" />
     <PackageVersion Include="Azure.Identity" Version="1.21.0" />
     <PackageVersion Include="DotNetEnv" Version="3.1.1" />
     <PackageVersion Include="Azure.Monitor.OpenTelemetry.Exporter" Version="1.5.0" />
@@ -44,7 +44,7 @@
     <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.6" />
     <PackageVersion Include="Microsoft.Bcl.HashCode" Version="6.0.0" />
     <PackageVersion Include="Microsoft.Bcl.Memory" Version="10.0.5" />
-    <PackageVersion Include="System.ClientModel" Version="1.10.0" />
+    <PackageVersion Include="System.ClientModel" Version="1.11.0" />
     <PackageVersion Include="System.CodeDom" Version="10.0.0" />
     <PackageVersion Include="System.Collections.Immutable" Version="10.0.1" />
     <PackageVersion Include="System.CommandLine" Version="2.0.0-rc.2.25502.107" />

dotnet/agent-framework-dotnet.slnx

@@ -122,7 +122,7 @@
     <File Path="samples/02-agents/Harness/README.md" />
     <Project Path="samples/02-agents/Harness/Harness_Shared_Console/Harness_Shared_Console.csproj" />
     <Project Path="samples/02-agents/Harness/Harness_Step01_Research/Harness_Step01_Research.csproj" />
-    <Project Path="samples/02-agents/Harness/Harness_Step02_Research_WithSubAgents/Harness_Step02_Research_WithSubAgents.csproj" />
+    <Project Path="samples/02-agents/Harness/Harness_Step02_Research_WithBackgroundAgents/Harness_Step02_Research_WithBackgroundAgents.csproj" />
     <Project Path="samples/02-agents/Harness/Harness_Step03_DataProcessing/Harness_Step03_DataProcessing.csproj" />
     <Project Path="samples/02-agents/Harness/ConsoleReactiveFramework/ConsoleReactiveFramework.csproj" />
     <Project Path="samples/02-agents/Harness/ConsoleReactiveComponents/ConsoleReactiveComponents.csproj" />
@@ -327,9 +327,15 @@
   <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-McpTools/">
     <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-McpTools/HostedMcpTools.csproj" />
   </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-MemoryAgent/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-MemoryAgent/HostedMemoryAgent.csproj" />
+  </Folder>
   <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-Observability/">
     <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-Observability/HostedObservability.csproj" />
   </Folder>
+  <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted_Shared_Contributor_Setup/">
+    <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted_Shared_Contributor_Setup/Hosted_Shared_Contributor_Setup.csproj" />
+  </Folder>
   <Folder Name="/Samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox/">
     <Project Path="samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox/HostedToolbox.csproj" />
   </Folder>

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Commands/SessionCommandHandler.cs

@@ -0,0 +1,98 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using Microsoft.Agents.AI;
+
+namespace Harness.Shared.Console.Commands;
+
+/// <summary>
+/// Handles <c>/session-export &lt;filename&gt;</c> and <c>/session-import &lt;filename&gt;</c>
+/// commands for serializing the current session to a file and restoring a session from a file.
+/// </summary>
+public sealed class SessionCommandHandler : CommandHandler
+{
+    private readonly AIAgent _agent;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="SessionCommandHandler"/> class.
+    /// </summary>
+    /// <param name="agent">The agent used for session serialization and deserialization.</param>
+    public SessionCommandHandler(AIAgent agent)
+    {
+        this._agent = agent;
+    }
+
+    /// <inheritdoc/>
+    public override string? GetHelpText() => "/session-export <file> | /session-import <file>";
+
+    /// <inheritdoc/>
+    public override async ValueTask<bool> TryHandleAsync(string input, AgentSession session, IUXStateDriver ux)
+    {
+        string command = input.Split(' ', 2)[0];
+
+        if (command.Equals("/session-export", StringComparison.OrdinalIgnoreCase))
+        {
+            await this.HandleExportAsync(input, session, ux).ConfigureAwait(false);
+            return true;
+        }
+
+        if (command.Equals("/session-import", StringComparison.OrdinalIgnoreCase))
+        {
+            await this.HandleImportAsync(input, ux).ConfigureAwait(false);
+            return true;
+        }
+
+        return false;
+    }
+
+    private async Task HandleExportAsync(string input, AgentSession session, IUXStateDriver ux)
+    {
+        string[] parts = input.Split(' ', 2, StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+        if (parts.Length < 2)
+        {
+            await ux.WriteInfoLineAsync("Usage: /session-export <filename>").ConfigureAwait(false);
+            return;
+        }
+
+        string filename = parts[1];
+        try
+        {
+            JsonElement serialized = await this._agent.SerializeSessionAsync(session).ConfigureAwait(false);
+            string json = JsonSerializer.Serialize(serialized);
+            await File.WriteAllTextAsync(filename, json).ConfigureAwait(false);
+            await ux.WriteInfoLineAsync($"Session exported to {filename}").ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            await ux.WriteInfoLineAsync($"Failed to export session to {filename}: {ex.Message}").ConfigureAwait(false);
+        }
+    }
+
+    private async Task HandleImportAsync(string input, IUXStateDriver ux)
+    {
+        string[] parts = input.Split(' ', 2, StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+        if (parts.Length < 2)
+        {
+            await ux.WriteInfoLineAsync("Usage: /session-import <filename>").ConfigureAwait(false);
+            return;
+        }
+
+        string filename = parts[1];
+        try
+        {
+            string json = await File.ReadAllTextAsync(filename).ConfigureAwait(false);
+            JsonElement element = JsonSerializer.Deserialize<JsonElement>(json);
+            AgentSession newSession = await this._agent.DeserializeSessionAsync(element).ConfigureAwait(false);
+            await ux.ReplaceSessionAsync(newSession).ConfigureAwait(false);
+            await ux.WriteInfoLineAsync($"Session imported from {filename}").ConfigureAwait(false);
+        }
+        catch (FileNotFoundException)
+        {
+            await ux.WriteInfoLineAsync($"File not found: {filename}").ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            await ux.WriteInfoLineAsync($"Failed to import session from {filename}: {ex.Message}").ConfigureAwait(false);
+        }
+    }
+}

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

@@ -0,0 +1,67 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics;
+using System.Globalization;
+using OpenTelemetry;
+
+namespace Harness.Shared.Console;
+
+/// <summary>
+/// A simple OpenTelemetry span exporter that writes completed activities (spans) to a text file.
+/// Each span is formatted as a human-readable block with timestamps, operation name, duration,
+/// status, and any tags/events.
+/// </summary>
+public sealed class FileSpanExporter : BaseExporter<Activity>
+{
+    private readonly string _filePath;
+    private readonly object _lock = new();
+
+    public FileSpanExporter(string filePath)
+    {
+        this._filePath = filePath;
+        Directory.CreateDirectory(Path.GetDirectoryName(filePath)!);
+    }
+
+    public override ExportResult Export(in Batch<Activity> batch)
+    {
+        lock (this._lock)
+        {
+            using var writer = new StreamWriter(this._filePath, append: true);
+            foreach (var activity in batch)
+            {
+                WriteActivity(writer, activity);
+            }
+        }
+
+        return ExportResult.Success;
+    }
+
+    private static void WriteActivity(StreamWriter writer, Activity activity)
+    {
+        var start = activity.StartTimeUtc.ToString("yyyy-MM-dd HH:mm:ss.fff", CultureInfo.InvariantCulture);
+        var duration = activity.Duration.TotalMilliseconds.ToString("F1", CultureInfo.InvariantCulture);
+
+        writer.WriteLine($"[{start}] {activity.OperationName} ({duration}ms) [{activity.Status}]");
+
+        if (!string.IsNullOrEmpty(activity.DisplayName) && activity.DisplayName != activity.OperationName)
+        {
+            writer.WriteLine($"  DisplayName: {activity.DisplayName}");
+        }
+
+        foreach (var tag in activity.Tags)
+        {
+            writer.WriteLine($"  {tag.Key}: {tag.Value}");
+        }
+
+        foreach (var ev in activity.Events)
+        {
+            writer.WriteLine($"  Event: {ev.Name} @ {ev.Timestamp:HH:mm:ss.fff}");
+            foreach (var tag in ev.Tags)
+            {
+                writer.WriteLine($"    {tag.Key}: {tag.Value}");
+            }
+        }
+
+        writer.WriteLine();
+    }
+}

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

@@ -19,15 +19,15 @@ namespace Harness.Shared.Console;
 public sealed class HarnessAgentRunner : IDisposable
 {
     private readonly AIAgent _agent;
-    private readonly AgentSession _session;
     private readonly AgentModeProvider? _modeProvider;
     private readonly MessageInjectingChatClient? _messageInjector;
     private readonly IReadOnlyList<CommandHandler> _commandHandlers;
     private readonly IReadOnlyList<ConsoleObserver> _observers;
     private readonly IUXStateDriver _ux;
-
     private readonly SemaphoreSlim _inputGate = new(1, 1);
 
+    private AgentSession _session;
+
     /// <summary>
     /// Initializes a new instance of the <see cref="HarnessAgentRunner"/> class.
     /// </summary>
@@ -62,6 +62,25 @@ public sealed class HarnessAgentRunner : IDisposable
     /// </summary>
     public string HelpText { get; }
 
+    /// <summary>
+    /// Replaces the current session with the specified session. Used by the UX driver
+    /// when importing a serialized session. Acquires the input gate to ensure no
+    /// concurrent agent turn is reading the session.
+    /// </summary>
+    /// <param name="newSession">The new session to use.</param>
+    internal async Task ReplaceSessionAsync(AgentSession newSession)
+    {
+        await this._inputGate.WaitAsync().ConfigureAwait(false);
+        try
+        {
+            this._session = newSession;
+        }
+        finally
+        {
+            this._inputGate.Release();
+        }
+    }
+
     /// <inheritdoc/>
     public void Dispose() => this._inputGate.Dispose();
 

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

@@ -63,6 +63,7 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
             getState: () => this.State!,
             setState: s => this.SetState(s),
             requestShutdown: () => this._shutdownTcs.TrySetResult(true),
+            replaceSession: s => this.Runner!.ReplaceSessionAsync(s),
             modeColors: modeColors);
 
         this.Runner = runnerFactory(this._uxDriver);

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

@@ -128,6 +128,7 @@ public class HarnessConsoleOptions
             new ExitCommandHandler(),
             new TodoCommandHandler(todoProvider),
             new ModeCommandHandler(modeProvider, modeColors ?? DefaultModeColors),
+            new SessionCommandHandler(agent),
         ];
     }
 }

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

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 using Harness.ConsoleReactiveComponents;
+using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 
 namespace Harness.Shared.Console;
@@ -16,6 +17,7 @@ internal sealed class HarnessConsoleUXStateDriver : IUXStateDriver
     private readonly Func<HarnessAppComponentState> _getState;
     private readonly Action<HarnessAppComponentState> _setState;
     private readonly Action _requestShutdown;
+    private readonly Func<AgentSession, Task> _replaceSession;
     private readonly IReadOnlyDictionary<string, ConsoleColor>? _modeColors;
     private readonly List<string> _outputItems = [];
     private readonly object _stateLock = new();
@@ -32,16 +34,19 @@ internal sealed class HarnessConsoleUXStateDriver : IUXStateDriver
     /// <param name="getState">Returns the component's current state.</param>
     /// <param name="setState">Replaces the component's state and triggers a re-render.</param>
     /// <param name="requestShutdown">Callback invoked when a command handler requests application shutdown.</param>
+    /// <param name="replaceSession">Callback invoked to replace the current agent session (e.g., on import).</param>
     /// <param name="modeColors">Optional mapping of mode names to console colors.</param>
     public HarnessConsoleUXStateDriver(
         Func<HarnessAppComponentState> getState,
         Action<HarnessAppComponentState> setState,
         Action requestShutdown,
+        Func<AgentSession, Task> replaceSession,
         IReadOnlyDictionary<string, ConsoleColor>? modeColors = null)
     {
         this._getState = getState;
         this._setState = setState;
         this._requestShutdown = requestShutdown;
+        this._replaceSession = replaceSession;
         this._modeColors = modeColors;
         this._currentMode = getState().ModeText;
     }
@@ -405,4 +410,7 @@ internal sealed class HarnessConsoleUXStateDriver : IUXStateDriver
 
     /// <inheritdoc/>
     public void RequestShutdown() => this._requestShutdown();
+
+    /// <inheritdoc/>
+    public Task ReplaceSessionAsync(AgentSession newSession) => this._replaceSession(newSession);
 }

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

@@ -0,0 +1,55 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+#pragma warning disable VSTHRD002 // Synchronous waits are required by OpenTelemetry enrichment callbacks.
+
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+
+namespace Harness.Shared.Console;
+
+/// <summary>
+/// Provides factory methods for creating pre-configured OpenTelemetry tracing for harness samples.
+/// </summary>
+public static class HarnessTracing
+{
+    /// <summary>
+    /// Creates a <see cref="TracerProvider"/> that captures spans from the specified source and HTTP client activity,
+    /// enriching HTTP spans with full request/response headers and bodies, and exports all spans to a timestamped
+    /// text file in the application base directory.
+    /// </summary>
+    /// <param name="sourceName">The activity source name to subscribe to (e.g., "Harness.Research").</param>
+    /// <returns>A configured <see cref="TracerProvider"/>, or <see langword="null"/> if the builder returns null.</returns>
+    public static TracerProvider? CreateFileTracerProvider(string sourceName)
+    {
+        var traceLogPath = Path.Combine(AppContext.BaseDirectory, $"traces_{DateTime.UtcNow:yyyyMMdd_HHmmss}_{Guid.NewGuid()}.log");
+
+        return Sdk.CreateTracerProviderBuilder()
+            .AddSource(sourceName)
+            .AddHttpClientInstrumentation((options) =>
+            {
+                options.EnrichWithHttpRequestMessage = (activity, request) =>
+                {
+                    activity.SetTag("http.request.headers", request.Headers.ToString());
+                    if (request.Content != null)
+                    {
+                        activity.SetTag("http.request.content.headers", request.Content.Headers.ToString());
+                        var content = request.Content.ReadAsStringAsync().GetAwaiter().GetResult();
+                        activity.SetTag("http.request.content.body", content);
+                    }
+                };
+
+                options.EnrichWithHttpResponseMessage = (activity, response) =>
+                {
+                    activity.SetTag("http.response.headers", response.Headers.ToString());
+                    if (response.Content != null)
+                    {
+                        activity.SetTag("http.response.content.headers", response.Content.Headers.ToString());
+                        var content = response.Content.ReadAsStringAsync().GetAwaiter().GetResult();
+                        activity.SetTag("http.response.content.body", content);
+                    }
+                };
+            })
+            .AddProcessor(new SimpleActivityExportProcessor(new FileSpanExporter(traceLogPath)))
+            .Build();
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Harness_Shared_Console.csproj

@@ -7,6 +7,11 @@
     <ImplicitUsings>enable</ImplicitUsings>
   </PropertyGroup>
 
+  <ItemGroup>
+    <PackageReference Include="OpenTelemetry" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.Http" />
+  </ItemGroup>
+
   <ItemGroup>
     <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
     <ProjectReference Include="..\ConsoleReactiveFramework\ConsoleReactiveFramework.csproj" />

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

@@ -1,5 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 
 namespace Harness.Shared.Console;
@@ -117,4 +118,11 @@ public interface IUXStateDriver
     /// on the owning component.
     /// </summary>
     void RequestShutdown();
+
+    /// <summary>
+    /// Replaces the current agent session with the specified session (e.g., after importing
+    /// a serialized session from a file).
+    /// </summary>
+    /// <param name="newSession">The new session to use.</param>
+    Task ReplaceSessionAsync(AgentSession newSession);
 }

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

@@ -31,6 +31,10 @@ public sealed class ToolCallDisplayObserver : ConsoleObserver
         {
             await ux.WriteInfoLineAsync($"🔧 Calling tool: {ToolCallFormatter.Format(this._formatters, functionCall)}...", ConsoleColor.DarkYellow);
         }
+        else if (content is WebSearchToolCallContent)
+        {
+            // Handled by OpenAIResponsesWebSearchDisplayObserver when present; skip here to avoid duplication.
+        }
         else if (content is ToolCallContent toolCall)
         {
             await ux.WriteInfoLineAsync($"🔧 Calling tool: {toolCall}...", ConsoleColor.DarkYellow);

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

@@ -6,26 +6,26 @@ using Microsoft.Extensions.AI;
 namespace Harness.Shared.Console.ToolFormatters;
 
 /// <summary>
-/// Formats <c>SubAgents_*</c> tool calls with human-readable details
+/// Formats <c>BackgroundAgents_*</c> tool calls with human-readable details
 /// for task start, continue, wait, and result retrieval operations.
 /// </summary>
-public sealed class SubAgentToolFormatter : ToolCallFormatter
+public sealed class BackgroundAgentToolFormatter : ToolCallFormatter
 {
     /// <inheritdoc/>
-    public override bool CanFormat(FunctionCallContent call) => call.Name.StartsWith("SubAgents_", StringComparison.Ordinal);
+    public override bool CanFormat(FunctionCallContent call) => call.Name.StartsWith("BackgroundAgents_", StringComparison.Ordinal);
 
     /// <inheritdoc/>
     public override string? FormatDetail(FunctionCallContent call) => call.Name switch
     {
-        "SubAgents_StartTask" => FormatStartSubTask(call),
-        "SubAgents_WaitForFirstCompletion" => FormatIdList(call, "taskIds", "Wait for"),
-        "SubAgents_GetTaskResults" => FormatSingleId(call, "taskId"),
-        "SubAgents_ContinueTask" => FormatContinueTask(call),
-        "SubAgents_ClearCompletedTask" => FormatSingleId(call, "taskId"),
+        "BackgroundAgents_StartTask" => FormatStartBackgroundTask(call),
+        "BackgroundAgents_WaitForFirstCompletion" => FormatIdList(call, "taskIds", "Wait for"),
+        "BackgroundAgents_GetTaskResults" => FormatSingleId(call, "taskId"),
+        "BackgroundAgents_ContinueTask" => FormatContinueTask(call),
+        "BackgroundAgents_ClearCompletedTask" => FormatSingleId(call, "taskId"),
         _ => null,
     };
 
-    private static string? FormatStartSubTask(FunctionCallContent call)
+    private static string? FormatStartBackgroundTask(FunctionCallContent call)
     {
         string? agentName = GetStringArgumentValue(call, "agentName");
         string? description = GetStringArgumentValue(call, "description");

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

@@ -19,7 +19,7 @@ public sealed class TodoToolFormatter : ToolCallFormatter
     public override string? FormatDetail(FunctionCallContent call) => call.Name switch
     {
         "TodoList_Add" => FormatAddTodos(call),
-        "TodoList_Complete" => FormatIdList(call, "ids", "Complete"),
+        "TodoList_Complete" => FormatCompleteTodos(call),
         "TodoList_Remove" => FormatIdList(call, "ids", "Remove"),
         _ => null,
     };
@@ -64,6 +64,50 @@ public sealed class TodoToolFormatter : ToolCallFormatter
         return sb.ToString();
     }
 
+    private static string? FormatCompleteTodos(FunctionCallContent call)
+    {
+        if (call.Arguments?.TryGetValue("items", out object? itemsObj) != true || itemsObj is null)
+        {
+            return null;
+        }
+
+        var entries = new List<(int Id, string? Reason)>();
+
+        if (itemsObj is JsonElement jsonArray && jsonArray.ValueKind == JsonValueKind.Array)
+        {
+            foreach (JsonElement item in jsonArray.EnumerateArray())
+            {
+                if (!item.TryGetProperty("id", out JsonElement idElement) || !idElement.TryGetInt32(out int id))
+                {
+                    continue;
+                }
+
+                string? reason = item.TryGetProperty("reason", out JsonElement reasonElement)
+                    ? reasonElement.GetString()
+                    : null;
+                entries.Add((id, reason));
+            }
+        }
+
+        if (entries.Count == 0)
+        {
+            return null;
+        }
+
+        var sb = new StringBuilder();
+        for (int i = 0; i < entries.Count; i++)
+        {
+            string connector = i < entries.Count - 1 ? "├─" : "└─";
+            sb.Append($"\n   {connector} Complete #{entries[i].Id}");
+            if (!string.IsNullOrEmpty(entries[i].Reason))
+            {
+                sb.Append($" — {Truncate(entries[i].Reason!, 80)}");
+            }
+        }
+
+        return sb.ToString();
+    }
+
     private static string? FormatIdList(FunctionCallContent call, string paramName, string verb)
     {
         List<int>? ids = GetIntListArgumentValue(call, paramName);

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

@@ -56,7 +56,7 @@ public abstract class ToolCallFormatter
         [
             new TodoToolFormatter(),
             new ModeToolFormatter(),
-            new SubAgentToolFormatter(),
+            new BackgroundAgentToolFormatter(),
             new FileMemoryToolFormatter(),
             new WebSearchToolFormatter(),
             new FallbackToolFormatter(),

dotnet/samples/02-agents/Harness/Harness_Step01_Research/Harness_Step01_Research.csproj

@@ -13,8 +13,8 @@
   </ItemGroup>
 
   <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
     <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Harness\Microsoft.Agents.AI.Harness.csproj" />
-    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
     <ProjectReference Include="..\Harness_Shared_Console\Harness_Shared_Console.csproj" />
   </ItemGroup>
 

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

@@ -0,0 +1,206 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+#pragma warning disable OPENAI001 // Suppress experimental API warnings for Responses API usage.
+
+using System.Text;
+using Harness.Shared.Console;
+using Harness.Shared.Console.Observers;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using OpenAI.Responses;
+
+namespace SampleApp;
+
+/// <summary>
+/// Displays web search activity in the scroll area. Shows search queries,
+/// page opens, and find-in-page actions as they stream in from the API.
+/// </summary>
+internal sealed class OpenAIResponsesWebSearchDisplayObserver : ConsoleObserver
+{
+    private const int MaxQueryDisplayLength = 120;
+
+    /// <inheritdoc/>
+    public override async Task OnContentAsync(IUXStateDriver ux, AIContent content, AIAgent agent, AgentSession session)
+    {
+        if (content is WebSearchToolResultContent resultContent
+            && resultContent.RawRepresentation is WebSearchCallResponseItem wscri)
+        {
+            await WriteActionAsync(ux, wscri, resultContent.Outputs);
+        }
+    }
+
+    private static async Task WriteActionAsync(IUXStateDriver ux, WebSearchCallResponseItem wscri, IList<AIContent>? outputs)
+    {
+        WebSearchAction? action = wscri.Action;
+        if (action is null)
+        {
+            await ux.WriteInfoLineAsync("🌐 Web Search Tool (no action details)", ConsoleColor.DarkCyan);
+            return;
+        }
+
+        switch (action)
+        {
+            case WebSearchFindInPageAction findInPage:
+                await WriteFindInPageAsync(ux, findInPage);
+                break;
+
+            case WebSearchOpenPageAction openPage:
+                await WriteOpenPageAsync(ux, openPage);
+                break;
+
+            case WebSearchSearchAction search:
+                await WriteSearchAsync(ux, search, outputs);
+                break;
+
+            default:
+                await ux.WriteInfoLineAsync("🌐 Web Search Tool (unknown action)", ConsoleColor.DarkCyan);
+                break;
+        }
+    }
+
+    private static async Task WriteSearchAsync(IUXStateDriver ux, WebSearchSearchAction search, IList<AIContent>? outputs)
+    {
+        // Read queries directly from the typed action.
+        IList<string> queries = search.Queries;
+
+        if (queries.Count == 0)
+        {
+            await ux.WriteInfoLineAsync("🌐 Web Search Tool: search", ConsoleColor.DarkCyan);
+            return;
+        }
+
+        var sb = new StringBuilder();
+        sb.Append("🌐 Web Search Tool: search");
+
+        // Show the search queries.
+        bool hasResults = outputs is { Count: > 0 };
+        for (int i = 0; i < queries.Count; i++)
+        {
+            string connector = (i < queries.Count - 1 || hasResults) ? "├─" : "└─";
+            string query = Truncate(queries[i], MaxQueryDisplayLength);
+            sb.Append($"\n   {connector} \"{query}\"");
+        }
+
+        // Show search result sources (URLs + titles) when available.
+        // Sources come from M.E.AI's Outputs when IncludedResponseProperty.WebSearchCallActionSources is set,
+        // or directly from the SDK's WebSearchSearchAction.Sources.
+        if (hasResults)
+        {
+            sb.Append("\n   │");
+            for (int i = 0; i < outputs!.Count; i++)
+            {
+                string connector = i < outputs.Count - 1 ? "├─" : "└─";
+                string line = FormatOutput(outputs[i]);
+                sb.Append($"\n   {connector} {line}");
+            }
+        }
+        else if (search.Sources is { Count: > 0 } sources)
+        {
+            sb.Append("\n   │");
+            for (int i = 0; i < sources.Count; i++)
+            {
+                string connector = i < sources.Count - 1 ? "├─" : "└─";
+                string line = FormatSource(sources[i]);
+                sb.Append($"\n   {connector} {line}");
+            }
+        }
+
+        await ux.WriteInfoLineAsync(sb.ToString(), ConsoleColor.DarkCyan);
+    }
+
+    private static async Task WriteOpenPageAsync(IUXStateDriver ux, WebSearchOpenPageAction openPage)
+    {
+        string url = openPage.Uri?.AbsoluteUri ?? "(unknown)";
+        await ux.WriteInfoLineAsync(
+            $"🌐 Web Search Tool: open page\n   └─ {url}",
+            ConsoleColor.DarkCyan);
+    }
+
+    private static async Task WriteFindInPageAsync(IUXStateDriver ux, WebSearchFindInPageAction findInPage)
+    {
+        string url = findInPage.Uri?.AbsoluteUri ?? "(unknown)";
+        string pattern = findInPage.Pattern ?? "(unknown)";
+
+        await ux.WriteInfoLineAsync(
+            $"🌐 Web Search Tool: find in page\n   ├─ \"{Truncate(pattern, MaxQueryDisplayLength)}\"\n   └─ {url}",
+            ConsoleColor.DarkCyan);
+    }
+
+    /// <summary>
+    /// Formats a single search result source from the SDK's <see cref="WebSearchActionSource"/> for display.
+    /// </summary>
+    private static string FormatSource(WebSearchActionSource source)
+    {
+        if (source is WebSearchActionUriSource uriSource)
+        {
+            string url = uriSource.Uri?.AbsoluteUri ?? "(unknown)";
+
+            // WebSearchActionUriSource doesn't expose a title property,
+            // but the API may include one in the raw response JSON.
+            string? title = GetTitleFromRawRepresentation(uriSource);
+
+            return title is not null
+                ? $"{Truncate(title, MaxQueryDisplayLength)} — {url}"
+                : url;
+        }
+
+        return source.ToString() ?? "(unknown source)";
+    }
+
+    /// <summary>
+    /// Formats a single search result output from M.E.AI's <see cref="AIContent"/> for display.
+    /// </summary>
+    private static string FormatOutput(AIContent output)
+    {
+        if (output is UriContent uriContent)
+        {
+            string url = uriContent.Uri?.AbsoluteUri ?? "(unknown)";
+
+            // Try to extract a title from the raw JSON of the source.
+            // The SDK's WebSearchActionUriSource doesn't expose a title property,
+            // but the API may include one in the raw response.
+            string? title = GetTitleFromRawRepresentation(uriContent.RawRepresentation)
+                ?? (uriContent.AdditionalProperties?.TryGetValue("title", out var t) is true ? t?.ToString() : null);
+
+            return title is not null
+                ? $"{Truncate(title, MaxQueryDisplayLength)} — {url}"
+                : url;
+        }
+
+        return output.ToString() ?? "(unknown output)";
+    }
+
+    /// <summary>
+    /// Attempts to extract a "title" field from a raw representation object by serializing it to JSON.
+    /// The SDK's <see cref="WebSearchActionUriSource"/> doesn't expose a title property,
+    /// but the API may include one in the raw JSON — this is forward-compatible for when
+    /// the SDK adds title support.
+    /// </summary>
+    private static string? GetTitleFromRawRepresentation(object? rawRepresentation)
+    {
+        if (rawRepresentation is null)
+        {
+            return null;
+        }
+
+        try
+        {
+            var data = System.ClientModel.Primitives.ModelReaderWriter.Write(rawRepresentation);
+            using var doc = System.Text.Json.JsonDocument.Parse(data);
+            if (doc.RootElement.TryGetProperty("title", out var titleEl)
+                && titleEl.ValueKind == System.Text.Json.JsonValueKind.String)
+            {
+                return titleEl.GetString();
+            }
+        }
+        catch
+        {
+            // Serialization may not be supported for this object type.
+        }
+
+        return null;
+    }
+
+    private static string Truncate(string text, int maxLength)
+        => text.Length <= maxLength ? text : string.Concat(text.AsSpan(0, maxLength - 1), "…");
+}

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

@@ -1,8 +1,9 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-// This sample demonstrates how to use a HarnessAgent with the Harness AIContextProviders
-// (TodoProvider and AgentModeProvider) for interactive research tasks with web search
-// capabilities powered by Azure AI Foundry.
+// This sample demonstrates how to use a HarnessAgent for interactive research tasks.
+// The HarnessAgent comes pre-configured with TodoProvider, AgentModeProvider, FileMemoryProvider,
+// ToolApproval, WebSearch, and OpenTelemetry — so this sample only needs custom instructions
+// and a WebBrowsingTool.
 // The agent plans research tasks, creates a todo list, gets user approval,
 // and then executes each step — all within an interactive conversation loop.
 //
@@ -15,147 +16,88 @@
 #pragma warning disable MAAI001  // Suppress experimental API warnings for Agents AI experiments.
 
 using System.ClientModel.Primitives;
+using Azure.AI.Projects;
 using Azure.Identity;
 using Harness.Shared.Console;
 using Harness.Shared.Console.ToolFormatters;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
-using OpenAI;
-using OpenAI.Responses;
 using SampleApp;
 
-var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_OPENAI_ENDPOINT is not set.");
+var endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5.4";
 
 const int MaxContextWindowTokens = 1_050_000;
 const int MaxOutputTokens = 128_000;
+const string TracingSourceName = "Harness.Research";
+
+// Set up OpenTelemetry tracing that writes spans to a text file.
+// This captures all agent activity (tool calls, model invocations, compaction, etc.)
+// as well as HTTP requests made by the underlying HttpClient transport.
+using var tracerProvider = HarnessTracing.CreateFileTracerProvider(TracingSourceName);
 
 // Create a HarnessAgent with the Harness providers (TodoProvider and AgentModeProvider)
 // and research-focused instructions including the mandatory planning workflow.
 var instructions =
     """
+    ## Research Assistant Instructions
+
     You are a research assistant. When given a research topic, research it thoroughly using web search and web browsing.
     Use your knowledge to form good search queries and hypotheses, but always verify claims with the tools available to you rather than relying on memory alone.
 
-    ## Mandatory planning workflow
-
-    For every new substantive user request, including short factual questions, your behavior is determined by the mode you are in.
-    If you are in plan mode, start with the *Plan Mode* steps, and if you are in execute mode, skip directly to the *Execute Mode* steps below.
-
-    *Plan Mode*
-
-    1. Analyze the request with the purpose of building a research plan.
-    2. Create a list of todo items.
-    3. If needed, use the provided tools to do some exploratory checks to help build a plan and determine what clarifying questions you may need from the user.
-    4. Ask for clarifications from the user where needed.
-      1. Ask each clarification one by one.
-      2. When asking for clarification and you have specific options in mind, present them to the user, so they can choose the option instead of having to retype the entire response.
-      3. Do not proceed until you have received all the needed clarifications.
-      4. Do short exploratory research if it helps with being able to ask sensible clarifications from the user.
-    5. Write the plan to a memory file, so that it is retained even if compaction happens. Make sure to update the plan file if the user requests changes.
-    6. Present the plan to the user and ask for approval to switch to execute mode and process the plan.
-    7. When approval is granted, always switch to execute mode (using the `AgentMode_Set` tool), and follow the steps for *Execute mode*.
-
-    *Execute Mode*
-
-    1. If you don't have a plan or tasks yet, analyse the user request and create tasks and a plan. (**Skip this step if you came from plan mode**)
-    2. Work autonomously — use your best judgement to make decisions and keep progressing without asking the user questions. The goal is to have a complete, useful result ready when the user returns.
-    3. If you encounter ambiguity or an unexpected situation during execution, choose the most reasonable option, note your choice, and keep going.
-    4. Mark tasks as completed as you finish them.
-    5. Continue working, thinking and calling tools until you have the research result for the user.
-
-    ## General Instructions
-
-    - You must check the current mode after any user input, since the user may have changed the mode themselves,
-      e.g. the user may have switched to 'plan' mode after a previous research task finished in 'execute' mode, meaning they want to review a plan first before execution.
-    - Explain your reasoning and thought process as you work through tasks.
-    - Explain what you learned and what you are going to do next between tool calls, so the user can follow along with your thought process.
-    - Avoid making more than 4 tool calls in a row without explaining what you are doing.
-    - Do not answer the underlying question before the plan has been presented and approved.
-    - This rule applies even when the answer seems obvious or the task seems small.
-    - For short requests, use a brief micro-plan rather than skipping planning. The only exceptions are:
-      - greetings,
-      - pure acknowledgments,
-      - clarification questions needed to form the plan,
-      - follow-up questions about results you have already presented,
-      - meta-discussion about the workflow itself.
-
-    **Todo management**
-
-    Mark each todo complete as you finish it so the list stays current.
-    If a todo turns out to be unnecessary or is blocked, remove it and briefly explain why.
-    Once the user finishes with a topic and moves onto a new one, clean up old completed todos by deleting them.
-
-    **Research quality**
+    ### Research quality
 
     Consult multiple sources when possible and cross-reference key claims.
     When sources disagree, note the discrepancy and explain which source you consider more reliable and why.
     If a web page fails to load or a search returns irrelevant results, try alternative search queries or sources before moving on.
     Track your sources — you will need them when presenting results.
 
-    **Presenting results**
+    ### Presenting results
 
     When presenting your final findings:
+    - Use Markdown formatting for clarity.
     - Use clear sections with headings for each major topic or sub-question.
     - Cite your sources inline (e.g., "According to [source name](URL), ...").
     - End with a brief summary of key takeaways.
-    - Save the final research report to file memory so it survives compaction and can be referenced later.
-
-    **File memory**
-
-    Use the FileMemory_* tools to:
-    - Store downloaded search results or web pages.
-    - Store plans.
-    - Read the current plan to make sure tasks were done according to plan.
-    - Store findings.
-    - Check for relevant previously downloaded data / findings before starting new research.
+    - In addition to returning the results to the user, save the final research report to file memory so it survives compaction and can be referenced later.
     """;
 
 // Create the agent using AsHarnessAgent, which pre-configures function invocation,
-// per-service-call chat history persistence, and in-loop compaction.
-// Then wrap with UseToolApproval to allow auto-approving tools once confirmed.
+// per-service-call chat history persistence, in-loop compaction, TodoProvider, AgentModeProvider,
+// FileMemoryProvider, ToolApproval, WebSearch, AgentSkillsProvider, and OpenTelemetry.
+// Only custom instructions, a WebBrowsingTool, and FileAccess opt-out are needed.
 AIAgent agent =
     // Create an OpenAIClient that communicates with the Foundry responses service.
-    new OpenAIClient(
+    new AIProjectClient(
+        new Uri(endpoint),
         // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
         // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
         // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-        new BearerTokenPolicy(new DefaultAzureCredential(), "https://ai.azure.com/.default"),
-        new OpenAIClientOptions()
-        {
-            Endpoint = new Uri(endpoint),
-            RetryPolicy = new ClientRetryPolicy(3)          // Enable retries to improve resiliency.
-        })
+        new DefaultAzureCredential(),
+        new AIProjectClientOptions { RetryPolicy = new ClientRetryPolicy(3) })  // Enable retries to improve resiliency.
+    .GetProjectOpenAIClient()
     .GetResponsesClient()
-    .AsIChatClientWithStoredOutputDisabled(deploymentName)   // We want to manage chat history locally (not stored in the responses service), so that we can manage compaction ourselves.
+    .AsIChatClient(deploymentName)
     .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
     {
         Name = "ResearchAgent",
         Description = "A research assistant that plans and executes research tasks.",
-        AIContextProviders =
-        [
-            new TodoProvider(),         // Add an AIContextProvider to allow the agent to create a TODO list, which is stored in the session.
-            new AgentModeProvider(),    // Add an AIContextProvider that tracks the agent mode and allows switching mode. Current mode is stored in the session.
-            new FileMemoryProvider(     // Add an AIContextProvider that can store memories in files under a session specific working folder.
-                new FileSystemAgentFileStore(Path.Combine(AppContext.BaseDirectory, "agent-files")),
-                (_) => new FileMemoryState() { WorkingFolder = DateTime.UtcNow.ToString("yyyyMMdd_HHmmss") + "_" + Guid.NewGuid().ToString() })
-        ],
+        DisableFileAccess = true,                           // If enabled, this would allow the agent to read/write files in a working directory
+        OpenTelemetrySourceName = TracingSourceName,        // Use our custom source name so spans are captured by the TracerProvider above.
+        FileMemoryStore = new FileSystemAgentFileStore(     // Configure the file memory provider to store files in a local folder called "agent-files".
+            Path.Combine(AppContext.BaseDirectory, "agent-files")),
         ChatOptions = new ChatOptions
         {
             Instructions = instructions,
             Tools =
             [
-                ResponseTool.CreateWebSearchTool().AsAITool(),          // Add the foundry hosted web search tool that runs in the service.
-                new WebBrowsingTool(                                    // Add a local web browsing tool that converts html to markdown.
+                new WebBrowsingTool(                        // Add a local web browsing tool that converts html to markdown.
                     new WebBrowsingToolOptions { AllowPublicNetworks = true }),
             ],
-            MaxOutputTokens = MaxOutputTokens,                          // Set a high token limit for long research tasks with many tool calls and long outputs.
+            MaxOutputTokens = MaxOutputTokens,              // Set a high token limit for long research tasks with many tool calls and long outputs.
             Reasoning = new() { Effort = ReasoningEffort.Medium },
         },
-    })
-    .AsBuilder()
-    .UseToolApproval()                                                      // Add the ability to auto approve tools once a user has said they don't want to be asked again. Approval rules are tied to the session.
-    .Build();
+    });
 
 // Run the interactive console session using the shared HarnessConsole helper.
 await HarnessConsole.RunAgentAsync(
@@ -163,12 +105,14 @@ await HarnessConsole.RunAgentAsync(
     userPrompt: "Enter a research topic to get started.",
     new HarnessConsoleOptions
     {
-        Observers = HarnessConsoleOptions.BuildObserversWithPlanning(
-            agent,
-            planModeName: "plan",
-            executionModeName: "execute",
-            maxContextWindowTokens: MaxContextWindowTokens,
-            maxOutputTokens: MaxOutputTokens,
-            toolFormatters: [new DownloadUriToolFormatter(), .. ToolCallFormatter.BuildDefaultToolFormatters()]),
+        Observers = [
+            new OpenAIResponsesWebSearchDisplayObserver(),
+            .. HarnessConsoleOptions.BuildObserversWithPlanning(
+                agent,
+                planModeName: "plan",
+                executionModeName: "execute",
+                maxContextWindowTokens: MaxContextWindowTokens,
+                maxOutputTokens: MaxOutputTokens,
+                toolFormatters: [new DownloadUriToolFormatter(), .. ToolCallFormatter.BuildDefaultToolFormatters()])],
         CommandHandlers = HarnessConsoleOptions.BuildDefaultCommandHandlers(agent),
     });

dotnet/samples/02-agents/Harness/Harness_Step02_Research_WithBackgroundAgents/Harness_Step02_Research_WithBackgroundAgents.csproj

@@ -13,8 +13,8 @@
   </ItemGroup>
 
   <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
     <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Harness\Microsoft.Agents.AI.Harness.csproj" />
-    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
     <ProjectReference Include="..\Harness_Shared_Console\Harness_Shared_Console.csproj" />
   </ItemGroup>
 

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

@@ -0,0 +1,119 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to use the BackgroundAgentsProvider to delegate work to background agents.
+// A parent agent is given a list of stock tickers and instructed to find the closing price
+// for each ticker on December 31, 2025. It delegates the web searches to a background agent.
+// The HarnessAgent provides built-in WebSearch (HostedWebSearchTool) so no manual web search
+// tool configuration is needed on the background agent.
+//
+// Special commands:
+//   /exit    — End the session.
+
+#pragma warning disable OPENAI001 // Suppress experimental API warnings for Responses API usage.
+#pragma warning disable MAAI001  // Suppress experimental API warnings for Agents AI experiments.
+
+using System.ClientModel.Primitives;
+using Azure.AI.Projects;
+using Azure.Identity;
+using Harness.Shared.Console;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+var endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5.4";
+
+const int MaxContextWindowTokens = 1_050_000;
+const int MaxOutputTokens = 128_000;
+const string TracingSourceName = "Harness.SubAgents";
+
+// Set up OpenTelemetry tracing that writes spans to a text file.
+using var tracerProvider = HarnessTracing.CreateFileTracerProvider(TracingSourceName);
+
+// Create the AIProjectClient for communicating with the Foundry responses service.
+var projectClient = new AIProjectClient(
+    new Uri(endpoint),
+    new DefaultAzureCredential(),
+    new AIProjectClientOptions { RetryPolicy = new ClientRetryPolicy(3) });
+
+// --- Background agent: Web Search Agent ---
+// This agent uses the HarnessAgent's built-in HostedWebSearchTool to search the web.
+// Features not needed by this sub-agent are disabled.
+AIAgent webSearchAgent =
+    projectClient
+    .GetProjectOpenAIClient()
+    .GetResponsesClient()
+    .AsIChatClient(deploymentName)
+    .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
+    {
+        Name = "WebSearchAgent",
+        Description = "An agent that can search the web to find information.",
+        OpenTelemetrySourceName = TracingSourceName,
+        DisableTodoProvider = true,
+        DisableAgentModeProvider = true,
+        DisableFileMemory = true,   // If enabled, this would allow the agent to store memories as files in a directory associated with the current session
+        DisableFileAccess = true,   // If enabled, this would allow the agent to read/write files in a working directory
+        DisableToolApproval = true, // If enabled, this allows don't-ask-again approval functionality.
+        ChatOptions = new ChatOptions
+        {
+            Instructions = "You are a web search assistant. When asked to find information, use the web search tool to look it up and return a concise, factual answer.",
+        },
+    });
+
+// --- Parent agent: Stock Price Researcher ---
+// This agent orchestrates the background agent to look up stock prices in parallel.
+var parentInstructions =
+    """
+    You are a stock price research assistant. You have access to a web search background agent that can look up information on the web.
+
+    When given a list of stock tickers, your job is to find the closing price for each ticker on December 31, 2025.
+
+    ## Workflow
+
+    1. For each ticker, start a background task on the WebSearchAgent asking it to find the closing price on December 31, 2025.
+       - Start all background tasks before waiting for any of them to complete, so they run concurrently.
+    2. Wait for all background tasks to complete.
+    3. Retrieve the results from each background task.
+    4. Present a summary table with the ticker symbol and closing price for each stock.
+    5. Clear all completed tasks to free memory.
+
+    ## Important
+
+    - Always delegate web searches to the WebSearchAgent background agent. Do not try to answer from memory.
+    - If a background task fails or returns unclear results, continue the task with a more specific query.
+    - Present results in a clean markdown table format.
+    """;
+
+// --- Parent agent: Stock Price Researcher ---
+// This agent orchestrates the sub-agent to look up stock prices in parallel.
+// Most features are disabled since the parent only needs SubAgentsProvider.
+AIAgent parentAgent =
+    projectClient
+    .GetProjectOpenAIClient()
+    .GetResponsesClient()
+    .AsIChatClient(deploymentName)
+    .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
+    {
+        Name = "StockPriceResearcher",
+        Description = "An agent that researches stock prices using background agents.",
+        OpenTelemetrySourceName = TracingSourceName,
+        DisableTodoProvider = true,
+        DisableAgentModeProvider = true,
+        DisableFileMemory = true,   // If enabled, this would allow the agent to store memories as files in a directory associated with the current session
+        DisableFileAccess = true,   // If enabled, this would allow the agent to read/write files in a working directory
+        DisableToolApproval = true, // If enabled, this allows don't-ask-again approval functionality.
+        DisableWebSearch = true,
+        AIContextProviders =
+        [
+            new BackgroundAgentsProvider([webSearchAgent]),
+        ],
+        ChatOptions = new ChatOptions
+        {
+            Instructions = parentInstructions,
+            MaxOutputTokens = 16_000,
+        },
+    });
+
+// Run the interactive console session.
+await HarnessConsole.RunAgentAsync(
+    parentAgent,
+    userPrompt: "Enter a list of stock tickers (e.g., BAC, MSFT, BA):");

dotnet/samples/02-agents/Harness/Harness_Step02_Research_WithBackgroundAgents/README.md

@@ -1,24 +1,24 @@
-# Harness Step 02 — SubAgents (Stock Price Research)
+# Harness Step 02 — BackgroundAgents (Stock Price Research)
 
-This sample demonstrates how to use the **SubAgentsProvider** to delegate work from a parent agent to sub-agents. Both agents use `HarnessAgent` for pre-configured function invocation, per-service-call persistence, and context-window compaction.
+This sample demonstrates how to use the **BackgroundAgentsProvider** to delegate work from a parent agent to background agents. Both agents use `HarnessAgent` for pre-configured function invocation, per-service-call persistence, and context-window compaction.
 
 ## What It Does
 
-A parent agent receives a list of stock tickers and uses a web-search sub-agent to find the closing price for each ticker on December 31, 2025. The sub-tasks run concurrently, and results are presented in a summary table.
+A parent agent receives a list of stock tickers and uses a web-search background agent to find the closing price for each ticker on December 31, 2025. The background tasks run concurrently, and results are presented in a summary table.
 
 ### Architecture
 
 ```
-┌─────────────────────────────────┐
-│     StockPriceResearcher        │
-│         (Parent Agent)          │
-│                                 │
-│  SubAgentsProvider              │
-│    ├─ SubAgents_StartTask       │
-│    ├─ SubAgents_WaitFor...      │
-│    ├─ SubAgents_GetTaskResults  │
-│    └─ ...                       │
-└────────────┬────────────────────┘
+┌────────────────────────────────────────┐
+│     StockPriceResearcher               │
+│         (Parent Agent)                 │
+│                                        │
+│  BackgroundAgentsProvider              │
+│    ├─ BackgroundAgents_StartTask       │
+│    ├─ BackgroundAgents_WaitFor...      │
+│    ├─ BackgroundAgents_GetTaskResults  │
+│    └─ ...                              │
+└────────────┬───────────────────────────┘
              │  delegates to
              ▼
 ┌─────────────────────────────────┐
@@ -40,7 +40,7 @@ A parent agent receives a list of stock tickers and uses a web-search sub-agent
 ## Running the Sample
 
 ```bash
-cd dotnet/samples/02-agents/Harness/Harness_Step02_Research_WithSubAgents
+cd dotnet/samples/02-agents/Harness/Harness_Step02_Research_WithBackgroundAgents
 dotnet run
 ```
 
@@ -50,4 +50,4 @@ When prompted, enter a list of stock tickers such as:
 BAC, MSFT, BA
 ```
 
-The parent agent will delegate each ticker lookup to the web search sub-agent concurrently and present the results in a table.
+The parent agent will delegate each ticker lookup to the web search background agent concurrently and present the results in a table.

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

@@ -1,106 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample demonstrates how to use the SubAgentsProvider to delegate work to sub-agents.
-// A parent agent is given a list of stock tickers and instructed to find the closing price
-// for each ticker on December 31, 2025. It delegates the web searches to a sub-agent
-// equipped with Foundry's hosted web search tool.
-//
-// Special commands:
-//   /exit    — End the session.
-
-#pragma warning disable OPENAI001 // Suppress experimental API warnings for Responses API usage.
-#pragma warning disable MAAI001  // Suppress experimental API warnings for Agents AI experiments.
-
-using System.ClientModel.Primitives;
-using Azure.Identity;
-using Harness.Shared.Console;
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-using OpenAI;
-using OpenAI.Responses;
-
-var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_OPENAI_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5.4";
-
-const int MaxContextWindowTokens = 1_050_000;
-const int MaxOutputTokens = 128_000;
-
-// --- Sub-agent: Web Search Agent ---
-// This agent can search the web and is used by the parent agent to look up stock prices.
-AIAgent webSearchAgent =
-    new OpenAIClient(
-        new BearerTokenPolicy(new DefaultAzureCredential(), "https://ai.azure.com/.default"),
-        new OpenAIClientOptions()
-        {
-            Endpoint = new Uri(endpoint),
-            RetryPolicy = new ClientRetryPolicy(3)
-        })
-    .GetResponsesClient()
-    .AsIChatClientWithStoredOutputDisabled(deploymentName)
-    .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
-    {
-        Name = "WebSearchAgent",
-        Description = "An agent that can search the web to find information.",
-        ChatOptions = new ChatOptions
-        {
-            Instructions = "You are a web search assistant. When asked to find information, use the web search tool to look it up and return a concise, factual answer.",
-            Tools =
-            [
-                ResponseTool.CreateWebSearchTool().AsAITool(),
-            ],
-        },
-    });
-
-// --- Parent agent: Stock Price Researcher ---
-// This agent orchestrates the sub-agent to look up stock prices in parallel.
-var parentInstructions =
-    """
-    You are a stock price research assistant. You have access to a web search sub-agent that can look up information on the web.
-
-    When given a list of stock tickers, your job is to find the closing price for each ticker on December 31, 2025.
-
-    ## Workflow
-
-    1. For each ticker, start a sub-task on the WebSearchAgent asking it to find the closing price on December 31, 2025.
-       - Start all sub-tasks before waiting for any of them to complete, so they run concurrently.
-    2. Wait for all sub-tasks to complete.
-    3. Retrieve the results from each sub-task.
-    4. Present a summary table with the ticker symbol and closing price for each stock.
-    5. Clear all completed tasks to free memory.
-
-    ## Important
-
-    - Always delegate web searches to the WebSearchAgent sub-agent. Do not try to answer from memory.
-    - If a sub-task fails or returns unclear results, continue the task with a more specific query.
-    - Present results in a clean markdown table format.
-    """;
-
-AIAgent parentAgent =
-    new OpenAIClient(
-        new BearerTokenPolicy(new DefaultAzureCredential(), "https://ai.azure.com/.default"),
-        new OpenAIClientOptions()
-        {
-            Endpoint = new Uri(endpoint),
-            RetryPolicy = new ClientRetryPolicy(3)
-        })
-    .GetResponsesClient()
-    .AsIChatClientWithStoredOutputDisabled(deploymentName)
-    .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
-    {
-        Name = "StockPriceResearcher",
-        Description = "An agent that researches stock prices using sub-agents.",
-        AIContextProviders =
-        [
-            new SubAgentsProvider([webSearchAgent]),
-        ],
-        ChatOptions = new ChatOptions
-        {
-            Instructions = parentInstructions,
-            MaxOutputTokens = 16_000,
-        },
-    });
-
-// Run the interactive console session.
-await HarnessConsole.RunAgentAsync(
-    parentAgent,
-    userPrompt: "Enter a list of stock tickers (e.g., BAC, MSFT, BA):");

dotnet/samples/02-agents/Harness/Harness_Step03_DataProcessing/Harness_Step03_DataProcessing.csproj

@@ -13,13 +13,13 @@
   </ItemGroup>
 
   <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
     <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Harness\Microsoft.Agents.AI.Harness.csproj" />
-    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
     <ProjectReference Include="..\Harness_Shared_Console\Harness_Shared_Console.csproj" />
   </ItemGroup>
 
   <ItemGroup>
-    <Content Include="data\**\*" CopyToOutputDirectory="PreserveNewest" />
+    <Content Include="working\**\*" CopyToOutputDirectory="PreserveNewest" />
   </ItemGroup>
 
 </Project>

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

@@ -1,10 +1,12 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-// This sample demonstrates how to use a HarnessAgent with the FileAccessProvider
+// This sample demonstrates how to use a HarnessAgent with the default FileAccessProvider
 // to give an agent access to a folder of CSV data files. The agent can read, analyze,
 // and extract information from the data, then write results back as new files.
 //
-// The sample includes a pre-populated `data/` folder with sales transaction data.
+// The sample includes a pre-populated `working/` folder with sales transaction data.
+// The HarnessAgent's default FileAccessProvider uses `{cwd}/working` as its working directory,
+// which matches this sample's folder layout.
 // Ask the agent to analyze the data, produce summaries, or create new output files.
 //
 // Special commands:
@@ -14,22 +16,21 @@
 #pragma warning disable MAAI001  // Suppress experimental API warnings for Agents AI experiments.
 
 using System.ClientModel.Primitives;
+using Azure.AI.Projects;
 using Azure.Identity;
 using Harness.Shared.Console;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
-using OpenAI;
-using OpenAI.Responses;
 
-var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_OPENAI_ENDPOINT is not set.");
+var endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5.4";
 
 const int MaxContextWindowTokens = 1_050_000;
 const int MaxOutputTokens = 128_000;
+const string TracingSourceName = "Harness.DataProcessing";
 
-// Point the file store at the data/ folder that ships with the sample.
-var dataFolder = Path.Combine(AppContext.BaseDirectory, "data");
-var fileStore = new FileSystemAgentFileStore(dataFolder);
+// Set up OpenTelemetry tracing that writes spans to a text file.
+using var tracerProvider = HarnessTracing.CreateFileTracerProvider(TracingSourceName);
 
 var instructions =
     """
@@ -56,25 +57,27 @@ var instructions =
     - Always explain what you learned and what you are going to do next between tool calls, so the user can follow along with your thought process.
     """;
 
-// Create the chat client from the OpenAI provider.
+// Create the agent using AsHarnessAgent. The FileAccessStore is explicitly set to the
+// sample's working/ folder (copied to the output directory) so it works regardless of cwd.
+// Unused features are disabled.
 AIAgent agent =
-    new OpenAIClient(
-        new BearerTokenPolicy(new DefaultAzureCredential(), "https://ai.azure.com/.default"),
-        new OpenAIClientOptions()
-        {
-            Endpoint = new Uri(endpoint),
-            RetryPolicy = new ClientRetryPolicy(3)
-        })
+    new AIProjectClient(
+        new Uri(endpoint),
+        new DefaultAzureCredential(),
+        new AIProjectClientOptions { RetryPolicy = new ClientRetryPolicy(3) })
+    .GetProjectOpenAIClient()
     .GetResponsesClient()
-    .AsIChatClientWithStoredOutputDisabled(deploymentName)
+    .AsIChatClient(deploymentName)
     .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
     {
         Name = "DataAnalyst",
         Description = "A data analyst assistant that reads, analyzes, and processes data files.",
-        AIContextProviders =
-        [
-            new FileAccessProvider(fileStore),
-        ],
+        OpenTelemetrySourceName = TracingSourceName,
+        FileAccessStore = new FileSystemAgentFileStore(Path.Combine(AppContext.BaseDirectory, "working")),
+        DisableTodoProvider = true,
+        DisableAgentModeProvider = true,
+        DisableFileMemory = true,   // If enabled, this would allow the agent to store memories as files in a directory associated with the current session
+        DisableWebSearch = true,
         ChatOptions = new ChatOptions
         {
             Instructions = instructions,

dotnet/samples/02-agents/Harness/Harness_Step03_DataProcessing/README.md

@@ -1,11 +1,11 @@
 # What this sample demonstrates
 
-This sample demonstrates how to use a `HarnessAgent` with the `FileAccessProvider` to give an agent access to a folder of data files for reading, analyzing, and writing results. The `HarnessAgent` pre-configures function invocation, per-service-call chat history persistence, and in-loop compaction — so the sample only needs to supply the chat client, token limits, and application-specific options.
+This sample demonstrates how to use a `HarnessAgent` with the default `FileAccessProvider` to give an agent access to a folder of data files for reading, analyzing, and writing results. The `HarnessAgent` pre-configures function invocation, per-service-call chat history persistence, in-loop compaction, tool approval, and OpenTelemetry — so the sample only needs to supply the chat client, token limits, custom instructions, and opt out of unused features.
 
 Key features showcased:
 
 - **HarnessAgent** — a pre-configured agent that wraps a `ChatClientAgent` with function invocation, per-service-call persistence, and context-window compaction
-- **FileAccessProvider** — gives the agent tools to read, write, list, search, and delete files in a shared data folder
+- **FileAccessProvider** — the HarnessAgent's default file access provider uses `{cwd}/working` as its working directory, matching this sample's `working/` folder
 - **CSV data processing** — the agent reads sales transaction data and performs analysis on demand
 - **Output file creation** — the agent can write summaries, filtered data, or reports back to the data folder
 - **Streaming output** — responses are streamed token-by-token for a natural experience
@@ -39,7 +39,7 @@ dotnet run --project samples/02-agents/Harness/Harness_Step03_DataProcessing
 
 ## What to Expect
 
-The sample starts an interactive conversation with a data analyst agent. The `data/` folder contains a `sales.csv` file with ~50 rows of sales transaction data (date, product, category, quantity, unit price, region, salesperson).
+The sample starts an interactive conversation with a data analyst agent. The `working/` folder contains a `sales.csv` file with ~50 rows of sales transaction data (date, product, category, quantity, unit price, region, salesperson).
 
 You can ask the agent to:
 
@@ -53,7 +53,7 @@ E.g. try the following prompt `Please process the sales.csv file by first filter
 
 ## Sample Data
 
-The included `data/sales.csv` contains sales transactions from January to March 2025 with the following columns:
+The included `working/sales.csv` contains sales transactions from January to March 2025 with the following columns:
 
 | Column | Description |
 | --- | --- |

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

@@ -7,5 +7,5 @@ Samples demonstrating the [Harness AIContextProviders](../../../src/Microsoft.Ag
 | Sample | Description |
 | --- | --- |
 | [Harness_Step01_Research](./Harness_Step01_Research/README.md) | Using a ChatClientAgent with TodoProvider and AgentModeProvider for research, showcasing planning mode and todo management |
-| [Harness_Step02_Research_WithSubAgents](./Harness_Step02_Research_WithSubAgents/README.md) | Using SubAgentsProvider to delegate stock price lookups to a web-search sub-agent concurrently |
+| [Harness_Step02_Research_WithBackgroundAgents](./Harness_Step02_Research_WithBackgroundAgents/README.md) | Using BackgroundAgentsProvider to delegate stock price lookups to a web-search background agent concurrently |
 | [Harness_Step03_DataProcessing](./Harness_Step03_DataProcessing/README.md) | Using FileAccessProvider to give an agent access to CSV data files for reading, analysis, and output generation |

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/HostedAzureSearchRag.csproj

@@ -11,7 +11,7 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.AI.Projects" />
     <PackageReference Include="Azure.Identity" />
     <PackageReference Include="Azure.Search.Documents" />
     <PackageReference Include="DotNetEnv" />
@@ -22,6 +22,7 @@
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry.Hosting\Microsoft.Agents.AI.Foundry.Hosting.csproj" />
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\Hosted_Shared_Contributor_Setup\Hosted_Shared_Contributor_Setup.csproj" />
   </ItemGroup>
 
   <!-- For end-users: uncomment the PackageReference below and remove the ProjectReferences above

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

@@ -14,6 +14,7 @@ using Azure.Identity;
 using Azure.Search.Documents;
 using Azure.Search.Documents.Models;
 using DotNetEnv;
+using Hosted_Shared_Contributor_Setup;
 using Microsoft.Agents.AI;
 using Microsoft.Agents.AI.Foundry.Hosting;
 using Microsoft.Extensions.AI;
@@ -66,14 +67,15 @@ AIAgent agent = new AIProjectClient(new Uri(projectEndpoint), credential)
 // Host the agent as a Foundry Hosted Agent using the Responses API.
 var builder = WebApplication.CreateBuilder(args);
 builder.Services.AddFoundryResponses(agent);
+builder.Services.AddDevTemporaryLocalContributorSetup(); // Local Docker debugging only - must not be used in production.
 
 var app = builder.Build();
 app.MapFoundryResponses();
 
-if (app.Environment.IsDevelopment())
-{
-    app.MapFoundryResponses("openai/v1");
-}
+// 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();
 

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

@@ -18,6 +18,7 @@
   <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

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

@@ -4,6 +4,7 @@ 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;
 
@@ -40,59 +41,14 @@ AIAgent agent = new AIProjectClient(projectEndpoint, credential)
 // Host the agent as a Foundry Hosted Agent using the Responses API.
 var builder = WebApplication.CreateBuilder(args);
 builder.Services.AddFoundryResponses(agent);
+builder.Services.AddDevTemporaryLocalContributorSetup(); // Local Docker debugging only - must not be used in production.
 
 var app = builder.Build();
 app.MapFoundryResponses();
 
-// In Development, also map the OpenAI-compatible route that AIProjectClient uses.
-if (app.Environment.IsDevelopment())
-{
-    app.MapFoundryResponses("openai/v1");
-}
+// 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();
-
-/// <summary>
-/// A <see cref="TokenCredential"/> for local Docker debugging only.
-///
-/// When debugging and testing a hosted agent in a local Docker container, Azure CLI
-/// and other interactive credentials are not available. This credential reads a
-/// pre-fetched bearer token from the <c>AZURE_BEARER_TOKEN</c> environment variable.
-///
-/// This should NOT be used in production — tokens expire (~1 hour) and cannot be refreshed.
-/// In production, the Foundry platform injects a managed identity automatically.
-///
-/// Generate a token on your host and pass it to the container:
-///   export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
-///   docker run -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN ...
-/// </summary>
-internal sealed class DevTemporaryTokenCredential : TokenCredential
-{
-    private const string EnvironmentVariable = "AZURE_BEARER_TOKEN";
-    private readonly string? _token;
-
-    public DevTemporaryTokenCredential()
-    {
-        this._token = Environment.GetEnvironmentVariable(EnvironmentVariable);
-    }
-
-    public override AccessToken GetToken(TokenRequestContext requestContext, CancellationToken cancellationToken)
-    {
-        return this.GetAccessToken();
-    }
-
-    public override ValueTask<AccessToken> GetTokenAsync(TokenRequestContext requestContext, CancellationToken cancellationToken)
-    {
-        return new ValueTask<AccessToken>(this.GetAccessToken());
-    }
-
-    private AccessToken GetAccessToken()
-    {
-        if (string.IsNullOrEmpty(this._token) || this._token == "DefaultAzureCredential")
-        {
-            throw new CredentialUnavailableException($"{EnvironmentVariable} environment variable is not set.");
-        }
-
-        return new AccessToken(this._token, DateTimeOffset.UtcNow.AddHours(1));
-    }
-}

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files/HostedFiles.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk.Web">
+<Project Sdk="Microsoft.NET.Sdk.Web">
 
   <PropertyGroup>
     <TargetFrameworks>net10.0</TargetFrameworks>
@@ -11,7 +11,7 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.AI.Projects" />
     <PackageReference Include="Azure.Identity" />
     <PackageReference Include="DotNetEnv" />
   </ItemGroup>
@@ -28,6 +28,7 @@
   <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

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

@@ -35,6 +35,7 @@ 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;
 using Microsoft.Extensions.AI;
@@ -175,14 +176,15 @@ AIAgent agent = new AIProjectClient(new Uri(endpoint), credential)
 
 var builder = WebApplication.CreateBuilder(args);
 builder.Services.AddFoundryResponses(agent);
+builder.Services.AddDevTemporaryLocalContributorSetup(); // Local Docker debugging only - must not be used in production.
 
 var app = builder.Build();
 app.MapFoundryResponses();
 
-if (app.Environment.IsDevelopment())
-{
-    app.MapFoundryResponses("openai/v1");
-}
+// 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();
 

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

@@ -18,6 +18,7 @@
   <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

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

@@ -5,6 +5,7 @@ using Azure.AI.Projects.Agents;
 using Azure.Core;
 using Azure.Identity;
 using DotNetEnv;
+using Hosted_Shared_Contributor_Setup;
 using Microsoft.Agents.AI.Foundry;
 using Microsoft.Agents.AI.Foundry.Hosting;
 
@@ -33,59 +34,14 @@ FoundryAgent agent = aiProjectClient.AsAIAgent(agentRecord);
 // Host the agent as a Foundry Hosted Agent using the Responses API.
 var builder = WebApplication.CreateBuilder(args);
 builder.Services.AddFoundryResponses(agent);
+builder.Services.AddDevTemporaryLocalContributorSetup(); // Local Docker debugging only - must not be used in production.
 
 var app = builder.Build();
 app.MapFoundryResponses();
 
-// In Development, also map the OpenAI-compatible route that AIProjectClient uses.
-if (app.Environment.IsDevelopment())
-{
-    app.MapFoundryResponses("openai/v1");
-}
+// 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();
-
-/// <summary>
-/// A <see cref="TokenCredential"/> for local Docker debugging only.
-///
-/// When debugging and testing a hosted agent in a local Docker container, Azure CLI
-/// and other interactive credentials are not available. This credential reads a
-/// pre-fetched bearer token from the <c>AZURE_BEARER_TOKEN</c> environment variable.
-///
-/// This should NOT be used in production — tokens expire (~1 hour) and cannot be refreshed.
-/// In production, the Foundry platform injects a managed identity automatically.
-///
-/// Generate a token on your host and pass it to the container:
-///   export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
-///   docker run -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN ...
-/// </summary>
-internal sealed class DevTemporaryTokenCredential : TokenCredential
-{
-    private const string EnvironmentVariable = "AZURE_BEARER_TOKEN";
-    private readonly string? _token;
-
-    public DevTemporaryTokenCredential()
-    {
-        this._token = Environment.GetEnvironmentVariable(EnvironmentVariable);
-    }
-
-    public override AccessToken GetToken(TokenRequestContext requestContext, CancellationToken cancellationToken)
-    {
-        return this.GetAccessToken();
-    }
-
-    public override ValueTask<AccessToken> GetTokenAsync(TokenRequestContext requestContext, CancellationToken cancellationToken)
-    {
-        return new ValueTask<AccessToken>(this.GetAccessToken());
-    }
-
-    private AccessToken GetAccessToken()
-    {
-        if (string.IsNullOrEmpty(this._token) || this._token == "DefaultAzureCredential")
-        {
-            throw new CredentialUnavailableException($"{EnvironmentVariable} environment variable is not set.");
-        }
-
-        return new AccessToken(this._token, DateTimeOffset.UtcNow.AddHours(1));
-    }
-}

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

@@ -20,6 +20,7 @@
   <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

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

@@ -11,6 +11,7 @@ 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;
 using Microsoft.Extensions.AI;
@@ -112,53 +113,18 @@ AIAgent agent = new AIProjectClient(new Uri(endpoint), credential)
 
 var builder = WebApplication.CreateBuilder(args);
 builder.Services.AddFoundryResponses(agent);
+builder.Services.AddDevTemporaryLocalContributorSetup(); // Local Docker debugging only - must not be used in production.
 
 var app = builder.Build();
 app.MapFoundryResponses();
 
-if (app.Environment.IsDevelopment())
-{
-    app.MapFoundryResponses("openai/v1");
-}
+// 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();
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
 internal sealed record Hotel(string Name, int PricePerNight, double Rating, string Location);
-
-/// <summary>
-/// A <see cref="TokenCredential"/> for local Docker debugging only.
-/// Reads a pre-fetched bearer token from the <c>AZURE_BEARER_TOKEN</c> environment variable
-/// once at startup. This should NOT be used in production.
-///
-/// Generate a token on your host and pass it to the container:
-///   export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
-///   docker run -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN ...
-/// </summary>
-internal sealed class DevTemporaryTokenCredential : TokenCredential
-{
-    private const string EnvironmentVariable = "AZURE_BEARER_TOKEN";
-    private readonly string? _token;
-
-    public DevTemporaryTokenCredential()
-    {
-        this._token = Environment.GetEnvironmentVariable(EnvironmentVariable);
-    }
-
-    public override AccessToken GetToken(TokenRequestContext requestContext, CancellationToken cancellationToken)
-        => this.GetAccessToken();
-
-    public override ValueTask<AccessToken> GetTokenAsync(TokenRequestContext requestContext, CancellationToken cancellationToken)
-        => new(this.GetAccessToken());
-
-    private AccessToken GetAccessToken()
-    {
-        if (string.IsNullOrEmpty(this._token) || this._token == "DefaultAzureCredential")
-        {
-            throw new CredentialUnavailableException($"{EnvironmentVariable} environment variable is not set.");
-        }
-
-        return new AccessToken(this._token, DateTimeOffset.UtcNow.AddHours(1));
-    }
-}

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

@@ -21,6 +21,7 @@
   <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

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

@@ -19,6 +19,7 @@ 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;
 using Microsoft.Extensions.AI;
@@ -81,50 +82,14 @@ AIAgent agent = new AIProjectClient(projectEndpoint, credential)
 // Host the agent as a Foundry Hosted Agent using the Responses API.
 var builder = WebApplication.CreateBuilder(args);
 builder.Services.AddFoundryResponses(agent);
+builder.Services.AddDevTemporaryLocalContributorSetup(); // Local Docker debugging only - must not be used in production.
 
 var app = builder.Build();
 app.MapFoundryResponses();
 
-// In Development, also map the OpenAI-compatible route that AIProjectClient uses.
-if (app.Environment.IsDevelopment())
-{
-    app.MapFoundryResponses("openai/v1");
-}
+// 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();
-
-/// <summary>
-/// A <see cref="TokenCredential"/> for local Docker debugging only.
-/// Reads a pre-fetched bearer token from the <c>AZURE_BEARER_TOKEN</c> environment variable
-/// once at startup. This should NOT be used in production.
-///
-/// Generate a token on your host and pass it to the container:
-///   export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
-///   docker run -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN ...
-/// </summary>
-internal sealed class DevTemporaryTokenCredential : TokenCredential
-{
-    private const string EnvironmentVariable = "AZURE_BEARER_TOKEN";
-    private readonly string? _token;
-
-    public DevTemporaryTokenCredential()
-    {
-        this._token = Environment.GetEnvironmentVariable(EnvironmentVariable);
-    }
-
-    public override AccessToken GetToken(TokenRequestContext requestContext, CancellationToken cancellationToken)
-        => this.GetAccessToken();
-
-    public override ValueTask<AccessToken> GetTokenAsync(TokenRequestContext requestContext, CancellationToken cancellationToken)
-        => new(this.GetAccessToken());
-
-    private AccessToken GetAccessToken()
-    {
-        if (string.IsNullOrEmpty(this._token) || this._token == "DefaultAzureCredential")
-        {
-            throw new CredentialUnavailableException($"{EnvironmentVariable} environment variable is not set.");
-        }
-
-        return new AccessToken(this._token, DateTimeOffset.UtcNow.AddHours(1));
-    }
-}

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

@@ -0,0 +1,12 @@
+AZURE_AI_PROJECT_ENDPOINT=<your-azure-ai-project-endpoint>
+ASPNETCORE_URLS=http://+:8088
+ASPNETCORE_ENVIRONMENT=Development
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+AZURE_AI_EMBEDDING_DEPLOYMENT_NAME=text-embedding-ada-002
+AZURE_AI_MEMORY_STORE_ID=hosted-memory-sample
+AGENT_NAME=hosted-memory-agent
+AZURE_BEARER_TOKEN=DefaultAzureCredential
+# When running outside the Foundry platform the platform-injected isolation keys are absent.
+# These two variables provide fallback values for local Docker debugging only.
+HOSTED_USER_ISOLATION_KEY=local-dev-user
+HOSTED_CHAT_ISOLATION_KEY=local-dev-chat

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

@@ -0,0 +1,26 @@
+# Dockerfile for end-users consuming the Agent Framework via NuGet packages.
+#
+# This Dockerfile performs a full `dotnet restore` and `dotnet publish` inside the container,
+# which only succeeds when the project references its dependencies via PackageReference (see the
+# commented-out section in HostedMemoryAgent.csproj). Contributors building from the
+# agent-framework repository source must use Dockerfile.contributor instead because
+# ProjectReference dependencies live outside this folder and cannot be restored from inside
+# this build context.
+#
+# 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", "HostedMemoryAgent.dll"]

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

@@ -0,0 +1,23 @@
+# 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-memory-agent .
+#   docker run --rm -p 8088:8088 \
+#     -e AGENT_NAME=hosted-memory-agent \
+#     -e HOSTED_USER_ISOLATION_KEY=alice \
+#     -e HOSTED_CHAT_ISOLATION_KEY=alice-chat-1 \
+#     --env-file .env hosted-memory-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", "HostedMemoryAgent.dll"]

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-MemoryAgent/HostedMemoryAgent.csproj

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

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

@@ -0,0 +1,87 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// Hosted-MemoryAgent
+//
+// Demonstrates how to host an agent that uses FoundryMemoryProvider so that user-private memories
+// persist across requests and across sessions, scoped per user via the Foundry platform's
+// isolation key headers.
+//
+// Memory scope flows from request -> hosting layer -> session -> provider:
+//   1. Foundry sets x-agent-user-isolation-key on every inbound request.
+//   2. AgentFrameworkResponseHandler reads context.Isolation.UserIsolationKey via the registered
+//      HostedSessionIsolationKeyProvider and stores it on the session as a HostedSessionContext.
+//   3. FoundryMemoryProvider's stateInitializer reads HostedSessionContext.UserId and uses it as
+//      the FoundryMemoryProviderScope, partitioning memories per user.
+
+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;
+using Microsoft.Agents.AI.Foundry.Hosting;
+using Microsoft.Extensions.AI;
+
+// Load .env file if present (for local development).
+Env.TraversePath().Load();
+
+var projectEndpoint = new Uri(Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set."));
+var agentName = Environment.GetEnvironmentVariable("AGENT_NAME")
+    ?? throw new InvalidOperationException("AGENT_NAME is not set.");
+var deployment = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";
+var embeddingDeployment = Environment.GetEnvironmentVariable("AZURE_AI_EMBEDDING_DEPLOYMENT_NAME") ?? "text-embedding-ada-002";
+var memoryStoreName = Environment.GetEnvironmentVariable("AZURE_AI_MEMORY_STORE_ID") ?? "hosted-memory-sample";
+
+// Use a chained credential: try a temporary dev token first (for local Docker debugging),
+// then fall back to DefaultAzureCredential (for local dev via dotnet run / managed identity in foundry).
+TokenCredential credential = new ChainedTokenCredential(
+    new DevTemporaryTokenCredential(),
+    new DefaultAzureCredential());
+
+AIProjectClient projectClient = new(projectEndpoint, credential);
+
+// FoundryMemoryProvider partitions memories per end user via a built-in HostedFoundryMemoryProviderScopes
+// helper that reads the platform-injected user isolation key from the HostedSessionContext that the
+// hosting layer placed on the session.
+FoundryMemoryProvider memoryProvider = new(
+    projectClient,
+    memoryStoreName,
+    stateInitializer: HostedFoundryMemoryProviderScopes.PerUser());
+
+// Provision the memory store on startup if it does not already exist. EnsureMemoryStoreCreatedAsync
+// is idempotent. Doing this once at start avoids per-request latency.
+await memoryProvider.EnsureMemoryStoreCreatedAsync(deployment, embeddingDeployment, "Memory store for the hosted travel-assistant sample.");
+
+const string AgentInstructions = """
+    You are a friendly travel assistant. When the user shares trip preferences, destinations,
+    travel companions, or constraints, remember them and use them in later turns. Use known
+    memories about the user when responding, and do not invent details.
+    """;
+
+ChatClientAgent agent = projectClient.AsAIAgent(new ChatClientAgentOptions()
+{
+    Name = agentName,
+    ChatOptions = new ChatOptions
+    {
+        ModelId = deployment,
+        Instructions = AgentInstructions
+    },
+    AIContextProviders = [memoryProvider]
+});
+
+// Host the agent as a Foundry Hosted Agent using the Responses API.
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddFoundryResponses(agent);
+builder.Services.AddDevTemporaryLocalContributorSetup(); // Local Docker debugging only - must not be used in production.
+
+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();

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

@@ -0,0 +1,155 @@
+# Hosted-MemoryAgent
+
+A hosted Foundry agent that uses **FoundryMemoryProvider** to remember user-private details across
+requests and across sessions, scoped per end user via the Foundry platform's isolation keys. The
+agent plays a friendly travel assistant: tell it about your trip, ask follow-up questions in a new
+session, and it recalls what it learned about you.
+
+This sample exists to demonstrate two things together:
+
+1. How to host an agent that consumes a `Microsoft.Extensions.AI.AIContextProvider` (specifically
+   `FoundryMemoryProvider`) under the Foundry Responses hosting layer.
+2. How the new `HostedSessionContext` flows from the `Foundry` platform isolation headers
+   (`x-agent-user-isolation-key`, `x-agent-chat-isolation-key`) through the
+   `HostedSessionIsolationKeyProvider` into the provider's `stateInitializer`, so memories are
+   partitioned per user automatically.
+
+## Prerequisites
+
+- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
+- An Azure AI Foundry project with at least one chat model deployment and one embedding model deployment
+- Azure CLI logged in (`az login`)
+
+## Configuration
+
+Copy the template and fill in your values:
+
+```bash
+cp .env.example .env
+```
+
+Required:
+
+```env
+AZURE_AI_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+AZURE_AI_EMBEDDING_DEPLOYMENT_NAME=text-embedding-ada-002
+AZURE_AI_MEMORY_STORE_ID=hosted-memory-sample
+AGENT_NAME=hosted-memory-agent
+ASPNETCORE_URLS=http://+:8088
+ASPNETCORE_ENVIRONMENT=Development
+```
+
+For local container runs only (the platform supplies these in production):
+
+```env
+HOSTED_USER_ISOLATION_KEY=alice
+HOSTED_CHAT_ISOLATION_KEY=alice-chat-1
+```
+
+> `.env` is gitignored. The `.env.example` template is checked in as a reference.
+
+## How memory scoping works
+
+| Layer | Source of the user identity |
+|---|---|
+| Inbound request | The Foundry platform sets `x-agent-user-isolation-key` and `x-agent-chat-isolation-key` headers on every request. |
+| Hosting layer | `AgentFrameworkResponseHandler` resolves a `HostedSessionIsolationKeyProvider` from DI and calls `GetKeysAsync(context, request, ct)`. The default implementation reads `context.Isolation.UserIsolationKey` and `context.Isolation.ChatIsolationKey`. |
+| Session | The handler stores the resolved values on the session as a `HostedSessionContext` on the first request, and validates the values on every subsequent request that resumes the same conversation (mismatch returns 403). |
+| Memory provider | The sample's `stateInitializer` reads `session.GetHostedContext().UserId` and uses it as the `FoundryMemoryProviderScope`. Memories are partitioned per user. |
+
+When running outside the Foundry platform the headers are absent. The sample registers
+`DevTemporaryLocalSessionIsolationKeyProvider` (via `AddDevTemporaryLocalContributorSetup`) which
+falls back to the `HOSTED_USER_ISOLATION_KEY` and `HOSTED_CHAT_ISOLATION_KEY` environment variables,
+defaulting to a single `local-dev-*` bucket when neither is set.
+
+> **Production warning.** Never register `DevTemporaryLocalSessionIsolationKeyProvider` in
+> production. The Foundry platform sets the isolation keys for every inbound request, and
+> client-supplied environment variables can be forged.
+
+## Running directly (contributors)
+
+This project uses `ProjectReference` to build against the local Agent Framework source.
+
+```bash
+cd dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-MemoryAgent
+dotnet run
+```
+
+The agent starts on `http://localhost:8088`.
+
+### Test it
+
+```bash
+curl -X POST http://localhost:8088/responses \
+  -H "Content-Type: application/json" \
+  -d '{"input": "Hi! My name is Taylor and I am planning a hiking trip to Patagonia in November.", "model": "hosted-memory-agent"}'
+```
+
+Wait a few seconds for memory extraction, then ask a follow-up using the response id from the
+previous call as `previous_response_id`:
+
+```bash
+curl -X POST http://localhost:8088/responses \
+  -H "Content-Type: application/json" \
+  -d '{"input": "What do you already know about my upcoming trip?", "previous_response_id": "<id>", "model": "hosted-memory-agent"}'
+```
+
+## Running with Docker
+
+Since this project uses `ProjectReference`, the standard `Dockerfile` cannot resolve dependencies
+outside this folder. Use `Dockerfile.contributor` which takes a pre-published output.
+
+### 1. Publish for the container runtime (Linux Alpine)
+
+```bash
+dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+```
+
+### 2. Build the Docker image
+
+```bash
+docker build -f Dockerfile.contributor -t hosted-memory-agent .
+```
+
+### 3. Run the container
+
+```bash
+export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
+
+docker run --rm -p 8088:8088 \
+  -e AGENT_NAME=hosted-memory-agent \
+  -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN \
+  -e HOSTED_USER_ISOLATION_KEY=alice \
+  -e HOSTED_CHAT_ISOLATION_KEY=alice-chat-1 \
+  --env-file .env \
+  hosted-memory-agent
+```
+
+### 4. Smoke test the running container
+
+A scripted smoke test that exercises memory recall and per-user isolation across two simulated
+users is provided at `scripts/smoke.ps1`. From the sample folder:
+
+```powershell
+pwsh ./scripts/smoke.ps1
+```
+
+The script publishes the project, builds the image, runs the container with two distinct
+`HOSTED_USER_ISOLATION_KEY` values, drives a multi-turn conversation per user, asserts that each
+user only sees their own memories, and exits non-zero on failure.
+
+## 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
+`HostedMemoryAgent.csproj` for the `PackageReference` alternative.
+
+## How it differs from sibling samples
+
+| | Hosted-ChatClientAgent | Hosted-MemoryAgent |
+|---|---|---|
+| **Agent definition** | Inline (`AsAIAgent(model, instructions)`) | Inline, plus `AIContextProviders = [memoryProvider]` |
+| **State** | None beyond the conversation history | Per-user memories persisted in Foundry Memory |
+| **Identity** | Not used | Required: `HostedSessionContext.UserId` flows into the memory scope |
+| **Local dev** | `AddDevTemporaryLocalContributorSetup()` keeps requests succeeding when isolation headers are absent | Same; additionally honours `HOSTED_USER_ISOLATION_KEY` to simulate distinct users |

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

@@ -0,0 +1,31 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/AgentManifest.yaml
+name: hosted-memory-agent
+displayName: "Hosted Memory Agent"
+
+description: >
+  A travel-assistant hosted agent that uses FoundryMemoryProvider to remember user-private
+  preferences and details across sessions. Memory is scoped per end user via the Foundry
+  platform's isolation key headers.
+
+metadata:
+  tags:
+    - AI Agent Hosting
+    - Azure AI AgentServer
+    - Responses Protocol
+    - Streaming
+    - Agent Framework
+    - Memory
+    - Foundry Memory
+
+template:
+  name: hosted-memory-agent
+  kind: hosted
+  protocols:
+    - protocol: responses
+      version: 1.0.0
+  resources:
+    cpu: "0.25"
+    memory: 0.5Gi
+parameters:
+  properties: []
+resources: []

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

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

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-MemoryAgent/scripts/smoke.ps1

@@ -0,0 +1,110 @@
+#requires -Version 7
+<#
+.SYNOPSIS
+  Local smoke test for the Hosted-MemoryAgent sample.
+.DESCRIPTION
+  Publishes the sample, builds the contributor Docker image, runs the container twice with two
+  distinct HOSTED_USER_ISOLATION_KEY values, drives a multi-turn conversation per user via curl
+  invocations, and asserts that each user only sees their own remembered details.
+  Exits non-zero on failure.
+
+  Prerequisites:
+    - Docker
+    - az login (token is fetched from the host)
+    - .env populated with AZURE_AI_PROJECT_ENDPOINT and model deployments
+.NOTES
+  This script is for local Docker debugging only. The Foundry platform supplies the isolation
+  keys for every inbound request in production and the dev fallback used here must not be
+  enabled in production deployments.
+#>
+
+[CmdletBinding()]
+param(
+    [int]$Port = 8088,
+    [string]$ImageName = 'hosted-memory-agent-smoke',
+    [int]$RecallDelaySeconds = 25
+)
+
+$ErrorActionPreference = 'Stop'
+Set-Location -Path $PSScriptRoot/..
+
+if (-not (Test-Path .env)) {
+    throw '.env not found. Copy .env.example to .env and fill in AZURE_AI_PROJECT_ENDPOINT.'
+}
+
+Write-Host '==> Publishing sample for linux-musl-x64 ...'
+dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out --tl:off | Out-Host
+if ($LASTEXITCODE -ne 0) { throw 'dotnet publish failed.' }
+
+Write-Host '==> Building docker image ...'
+docker build -f Dockerfile.contributor -t $ImageName . | Out-Host
+if ($LASTEXITCODE -ne 0) { throw 'docker build failed.' }
+
+Write-Host '==> Fetching bearer token ...'
+$bearer = az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv
+if (-not $bearer) { throw 'Failed to obtain bearer token. Run az login.' }
+
+function Start-Container([string]$UserKey, [string]$ChatKey, [string]$ContainerName) {
+    docker rm -f $ContainerName 2>$null | Out-Null
+    docker run -d --name $ContainerName -p ${Port}:8088 `
+        -e AGENT_NAME=hosted-memory-agent `
+        -e AZURE_BEARER_TOKEN=$bearer `
+        -e HOSTED_USER_ISOLATION_KEY=$UserKey `
+        -e HOSTED_CHAT_ISOLATION_KEY=$ChatKey `
+        --env-file .env `
+        $ImageName | Out-Host
+    if ($LASTEXITCODE -ne 0) { throw "docker run failed for $ContainerName." }
+    # Wait briefly for the listener to come up.
+    Start-Sleep -Seconds 6
+}
+
+function Invoke-Agent([string]$Prompt, [string]$PreviousResponseId = $null) {
+    $body = @{ input = $Prompt; model = 'hosted-memory-agent' }
+    if ($PreviousResponseId) { $body['previous_response_id'] = $PreviousResponseId }
+    $json = $body | ConvertTo-Json -Compress
+    $resp = Invoke-RestMethod -Method Post -Uri "http://localhost:$Port/responses" -ContentType 'application/json' -Body $json
+    return $resp
+}
+
+function Assert-Contains([string]$Haystack, [string]$Needle, [string]$Label) {
+    if ($Haystack -notmatch [regex]::Escape($Needle)) {
+        throw "FAILED [$Label]: expected response to contain '$Needle' but got: $Haystack"
+    }
+    Write-Host "PASS  [$Label]: response contains '$Needle'."
+}
+
+function Assert-NotContains([string]$Haystack, [string]$Needle, [string]$Label) {
+    if ($Haystack -match [regex]::Escape($Needle)) {
+        throw "FAILED [$Label]: response unexpectedly contains '$Needle': $Haystack"
+    }
+    Write-Host "PASS  [$Label]: response does not contain '$Needle'."
+}
+
+try {
+    Write-Host '==> Phase 1: alice teaches the agent her trip details ...'
+    Start-Container -UserKey 'alice' -ChatKey 'alice-chat-1' -ContainerName 'hosted-memory-smoke-alice'
+    $r1 = Invoke-Agent -Prompt 'Hi! My name is Taylor and I am planning a hiking trip to Patagonia in November.'
+    $r2 = Invoke-Agent -Prompt 'I am travelling with my sister and we love finding scenic viewpoints.' -PreviousResponseId $r1.id
+
+    Write-Host "==> Waiting $RecallDelaySeconds s for memory extraction ..."
+    Start-Sleep -Seconds $RecallDelaySeconds
+
+    $r3 = Invoke-Agent -Prompt 'What do you already know about my upcoming trip?' -PreviousResponseId $r2.id
+    $aliceText = ($r3.output | ForEach-Object { $_.content | ForEach-Object { $_.text } }) -join ' '
+    Assert-Contains $aliceText 'Patagonia' 'alice recall: Patagonia'
+
+    docker rm -f hosted-memory-smoke-alice | Out-Null
+
+    Write-Host '==> Phase 2: bob starts a fresh container with a different user isolation key ...'
+    Start-Container -UserKey 'bob' -ChatKey 'bob-chat-1' -ContainerName 'hosted-memory-smoke-bob'
+    $b1 = Invoke-Agent -Prompt 'Hello, what trip am I planning?'
+    $bobText = ($b1.output | ForEach-Object { $_.content | ForEach-Object { $_.text } }) -join ' '
+    Assert-NotContains $bobText 'Patagonia' 'bob isolation: no leak of alice memories'
+
+    Write-Host ''
+    Write-Host '==> All smoke assertions passed.'
+}
+finally {
+    docker rm -f hosted-memory-smoke-alice 2>$null | Out-Null
+    docker rm -f hosted-memory-smoke-bob 2>$null | Out-Null
+}

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Observability/.dockerignore

@@ -1,7 +1,6 @@
 .env
 bin/
 obj/
-out/
 .vs/
 .vscode/
 *.user

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Observability/HostedObservability.csproj

@@ -20,6 +20,7 @@
   <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

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

@@ -10,6 +10,7 @@ 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;
 using Microsoft.Extensions.AI;
@@ -60,49 +61,14 @@ AIAgent agent = new AIProjectClient(new Uri(endpoint), credential)
 
 var builder = WebApplication.CreateBuilder(args);
 builder.Services.AddFoundryResponses(agent);
+builder.Services.AddDevTemporaryLocalContributorSetup(); // Local Docker debugging only - must not be used in production.
 
 var app = builder.Build();
 app.MapFoundryResponses();
 
-if (app.Environment.IsDevelopment())
-{
-    app.MapFoundryResponses("openai/v1");
-}
+// 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();
-
-/// <summary>
-/// A <see cref="TokenCredential"/> for local Docker debugging only.
-/// Reads a pre-fetched bearer token from the <c>AZURE_BEARER_TOKEN</c> environment variable
-/// once at startup. This should NOT be used in production.
-///
-/// Generate a token on your host and pass it to the container:
-///   export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
-///   docker run -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN ...
-/// </summary>
-internal sealed class DevTemporaryTokenCredential : TokenCredential
-{
-    private const string EnvironmentVariable = "AZURE_BEARER_TOKEN";
-    private readonly string? _token;
-
-    public DevTemporaryTokenCredential()
-    {
-        this._token = Environment.GetEnvironmentVariable(EnvironmentVariable);
-    }
-
-    public override AccessToken GetToken(TokenRequestContext requestContext, CancellationToken cancellationToken)
-        => this.GetAccessToken();
-
-    public override ValueTask<AccessToken> GetTokenAsync(TokenRequestContext requestContext, CancellationToken cancellationToken)
-        => new(this.GetAccessToken());
-
-    private AccessToken GetAccessToken()
-    {
-        if (string.IsNullOrEmpty(this._token) || this._token == "DefaultAzureCredential")
-        {
-            throw new CredentialUnavailableException($"{EnvironmentVariable} environment variable is not set.");
-        }
-
-        return new AccessToken(this._token, DateTimeOffset.UtcNow.AddHours(1));
-    }
-}

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

@@ -20,6 +20,7 @@
   <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" />
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
   </ItemGroup>
 

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

@@ -8,6 +8,7 @@ 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;
 using Microsoft.Extensions.AI;
@@ -47,14 +48,15 @@ AIAgent agent = new AIProjectClient(new Uri(endpoint), credential)
 // Host the agent as a Foundry Hosted Agent using the Responses API.
 var builder = WebApplication.CreateBuilder(args);
 builder.Services.AddFoundryResponses(agent);
+builder.Services.AddDevTemporaryLocalContributorSetup(); // Local Docker debugging only - must not be used in production.
 
 var app = builder.Build();
 app.MapFoundryResponses();
 
-if (app.Environment.IsDevelopment())
-{
-    app.MapFoundryResponses("openai/v1");
-}
+// 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();
 
@@ -97,34 +99,3 @@ static Task<IEnumerable<TextSearchProvider.TextSearchResult>> MockSearchAsync(st
 
     return Task.FromResult<IEnumerable<TextSearchProvider.TextSearchResult>>(results);
 }
-
-/// <summary>
-/// A <see cref="TokenCredential"/> for local Docker debugging only.
-/// Reads a pre-fetched bearer token from the <c>AZURE_BEARER_TOKEN</c> environment variable.
-/// This should NOT be used in production — tokens expire (~1 hour) and cannot be refreshed.
-///
-/// Generate a token on your host and pass it to the container:
-///   export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
-///   docker run -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN ...
-/// </summary>
-internal sealed class DevTemporaryTokenCredential : TokenCredential
-{
-    private const string EnvironmentVariable = "AZURE_BEARER_TOKEN";
-
-    public override AccessToken GetToken(TokenRequestContext requestContext, CancellationToken cancellationToken)
-        => GetAccessToken();
-
-    public override ValueTask<AccessToken> GetTokenAsync(TokenRequestContext requestContext, CancellationToken cancellationToken)
-        => new(GetAccessToken());
-
-    private static AccessToken GetAccessToken()
-    {
-        var token = Environment.GetEnvironmentVariable(EnvironmentVariable);
-        if (string.IsNullOrEmpty(token) || token == "DefaultAzureCredential")
-        {
-            throw new CredentialUnavailableException($"{EnvironmentVariable} environment variable is not set.");
-        }
-
-        return new AccessToken(token, DateTimeOffset.UtcNow.AddHours(1));
-    }
-}

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox/HostedToolbox.csproj

@@ -20,6 +20,7 @@
   <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

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

@@ -21,6 +21,7 @@ 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;
 
@@ -57,6 +58,7 @@ var builder = WebApplication.CreateBuilder(args);
 
 // Register the agent and response handler
 builder.Services.AddFoundryResponses(agent);
+builder.Services.AddDevTemporaryLocalContributorSetup(); // Local Docker debugging only - must not be used in production.
 
 // Register Foundry Toolbox: connects to the MCP proxy at startup and makes tools available.
 // The toolset name must match a toolset registered in your Foundry project.
@@ -67,47 +69,11 @@ builder.Services.AddFoundryToolboxes(toolboxName);
 var app = builder.Build();
 app.MapFoundryResponses();
 
-if (app.Environment.IsDevelopment())
-{
-    app.MapFoundryResponses("openai/v1");
-}
+// 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();
 
 // ── DevTemporaryTokenCredential ───────────────────────────────────────────────
-
-/// <summary>
-/// A <see cref="TokenCredential"/> for local Docker debugging only.
-/// Reads a pre-fetched bearer token from the <c>AZURE_BEARER_TOKEN</c> environment variable
-/// once at startup. This should NOT be used in production.
-///
-/// Generate a token on your host and pass it to the container:
-///   export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
-///   docker run -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN ...
-/// </summary>
-internal sealed class DevTemporaryTokenCredential : TokenCredential
-{
-    private const string EnvironmentVariable = "AZURE_BEARER_TOKEN";
-    private readonly string? _token;
-
-    public DevTemporaryTokenCredential()
-    {
-        this._token = Environment.GetEnvironmentVariable(EnvironmentVariable);
-    }
-
-    public override AccessToken GetToken(TokenRequestContext requestContext, CancellationToken cancellationToken)
-        => this.GetAccessToken();
-
-    public override ValueTask<AccessToken> GetTokenAsync(TokenRequestContext requestContext, CancellationToken cancellationToken)
-        => new(this.GetAccessToken());
-
-    private AccessToken GetAccessToken()
-    {
-        if (string.IsNullOrEmpty(this._token) || this._token == "DefaultAzureCredential")
-        {
-            throw new CredentialUnavailableException($"{EnvironmentVariable} environment variable is not set.");
-        }
-
-        return new AccessToken(this._token, DateTimeOffset.MaxValue);
-    }
-}

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Handoff/HostedWorkflowHandoff.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk.Web">
+<Project Sdk="Microsoft.NET.Sdk.Web">
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
@@ -24,6 +24,7 @@
   <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" />
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Hosting\Microsoft.Agents.AI.Hosting.csproj" />
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />

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

@@ -17,9 +17,9 @@
 
 using System.ComponentModel;
 using Azure.AI.OpenAI;
-using Azure.Core;
 using Azure.Identity;
 using DotNetEnv;
+using Hosted_Shared_Contributor_Setup;
 using Microsoft.Agents.AI;
 using Microsoft.Agents.AI.Foundry.Hosting;
 using Microsoft.Agents.AI.Hosting;
@@ -192,30 +192,3 @@ static string GetWeather(
     var condition = conditions[rng.Next(conditions.Length)];
     return $"Weather in {location}: {temp}C, {condition}. Humidity: {rng.Next(30, 90)}%. Wind: {rng.Next(5, 30)} km/h.";
 }
-
-internal sealed class DevTemporaryTokenCredential : TokenCredential
-{
-    private const string EnvironmentVariable = "AZURE_BEARER_TOKEN";
-    private readonly string? _token;
-
-    public DevTemporaryTokenCredential()
-    {
-        this._token = Environment.GetEnvironmentVariable(EnvironmentVariable);
-    }
-
-    public override AccessToken GetToken(TokenRequestContext requestContext, CancellationToken cancellationToken)
-        => this.GetAccessToken();
-
-    public override ValueTask<AccessToken> GetTokenAsync(TokenRequestContext requestContext, CancellationToken cancellationToken)
-        => new(this.GetAccessToken());
-
-    private AccessToken GetAccessToken()
-    {
-        if (string.IsNullOrEmpty(this._token) || this._token == "DefaultAzureCredential")
-        {
-            throw new CredentialUnavailableException($"{EnvironmentVariable} environment variable is not set.");
-        }
-
-        return new AccessToken(this._token, DateTimeOffset.UtcNow.AddHours(1));
-    }
-}

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Simple/HostedWorkflowSimple.csproj

@@ -20,6 +20,7 @@
   <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" />
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
   </ItemGroup>

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

@@ -9,6 +9,7 @@ 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;
 using Microsoft.Agents.AI.Workflows;
@@ -49,49 +50,14 @@ AIAgent agent = new WorkflowBuilder(frenchAgent)
 // Host the workflow agent as a Foundry Hosted Agent using the Responses API.
 var builder = WebApplication.CreateBuilder(args);
 builder.Services.AddFoundryResponses(agent);
+builder.Services.AddDevTemporaryLocalContributorSetup(); // Local Docker debugging only - must not be used in production.
 
 var app = builder.Build();
 app.MapFoundryResponses();
 
-if (app.Environment.IsDevelopment())
-{
-    app.MapFoundryResponses("openai/v1");
-}
+// 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();
-
-/// <summary>
-/// A <see cref="TokenCredential"/> for local Docker debugging only.
-/// Reads a pre-fetched bearer token from the <c>AZURE_BEARER_TOKEN</c> environment variable
-/// once at startup. This should NOT be used in production.
-///
-/// Generate a token on your host and pass it to the container:
-///   export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
-///   docker run -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN ...
-/// </summary>
-internal sealed class DevTemporaryTokenCredential : TokenCredential
-{
-    private const string EnvironmentVariable = "AZURE_BEARER_TOKEN";
-    private readonly string? _token;
-
-    public DevTemporaryTokenCredential()
-    {
-        this._token = Environment.GetEnvironmentVariable(EnvironmentVariable);
-    }
-
-    public override AccessToken GetToken(TokenRequestContext requestContext, CancellationToken cancellationToken)
-        => this.GetAccessToken();
-
-    public override ValueTask<AccessToken> GetTokenAsync(TokenRequestContext requestContext, CancellationToken cancellationToken)
-        => new(this.GetAccessToken());
-
-    private AccessToken GetAccessToken()
-    {
-        if (string.IsNullOrEmpty(this._token) || this._token == "DefaultAzureCredential")
-        {
-            throw new CredentialUnavailableException($"{EnvironmentVariable} environment variable is not set.");
-        }
-
-        return new AccessToken(this._token, DateTimeOffset.UtcNow.AddHours(1));
-    }
-}

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted_Shared_Contributor_Setup/DevTemporaryLocalSessionIsolationKeyProvider.cs

@@ -0,0 +1,72 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.AgentServer.Responses;
+using Azure.AI.AgentServer.Responses.Models;
+using Microsoft.Agents.AI.Foundry.Hosting;
+
+namespace Hosted_Shared_Contributor_Setup;
+
+/// <summary>
+/// A <see cref="HostedSessionIsolationKeyProvider"/> for local Docker debugging only.
+///
+/// When the Foundry platform's <c>x-agent-user-isolation-key</c> and
+/// <c>x-agent-chat-isolation-key</c> headers are absent (i.e., when the container is running
+/// outside the Foundry platform), the hosting layer rejects every request with a 500 because the
+/// default <see cref="HostedSessionIsolationKeyProvider"/> returns null. This provider supplies
+/// fallback values from the <c>HOSTED_USER_ISOLATION_KEY</c> and <c>HOSTED_CHAT_ISOLATION_KEY</c>
+/// environment variables, defaulting to the constants below when neither is set.
+///
+/// This should NOT be used in production. The Foundry platform sets the isolation keys for every
+/// inbound request and forging them client-side defeats the per-user partitioning. The dev
+/// fallback exists solely so a contributor can <c>docker run</c> the sample on their laptop and
+/// drive a few requests end to end.
+/// </summary>
+public sealed class DevTemporaryLocalSessionIsolationKeyProvider : HostedSessionIsolationKeyProvider
+{
+    /// <summary>
+    /// Environment variable that supplies the user isolation key when the platform header is absent.
+    /// </summary>
+    public const string UserIsolationKeyEnvironmentVariable = "HOSTED_USER_ISOLATION_KEY";
+
+    /// <summary>
+    /// Environment variable that supplies the chat isolation key when the platform header is absent.
+    /// </summary>
+    public const string ChatIsolationKeyEnvironmentVariable = "HOSTED_CHAT_ISOLATION_KEY";
+
+    /// <summary>
+    /// Default user isolation key used when neither the platform header nor the environment variable
+    /// supplies a value. All local requests collapse onto this single bucket unless overridden.
+    /// </summary>
+    public const string DefaultLocalUserIsolationKey = "local-dev-user";
+
+    /// <summary>
+    /// Default chat isolation key used when neither the platform header nor the environment variable
+    /// supplies a value.
+    /// </summary>
+    public const string DefaultLocalChatIsolationKey = "local-dev-chat";
+
+    /// <inheritdoc />
+    public override ValueTask<HostedSessionContext?> GetKeysAsync(
+        ResponseContext context,
+        CreateResponse request,
+        CancellationToken cancellationToken)
+    {
+        var userKey = !string.IsNullOrWhiteSpace(context?.Isolation?.UserIsolationKey)
+            ? context!.Isolation!.UserIsolationKey
+            : Environment.GetEnvironmentVariable(UserIsolationKeyEnvironmentVariable);
+        if (string.IsNullOrWhiteSpace(userKey))
+        {
+            userKey = DefaultLocalUserIsolationKey;
+        }
+
+        var chatKey = !string.IsNullOrWhiteSpace(context?.Isolation?.ChatIsolationKey)
+            ? context!.Isolation!.ChatIsolationKey
+            : Environment.GetEnvironmentVariable(ChatIsolationKeyEnvironmentVariable);
+        if (string.IsNullOrWhiteSpace(chatKey))
+        {
+            chatKey = DefaultLocalChatIsolationKey;
+        }
+
+        return new ValueTask<HostedSessionContext?>(new HostedSessionContext(userKey!, chatKey!));
+    }
+}

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted_Shared_Contributor_Setup/DevTemporaryTokenCredential.cs

@@ -0,0 +1,57 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.Core;
+using Azure.Identity;
+
+namespace Hosted_Shared_Contributor_Setup;
+
+/// <summary>
+/// A <see cref="TokenCredential"/> for local Docker debugging only.
+///
+/// When debugging and testing a hosted agent in a local Docker container, Azure CLI
+/// and other interactive credentials are not available. This credential reads a
+/// pre-fetched bearer token from the <c>AZURE_BEARER_TOKEN</c> environment variable.
+///
+/// This should NOT be used in production. Tokens expire (around one hour) and cannot be refreshed.
+/// In production, the Foundry platform injects a managed identity automatically.
+///
+/// Generate a token on your host and pass it to the container:
+///   export AZURE_BEARER_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
+///   docker run -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN ...
+/// </summary>
+public sealed class DevTemporaryTokenCredential : TokenCredential
+{
+    private const string EnvironmentVariable = "AZURE_BEARER_TOKEN";
+    private readonly string? _token;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DevTemporaryTokenCredential"/> class.
+    /// Reads the bearer token from the <c>AZURE_BEARER_TOKEN</c> environment variable when present.
+    /// </summary>
+    public DevTemporaryTokenCredential()
+    {
+        this._token = Environment.GetEnvironmentVariable(EnvironmentVariable);
+    }
+
+    /// <inheritdoc />
+    public override AccessToken GetToken(TokenRequestContext requestContext, CancellationToken cancellationToken)
+    {
+        return this.GetAccessToken();
+    }
+
+    /// <inheritdoc />
+    public override ValueTask<AccessToken> GetTokenAsync(TokenRequestContext requestContext, CancellationToken cancellationToken)
+    {
+        return new ValueTask<AccessToken>(this.GetAccessToken());
+    }
+
+    private AccessToken GetAccessToken()
+    {
+        if (string.IsNullOrEmpty(this._token) || this._token == "DefaultAzureCredential")
+        {
+            throw new CredentialUnavailableException($"{EnvironmentVariable} environment variable is not set.");
+        }
+
+        return new AccessToken(this._token, DateTimeOffset.UtcNow.AddHours(1));
+    }
+}

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted_Shared_Contributor_Setup/HostedContributorRouteExtensions.cs

@@ -0,0 +1,41 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Foundry.Hosting;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.Extensions.Hosting;
+
+namespace Hosted_Shared_Contributor_Setup;
+
+/// <summary>
+/// Routing helpers for contributor samples that host a Foundry-managed agent locally.
+/// </summary>
+public static class HostedContributorRouteExtensions
+{
+    /// <summary>
+    /// In Development, maps the per-agent OpenAI route shape that live Foundry uses
+    /// (<c>/api/projects/{project}/agents/{agentName}/endpoint/protocols/openai/responses</c>) on top
+    /// of the default <c>MapFoundryResponses()</c> so a local REPL client can reach the agent through
+    /// <c>AIProjectClient.AsAIAgent(Uri agentEndpoint)</c>, which is the only supported consumption path
+    /// for Foundry-hosted agents.
+    ///
+    /// <para>
+    /// The <c>{project}</c> and <c>{agentName}</c> segments are route-parameter wildcards on the server
+    /// side; the handler does not consume them, so any value sent by the client is accepted.
+    /// </para>
+    ///
+    /// <para><b>For local contributor debugging only and should not be used in production.</b></para>
+    /// </summary>
+    /// <param name="app">The <see cref="WebApplication"/> to attach the routes to.</param>
+    /// <returns>The same <see cref="WebApplication"/> for chaining.</returns>
+    public static WebApplication MapDevTemporaryLocalAgentEndpoint(this WebApplication app)
+    {
+        ArgumentNullException.ThrowIfNull(app);
+
+        if (app.Environment.IsDevelopment())
+        {
+            app.MapFoundryResponses("api/projects/{project}/agents/{agentName}/endpoint/protocols/openai");
+        }
+
+        return app;
+    }
+}

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted_Shared_Contributor_Setup/HostedContributorSetupExtensions.cs

@@ -0,0 +1,33 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Foundry.Hosting;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace Hosted_Shared_Contributor_Setup;
+
+/// <summary>
+/// Registration helpers for the developer-only utilities shipped in this sample-shared project.
+/// </summary>
+public static class HostedContributorSetupExtensions
+{
+    /// <summary>
+    /// Registers developer-only services that allow a hosted Foundry agent to run outside the
+    /// Foundry platform (e.g., inside a Docker container during contributor debugging).
+    ///
+    /// <para><b>For local Docker debugging only and should not be used in production.</b></para>
+    ///
+    /// Currently this method registers a <see cref="DevTemporaryLocalSessionIsolationKeyProvider"/>
+    /// so that requests succeed when the platform's <c>x-agent-user-isolation-key</c> and
+    /// <c>x-agent-chat-isolation-key</c> headers are absent. In production those headers are
+    /// always present and the default platform isolation key provider (registered automatically by
+    /// the hosting layer) is used instead.
+    /// </summary>
+    /// <param name="services">The service collection to register the developer-only services into.</param>
+    /// <returns>The same <see cref="IServiceCollection"/> for chaining.</returns>
+    public static IServiceCollection AddDevTemporaryLocalContributorSetup(this IServiceCollection services)
+    {
+        ArgumentNullException.ThrowIfNull(services);
+        services.AddSingleton<HostedSessionIsolationKeyProvider, DevTemporaryLocalSessionIsolationKeyProvider>();
+        return services;
+    }
+}

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted_Shared_Contributor_Setup/Hosted_Shared_Contributor_Setup.csproj

@@ -0,0 +1,27 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <CentralPackageTransitivePinningEnabled>false</CentralPackageTransitivePinningEnabled>
+    <RootNamespace>Hosted_Shared_Contributor_Setup</RootNamespace>
+    <AssemblyName>Hosted_Shared_Contributor_Setup</AssemblyName>
+    <NoWarn>$(NoWarn);</NoWarn>
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <FrameworkReference Include="Microsoft.AspNetCore.App" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry.Hosting\Microsoft.Agents.AI.Foundry.Hosting.csproj" />
+  </ItemGroup>
+
+</Project>

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

@@ -1,7 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 using System.ClientModel.Primitives;
-using Azure.AI.Extensions.OpenAI;
 using Azure.AI.Projects;
 using Azure.Identity;
 using DotNetEnv;
@@ -11,28 +10,34 @@ using Microsoft.Agents.AI.Foundry;
 // Load .env file if present (for local development)
 Env.TraversePath().Load();
 
-Uri agentEndpoint = new(Environment.GetEnvironmentVariable("AGENT_ENDPOINT")
-    ?? "http://localhost:8088");
+// AZURE_AI_PROJECT_ENDPOINT is the Foundry project endpoint. Shape:
+//   https://<host>/api/projects/<project>
+Uri projectEndpoint = new(Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set."));
 
-var agentName = Environment.GetEnvironmentVariable("AGENT_NAME")
-    ?? throw new InvalidOperationException("AGENT_NAME is not set.");
+// 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.");
 
-// ── Create an agent-framework agent backed by the remote Hosted-Files agent ──
+// Derive the per-agent OpenAI endpoint that hosted Foundry agents require.
+Uri agentEndpoint = new($"{projectEndpoint}/agents/{agentName}/endpoint/protocols/openai");
+
+// ── Create an agent-framework agent backed by the remote agent endpoint ──────
 
 var options = new AIProjectClientOptions();
 
-if (agentEndpoint.Scheme == "http")
+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(agentEndpoint, new AzureCliCredential(), options);
-FoundryAgent agent = aiProjectClient.AsAIAgent(new AgentReference(agentName));
+var aiProjectClient = new AIProjectClient(projectEndpoint, new AzureCliCredential(), options);
+FoundryAgent agent = aiProjectClient.AsAIAgent(agentEndpoint);
 
 AgentSession session = await agent.CreateSessionAsync();
 
@@ -41,10 +46,10 @@ AgentSession session = await agent.CreateSessionAsync();
 Console.ForegroundColor = ConsoleColor.Cyan;
 Console.WriteLine($"""
     ══════════════════════════════════════════════════════════
-    Session Files Client                                    
+    Session Files Client
     Connected to: {agentEndpoint}
     Try: "Give me the total revenue in the contoso file."
-    Type a message or 'quit' to exit                        
+    Type a message or 'quit' to exit
     ══════════════════════════════════════════════════════════
     """);
 Console.ResetColor();

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

@@ -13,18 +13,18 @@ The agent's container-side `ListFiles` and `ReadFile` tools surface the bundled
 ## Configuration
 
 ```env
-AGENT_ENDPOINT=http://localhost:8088
-AGENT_NAME=hosted-files
+AZURE_AI_PROJECT_ENDPOINT=https://<host>/api/projects/<project>
+AZURE_AI_AGENT_NAME=hosted-files
 ```
 
-`AGENT_ENDPOINT` defaults to `http://localhost:8088`. Override with the deployed agent endpoint when chatting against Foundry.
+Both are required. `AZURE_AI_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 from these.
 
 ## Run
 
 ```bash
 cd dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SessionFilesClient
-$env:AGENT_ENDPOINT = "http://localhost:8088"
-$env:AGENT_NAME = "hosted-files"
+$env:AZURE_AI_PROJECT_ENDPOINT = "http://localhost:8088/api/projects/local"
+$env:AZURE_AI_AGENT_NAME = "hosted-files"
 dotnet run
 ```
 

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

@@ -1,7 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 using System.ClientModel.Primitives;
-using Azure.AI.Extensions.OpenAI;
 using Azure.AI.Projects;
 using Azure.Identity;
 using DotNetEnv;
@@ -11,28 +10,34 @@ using Microsoft.Agents.AI.Foundry;
 // Load .env file if present (for local development)
 Env.TraversePath().Load();
 
-Uri agentEndpoint = new(Environment.GetEnvironmentVariable("AGENT_ENDPOINT")
-    ?? "http://localhost:8088");
+// AZURE_AI_PROJECT_ENDPOINT is the Foundry project endpoint. Shape:
+//   https://<host>/api/projects/<project>
+Uri projectEndpoint = new(Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set."));
 
-var agentName = Environment.GetEnvironmentVariable("AGENT_NAME")
-    ?? throw new InvalidOperationException("AGENT_NAME is not set.");
+// 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");
 
 // ── Create an agent-framework agent backed by the remote agent endpoint ──────
 
 var options = new AIProjectClientOptions();
 
-if (agentEndpoint.Scheme == "http")
+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(agentEndpoint, new AzureCliCredential(), options);
-FoundryAgent agent = aiProjectClient.AsAIAgent(new AgentReference(agentName));
+var aiProjectClient = new AIProjectClient(projectEndpoint, new AzureCliCredential(), options);
+FoundryAgent agent = aiProjectClient.AsAIAgent(agentEndpoint);
 
 AgentSession session = await agent.CreateSessionAsync();
 
@@ -41,9 +46,9 @@ AgentSession session = await agent.CreateSessionAsync();
 Console.ForegroundColor = ConsoleColor.Cyan;
 Console.WriteLine($"""
     ══════════════════════════════════════════════════════════
-    Simple Agent Sample                                     
+    Simple Agent Sample
     Connected to: {agentEndpoint}
-    Type a message or 'quit' to exit                        
+    Type a message or 'quit' to exit
     ══════════════════════════════════════════════════════════
     """);
 Console.ResetColor();

dotnet/src/Microsoft.Agents.AI.AGUI/Shared/ChatResponseUpdateAGUIExtensions.cs

@@ -458,8 +458,9 @@ internal static class ChatResponseUpdateAGUIExtensions
             // This ensures all AGUI events have a valid messageId regardless of agent type.
             if (string.IsNullOrWhiteSpace(chatResponse.MessageId))
             {
-                streamingMessageId ??= Guid.NewGuid().ToString("N");
-                chatResponse.MessageId = streamingMessageId;
+                chatResponse.MessageId = ContainsToolResult(chatResponse)
+                    ? Guid.NewGuid().ToString("N")
+                    : (streamingMessageId ??= Guid.NewGuid().ToString("N"));
             }
 
             if (chatResponse is { Contents.Count: > 0 } &&
@@ -725,4 +726,17 @@ internal static class ChatResponseUpdateAGUIExtensions
             _ => JsonSerializer.Serialize(functionResultContent.Result, options.GetTypeInfo(functionResultContent.Result.GetType())),
         };
     }
+
+    private static bool ContainsToolResult(ChatResponseUpdate chatResponse)
+    {
+        foreach (AIContent content in chatResponse.Contents)
+        {
+            if (content is FunctionResultContent)
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
 }

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

@@ -26,6 +26,12 @@ public class AgentFrameworkResponseHandler : ResponseHandler
     private readonly ILogger<AgentFrameworkResponseHandler> _logger;
     private readonly FoundryToolboxService? _toolboxService;
 
+    /// <summary>
+    /// Cached fallback used when no <see cref="HostedSessionIsolationKeyProvider"/> is registered in DI.
+    /// Avoids a per-request allocation on the request hot path.
+    /// </summary>
+    private static readonly HostedSessionIsolationKeyProvider s_defaultIsolationKeyProvider = new PlatformHostedSessionIsolationKeyProvider();
+
     /// <summary>
     /// Initializes a new instance of the <see cref="AgentFrameworkResponseHandler"/> class
     /// that resolves agents from keyed DI services.
@@ -67,6 +73,42 @@ public class AgentFrameworkResponseHandler : ResponseHandler
                 ? await chatClientAgent.CreateSessionAsync(cancellationToken).ConfigureAwait(false)
                 : await agent.CreateSessionAsync(cancellationToken).ConfigureAwait(false);
 
+        // 2.5. Resolve and apply the per-request hosted session identity context.
+        // Fresh sessions are tagged once. Resumed sessions are validated against the live request
+        // to detect cross-user session leaks and in-process tampering of the persisted identity.
+        var isolationKeyProvider = this._serviceProvider.GetService<HostedSessionIsolationKeyProvider>()
+            ?? s_defaultIsolationKeyProvider;
+        var resolvedHostedContext = await isolationKeyProvider.GetKeysAsync(context, request, cancellationToken).ConfigureAwait(false);
+        if (resolvedHostedContext is null)
+        {
+            throw new InvalidOperationException(
+                $"The registered {nameof(HostedSessionIsolationKeyProvider)} returned null for the current request. " +
+                "Ensure the Foundry platform is providing the x-agent-user-isolation-key and x-agent-chat-isolation-key headers, " +
+                "or register a custom provider that supplies fallback values for local development.");
+        }
+
+        if (session is not null)
+        {
+            var existingHostedContext = session.GetHostedContext();
+            if (existingHostedContext is null)
+            {
+                // Fresh path: the session has no hosted context yet (either freshly created here,
+                // or freshly loaded for a conversation_id that the platform supplied without any
+                // prior hosted-agent request having stamped a context). Stamp it now.
+                session.SetHostedContext(resolvedHostedContext);
+            }
+            else if (!string.Equals(existingHostedContext.UserId, resolvedHostedContext.UserId, StringComparison.Ordinal)
+                || !string.Equals(existingHostedContext.ChatId, resolvedHostedContext.ChatId, StringComparison.Ordinal))
+            {
+                // Resume path: the persisted identity must match the live request. A mismatch
+                // signals either a cross-user session leak or in-process tampering of the
+                // persisted identity. Reject the request hard.
+                throw new ResponsesApiException(
+                    new Error("hosted_session_identity_mismatch", "Hosted session identity context mismatch"),
+                    403);
+            }
+        }
+
         // 3. Create the SDK event stream builder
         var stream = new ResponseEventStream(context, request);
 

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

@@ -0,0 +1,65 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI.Foundry.Hosting;
+
+/// <summary>
+/// Built-in <see cref="FoundryMemoryProvider"/> <c>stateInitializer</c> factories that derive the
+/// <see cref="FoundryMemoryProviderScope"/> from the per-session <see cref="HostedSessionContext"/>
+/// applied by the Foundry hosting layer.
+/// </summary>
+/// <remarks>
+/// Pass the result of any of these helpers as the <c>stateInitializer</c> argument when constructing
+/// <see cref="FoundryMemoryProvider"/>:
+/// <code>
+/// new FoundryMemoryProvider(client, "my-store",
+///     stateInitializer: HostedFoundryMemoryProviderScopes.PerUser());
+/// </code>
+/// All helpers throw <see cref="InvalidOperationException"/> when
+/// <see cref="HostedSessionContextExtensions.GetHostedContext"/> returns <see langword="null"/>.
+/// That happens when the agent runs outside the Foundry hosting layer (e.g., a console app); in
+/// that case write a custom <c>stateInitializer</c> instead of using these helpers.
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
+public static class HostedFoundryMemoryProviderScopes
+{
+    /// <summary>
+    /// Returns a <c>stateInitializer</c> that scopes memories per end user, using
+    /// <see cref="HostedSessionContext.UserId"/> as the partition key.
+    /// </summary>
+    /// <returns>A delegate suitable for the <c>stateInitializer</c> argument of <see cref="FoundryMemoryProvider"/>.</returns>
+    public static Func<AgentSession?, FoundryMemoryProvider.State> PerUser() =>
+        session => new FoundryMemoryProvider.State(new FoundryMemoryProviderScope(GetRequiredHostedContext(session).UserId));
+
+    /// <summary>
+    /// Returns a <c>stateInitializer</c> that scopes memories per conversation, using
+    /// <see cref="HostedSessionContext.ChatId"/> as the partition key. Use this when memories should
+    /// be visible to every participant in a shared conversation (for example, a Teams group chat).
+    /// </summary>
+    /// <returns>A delegate suitable for the <c>stateInitializer</c> argument of <see cref="FoundryMemoryProvider"/>.</returns>
+    public static Func<AgentSession?, FoundryMemoryProvider.State> PerChat() =>
+        session => new FoundryMemoryProvider.State(new FoundryMemoryProviderScope(GetRequiredHostedContext(session).ChatId));
+
+    /// <summary>
+    /// Returns a <c>stateInitializer</c> that scopes memories per (user, chat) pair, using
+    /// <c>"{UserId}:{ChatId}"</c> as the partition key. Use this when memories should be visible
+    /// only to the same user within the same conversation.
+    /// </summary>
+    /// <returns>A delegate suitable for the <c>stateInitializer</c> argument of <see cref="FoundryMemoryProvider"/>.</returns>
+    public static Func<AgentSession?, FoundryMemoryProvider.State> PerUserAndChat() =>
+        session =>
+        {
+            var ctx = GetRequiredHostedContext(session);
+            return new FoundryMemoryProvider.State(new FoundryMemoryProviderScope($"{ctx.UserId}:{ctx.ChatId}"));
+        };
+
+    private static HostedSessionContext GetRequiredHostedContext(AgentSession? session) =>
+        session?.GetHostedContext()
+            ?? throw new InvalidOperationException(
+                $"{nameof(HostedSessionContext)} was not provided by the hosting layer. " +
+                $"The {nameof(HostedFoundryMemoryProviderScopes)} helpers require the agent to be hosted via the Foundry hosting layer. " +
+                "If running outside a hosted Foundry container, supply a custom stateInitializer to FoundryMemoryProvider instead.");
+}

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

@@ -0,0 +1,88 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+using Azure.AI.Projects;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI.Foundry.Hosting;
+
+/// <summary>
+/// Dependency-injection helpers that register a <see cref="FoundryMemoryProvider"/> wired with a
+/// <see cref="HostedFoundryMemoryProviderScopes"/> strategy.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
+public static class HostedFoundryMemoryProviderServiceCollectionExtensions
+{
+    /// <summary>
+    /// Registers a singleton <see cref="FoundryMemoryProvider"/> wired to the supplied
+    /// <see cref="AIProjectClient"/> and the supplied <paramref name="stateInitializer"/>.
+    /// </summary>
+    /// <param name="services">The service collection.</param>
+    /// <param name="client">The <see cref="AIProjectClient"/> used to talk to Foundry Memory.</param>
+    /// <param name="memoryStoreName">The name of the memory store in Microsoft Foundry.</param>
+    /// <param name="stateInitializer">
+    /// Strategy that selects the per-session <see cref="FoundryMemoryProviderScope"/>. When
+    /// <see langword="null"/>, the extension uses <see cref="HostedFoundryMemoryProviderScopes.PerUser"/>.
+    /// Pass any other helper (or a custom delegate) to override.
+    /// </param>
+    /// <param name="options">Optional <see cref="FoundryMemoryProviderOptions"/>.</param>
+    /// <returns>The same <see cref="IServiceCollection"/> for chaining.</returns>
+    public static IServiceCollection AddHostedFoundryMemoryProvider(
+        this IServiceCollection services,
+        AIProjectClient client,
+        string memoryStoreName,
+        Func<AgentSession?, FoundryMemoryProvider.State>? stateInitializer = null,
+        FoundryMemoryProviderOptions? options = null)
+    {
+        Throw.IfNull(services);
+        Throw.IfNull(client);
+        Throw.IfNullOrWhitespace(memoryStoreName);
+
+        var initializer = stateInitializer ?? HostedFoundryMemoryProviderScopes.PerUser();
+        services.AddSingleton(sp => new FoundryMemoryProvider(
+            client,
+            memoryStoreName,
+            initializer,
+            options,
+            sp.GetService<ILoggerFactory>()));
+        return services;
+    }
+
+    /// <summary>
+    /// Registers a singleton <see cref="FoundryMemoryProvider"/> that resolves its
+    /// <see cref="AIProjectClient"/> from <see cref="IServiceProvider"/> at construction time.
+    /// Use this overload when an <see cref="AIProjectClient"/> is already registered with the
+    /// service collection.
+    /// </summary>
+    /// <param name="services">The service collection.</param>
+    /// <param name="memoryStoreName">The name of the memory store in Microsoft Foundry.</param>
+    /// <param name="stateInitializer">
+    /// Strategy that selects the per-session <see cref="FoundryMemoryProviderScope"/>. When
+    /// <see langword="null"/>, the extension uses <see cref="HostedFoundryMemoryProviderScopes.PerUser"/>.
+    /// Pass any other helper (or a custom delegate) to override.
+    /// </param>
+    /// <param name="options">Optional <see cref="FoundryMemoryProviderOptions"/>.</param>
+    /// <returns>The same <see cref="IServiceCollection"/> for chaining.</returns>
+    public static IServiceCollection AddHostedFoundryMemoryProvider(
+        this IServiceCollection services,
+        string memoryStoreName,
+        Func<AgentSession?, FoundryMemoryProvider.State>? stateInitializer = null,
+        FoundryMemoryProviderOptions? options = null)
+    {
+        Throw.IfNull(services);
+        Throw.IfNullOrWhitespace(memoryStoreName);
+
+        var initializer = stateInitializer ?? HostedFoundryMemoryProviderScopes.PerUser();
+        services.AddSingleton(sp => new FoundryMemoryProvider(
+            sp.GetRequiredService<AIProjectClient>(),
+            memoryStoreName,
+            initializer,
+            options,
+            sp.GetService<ILoggerFactory>()));
+        return services;
+    }
+}

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

@@ -0,0 +1,61 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI.Foundry.Hosting;
+
+/// <summary>
+/// Captures the per-session identity values produced by a <see cref="HostedSessionIsolationKeyProvider"/>
+/// when a Foundry hosted agent processes a request.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The <see cref="UserId"/> partitions data that belongs to the individual who initiated the request
+/// (e.g., personal memory, per-user preferences). The <see cref="ChatId"/> partitions data that belongs
+/// to the conversation (e.g., conversation history, turn state). Both values are opaque strings whose
+/// meaning is determined by the active <see cref="HostedSessionIsolationKeyProvider"/>.
+/// </para>
+/// <para>
+/// Instances are constructed by the hosting layer from the platform-provided
+/// <c>IsolationContext</c> headers and stored on the session via
+/// <see cref="HostedSessionContextExtensions.SetHostedContext"/>. Consumers (typically
+/// <see cref="AIContextProvider"/> implementations) read the values through
+/// <see cref="HostedSessionContextExtensions.GetHostedContext"/>.
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
+public sealed class HostedSessionContext
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="HostedSessionContext"/> class.
+    /// </summary>
+    /// <param name="userId">The opaque user identity for this hosted session. Must not be null or whitespace.</param>
+    /// <param name="chatId">The opaque chat (conversation) identity for this hosted session. Must not be null or whitespace.</param>
+    /// <exception cref="System.ArgumentException">Thrown when <paramref name="userId"/> or <paramref name="chatId"/> is null or whitespace.</exception>
+    public HostedSessionContext(string userId, string chatId)
+    {
+        this.UserId = Throw.IfNullOrWhitespace(userId);
+        this.ChatId = Throw.IfNullOrWhitespace(chatId);
+    }
+
+    /// <summary>
+    /// Gets the opaque user identity for this hosted session.
+    /// </summary>
+    /// <remarks>
+    /// Stable for a given user across sessions. In production this is sourced from the
+    /// <c>x-agent-user-isolation-key</c> platform header.
+    /// </remarks>
+    public string UserId { get; }
+
+    /// <summary>
+    /// Gets the opaque chat (conversation) identity for this hosted session.
+    /// </summary>
+    /// <remarks>
+    /// In a 1:1 user-to-agent chat this typically equals <see cref="UserId"/>. In shared-surface
+    /// scenarios (e.g., a Teams group chat) it represents the common partition all participants
+    /// write to. In production this is sourced from the <c>x-agent-chat-isolation-key</c> platform header.
+    /// </remarks>
+    public string ChatId { get; }
+}

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

@@ -0,0 +1,81 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI.Foundry.Hosting;
+
+/// <summary>
+/// Extension methods for reading and writing the <see cref="HostedSessionContext"/> associated
+/// with an <see cref="AgentSession"/> in a Foundry hosted agent.
+/// </summary>
+/// <remarks>
+/// The hosted session context is written exactly once by the hosting layer when a session is created,
+/// and is validated against the live request on every subsequent invocation. The <see cref="SetHostedContext"/>
+/// method is intentionally <see langword="internal"/> so that only the hosting layer can establish the
+/// identity values; consumers (such as <see cref="AIContextProvider"/> implementations) read the values
+/// through the public <see cref="GetHostedContext"/> accessor.
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
+public static class HostedSessionContextExtensions
+{
+    /// <summary>
+    /// The well-known <see cref="AgentSessionStateBag"/> key used to store the
+    /// <see cref="HostedSessionContext"/> on a session.
+    /// </summary>
+    /// <remarks>
+    /// Exposed as a constant so consumers can correlate persisted state across processes.
+    /// External code must not write to this key directly; use <see cref="SetHostedContext"/> from the
+    /// hosting assembly instead.
+    /// </remarks>
+    public const string StateKey = "Microsoft.Agents.AI.Foundry.Hosting.HostedSessionContext";
+
+    /// <summary>
+    /// Gets the <see cref="HostedSessionContext"/> previously written by the hosting layer
+    /// for this session, if any.
+    /// </summary>
+    /// <param name="session">The session to read from.</param>
+    /// <returns>
+    /// The <see cref="HostedSessionContext"/> for the session, or <see langword="null"/> when the
+    /// session was not produced by a hosted agent (or the value has not yet been written).
+    /// </returns>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="session"/> is <see langword="null"/>.</exception>
+    public static HostedSessionContext? GetHostedContext(this AgentSession session)
+    {
+        Throw.IfNull(session);
+
+        return session.StateBag.TryGetValue<HostedSessionContext>(StateKey, out var context, HostedSessionJsonUtilities.DefaultOptions)
+            ? context
+            : null;
+    }
+
+    /// <summary>
+    /// Writes the <see cref="HostedSessionContext"/> for this session.
+    /// </summary>
+    /// <param name="session">The session to write to.</param>
+    /// <param name="context">The hosted session context to associate with <paramref name="session"/>.</param>
+    /// <remarks>
+    /// Internal to the hosting assembly. Consumers must not invoke this method directly; the hosting
+    /// layer is the single writer and uses validation against the live request to detect any tampering
+    /// that does occur via lower-level APIs. Throws when a context has already been written for this
+    /// session to enforce the write-once contract.
+    /// </remarks>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="session"/> or <paramref name="context"/> is <see langword="null"/>.</exception>
+    /// <exception cref="InvalidOperationException">Thrown when this session already carries a <see cref="HostedSessionContext"/>.</exception>
+    internal static void SetHostedContext(this AgentSession session, HostedSessionContext context)
+    {
+        Throw.IfNull(session);
+        Throw.IfNull(context);
+
+        if (session.StateBag.TryGetValue<HostedSessionContext>(StateKey, out _, HostedSessionJsonUtilities.DefaultOptions))
+        {
+            throw new InvalidOperationException(
+                $"A {nameof(HostedSessionContext)} has already been written to this session. " +
+                "The hosted session identity is write-once; resumed sessions must validate against the existing context, not overwrite it.");
+        }
+
+        session.StateBag.SetValue(StateKey, context, HostedSessionJsonUtilities.DefaultOptions);
+    }
+}

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

@@ -0,0 +1,54 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Threading;
+using System.Threading.Tasks;
+using Azure.AI.AgentServer.Responses;
+using Azure.AI.AgentServer.Responses.Models;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI.Foundry.Hosting;
+
+/// <summary>
+/// Resolves the per-request <see cref="HostedSessionContext"/> for a Foundry hosted agent.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Implementations are invoked once per incoming Responses API request. The returned
+/// <see cref="HostedSessionContext"/> establishes the identity of a freshly created session and
+/// is validated against the live request on every subsequent invocation that resumes the same session.
+/// </para>
+/// <para>
+/// The default implementation registered when no custom <see cref="HostedSessionIsolationKeyProvider"/>
+/// is present in DI maps the platform-injected <c>x-agent-user-isolation-key</c> and
+/// <c>x-agent-chat-isolation-key</c> headers via <see cref="ResponseContext.Isolation"/>. Hosting samples and contributor-only environments
+/// can register an alternate implementation in DI to provide values when the platform headers are absent
+/// (e.g., during local Docker debugging).
+/// </para>
+/// <para>
+/// Implementations must return a <see cref="HostedSessionContext"/> whose <see cref="HostedSessionContext.UserId"/>
+/// and <see cref="HostedSessionContext.ChatId"/> are both non-null and non-whitespace. Returning either as null
+/// (or throwing from <see cref="GetKeysAsync"/>) is treated as a configuration error and surfaces as a
+/// 500 from the hosting layer.
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
+public abstract class HostedSessionIsolationKeyProvider
+{
+    /// <summary>
+    /// Resolves the <see cref="HostedSessionContext"/> for the supplied request.
+    /// </summary>
+    /// <param name="context">The per-request <see cref="ResponseContext"/> from the Azure AI Responses Server SDK.</param>
+    /// <param name="request">The <see cref="CreateResponse"/> describing the incoming request.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.</param>
+    /// <returns>
+    /// A <see cref="HostedSessionContext"/> with non-null <see cref="HostedSessionContext.UserId"/> and
+    /// <see cref="HostedSessionContext.ChatId"/>, or <see langword="null"/> when the implementation cannot
+    /// produce identity keys for the current request. A <see langword="null"/> result is treated as a
+    /// configuration error by the hosting layer and surfaces as 500.
+    /// </returns>
+    public abstract ValueTask<HostedSessionContext?> GetKeysAsync(
+        ResponseContext context,
+        CreateResponse request,
+        CancellationToken cancellationToken);
+}

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

@@ -0,0 +1,39 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI.Foundry.Hosting;
+
+/// <summary>
+/// JSON serialization utilities for hosted session identity types.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
+internal static class HostedSessionJsonUtilities
+{
+    /// <summary>
+    /// Default JSON serializer options for hosted session state.
+    /// </summary>
+    public static JsonSerializerOptions DefaultOptions { get; } = new JsonSerializerOptions
+    {
+        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
+        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
+        WriteIndented = false,
+        TypeInfoResolver = HostedSessionJsonContext.Default
+    };
+}
+
+/// <summary>
+/// Source-generated JSON serialization context for hosted session identity types.
+/// </summary>
+[JsonSourceGenerationOptions(
+    JsonSerializerDefaults.General,
+    UseStringEnumConverter = false,
+    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
+    PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
+    WriteIndented = false)]
+[JsonSerializable(typeof(HostedSessionContext))]
+[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
+internal partial class HostedSessionJsonContext : JsonSerializerContext;

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

@@ -0,0 +1,44 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Threading;
+using System.Threading.Tasks;
+using Azure.AI.AgentServer.Responses;
+using Azure.AI.AgentServer.Responses.Models;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI.Foundry.Hosting;
+
+/// <summary>
+/// Default <see cref="HostedSessionIsolationKeyProvider"/> implementation that maps the platform-injected
+/// <c>x-agent-user-isolation-key</c> and <c>x-agent-chat-isolation-key</c> headers from
+/// <see cref="ResponseContext.Isolation"/> into a <see cref="HostedSessionContext"/>.
+/// </summary>
+/// <remarks>
+/// This is the implementation used in production Foundry hosted environments. When running locally
+/// outside the platform, both isolation keys are <see langword="null"/>, which causes
+/// <see cref="GetKeysAsync"/> to return <see langword="null"/>. The hosting layer treats a null
+/// result as a configuration error and surfaces it as a 500 from the request. Local development
+/// should register an alternate <see cref="HostedSessionIsolationKeyProvider"/> implementation
+/// that provides fallback values for the missing headers.
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
+internal sealed class PlatformHostedSessionIsolationKeyProvider : HostedSessionIsolationKeyProvider
+{
+    /// <inheritdoc />
+    public override ValueTask<HostedSessionContext?> GetKeysAsync(
+        ResponseContext context,
+        CreateResponse request,
+        CancellationToken cancellationToken)
+    {
+        var userKey = context?.Isolation?.UserIsolationKey;
+        var chatKey = context?.Isolation?.ChatIsolationKey;
+
+        if (string.IsNullOrWhiteSpace(userKey) || string.IsNullOrWhiteSpace(chatKey))
+        {
+            return new ValueTask<HostedSessionContext?>((HostedSessionContext?)null);
+        }
+
+        return new ValueTask<HostedSessionContext?>(new HostedSessionContext(userKey!, chatKey!));
+    }
+}

dotnet/src/Microsoft.Agents.AI.Foundry/AzureAIProjectChatClientExtensions.cs

@@ -66,6 +66,42 @@ public static partial class AzureAIProjectChatClientExtensions
         return new FoundryAgent(aiProjectClient, innerAgent);
     }
 
+    /// <summary>
+    /// Wraps an existing server side hosted agent as a <see cref="FoundryAgent"/> using the provided
+    /// <see cref="AIProjectClient"/> and an agent-specific endpoint URI.
+    /// </summary>
+    /// <param name="aiProjectClient">The <see cref="AIProjectClient"/> to use for project-level operations. Cannot be <see langword="null"/>.</param>
+    /// <param name="agentEndpoint">
+    /// The agent-specific endpoint URI of shape
+    /// <c>https://&lt;host&gt;/.../projects/&lt;project&gt;/agents/&lt;agentName&gt;/endpoint/protocols/openai</c>.
+    /// The agent name is parsed from this URI and the active agent version is resolved server side
+    /// from the endpoint's administrator-controlled version selector. Cannot be <see langword="null"/>.
+    /// </param>
+    /// <param name="tools">The tools to use when interacting with the agent. This is required when using prompt agent definitions with tools.</param>
+    /// <param name="clientFactory">Provides a way to customize the creation of the underlying <see cref="IChatClient"/> used by the agent.</param>
+    /// <param name="services">An optional <see cref="IServiceProvider"/> to use for resolving services required by the <see cref="AIFunction"/> instances being invoked.</param>
+    /// <returns>A <see cref="FoundryAgent"/> instance that routes calls through the supplied agent endpoint.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="aiProjectClient"/> or <paramref name="agentEndpoint"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentException">Thrown when <paramref name="agentEndpoint"/> does not match the expected agent-endpoint shape.</exception>
+    /// <remarks>
+    /// Agent version selection is controlled by the Foundry administrator through the endpoint's
+    /// version selector and cannot be overridden by the caller. Use the
+    /// <see cref="AsAIAgent(AIProjectClient, AgentReference, IList{AITool}?, Func{IChatClient, IChatClient}?, IServiceProvider?)"/>
+    /// overload when an explicit agent version pin is required.
+    /// </remarks>
+    public static FoundryAgent AsAIAgent(
+        this AIProjectClient aiProjectClient,
+        Uri agentEndpoint,
+        IList<AITool>? tools = null,
+        Func<IChatClient, IChatClient>? clientFactory = null,
+        IServiceProvider? services = null)
+    {
+        Throw.IfNull(aiProjectClient);
+        Throw.IfNull(agentEndpoint);
+
+        return new FoundryAgent(aiProjectClient, agentEndpoint, tools, clientFactory, services);
+    }
+
     /// <summary>
     /// Uses an existing server side agent, wrapped as a <see cref="ChatClientAgent"/> using the provided <see cref="AIProjectClient"/> and <see cref="ProjectsAgentRecord"/>.
     /// </summary>

dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs

@@ -40,27 +40,9 @@ namespace Microsoft.Agents.AI.Foundry;
 public sealed class FoundryAgent : DelegatingAIAgent
 {
     /// <summary>
-    /// Default OAuth scope for the Azure AI resource. Matches the scope used by
-    /// <c>Azure.AI.Extensions.OpenAI</c>'s internal authentication helper so the bearer token is
-    /// accepted by the Foundry control plane.
+    /// The cached <see cref="AIProjectClient"/> supplied to or constructed by the active constructor.
     /// </summary>
-    private const string AzureAiResourceScope = "https://ai.azure.com/.default";
-
-    /// <summary>
-    /// The cached <see cref="AIProjectClient"/> when one was supplied or constructed by the active
-    /// constructor. Null when the agent was constructed via the agent-endpoint constructor, which
-    /// does not build a full <see cref="AIProjectClient"/>.
-    /// </summary>
-    private readonly AIProjectClient? _aiProjectClient;
-
-    /// <summary>
-    /// Project-scoped <see cref="ProjectOpenAIClient"/>. Always non-null. Used for project-level
-    /// operations such as <see cref="CreateConversationSessionAsync(CancellationToken)"/>.
-    /// In agent-endpoint mode this is built directly from the project root derived from the
-    /// supplied agent endpoint; in project-endpoint mode it is the cached client returned by
-    /// <see cref="AIProjectClient"/>.
-    /// </summary>
-    private readonly ProjectOpenAIClient _projectOpenAIClient;
+    private readonly AIProjectClient _aiProjectClient;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="FoundryAgent"/> class using the direct Responses API path.
@@ -94,7 +76,6 @@ public sealed class FoundryAgent : DelegatingAIAgent
             out var aiProjectClient))
     {
         this._aiProjectClient = aiProjectClient;
-        this._projectOpenAIClient = aiProjectClient.GetProjectOpenAIClient();
     }
 
     /// <summary>
@@ -106,11 +87,9 @@ public sealed class FoundryAgent : DelegatingAIAgent
     /// </param>
     /// <param name="credential">The authentication credential.</param>
     /// <param name="clientOptions">
-    /// Optional configuration for the underlying <see cref="ProjectOpenAIClient"/>. When supplied:
+    /// Optional configuration for the underlying <see cref="ProjectResponsesClient"/>. When supplied:
     /// <list type="bullet">
     ///   <item><description>The instance is passed through to the per-agent client; pipeline policies added via <c>AddPolicy(...)</c> on it execute on the per-agent traffic.</description></item>
-    ///   <item><description><c>Endpoint</c> and <see cref="ProjectOpenAIClientOptions.AgentName"/> are owned by this constructor and are overwritten with values derived from <paramref name="agentEndpoint"/>; any caller value is replaced.</description></item>
-    ///   <item><description>For the project-level conversations client a separate fresh options bag is built that copies only <see cref="ClientPipelineOptions.RetryPolicy"/>, <see cref="ClientPipelineOptions.NetworkTimeout"/>, <see cref="ClientPipelineOptions.Transport"/>, and <c>UserAgentApplicationId</c>; pipeline policies added via <c>AddPolicy(...)</c> do <strong>not</strong> propagate to the conversations pipeline.</description></item>
     /// </list>
     /// </param>
     /// <param name="tools">Optional tools to use when interacting with the agent.</param>
@@ -134,9 +113,34 @@ public sealed class FoundryAgent : DelegatingAIAgent
         IList<AITool>? tools = null,
         Func<IChatClient, IChatClient>? clientFactory = null,
         IServiceProvider? services = null)
-        : base(CreateInnerAgentFromAgentEndpoint(agentEndpoint, credential, clientOptions, tools, clientFactory, services))
+        : base(CreateInnerAgentFromAgentEndpoint(agentEndpoint, credential, clientOptions, tools, clientFactory, services, out var aiProjectClient))
     {
-        this._projectOpenAIClient = CreateProjectLevelOpenAIClientFromAgentEndpoint(agentEndpoint, credential, clientOptions);
+        this._aiProjectClient = aiProjectClient;
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FoundryAgent"/> class from an agent-specific
+    /// endpoint while reusing an existing <see cref="AIProjectClient"/>.
+    /// </summary>
+    /// <param name="aiProjectClient">An existing <see cref="AIProjectClient"/> rooted at the same project as <paramref name="agentEndpoint"/>.</param>
+    /// <param name="agentEndpoint">
+    /// The agent-specific endpoint URI. Must be of the shape
+    /// <c>https://&lt;host&gt;/.../projects/&lt;project&gt;/agents/&lt;agentName&gt;/endpoint/protocols/openai</c>.
+    /// </param>
+    /// <param name="tools">Optional tools to use when interacting with the agent.</param>
+    /// <param name="clientFactory">Provides a way to customize the creation of the underlying <see cref="IChatClient"/>.</param>
+    /// <param name="services">Optional service provider for resolving dependencies required by AI functions.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="aiProjectClient"/> or <paramref name="agentEndpoint"/> is null.</exception>
+    /// <exception cref="ArgumentException"><paramref name="agentEndpoint"/> does not match the expected agent-endpoint shape.</exception>
+    internal FoundryAgent(
+        AIProjectClient aiProjectClient,
+        Uri agentEndpoint,
+        IList<AITool>? tools = null,
+        Func<IChatClient, IChatClient>? clientFactory = null,
+        IServiceProvider? services = null)
+        : base(BuildAgentEndpointInnerAgent(aiProjectClient, agentEndpoint, clientOptions: null, tools, clientFactory, services))
+    {
+        this._aiProjectClient = Throw.IfNull(aiProjectClient);
     }
 
     /// <summary>
@@ -146,7 +150,6 @@ public sealed class FoundryAgent : DelegatingAIAgent
         : base(WireClientHeaders(Throw.IfNull(innerAgent)))
     {
         this._aiProjectClient = Throw.IfNull(aiProjectClient);
-        this._projectOpenAIClient = aiProjectClient.GetProjectOpenAIClient();
     }
 
     #region Convenience methods
@@ -179,7 +182,7 @@ public sealed class FoundryAgent : DelegatingAIAgent
     /// <returns>A <see cref="ChatClientAgentSession"/> linked to the newly created server-side conversation.</returns>
     public async Task<ChatClientAgentSession> CreateConversationSessionAsync(CancellationToken cancellationToken = default)
     {
-        var conversationsClient = this._projectOpenAIClient.GetProjectConversationsClient();
+        var conversationsClient = this._aiProjectClient.ProjectOpenAIClient.GetProjectConversationsClient();
 
         var conversation = (await conversationsClient.CreateProjectConversationAsync(options: null, cancellationToken).ConfigureAwait(false)).Value;
 
@@ -201,11 +204,6 @@ public sealed class FoundryAgent : DelegatingAIAgent
             return this._aiProjectClient;
         }
 
-        if (serviceKey is null && serviceType == typeof(ProjectOpenAIClient))
-        {
-            return this._projectOpenAIClient;
-        }
-
         return base.GetService(serviceType, serviceKey);
     }
 
@@ -291,11 +289,10 @@ public sealed class FoundryAgent : DelegatingAIAgent
 
     /// <summary>
     /// Builds the inner <see cref="ChatClientAgent"/> for the agent-endpoint constructor by
-    /// constructing a per-agent <see cref="ProjectOpenAIClient"/> via the
-    /// <c>ProjectOpenAIClient(AuthenticationPolicy, ProjectOpenAIClientOptions)</c>
-    /// constructor with <see cref="ProjectOpenAIClientOptions.AgentName"/> set. This routes the
-    /// outbound URL through the per-agent endpoint shape that the Foundry service expects for
-    /// hosted agents and lets the SDK auto-append the <c>api-version</c> query string.
+    /// constructing a project-scoped <see cref="ProjectOpenAIClient"/> and using
+    /// <see cref="ProjectOpenAIClient.GetProjectResponsesClientForAgentEndpoint(string, string?, ProjectOpenAIClientOptions?)"/>.
+    /// This routes the outbound URL through the per-agent endpoint shape that the Foundry service
+    /// expects for hosted agents and lets the SDK auto-append the <c>api-version</c> query string.
     /// Caller-supplied <paramref name="clientOptions"/> are passed through to the per-agent
     /// client with <c>Endpoint</c> and
     /// <see cref="ProjectOpenAIClientOptions.AgentName"/> overridden by values derived from
@@ -308,22 +305,44 @@ public sealed class FoundryAgent : DelegatingAIAgent
         ProjectOpenAIClientOptions? clientOptions,
         IList<AITool>? tools,
         Func<IChatClient, IChatClient>? clientFactory,
-        IServiceProvider? services)
+        IServiceProvider? services,
+        out AIProjectClient outClient)
     {
         Throw.IfNull(agentEndpoint);
         Throw.IfNull(credential);
 
+        var (_, projectRoot) = ParseAgentEndpoint(agentEndpoint);
+        outClient = CreateProjectClient(projectRoot, credential, CreateProjectClientOptions(clientOptions));
+
+        return BuildAgentEndpointInnerAgent(outClient, agentEndpoint, clientOptions, tools, clientFactory, services);
+    }
+
+    /// <summary>
+    /// Builds the inner <see cref="ChatClientAgent"/> for an agent endpoint against a pre-built
+    /// <see cref="AIProjectClient"/>. The caller is responsible for ensuring the supplied client
+    /// is rooted at the same project as <paramref name="agentEndpoint"/>; the agent name is
+    /// parsed from the endpoint URI and passed to
+    /// <see cref="ProjectOpenAIClient.GetProjectResponsesClientForAgentEndpoint(string, string?, ProjectOpenAIClientOptions?)"/>.
+    /// </summary>
+    private static AIAgent BuildAgentEndpointInnerAgent(
+        AIProjectClient aiProjectClient,
+        Uri agentEndpoint,
+        ProjectOpenAIClientOptions? clientOptions,
+        IList<AITool>? tools,
+        Func<IChatClient, IChatClient>? clientFactory,
+        IServiceProvider? services)
+    {
+        Throw.IfNull(aiProjectClient);
+        Throw.IfNull(agentEndpoint);
+
         var (agentName, _) = ParseAgentEndpoint(agentEndpoint);
 
         var perAgentOptions = clientOptions ?? new ProjectOpenAIClientOptions();
-        perAgentOptions.Endpoint = agentEndpoint;
-        perAgentOptions.AgentName = agentName;
         perAgentOptions.AddPolicy(RequestOptionsExtensions.UserAgentPolicy, PipelinePosition.PerCall);
 
-        var authPolicy = new BearerTokenPolicy(credential, AzureAiResourceScope);
-        var perAgentClient = new ProjectOpenAIClient(authPolicy, perAgentOptions);
-
-        IChatClient chatClient = perAgentClient.GetProjectResponsesClient().AsIChatClient();
+        IChatClient chatClient = aiProjectClient.ProjectOpenAIClient
+            .GetProjectResponsesClientForAgentEndpoint(agentName, options: perAgentOptions)
+            .AsIChatClient();
         if (clientFactory is not null)
         {
             chatClient = clientFactory(chatClient);
@@ -339,57 +358,6 @@ public sealed class FoundryAgent : DelegatingAIAgent
         return WireClientHeaders(new ChatClientAgent(chatClient, agentOptions, services: services));
     }
 
-    /// <summary>
-    /// Builds the project-scoped <see cref="ProjectOpenAIClient"/> for the agent-endpoint
-    /// constructor by deriving the project root from the supplied agent endpoint and constructing
-    /// a fresh client without <see cref="ProjectOpenAIClientOptions.AgentName"/> so the SDK
-    /// appends the standard <c>/openai/v1</c> suffix expected for project-level surfaces such as
-    /// conversations.
-    /// </summary>
-    /// <remarks>
-    /// Only the four observable primitive properties (<see cref="ClientPipelineOptions.RetryPolicy"/>,
-    /// <see cref="ClientPipelineOptions.NetworkTimeout"/>, <see cref="ClientPipelineOptions.Transport"/>,
-    /// and <c>UserAgentApplicationId</c>) are copied from the caller's options bag. Pipeline
-    /// policies added via <c>AddPolicy</c> on the caller bag do not propagate because
-    /// <see cref="ClientPipelineOptions"/> does not publicly enumerate its policies. The MEAI
-    /// user-agent policy is appended last.
-    /// </remarks>
-    private static ProjectOpenAIClient CreateProjectLevelOpenAIClientFromAgentEndpoint(
-        Uri agentEndpoint,
-        AuthenticationTokenProvider credential,
-        ProjectOpenAIClientOptions? clientOptions)
-    {
-        var (_, projectRoot) = ParseAgentEndpoint(agentEndpoint);
-
-        var projectOptions = new ProjectOpenAIClientOptions();
-        if (clientOptions is not null)
-        {
-            if (clientOptions.RetryPolicy is not null)
-            {
-                projectOptions.RetryPolicy = clientOptions.RetryPolicy;
-            }
-
-            if (clientOptions.NetworkTimeout is not null)
-            {
-                projectOptions.NetworkTimeout = clientOptions.NetworkTimeout;
-            }
-
-            if (clientOptions.Transport is not null)
-            {
-                projectOptions.Transport = clientOptions.Transport;
-            }
-
-            if (!string.IsNullOrEmpty(clientOptions.UserAgentApplicationId))
-            {
-                projectOptions.UserAgentApplicationId = clientOptions.UserAgentApplicationId;
-            }
-        }
-
-        projectOptions.AddPolicy(RequestOptionsExtensions.UserAgentPolicy, PipelinePosition.PerCall);
-
-        return new ProjectOpenAIClient(projectRoot, credential, projectOptions);
-    }
-
     /// <summary>
     /// Parses an agent endpoint URI of shape
     /// <c>https://&lt;host&gt;/.../projects/&lt;project&gt;/agents/&lt;agentName&gt;/endpoint/protocols/openai</c>
@@ -417,8 +385,7 @@ public sealed class FoundryAgent : DelegatingAIAgent
         if (idx < 0)
         {
             throw new ArgumentException(
-                $"Expected an agent endpoint of shape 'https://<host>/.../projects/<project>/agents/<agentName>/endpoint/protocols/openai' but got '{agentEndpoint}'. " +
-                "If you want to construct a FoundryAgent against a project endpoint, use the (Uri projectEndpoint, AuthenticationTokenProvider credential, string model, string instructions, ...) constructor instead.",
+                $"Expected an agent endpoint of shape 'https://<host>/.../projects/<project>/agents/<agentName>/endpoint/protocols/openai' but got '{agentEndpoint}'.",
                 nameof(agentEndpoint));
         }
 
@@ -461,5 +428,32 @@ public sealed class FoundryAgent : DelegatingAIAgent
         return new AIProjectClient(endpoint, credential, clientOptions);
     }
 
+    internal static AIProjectClientOptions? CreateProjectClientOptions(ProjectOpenAIClientOptions? clientOptions)
+    {
+        if (clientOptions is null)
+        {
+            return null;
+        }
+
+        // Copy pipeline behavior the caller configured on the per-agent options bag onto the
+        // project-level options bag so the agent endpoint client honors it. UserAgentApplicationId
+        // is project-level (not derived from the agent endpoint), so it must be carried through too.
+        var projectOptions = new AIProjectClientOptions
+        {
+            Transport = clientOptions.Transport,
+            RetryPolicy = clientOptions.RetryPolicy,
+            NetworkTimeout = clientOptions.NetworkTimeout,
+            MessageLoggingPolicy = clientOptions.MessageLoggingPolicy,
+            UserAgentApplicationId = clientOptions.UserAgentApplicationId,
+        };
+
+        if (clientOptions.ClientLoggingOptions is not null)
+        {
+            projectOptions.ClientLoggingOptions = clientOptions.ClientLoggingOptions;
+        }
+
+        return projectOptions;
+    }
+
     #endregion
 }

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

@@ -1,6 +1,9 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using System;
+using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
+using System.IO;
 using Microsoft.Agents.AI.Compaction;
 using Microsoft.Extensions.AI;
 using Microsoft.Shared.DiagnosticIds;
@@ -10,7 +13,8 @@ namespace Microsoft.Agents.AI;
 
 /// <summary>
 /// A pre-configured <see cref="DelegatingAIAgent"/> that wraps a <see cref="ChatClientAgent"/> with
-/// function invocation, per-service-call chat history persistence, and in-loop compaction.
+/// function invocation, per-service-call chat history persistence, in-loop compaction, and a rich set
+/// of default context providers and agent decorators.
 /// </summary>
 /// <remarks>
 /// <para>
@@ -23,6 +27,27 @@ namespace Microsoft.Agents.AI;
 /// </list>
 /// </para>
 /// <para>
+/// By default, the following context providers are included (each can be disabled via <see cref="HarnessAgentOptions"/>):
+/// <list type="bullet">
+/// <item><description><see cref="TodoProvider"/> — todo list management.</description></item>
+/// <item><description><see cref="AgentModeProvider"/> — agent mode tracking (plan/execute).</description></item>
+/// <item><description><see cref="FileMemoryProvider"/> — file-based session memory.</description></item>
+/// <item><description><see cref="FileAccessProvider"/> — shared file access.</description></item>
+/// <item><description><see cref="AgentSkillsProvider"/> — skill discovery and loading.</description></item>
+/// </list>
+/// </para>
+/// <para>
+/// The agent is also wrapped with the following decorators by default (each can be disabled):
+/// <list type="bullet">
+/// <item><description><see cref="ToolApprovalAgent"/> — "don't ask again" tool approval rules.</description></item>
+/// <item><description><see cref="OpenTelemetryAgent"/> — OpenTelemetry instrumentation.</description></item>
+/// </list>
+/// </para>
+/// <para>
+/// A <see cref="HostedWebSearchTool"/> is added to the chat options by default (can be disabled via
+/// <see cref="HarnessAgentOptions.DisableWebSearch"/>).
+/// </para>
+/// <para>
 /// The underlying <see cref="ChatClientAgent"/> is configured with
 /// <see cref="ChatClientAgentOptions.UseProvidedChatClientAsIs"/> and
 /// <see cref="ChatClientAgentOptions.RequirePerServiceCallChatHistoryPersistence"/> set to <see langword="true"/>
@@ -48,7 +73,9 @@ public sealed class HarnessAgent : DelegatingAIAgent
 
         - Think through the task before acting. Break complex work into clear steps.
         - Use the tools available to you to gather information, perform actions, and verify results.
-        - Explain your reasoning between tool calls so the user can follow your progress.
+        - Explain your reasoning and thought process as you work through tasks.
+        - Explain what you learned and what you are going to do next between tool calls, so the user can follow along with your thought process.
+        - Avoid making more than 4 tool calls in a row without explaining what you are doing.
         - If a tool call fails or returns unexpected results, adapt your approach rather than repeating the same call.
         - When you have completed the task, present a clear and concise summary of what you did and what you found.
         """;
@@ -74,15 +101,15 @@ public sealed class HarnessAgent : DelegatingAIAgent
     /// additional context providers, and chat history provider.
     /// When <see langword="null"/>, the agent uses built-in default settings.
     /// </param>
-    /// <exception cref="System.ArgumentNullException">
+    /// <exception cref="ArgumentNullException">
     /// <paramref name="chatClient"/> is <see langword="null"/>.
     /// </exception>
-    /// <exception cref="System.ArgumentOutOfRangeException">
+    /// <exception cref="ArgumentOutOfRangeException">
     /// <paramref name="maxContextWindowTokens"/> is not positive, or
     /// <paramref name="maxOutputTokens"/> is negative or greater than or equal to <paramref name="maxContextWindowTokens"/>.
     /// </exception>
     public HarnessAgent(IChatClient chatClient, int maxContextWindowTokens, int maxOutputTokens, HarnessAgentOptions? options = null)
-        : base(BuildInnerAgent(
+        : base(BuildAgent(
             Throw.IfNull(chatClient),
             maxContextWindowTokens,
             maxOutputTokens,
@@ -90,6 +117,25 @@ public sealed class HarnessAgent : DelegatingAIAgent
     {
     }
 
+    private static AIAgent BuildAgent(IChatClient chatClient, int maxContextWindowTokens, int maxOutputTokens, HarnessAgentOptions? options)
+    {
+        ChatClientAgent innerAgent = BuildInnerAgent(chatClient, maxContextWindowTokens, maxOutputTokens, options);
+
+        AIAgentBuilder builder = innerAgent.AsBuilder();
+
+        if (options?.DisableToolApproval is not true)
+        {
+            builder.UseToolApproval();
+        }
+
+        if (options?.DisableOpenTelemetry is not true)
+        {
+            builder.UseOpenTelemetry(sourceName: options?.OpenTelemetrySourceName);
+        }
+
+        return builder.Build();
+    }
+
     private static ChatClientAgent BuildInnerAgent(IChatClient chatClient, int maxContextWindowTokens, int maxOutputTokens, HarnessAgentOptions? options)
     {
         var compactionStrategy = new ContextWindowCompactionStrategy(
@@ -102,15 +148,28 @@ public sealed class HarnessAgent : DelegatingAIAgent
                 ChatReducer = compactionStrategy.AsChatReducer(),
             });
 
-        string instructions = options?.ChatOptions?.Instructions ?? DefaultInstructions;
+        string harnessInstructions = options?.HarnessInstructions ?? DefaultInstructions;
+        string? agentInstructions = options?.ChatOptions?.Instructions;
 
-        ChatOptions chatOptions = BuildChatOptions(options?.ChatOptions, instructions, maxOutputTokens);
+        string instructions = (string.IsNullOrWhiteSpace(harnessInstructions), string.IsNullOrWhiteSpace(agentInstructions)) switch
+        {
+            (true, true) => harnessInstructions,
+            (true, false) => agentInstructions!,
+            (false, true) => harnessInstructions,
+            (false, false) => $"{harnessInstructions}\n\n{agentInstructions}",
+        };
+
+        ChatOptions chatOptions = BuildChatOptions(options, instructions, maxOutputTokens);
 
         var compactionProvider = new CompactionProvider(compactionStrategy);
 
+        IEnumerable<AIContextProvider> contextProviders = BuildContextProviders(options);
+
         return chatClient
             .AsBuilder()
-            .UseFunctionInvocation()
+            .UseFunctionInvocation(configure: options?.MaximumIterationsPerRequest is int maxIterations
+                ? ficc => ficc.MaximumIterationsPerRequest = maxIterations
+                : null)
             .UseMessageInjection()
             .UsePerServiceCallChatHistoryPersistence()
             .UseAIContextProviders(compactionProvider)
@@ -121,17 +180,80 @@ public sealed class HarnessAgent : DelegatingAIAgent
                 Description = options?.Description,
                 ChatOptions = chatOptions,
                 ChatHistoryProvider = chatHistoryProvider,
-                AIContextProviders = options?.AIContextProviders,
+                AIContextProviders = contextProviders,
                 UseProvidedChatClientAsIs = true,
                 RequirePerServiceCallChatHistoryPersistence = true,
+                WarnOnChatHistoryProviderConflict = false,
+                ThrowOnChatHistoryProviderConflict = false,
             });
     }
 
-    private static ChatOptions BuildChatOptions(ChatOptions? source, string instructions, int maxOutputTokens)
+    private static ChatOptions BuildChatOptions(HarnessAgentOptions? options, string instructions, int maxOutputTokens)
     {
-        ChatOptions result = source?.Clone() ?? new ChatOptions();
+        ChatOptions result = options?.ChatOptions?.Clone() ?? new ChatOptions();
         result.Instructions = instructions;
         result.MaxOutputTokens ??= maxOutputTokens;
+
+        if (options?.DisableWebSearch is not true)
+        {
+            result.Tools ??= [];
+            result.Tools.Add(new HostedWebSearchTool());
+        }
+
         return result;
     }
+
+    private static List<AIContextProvider> BuildContextProviders(HarnessAgentOptions? options)
+    {
+        var providers = new List<AIContextProvider>();
+
+        if (options?.DisableTodoProvider is not true)
+        {
+            providers.Add(new TodoProvider());
+        }
+
+        if (options?.DisableAgentModeProvider is not true)
+        {
+            providers.Add(new AgentModeProvider(options?.AgentModeProviderOptions));
+        }
+
+        if (options?.DisableFileMemory is not true)
+        {
+            AgentFileStore fileMemoryStore = options?.FileMemoryStore
+                ?? new FileSystemAgentFileStore(
+                    Path.Combine(Directory.GetCurrentDirectory(), "agent-file-memory"));
+
+            providers.Add(new FileMemoryProvider(
+                fileMemoryStore,
+                _ => new FileMemoryState
+                {
+                    WorkingFolder = DateTime.UtcNow.ToString("yyyyMMdd_HHmmss") + "_" + Guid.NewGuid().ToString(),
+                }));
+        }
+
+        if (options?.DisableFileAccess is not true)
+        {
+            AgentFileStore fileAccessStore = options?.FileAccessStore
+                ?? new FileSystemAgentFileStore(
+                    Path.Combine(Directory.GetCurrentDirectory(), "working"));
+
+            providers.Add(new FileAccessProvider(fileAccessStore));
+        }
+
+        if (options?.DisableAgentSkillsProvider is not true)
+        {
+            AgentSkillsProvider skillsProvider = options?.AgentSkillsSource is AgentSkillsSource source
+                ? new AgentSkillsProvider(source)
+                : new AgentSkillsProvider(Directory.GetCurrentDirectory());
+
+            providers.Add(skillsProvider);
+        }
+
+        if (options?.AIContextProviders is IEnumerable<AIContextProvider> userProviders)
+        {
+            providers.AddRange(userProviders);
+        }
+
+        return providers;
+    }
 }

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

@@ -36,13 +36,31 @@ public sealed class HarnessAgentOptions
     /// Use <see cref="ChatOptions.Tools"/> to supply additional tools the agent can invoke.
     /// </para>
     /// <para>
-    /// Use <see cref="ChatOptions.Instructions"/> to override the <see cref="HarnessAgent"/>'s built-in
-    /// default instructions. When <see cref="ChatOptions.Instructions"/> is <see langword="null"/> or not set,
-    /// the default instructions are used.
+    /// Use <see cref="ChatOptions.Instructions"/> to provide agent-specific instructions (e.g., research methodology,
+    /// data analysis workflow). These are combined with <see cref="HarnessInstructions"/> to form the final instructions
+    /// sent to the model: harness instructions appear first, followed by agent-specific instructions.
+    /// When <see cref="ChatOptions.Instructions"/> is <see langword="null"/>, only <see cref="HarnessInstructions"/>
+    /// (or the default) is used.
     /// </para>
     /// </remarks>
     public ChatOptions? ChatOptions { get; set; }
 
+    /// <summary>
+    /// Gets or sets the harness-level instructions that control general tool usage and behavior patterns.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Harness instructions provide guidance on how to use tools, explain reasoning, and structure work.
+    /// They are combined with <see cref="ChatOptions"/>.<see cref="ChatOptions.Instructions"/> (agent-specific instructions)
+    /// to produce the final instructions sent to the model: harness instructions first, then agent-specific instructions.
+    /// </para>
+    /// <para>
+    /// When <see langword="null"/> (the default), <see cref="HarnessAgent.DefaultInstructions"/> is used.
+    /// Set to <see cref="string.Empty"/> to omit harness instructions entirely.
+    /// </para>
+    /// </remarks>
+    public string? HarnessInstructions { get; set; }
+
     /// <summary>
     /// Gets or sets the <see cref="ChatHistoryProvider"/> to use for storing chat history.
     /// </summary>
@@ -61,4 +79,143 @@ public sealed class HarnessAgentOptions
     /// <see cref="ChatClientAgentOptions.AIContextProviders"/>.
     /// </remarks>
     public IEnumerable<AIContextProvider>? AIContextProviders { get; set; }
+
+    /// <summary>
+    /// Gets or sets the maximum number of function-invocation loop iterations per request.
+    /// </summary>
+    /// <remarks>
+    /// When set, this value is passed to <see cref="FunctionInvokingChatClient.MaximumIterationsPerRequest"/>.
+    /// When <see langword="null"/>, the <see cref="FunctionInvokingChatClient"/> default is used.
+    /// </remarks>
+    public int? MaximumIterationsPerRequest { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the <see cref="ToolApprovalAgent"/> wrapper is disabled.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="false"/> (the default), the agent is wrapped with tool approval middleware
+    /// that supports "don't ask again" auto-approval rules.
+    /// </remarks>
+    public bool DisableToolApproval { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the <see cref="FileMemoryProvider"/> is disabled.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="false"/> (the default), a <see cref="FileMemoryProvider"/> is included in the
+    /// agent's context providers, using either <see cref="FileMemoryStore"/> or a default
+    /// <see cref="FileSystemAgentFileStore"/> rooted at <c>{cwd}/agent-file-memory/{timestamp}_{guid}</c>.
+    /// </remarks>
+    public bool DisableFileMemory { get; set; }
+
+    /// <summary>
+    /// Gets or sets a custom <see cref="AgentFileStore"/> for the <see cref="FileMemoryProvider"/>.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="null"/> and <see cref="DisableFileMemory"/> is <see langword="false"/>,
+    /// a default <see cref="FileSystemAgentFileStore"/> is created.
+    /// This property is ignored when <see cref="DisableFileMemory"/> is <see langword="true"/>.
+    /// </remarks>
+    public AgentFileStore? FileMemoryStore { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the <see cref="FileAccessProvider"/> is disabled.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="false"/> (the default), a <see cref="FileAccessProvider"/> is included in the
+    /// agent's context providers, using either <see cref="FileAccessStore"/> or a default
+    /// <see cref="FileSystemAgentFileStore"/> rooted at <c>{cwd}/working</c>.
+    /// </remarks>
+    public bool DisableFileAccess { get; set; }
+
+    /// <summary>
+    /// Gets or sets a custom <see cref="AgentFileStore"/> for the <see cref="FileAccessProvider"/>.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="null"/> and <see cref="DisableFileAccess"/> is <see langword="false"/>,
+    /// a default <see cref="FileSystemAgentFileStore"/> is created.
+    /// This property is ignored when <see cref="DisableFileAccess"/> is <see langword="true"/>.
+    /// </remarks>
+    public AgentFileStore? FileAccessStore { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the <see cref="HostedWebSearchTool"/> is disabled.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="false"/> (the default), a <see cref="HostedWebSearchTool"/> is added
+    /// to <see cref="ChatOptions"/>.<see cref="ChatOptions.Tools"/>.
+    /// </remarks>
+    public bool DisableWebSearch { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the <see cref="TodoProvider"/> is disabled.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="false"/> (the default), a <see cref="TodoProvider"/> is included
+    /// in the agent's context providers for tracking work items.
+    /// </remarks>
+    public bool DisableTodoProvider { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the <see cref="AgentModeProvider"/> is disabled.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="false"/> (the default), an <see cref="AgentModeProvider"/> is included
+    /// in the agent's context providers. Use <see cref="AgentModeProviderOptions"/> to configure
+    /// custom modes.
+    /// </remarks>
+    public bool DisableAgentModeProvider { get; set; }
+
+    /// <summary>
+    /// Gets or sets custom options for the <see cref="AgentModeProvider"/>.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="null"/>, the <see cref="AgentModeProvider"/> uses its built-in default
+    /// modes ("plan" and "execute"). This property is ignored when
+    /// <see cref="DisableAgentModeProvider"/> is <see langword="true"/>.
+    /// </remarks>
+    public AgentModeProviderOptions? AgentModeProviderOptions { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the <see cref="AgentSkillsProvider"/> is disabled.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="false"/> (the default), an <see cref="AgentSkillsProvider"/> is included
+    /// in the agent's context providers. Use <see cref="AgentSkillsSource"/> to provide a custom
+    /// skills source; otherwise, the provider defaults to file-based skill discovery from the current
+    /// working directory.
+    /// </remarks>
+    public bool DisableAgentSkillsProvider { get; set; }
+
+    /// <summary>
+    /// Gets or sets a custom <see cref="AI.AgentSkillsSource"/> for the <see cref="AgentSkillsProvider"/>.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="null"/> and <see cref="DisableAgentSkillsProvider"/> is <see langword="false"/>,
+    /// the provider defaults to file-based skill discovery from the current working directory.
+    /// This property is ignored when <see cref="DisableAgentSkillsProvider"/> is <see langword="true"/>.
+    /// </remarks>
+    public AgentSkillsSource? AgentSkillsSource { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the <see cref="OpenTelemetryAgent"/> wrapper is disabled.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="false"/> (the default), the agent is wrapped with an
+    /// <see cref="OpenTelemetryAgent"/> that provides OpenTelemetry instrumentation
+    /// following the Semantic Conventions for Generative AI systems.
+    /// </remarks>
+    public bool DisableOpenTelemetry { get; set; }
+
+    /// <summary>
+    /// Gets or sets the OpenTelemetry source name used by the <see cref="OpenTelemetryAgent"/> wrapper.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="null"/> (the default), the framework's default source name
+    /// (<c>"Experimental.Microsoft.Agents.AI"</c>) is used.
+    /// Set this to a custom value to enable filtering spans from a specific <see cref="System.Diagnostics.ActivitySource"/>
+    /// in your <c>TracerProvider</c> configuration.
+    /// This property is ignored when <see cref="DisableOpenTelemetry"/> is <see langword="true"/>.
+    /// </remarks>
+    public string? OpenTelemetrySourceName { get; set; }
 }

dotnet/src/Microsoft.Agents.AI.OpenAI/Extensions/OpenAIResponseClientExtensions.cs

@@ -120,9 +120,24 @@ public static class OpenAIResponseClientExtensions
         return Throw.IfNull(responseClient)
             .AsIChatClient(model)
             .AsBuilder()
-            .ConfigureOptions(x => x.RawRepresentationFactory = _ => includeReasoningEncryptedContent
-                ? new CreateResponseOptions() { StoredOutputEnabled = false, IncludedProperties = { IncludedResponseProperty.ReasoningEncryptedContent } }
-                : new CreateResponseOptions() { StoredOutputEnabled = false })
+            .ConfigureOptions(x =>
+            {
+                var previousFactory = x.RawRepresentationFactory;
+                x.RawRepresentationFactory = state =>
+                {
+                    var responseOptions = previousFactory?.Invoke(state) as CreateResponseOptions ?? new CreateResponseOptions();
+
+                    responseOptions.StoredOutputEnabled = false;
+
+                    if (includeReasoningEncryptedContent &&
+                        !responseOptions.IncludedProperties.Contains(IncludedResponseProperty.ReasoningEncryptedContent))
+                    {
+                        responseOptions.IncludedProperties.Add(IncludedResponseProperty.ReasoningEncryptedContent);
+                    }
+
+                    return responseOptions;
+                };
+            })
             .Build();
     }
 }

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative.Mcp/DefaultMcpToolHandler.cs

@@ -12,6 +12,7 @@ using System.Threading;
 using System.Threading.Tasks;
 using Microsoft.Extensions.AI;
 using Microsoft.Shared.Diagnostics;
+using ModelContextProtocol;
 using ModelContextProtocol.Client;
 using ModelContextProtocol.Protocol;
 
@@ -27,6 +28,8 @@ namespace Microsoft.Agents.AI.Workflows.Declarative.Mcp;
 /// </remarks>
 public sealed class DefaultMcpToolHandler : IMcpToolHandler, IAsyncDisposable
 {
+    private const string FilenameAdditionalPropertyName = "filename";
+
     /// <summary>
     /// Reserved <c>toolName</c> value that maps an <see cref="IMcpToolHandler.InvokeToolAsync"/> request
     /// to the MCP protocol <c>tools/list</c> discovery operation.
@@ -272,46 +275,46 @@ public sealed class DefaultMcpToolHandler : IMcpToolHandler, IAsyncDisposable
 
     internal static AIContent ConvertContentBlock(ContentBlock block)
     {
-        return block switch
+        // Delegate to the MCP SDK's canonical converter. It maps every known
+        // ContentBlock subtype (Text/Image/Audio/EmbeddedResource/ToolUse/ToolResult)
+        // and sets RawRepresentation + AdditionalProperties from block.Meta.
+        // It intentionally returns null for ResourceLinkBlock — map that to
+        // UriContent here so callers always receive a usable AIContent.
+        return block.ToAIContent() ?? block switch
         {
-            TextContentBlock text => new TextContent(text.Text),
-            ImageContentBlock image => CreateDataContent(image.Data, image.MimeType ?? "image/*"),
-            AudioContentBlock audio => CreateDataContent(audio.Data, audio.MimeType ?? "audio/*"),
-            EmbeddedResourceBlock embedded => ConvertEmbeddedResource(embedded),
-            _ => new TextContent(block.ToString() ?? string.Empty),
+            ResourceLinkBlock link => new UriContent(link.Uri, link.MimeType ?? "application/octet-stream")
+            {
+                RawRepresentation = link,
+                AdditionalProperties = CreateAdditionalProperties(link),
+            },
+            _ => new TextContent(block.ToString() ?? string.Empty)
+            {
+                RawRepresentation = block,
+                AdditionalProperties = CreateAdditionalProperties(block),
+            },
         };
     }
 
-    private static AIContent ConvertEmbeddedResource(EmbeddedResourceBlock block)
+    private static AdditionalPropertiesDictionary? CreateAdditionalProperties(ContentBlock block)
     {
-        return block.Resource switch
-        {
-            TextResourceContents text => new TextContent(text.Text),
-            BlobResourceContents blob => CreateDataContent(blob.Blob, blob.MimeType ?? "application/octet-stream"),
-            _ => new TextContent(block.ToString() ?? string.Empty),
-        };
-    }
+        AdditionalPropertiesDictionary? properties = null;
 
-    private static DataContent CreateDataContent(ReadOnlyMemory<byte> base64Utf8Data, string mediaType)
-    {
-        if (base64Utf8Data.IsEmpty)
+        if (block.Meta is not null)
         {
-            return new DataContent($"data:{mediaType};base64,", mediaType);
+            foreach (var property in block.Meta)
+            {
+                properties ??= new AdditionalPropertiesDictionary();
+                properties.Add(property.Key, property.Value);
+            }
         }
 
-#if NET8_0_OR_GREATER
-        string base64 = Encoding.UTF8.GetString(base64Utf8Data.Span);
-#else
-        string base64 = Encoding.UTF8.GetString(base64Utf8Data.ToArray());
-#endif
-
-        // If it's already a data URI, use it directly
-        if (base64.StartsWith("data:", StringComparison.OrdinalIgnoreCase))
+        if (block is ResourceLinkBlock { Name: { Length: > 0 } name })
         {
-            return new DataContent(base64, mediaType);
+            properties ??= new AdditionalPropertiesDictionary();
+            properties.TryAdd(FilenameAdditionalPropertyName, name);
         }
 
-        return new DataContent($"data:{mediaType};base64,{base64}", mediaType);
+        return properties;
     }
 
     private static string SerializeToolsList(IEnumerable<Tool> tools)

dotnet/src/Microsoft.Agents.AI/AgentJsonUtilities.cs

@@ -74,9 +74,11 @@ internal static partial class AgentJsonUtilities
     [JsonSerializable(typeof(TodoState))]
     [JsonSerializable(typeof(TodoItem))]
     [JsonSerializable(typeof(TodoItemInput))]
+    [JsonSerializable(typeof(TodoCompleteInput))]
     [JsonSerializable(typeof(List<int>), TypeInfoPropertyName = "IntList")]
     [JsonSerializable(typeof(List<TodoItem>), TypeInfoPropertyName = "TodoItemList")]
     [JsonSerializable(typeof(List<TodoItemInput>), TypeInfoPropertyName = "TodoItemInputList")]
+    [JsonSerializable(typeof(List<TodoCompleteInput>), TypeInfoPropertyName = "TodoCompleteInputList")]
 
     // AgentModeProvider types
     [JsonSerializable(typeof(AgentModeState))]
@@ -95,12 +97,12 @@ internal static partial class AgentJsonUtilities
     [JsonSerializable(typeof(FileListEntry))]
     [JsonSerializable(typeof(List<FileListEntry>), TypeInfoPropertyName = "FileListEntryList")]
 
-    // SubAgentsProvider types
-    [JsonSerializable(typeof(SubAgentState))]
-    [JsonSerializable(typeof(SubAgentRuntimeState))]
-    [JsonSerializable(typeof(SubTaskInfo))]
-    [JsonSerializable(typeof(SubTaskStatus))]
-    [JsonSerializable(typeof(List<SubTaskInfo>), TypeInfoPropertyName = "SubTaskInfoList")]
+    // BackgroundAgentsProvider types
+    [JsonSerializable(typeof(BackgroundAgentState))]
+    [JsonSerializable(typeof(BackgroundAgentRuntimeState))]
+    [JsonSerializable(typeof(BackgroundTaskInfo))]
+    [JsonSerializable(typeof(BackgroundTaskStatus))]
+    [JsonSerializable(typeof(List<BackgroundTaskInfo>), TypeInfoPropertyName = "BackgroundTaskInfoList")]
 
     [ExcludeFromCodeCoverage]
     internal sealed partial class JsonContext : JsonSerializerContext;

dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeProvider.cs

@@ -45,20 +45,54 @@ public sealed class AgentModeProvider : AIContextProvider
         """
         ## Agent Mode
 
-        You can operate in different modes. Depending on the mode you are in, you will be required to follow different processes.
+        - You can operate in different modes. Depending on the mode you are in, you will be required to follow different processes.
+        - You must check the current mode after any user input, since the user may have changed the mode themselves,
+          e.g. the user may have switched to 'plan' mode after a previous research task finished in 'execute' mode, meaning they want to review a plan first before execution.
 
         Use the AgentMode_Get tool to check your current operating mode.
         Use the AgentMode_Set tool to switch between modes as your work progresses. Only use AgentMode_Set if the user explicitly instructs/allows you to change modes.
 
-        {available_modes}
-
         You are currently operating in the {current_mode} mode.
+
+        ### Mandatory Mode based Workflow
+
+        For every new substantive user request, including short factual questions, your behavior is determined by the mode you are in.
+
+        {available_modes}
         """;
 
     private static readonly IReadOnlyList<AgentModeProviderOptions.AgentMode> s_defaultModes =
     [
-        new("plan", "Use this mode when analyzing requirements, breaking down tasks, and creating plans. This is the interactive mode — ask clarifying questions, discuss options, and get user approval before proceeding."),
-        new("execute", "Use this mode when carrying out approved plans. Work autonomously using your best judgement — do not ask the user questions or wait for feedback. Make reasonable decisions on your own so that there is a complete, useful result when the user returns. If you encounter ambiguity, choose the most reasonable option and note your choice."),
+        new(
+            "plan",
+            """
+            Use this mode when analyzing requirements, breaking down tasks, and creating plans. This is the interactive mode — ask clarifying questions, discuss options, and get user approval before proceeding.
+
+            Process to follow when in plan mode:
+            1. Analyze the request with the purpose of building a research plan.
+            2. Create a list of todo items.
+            3. If needed, use the provided tools to do some exploratory checks to help build a plan and determine what clarifying questions you may need from the user.
+            4. Ask for clarifications from the user where needed.
+              1. Ask each clarification one by one.
+              2. When asking for clarification and you have specific options in mind, present them to the user, so they can choose the option instead of having to retype the entire response.
+              3. Do not proceed until you have received all the needed clarifications.
+              4. Do short exploratory research if it helps with being able to ask sensible clarifications from the user.
+            5. Write the plan to a memory file, so that it is retained even if compaction happens. Make sure to update the plan file if the user requests changes.
+            6. Present the plan to the user and ask for approval to switch to execute mode and process the plan.
+            7. When approval is granted, always switch to execute mode (using the `AgentMode_Set` tool), and follow the steps for *Execute mode*.
+            """),
+        new(
+            "execute",
+            """
+            Use this mode when carrying out approved plans. Work autonomously using your best judgment — do not ask the user questions or wait for feedback.
+            
+            Process to follow when in execute mode:
+            1. If you don't have a plan or tasks yet, analyze the user request and create tasks and a plan. (**Skip this step if you came from plan mode**)
+            2. Work autonomously — use your best judgment to make decisions and keep progressing without asking the user questions. The goal is to have a complete, useful result ready when the user returns.
+            3. If you encounter ambiguity or an unexpected situation during execution, choose the most reasonable option, note your choice, and keep going.
+            4. Mark tasks as completed as you finish them.
+            5. Continue working, thinking and calling tools until you have the research result for the user.
+            """),
     ];
 
     private readonly ProviderSessionState<AgentModeState> _sessionState;
@@ -187,12 +221,15 @@ public sealed class AgentModeProvider : AIContextProvider
 
     private string BuildInstructions(string currentMode)
     {
-        // Build list of modes text:
         var modesListBuilder = new StringBuilder();
         foreach (var mode in this._modes)
         {
-            modesListBuilder.AppendLine($"- \"{mode.Name}\": {mode.Description}");
+            modesListBuilder.AppendLine($"#### {mode.Name}");
+            modesListBuilder.AppendLine();
+            modesListBuilder.AppendLine(mode.Description.TrimEnd());
+            modesListBuilder.AppendLine();
         }
+
         var modesListText = modesListBuilder.ToString();
 
         return new StringBuilder(this._instructions)

dotnet/src/Microsoft.Agents.AI/Harness/BackgroundAgents/BackgroundAgentRuntimeState.cs

@@ -7,15 +7,15 @@ using System.Threading.Tasks;
 namespace Microsoft.Agents.AI;
 
 /// <summary>
-/// Holds non-serializable runtime references for in-flight sub-tasks within a single parent session.
+/// Holds non-serializable runtime references for in-flight background tasks within a single parent session.
 /// </summary>
 /// <remarks>
 /// Properties are marked with <see cref="JsonIgnoreAttribute"/> because <see cref="Task{TResult}"/>
 /// and <see cref="AgentSession"/> are not JSON-serializable. After deserialization (e.g., after a restart),
 /// a fresh empty instance is created and any previously-running tasks are marked as
-/// <see cref="SubTaskStatus.Lost"/> by <see cref="SubAgentsProvider"/>.
+/// <see cref="BackgroundTaskStatus.Lost"/> by <see cref="BackgroundAgentsProvider"/>.
 /// </remarks>
-internal sealed class SubAgentRuntimeState
+internal sealed class BackgroundAgentRuntimeState
 {
     /// <summary>
     /// Gets the mapping of task IDs to their in-flight <see cref="Task{AgentResponse}"/> instances.
@@ -24,9 +24,9 @@ internal sealed class SubAgentRuntimeState
     public Dictionary<int, Task<AgentResponse>> InFlightTasks { get; } = [];
 
     /// <summary>
-    /// Gets the mapping of task IDs to their sub-agent <see cref="AgentSession"/> instances,
+    /// Gets the mapping of task IDs to their background agent <see cref="AgentSession"/> instances,
     /// needed for <c>ContinueTask</c>.
     /// </summary>
     [JsonIgnore]
-    public Dictionary<int, AgentSession> SubTaskSessions { get; } = [];
+    public Dictionary<int, AgentSession> BackgroundTaskSessions { get; } = [];
 }

dotnet/src/Microsoft.Agents.AI/Harness/BackgroundAgents/BackgroundAgentState.cs

@@ -8,21 +8,21 @@ using Microsoft.Shared.DiagnosticIds;
 namespace Microsoft.Agents.AI;
 
 /// <summary>
-/// Represents the serializable state of sub-tasks managed by the <see cref="SubAgentsProvider"/>,
+/// Represents the serializable state of background tasks managed by the <see cref="BackgroundAgentsProvider"/>,
 /// stored in the session's <see cref="AgentSessionStateBag"/>.
 /// </summary>
 [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
-internal sealed class SubAgentState
+internal sealed class BackgroundAgentState
 {
     /// <summary>
-    /// Gets or sets the next ID to assign to a new sub-task.
+    /// Gets or sets the next ID to assign to a new background task.
     /// </summary>
     [JsonPropertyName("nextTaskId")]
     public int NextTaskId { get; set; } = 1;
 
     /// <summary>
-    /// Gets the list of sub-task metadata entries.
+    /// Gets the list of background task metadata entries.
     /// </summary>
     [JsonPropertyName("tasks")]
-    public List<SubTaskInfo> Tasks { get; set; } = [];
+    public List<BackgroundTaskInfo> Tasks { get; set; } = [];
 }

dotnet/src/Microsoft.Agents.AI/Harness/BackgroundAgents/BackgroundAgentsProvider.cs

@@ -15,56 +15,56 @@ using Microsoft.Shared.Diagnostics;
 namespace Microsoft.Agents.AI;
 
 /// <summary>
-/// An <see cref="AIContextProvider"/> that enables an agent to delegate work to sub-agents asynchronously.
+/// An <see cref="AIContextProvider"/> that enables an agent to delegate work to background agents asynchronously.
 /// </summary>
 /// <remarks>
 /// <para>
-/// The <see cref="SubAgentsProvider"/> allows a parent agent to start sub-tasks on child agents,
-/// wait for their completion, and retrieve results. Each sub-task runs in its own session and
+/// The <see cref="BackgroundAgentsProvider"/> allows a parent agent to start background tasks on child agents,
+/// wait for their completion, and retrieve results. Each background task runs in its own session and
 /// executes concurrently.
 /// </para>
 /// <para>
 /// This provider exposes the following tools to the agent:
 /// <list type="bullet">
-/// <item><description><c>SubAgents_StartTask</c> — Start a sub-task on a named agent with text input. Returns the task ID.</description></item>
-/// <item><description><c>SubAgents_WaitForFirstCompletion</c> — Block until the first of the specified tasks completes. Returns the completed task's ID.</description></item>
-/// <item><description><c>SubAgents_GetTaskResults</c> — Retrieve the text output of a completed sub-task.</description></item>
-/// <item><description><c>SubAgents_GetAllTasks</c> — List all sub-tasks with their IDs, statuses, descriptions, and agent names.</description></item>
-/// <item><description><c>SubAgents_ContinueTask</c> — Send follow-up input to a completed sub-task's session to resume work.</description></item>
-/// <item><description><c>SubAgents_ClearCompletedTask</c> — Remove a completed sub-task and release its session to free memory.</description></item>
+/// <item><description><c>BackgroundAgents_StartTask</c> — Start a background task on a named agent with text input. Returns the task ID.</description></item>
+/// <item><description><c>BackgroundAgents_WaitForFirstCompletion</c> — Block until the first of the specified tasks completes. Returns the completed task's ID.</description></item>
+/// <item><description><c>BackgroundAgents_GetTaskResults</c> — Retrieve the text output of a completed background task.</description></item>
+/// <item><description><c>BackgroundAgents_GetAllTasks</c> — List all background tasks with their IDs, statuses, descriptions, and agent names.</description></item>
+/// <item><description><c>BackgroundAgents_ContinueTask</c> — Send follow-up input to a completed background task's session to resume work.</description></item>
+/// <item><description><c>BackgroundAgents_ClearCompletedTask</c> — Remove a completed background task and release its session to free memory.</description></item>
 /// </list>
 /// </para>
 /// </remarks>
 [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
-public sealed class SubAgentsProvider : AIContextProvider
+public sealed class BackgroundAgentsProvider : AIContextProvider
 {
     private const string DefaultInstructions =
         """
-        ## SubAgents
-        You have access to sub-agents that can perform work on your behalf.
+        ## BackgroundAgents
+        You have access to background agents that can perform work on your behalf.
 
-        - Use the `SubAgents_*` list of tools to start tasks on sub agents and check their results.
-        - Creating a sub task does not block, and sub-tasks run concurrently.
+        - Use the `BackgroundAgents_*` list of tools to start tasks on background agents and check their results.
+        - Creating a background task does not block, and background tasks run concurrently.
         - Important: Always wait for outstanding tasks to finish before you finish processing.
-        - Important: After retrieving results from a completed task, clear it with SubAgents_ClearCompletedTask to free memory, unless you plan to continue it with SubAgents_ContinueTask.
+        - Important: After retrieving results from a completed task, clear it with BackgroundAgents_ClearCompletedTask to free memory, unless you plan to continue it with BackgroundAgents_ContinueTask.
 
-        {sub_agents}
+        {background_agents}
         """;
 
     private readonly Dictionary<string, AIAgent> _agents;
-    private readonly ProviderSessionState<SubAgentState> _sessionState;
-    private readonly ProviderSessionState<SubAgentRuntimeState> _runtimeSessionState;
+    private readonly ProviderSessionState<BackgroundAgentState> _sessionState;
+    private readonly ProviderSessionState<BackgroundAgentRuntimeState> _runtimeSessionState;
     private readonly string _instructions;
     private IReadOnlyList<string>? _stateKeys;
 
     /// <summary>
-    /// Initializes a new instance of the <see cref="SubAgentsProvider"/> class.
+    /// Initializes a new instance of the <see cref="BackgroundAgentsProvider"/> class.
     /// </summary>
-    /// <param name="agents">The collection of sub-agents available for delegation.</param>
+    /// <param name="agents">The collection of background agents available for delegation.</param>
     /// <param name="options">Optional settings controlling the provider behavior.</param>
     /// <exception cref="ArgumentNullException"><paramref name="agents"/> is <see langword="null"/>.</exception>
     /// <exception cref="ArgumentException">An agent has a null or empty name, or agent names are not unique.</exception>
-    public SubAgentsProvider(IEnumerable<AIAgent> agents, SubAgentsProviderOptions? options = null)
+    public BackgroundAgentsProvider(IEnumerable<AIAgent> agents, BackgroundAgentsProviderOptions? options = null)
     {
         _ = Throw.IfNull(agents);
 
@@ -74,15 +74,15 @@ public sealed class SubAgentsProvider : AIContextProvider
         string agentListText = options?.AgentListBuilder is not null
             ? options.AgentListBuilder(this._agents)
             : BuildDefaultAgentListText(this._agents);
-        this._instructions = baseInstructions.Replace("{sub_agents}", agentListText);
+        this._instructions = baseInstructions.Replace("{background_agents}", agentListText);
 
-        this._sessionState = new ProviderSessionState<SubAgentState>(
-            _ => new SubAgentState(),
+        this._sessionState = new ProviderSessionState<BackgroundAgentState>(
+            _ => new BackgroundAgentState(),
             this.GetType().Name,
             AgentJsonUtilities.DefaultOptions);
 
-        this._runtimeSessionState = new ProviderSessionState<SubAgentRuntimeState>(
-            _ => new SubAgentRuntimeState(),
+        this._runtimeSessionState = new ProviderSessionState<BackgroundAgentRuntimeState>(
+            _ => new BackgroundAgentRuntimeState(),
             this.GetType().Name + "_Runtime",
             AgentJsonUtilities.DefaultOptions);
     }
@@ -93,8 +93,8 @@ public sealed class SubAgentsProvider : AIContextProvider
     /// <inheritdoc />
     protected override ValueTask<AIContext> ProvideAIContextAsync(InvokingContext context, CancellationToken cancellationToken = default)
     {
-        SubAgentState state = this._sessionState.GetOrInitializeState(context.Session);
-        SubAgentRuntimeState runtimeState = this._runtimeSessionState.GetOrInitializeState(context.Session);
+        BackgroundAgentState state = this._sessionState.GetOrInitializeState(context.Session);
+        BackgroundAgentRuntimeState runtimeState = this._runtimeSessionState.GetOrInitializeState(context.Session);
 
         return new ValueTask<AIContext>(new AIContext
         {
@@ -113,12 +113,12 @@ public sealed class SubAgentsProvider : AIContextProvider
         {
             if (string.IsNullOrWhiteSpace(agent.Name))
             {
-                throw new ArgumentException("All sub-agents must have a non-empty Name.", nameof(agents));
+                throw new ArgumentException("All background agents must have a non-empty Name.", nameof(agents));
             }
 
             if (dict.ContainsKey(agent.Name))
             {
-                throw new ArgumentException($"Duplicate sub-agent name: '{agent.Name}'. Agent names must be unique (case-insensitive).", nameof(agents));
+                throw new ArgumentException($"Duplicate background agent name: '{agent.Name}'. Agent names must be unique (case-insensitive).", nameof(agents));
             }
 
             dict[agent.Name] = agent;
@@ -126,19 +126,19 @@ public sealed class SubAgentsProvider : AIContextProvider
 
         if (dict.Count == 0)
         {
-            throw new ArgumentException("At least one sub-agent must be provided.", nameof(agents));
+            throw new ArgumentException("At least one background agent must be provided.", nameof(agents));
         }
 
         return dict;
     }
 
     /// <summary>
-    /// Builds the default text listing available sub-agents and their descriptions.
+    /// Builds the default text listing available background agents and their descriptions.
     /// </summary>
     private static string BuildDefaultAgentListText(IReadOnlyDictionary<string, AIAgent> agents)
     {
         var sb = new StringBuilder();
-        sb.AppendLine("Available sub-agents:");
+        sb.AppendLine("Available background agents:");
         foreach (var kvp in agents)
         {
             sb.Append("- ").Append(kvp.Key);
@@ -156,12 +156,12 @@ public sealed class SubAgentsProvider : AIContextProvider
     /// <summary>
     /// Refreshes the status of in-flight tasks in the given state for the specified session.
     /// </summary>
-    private void TryRefreshTaskState(SubAgentState state, SubAgentRuntimeState runtimeState, AgentSession? session)
+    private void TryRefreshTaskState(BackgroundAgentState state, BackgroundAgentRuntimeState runtimeState, AgentSession? session)
     {
         bool changed = false;
-        foreach (SubTaskInfo task in state.Tasks)
+        foreach (BackgroundTaskInfo task in state.Tasks)
         {
-            if (task.Status != SubTaskStatus.Running)
+            if (task.Status != BackgroundTaskStatus.Running)
             {
                 continue;
             }
@@ -169,7 +169,7 @@ public sealed class SubAgentsProvider : AIContextProvider
             if (!runtimeState.InFlightTasks.TryGetValue(task.Id, out Task<AgentResponse>? inFlight))
             {
                 // In-flight reference lost (e.g., after restart/deserialization).
-                task.Status = SubTaskStatus.Lost;
+                task.Status = BackgroundTaskStatus.Lost;
                 changed = true;
                 continue;
             }
@@ -188,32 +188,32 @@ public sealed class SubAgentsProvider : AIContextProvider
     }
 
     /// <summary>
-    /// Finalizes a task by extracting results from the completed Task and updating the SubTaskInfo.
+    /// Finalizes a task by extracting results from the completed Task and updating the BackgroundTaskInfo.
     /// </summary>
-    private static void FinalizeTask(SubTaskInfo taskInfo, Task<AgentResponse> completedTask, SubAgentRuntimeState runtimeState)
+    private static void FinalizeTask(BackgroundTaskInfo taskInfo, Task<AgentResponse> completedTask, BackgroundAgentRuntimeState runtimeState)
     {
         if (completedTask.Status == TaskStatus.RanToCompletion)
         {
-            taskInfo.Status = SubTaskStatus.Completed;
+            taskInfo.Status = BackgroundTaskStatus.Completed;
 #pragma warning disable VSTHRD002 // Avoid problematic synchronous waits — task is already completed
             taskInfo.ResultText = completedTask.Result.Text;
 #pragma warning restore VSTHRD002
         }
         else if (completedTask.IsFaulted)
         {
-            taskInfo.Status = SubTaskStatus.Failed;
+            taskInfo.Status = BackgroundTaskStatus.Failed;
             taskInfo.ErrorText = completedTask.Exception?.InnerException?.Message ?? completedTask.Exception?.Message ?? "Unknown error";
         }
         else if (completedTask.IsCanceled)
         {
-            taskInfo.Status = SubTaskStatus.Failed;
+            taskInfo.Status = BackgroundTaskStatus.Failed;
             taskInfo.ErrorText = "Task was canceled.";
         }
 
         runtimeState.InFlightTasks.Remove(taskInfo.Id);
     }
 
-    private AITool[] CreateTools(SubAgentState state, SubAgentRuntimeState runtimeState, AgentSession? session)
+    private AITool[] CreateTools(BackgroundAgentState state, BackgroundAgentRuntimeState runtimeState, AgentSession? session)
     {
         var serializerOptions = AgentJsonUtilities.DefaultOptions;
 
@@ -221,43 +221,43 @@ public sealed class SubAgentsProvider : AIContextProvider
         [
             AIFunctionFactory.Create(
                 async (
-                    [Description("The name of the sub agent to delegate the task to.")] string agentName,
-                    [Description("The request to pass to the sub agent.")] string input,
+                    [Description("The name of the background agent to delegate the task to.")] string agentName,
+                    [Description("The request to pass to the background agent.")] string input,
                     [Description("A description of the task used to identify the task later.")] string description) =>
                 {
                     if (!this._agents.TryGetValue(agentName, out AIAgent? agent))
                     {
-                        return $"Error: No sub-agent found with name '{agentName}'. Available agents: {string.Join(", ", this._agents.Keys)}";
+                        return $"Error: No background agent found with name '{agentName}'. Available agents: {string.Join(", ", this._agents.Keys)}";
                     }
 
                     int taskId = state.NextTaskId++;
-                    var taskInfo = new SubTaskInfo
+                    var taskInfo = new BackgroundTaskInfo
                     {
                         Id = taskId,
                         AgentName = agentName,
                         Description = description,
-                        Status = SubTaskStatus.Running,
+                        Status = BackgroundTaskStatus.Running,
                     };
                     state.Tasks.Add(taskInfo);
 
-                    // Create a dedicated session for this sub-task so it can be continued later.
+                    // Create a dedicated session for this background task so it can be continued later.
                     AgentSession subSession = await agent.CreateSessionAsync().ConfigureAwait(false);
 
                     // Wrap in Task.Run to fork the ExecutionContext. AIAgent.RunAsync is a non-async
                     // method that synchronously sets the static AsyncLocal CurrentRunContext. Without
-                    // this isolation, the sub-agent's RunAsync would overwrite the outer (calling)
+                    // this isolation, the background agent's RunAsync would overwrite the outer (calling)
                     // agent's CurrentRunContext, corrupting all subsequent tool invocations in the
                     // same FICC batch.
                     runtimeState.InFlightTasks[taskId] = Task.Run(() => agent.RunAsync(input, subSession));
-                    runtimeState.SubTaskSessions[taskId] = subSession;
+                    runtimeState.BackgroundTaskSessions[taskId] = subSession;
 
                     this._sessionState.SaveState(session, state);
-                    return $"Sub-task {taskId} started on agent '{agentName}'.";
+                    return $"Background task {taskId} started on agent '{agentName}'.";
                 },
                 new AIFunctionFactoryOptions
                 {
-                    Name = "SubAgents_StartTask",
-                    Description = "Start a sub-task on a named sub-agent. Returns a confirmation message containing the task ID.",
+                    Name = "BackgroundAgents_StartTask",
+                    Description = "Start a background task on a named background agent. Returns a confirmation message containing the task ID.",
                     SerializerOptions = serializerOptions,
                 }),
 
@@ -287,7 +287,7 @@ public sealed class SubAgentsProvider : AIContextProvider
                         this._sessionState.SaveState(session, state);
 
                         // Check if any of the requested IDs are already complete.
-                        SubTaskInfo? alreadyComplete = state.Tasks.FirstOrDefault(t => taskIds.Contains(t.Id) && t.Status != SubTaskStatus.Running);
+                        BackgroundTaskInfo? alreadyComplete = state.Tasks.FirstOrDefault(t => taskIds.Contains(t.Id) && t.Status != BackgroundTaskStatus.Running);
                         if (alreadyComplete is not null)
                         {
                             return $"Task {alreadyComplete.Id} is not running; current status: {alreadyComplete.Status}.";
@@ -303,7 +303,7 @@ public sealed class SubAgentsProvider : AIContextProvider
                     var completedEntry = waitableTasks.First(t => t.Task == completedTask);
 
                     // Finalize the completed task.
-                    SubTaskInfo? taskInfo = state.Tasks.FirstOrDefault(t => t.Id == completedEntry.Id);
+                    BackgroundTaskInfo? taskInfo = state.Tasks.FirstOrDefault(t => t.Id == completedEntry.Id);
                     if (taskInfo is not null)
                     {
                         FinalizeTask(taskInfo, completedEntry.Task, runtimeState);
@@ -314,8 +314,8 @@ public sealed class SubAgentsProvider : AIContextProvider
                 },
                 new AIFunctionFactoryOptions
                 {
-                    Name = "SubAgents_WaitForFirstCompletion",
-                    Description = "Block until the first of the specified sub-tasks completes. Provide one or more task IDs. Returns a status message containing the ID of the task that completed first.",
+                    Name = "BackgroundAgents_WaitForFirstCompletion",
+                    Description = "Block until the first of the specified background tasks completes. Provide one or more task IDs. Returns a status message containing the ID of the task that completed first.",
                     SerializerOptions = serializerOptions,
                 }),
 
@@ -324,7 +324,7 @@ public sealed class SubAgentsProvider : AIContextProvider
                 {
                     this.TryRefreshTaskState(state, runtimeState, session);
 
-                    SubTaskInfo? taskInfo = state.Tasks.FirstOrDefault(t => t.Id == taskId);
+                    BackgroundTaskInfo? taskInfo = state.Tasks.FirstOrDefault(t => t.Id == taskId);
                     if (taskInfo is null)
                     {
                         return $"Error: No task found with ID {taskId}.";
@@ -332,17 +332,17 @@ public sealed class SubAgentsProvider : AIContextProvider
 
                     return taskInfo.Status switch
                     {
-                        SubTaskStatus.Completed => taskInfo.ResultText ?? "(no output)",
-                        SubTaskStatus.Failed => $"Task failed: {taskInfo.ErrorText ?? "Unknown error"}",
-                        SubTaskStatus.Lost => "Task state was lost (reference unavailable).",
-                        SubTaskStatus.Running => $"Task {taskId} is still running.",
+                        BackgroundTaskStatus.Completed => taskInfo.ResultText ?? "(no output)",
+                        BackgroundTaskStatus.Failed => $"Task failed: {taskInfo.ErrorText ?? "Unknown error"}",
+                        BackgroundTaskStatus.Lost => "Task state was lost (reference unavailable).",
+                        BackgroundTaskStatus.Running => $"Task {taskId} is still running.",
                         _ => $"Task {taskId} has status: {taskInfo.Status}.",
                     };
                 },
                 new AIFunctionFactoryOptions
                 {
-                    Name = "SubAgents_GetTaskResults",
-                    Description = "Get the text output of a sub-task by its ID. Returns the result text if complete, or status information if still running or failed.",
+                    Name = "BackgroundAgents_GetTaskResults",
+                    Description = "Get the text output of a background task by its ID. Returns the result text if complete, or status information if still running or failed.",
                     SerializerOptions = serializerOptions,
                 }),
 
@@ -358,7 +358,7 @@ public sealed class SubAgentsProvider : AIContextProvider
 
                     var sb = new StringBuilder();
                     sb.AppendLine("Tasks:");
-                    foreach (SubTaskInfo task in state.Tasks)
+                    foreach (BackgroundTaskInfo task in state.Tasks)
                     {
                         sb.Append("- Task ").Append(task.Id).Append(" [").Append(task.Status).Append("] (").Append(task.AgentName).Append("): ").AppendLine(task.Description);
                     }
@@ -367,8 +367,8 @@ public sealed class SubAgentsProvider : AIContextProvider
                 },
                 new AIFunctionFactoryOptions
                 {
-                    Name = "SubAgents_GetAllTasks",
-                    Description = "List all sub-tasks with their IDs, statuses, agent names, and descriptions.",
+                    Name = "BackgroundAgents_GetAllTasks",
+                    Description = "List all background tasks with their IDs, statuses, agent names, and descriptions.",
                     SerializerOptions = serializerOptions,
                 }),
 
@@ -377,18 +377,18 @@ public sealed class SubAgentsProvider : AIContextProvider
                 {
                     this.TryRefreshTaskState(state, runtimeState, session);
 
-                    SubTaskInfo? taskInfo = state.Tasks.FirstOrDefault(t => t.Id == taskId);
+                    BackgroundTaskInfo? taskInfo = state.Tasks.FirstOrDefault(t => t.Id == taskId);
                     if (taskInfo is null)
                     {
                         return $"Error: No task found with ID {taskId}.";
                     }
 
-                    if (taskInfo.Status == SubTaskStatus.Lost)
+                    if (taskInfo.Status == BackgroundTaskStatus.Lost)
                     {
                         return $"Error: Task {taskId} cannot be continued because its session was lost (e.g., after a session restore). Start a new task instead.";
                     }
 
-                    if (taskInfo.Status == SubTaskStatus.Running)
+                    if (taskInfo.Status == BackgroundTaskStatus.Running)
                     {
                         return $"Error: Task {taskId} is still running. Wait for it to complete before continuing.";
                     }
@@ -398,17 +398,17 @@ public sealed class SubAgentsProvider : AIContextProvider
                         return $"Error: Agent '{taskInfo.AgentName}' is no longer available.";
                     }
 
-                    if (!runtimeState.SubTaskSessions.TryGetValue(taskId, out AgentSession? subSession))
+                    if (!runtimeState.BackgroundTaskSessions.TryGetValue(taskId, out AgentSession? subSession))
                     {
                         return $"Error: Session for task {taskId} is no longer available.";
                     }
 
                     // Reset task state and start a new run on the existing session.
-                    taskInfo.Status = SubTaskStatus.Running;
+                    taskInfo.Status = BackgroundTaskStatus.Running;
                     taskInfo.ResultText = null;
                     taskInfo.ErrorText = null;
 
-                    // Wrap in Task.Run to isolate the ExecutionContext (see StartSubTask comment).
+                    // Wrap in Task.Run to isolate the ExecutionContext (see StartBackgroundTask comment).
                     runtimeState.InFlightTasks[taskId] = Task.Run(() => agent.RunAsync(text, subSession));
 
                     this._sessionState.SaveState(session, state);
@@ -416,8 +416,8 @@ public sealed class SubAgentsProvider : AIContextProvider
                 },
                 new AIFunctionFactoryOptions
                 {
-                    Name = "SubAgents_ContinueTask",
-                    Description = "Send follow-up input to a completed or failed sub-task to resume its work. The sub-task's session is preserved, so the agent retains conversational context.",
+                    Name = "BackgroundAgents_ContinueTask",
+                    Description = "Send follow-up input to a completed or failed background task to resume its work. The background task's session is preserved, so the agent retains conversational context.",
                     SerializerOptions = serializerOptions,
                 }),
 
@@ -426,13 +426,13 @@ public sealed class SubAgentsProvider : AIContextProvider
                 {
                     this.TryRefreshTaskState(state, runtimeState, session);
 
-                    SubTaskInfo? taskInfo = state.Tasks.FirstOrDefault(t => t.Id == taskId);
+                    BackgroundTaskInfo? taskInfo = state.Tasks.FirstOrDefault(t => t.Id == taskId);
                     if (taskInfo is null)
                     {
                         return $"Error: No task found with ID {taskId}.";
                     }
 
-                    if (taskInfo.Status == SubTaskStatus.Running)
+                    if (taskInfo.Status == BackgroundTaskStatus.Running)
                     {
                         return $"Error: Task {taskId} is still running. Wait for it to complete before clearing.";
                     }
@@ -442,15 +442,15 @@ public sealed class SubAgentsProvider : AIContextProvider
 
                     // Clean up runtime references.
                     runtimeState.InFlightTasks.Remove(taskId);
-                    runtimeState.SubTaskSessions.Remove(taskId);
+                    runtimeState.BackgroundTaskSessions.Remove(taskId);
 
                     this._sessionState.SaveState(session, state);
                     return $"Task {taskId} cleared.";
                 },
                 new AIFunctionFactoryOptions
                 {
-                    Name = "SubAgents_ClearCompletedTask",
-                    Description = "Remove a completed or failed sub-task and release its session to free memory. Use this after retrieving results when you no longer need to continue the task.",
+                    Name = "BackgroundAgents_ClearCompletedTask",
+                    Description = "Remove a completed or failed background task and release its session to free memory. Use this after retrieving results when you no longer need to continue the task.",
                     SerializerOptions = serializerOptions,
                 }),
         ];

dotnet/src/Microsoft.Agents.AI/Harness/BackgroundAgents/BackgroundAgentsProviderOptions.cs

@@ -8,21 +8,21 @@ using Microsoft.Shared.DiagnosticIds;
 namespace Microsoft.Agents.AI;
 
 /// <summary>
-/// Options controlling the behavior of <see cref="SubAgentsProvider"/>.
+/// Options controlling the behavior of <see cref="BackgroundAgentsProvider"/>.
 /// </summary>
 [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
-public sealed class SubAgentsProviderOptions
+public sealed class BackgroundAgentsProviderOptions
 {
     /// <summary>
-    /// Gets or sets custom instructions provided to the agent for using the sub-agent tools.
+    /// Gets or sets custom instructions provided to the agent for using the background agent tools.
     /// </summary>
     /// <remarks>
-    /// Use the <c>{sub_agents}</c> placeholder to allow the provider to inject
-    /// the formatted list of available sub agents.
+    /// Use the <c>{background_agents}</c> placeholder to allow the provider to inject
+    /// the formatted list of available background agents.
     /// </remarks>
     /// <value>
     /// When <see langword="null"/> (the default), the provider uses built-in instructions
-    /// that guide the agent on how to use the sub-agent tools.
+    /// that guide the agent on how to use the background agent tools.
     /// The agent list is always appended after the instructions regardless of this setting.
     /// </value>
     public string? Instructions { get; set; }
@@ -33,7 +33,7 @@ public sealed class SubAgentsProviderOptions
     /// <value>
     /// When <see langword="null"/> (the default), the provider generates a standard list of agent names and descriptions.
     /// When set, this function receives the dictionary of available agents (keyed by name) and should return
-    /// a formatted string describing the available sub-agents.
+    /// a formatted string describing the available background agents.
     /// </value>
     public Func<IReadOnlyDictionary<string, AIAgent>, string>? AgentListBuilder { get; set; }
 }

dotnet/src/Microsoft.Agents.AI/Harness/BackgroundAgents/BackgroundTaskInfo.cs

@@ -7,43 +7,43 @@ using Microsoft.Shared.DiagnosticIds;
 namespace Microsoft.Agents.AI;
 
 /// <summary>
-/// Represents the metadata and result of a sub-task managed by the <see cref="SubAgentsProvider"/>.
+/// Represents the metadata and result of a background task managed by the <see cref="BackgroundAgentsProvider"/>.
 /// </summary>
 [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
-public sealed class SubTaskInfo
+public sealed class BackgroundTaskInfo
 {
     /// <summary>
-    /// Gets or sets the unique identifier for this sub-task.
+    /// Gets or sets the unique identifier for this background task.
     /// </summary>
     [JsonPropertyName("id")]
     public int Id { get; set; }
 
     /// <summary>
-    /// Gets or sets the name of the agent that is executing this sub-task.
+    /// Gets or sets the name of the agent that is executing this background task.
     /// </summary>
     [JsonPropertyName("agentName")]
     public string AgentName { get; set; } = string.Empty;
 
     /// <summary>
-    /// Gets or sets a description of what this sub-task is doing.
+    /// Gets or sets a description of what this background task is doing.
     /// </summary>
     [JsonPropertyName("description")]
     public string Description { get; set; } = string.Empty;
 
     /// <summary>
-    /// Gets or sets the current status of this sub-task.
+    /// Gets or sets the current status of this background task.
     /// </summary>
     [JsonPropertyName("status")]
-    public SubTaskStatus Status { get; set; }
+    public BackgroundTaskStatus Status { get; set; }
 
     /// <summary>
-    /// Gets or sets the text result of the sub-task, populated when the task completes successfully.
+    /// Gets or sets the text result of the background task, populated when the task completes successfully.
     /// </summary>
     [JsonPropertyName("resultText")]
     public string? ResultText { get; set; }
 
     /// <summary>
-    /// Gets or sets the error message if the sub-task failed.
+    /// Gets or sets the error message if the background task failed.
     /// </summary>
     [JsonPropertyName("errorText")]
     public string? ErrorText { get; set; }

dotnet/src/Microsoft.Agents.AI/Harness/BackgroundAgents/BackgroundTaskStatus.cs

@@ -6,28 +6,28 @@ using Microsoft.Shared.DiagnosticIds;
 namespace Microsoft.Agents.AI;
 
 /// <summary>
-/// Represents the status of a sub-task managed by the <see cref="SubAgentsProvider"/>.
+/// Represents the status of a background task managed by the <see cref="BackgroundAgentsProvider"/>.
 /// </summary>
 [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
-public enum SubTaskStatus
+public enum BackgroundTaskStatus
 {
     /// <summary>
-    /// The sub-task is currently running.
+    /// The background task is currently running.
     /// </summary>
     Running,
 
     /// <summary>
-    /// The sub-task completed successfully.
+    /// The background task completed successfully.
     /// </summary>
     Completed,
 
     /// <summary>
-    /// The sub-task failed with an error.
+    /// The background task failed with an error.
     /// </summary>
     Failed,
 
     /// <summary>
-    /// The sub-task's in-flight reference was lost (e.g., after a restart),
+    /// The background task's in-flight reference was lost (e.g., after a restart),
     /// and its final state cannot be determined.
     /// </summary>
     Lost,

dotnet/src/Microsoft.Agents.AI/Harness/FileMemory/FileMemoryProvider.cs

@@ -55,7 +55,7 @@ public sealed class FileMemoryProvider : AIContextProvider, IDisposable
 
         - Use descriptive file names (e.g., "projectarchitecture.md", "userpreferences.md").
         - Include a description when saving a file to help with future discovery.
-        - Before starting new tasks, use FileMemory_ListFiles and FileMemory_SearchFiles to check for relevant existing memories.
+        - Before starting new tasks, use FileMemory_ListFiles and FileMemory_SearchFiles to check for relevant existing memories to avoid duplicate work.
         - Keep memories up-to-date by overwriting files when information changes.
         - When you receive large amounts of data (e.g., downloaded web pages, API responses, research results),
           save them to files if they will be required later, so that they are not lost when older context is compacted or truncated.

dotnet/src/Microsoft.Agents.AI/Harness/Todo/TodoCompleteInput.cs

@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents the input for completing a single todo item via the <see cref="TodoProvider"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+internal sealed class TodoCompleteInput
+{
+    /// <summary>
+    /// Gets or sets the ID of the todo item to mark as complete.
+    /// </summary>
+    [JsonPropertyName("id")]
+    public int Id { get; set; }
+
+    /// <summary>
+    /// Gets or sets the reason describing how or why the item was completed.
+    /// </summary>
+    [JsonPropertyName("reason")]
+    public string Reason { get; set; } = string.Empty;
+}

dotnet/src/Microsoft.Agents.AI/Harness/Todo/TodoProvider.cs

@@ -48,13 +48,13 @@ public sealed class TodoProvider : AIContextProvider, IDisposable
         You have access to a todo list for tracking work items.
         While planning, make sure that you break down complex tasks into manageable todo items and add them to the list.
         Ask questions from the user where clarification is needed to create effective todos.
-        If the user provides feedback on your plan, adjust your todos accordingly by adding new items or removing irrelevant ones.
+        If the user provides feedback on your plan, adjust your todos accordingly by adding new items or removing irrelevant/old ones.
         During execution, use the todo list to keep track of what needs to be done, mark items as complete when finished, and remove any items that are no longer needed.
-        When a user changes the topic or changes their mind, ensure that you update the todo list accordingly by removing irrelevant items or adding new ones as needed.
+        When a user changes the topic or changes their mind, ensure that you update the todo list accordingly by removing irrelevant/old items or adding new ones as needed.
         
         Use these tools to manage your tasks:
         - Use TodoList_Add to break down complex work into trackable items (supports adding one or many at once).
-        - Use TodoList_Complete to mark items as done when finished (supports one or many at once).
+        - Use TodoList_Complete to mark items as done when finished (supports one or many at once). Include a reason describing how the items were completed.
         - Use TodoList_GetRemaining to check what work is still pending.
         - Use TodoList_GetAll to review the full list including completed items.
         - Use TodoList_Remove to remove items that are no longer needed (supports one or many at once).
@@ -235,14 +235,14 @@ public sealed class TodoProvider : AIContextProvider, IDisposable
                 }),
 
             AIFunctionFactory.Create(
-                async (List<int> ids) =>
+                async (List<TodoCompleteInput> items) =>
                 {
                     SemaphoreSlim sessionLock = this.GetSessionLock(session);
                     await sessionLock.WaitAsync().ConfigureAwait(false);
                     try
                     {
                         TodoState state = this._sessionState.GetOrInitializeState(session);
-                        var idSet = new HashSet<int>(ids);
+                        var idSet = new HashSet<int>(items.Select(i => i.Id));
                         int completed = 0;
                         foreach (TodoItem item in state.Items)
                         {
@@ -268,7 +268,7 @@ public sealed class TodoProvider : AIContextProvider, IDisposable
                 new AIFunctionFactoryOptions
                 {
                     Name = "TodoList_Complete",
-                    Description = "Mark one or more todo items as complete by their IDs. Returns the number of items that were found and marked complete.",
+                    Description = "Mark one or more todo items as complete. Each entry has an ID and a reason describing how/why the item was completed. Returns the number of items that were found and marked complete.",
                     SerializerOptions = serializerOptions,
                 }),
 

dotnet/tests/Foundry.Hosting.IntegrationTests.TestContainer/Program.cs

@@ -7,6 +7,7 @@ using Azure.Identity;
 using Azure.Search.Documents;
 using Azure.Search.Documents.Models;
 using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry;
 using Microsoft.Agents.AI.Foundry.Hosting;
 using Microsoft.Extensions.AI;
 
@@ -34,6 +35,7 @@ AIAgent agent = scenario switch
     "tool-calling-approval" => CreateToolCallingApprovalAgent(projectClient, deployment),
     "mcp-toolbox" => CreateMcpToolboxAgent(projectClient, deployment),
     "custom-storage" => CreateCustomStorageAgent(projectClient, deployment),
+    "memory" => await CreateMemoryAgentAsync(projectClient, deployment).ConfigureAwait(false),
     "azure-search-rag" => CreateAzureSearchRagAgent(projectClient, deployment),
     "session-files" => CreateSessionFilesAgent(projectClient, deployment),
     _ => throw new InvalidOperationException($"Unknown IT_SCENARIO '{scenario}'.")
@@ -179,6 +181,34 @@ static AIAgent CreateSessionFilesAgent(AIProjectClient client, string deployment
             AIFunctionFactory.Create(ReadFile)
         ]);
 
+// Memory scenario. The agent uses FoundryMemoryProvider scoped per user via the
+// HostedSessionContext that the hosting layer applies from the platform isolation headers.
+// In production the platform sets the headers; here we rely on the default
+// PlatformHostedSessionIsolationKeyProvider that AgentFrameworkResponseHandler resolves.
+static async Task<AIAgent> CreateMemoryAgentAsync(AIProjectClient client, string deployment)
+{
+    var embedding = Environment.GetEnvironmentVariable("AZURE_AI_EMBEDDING_DEPLOYMENT_NAME") ?? "text-embedding-ada-002";
+    var memoryStoreName = Environment.GetEnvironmentVariable("IT_MEMORY_STORE_ID") ?? "it-memory-store";
+
+    var memoryProvider = new FoundryMemoryProvider(
+        client,
+        memoryStoreName,
+        stateInitializer: HostedFoundryMemoryProviderScopes.PerUser());
+
+    await memoryProvider.EnsureMemoryStoreCreatedAsync(deployment, embedding, "Memory store for hosted-memory IT scenario.").ConfigureAwait(false);
+
+    return client.AsAIAgent(new ChatClientAgentOptions
+    {
+        Name = "memory-agent",
+        ChatOptions = new ChatOptions
+        {
+            ModelId = deployment,
+            Instructions = "You are a friendly travel assistant. Use known memories about the user when responding, and do not invent details."
+        },
+        AIContextProviders = [memoryProvider]
+    });
+}
+
 [Description("Returns the current UTC date and time as an ISO 8601 string.")]
 static string GetUtcNow() => DateTime.UtcNow.ToString("o");
 

dotnet/tests/Foundry.Hosting.IntegrationTests/Fixtures/MemoryHostedAgentFixture.cs

@@ -0,0 +1,28 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+
+namespace Foundry.Hosting.IntegrationTests.Fixtures;
+
+/// <summary>
+/// Provisions a hosted agent that runs the test container in <c>IT_SCENARIO=memory</c> mode.
+/// Used by tests that exercise <see cref="Microsoft.Agents.AI.Foundry.FoundryMemoryProvider"/>
+/// running inside the Foundry hosted agent. The memory store name is randomised per fixture
+/// instance so concurrent test runs do not share state.
+/// </summary>
+public sealed class MemoryHostedAgentFixture : HostedAgentFixture
+{
+    protected override string ScenarioName => "memory";
+
+    /// <summary>
+    /// Memory store name passed to the test container via <c>IT_MEMORY_STORE_ID</c> so that each
+    /// fixture instance gets a fresh, isolated bucket of memories.
+    /// </summary>
+    public string MemoryStoreId { get; } = $"it-memory-{Guid.NewGuid():N}";
+
+    protected override void ConfigureEnvironment(IDictionary<string, string> environment)
+    {
+        environment["IT_MEMORY_STORE_ID"] = this.MemoryStoreId;
+    }
+}

dotnet/tests/Foundry.Hosting.IntegrationTests/Foundry.Hosting.IntegrationTests.csproj

@@ -20,7 +20,7 @@
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.AI.Projects" />
     <PackageReference Include="Azure.Identity" />
     <PackageReference Include="Azure.Search.Documents" />
     <PackageReference Include="Microsoft.Extensions.AI" />

dotnet/tests/Foundry.Hosting.IntegrationTests/MemoryHostedAgentTests.cs

@@ -0,0 +1,79 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Threading.Tasks;
+using Foundry.Hosting.IntegrationTests.Fixtures;
+using Microsoft.Agents.AI;
+
+#pragma warning disable OPENAI001 // Experimental Responses API surfaces
+
+namespace Foundry.Hosting.IntegrationTests;
+
+/// <summary>
+/// Validates the Hosted-MemoryAgent end-to-end against a deployed test container running the
+/// <c>IT_SCENARIO=memory</c> scenario. Asserts that <see cref="Microsoft.Agents.AI.Foundry.FoundryMemoryProvider"/>
+/// scoped via <see cref="Microsoft.Agents.AI.Foundry.Hosting.HostedSessionContext"/> recalls user
+/// preferences across multiple turns of a conversation.
+/// </summary>
+[Trait("Category", "FoundryHostedAgents")]
+public sealed class MemoryHostedAgentTests(MemoryHostedAgentFixture fixture) : IClassFixture<MemoryHostedAgentFixture>
+{
+    private readonly MemoryHostedAgentFixture _fixture = fixture;
+
+    [Fact]
+    public async Task Memory_RecallsAcrossTurnsAsync()
+    {
+        // Arrange
+        var agent = this._fixture.Agent;
+        var session = await agent.CreateSessionAsync();
+
+        // Act: teach the agent two pieces of information about the user.
+        var first = await agent.RunAsync("My name is Taylor and I am planning a hiking trip to Patagonia in November.", session);
+        Assert.False(string.IsNullOrWhiteSpace(first.Text));
+
+        var second = await agent.RunAsync("I am travelling with my sister and we love finding scenic viewpoints.", session);
+        Assert.False(string.IsNullOrWhiteSpace(second.Text));
+
+        // FoundryMemoryProvider defaults to UpdateDelay=0 (immediate trigger). Server-side ingestion
+        // typically completes within ~3 seconds; allow a small margin.
+        await Task.Delay(TimeSpan.FromSeconds(5));
+
+        var recall = await agent.RunAsync("What do you already know about my upcoming trip?", session);
+
+        // Assert
+        Assert.Contains("Patagonia", recall.Text, StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Fact(Skip = "Foundry Memory write propagation is eventually consistent and the in-container WhenUpdatesCompletedAsync flush hook is not callable from the test process; this scenario is exercised manually via the sample's smoke.ps1.")]
+    public async Task Memory_PersistsAcrossSessionsForSameUserAsync()
+    {
+        // Arrange: drive a session that establishes some user-private memory. Foundry Memory
+        // extracts memories more reliably from multi-turn conversations than from a single
+        // imperative utterance, so mirror the sample's two-turn teaching pattern.
+        var agent = this._fixture.Agent;
+        var teachingSession = await agent.CreateSessionAsync();
+        await agent.RunAsync("My preferred airline is Iberia and I always fly business class.", teachingSession);
+        await agent.RunAsync("I also prefer aisle seats whenever they are available.", teachingSession);
+
+        // FoundryMemoryProvider defaults to UpdateDelay=0 (immediate trigger). Server-side
+        // ingestion typically completes within ~3 seconds; poll a fresh-session recall a few
+        // times before failing so the test does not flake on cold caches.
+        AgentResponse recall = null!;
+        const int MaxAttempts = 6;
+        for (var attempt = 1; attempt <= MaxAttempts; attempt++)
+        {
+            await Task.Delay(TimeSpan.FromSeconds(5));
+
+            var freshSession = await agent.CreateSessionAsync();
+            recall = await agent.RunAsync("Which airline do I prefer? Reply with just the airline name.", freshSession);
+
+            if (recall.Text.Contains("Iberia", StringComparison.OrdinalIgnoreCase))
+            {
+                break;
+            }
+        }
+
+        // Assert
+        Assert.Contains("Iberia", recall.Text, StringComparison.OrdinalIgnoreCase);
+    }
+}