Update Foundry agent builder APIs

[tommasodotNET]

Description

Foundry agent builder APIs should follow the same AppHost conventions as the rest of Aspire. This updates the prompt-agent API so the resource name comes before dependent resources, and renames hosted-agent publishing to use the existing compute-environment pattern.

User-facing usage

C# AppHost:

var chat = project.AddModelDeployment("chat", FoundryModel.OpenAI.Gpt41);

var agent = project.AddPromptAgent("joker-agent", chat,
    instructions: "You are good at telling jokes.");

builder.AddPythonApp("hosted-agent", "../app", "main.py")
    .WithComputeEnvironment(project);

TypeScript AppHost:

await hostedAgent.withComputeEnvironment({
    project,
    configure: async (configuration) => {
        await configuration.description.set("Validation hosted agent");
    }
});

The hosted-agent implementation still configures the same Foundry deployment behavior; the API name now matches the WithComputeEnvironment(...) shape used for other deployment targets. Polyglot validation apphosts, the ATS surface, and the public API baseline were updated to use the new hosted-agent method name.

Breaking changes

This changes preview Foundry APIs:

• AddPromptAgent(model, name, ...) is now AddPromptAgent(name, model, ...).
• PublishAsHostedAgent(project, ...) is now WithComputeEnvironment(project, ...).
• The old AsHostedAgent(...) and RunAsHostedAgent(...) preview APIs were removed from the public API surface. They only threw NotImplementedException.

Users should update existing AppHost code to the new parameter order and method name.

Validation

• dotnet test --project tests/Aspire.Hosting.Foundry.Tests/Aspire.Hosting.Foundry.Tests.csproj --no-launch-profile -- --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true"
• dotnet test --project tests/Aspire.Hosting.Azure.Tests/Aspire.Hosting.Azure.Tests.csproj --no-launch-profile -- --filter-class "*.FoundryExtensionsTests" --filter-class "*.AzureDeployerTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true"
• TypeScript, Java, Go, and Python code generation test projects

Fixes #16707

Checklist

• Is this feature complete?
  • Yes. Ready to ship.
  • No. Follow-up changes expected.
• Are you including unit tests for the changes and scenario tests if relevant?
  • Yes
  • No
• Did you add public API?
  • Yes
    • If yes, did you have an API Review for it?
      • Yes
      • No
    • Did you add <remarks /> and <code /> elements on your triple slash comments?
      • Yes
      • No
  • No
• Does the change make any security assumptions or guarantees?
  • Yes
    • If yes, have you done a threat model and had a security review?
      • Yes
      • No
  • No

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 17499

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 17499"

[Copilot]

Pull request overview

This PR updates the Aspire Hosting Foundry “agent builder” APIs to better match established AppHost conventions: the prompt-agent builder now takes the resource name before dependent resources, and hosted-agent publishing is renamed to the existing “compute environment” pattern.

Changes:

• Reordered AddPromptAgent parameters from (model, name, …) to (name, model, …) and updated call sites/tests.
• Renamed hosted-agent publishing from PublishAsHostedAgent(...) / publishAsHostedAgent(...) to WithComputeEnvironment(...) / withComputeEnvironment(...) across C#, ATS, docs, samples, and polyglot validation apphosts.
• Updated deployment/E2E tests, Azure deployer tests, and playground samples to use the new API names.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/PolyglotAppHosts/Aspire.Hosting.Foundry/TypeScript/apphost.mts	Updates TS polyglot validation apphost to call withComputeEnvironment.
tests/PolyglotAppHosts/Aspire.Hosting.Foundry/Python/apphost.py	Updates Python polyglot validation apphost to call with_compute_environment.
tests/PolyglotAppHosts/Aspire.Hosting.Foundry/Java/AppHost.java	Updates Java polyglot validation apphost to call withComputeEnvironment.
tests/PolyglotAppHosts/Aspire.Hosting.Foundry/Go/apphost.go	Updates Go polyglot validation apphost to call WithComputeEnvironment.
tests/Aspire.Hosting.Foundry.Tests/PromptAgentTests.cs	Updates tests for the new AddPromptAgent(name, model, …) signature.
tests/Aspire.Hosting.Foundry.Tests/HostedAgentExtensionTests.cs	Renames tests to match WithComputeEnvironment and adjusts call sites.
tests/Aspire.Hosting.Azure.Tests/FoundryExtensionsTests.cs	Updates Azure integration tests to use WithComputeEnvironment for Foundry hosted agents.
tests/Aspire.Hosting.Azure.Tests/AzureDeployerTests.cs	Updates deployer tests to use the new hosted-agent method name.
tests/Aspire.Deployment.EndToEnd.Tests/FoundryHostedAgentDeploymentTests.cs	Updates E2E deployment test content/comments and call sites for the rename.
src/Aspire.Hosting.Foundry/README.md	Updates README usage snippet to WithComputeEnvironment(project).
src/Aspire.Hosting.Foundry/PromptAgent/PromptAgentBuilderExtensions.cs	Updates XML docs/example and signature for AddPromptAgent(name, model, …).
src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentBuilderExtension.cs	Renames the hosted-agent extension to WithComputeEnvironment and updates ATS export name.
src/Aspire.Hosting.Foundry/api/Aspire.Hosting.Foundry.ats.txt	Updates ATS surface to export withComputeEnvironmentExecutable.
playground/FoundryAgents/FoundryAgents.AppHost/AppHost.cs	Updates playground AppHost to the new Foundry APIs and sample resource names.
playground/FoundryAgents/DotNetHostedAgent/Program.cs	Updates env var names/error strings to match new playground project resource name.
playground/FoundryAgents/app/main.py	Updates env var lookup to match new playground project resource name.
playground/FoundryAgentEnterprise/FoundryAgentEnterprise.AppHost/AppHost.cs	Updates enterprise playground AppHost call site to WithComputeEnvironment.

[davidfowl]

@sebastienros send changes to @tommasodotNET's branch. We need to get this in today.

[sebastienros]

I need a raise