10 Commits

• .NET: Promote FoundryChatClient to public, add file/vector-store helpers and ToPromptAgentAsync converter (#5940)

  * Consolidate Foundry chat client decorators into FoundryChatClient
  
  - Replace AzureAIProjectChatClient and AzureAIProjectResponsesChatClient with a single internal sealed FoundryChatClient that covers three modes (pure responses, server-side agent reference, hosted agent endpoint).
  - Rename AzureAIProjectChatClientExtensions to AIProjectClientExtensions to reflect that it extends AIProjectClient.
  - All four AsAIAgent extension overloads and both FoundryAgent constructors now construct FoundryChatClient internally so the microsoft.foundry telemetry tag is uniform across paths.
  - Introduce AgentFrameworkUserAgentPolicy that stamps agent-framework-dotnet/{version} on outbound requests, mirroring the Python agent-framework-python/{version} contract.
  - Delete the Foundry-local MeaiUserAgentPolicy duplicate; rely on MEAI 10.5.1 to stamp MEAI/{version} automatically.
  - HostedAgentUserAgentPolicy keeps the combined foundry-hosting/agent-framework-dotnet/{version} segment (Python parity) and upgrades the bare segment in place to avoid duplication.
  - Tests reorganized: FoundryChatClientTests, AIProjectClientExtensionsTests, AgentFrameworkUserAgentPolicyTests, MeaiAutoUserAgentVerificationTests, plus in-place upgrade unit tests in HostedOutboundUserAgentTests.
  
  * Promote FoundryChatClient to public; add file/vector-store helpers and ToPromptAgentAsync converter
  
  - Promote FoundryChatClient from internal sealed to public sealed for Python parity, so .NET developers can hold and pass a FoundryChatClient directly the way Python developers do.
  - Mode 3 (hosted agent endpoint) now materializes an AIProjectClient from the parsed project root, making GetService<AIProjectClient>() non-null across all three construction modes. This eliminates the per-mode asymmetry that previously hid project-level helpers from agents constructed via an agent endpoint URL.
  - Add four new instance methods on FoundryChatClient mirroring Python's spec: UploadFileAsync, DeleteFileAsync, CreateVectorStoreAsync (bundles upload + create + wait), DeleteVectorStoreAsync. Single overload each, path-only inputs to start; additional overloads can be added later without breaking callers. All are Experimental, consistent with the rest of the Foundry package.
  - Add ToPromptAgentAsync extension methods on ChatClientAgent and FoundryAgent for the agent-to-prompt-agent converter described in the Foundry spec. Mode 1 (responses API) synthesizes a DeclarativeAgentDefinition from the agent's ChatOptions; mode 2 (server-side agent reference, version, or record) returns the cached or freshly fetched Definition; mode 3 throws InvalidOperationException because no local definition exists to convert.
  - Strict AITool to ResponseTool mapping for mode 1: AIFunction becomes CreateFunctionTool with the function's JSON schema; AITool instances that wrap a ResponseTool unwrap via GetService(typeof(ResponseTool)); anything else throws InvalidOperationException naming the offending tool type. Matches the Python spec's unsupported-tools-raise-ValueError contract.
  - New unit tests: FoundryChatClientVectorStoreTests (22 tests covering all four helpers across the three FoundryChatClient construction modes plus validation and cancellation), FoundryPromptAgentConverterTests (16 tests covering both extension entry points across mode 1 synthesis, mode 2 cached and fetched paths, all failure modes, and a Python-parity guard asserting both extensions produce equivalent definitions for equivalent inputs), plus four new tests in FoundryChatClientTests for the mode 3 AIProjectClient materialization.
  
  * Stop building duplicate ProjectOpenAIClient in FoundryAgent agent-endpoint ctor
  
  After Plan #2's mode-3 AIProjectClient materialization, the inner FoundryChatClient already exposes a project-level AIProjectClient (via GetService) that internally provides the project-level ProjectOpenAIClient via GetProjectOpenAIClient(). FoundryAgent's agent-endpoint constructor was still independently constructing a second project-level ProjectOpenAIClient via the now-redundant CreateProjectLevelOpenAIClientFromAgentEndpoint helper — two handles to the same logical resource.
  
  Refactor: the agent-endpoint constructor now reads the inner FoundryChatClient's materialized AIProjectClient via base.GetService(typeof(AIProjectClient)) and derives the project-level ProjectOpenAIClient from it. The dead helper on both FoundryAgent (private static wrapper) and FoundryChatClient (the actual implementation) is removed. The user-supplied per-agent ClientPipelineOptions primitives (Transport, RetryPolicy, NetworkTimeout, UserAgentApplicationId) are propagated into the materialized AIProjectClientOptions so test-injected transports and explicit retry / timeout / user-agent settings reach the project-level pipeline — preserving the behavior the dead helper used to provide.
  
  Updated AgentEndpointConstructor_GetServiceAIProjectClient_ReturnsNull to its now-correct counterpart AgentEndpointConstructor_GetServiceAIProjectClient_ReturnsNonNull, since after Plan #2 the agent-endpoint ctor surfaces a non-null AIProjectClient (per user direction in Plan #2 Q2).
  
  * Strip duplicated AIProjectClient/ProjectOpenAIClient state from FoundryAgent
  
  Both _aiProjectClient and _projectOpenAIClient fields on FoundryAgent were redundant:
  
  - _aiProjectClient: FoundryAgent's GetService<AIProjectClient> override returned this field, but DelegatingAIAgent.GetService → ChatClientAgent.GetService → FoundryChatClient.GetService<AIProjectClient> already returns the same instance through the delegating chain. Field + override are pure duplication.
  
  - _projectOpenAIClient: only used by FoundryAgent's own GetService<ProjectOpenAIClient> override and by CreateConversationSessionAsync. Per user direction, ProjectOpenAIClient is no longer exposed via GetService on either FoundryChatClient or FoundryAgent — callers retrieve it from the AIProjectClient themselves (aiProjectClient.GetProjectOpenAIClient()) the same way the framework does internally. This eliminates the mode-3 asymmetry where the chat client's stored ProjectOpenAIClient was per-agent (URL /agents/{name}/endpoint/protocols/openai) while the agent's was project-level.
  
  Refactor:
  - Delete both fields on FoundryAgent and the GetService override.
  - Delete the ProjectOpenAIClient branch from FoundryChatClient.GetService.
  - CreateConversationSessionAsync now resolves AIProjectClient at call time via this.GetService<AIProjectClient>() and derives the conversations client from it.
  - Update FoundryChatClient tests that asserted on GetService<ProjectOpenAIClient> to assert Null (deliberate removal).
  - Update FoundryAgent tests AgentEndpointConstructor_GetServiceProjectOpenAIClient_ReturnsNonNull and ProjectEndpointConstructor_GetServiceProjectOpenAIClient_ReturnsNonNull to ...ReturnsNull, and rewrite AgentEndpointConstructor_PropagatesUserAgentApplicationId_ToProjectLevelClient to look up AIProjectClient instead.
  
  No production code (only tests) referenced GetService<ProjectOpenAIClient>, so this is a safe surface reduction. Net: 30 insertions, 61 deletions; FoundryAgent shrinks to a pure delegator with only the two convenience methods (CreateSessionAsync, CreateConversationSessionAsync) on top of the delegating chain.
  
  * Rename FoundryChatClient.HostedAgentName to AgentName and populate it for mode 2
  
  The previous name implied a mode 3 only property tied to the hosted-agent endpoint URL. Today only hosted endpoints surface this name, but conceptually an agent name exists for every server-side agent the client talks to. Renaming to AgentName makes the property general-purpose and ready for future modes where the same chat client may target other server-side agent shapes that are not necessarily 'hosted'.
  
  Mode 2 (server-side agent reference) now mirrors AgentReference.Name into AgentName so callers have a uniform handle regardless of construction mode:
  
  * Mode 1 (pure responses): AgentName is null. There is no agent.
  * Mode 2 (AgentReference): AgentName == AgentReference.Name.
  * Mode 3 (agent endpoint URL): AgentName is parsed from the URL segment as before.
  
  Converter discriminator update: FoundryPromptAgentConverter previously used 'HostedAgentName is not null' to detect mode 3 and reject it. Now that mode 2 also populates AgentName, the mode 3 guard moves to the end of the resolution chain and uses the unambiguous 'AgentName is set AND no AgentReference exists' test. The user-visible error message and behavior are preserved.
  
  Dead-state cleanup spotted during format verify:
  
  * IDE0052 surfaced that FoundryChatClient._projectOpenAIClient is never read since the prior refactor stopped exposing ProjectOpenAIClient via GetService and rewired CreateConversationSessionAsync to resolve the AIProjectClient through the delegating chain. The field is deleted and its three ctor assignments removed.
  * HostedAgentEndpointInner.PerAgentClient only existed to plumb the per-agent ProjectOpenAIClient into that now-deleted field, so the property and its ctor parameter are removed. The local 'perAgentClient' variable inside BuildHostedAgentEndpointInner is still needed to derive the inner IChatClient, but no longer escapes the helper.
  
  Tests:
  
  * Mode1_PureResponses_ReturnsNullForAgentSpecificServices now also asserts AgentName is null.
  * New Mode2_AgentReference_PopulatesAgentNameFromAgentReference asserts the mode 2 mirror.
  * Mode3_HostedAgentEndpoint_ParsesAgentNameFromUrl renamed assertion target HostedAgentName to AgentName.
  
  Verification: 335/335 net10.0, 273/273 net472 Foundry unit; 229/229 Foundry.Hosting unit; format-verify (WSL2 + Docker mcr.microsoft.com/dotnet/sdk:10.0) clean on Microsoft.Agents.AI.Foundry.
  
  * Adopt canonical mode names: Responses Agent, Prompt Agent, Agent Endpoint
  
  Three FoundryChatClient construction modes now have one canonical noun used everywhere.
  
  * Responses Agent (Mode 1): inline ChatClientAgent, project-level Responses API, no server-side def.
  * Prompt Agent (Mode 2): server-side ProjectsAgentDefinition invoked by AgentReference.
  * Agent Endpoint (Mode 3): per-agent URL /agents/{name}/endpoint/protocols/openai. Hosted-or-not.
  
  'Hosted' stays the kind of agent (Microsoft.Agents.AI.Foundry.Hosting). Not synonym of Mode 3.
  
  Rings:
  1. XML docs + error messages use canonical names. en-GB to en-US: centralises, synthesise.
  2. HostedAgentEndpointInner -> AgentEndpointInner, BuildHostedAgentEndpointInner -> BuildAgentEndpointInner.
  3. Tests: Mode1_PureResponses_* -> Mode1_ResponsesAgent_*, Mode2_AgentReference_* -> Mode2_PromptAgent_*, Mode3_HostedAgentEndpoint_* -> Mode3_AgentEndpoint_*.
  
  Pure rename. No behavior change. 335/335 net10 + 273/273 net472 unit, format clean.
  
  * Address PR #5940 design feedback (Q-A through Q-F)
  
  Q-A: poll vector store til status leaves InProgress before return. Exp backoff 250ms-2s. Honor cancel.
  Q-B: try/catch upload loop. Mid-fail = best-effort DeleteFileAsync on already-uploaded ids. Swallow cleanup errors.
  Q-C: pinned AgentReference.Version uses GetAgentVersionAsync. Empty/whitespace/'latest' = GetLatest path.
  Q-D: HostedAgentUserAgentPolicy detects existing combined 'foundry-hosting/...' segment. No double prefix.
  Q-E: mode-3 vector-store test uses fake transport. No DNS to example.com.
  Q-F: no shim. Class always [Experimental] (since 8015e00f5, before dotnet-1.0.0). No compat contract. Callers rename to AIProjectClientExtensions.
  
  Rebase onto origin/main reconciliation: aad20c2b3 added public AsAIAgent(this AIProjectClient, Uri agentEndpoint, ...) extension that calls an internal FoundryAgent(AIProjectClient, Uri, ...) ctor. Reintroduced that ctor + a new FoundryChatClient(AIProjectClient, Uri, ProjectOpenAIClientOptions?) overload that reuses the supplied AIProjectClient's pipeline (via GetProjectResponsesClientForAgentEndpoint) instead of stamping a fresh credential.
  
  Verified: 346/346 net10 + 284/284 net472 Foundry unit, 230/230 Foundry.Hosting unit, format clean.
  
  * Add FoundryAgent helper extensions: UploadFile/DeleteFile/CreateVectorStore/DeleteVectorStore
  
  4 thin forwarders on FoundryAgent that route to the inner FoundryChatClient's helpers via agent.GetService<FoundryChatClient>().X(). Live in existing FoundryAgentExtensions.cs alongside ToPromptAgentAsync.
  
  Throws InvalidOperationException when agent does not expose a FoundryChatClient via GetService (same pattern as ToPromptAgentAsync).
  
  Unit tests: FoundryAgentExtensionsTests covers all 4 forwarders + null-agent ArgumentNullException for each. 8 new tests, 354/354 net10 + 292/292 net472.
  
  Integration tests: parallel FoundryAgentExtensionsTests under Foundry.IntegrationTests mirrors the existing CreateAgent_CreatesAgentWithVectorStoresAsync shape (upload -> create vector store -> FileSearch tool answers question -> cleanup), but routes every helper call through the new FoundryAgent extensions. 4 new IT tests, all verified pass live against the real Foundry project (12-30s each). Skipped by default like the existing vector-store IT.
  
  * Address Sergey's PR review comments
  
  #1 (FoundryAgent.cs:139): drop unused aiProjectClient param from internal FoundryAgent(AIProjectClient, ChatClientAgent) ctor. Was discarded after null-check. Inner FoundryChatClient already surfaces AIProjectClient via GetService. 3 call sites in AIProjectClientExtensions updated.
  
  #2 (FoundryChatClient.cs:376): add pollingTimeout param to CreateVectorStoreAsync. Defaults to 5 min, configurable, Timeout.InfiniteTimeSpan disables. Throws TimeoutException with vector store id and elapsed seconds when bound exceeded. CancellationToken still wins. New unit test PollingTimeout_ThrowsTimeoutExceptionAsync. FoundryAgentExtensions forwarder updated to plumb the new param.
  
  Verified: 355/355 net10 + 293/293 net472 Foundry unit, 230/230 Foundry.Hosting unit, format clean.

  Roger Barreto · 2026-05-21 10:05:58 +00:00
  a12cc3878e
• .NET: Add Hosted-MemoryAgent sample with isolation key plumbing (#5692) (#5702)

  * .NET: Add Hosted-MemoryAgent sample with isolation key plumbing (#5692)
  
  Adds HostedSessionContext + HostedSessionIsolationKeyProvider in Microsoft.Agents.AI.Foundry.Hosting so AIContextProviders (notably FoundryMemoryProvider) can scope per user via the platform's x-agent-user-isolation-key / x-agent-chat-isolation-key headers.
  
  - New types: HostedSessionContext (sealed), HostedSessionContextExtensions (public Get, internal Set), abstract HostedSessionIsolationKeyProvider (async), internal PlatformHostedSessionIsolationKeyProvider mapping ResponseContext.Isolation.
  
  - AgentFrameworkResponseHandler now resolves the provider, tags fresh sessions, and validates resumed sessions against the live request (strict 403 'Hosted session identity context mismatch' on any mismatch; 500 on null keys).
  
  - New shared sample project Hosted_Shared_Contributor_Setup hosts DevTemporaryTokenCredential and DevTemporaryLocalSessionIsolationKeyProvider plus AddDevTemporaryLocalContributorSetup. All 9 existing responses samples migrated to consume it so local runs keep working under the strict isolation contract.
  
  - New Hosted-MemoryAgent sample: travel assistant wired through FoundryMemoryProvider with stateInitializer reading session.GetHostedContext().UserId. Includes Dockerfile, smoke.ps1, agent.yaml/manifest.
  
  - New IT scenario 'memory' in Foundry.Hosting.IntegrationTests + MemoryHostedAgentFixture + MemoryHostedAgentTests. Verified end to end against the tao Foundry project.
  
  - ADR 0026 captures the design tree.
  
  * Address PR review feedback
  
  - Dockerfile: add header noting it targets NuGet builds; contributors must use Dockerfile.contributor for ProjectReference source builds.
  
  - PlatformHostedSessionIsolationKeyProvider: doc said 'returns context with empty values'; corrected to 'returns null' which the handler treats as 500.
  
  - FakeHostedSessionIsolationKeyProvider: doc clarifies that null configurations are allowed for testing the handler error path.
  
  - HostedSessionContextExtensions.SetHostedContext: enforce write-once with InvalidOperationException; doc + xml exception updated.
  
  - AgentFrameworkResponseHandler: cache PlatformHostedSessionIsolationKeyProvider as static readonly to avoid per-request allocation.
  
  - MemoryHostedAgentTests: tighten waits from 20s to 5s (FoundryMemoryProvider defaults UpdateDelay=0; ingestion ~3s).
  
  - Sample Program.cs imports reordered to satisfy IDE0005.
  
  * Add HostedFoundryMemoryProviderScopes built-in helpers (#5692)
  
  Addresses review feedback from @lokitoth on Hosted-MemoryAgent/Program.cs:54.
  
  - New HostedFoundryMemoryProviderScopes static class with PerUser, PerChat, PerUserAndChat factories returning Func<AgentSession?, FoundryMemoryProvider.State>.
  
  - All helpers throw InvalidOperationException when GetHostedContext() is null, with a message pointing at writing a custom stateInitializer for non-hosted scenarios.
  
  - New HostedFoundryMemoryScope enum and AddHostedFoundryMemoryProvider DI extension (two overloads: explicit AIProjectClient and DI-resolved). Singleton lifetime. Default scope = PerUser.
  
  - Hosted-MemoryAgent sample and the memory IT scenario container both swap their inline lambdas for HostedFoundryMemoryProviderScopes.PerUser().
  
  - 14 new unit tests (241/241 hosting unit tests pass).
  
  * Replace HostedFoundryMemoryScope enum with Func<...> parameter (#5692)
  
  Address PR review feedback from @westey-m: enums are a breaking-change hazard when extended, and the enum was redundant with the existing HostedFoundryMemoryProviderScopes static class.
  
  - Delete HostedFoundryMemoryScope.cs.
  
  - AddHostedFoundryMemoryProvider DI extensions now take Func<AgentSession?, FoundryMemoryProvider.State>? stateInitializer = null. When null, default to HostedFoundryMemoryProviderScopes.PerUser().
  
  - Callers pick a built-in helper (PerUser/PerChat/PerUserAndChat) or pass a custom delegate. New built-ins are a single static method addition with zero impact on existing callers.
  
  - Tests updated; 244/244 hosting unit tests pass.
  
  * Fix isolation context resume for externally-created conversations (#5692)
  
  Branch on the session's existing hosted-context (not on conversation_id presence) so a conversation provisioned externally (e.g. via conversations.CreateProjectConversationAsync) is treated as fresh on first hosted-agent request and stamped, rather than rejected with 403 hosted_session_identity_mismatch. Strict equality is preserved on real resume of an already-stamped session.
  
  Also tighten dotnet/global.json to version 10.0.204 + rollForward latestPatch so local builds match the CI Docker image SDK and avoid 10.0.300 dotnet format stripping required usings.
  
  * Revert global.json SDK pin to upstream (#5692)
  
  The 10.0.204 + latestPatch pin from the previous commit broke the dotnet-format CI job (hostfxr_resolve_sdk2 could not find a compatible SDK in the mcr.microsoft.com/dotnet/sdk:10.0 image). Restore upstream 10.0.200 + minor; local Release builds with SDK 10.0.300 should set GITHUB_ACTIONS=true to bypass the auto-format-on-build target.

  Roger Barreto · 2026-05-15 05:42:12 +00:00
  ad95f2f2fa
• .NET: Remove Foundry Toolbox server-side tools support (#5753)

  * .NET: Remove Foundry Toolbox server-side tools support
  
  Mirrors the Python cleanup in microsoft/agent-framework#5671. Passing
  toolbox tools as server-side Responses tools is not the experience we
  want to support; the hosted-agent MCP toolbox path (HostedMcpToolboxAITool
  + FoundryToolboxService) remains the supported way to consume Foundry
  Toolboxes.
  
  Removed:
  - FoundryToolbox static class (GetToolboxVersionAsync / GetToolsAsync /
    ToAITools / SanitizeAndConvert)
  - AIProjectClient.GetToolboxToolsAsync extension
  - Agent_Step25_ToolboxServerSideTools sample (+ slnx entry)
  - FoundryToolboxTests, TestDataUtil, HttpHandlerAssert, and the toolbox
    JSON fixtures only those tests referenced
  - ToolboxHostedAgentTests and ToolboxHostedAgentFixture; the "toolbox"
    switch arm + CreateToolboxAgent helper in TestContainer; matching
    README scenario row and bootstrap script entry
  
  Kept (MCP path, unchanged):
  - HostedMcpToolboxAITool, FoundryAITool.CreateHostedMcpToolbox,
    FoundryAIToolExtensions.CreateHostedMcpToolbox(ToolboxRecord/Version)
  - FoundryToolboxService, AddFoundryToolboxes, marker injection in
    AgentFrameworkResponseHandler, InputConverter.ReadMcpToolboxMarkers
  - Hosted-Toolbox sample, McpToolbox* tests, FoundryToolboxServiceTests
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * .NET: Add Foundry Toolbox MCP sample (Agent_Step25_FoundryToolboxMcp)
  
  Adds a non-hosted-agent equivalent of the Python foundry_chat_client_with_toolbox.py sample. The agent connects to a Foundry Toolbox's MCP endpoint via Streamable HTTP, injects a fresh Azure AI bearer token on every request, and discovers the toolbox's tools at runtime via McpClient.ListToolsAsync.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * .NET: Tighten Agent_Step25_FoundryToolboxMcp README/Program comments
  
  Drop 'non-hosted agent' framing from README (this sample isn't related to hosted agents) and remove narrative comparison to server-side tools from the Program.cs header comment.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Drop python sample reference from Agent_Step25 README
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Drop incorrect .NET 10 prereq from Agent_Step25 README
  
  Toolboxes don't require .NET 10 (Microsoft.Agents.AI.Foundry targets net8.0+); the parent AgentsWithFoundry README already lists the sample SDK prereq.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Fix Toolsets api-version in Agent_Step25 example endpoint
  
  Use 2025-05-01-preview to match FoundryToolboxOptions.ApiVersion. The placeholder 'v1' is not accepted by the Toolsets endpoint.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  ---------
  
  Co-authored-by: alliscode <bentho@microsoft.com>
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

  Ben Thomas · 2026-05-11 22:05:14 +00:00
  9199c84d42
• .NET: Update FoundryAgent to address HostedAgents strict URL routing (#5677)

  * .NET: Foundry agent-endpoint constructor uses ProjectOpenAIClient directly to fix hosted-agent URL routing
  
  Fixes the experimental FoundryAgent(Uri agentEndpoint, AuthenticationTokenProvider, ...)
  constructor so it actually works against Foundry hosted agents.
  
  The previous implementation routed through AzureAIProjectChatClient, which
  internally called aiProjectClient.GetProjectOpenAIClient().GetProjectResponsesClientForAgent(...).
  For an agent-endpoint URL of the canonical shape
  
    https://<host>/api/projects/<project>/agents/<agentName>/endpoint/protocols/openai
  
  the chain produced
  
    POST https://<host>/api/projects/<project>/openai/v1/responses
  
  (project-level path, no /agents/ segment). The Foundry service rejects this with
  HTTP 400 "Hosted agents can only be called through the agent endpoint:
  .../agents/<agentName>/endpoint/protocols/openai/responses".
  
  The constructor also extracted the agent name via
  agentEndpoint.Segments[^1].TrimEnd('/'), which returns "openai" (the last segment),
  not the agent name.
  
  What changed
  - Public ctor signature: clientOptions parameter type changed from
    AIProjectClientOptions? to ProjectOpenAIClientOptions?. The constructor is
    fundamentally building a ProjectOpenAIClient; accepting AIProjectClientOptions
    was a leaky abstraction whose translation silently dropped any pipeline
    policies the caller added via AddPolicy(...). With the direct type, caller
    policies pass through to the per-agent traffic verbatim.
  - Per-agent client construction: `new ProjectOpenAIClient(BearerTokenPolicy, ProjectOpenAIClientOptions)`
    with Endpoint and AgentName set, then `GetProjectResponsesClient().AsIChatClient()`.
    The SDK auto-appends ?api-version=v1 when AgentName is set.
  - New private static ParseAgentEndpoint helper: single source of truth for both
    agent-name extraction and project-root derivation. Tolerates trailing slash,
    case variants on /agents/ and the suffix segment, strips query/fragment, and
    throws ArgumentException with paramName=nameof(agentEndpoint) for malformed input.
  - Project-level client (used by CreateConversationSessionAsync) is built fresh
    from the derived project root with primitive properties copied
    (RetryPolicy/NetworkTimeout/Transport/UserAgentApplicationId) plus MEAI UA.
  - New GetService<ProjectOpenAIClient>() entry alongside the existing
    GetService<AIProjectClient>() (the latter returns null in agent-endpoint mode
    since no AIProjectClient is constructed on that path).
  - Endpoint and AgentName on caller-supplied ProjectOpenAIClientOptions are
    overridden by values derived from agentEndpoint.
  
  Compatibility
  - FoundryAgent is [Experimental(OPENAI001)]. No GA surface touched. The Foundry
    project does not maintain PublicAPI.*.txt baselines so there is no shipped
    baseline to update.
  - The Microsoft.Agents.AI.Foundry csproj pins
    Azure.AI.Projects to VersionOverride 2.1.0-beta.1 (matching what the IT and
    hosting projects already use); the central pin in Directory.Packages.props
    stays at 2.0.0.
  - WireClientHeaders from PR #5652 is invoked on the agent-endpoint path so
    per-call x-client-* headers behave identically across both ctors.
  
  Tests
  - 23 new unit tests in FoundryAgentTests.cs:
    - 12 for the agent-endpoint constructor (URL routing for non-streaming and
      streaming, conversations URL shape, MEAI UA stamping, caller-policy
      passthrough on the per-agent pipeline, Endpoint/AgentName override
      semantics, GetService matrix, ProjectOpenAIClient propagation,
      UserAgentApplicationId propagation, null-arg validation, ID/Name slug)
    - 9 for ParseAgentEndpoint (standard shape, trailing slash, casing,
      sovereign-cloud host without /api/projects/ literal prefix, special chars
      in agent name, query/fragment stripping, three negative cases)
    - 2 null-arg tests for the public ctor
  - All 250 Microsoft.Agents.AI.Foundry.UnitTests pass (was 221 baseline plus
    29 from PR #5652 plus 23 new in this PR equals 273; pre-existing tests
    collapsed by the rebase merge keep the total at 250).
  - All 225 Microsoft.Agents.AI.Foundry.Hosting.UnitTests pass; no behavioral
    change to the hosting layer.
  - dotnet build clean across net8/9/10/netstandard2.0/net472 with
    TreatWarningsAsErrors=true.
  - dotnet format --verify-no-changes clean for the touched src and test projects.
  
  * .NET: Bump central Azure.AI.Projects pin to 2.1.0-beta.1 and flip Microsoft.Agents.AI.Foundry to preview
  
  Required to fix the NU1109 downgrade chain that broke CI on the agent-endpoint
  constructor rewire (#5677). Microsoft.Agents.AI.Foundry now depends on
  ProjectOpenAIClientOptions.AgentName and the (AuthenticationPolicy, options)
  constructor that only exist in Azure.AI.Projects 2.1.0-beta.1.
  
  Changes:
  * Directory.Packages.props: Azure.AI.Projects 2.0.0 -> 2.1.0-beta.1.
  * Microsoft.Agents.AI.Foundry.csproj: drop IsReleased=true so the package ships
    as preview (matches the beta SDK we now depend on). Add a comment noting the
    flip is temporary and should revert once Azure.AI.Projects ships a stable
    2.1.0.
  * Drop redundant VersionOverride="2.1.0-beta.1" from the 10 csprojs that had it
    as a workaround; the central pin now suffices.
  
  Verified:
  * dotnet build agent-framework-dotnet.slnx --warnaserror clean across all TFMs.
  * Microsoft.Agents.AI.Foundry.UnitTests 250/250 pass.
  * Microsoft.Agents.AI.Foundry.Hosting.UnitTests 211/211 pass.
  * dotnet format --verify-no-changes clean for the touched src and test projects.

  Roger Barreto · 2026-05-08 14:46:52 +00:00
  eb709d8fc9
• .NET: Fix function_call_output.output to be a JSON string on the wire (#5705)

  * Fix function_call_output.output to be a JSON string on the wire
  
  OutputConverter was passing the JSON serialization of complex tool results (e.g. List<TodoItem>) directly into OutputItemFunctionToolCallOutput via BinaryData.FromString. The Responses SDK treats that BinaryData as the *raw JSON value* for the field, so non-string results landed on the wire as an unquoted JSON array (e.g. `"output":[{...}]`) instead of a JSON string.
  
  The OpenAI Responses spec requires `function_call_output.output` to be a JSON string. The strict-parsing OpenAI .NET client (FunctionCallOutputResponseItem) consequently failed when threading a follow-up turn that replayed such an item, with: `The JSON value could not be converted... requires an element of type 'String', but the target element has type 'Array'`.
  
  Always wrap the payload as a JSON string literal:
  
    - string s   -> JSON-encode s (quoted, with escapes)
  
    - object o   -> JSON-serialize o, then JSON-encode the resulting text
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Address PR feedback: JsonElement special-case, symmetric inbound unwrap, tests
  
  OutputConverter: extract EncodeFunctionResultAsJsonStringPayload helper
  that special-cases JsonElement / JsonDocument so a string-kind element
  does not get double-encoded into "\"value\"". Other JsonElement kinds
  (object/array/number/bool) round-trip via GetRawText() and are then
  JSON-string-wrapped, matching the spec.
  
  InputConverter: symmetric DecodeFunctionResultPayload added to
  ConvertFunctionCallOutput and ConvertFunctionToolCallOutput so
  previously-stored function_call_output items replayed via
  previous_response_id unwrap back to the original tool result text
  instead of leaking the JSON-encoded form into FunctionResultContent.Result.
  Legacy non-conforming raw-JSON-value payloads pass through unchanged.
  
  Tests:
    - Replace ConvertUpdatesToEventsAsync_FunctionResultStringPayload_EmittedAsRawTextAsync
      with EmittedAsJsonStringAsync asserting the new wire contract ("sunny" -> "\"sunny\"").
    - Add coverage for object payloads, JsonElement string kind (no double-encoding),
      and JsonElement array kind (JSON-stringified).
    - Add InputConverter round-trip tests for spec-compliant JSON-string payloads
      and legacy raw-JSON-array payloads.
  
  All 663 tests pass on net8/net9/net10. Verified end-to-end against the local
  hosted-harness sample: T1-T4 (incl. TodoList tool replay across turns) all
  succeed with no SDK parse errors.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  ---------
  
  Co-authored-by: alliscode <bentho@microsoft.com>
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

  Ben Thomas · 2026-05-07 23:27:57 +00:00
  76772ffc19
• .NET: Foundry.Hosting IT: avoid MSB3026 in publish; fix telemetry UT flake (#5689)

  CI publish step: gate the BuildProjectReferences=false fast-path on an explicit -UsePrebuiltProjectReferences switch (passed by the workflow) instead of marker detection. Adds a preflight error when stale obj/Release/net10.0 outputs would cause CS0579, with actionable recovery instructions.
  
  Telemetry UT flake: AgentFrameworkResponseHandlerTelemetryTests was using a plain List<Activity> for OTel's InMemoryExporter. The exporter writes from background Activity completion callbacks while parallel tests on the same global ActivitySource feed every listener, racing against the assertion's enumeration and throwing 'Collection was modified'. Replaced with a small thread-safe ConcurrentActivityList that locks add/enumerate and returns a snapshot for assertions.

  Roger Barreto · 2026-05-07 18:54:46 +00:00
  a478d1b53c
• .NET: Issue 5662 (#5668)

  * Fix dangling function_call on approval response in Foundry hosting (#5662)
  
  Make the wire<->AF approval translation in Microsoft.Agents.AI.Foundry.Hosting lossless so the resume turn pairs function_call/function_call_output correctly.
  
  Root cause: InputConverter.ConvertMcpApprovalResponse rebuilt FunctionCallContent with CallId set to the FICC-composed AF request id (ficc_<callId>) and Name hardcoded to 'mcp_approval'. This (a) broke Azure Conversations pairing because the persisted function_call had CallId <callId> without prefix, and (b) made FICC unable to invoke the original tool by name on resume.
  
  Fix: ToolApprovalIdMap now records the original FunctionCallContent (CallId, Name, Arguments) keyed by wire id at outbound time. InputConverter reconstructs the original FCC on inbound, falling back to the legacy placeholder when no mapping exists.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Suppress orphan function_call items at the wire (#5662)
  
  Foundry-Hosting's OutputConverter was emitting FunctionCallContent as wire `function_call` items while dropping the paired FunctionResultContent. The result: every auto-invoked tool call left an orphan `function_call` in the response store. The next turn (chained via previous_response_id or via a workflow that yields after one turn under externalLoop) reloaded that history and submitted it to Azure Conversations, which rejected it with HTTP 400 `No tool output found for function call ...`.
  
  Function call/result pairs are entirely internal to the agent's tool-calling loop and have no place on the wire. Approval-required calls already surface separately via ToolApprovalRequestContent → mcp_approval_request, so dropping FCC is safe.
  
  FCC's message-close behavior is preserved so pre-tool text doesn't accidentally concatenate with post-tool text under the same MessageId. Existing OutputConverter tests asserting FCC wire emission are updated to assert suppression.
  
  Verified end-to-end against the declarative-workflow-menu external_loop bench: three-turn previous_response_id chain (menu → carbonara price → EXIT) now completes, where it previously failed at turn 2 with HTTP 400.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Fail fast when no approval mapping is recorded (#5662)
  
  The previous best-effort placeholder fallback in InputConverter.ConvertMcpApprovalResponse couldn't actually round-trip — it just delayed and obscured the failure as an HTTP 400 deep inside the agent loop. Throw InvalidOperationException with the wire id and a clear cause hint instead so the failure is local and actionable.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Trim narrative comments and exception message (#5662)
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Defer FunctionCallContent emission until matched FunctionResultContent (#5662)
  
  Replace blanket FCC suppression with deferred emission. FunctionCallContent
  is buffered (name + serialized arguments) keyed by CallId; the function_call
  and function_call_output wire items are only flushed once the matching
  FunctionResultContent arrives.
  
  - Auto-invoked FCC/FRC pairs surface as paired wire items so Azure's stored
    conversation has matched call+output and previous_response_id resume
    works (closes the orphan-function_call symptom from #5662).
  - Orphan FCCs (e.g. workflow paused at a checkpoint mid-tool-loop) are
    dropped so they never poison the response store.
  - Approval flows are unchanged: TARC still emits mcp_approval_request and
    the post-approval FRC has no buffered FCC to pair with so it is dropped;
    the approval round-trip handles its own pairing via mcp_approval_*.
  - Leaves the door open for future client-side function calling: that
    pattern would surface an FCC without an FRC, would need to opt out of
    buffering, but the wire shape is already correct.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Emit FunctionCallContent and FunctionResultContent directly (option B)
  
  Replace the deferred-emission/buffer-and-drop strategy with direct emission of both function_call and function_call_output wire items.
  
  Rationale: a lone FunctionCallContent in OutputConverter's input can mean two semantically different things, and only the caller knows which:
  
  - Auto-invoke (FICC response surface): always paired with a matching FRC; both halves should appear on the wire as historical record.
  
  - HITL / port-pause request (typed RequestPort<FunctionCallContent,...> or workflow synthesizing a request): a lone FCC IS the wire signal that the caller must resume by supplying a function_call_output.
  
  Buffering+dropping orphans silently swallows the second case. Emitting both directly is the only correct shape for OpenAI Responses semantics.
  
  The InputConverter already accepts function_call_output and mcp_approval_response on resume, so the round-trip works for both kinds.
  
  The approval-flow round-trip fixes (ToolApprovalIdMap rich ApprovalEntry, fail-fast on missing mapping in ConvertMcpApprovalResponse) remain intact.
  
  Tests: updated 7 OutputConverter tests + 1 OutputConverterWorkflow test that asserted the old buffer/drop semantics; all 227 tests pass.
  
  Refs #5662
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Address PR #5668 review feedback on TryLoadMap
  
  Stop swallowing JsonException in ToolApprovalIdMap.TryLoadMap. The catch block recovered to an empty map and a stale comment claimed the caller would gracefully degrade via a 'wire-id fallback path' — but that path no longer exists: InputConverter.ConvertMcpApprovalResponse fails fast when no entry is found.
  
  Letting the JsonException propagate produces an error message that points at the actual cause (a state-bag format incompatibility), instead of converting it into a confusing 'no approval mapping recorded' InvalidOperationException one stack frame later.
  
  Refs #5662, PR #5668
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Address PR #5668 review feedback round 2
  
  - OutputConverter FRC: emit string results as raw text (no JSON-quoting),
    matching the wire contract for function_call_output.output.
  - OutputConverter FCC: validate non-empty CallId before closing the in-flight
    text message, so a skipped FCC no longer breaks output-item boundaries.
  - ToolApprovalIdMap.Record: take pre-serialized arguments JSON (string) and
    primitive callId/name. Drops [RequiresUnreferencedCode]/[RequiresDynamicCode]
    so trim/AOT warnings stop propagating to call sites.
  - ToolApprovalIdMap.Record: no-op when callId or name is empty.
  - Tests: dedup duplicate ConvertItemsToMessages_McpApprovalResponse no-mapping
    test; add coverage for empty-CallId boundary, raw-string FRC payload, and
    Record empty-key no-op.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  ---------
  
  Co-authored-by: alliscode <bentho@microsoft.com>
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

  Ben Thomas · 2026-05-07 00:30:41 +00:00
  cdd80c61ac
• .NET: Bump MEAI to 10.5.1 and add Foundry per-call x-client header support (#5652)

  * Bump MEAI to 10.5.1 and add per-call x-client header support
  
  Replaces the brittle UserAgentResponsesClient subclass with a clean
  per-call x-client-* header pipeline built on the new Microsoft.Extensions.AI
  10.5.1 OpenAIRequestPolicies hook.
  
  Public surface (Microsoft.Agents.AI.Foundry, [Experimental(MAAI001)]):
  * chatOptions.WithClientHeader(name, value) and .WithClientHeaders(IEnumerable)
    validate the x-client- prefix (case-insensitive), apply all-or-nothing on
    bulk, and throw InvalidOperationException on foreign-typed slot collision
  * myAgent.AsBuilder().UseClientHeaders().Build() opts a customer-built agent
    into the pipeline; idempotent via agent.GetService<ClientHeadersAgent>()
  * Foundry-built agents (FoundryAgent.Create*) pre-wire automatically
  
  Internals:
  * ClientHeadersAgent decorator snapshots the dict at scope-push time so
    concurrent runs sharing a ChatOptions reference do not leak headers
  * ClientHeadersScope is an AsyncLocal<IReadOnlyDictionary<string,string>?>
    with LIFO push/dispose semantics
  * ClientHeadersPolicy singleton stamps headers via Headers.Set so per-call
    values overwrite any same-name header from earlier policies and so
    duplicate registration is value-stable
  * OpenAIRequestPoliciesReflection dedups against MEAI's private _entries
    field and falls back to AddPolicy on any reflection failure; a CI test
    asserts the field shape on every MEAI bump
  
  Hosting cleanup:
  * Deleted UserAgentResponsesClient and its dummy throwing pipeline
  * HostedAgentUserAgentPolicy is now registered via OpenAIRequestPolicies
    in FoundryHostingExtensions.TryApplyUserAgent
  
  Tests:
  * 19 new unit tests in ClientHeadersExtensionsTests.cs covering validation,
    AsyncLocal isolation, snapshot semantics, end-to-end wire stamping, and
    shared-chat-client dedup
  * Updated OpenTelemetryAgentTests for MEAI 10.5.1 changes to web_search
    serialization and the reduced tool definition payload when sensitive
    data capture is disabled
  
  Microsoft.Extensions.Compliance.Abstractions stays at 10.5.0 because no
  10.5.1 release exists on nuget.org.
  
  * Address PR review: pre-wire AsAIAgent path and dedup TryApplyUserAgent
  
  * FoundryAgent: extract WireClientHeaders helper and call it from the
    internal (AIProjectClient, ChatClientAgent) constructor used by
    AzureAIProjectChatClientExtensions.AsAIAgent so those Foundry-built
    agents also pre-wire the x-client header pipeline.
  * Foundry.Hosting TryApplyUserAgent: dedup HostedAgentUserAgentPolicy
    registration per OpenAIRequestPolicies instance via
    ConditionalWeakTable so per-request resolution does not grow the
    policy list unboundedly on singleton agents.
  
  * Add tests covering AsAIAgent pre-wire and TryApplyUserAgent dedup
  
  Backs the PR review fixes from a4c8f91 with regression tests:
  * ClientHeadersExtensionsTests: AsAIAgent_FoundryAgent_HasPreWiredClientHeadersAgent
    asserts the FoundryAgent built via AzureAIProjectChatClientExtensions.AsAIAgent
    contains a ClientHeadersAgent in its delegating chain (catches future
    regressions of the bypass).
  * ClientHeadersExtensionsTests: FoundryAgent_PublicConstructor_HasPreWiredClientHeadersAgent
    covers the public constructor path the same way.
  * ClientHeadersExtensionsTests: UseClientHeaders_RepeatedRegistrations_OnSameChatClient_OnlyRegistersOnce
    invokes UseClientHeaders 25 times on a shared chat client and asserts via
    reflection that OpenAIRequestPolicies._entries length is exactly 1.
  * HostedTryApplyUserAgentDedupTests: two tests asserting
    FoundryHostingExtensions.TryApplyUserAgent stays at one entry per
    OpenAIRequestPolicies instance after 50 calls on the same agent and across
    distinct agents on different chat clients.
  
  * Move tests next to their SUT
  
  Removes the dedicated HostedTryApplyUserAgentDedupTests.cs test class.
  Tests are co-located with the SUT they exercise:
  
  * FoundryAgentTests.cs gains the Constructor_PreWiresClientHeadersAgent
    and Constructor_FromAsAIAgentExtension_PreWiresClientHeadersAgent
    cases, since FoundryAgent is the SUT for the pre-wire behavior.
  * HostedOutboundUserAgentTests.cs gains the two TryApplyUserAgent dedup
    cases, since FoundryHostingExtensions.TryApplyUserAgent is the SUT
    it already covers.
  * ClientHeadersExtensionsTests.cs keeps only the
    UseClientHeaders_RepeatedRegistrations_OnSameChatClient_OnlyRegistersOnce
    case, which exercises the public ClientHeadersExtensions surface.
  
  * Remove redundant WithCancellation on inner streaming call
  
  ct is already passed to InnerAgent.RunStreamingAsync, so
  .WithCancellation(ct) on the resulting IAsyncEnumerable is a no-op.
  Caught by Sergey on PR review.
  
  * Address PR review: surface downstream MEAI experimental ID
  
  * Add AIOpenAIRequestPolicies = MEAIExperiments alias to
    DiagnosticIds.Experiments (matches the existing AIResponseContinuations,
    AIMcpServers, AIFunctionApprovals pattern).
  * Mark public ClientHeadersExtensions with [Experimental(AIOpenAIRequestPolicies)]
    instead of AgentsAIExperiments. Consumers now see the MEAI001 warning,
    surfacing the dependency on MEAI's experimental OpenAIRequestPolicies hook.
  * Mark internal OpenAIRequestPoliciesReflection with the same alias to
    suppress warnings at the source rather than via project-wide NoWarn.
  * Remove MEAI001 from Foundry csproj NoWarn (kept on Foundry.Hosting where
    pre-PR usages remain).
  * Clarify ClientHeadersScope XML doc: AsyncLocal flows values forward but
    does NOT auto-restore on method return; explicit using/Dispose is what
    gives stack-style LIFO semantics.

  Roger Barreto · 2026-05-06 14:43:08 +00:00
  b12109b7e4
• .NET: Hosting updates to declarative workflows (#5589)

  * Make DeclarativeWorkflowExecutor ChatProtocol-compatible for AsAIAgent hosting
  
  Extends the existing DeclarativeWorkflowExecutor<TInput> root executor with
  additional ChatProtocol-compatible input routes (string, ChatMessage,
  IEnumerable<ChatMessage>, ChatMessage[], TurnToken) so that workflows built
  via DeclarativeWorkflowBuilder.Build<TInput>(...) work both for direct
  invocation and when hosted via Workflow.AsAIAgent(...).
  
  - Each input message advances the declarative graph immediately; the
    TurnToken that the host sends after the message batch is treated as a
    no-op since the message has already been processed.
  - Conversation id resolution now prefers persisted workflow system state,
    then DeclarativeWorkflowOptions.ConversationId, then a newly created
    conversation. This makes multi-turn invocations reuse the prior
    conversation rather than creating a fresh one each turn.
  - The separate DeclarativeChatProtocolStartExecutor and
    DeclarativeWorkflowBuilder.BuildChatProtocol overloads introduced
    earlier are removed; callers continue to use Build<TInput>(...).
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * fix: use DeclarativeWorkflowContext when reading workflow conversation id
  
  GetWorkflowConversation() requires a DeclarativeWorkflowContext (it calls ReadState which dynamic-casts via the DeclarativeContext helper). The chat-protocol auxiliary handlers receive a BoundWorkflowContext, so calling the extension on the raw IWorkflowContext throws `Invalid workflow context: BoundWorkflowContext`. Use the wrapped declarativeContext that we already constructed.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * fix: surface ExecutorFailedEvent as ErrorContent in AsAIAgent response
  
  WorkflowSession.InvokeStageAsync only converted WorkflowErrorEvent into an ErrorContent payload. ExecutorFailedEvent fell through to the default branch which emits an empty AgentResponseUpdate carrying the event in RawRepresentation. OutputConverter then mapped that to a workflow_action item with status=failed and dropped the exception entirely, so callers got status=completed and error=null even when an executor threw.
  
  - WorkflowSession.cs: add ExecutorFailedEvent case mirroring WorkflowErrorEvent. Honors _includeExceptionDetails.
  
  - OutputConverter.cs: when an update carries both a WorkflowEvent in RawRepresentation and non-empty Contents, fall through to content processing so the unwrapped error (or any future content payload from a workflow event) is actually emitted.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * improve: walk inner exceptions when surfacing ExecutorFailedEvent
  
  DeclarativeActionExecutor wraps inner exceptions in DeclarativeActionException with a generic `Unhandled workflow failure` message, hiding the real cause. Walk InnerException so the response shows the full chain (e.g. the underlying HTTP 400 / auth error).
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Surface declarative SendActivity output as chat content
  
  SendActivityExecutor now emits AgentResponseEvent in addition to
  MessageActivityEvent so chat protocols (e.g. AsAIAgent) receive the
  formatted activity text. The existing MessageActivityEvent is preserved
  for DevUI/observability.
  
  Also extend WorkflowSession.WorkflowOutputEvent handling to accept
  AgentResponse payloads, mapping them to their constituent ChatMessages.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Persist hosted-agent sessions to disk; fix System.LastMessageText
  
  Adds FileSystemAgentSessionStore that writes the serialized AgentSession JSON
  
  (which already embeds the workflow's in-memory checkpoint manager) to a per-
  
  conversation file under /.checkpoints when running in a Foundry hosted env
  
  or {cwd}/.checkpoints locally. Mirrors the python foundry_hosting._responses
  
  FileCheckpointStorage pattern so multi-turn workflow state survives process
  
  restarts without requiring callers to wire up storage themselves.
  
  AddFoundryResponses now defaults to FileSystemAgentSessionStore.CreateDefault()
  
  instead of InMemoryAgentSessionStore; callers can still override via DI.
  
  Also fixes {System.LastMessageText} resolving empty: DeclarativeWorkflowExecutor
  
  .AdvanceAsync was passing the message rehydrated from CreateMessageAsync to
  
  SetLastMessageAsync, but ResponseItem -> ChatMessage round-trip drops the .Text
  
  extension content. Use the original input ChatMessage (which still has the
  
  user-supplied text) and copy the server-assigned MessageId across when present.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Close multi-modal input parity gaps with python foundry_hosting
  
  InputConverter now mirrors the python _responses.py content handling:
  
  - ComputerScreenshotContent maps to UriContent/HostedFileContent (was dropped).
  
  - Plain TextContent and SummaryTextContent map to MEAI TextContent.
  
  - MessageContentReasoningTextContent maps to MEAI TextReasoningContent.
  
  - input_file with text/* file_data data URIs is decoded inline into
  
    TextContent with a [File: name] prefix, matching python _convert_file_data
  
    so {System.LastMessageText} surfaces the file body. Non-text data URIs and
  
    hosted/url file references preserve filename as AdditionalProperties.
  
  Image/file extraction logic is extracted into shared AppendImageContent and
  
  AppendFileContent helpers used by both the fresh-input and history-replay
  
  switches. Existing 37 InputConverter tests still pass.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Foundry hosting: round-trip tool-approval (HITL) content as mcp_approval_request/response
  
  Closes the gap where Microsoft.Agents.AI.Foundry.Hosting silently dropped
  MEAI ToolApprovalRequestContent/ToolApprovalResponseContent in both
  directions. We now serialize them onto the wire as the standard Responses
  API mcp_approval_request/mcp_approval_response items with
  server_label='agent_framework', and parse the symmetric inbound shapes
  back into MEAI content.
  
  Wire format:
  - The Responses API only standardizes mcp_approval_* as the approval
    primitive. We declare AF as a virtual MCP server via the server_label
    field, which is honest for AF's server-side tool-call holding pattern.
  - The SDK enforces a strict {prefix}_{50hex} wire-id format, so we hash
    the AF RequestId and persist a wireId<->afRequestId mapping in
    AgentSession.StateBag so a later mcp_approval_response can be matched
    back to the originating workflow request.
  
  Coexists with the existing ConsentAwareMcpClientAIFunction flow
  (AgentFrameworkResponseHandler.cs) which emits mcp_approval_request from
  a side-channel, not via OutputConverter's content switch.
  
  Known follow-up: python (foundry_hosting/_responses.py) has the same
  output-side gap (ToolApprovalRequestContent emission). Out of scope here.
  
  Tests: +9 unit tests covering both fresh-input and history-replay shapes,
  StateBag mapping resolution, and the non-FunctionCallContent skip path.
  Existing 108 converter tests still pass; full suite 370/370.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Address PR review feedback for hosted-declarative-dotnet
  
  FileSystemAgentSessionStore reliability/scoping:
  
  - Bound Sanitize() stackalloc at 256 chars, fall back to ArrayPool for longer ids so a long conversationId can no longer crash the hosting process with StackOverflowException.
  
  - Use a Guid-suffixed temp file (\{path}.{guid}.tmp\) so concurrent SaveSessionAsync calls on the same conversation can no longer race on the same temp file. Best-effort temp cleanup on failure.
  
  - Bucket session files by agent.Name when set so two keyed agents that happen to share a conversationId no longer overwrite each other's persisted state. Single-agent / unnamed-agent cases keep the original flat layout (Python parity).
  
  DeclarativeWorkflowExecutor chat-protocol routing:
  
  - ConfigureChatProtocolRoutes uses IsAssignableFrom rather than exact type equality so a broader TInput (object, base interfaces) does not have its inherited inputTransform shadowed by handlers we register here.
  
  - HandleChatMessagesAsync / HandleChatMessageArrayAsync now advance through every message in the batch instead of keeping only the trailing one, so multi-message turns and replayed history are no longer silently truncated. AdvanceAsync gains a finalizeTurn flag so only the last message in the batch sends the result.
  
  Tests:
  
  - New FileSystemAgentSessionStoreTests covering constructor, fresh-session fallback for missing/empty files, root-directory creation, save/get round-trip, agent-Name scoping isolation, long conversationId, invalid-character sanitization, and concurrent-save behavior.
  
  - New InputConverterTests covering AppendFileContent: text/* data URI decode (with and without filename prefix), non-text data URI passthrough, malformed data URI fallback, and filename propagation onto UriContent / HostedFileContent.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Add tests for remaining PR review feedback (C2, D1, E1)
  
  C2: InputConverter — add 9 tests covering SDK content types that previously
  had no coverage:
    - SdkTextContent → TextContent (input + output paths)
    - SummaryTextContent → TextContent (input + output paths)
    - MessageContentReasoningTextContent → TextReasoningContent (input + output)
    - ComputerScreenshotContent (HTTP URL → UriContent, data: URI → DataContent,
      output path → UriContent)
  
  D1: OutputConverter — add 2 tests for the WorkflowEvent + Contents fall-through:
    - WorkflowEvent in RawRepresentation with text Contents must flow through
      the content-processing path (text-delta event emitted).
    - WorkflowEvent + ErrorContent must produce a failed event rather than be
      swallowed by the workflow branch.
  
  E1: SendActivityExecutor — extend CaptureActivityAsync to assert that the
  executor emits an AgentResponseEvent carrying the activity text with the
  correct ExecutorId and ChatRole.Assistant role.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Defense-in-depth: neutralize dot-segments in Sanitize and cap TryDecodeTextDataUri input size
  
  Addresses claude-opus-4.6 security review on PR #5589:
  
  - FileSystemAgentSessionStore.Sanitize now replaces all-dot segments
    (., .., ...) with underscores so a developer-controlled agent.Name
    cannot escape the root directory on Linux (where Path.GetInvalidFileNameChars
    only contains NUL and '/').
  
  - InputConverter.TryDecodeTextDataUri rejects encoded payloads larger than
    16 MiB before calling Convert.FromBase64String, preventing a single
    oversized data URI from triggering a multi-megabyte allocation.
  
  - Adds unit tests covering both fixes.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Fix Linux-only failure in SaveSessionAsync_SanitizesInvalidPathCharactersAsync
  
  '?' is in Path.GetInvalidFileNameChars only on Windows, not on Linux/macOS,
  so the test failed on Ubuntu in CI. Use Path.GetInvalidFileNameChars()[0]
  (skipping NUL) to pick a guaranteed-invalid character for the running OS,
  and assert the result no longer contains it.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Address claude-opus-4.6 security/reliability review feedback
  
  WorkflowSession.cs:
  - ExecutorFailedEvent handler no longer leaks the internal executor ID
    in error messages. Mirror the WorkflowErrorEvent pattern: surface the
    exception's Message when _includeExceptionDetails is true, fall back
    to the generic 'An error occurred while executing the workflow.' otherwise.
    This also resolves the failing WorkflowHostSmokeTests assertions.
  
  FileSystemAgentSessionStore.cs:
  - GetSessionPath no longer has a write side effect. Directory.CreateDirectory
    for the per-agent bucket is now performed only on the SaveSessionAsync
    path, so a read miss on GetSessionAsync no longer leaves an empty
    directory on disk.
  - Adds GetSessionAsync_NoExistingFile_DoesNotCreateAgentDirectoryAsync
    to lock in the no-side-effect-on-read contract.
  
  OutputConverterTests.cs:
  - Strengthen ConvertUpdatesToEventsAsync_ToolApprovalRequest_NonFunctionToolCall_SkippedAsync
    to assert exactly one event (the terminal ResponseCompletedEvent) so a
    spurious output-item-added/-done leak would now fail the test.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Address PR review: clean up comments and rename TryParseArguments
  
  - Remove Python-codebase references from C# XML docs and inline comments.
  - Drop fix-history comments referring to previously-resolved issues.
  - Drop `Defense-in-depth:` prefixes; keep the concrete `what & why`.
  - Drop `previously we kept only the trailing message` comment in
    DeclarativeWorkflowExecutor; just describe current loop behavior.
  - Rename InputConverter.TryParseArguments to ParseFunctionArgumentsObject
    to make the intent obvious at the call site.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * Address PR review: collision-free Sanitize, MAF-style refactors
  
  - FileSystemAgentSessionStore.Sanitize now percent-encodes invalid chars
    (and `%` itself) instead of replacing them with `_`, eliminating
    collisions like `foo/bar` vs `foo_bar` mapping to the same bucket.
    All-dot segments encode every dot so Windows trailing-dot trimming
    cannot reintroduce a navigable name.
  - AddFoundryResponses XML doc updated to accurately describe the default
    store root (/.checkpoints when hosted, {cwd}/.checkpoints locally).
  - DeclarativeWorkflowExecutor.ConfigureChatProtocolRoutes now uses exact
    type equality instead of IsAssignableFrom so a broad TInput (e.g.
    object) does not skip registering IEnumerable<ChatMessage>, which
    ChatProtocolExtensions.IsChatProtocol requires verbatim.
  - SendActivityExecutor uses context.YieldOutputAsync(response) instead
    of manually constructing AgentResponseEvent, so the activity will
    participate in any future OutputFilter coverage.
  - WorkflowSession handles AgentResponseEvent in its own switch case,
    avoiding the second typecheck against output.Data.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  * fix(workflows): bridge declarative HITL through Foundry hosting via IExternalRequestEnvelope
  
  Introduce a new public interface IExternalRequestEnvelope in
  Microsoft.Agents.AI.Workflows that lets the runtime peek through a
  declarative-layer envelope without taking a circular reference back into
  the declarative package. ExternalInputRequest (declarative) implements
  it; ExternalInputResponse is constructed via the request's CreateResponse
  factory. WorkflowSession unwraps inner AIContent on the request side and
  rewraps the client's ChatMessage reply into an ExternalInputResponse on
  the response side. PortableValue cannot deserialize directly into an
  interface, so TryGetRequestEnvelope resolves the concrete type via
  RequestPortInfo.RequestType (TypeId -> Type.GetType) before casting.
  
  Public WorkflowHarness contract preserved: InvokeFunctionToolExecutor
  and WorkflowActionVisitor are unchanged from upstream, so public
  InvokeToolWorkflowTest scenarios continue to drive
  ExternalInputRequest / ExternalInputResponse directly through the
  harness.
  
  AgentFrameworkResponseHandler: skip prior conversation history replay
  when an existing session is being resumed (workflow checkpoint already
  holds the prior messages).
  
  WorkflowSession: when includeExceptionDetails is opted in, also unwrap
  DeclarativeActionException so HITL failures are debuggable.
  
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
  
  ---------
  
  Co-authored-by: alliscode <bentho@microsoft.com>
  Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

  Ben Thomas · 2026-05-04 22:09:54 +00:00
  4b5a8478de
• .NET: Add dedicated Foundry.Hosting UnitTest project (#5592)

  * Foundry.Hosting.UnitTests: extract project from Foundry.UnitTests
  
  Move all Hosting/* tests, three toolbox TestData JSONs, and the FakeAuthenticationTokenProvider/HttpHandlerAssert/TestDataUtil helpers (trimmed to toolbox getters) into a new Microsoft.Agents.AI.Foundry.Hosting.UnitTests project. Add it to the slnx and grant the new assembly InternalsVisibleTo from Microsoft.Agents.AI.Foundry and Microsoft.Agents.AI.Foundry.Hosting.
  
  * Foundry.Hosting.UnitTests: align namespaces to assembly name
  
  Rename namespaces from Microsoft.Agents.AI.Foundry.UnitTests(.Hosting) to Microsoft.Agents.AI.Foundry.Hosting.UnitTests across all moved tests, the duplicated helpers, and the trimmed TestDataUtil. Also fixes the prior namespace inconsistency in FoundryToolboxTests.
  
  * Foundry.Hosting.UnitTests: split WorkflowIntegrationTests by SUT
  
  Replace the WorkflowIntegrationTests file (an IT-named file inside a UT project) with two SUT-focused files plus a shared test-doubles file:
  
  - AgentFrameworkResponseHandlerWorkflowTests.cs - the 5 handler-driven tests that exercise AgentFrameworkResponseHandler with a real workflow agent.
  - OutputConverterWorkflowTests.cs - the 5 OutputConverter tests driven by hand-crafted update sequences mirroring real workflow patterns.
  - WorkflowTestAgents.cs - StreamingTextAgent and ThrowingStreamingAgent extracted as internal types used by both files.
  
  * Foundry.UnitTests: trim Hosting-related conditionals and dead testdata
  
  Now that Hosting tests live in their own project:
  - drop the Compile Remove guard for the Hosting subfolder,
  - drop the .NETCoreApp-only PackageReferences (Azure.AI.AgentServer.Responses, Microsoft.AspNetCore.TestHost, OpenTelemetry, OpenTelemetry.Exporter.InMemory),
  - drop the conditional ProjectReference to Microsoft.Agents.AI.Foundry.Hosting,
  - delete the three Toolbox JSON files and the matching Toolbox getters in TestDataUtil.
  
  * Foundry.Hosting.UnitTests: drop redundant 'using Microsoft.Agents.AI.Foundry.Hosting'
  
  The new project namespace is Microsoft.Agents.AI.Foundry.Hosting.UnitTests, which already brings the parent Microsoft.Agents.AI.Foundry.Hosting namespace into scope. The explicit using statement is therefore redundant (IDE0005). Caught by 'dotnet format --verify-no-changes' running on Linux against the .NET 10 SDK.
  
  * Foundry.Hosting: drop InternalsVisibleTo to Foundry.UnitTests
  
  The non-hosting Foundry.UnitTests project no longer holds any Hosting tests after the split, so it doesn't need access to internal types in Microsoft.Agents.AI.Foundry.Hosting. Only Microsoft.Agents.AI.Foundry.Hosting.UnitTests needs it.
  
  * Foundry.Hosting: rename DelegatingResponsesClient to UserAgentResponsesClient
  
  Address westey-m's review feedback on PR #5453: `Delegating*` is conventionally reserved for inheritable base classes (mirroring `DelegatingHandler`) where consumers override one or two members. This polyfill is sealed and only injects the User-Agent supplement, so the new name reflects its actual purpose.
  
  Renamed via `git mv` to preserve history:
  * `src/Microsoft.Agents.AI.Foundry.Hosting/DelegatingResponsesClient.cs` to `UserAgentResponsesClient.cs`
  * `tests/Microsoft.Agents.AI.Foundry.Hosting.UnitTests/DelegatingResponsesClientTests.cs` to `UserAgentResponsesClientTests.cs`
  
  Class, constructor, and all references updated across:
  * `src/.../UserAgentResponsesClient.cs` (class + constructor + internal log message)
  * `src/.../ServiceCollectionExtensions.cs` (cref + type check + instantiation)
  * `src/.../HostedAgentUserAgentPolicy.cs` (cref)
  * `tests/Foundry.UnitTests/RequestOptionsExtensionsTests.cs` (comment)
  * `tests/Foundry.Hosting.UnitTests/UserAgentResponsesClientTests.cs` (class + cref + instantiations)

  Roger Barreto · 2026-04-30 21:09:25 +00:00
  fb97e93a01