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

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

Hosting Integration	Aspire.OpenAI	Aspire.Azure.AI.OpenAI	Aspire.Azure.AI.Inference
Aspire.Hosting.Foundry	❌ No	⚠️ Partial	✅ Yes (preferred)
Aspire.Hosting.Azure.CognitiveServices	❌ No	✅ Yes (preferred)	❌ No
Aspire.Hosting.OpenAI	✅ Yes (preferred)	✅ Yes	❌ No
Aspire.Hosting.GitHub.Models	⚠️ Partial	❌ No	✅ Yes (preferred)

Legend

• ✅ Yes: The client integration is compatible with the hosting integration.
• ⚠️ Partial: The client integration might not support all models or APIs.
• ❌ No: The client integration does not support the hosting environment.
• (preferred): The recommended client integration for this hosting integration.

Recommended pairings

In general, use Aspire.Azure.AI.Inference to connect to Azure hosted models, or Aspire.OpenAI to connect directly to OpenAI.

Microsoft Foundry

For Microsoft Foundry resources, use the Aspire.Azure.AI.Inference client integration. This provides the best compatibility with the diverse range of models available through Microsoft Foundry. For more information, see Microsoft Foundry integration.

Hosting integration

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

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var foundry = builder.AddFoundry("foundry");

builder.AddProject<Projects.ExampleProject>()
    .WithReference(foundry);

TypeScript

TypeScript — apphost.ts

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const foundry = await builder.addFoundry("foundry");

await builder.addNodeApp("api", "./api", "index.js")
    .withReference(foundry);

Client integration

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

C# — Program.cs

builder.AddAzureChatCompletionsClient("foundry");

Azure Cognitive Services (Azure OpenAI)

For Azure OpenAI resources, use the Aspire.Azure.AI.OpenAI client integration for full Azure-specific features and authentication support. For more information, see Azure OpenAI integration.

Hosting integration

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

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var openai = builder.AddAzureOpenAI("openai");

builder.AddProject<Projects.ExampleProject>()
    .WithReference(openai);

TypeScript

TypeScript — apphost.ts

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const openai = await builder.addAzureOpenAI("openai");

await builder.addNodeApp("api", "./api", "index.js")
    .withReference(openai);

Client integration

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

C# — Program.cs

builder.AddAzureOpenAIClient("openai");

Direct OpenAI

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

Hosting integration

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

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var openai = builder.AddOpenAI("openai");

builder.AddProject<Projects.ExampleProject>()
    .WithReference(openai);

TypeScript

TypeScript — apphost.ts

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const openai = await builder.addOpenAI("openai");

await builder.addNodeApp("api", "./api", "index.js")
    .withReference(openai);

Client integration

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

C# — Program.cs

builder.AddOpenAIClient("openai");

GitHub Models

For GitHub Models, use the Aspire.Azure.AI.Inference client integration for the best compatibility with the GitHub Models API. For more information, see Aspire GitHub Models integration (Preview).

Hosting integration

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

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var chat = builder.AddGitHubModel("chat", "openai/gpt-4o-mini");

builder.AddProject<Projects.ExampleProject>()
    .WithReference(chat);

TypeScript

TypeScript — apphost.ts

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const chat = await builder.addGitHubModel("chat", "openai/gpt-4o-mini");
Error ts(2769)  ― No overload matches this call.
  Overload 1 of 2, '(name: string, model: GitHubModelName, options?: { organization?: string | ParameterResource | undefined; } | undefined): GitHubModelResource', gave the following error.
    Argument of type '"openai/gpt-4o-mini"' is not assignable to parameter of type 'GitHubModelName'.
  Overload 2 of 2, '(name: string, model: GitHubModelName, organization?: string | ParameterResource | undefined): GitHubModelResource', gave the following error.
    Argument of type '"openai/gpt-4o-mini"' is not assignable to parameter of type 'GitHubModelName'.

await builder.addNodeApp("api", "./api", "index.js")
    .withReference(chat);

Client integration

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

C# — Program.cs

builder.AddAzureChatCompletionsClient("chat");

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

Aspire.Hosting.Foundry

Azure:

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

Foundry Local:

Endpoint={EmulatorServiceUri};Key={ApiKey}

Deployment:

{Parent};Deployment={DeploymentName}

Aspire.Hosting.Azure.CognitiveServices

Deployment:

{ConnectionString};Deployment={DeploymentName}

Aspire.Hosting.OpenAI

Endpoint={Endpoint};Key={Key};Model={Model}

Aspire.Hosting.GitHub.Models

Endpoint=https://models.github.ai/inference;Key={Key};Model={ModelName}

Client integration connection string requirements

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.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.

This integration is a superset of Aspire.OpenAI and supports TokenCredential and Azure-specific features.

Aspire.Azure.AI.Inference

Expects connection strings in the format:

Endpoint={Endpoint};EndpointAIInference={EndpointAIInference};Key={Key};Deployment={DeploymentName};Model={ModelName}

Uses either Deployment or Model (in that order). Deployment is set by Aspire.Hosting.Azure.CognitiveServices while Model is set by Aspire.Hosting.GitHub.Models.

Uses EndpointAIInference if available, otherwise Endpoint.

See also

• Azure OpenAI integration
• Azure AI Inference integration
• Microsoft Foundry integration
• Azure AI Search integration
• Microsoft.Extensions.AI documentation