AI integrations compatibility matrix
Aspire provides several AI hosting and client integrations that enable you to work with different AI services and platforms. This article is a compatibility reference showing which client integrations work with which hosting integrations, along with the recommended pairings and AppHost API examples.
Compatibility matrix
Section titled “Compatibility matrix”The following table shows the compatibility between Aspire AI hosting and client integrations:
| Hosting Integration | Aspire.OpenAI | Aspire.Azure.AI.Extensions.OpenAI | Aspire.Azure.AI.Projects |
|---|---|---|---|
Aspire.Hosting.Foundry | ⚠️ Partial — Foundry Local only (preferred) | ✅ Yes — deployments and projects (preferred) | ⚠️ Partial — projects only |
Aspire.Hosting.Azure.CognitiveServices | ❌ No | ✅ Yes (preferred) | ❌ No |
Aspire.Hosting.OpenAI | ✅ Yes (preferred) | ⚠️ Partial — AddOpenAIClientFromConfiguration only | ❌ No |
Recommended pairings
Section titled “Recommended pairings”In general, use an Aspire client integration when one supports the resource and its authentication method. Use Aspire.OpenAI for OpenAI-compatible resources that provide an API key, including Foundry Local. For Azure OpenAI and cloud-provisioned Microsoft Foundry resources, which authenticate with Microsoft Entra ID, use Aspire.Azure.AI.Extensions.OpenAI.
Microsoft Foundry
Section titled “Microsoft Foundry”For Foundry Local resources, use the Aspire.OpenAI client integration. It provides dependency injection and telemetry for the OpenAI-compatible endpoint and the API key that Foundry Local exposes. For cloud-provisioned Microsoft Foundry resources, use Aspire.Azure.AI.Extensions.OpenAI: AddAzureOpenAIClient for model deployments, or AddAzureProjectOpenAIClient for Foundry projects. Use Aspire.Azure.AI.Projects (AddAzureAIProjectClient) for project and agent-management operations.
For more information, see Microsoft Foundry integration.
Hosting integration
Section titled “Hosting integration”The Aspire.Hosting.Foundry package provides the hosting integration. In your app host project:
import { function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder } from './.aspire/modules/aspire.mjs';
const const builder: IDistributedApplicationBuilder
builder = await function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder();
const const foundry: FoundryResource
foundry = await const builder: IDistributedApplicationBuilder
builder.IDistributedApplicationBuilder.addFoundry(name: string): FoundryResource
Adds a Microsoft Foundry resource to the application model.
addFoundry("foundry").FoundryResource.runAsFoundryLocal(endpoint?: string): FoundryResource
Configures a Microsoft Foundry resource to use an Aspire-managed or existing Foundry Local service.
runAsFoundryLocal();
const const chat: FoundryDeploymentResource
chat = await const foundry: FoundryResource
foundry.FoundryResource.addDeployment(name: string, model: FoundryModel | string, options?: { modelVersion?: string; format?: string;} | undefined): FoundryDeploymentResource (+1 overload)
Adds a Microsoft Foundry deployment resource to a Microsoft Foundry resource.
addDeployment('chat', { FoundryModel.name?: string | undefined
name: 'Phi-4', FoundryModel.version?: string | undefined
version: '1', FoundryModel.format?: string | undefined
format: 'Microsoft',});
await const builder: IDistributedApplicationBuilder
builder.IDistributedApplicationBuilder.addNodeApp(name: string, appDirectory: string, scriptPath: string): NodeAppResource
Adds a node application to the application model. Node should be available on the PATH.
addNodeApp("api", "./api", "index.js") .ExecutableResource.withReference(source: IResource | EndpointReference | string | uri, options?: { connectionName?: string; optional?: boolean; name?: string;} | undefined): NodeAppResource (+1 overload)
Adds a reference to another resource
withReference(const chat: FoundryDeploymentResource
chat);var builder = DistributedApplication.CreateBuilder(args);
var foundry = builder.AddFoundry("foundry") .RunAsFoundryLocal();
var chat = foundry.AddDeployment("chat", FoundryModel.Local.Phi4);
builder.AddDotnetProject("exampleproject", "../ExampleProject/ExampleProject.csproj") .WithReference(chat);builder, err := aspire.CreateBuilder()if err != nil { log.Fatal(aspire.FormatError(err))}
foundry := builder.AddFoundry("foundry"). RunAsFoundryLocal()
chat := foundry.AddDeployment("chat", "Phi-4", aspire.AddDeploymentModelVersion("1"), aspire.AddDeploymentFormat("Microsoft"))
api := builder.AddNodeApp("api", "./api", "index.js"). WithReference(chat)Client integration
Section titled “Client integration”For Foundry Local, the Aspire.OpenAI package provides the recommended client integration. For its configuration sample, see Connect with Aspire.OpenAI. For cloud-provisioned Foundry resources, the Aspire.Azure.AI.Extensions.OpenAI package provides the client integration:
builder.AddAzureOpenAIClient("chat").AddChatClient();For Foundry projects and the Aspire.Azure.AI.Projects package, see Connect to a Foundry project.
Azure Cognitive Services (Azure OpenAI)
Section titled “Azure Cognitive Services (Azure OpenAI)”For Azure OpenAI resources, use the Aspire.Azure.AI.Extensions.OpenAI client integration for Microsoft Entra ID and API-key authentication support. For more information, see Azure OpenAI integration.
Hosting integration
Section titled “Hosting integration”The Aspire.Hosting.Azure.CognitiveServices package provides the hosting integration. In your app host project:
import { function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder } from './.aspire/modules/aspire.mjs';
const const builder: IDistributedApplicationBuilder
builder = await function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder();
const const openai: AzureOpenAIResource
openai = await const builder: IDistributedApplicationBuilder
builder.IDistributedApplicationBuilder.addAzureOpenAI(name: string): AzureOpenAIResource
Adds an Azure OpenAI resource to the application model.
addAzureOpenAI("openai");
await const builder: IDistributedApplicationBuilder
builder.IDistributedApplicationBuilder.addNodeApp(name: string, appDirectory: string, scriptPath: string): NodeAppResource
Adds a node application to the application model. Node should be available on the PATH.
addNodeApp("api", "./api", "index.js") .ExecutableResource.withReference(source: IResource | EndpointReference | string | uri, options?: { connectionName?: string; optional?: boolean; name?: string;} | undefined): NodeAppResource (+1 overload)
Adds a reference to another resource
withReference(const openai: AzureOpenAIResource
openai);var builder = DistributedApplication.CreateBuilder(args);
var openai = builder.AddAzureOpenAI("openai");
builder.AddDotnetProject("exampleproject", "../ExampleProject/ExampleProject.csproj") .WithReference(openai);builder, err := aspire.CreateBuilder()if err != nil { log.Fatal(aspire.FormatError(err))}
openai := builder.AddAzureOpenAI("openai")
api := builder.AddNodeApp("api", "./api", "index.js"). WithReference(openai)Client integration
Section titled “Client integration”The Aspire.Azure.AI.Extensions.OpenAI package provides the client integration. In your service project:
builder.AddAzureOpenAIClient("openai");Direct OpenAI
Section titled “Direct OpenAI”For direct OpenAI API access, use the Aspire.OpenAI client integration. For more information, see Aspire OpenAI integration (Preview).
Hosting integration
Section titled “Hosting integration”The Aspire.Hosting.OpenAI package provides the hosting integration. In your app host project:
import { function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder } from './.aspire/modules/aspire.mjs';
const const builder: IDistributedApplicationBuilder
builder = await function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder();
const const openai: OpenAIResource
openai = await const builder: IDistributedApplicationBuilder
builder.IDistributedApplicationBuilder.addOpenAI(name: string): OpenAIResource
Adds an OpenAI parent resource that can host multiple models.
addOpenAI("openai");
await const builder: IDistributedApplicationBuilder
builder.IDistributedApplicationBuilder.addNodeApp(name: string, appDirectory: string, scriptPath: string): NodeAppResource
Adds a node application to the application model. Node should be available on the PATH.
addNodeApp("api", "./api", "index.js") .ExecutableResource.withReference(source: IResource | EndpointReference | string | uri, options?: { connectionName?: string; optional?: boolean; name?: string;} | undefined): NodeAppResource (+1 overload)
Adds a reference to another resource
withReference(const openai: OpenAIResource
openai);var builder = DistributedApplication.CreateBuilder(args);
var openai = builder.AddOpenAI("openai");
builder.AddDotnetProject("exampleproject", "../ExampleProject/ExampleProject.csproj") .WithReference(openai);builder, err := aspire.CreateBuilder()if err != nil { log.Fatal(aspire.FormatError(err))}
openai := builder.AddOpenAI("openai")
api := builder.AddNodeApp("api", "./api", "index.js"). WithReference(openai)Client integration
Section titled “Client integration”The Aspire.OpenAI package provides the client integration. In your service project:
builder.AddOpenAIClient("openai");Connection string formats
Section titled “Connection string formats”Understanding how hosting and client integrations communicate through connection strings can help you troubleshoot connectivity issues and understand the underlying mechanics.
Each hosting integration generates connection strings in different formats that are consumed by the client integrations.
Hosting integration connection strings
Section titled “Hosting integration connection strings”Aspire.Hosting.Foundry
Section titled “Aspire.Hosting.Foundry”Azure:
Endpoint={Endpoint};EndpointAIInference={EndpointAIInference}modelsFoundry Local:
Endpoint={EmulatorServiceUri};Key={ApiKey}Deployment:
{Parent};Deployment={DeploymentName}Aspire.Hosting.Azure.CognitiveServices
Section titled “Aspire.Hosting.Azure.CognitiveServices”Deployment:
{ConnectionString};Deployment={DeploymentName}Aspire.Hosting.OpenAI
Section titled “Aspire.Hosting.OpenAI”Endpoint={Endpoint};Key={Key};Model={Model}Client integration connection string requirements
Section titled “Client integration connection string requirements”Aspire.OpenAI
Section titled “Aspire.OpenAI”Expects connection strings in the format:
Endpoint={Endpoint};Key={Key};Deployment={Deployment};Model={Model}Uses either Deployment or Model (in that order). Deployment is set by Aspire.Hosting.Azure.CognitiveServices while Model is set by Aspire.Hosting.OpenAI.
Aspire.Azure.AI.Extensions.OpenAI
Section titled “Aspire.Azure.AI.Extensions.OpenAI”AddAzureOpenAIClient expects an HTTPS Azure OpenAI or Foundry account endpoint:
Endpoint={Endpoint};Key={Key};Deployment={Deployment}Key is optional; without it, the client uses Microsoft Entra ID. A bare endpoint URI is also accepted. Chat and embedding helpers use either Deployment or Model, but not both.
AddAzureProjectOpenAIClient expects a Foundry project endpoint and rejects Key:
Endpoint=https://{account}.services.ai.azure.com/api/projects/{project}AddOpenAIClientFromConfiguration selects an Azure account, Foundry project, or OpenAI-compatible registration from the endpoint. Endpoints on Azure hosts are treated as Azure; use IsAzure=true or IsAzure=false to override detection.
Aspire.Azure.AI.Projects
Section titled “Aspire.Azure.AI.Projects”Expects a Foundry project endpoint, either as a bare URI or in the format:
Endpoint=https://{account}.services.ai.azure.com/api/projects/{project}Key isn’t supported; the client uses Microsoft Entra ID.