Add IHostedConversationClient abstraction for hosted conversation lifecycle management

[rogerbarreto]

Add IHostedConversationClient abstraction for hosted conversation lifecycle management

Summary

Adds a new IHostedConversationClient interface to Microsoft.Extensions.AI for managing server-side hosted conversations (create, get, delete, add messages, list messages). This is complementary to IChatClient — the ConversationId returned by this client feeds into ChatOptions.ConversationId for inference.

Includes the full middleware stack (logging, OpenTelemetry, ConfigureOptions, builder, DI registration), an OpenAI implementation wrapping ConversationClient, and a UseHostedConversations() ChatClient builder extension that enables chatClient.GetService<IHostedConversationClient>().

Components

Microsoft.Extensions.AI.Abstractions (6 files):

• IHostedConversationClient — 5 CRUD operations (CreateAsync, GetAsync, DeleteAsync, AddMessagesAsync, GetMessagesAsync) + GetService
• HostedConversation — Response type with ConversationId, CreatedAt, Metadata, RawRepresentation, AdditionalProperties
• HostedConversationCreationOptions — Options with Metadata, Messages, RawRepresentationFactory, Clone()
• HostedConversationClientMetadata — ProviderName, ProviderUri
• DelegatingHostedConversationClient — Base class for middleware chains
• HostedConversationClientExtensions — GetService<T> convenience

Microsoft.Extensions.AI (10 files):

• HostedConversationClientBuilder — Use()/Build() pipeline builder
• LoggingHostedConversationClient — Debug/Trace level logging
• OpenTelemetryHostedConversationClient — Activity spans + duration histogram
• ConfigureOptionsHostedConversationClient — Options callback for CreateAsync
• HostedConversationChatClient — DelegatingChatClient bridge enabling chatClient.GetService<IHostedConversationClient>() via UseHostedConversations() builder extension
• Builder extension methods + DI ServiceCollection registration

Microsoft.Extensions.AI.OpenAI (1 new file + 1 modified):

• OpenAIHostedConversationClient — Wraps OpenAI.Conversations.ConversationClient with protocol-level JSON APIs
• AsIHostedConversationClient() extension on ConversationClient

Tests (8 files, 63 tests):

• Abstraction tests: property roundtrips, clone independence, delegation
• Middleware tests: builder chain, logging, ConfigureOptions, ChatClient bridge
• OpenAI tests: GetService, metadata, null guards

Documentation:

• docs/HostedConversation-ProviderMapping.md — Provider mapping for OpenAI, Azure Foundry, AWS Bedrock, Google Gemini, Anthropic, Ollama with gap analysis

Usage Example

OpenAIClient openAIClient = new(apiKey);

// Build a chat client with conversation support wired in
IChatClient chatClient = openAIClient.GetChatClient("gpt-4o")
    .AsIChatClient()
    .AsBuilder()
    .UseHostedConversations(
        openAIClient.GetConversationClient().AsIHostedConversationClient())
    .UseLogging()
    .Build();

// Discover the conversation client via GetService
var conversationClient = chatClient.GetService<IHostedConversationClient>()!;
var conversation = await conversationClient.CreateAsync();

// Use the conversation for inference
var response = await chatClient.GetResponseAsync(messages, new ChatOptions
{
    ConversationId = conversation.ConversationId
});

Design Decisions

• Reuses ChatMessage for conversation items — no new message type needed
• [Experimental(MEAI001)] on all types — same diagnostic ID as other AI experiments
• RawRepresentation / RawRepresentationFactory escape hatches for 99.9% provider coverage
• UseHostedConversations() builder extension bridges IChatClient → IHostedConversationClient discovery
• Anthropic/Ollama: implementable via local adapter pattern (no native server-side conversation CRUD)

Microsoft Reviewers: Open in CodeFlow

[qubitron]

threads is agents v1, which is now deprecated -- don't recommend adding support for this one

for agents v2, we use openai