Aspire.Hosting.Foundry

Aspire.Hosting.Foundry library

Provides extension methods and resource definitions for an Aspire AppHost to configure Microsoft Foundry.

Getting started

Prerequisites

• Azure subscription - create one for free

Install the package

In your AppHost project, install the Aspire Microsoft Foundry Hosting library with NuGet:

dotnet add package Aspire.Hosting.Foundry

Configure Azure Provisioning for local development

Adding Azure resources to the Aspire application model will automatically enable development-time provisioning for Azure resources so that you don't need to configure them manually. Provisioning requires a number of settings to be available via .NET configuration. Set these values in user secrets in order to allow resources to be configured automatically.

{
    "Azure": {
      "SubscriptionId": "<your subscription id>",
      "ResourceGroupPrefix": "<prefix for the resource group>",
      "Location": "<azure location>"
    }
}

Usage example

Then, in the AppHost.cs file of AppHost, add a Microsoft Foundry deployment and consume the connection using the following methods:

var chat = builder.AddFoundry("foundry")
                  .AddDeployment("chat", "Phi-4", "1", "Microsoft");

var myService = builder.AddProject<Projects.MyService>()
                       .WithReference(chat);

The WithReference method passes that connection information into a connection string named chat in the MyService project.

Configuring deployment rate limits

The SkuCapacity property controls the rate limit in thousands of tokens per minute (TPM). For example, a value of 10 means 10,000 TPM. The default is 1 (1,000 TPM). Use WithProperties to configure it:

var chat = builder.AddFoundry("foundry")
                  .AddDeployment("chat", "gpt-4", "1", "OpenAI")
                  .WithProperties(d => d.SkuCapacity = 10);

See the Azure AI quota management documentation for available quota limits per model and region.

In the Program.cs file of MyService, the connection can be consumed using a client library like Aspire.Azure.AI.Inference or Aspire.OpenAI if the model is compatible with the OpenAI API:

Note: The format parameter of the AddDeployment() method can be found in the Microsoft Foundry portal in the details page of the model, right after the Quick facts text.

Inference client usage

builder.AddAzureChatCompletionsClient("chat")
       .AddChatClient();

OpenAI client usage

builder.AddOpenAIClient("chat")
       .AddChatClient();

Emulator usage

Aspire supports the usage of Foundry Local. Add the following to your AppHost project:

// AppHost
var chat = builder.AddFoundry("foundry")
                  .RunAsFoundryLocal()
                  .AddDeployment("chat", "phi-3.5-mini", "1", "Microsoft");

When the AppHost starts up, the local Foundry service will also be started.

This requires the local machine to have Foundry Local installed and running.

Connection Properties

When you reference Microsoft Foundry resources using WithReference, the following connection properties are made available to the consuming project:

Microsoft Foundry resource

The Microsoft Foundry resource exposes the following connection properties:

Microsoft Foundry deployment

The Microsoft Foundry deployment resource inherits all properties from its parent Microsoft Foundry resource and adds:

Microsoft Foundry project

The Microsoft Foundry project resource exposes the following connection properties:

Aspire exposes each property as an environment variable named [RESOURCE]_[PROPERTY]. For instance, the Uri property of a resource called chat becomes CHAT_URI.

Microsoft Foundry project usage

You can create a Microsoft Foundry project resource to organize agents and model deployments:

var foundry = builder.AddFoundry("foundry");
var project = foundry.AddProject("my-project");

var chat = project.AddModelDeployment("chat", "gpt-4", "1.0", "OpenAI");

var myService = builder.AddPythonApp("agent", "./app", "main:app")
                       .WithReference(project);

The project can also be configured with additional Azure resources:

var appInsights = builder.AddAzureApplicationInsights("ai");
var keyVault = builder.AddAzureKeyVault("kv");

var project = foundry.AddProject("my-project")
                     .WithAppInsights(appInsights)
                     .WithKeyVault(keyVault);

Hosted agent usage

To deploy a containerized application as a hosted agent in Microsoft Foundry:

var foundry = builder.AddFoundry("foundry");
var project = foundry.AddProject("my-project");

builder.AddPythonApp("agent", "./app", "main:app")
       .PublishAsHostedAgent(project);

In run mode, the agent runs locally with health check endpoints and OpenTelemetry instrumentation. In publish mode, the agent is deployed as a hosted agent in Microsoft Foundry.

Additional documentation

• https://learn.microsoft.com/azure/ai-foundry/what-is-azure-ai-foundry
• https://learn.microsoft.com/azure/ai-foundry/foundry-local/
• https://github.com/microsoft/aspire/tree/main/src/Components/README.md

Feedback & contributing

https://github.com/microsoft/aspire