Watch Aspire live streamsDocsTry Aspire

AI integrations compatibility matrix

Azure OpenAI logo

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.

The following table shows the compatibility between Aspire AI hosting and client integrations:

Hosting IntegrationAspire.OpenAIAspire.Azure.AI.Extensions.OpenAIAspire.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

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.

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.

The Aspire.Hosting.Foundry package provides the hosting integration. In your app host project:

apphost.mts
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
);

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:

Program.cs
builder.AddAzureOpenAIClient("chat").AddChatClient();

For Foundry projects and the Aspire.Azure.AI.Projects package, see Connect to a Foundry project.

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.

The Aspire.Hosting.Azure.CognitiveServices package provides the hosting integration. In your app host project:

apphost.mts
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
);

The Aspire.Azure.AI.Extensions.OpenAI package provides the client integration. In your service project:

Program.cs
builder.AddAzureOpenAIClient("openai");

For direct OpenAI API access, use the Aspire.OpenAI client integration. For more information, see Aspire OpenAI integration (Preview).

The Aspire.Hosting.OpenAI package provides the hosting integration. In your app host project:

apphost.mts
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
);

The Aspire.OpenAI package provides the client integration. In your service project:

Program.cs
builder.AddOpenAIClient("openai");

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.

Azure:

Endpoint={Endpoint};EndpointAIInference={EndpointAIInference}models

Foundry Local:

Endpoint={EmulatorServiceUri};Key={ApiKey}

Deployment:

{Parent};Deployment={DeploymentName}

Deployment:

{ConnectionString};Deployment={DeploymentName}
Endpoint={Endpoint};Key={Key};Model={Model}

Client integration connection string requirements

Section titled “Client integration connection string requirements”

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.

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.

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.