Aspire.Hosting.Foundry

Microsoft Foundry hosting integration

Use this integration to model, configure, and orchestrate Microsoft Foundry in an Aspire solution.

Getting started

Prerequisites

• Azure subscription - create one for free

Add the integration

From your AppHost directory, add the Aspire.Hosting.Foundry integration with the Aspire CLI:

aspire add Aspire.Hosting.Foundry

Configure Azure Provisioning for local development

Adding Azure resources to the AppHost 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 AppHost configuration. From your AppHost directory, set these values with aspire secret set:

aspire secret set Azure:SubscriptionId "<your subscription id>"
aspire secret set Azure:ResourceGroupPrefix "<prefix for the resource group>"
aspire secret set Azure:Location "<azure location>"

Usage example

In the AppHost, add a Microsoft Foundry deployment and reference it from another resource with either C# or TypeScript:

C#

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

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

TypeScript

const chat = await builder.addFoundry("foundry")
                  .addDeployment("chat", "Phi-4", "1", "Microsoft");

const myService = await builder.addNodeApp("myService", "../my-service", "server.js")
                       .withReference(chat);

Foundry Local usage

To let Aspire start Foundry Local and download or load models with the Foundry CLI installed on the AppHost machine:

C#

var chat = builder.AddFoundry("foundry")
                  .RunAsFoundryLocal()
                  .AddDeployment("chat", FoundryModel.Local.Phi4Mini);

TypeScript

const chat = await builder.addFoundry('foundry')
    .runAsFoundryLocal()
    .addDeployment('chat', FoundryModels.Local.Phi4Mini);

To connect from WSL2 or Linux to an existing Foundry Local service on another host, provide its reachable endpoint. Aspire observes this service but does not start, stop, download, or load anything on the remote host, so the model must already be loaded there:

C#

var foundry = builder.AddFoundry("foundry")
                     .RunAsFoundryLocal("http://windows-host:5273");

var chat = foundry.AddDeployment("chat", FoundryModel.Local.Phi4Mini)
                  .WithProperties(deployment =>
                  {
                      deployment.LocalModelId = "Phi-4-mini-instruct-generic-gpu:5";
                  });

TypeScript

const foundry = await builder.addFoundry('foundry')
    .runAsFoundryLocal({ endpoint: 'http://windows-host:5273' });

const chat = await foundry
    .addDeployment('chat', 'Phi-3.5-mini-instruct', { modelVersion: '1', format: 'Microsoft' })
    .withProperties(async (deployment) => {
        await deployment.localModelId.set('Phi-3.5-mini-instruct-generic-gpu:1');
    });

The endpoint must be reachable from the AppHost and every consuming resource. Set LocalModelId to the identifier reported by the remote service when the deployment's model name is an alias.

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:

Property Name	Description
Uri	The endpoint URI for the Microsoft Foundry resource, with the format https://<resource_name>.services.ai.azure.com/ or the emulator service URI when running Foundry Local (e.g., http://127.0.0.1:61799/v1)
AIInferenceUri	The AI inference endpoint URI, with the format https://<resource_name>.services.ai.azure.com/models when targeting Azure or the emulator service URI when running Foundry Local (e.g., http://127.0.0.1:61799/v1)
Key	The API key when using Foundry Local

See Migrate from Azure AI Inference to Azure OpenAI in Azure AI Foundry Models for guidance on which URI to use based on the SDK used by your application.

Microsoft Foundry deployment

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

Property Name	Description
ModelName	The deployment name when targeting Azure or LocalModelId when running Foundry Local, e.g., Phi-4-mini-instruct-generic-gpu:5
Format	The deployment format, e.g., OpenAI, Microsoft, xAi, Deepseek
Version	The deployment version, e.g., 1, 2025-08-07

Microsoft Foundry project

The Microsoft Foundry project resource exposes the following connection properties:

Property Name	Description
Uri	The project endpoint URI, with the format https://<account>.services.ai.azure.com/api/projects/<project>
ConnectionString	The connection string, with the format Endpoint=<uri>
ApplicationInsightsConnectionString	The Application Insights connection string for telemetry

Microsoft Foundry Toolbox

The Toolbox resource exposes the following connection properties:

Property Name	Description
Name	The Toolbox resource name
ProjectEndpoint	The parent Microsoft Foundry project endpoint
Uri	The MCP consumer endpoint, or the version-specific endpoint when Version is set
ApiVersion	The Toolbox data-plane API version
FoundryFeatures	The required Foundry-Features request header value
AuthorizationScope	The Microsoft Entra authorization scope for Toolbox requests
Version	The pinned immutable version, when configured

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")
       .AsHostedAgent(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.

Toolbox usage

Toolboxes bundle reusable Foundry tools behind a single MCP endpoint. Aspire creates the first immutable Toolbox version and promotes new versions only when the configured tools, description, or metadata change.

C#

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

var toolbox = project.AddToolbox("field-tools")
    .WithDescription("Tools for field technicians.")
    .WithWebSearchTool("web-search", "Search the public web.")
    .WithAISearchTool("knowledge-base", search, "docs", "Search the internal knowledge base.")
    .WithMcpTool(
        "inventory",
        "https://inventory.example.com/mcp",
        new FoundryToolboxMcpToolOptions
        {
            ServerDescription = "Inventory MCP server.",
            ApprovalPolicy = new()
            {
                Global = FoundryToolboxMcpGlobalApprovalMode.Always
            }
        });

builder.AddProject<Projects.MyService>("service")
    .WithReference(toolbox)
    .WaitFor(toolbox);

TypeScript

import { FoundryToolboxMcpGlobalApprovalMode } from "./.aspire/modules/aspire.mjs";

const foundry = await builder.addFoundry("foundry");
const project = await foundry.addProject("my-project");
const search = await builder.addAzureSearch("search");

const toolbox = await project.addToolbox("field-tools");
await toolbox.withDescription("Tools for field technicians.");
await toolbox.withWebSearchTool({
    name: "web-search",
    description: "Search the public web."
});
await toolbox.withAISearchTool(
    "knowledge-base",
    search,
    "docs",
    "Search the internal knowledge base.");
await toolbox.withMcpTool("inventory", "https://inventory.example.com/mcp", {
    serverDescription: "Inventory MCP server.",
    approvalPolicy: {
        global: FoundryToolboxMcpGlobalApprovalMode.Always
    }
});

const service = await builder.addNodeApp("service", "../service", "server.js");
await service.withReference(toolbox);
await service.waitFor(toolbox);

Azure AI Search tools reference an index that must already exist and contain the data the tool should search. AddAzureSearch provisions the Search service, but neither it nor WithAISearchTool creates or populates the named index.

The identity running aspire run or aspire deploy must have the Foundry User role on the Foundry project so Aspire can manage Toolbox versions. Deployed compute resources that reference the Toolbox receive this role automatically on that project.

MCP endpoints must be reachable from the Foundry data plane over HTTPS. For local development, use a development tunnel instead of a localhost endpoint. Inline credentials and headers are not supported. Connection-authenticated MCP servers are not currently supported by this integration.

MCP approval policies are declarations returned as Toolbox discovery metadata. The Toolbox service does not enforce approval when a client sends tools/call; the consuming application must inspect the metadata and obtain any required approval before invocation. A custom policy can classify individual MCP tool names:

new FoundryToolboxMcpApprovalPolicy
{
    Always = new()
    {
        ToolNames = ["delete-item", "update-item"],
        ReadOnly = false
    },
    Never = new()
    {
        ToolNames = ["get-item"],
        ReadOnly = true
    }
}

The default consumer endpoint always serves the promoted Toolbox version. Set FoundryToolboxResource.Version only when a consumer must target a specific immutable version.

Existing Toolboxes

Use the existing-resource methods to validate a remote Toolbox without resolving modeled tools, checking Aspire ownership metadata, creating versions, or changing the default:

Method	aspire run	aspire deploy
RunAsExisting()	Validate existing	Reconcile managed
PublishAsExisting()	Reconcile managed	Validate existing
AsExisting()	Validate existing	Validate existing

Existing mode permits a Toolbox with no locally modeled tools. If Version is set, validation also requires that immutable version to exist; otherwise it validates the current default and exposes the selected value through DeployedVersion.

Aspire ownership metadata provides best-effort coordination between deployments, not an atomic lease. The Toolbox API currently has no ETag or conditional update operation. Aspire re-checks the current default and target ownership immediately before promotion and verifies the result afterward, then fails rather than overwriting contradictory concurrent changes.

Prompt agent usage

Prompt agents are declarative agents defined by a model, instructions, and tools. They are always deployed to Azure Foundry — even during local development (aspire run) — and local services communicate with the cloud-provisioned agent.

Tools are project-level resources that can be reused across multiple agents:

var foundry = builder.AddFoundry("foundry");
var project = foundry.AddProject("my-project");
var chat = project.AddModelDeployment("gpt41", FoundryModel.OpenAI.Gpt41);

// Create tools at the project level
var codeInterp = project.AddCodeInterpreterTool("code-interp");
var webSearch = project.AddWebSearchTool("web-search");

// Add agent with tools
var agent = project.AddPromptAgent(chat, "joker-agent",
    instructions: "You are good at telling jokes.")
    .WithTool(codeInterp)
    .WithTool(webSearch);

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

Available tools

Prompt agents support several tool types, all created as project-level resources:

Tool	Extension Method	Description
Code Interpreter	project.AddCodeInterpreterTool(name)	Runs Python code in a sandbox
File Search	project.AddFileSearchTool(name, vectorStoreIds)	Searches uploaded documents via vector search
Web Search	project.AddWebSearchTool(name)	Retrieves real-time web information
Azure AI Search	project.AddAISearchTool(name).WithReference(search)	Grounds responses using Azure AI Search indexes
Bing Grounding	project.AddBingGroundingTool(name).WithReference(conn)	Grounds responses using Bing Search
SharePoint	project.AddSharePointTool(name, connectionIds)	Searches SharePoint data
Microsoft Fabric	project.AddFabricTool(name, connectionIds)	Queries data through Fabric data agents
Azure Functions	project.AddAzureFunctionTool(name, ...)	Invokes serverless Azure Functions
Function Calling	project.AddFunctionTool(name, funcName, params)	Calls application-defined functions
Image Generation	project.AddImageGenerationTool(name)	Generates and edits images (preview)
Computer Use	project.AddComputerUseTool(name, w, h)	Interacts with a computer desktop (preview)

Azure AI Search tool example

var search = builder.AddAzureSearch("search");
var aiSearch = project.AddAISearchTool("search-tool").WithReference(search);

var agent = project.AddPromptAgent(chat, "research-agent")
    .WithTool(aiSearch);

Bing Grounding tool example

Note: The Bing Search resource (Microsoft.Bing/accounts) cannot be provisioned via Bicep or ARM templates. You must create it manually in the Azure portal. Once created, Aspire can automatically provision the Foundry project connection for you.

The simplest approach is to pass the Bing resource ID directly — Aspire will create the connection with the correct authentication and metadata:

var bingResourceId = "/subscriptions/{subId}/resourceGroups/{rg}/providers/Microsoft.Bing/accounts/{name}";
var bing = project.AddBingGroundingTool("bing-tool").WithReference(bingResourceId);

var agent = project.AddPromptAgent(chat, "news-agent")
    .WithTool(bing);

Alternatively, you can create the connection yourself for full control:

var bingConnection = project.AddBingGroundingConnection("bing-conn", bingResourceId);
var bing = project.AddBingGroundingTool("bing-tool").WithReference(bingConnection);

Tool reuse across agents

Tools are project-level resources, so they can be shared across multiple agents:

var codeInterp = project.AddCodeInterpreterTool("code-interp");
var webSearch = project.AddWebSearchTool("web-search");

var agent1 = project.AddPromptAgent(chat, "agent-1").WithTool(codeInterp).WithTool(webSearch);
var agent2 = project.AddPromptAgent(chat, "agent-2").WithTool(codeInterp);

Additional documentation

• https://aspire.dev/integrations/gallery/
• https://aspire.dev/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host/
• https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox
• https://learn.microsoft.com/azure/ai-foundry/what-is-azure-ai-foundry
• https://learn.microsoft.com/azure/ai-foundry/foundry-local/

Feedback & contributing

https://github.com/microsoft/aspire