.NET: [BREAKING] Hosting OpenAI Responses protocol helpers and optional execution state

[Roger Barreto (rogerbarreto)]

Motivation & Context

ADR-0027 refocused the hosting design toward protocol conversion helpers plus optional execution state: Agent Framework owns protocol-native <-> run conversion, while the application owns HTTP routing, authentication, middleware, and storage. The Python slice landed in #6891.

This PR realizes that direction for .NET. A first-principles gap analysis showed .NET already covers most of the capability, and more richly, but bundled behind the route-owning MapOpenAIResponses server. The only genuine gap is the ownership model: an application cannot own its own route and call just the conversion primitives. So this change un-bundles the existing conversion rather than reinventing it. No new package, no OpenAI-SDK-typed reimplementation, and MapOpenAIResponses public behavior is unchanged.

Description & Review Guide

• What are the major changes?
  • New public facade OpenAIResponses in Microsoft.Agents.AI.Hosting.OpenAI (JsonElement/SSE boundary; wire DTOs stay internal), delegating to the existing internal converters:
    • ToAgentRunRequest(JsonElement) -> messages + AgentRunOptions?
    • WriteResponse(AgentResponse, responseId, sessionId?) -> Responses JSON
    • WriteResponseStreamAsync(IAsyncEnumerable<AgentResponseUpdate>, responseId, ...) -> Responses SSE frames
    • GetSessionId(JsonElement) -> previous_response_id/conversation id (kept separate so the trust boundary stays visible)
    • CreateResponseId() -> resp_*
  • Protocol-neutral execution state in Microsoft.Agents.AI.Hosting:
    • AgentSessionStore.DeleteSessionAsync (added as an abstract method so every store makes a conscious choice: implement deletion or throw NotSupportedException itself; the in-box stores implement it). Hosting is still preview, so this tightens the contract now rather than shipping a silent default.
    • No agent-side holder: applications use AgentSessionStore directly (GetSessionAsync creates on miss, SaveSessionAsync persists post-run including under a newly minted id, DeleteSessionAsync removes). ADR-0032 records why per-run instance and async target setup are left to the DI container in .NET.
    • HostedWorkflowState + HostedWorkflowRunResult (workflow instance or factory + CheckpointManager + an internal sessionId -> CheckpointInfo head cursor; RunOrResumeAsync/RunOrResumeStreamingAsync)
  • Two samples under dotnet/samples/04-hosting/af-hosting/: local_responses (app-owned route, sync + SSE) and local_responses_workflow (checkpoint resume).
  • ADR 0032-dotnet-hosting-protocol-helpers.md and spec 003-dotnet-hosting-protocol-helpers.md.
• What is the impact of these changes?
  • Breaking (preview package): adds a new abstract member (AgentSessionStore.DeleteSessionAsync) to a public abstract type and renames the store id parameter to sessionStoreId, so external subclasses must implement the new member. The net-new helpers are otherwise additive. MapOpenAIResponses, IResponsesService, ChatCompletions, and Conversations are untouched.
  • Applications can now expose an agent or workflow over OpenAI Responses while owning their own routing, auth, and storage.
• What do you want reviewers to focus on?
  • The public helper shape and the JsonElement boundary decision (recorded in ADR-0032, alongside why not the OpenAI SDK Responses types).
  • The decision to reuse the richer existing AgentSessionStore instead of cloning Python's in-memory SessionStore, and the abstract (implement-or-throw) DeleteSessionAsync.
  • The HostedWorkflowState head-cursor approach for per-session checkpoint resume.

Related Issue

N/A. This is the .NET realization of the accepted ADR-0027; it adds ADR-0032 and its spec. It supersedes the earlier channel-model draft in #6151 (closed). Opening as a draft for design feedback.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is a breaking change (preview package): a new abstract member is added to AgentSessionStore and the store id parameter is renamed to sessionStoreId. The breaking change label is applied.

[Copilot]

Pull request overview

This PR implements the ADR-0027 “helper-first” hosting direction for .NET by exposing a public OpenAI Responses protocol conversion facade (OpenAIResponses) and adding optional, protocol-neutral execution state helpers for agent session continuity and workflow checkpoint resume, plus new samples and design docs.

Changes:

• Adds Microsoft.Agents.AI.Hosting.OpenAI.OpenAIResponses public helper facade and OpenAIResponsesRunRequest for JsonElement-bound request/response conversions (JSON + SSE).
• Adds protocol-neutral execution state helpers in Microsoft.Agents.AI.Hosting (HostedAgentState, HostedWorkflowState, HostedWorkflowRunResult) and introduces AgentSessionStore.DeleteSessionAsync with in-box store overrides.
• Adds new hosting samples (agent + workflow) plus unit tests and ADR/spec documentation for the helper-first hosting shape.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
dotnet/tests/Microsoft.Agents.AI.Hosting.UnitTests/InMemoryAgentSessionStoreTests.cs	New tests covering AgentSessionStore.DeleteSessionAsync behavior across in-box stores.
dotnet/tests/Microsoft.Agents.AI.Hosting.UnitTests/HostedWorkflowStateTests.cs	New tests for HostedWorkflowState argument validation and checkpoint lookup behavior.
dotnet/tests/Microsoft.Agents.AI.Hosting.UnitTests/HostedAgentStateTests.cs	New tests for HostedAgentState store delegation and optional per-session locking.
dotnet/tests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests/OpenAIResponsesTests.cs	New tests for OpenAIResponses request mapping, session id extraction, id creation, and response rendering.
dotnet/src/Microsoft.Agents.AI.Hosting/NoopAgentSessionStore.cs	Implements no-op DeleteSessionAsync override.
dotnet/src/Microsoft.Agents.AI.Hosting/Local/InMemoryAgentSessionStore.cs	Implements DeleteSessionAsync by removing stored session content.
dotnet/src/Microsoft.Agents.AI.Hosting/IsolationKeyScopedAgentSessionStore.cs	Pass-through implementation for DeleteSessionAsync with scoped conversation ids.
dotnet/src/Microsoft.Agents.AI.Hosting/HostedWorkflowState.cs	Adds in-memory per-session checkpoint “head cursor” and RunOrResumeAsync.
dotnet/src/Microsoft.Agents.AI.Hosting/HostedWorkflowRunResult.cs	Adds run result wrapper carrying session id, emitted events, and head checkpoint.
dotnet/src/Microsoft.Agents.AI.Hosting/HostedAgentState.cs	Adds helper that pairs an agent with a session store plus optional per-session locking.
dotnet/src/Microsoft.Agents.AI.Hosting/DelegatingAgentSessionStore.cs	Pass-through implementation for new DeleteSessionAsync API.
dotnet/src/Microsoft.Agents.AI.Hosting/AgentSessionStore.cs	Adds new virtual DeleteSessionAsync with throwing default.
dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/OpenAIResponsesRunRequest.cs	Adds public run request carrier (messages + optional run options).
dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/OpenAIResponses.cs	Adds public conversion facade for Responses JSON and SSE rendering.
dotnet/samples/04-hosting/HostingResponsesWorkflow/README.md	New sample README for app-owned workflow route + checkpoint resume.
dotnet/samples/04-hosting/HostingResponsesWorkflow/Program.cs	New minimal API workflow sample using OpenAIResponses + HostedWorkflowState.
dotnet/samples/04-hosting/HostingResponsesWorkflow/HostingResponsesWorkflow.csproj	New workflow sample project.
dotnet/samples/04-hosting/HostingResponsesAgent/README.md	New sample README for app-owned agent route (sync + SSE).
dotnet/samples/04-hosting/HostingResponsesAgent/Program.cs	New minimal API agent sample using OpenAIResponses + HostedAgentState.
dotnet/samples/04-hosting/HostingResponsesAgent/HostingResponsesAgent.csproj	New agent sample project.
dotnet/agent-framework-dotnet.slnx	Includes the new hosting samples in the solution.
docs/specs/003-dotnet-hosting-protocol-helpers.md	Adds accepted spec describing the new helper + state surface and samples.
docs/decisions/0032-dotnet-hosting-protocol-helpers.md	Adds accepted ADR capturing the decision and rationale for the new surface.

[github-actions]

Automated Code Review

Reviewers: 5 | Confidence: 88%

✓ Correctness

The framework code (OpenAIResponses facade, HostedAgentState, HostedWorkflowState, DeleteSessionAsync additions) is well-designed and correct. The one correctness issue is in the HostingResponsesAgent sample, which passes responseId as the sessionId parameter to WriteResponse and WriteResponseStreamAsync, whereas the spec's own E2E sample (docs/specs/003-dotnet-hosting-protocol-helpers.md lines 183, 194) correctly passes sessionId. This causes the rendered response's conversation.id to equal the response id rather than the actual conversation/session id, breaking the OpenAI Responses conversation-grouping semantic.

✓ Security Reliability

The PR is well-designed with clear trust boundary documentation and proper input validation. Two issues found: (1) the session locking dictionary in HostedAgentState grows without bound, creating a resource leak for long-lived services; (2) the HostingResponsesAgent sample passes responseId where the spec (in the same PR) passes sessionId as the conversation identifier, causing conversation.id in the response to be per-turn rather than stable.

✓ Test Coverage

The PR adds good unit tests for guard clauses, delegation, and basic conversion paths. However, three significant behaviors lack test coverage: (1) the WriteResponseStreamAsync streaming facade has zero tests — the SSE frame formatting logic is entirely untested; (2) HostedWorkflowState.RunOrResumeAsync only tests argument validation, not the actual run-or-resume logic, event collection, or cursor recording; (3) IsolationKeyScopedAgentSessionStore.DeleteSessionAsync (new code) has no test verifying it applies isolation-key scoping before delegating to the inner store.

✓ Failure Modes

The PR is well-structured from a failure-mode perspective. Disposal patterns for Run are correct (await using), the semaphore releaser is safe against double-release via Interlocked.Exchange, argument validation gates all state operations, and the NotSupportedException default for DeleteSessionAsync is documented, tested, and maintains backward compatibility. No silent failure paths, swallowed exceptions, or partial-write scenarios were found in the new code. The in-memory cursor limitation in HostedWorkflowState is explicitly documented as a v1 trade-off.

✓ Design Approach

I found one production-surface design issue and one sample-level design issue. The new OpenAIResponses helper path no longer enforces the existing OpenAI Responses invariant that conversation and previous_response_id are mutually exclusive, so invalid requests are silently accepted and resolved differently from MapOpenAIResponses. Separately, the new agent sample collapses conversation.id and previous_response_id into a single storage key, which breaks stable conversation.id continuity for callers following the documented protocol shape.

---

Automated review by rogerbarreto's agents