Help Needed: Bridging Azure.AI.OpenAI to Microsoft.Extensions.AI in a Multi-Project Solution

[hexbit2]

Help Needed: Bridging Azure.AI.OpenAI to Microsoft.Extensions.AI in a Multi-Project Solution

Problem Statement

We're building a document processing system using Azure OpenAI for embeddings and chat, but we're struggling to properly bridge the Azure OpenAI clients to the Microsoft.Extensions.AI interfaces (IChatClient, IEmbeddingGenerator) using dependency injection. The blog posts about Microsoft Agent Framework show builder.AddAzureOpenAIClient() but this method doesn't seem to exist in our setup.

Our Architecture

Solution Structure

DocCore/
├── DocCore.API/              # ASP.NET Core Web API
├── DocCore.Worker/           # Background worker (Temporal workflows)
├── DocCore.Services/         # Business logic & AI services
├── DocCore.Workflows/        # Temporal workflow definitions
└── DocCore.Persistence/      # Database layer

Technology Stack

• .NET 9.0
• Azure OpenAI for embeddings (text-embedding-ada-002) and chat (gpt-4)
• Temporal for workflow orchestration
• Qdrant for vector storage
• PostgreSQL for document metadata

The Goal

We want to use Microsoft.Extensions.AI interfaces (IChatClient, IEmbeddingGenerator) throughout our application to:

1. Enable provider switching (Azure OpenAI → OpenAI → Ollama) without code changes
2. Use dependency injection properly
3. Follow Microsoft's recommended patterns from the Agent Framework

What We've Discovered

Package Hierarchy Understanding

Azure.AI.OpenAI (v2.1.0)
└── Provides: AzureOpenAIClient

OpenAI (transitive dependency)
└── Provides: ChatClient, EmbeddingClient

Microsoft.Extensions.AI
└── Provides: IChatClient, IEmbeddingGenerator interfaces

The Core Problem

// This works fine:
AzureOpenAIClient azureClient = new AzureOpenAIClient(
    new Uri("https://endpoint.openai.azure.com"),
    new AzureKeyCredential("key"));

ChatClient chatClient = azureClient.GetChatClient("gpt-4");

// But this FAILS:
IChatClient extensionsClient = (IChatClient)chatClient; // InvalidCastException!

ChatClient does NOT implement IChatClient! They're completely separate type hierarchies.

What We've Tried

Attempt 1: Direct Casting ❌

ChatClient chatClient = azureClient.GetChatClient("gpt-4");
IChatClient iChatClient = (IChatClient)chatClient; // Runtime error

Result: InvalidCastException - no direct relationship between types

Attempt 2: Microsoft.Extensions.AI.OpenAI Package ❌

We found a package called Microsoft.Extensions.AI.OpenAI that supposedly provides bridge methods:

// According to docs, should work:
IChatClient client = chatClient.AsChatClient();

Result: Method doesn't exist, even with package installed

Attempt 3: Aspire.OpenAI Package ⚠️

builder.AddOpenAIClient("chat")
    .AddChatClient("gpt-4");

Result: Works but only for regular OpenAI, NOT Azure OpenAI. Also brings in Aspire dependencies we don't need.

Attempt 4: Microsoft.Agents.AI.Hosting.OpenAI ❌

Based on blog posts showing:

var openai = builder.AddAzureOpenAIClient("openai");
openai.AddChatClient("gpt-4");

We installed:

• Microsoft.Agents.AI.Hosting
• Microsoft.Agents.AI.Hosting.OpenAI
• Microsoft.Agents.AI
• Microsoft.Agents.AI.Abstractions
• Microsoft.Agents.AI.OpenAI

Result: AddAzureOpenAIClient method doesn't exist on either WebApplicationBuilder or HostApplicationBuilder

Attempt 5: Manual Wrapper (Works but not ideal) ✅

public class AzureChatClientWrapper : IChatClient
{
    private readonly ChatClient _innerClient;

    public async Task<ChatCompletion> CompleteAsync(
        IList<ChatMessage> messages,
        ChatOptions? options = null,
        CancellationToken cancellationToken = default)
    {
        // Manual conversion between types
        var azureMessages = ConvertMessages(messages);
        var response = await _innerClient.CompleteChatAsync(azureMessages);
        return ConvertResponse(response);
    }
    // ... more implementation
}

This works but requires maintaining manual wrapper code.

Current Working Code (Without DI/Interfaces)

// In DocCore.Services/Extensions/DependencyInjection.cs
services.AddSingleton(sp =>
{
    var endpoint = new Uri(configuration.GetValue<string>("Embedding:Endpoint")!);
    var credential = new AzureKeyCredential(configuration.GetValue<string>("Embedding:ApiKey")!);
    var deploymentName = configuration.GetValue<string>("Embedding:DeploymentName")!;

    var azureClient = new AzureOpenAIClient(endpoint, credential);
    return azureClient.GetEmbeddingClient(deploymentName);
});

This works but returns concrete EmbeddingClient, not IEmbeddingGenerator<string, Embedding<float>>.

Questions

1. What is the correct way to bridge Azure.AI.OpenAI clients to Microsoft.Extensions.AI interfaces?

2. Does AddAzureOpenAIClient() actually exist?

   • If yes, what package provides it?
   • What version?
   • Are there prerequisites?

3. Is manual wrapper the recommended approach?

   • Should we write our own adapters?
   • Is there a package that provides these adapters?

4. For a multi-project solution (API + Worker + Services), where should the AI client registration happen?

5. Are we missing a fundamental package or concept?

Environment Details

• .NET SDK: 9.0.203
• IDE: VS Code with C# Dev Kit
• OS: macOS
• Key Packages Tested:
  • Azure.AI.OpenAI: 2.1.0
  • Microsoft.Extensions.AI: 9.0.0-preview.9.24556.5
  • Microsoft.Extensions.AI.OpenAI: 9.10.1-preview.1.25521.4
  • Microsoft.Agents.AI: 1.0.0-preview.251028.1
  • Microsoft.Agents.AI.Hosting: 1.0.0-preview.251028.1
  • Microsoft.Agents.AI.Hosting.OpenAI: 1.0.0-alpha.251028.1
  • Aspire.OpenAI: 9.5.2-preview.1.25522.3

Ideal Solution

We want to write:

// In Program.cs or DI setup
builder.AddAzureOpenAIClient("openai")
    .AddChatClient("gpt-4")
    .AddEmbeddingGenerator("text-embedding-ada-002");

// In services
public class DocumentService(IChatClient chatClient,
    IEmbeddingGenerator<string, Embedding<float>> embeddingGenerator)
{
    public async Task<float[]> GenerateEmbedding(string text)
    {
        var result = await embeddingGenerator.GenerateAsync([text]);
        return result.First().Vector.ToArray();
    }
}

References

• Introducing Microsoft Agent Framework
• Upgrading to Microsoft Agent Framework
• Microsoft.Extensions.AI Documentation

Any guidance on the proper way to achieve this would be greatly appreciated. Are we fundamentally misunderstanding how these packages are meant to work together?

[stephentoub]

// According to docs, should work:
IChatClient client = chatClient.AsChatClient();

The method from Microsoft.Extension.AI.OpenAI is named AsIChatClient (note the 'I`).

[stephentoub]

Azure.AI.OpenAI (v2.1.0)

This is an old version. You will want to use the latest.

[stephentoub]

Microsoft.Extensions.AI: 9.0.0-preview.9.24556.5

This is also old. You should use the latest.

[stephentoub]

AddAzureOpenAIClient method doesn't exist on either WebApplicationBuilder or HostApplicationBuilder

It's from the Aspire.Azure.AI.OpenAI package and is an extension on IHostApplicationBuilder.

[hexbit2]

Thanks @stephentoub! The AsIChatClient() method works perfectly. Here's our final solution for anyone else struggling with this:

Working DI Registration:

services.AddSingleton<IChatClient>(sp =>
{
    var azureClient = new AzureOpenAIClient(endpoint, credential);
    var chatClient = azureClient.GetChatClient("gpt-4");
    return chatClient.AsIChatClient(); // Bridge to interface
});

services.AddSingleton<IEmbeddingGenerator<string, Embedding<float>>>(sp =>
{
    var azureClient = new AzureOpenAIClient(endpoint, credential);
    var embeddingClient = azureClient.GetEmbeddingClient("ada-002");
    return embeddingClient.AsIEmbeddingGenerator(); // Bridge to interface
});

This gives us provider independence through the Microsoft.Extensions.AI interfaces.

Question: Is this manual DI registration approach considered best practice for production systems? We noticed the blog examples show builder.AddAzureOpenAIClient() but that method doesn't seem to exist in the current packages.

Also, regarding service lifetime - would you recommend Singleton vs Scoped for IChatClient? We're thinking Scoped might be better since users might want different models per request.

Any guidance on production best practices or recommended reading would be much appreciated!

Thanks for pointing us in the right direction!