Skip to content

[docs] Update Foundry hosted agent API from PublishAsHostedAgent to AsHostedAgent #1130

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
IEvangelist merged 2 commits into from
Jun 1, 2026
Merged

[docs] Update Foundry hosted agent API from PublishAsHostedAgent to AsHostedAgent #1130

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c3ac0ba
Update Foundry hosted agent API from PublishAsHostedAgent to AsHosted…
aspire-repo-bot[bot] May 29, 2026
f1bc780
Address review feedback (5 threads)
IEvangelist May 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 14 additions & 14 deletions ...ontent/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -347,11 +347,11 @@ await foundry
</TabItem>
</Tabs>

`AddProject` creates a default Azure Container Registry for hosted agents. Use `WithContainerRegistry` when you want to point the project at a different registry.
`AddProject` creates a default Azure Container Registry for hosted agents only in publish mode (when deploying to Azure). In local run mode, no default registry is created. Use `WithContainerRegistry` when you want to point the project at a specific registry.

## Publish a hosted agent to Azure AI Foundry
## Add a hosted agent to Azure AI Foundry

Use `PublishAsHostedAgent` in C# or `withComputeEnvironment` in TypeScript to publish an executable or containerized app as a hosted agent in a Foundry project:
Use `AsHostedAgent` in C# or `asHostedAgent` in TypeScript to configure an executable or containerized app as a hosted agent in a Foundry project:

<Tabs syncKey='aspire-lang'>
<TabItem id='csharp' label='C#'>
Expand All @@ -366,13 +366,13 @@ var chat = project.AddModelDeployment("chat", FoundryModel.OpenAI.Gpt5Mini);
builder.AddPythonApp("agent-python", "..\\agent", "main:app")
.WithReference(project)
.WithReference(chat)
.PublishAsHostedAgent(project);
.AsHostedAgent(project);

builder.AddProject<Projects.Agent>("agent-dotnet")
.WithHttpEndpoint(targetPort: 9000)
.WithReference(project)
.WithReference(chat)
.PublishAsHostedAgent(project);
.AsHostedAgent(project);

builder.Build().Run();
```
Expand All @@ -397,22 +397,22 @@ await builder
.addPythonApp('agent-python', '../agent', 'main:app')
.withReference(project)
.withReference(chat)
.withComputeEnvironment({ project });
.asHostedAgent(project);

await builder
.addProject('agent-dotnet', '../Agent/Agent.csproj')
.withHttpEndpoint({ targetPort: 9000 })
.withReference(project)
.withReference(chat)
.withComputeEnvironment({ project });
.asHostedAgent(project);

await builder.build().run();
```

</TabItem>
</Tabs>

In run mode, the hosted-agent configuration configures a local `http` endpoint for the agent. Aspire first checks whether the resource already has an endpoint named `http`. If that endpoint has a target port, Aspire preserves it. If there is no existing `http` target port, Aspire defaults to `8088`.
In run mode, `AsHostedAgent(...)` configures a local `http` endpoint for the agent. Aspire first checks whether the resource already has an endpoint named `http`. If that endpoint has a target port, Aspire preserves it. If there is no existing `http` target port, Aspire defaults to `8088`.

Aspire also injects the selected port as `DEFAULT_AD_PORT`, so hosted-agent apps can bind to the right port:

Expand All @@ -421,7 +421,7 @@ var port = Environment.GetEnvironmentVariable("DEFAULT_AD_PORT") ?? "8088";
builder.WebHost.UseUrls($"http://+:{port}");
```

If your hosted agent listens on a different port, declare the endpoint before configuring the resource as a hosted agent:
If your hosted agent listens on a different port, declare the endpoint before calling `AsHostedAgent(...)`:

<Tabs syncKey="aspire-lang">
<TabItem id="csharp" label="C#">
Expand All @@ -432,7 +432,7 @@ var dotnetWeatherAgent = builder.AddProject<Projects.WeatherAgent_Dotnet>("weath
.WithReference(project).WaitFor(project)
.WithReference(chat).WaitFor(chat);

dotnetWeatherAgent.PublishAsHostedAgent(project);
dotnetWeatherAgent.AsHostedAgent(project);
```

</TabItem>
Expand All @@ -450,19 +450,19 @@ const dotnetWeatherAgent = await builder
.withReference(chat)
.waitFor(chat);

await dotnetWeatherAgent.withComputeEnvironment({ project });
await dotnetWeatherAgent.asHostedAgent(project);
```

</TabItem>
</Tabs>

In run mode, Aspire also adds dashboard URLs for `/responses`, `/liveness`, and `/readiness`, configures `/liveness` as an HTTP health check, adds a dashboard command for sending a message to `/responses`, and enables OpenTelemetry environment variables for agent instrumentation.
In run mode, Aspire also opens the agent's dashboard URL at the selected protocol path, defaults that path to `/responses`, adds a dashboard command for sending a message to the selected path, and enables OpenTelemetry environment variables for agent instrumentation.

For .NET hosted agents, add your Service Defaults project reference and call `builder.AddServiceDefaults()` in the hosted-agent app so logs, metrics, traces, HTTP instrumentation, and OTLP export flow into the Aspire dashboard. Then enable telemetry on the Foundry Responses chat client that backs the Microsoft Agent Framework (MAF) agent.

In publish mode, Aspire creates an `AzureHostedAgentResource` and publishes the container to the project-associated registry.

If you omit the `project` argument, Aspire uses an existing Foundry project from the app model or creates one automatically.
For C# AppHosts, the parameterless `AsHostedAgent()` overload reuses an existing Foundry project from the app model or creates one automatically. TypeScript AppHosts pass the project resource explicitly.

### Add and publish a prompt agent

Expand Down Expand Up @@ -539,7 +539,7 @@ Prompt agents are deployed to Azure AI Foundry even during local development. Lo

## Invoke agents from the Aspire dashboard

Aspire also makes the declared agents easy to try from the dashboard. Prompt agents get a **Send Message** command from `AddPromptAgent(...)`. Hosted agents published with `PublishAsHostedAgent(...)` get a highlighted **Send Message** command that posts to the local `/responses` endpoint, plus dashboard links for `/responses`, `/liveness`, and `/readiness`.
Aspire also makes the declared agents easy to try from the dashboard. Prompt agents get a **Send Message** command from `AddPromptAgent(...)`. Hosted agents configured with `AsHostedAgent(...)` get a highlighted **Send Message** command that posts to the selected protocol path, which defaults to the local `/responses` endpoint.

<ThemeAwareImage
dark={agentSendMessage}
Expand Down
23 changes: 10 additions & 13 deletions src/frontend/src/data/ts-modules/Aspire.Hosting.Foundry.13.4.0-preview.1.26279.5.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1260,25 +1260,22 @@
]
},
{
"name": "withComputeEnvironment",
"capabilityId": "Aspire.Hosting.Foundry/withComputeEnvironmentExecutable",
"qualifiedName": "withComputeEnvironment",
"description": "Configures the resource to run as a hosted agent in Microsoft Foundry. If a project resource is not provided, the method will attempt to find an existing Microsoft Foundry project resource in the application model. If none exists, a new project resource (and its parent account resource) will be created automatically.",
"remarks": "In run mode, this configures the resource with hosted agent endpoints, health checks,\nand OpenTelemetry settings. In publish mode, the resource is deployed as a hosted agent\nin Microsoft Foundry.",
"name": "asHostedAgent",
"capabilityId": "Aspire.Hosting.Foundry/asHostedAgentExecutable",
"qualifiedName": "asHostedAgent",
"description": "Configures the resource to run and publish as a hosted agent in Microsoft Foundry, targeting the specified Foundry project.",
"remarks": "In run mode, this configures the resource with a hosted-agent endpoint, dashboard command,\nand OpenTelemetry settings. In publish mode, the resource is deployed as a hosted agent\nin Microsoft Foundry.",
"kind": "Method",
"signature": "withComputeEnvironment(project?: AzureCognitiveServicesProjectResource, configure?: (obj: HostedAgentConfiguration) => Promise<void>): IResourceWithEndpoints",
"signature": "asHostedAgent(project: AzureCognitiveServicesProjectResource, options?: HostedAgentOptions): IResourceWithEndpoints",
"parameters": [
{
"name": "project",
"type": "AzureCognitiveServicesProjectResource",
"isOptional": true
"type": "AzureCognitiveServicesProjectResource"
},
{
"name": "configure",
"type": "callback",
"isOptional": true,
"isCallback": true,
"callbackSignature": "(obj: HostedAgentConfiguration) => Promise<void>"
"name": "options",
"type": "HostedAgentOptions",
"isOptional": true
}
],
"returnType": "IResourceWithEndpoints",
Expand Down
Loading
Loading