Adds support for foundry prompt agents by tommasodotNET · Pull Request #16353 · microsoft/aspire

tommasodotNET · 2026-04-21T06:47:02Z

Description

Adds support for Foundry Prompt Agents — declarative agents defined in the AppHost that are provisioned on Azure AI Foundry with configurable tools. Agents are deployed during both aspire run and aspire publish, and consumer services can invoke them via the Azure.AI.Projects SDK using standard Aspire connection strings.

AzurePromptAgentResource — resource representing a prompt agent (model + instructions + tools) that deploys to Foundry via the data-plane API
PromptAgentDeployer — lifecycle hook (IDistributedApplicationEventingSubscriber) that deploys agents during aspire run after Azure provisioning completes
PromptAgentConfiguration — wraps DeclarativeAgentDefinition / ProjectsAgentVersionCreationOptions from the SDK

As documented in the README and in the playground sample comments, there is currently no way to deploy a Bing resource on Azure via bicep. Therefore, there is a manual step involved that we cannot avoid if using Bing Grounding Tool.

Running the playground project, the resources tools need will be provisioned on azure and configured on foundry. The prompt agents will be provisioned as well and will provide a link to the agent on Foundry and a quick action button to invoke them from the dashboard (like we do for Hosted Agents):

I've tested both aspire run and aspire deploy commands.

Fixes #16263

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
Does the change require an update in our Aspire docs?
- Yes
  - Link to aspire.dev issue:
    - New issue
- No

Implement core infrastructure for Foundry prompt agents and tools: - IFoundryTool interface and FoundryToolResource base class for tool abstraction - AzurePromptAgentResource with pipeline steps, deploy logic, and connection properties - PromptAgentConfiguration wrapping SDK's PromptAgentDefinition - Built-in tool definitions: CodeInterpreter, FileSearch, WebSearch - AzureAISearchToolResource wrapping AzureSearchResource with project connections - PromptAgentBuilderExtensions with AddPromptAgent, WithTool, and convenience methods - Azure AI Search connection overload in ConnectionBuilderExtensions - OPENAI001 diagnostic suppression for OpenAI.Responses types Tools use ResponseTool (OpenAI.Responses) as the common type since PromptAgentDefinition.Tools is IList<ResponseTool>. AgentTool subtypes (like AzureAISearchAgentTool) have implicit conversion to ResponseTool. Part of: microsoft#16263 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Tests cover: - AddPromptAgent extension method (resource creation, model/instructions, null checks) - WithCodeInterpreter, WithFileSearch, WithWebSearch (built-in tools) - AddAzureAISearchTool (resource-backed tool) - WithTool (adding tools to agents) - WithReference for connection string injection - PromptAgentConfiguration (defaults, metadata, ToAgentVersionCreationOptions) - Interface implementation verification Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

New tools: - BingGroundingToolResource: Resource-backed tool for Bing Search grounding - SharePointToolDefinition: Config-only tool for SharePoint data grounding - FabricToolDefinition: Config-only tool for Microsoft Fabric data agents - AzureFunctionToolDefinition: Azure Functions with queue-based bindings - FunctionToolDefinition: OpenAI function calling (application-defined functions) - ImageGenerationToolDefinition: Image generation (preview, behind [Experimental]) - ComputerToolDefinition: Computer use (preview, behind [Experimental]) Extension methods: - AddBingGroundingTool, WithSharePoint, WithFabric, WithAzureFunction - WithFunction, WithImageGeneration, WithComputerUse Tests: 82 total (all passing), covering all tool types README: Updated with prompt agent usage and tool reference table Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Convert all tool types from IFoundryTool definitions to FoundryToolResource subclasses - Tools are now created at the project level with Add*Tool() methods - Resource-backed tools linked via .WithReference() overloads - AddPromptAgent takes params IResourceBuilder<FoundryToolResource>[] tools - Same-project validation: tools must belong to same project as agent - Keep IFoundryTool as escape hatch via WithCustomTool() on agent - Update all tests (86 passing) and README for new API Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

The Grounding with Bing Search resource cannot be provisioned via Bicep/ARM — users must create it in the Azure portal and reference the resulting Foundry project connection. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Add BingGroundingConnectionProperties with ApiKey auth and category 'GroundingWithBingSearch' matching the ARM template - Add AddBingGroundingConnection() to create connections from a Bing resource ID (Microsoft.Bing/accounts) - Add WithReference(string bingResourceId) overload that auto-creates the correctly-typed connection - Fix duplicate WithRoleAssignments call in AI Search WithReference (AddConnection already handles role assignments) - Update README with simplified Bing examples - Add 3 new tests (89 total, all passing) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- AppHost with two prompt agents: research-agent (Bing + AI Search + code interpreter) and joker-agent (code interpreter + file search) - PromptAgentChat consumer web app using OpenAI Responses API - Added WithReference(IResourceBuilder<ParameterResource>) overload for Bing Grounding tool (supports user secrets for resource ID) - Added AddBingGroundingConnection parameter overload - Added to Aspire.slnx solution - 91 tests passing Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-04-21T06:47:20Z

🚀 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 -- 16353

Or

Run remotely in PowerShell:

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

…tNET/aspire into features/foundry-prompt-agents

Copilot

Pull request overview

Adds first-class Aspire Hosting support for Azure AI Foundry prompt agents (declarative agents + tool catalog), including run-mode deployment via eventing, publish-time deployment via pipeline steps, and a playground sample to demonstrate end-to-end usage.

Changes:

Introduces AzurePromptAgentResource, supporting prompt-agent deployment to Foundry and connection-string consumption by services.
Adds a set of project-level Foundry tool resources (built-in, config-only, and resource-backed) plus builder extensions (Add*Tool, WithReference, etc.).
Updates Foundry project/connection provisioning outputs and bumps Azure AI Projects SDK usage, plus adds tests + a playground sample.

Reviewed changes

Copilot reviewed 32 out of 32 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
tests/Aspire.Hosting.Foundry.Tests/PromptAgentTests.cs	New unit tests covering prompt agent + tool resource creation and reference semantics.
tests/Aspire.Hosting.Foundry.Tests/PromptAgentConfigurationTests.cs	New unit tests validating prompt-agent configuration conversion to SDK options.
tests/Aspire.Hosting.Foundry.Tests/HostedAgentConfigurationTests.cs	Updates tests to the renamed hosted-agent options conversion method.
src/Aspire.Hosting.Foundry/README.md	Documents prompt-agent usage and available tools (plus examples).
src/Aspire.Hosting.Foundry/PromptAgent/PromptAgentDeployer.cs	Run-mode deployer that provisions prompt agents after Azure provisioning completes.
src/Aspire.Hosting.Foundry/PromptAgent/PromptAgentConfiguration.cs	Prompt-agent configuration wrapper around `ProjectsAgentVersionCreationOptions`.
src/Aspire.Hosting.Foundry/PromptAgent/PromptAgentBuilderExtensions.cs	Public builder API for adding prompt agents + tool resources and linking references.
src/Aspire.Hosting.Foundry/PromptAgent/IFoundryTool.cs	Tool extensibility interface for deploy-time conversion to SDK tool types.
src/Aspire.Hosting.Foundry/PromptAgent/FunctionToolDefinition.cs	Tool resource for function-calling tool definitions.
src/Aspire.Hosting.Foundry/PromptAgent/FoundryToolResource.cs	Base resource type for project-level Foundry tool resources.
src/Aspire.Hosting.Foundry/PromptAgent/ConfigOnlyToolDefinitions.cs	Tool resources for SharePoint/Fabric grounding via existing project connections.
src/Aspire.Hosting.Foundry/PromptAgent/BuiltInToolDefinitions.cs	Tool resources for built-in tools (code interpreter, file search, web search, etc.).
src/Aspire.Hosting.Foundry/PromptAgent/BingGroundingToolResource.cs	Tool resource for Bing grounding using a Foundry project connection.
src/Aspire.Hosting.Foundry/PromptAgent/AzurePromptAgentResource.cs	Core prompt-agent resource + publish/run deployment hooks + connection string projection.
src/Aspire.Hosting.Foundry/PromptAgent/AzureFunctionToolDefinition.cs	Tool resource for Azure Function tool definitions (queue bindings).
src/Aspire.Hosting.Foundry/PromptAgent/AzureAISearchToolResource.cs	Tool resource for Azure AI Search grounding via provisioned Foundry connection.
src/Aspire.Hosting.Foundry/Project/ProjectBuilderExtension.cs	Adjusts project provisioning outputs (notably the `name` output format).
src/Aspire.Hosting.Foundry/Project/ConnectionResource.cs	Adds connection properties type for Bing grounding connection category override.
src/Aspire.Hosting.Foundry/Project/ConnectionBuilderExtensions.cs	Updates connection outputs/sharing defaults and adds AI Search + Bing grounding connections.
src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentConfiguration.cs	Migrates hosted-agent configuration to `ProjectsAgentVersionCreationOptions` SDK surface.
src/Aspire.Hosting.Foundry/HostedAgent/AzureHostedAgentResource.cs	Updates hosted-agent deployment path to the new `AgentAdministrationClient` API shape.
src/Aspire.Hosting.Foundry/Aspire.Hosting.Foundry.csproj	Adds additional warning suppressions needed for new preview/evaluation SDK types.
playground/FoundryPromptAgents/aspire.config.json	New playground configuration pointing to the prompt-agent AppHost.
playground/FoundryPromptAgents/PromptAgentChat/PromptAgentChat.csproj	New consumer service sample that calls prompt agents via Azure AI Projects/OpenAI APIs.
playground/FoundryPromptAgents/PromptAgentChat/Program.cs	Sample HTTP endpoints invoking prompt agents using Aspire-injected connection strings.
playground/FoundryPromptAgents/FoundryPromptAgents.AppHost/appsettings.Production.json	Playground AppHost production settings stub.
playground/FoundryPromptAgents/FoundryPromptAgents.AppHost/appsettings.Development.json	Playground AppHost dev settings for Azure provisioning.
playground/FoundryPromptAgents/FoundryPromptAgents.AppHost/Properties/launchSettings.json	Playground launch profiles for local AppHost runs.
playground/FoundryPromptAgents/FoundryPromptAgents.AppHost/FoundryPromptAgents.AppHost.csproj	New AppHost project wiring up Foundry prompt agents + tools + consumer project.
playground/FoundryPromptAgents/FoundryPromptAgents.AppHost/AppHost.cs	Full sample demonstrating prompt agents with Bing + AI Search + code interpreter tools.
Directory.Packages.props	Updates Azure AI Projects dependency versions and adds Azure.AI.Extensions.OpenAI.
Aspire.slnx	Adds the new FoundryPromptAgents playground projects to the solution.

Comments suppressed due to low confidence (1)

playground/FoundryPromptAgents/FoundryPromptAgents.AppHost/appsettings.Development.json:9

This playground appsettings.Development.json includes what appear to be real tenant/subscription identifiers and a specific resource group/location. Even if not secrets, committing real tenant/subscription details is typically treated as sensitive and can cause accidental billing/resource conflicts for others running the playground. Replace with placeholders (e.g., {tenantId}, {subscriptionId}) and/or move these values to user-secrets/documentation so the repo doesn’t contain personal/environment-specific Azure identifiers.

tommasodotNET · 2026-04-21T16:45:47Z

@sebastienros need help with internal nuget feed config, once again 😅

sebastienros · 2026-04-21T17:31:39Z

Each new method/property needs to be exercized in a tests/polyglot corresponding apphost (for all languages). The agent can do that.

…scriptions

…Configuration

…properties

…across implementations

…lass

Add Java codegen inheritance handling for exported base types and cover it with a targeted regression test.\n\nCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…olyglot tests The three WithReference overloads (connection, resource ID, parameter) are mutually exclusive. The polyglot tests were calling all three on the same bingTool instance, which is incorrect. Each reference type now uses its own tool instance. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Replace three separate WithReference methods (withBingConnectionReference, withBingResourceIdReference, withBingParameterReference) with a single WithReference method using [AspireUnion] to accept connection, string, or parameter types. This gives polyglot hosts a single unified withReference method matching the Aspire convention. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Introduce a dedicated BingGroundingConnectionResource type that extends AzureCognitiveServicesProjectConnectionResource. This narrows the WithReference union to only accept Bing-specific connections, preventing callers from accidentally passing a non-Bing connection (e.g., an AI Search connection) to the Bing Grounding tool. The mistake is now caught at compile time rather than surfacing at deployment/runtime. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…tNET/aspire into features/foundry-prompt-agents

…ngToolResource

… tool

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

sebastienros · 2026-04-23T00:27:18Z

        var guid = Guid.Parse(subscriptionId);
-        var encoded = Base64Url.EncodeToString(guid.ToByteArray());
-        return encoded.TrimEnd('=');
+        // Convert hex pairs from the canonical GUID string to bytes (preserves display order)


I wonder if something should have been broken before

i realized this was an issue cause the subscriptionid is part of the prompt agent url when you navigate to them via browser. it's probably the only scenario where we actually want to use this. cause usually the subscriptionid is not part of the project endpoint.

tommasodotNET and others added 8 commits April 20, 2026 19:01

fixes bing and azure ai search tools

eaaaaeb

Copilot AI review requested due to automatic review settings April 21, 2026 06:47

tommasodotNET requested a review from sebastienros as a code owner April 21, 2026 06:47

Merge branch 'main' into features/foundry-prompt-agents

6628245

Copilot started reviewing on behalf of tommasodotNET April 21, 2026 06:47 View session

tommasodotNET added 2 commits April 21, 2026 08:48

-fix

ca1740a

Merge branch 'features/foundry-prompt-agents' of github.com:tommasodo…

e8dc62c

…tNET/aspire into features/foundry-prompt-agents

Copilot AI reviewed Apr 21, 2026

View reviewed changes

addresses copilot review

73b1a35

github-actions Bot mentioned this pull request Apr 21, 2026

[pull requests] Review required #13834

Open

dashboard improvements

864b8da

sebastienros reviewed Apr 21, 2026

View reviewed changes

Comment thread src/Aspire.Hosting.Foundry/Project/ProjectResource.cs Outdated

sebastienros reviewed Apr 21, 2026

View reviewed changes

Comment thread src/Aspire.Hosting.Foundry/PromptAgent/AzureFunctionToolDefinition.cs

sebastienros reviewed Apr 21, 2026

View reviewed changes

Comment thread src/Aspire.Hosting.Foundry/PromptAgent/PromptAgentConfiguration.cs Outdated

sebastienros reviewed Apr 21, 2026

View reviewed changes

Comment thread src/Aspire.Hosting.Foundry/Project/ConnectionBuilderExtensions.cs Outdated

tommasodotNET added 4 commits April 21, 2026 20:40

address code review

1a33ba7

avoid using big endian

3615b82

refactor: update Azure connection methods to use AspireExport with de…

c183b96

…scriptions

refactor: remove unnecessary AspireExport attributes from PromptAgent…

934bf59

…Configuration

tommasodotNET requested a review from sebastienros April 21, 2026 19:06

tommasodotNET and others added 5 commits April 21, 2026 23:28

refactor: update prompt agent tool parameters and remove unnecessary …

e4af31b

…properties

refactor: update prompt agent tool attachment syntax for consistency …

fa73c3f

…across implementations

refactor: add missing AspireExport attribute to FoundryToolResource c…

6a28b19

…lass

refactor: add AspireExport attribute to multiple tool resource classes

94372e9

Fix Java wrapper inheritance

c7f8932

Add Java codegen inheritance handling for exported base types and cover it with a targeted regression test.\n\nCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

sebastienros reviewed Apr 22, 2026

View reviewed changes

Comment thread tests/PolyglotAppHosts/Aspire.Hosting.Foundry/Java/AppHost.java Outdated

Comment thread src/Aspire.Hosting.Foundry/PromptAgent/PromptAgentBuilderExtensions.cs Outdated

sebastienros reviewed Apr 22, 2026

View reviewed changes

Comment thread src/Aspire.Hosting.Foundry/PromptAgent/PromptAgentBuilderExtensions.cs Outdated

tommasodotNET and others added 8 commits April 23, 2026 00:13

Merge branch 'features/foundry-prompt-agents' of github.com:tommasodo…

624544f

…tNET/aspire into features/foundry-prompt-agents

docs: update documentation for WithReference overloads in BingGroundi…

3885b4c

…ngToolResource

refactor: remove redundant WithReference overloads for Bing Grounding…

1763327

… tool

Fix Bing withReference export

335658a

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

sebastienros requested a review from eerhardt April 23, 2026 00:24

sebastienros reviewed Apr 23, 2026

View reviewed changes

github-actions Bot mentioned this pull request Apr 23, 2026

[repo-pulse] 📊 Repo Pulse — Daily Activity Dashboard #16404

Open

Conversation

tommasodotNET commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

github-actions Bot commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tommasodotNET commented Apr 21, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sebastienros commented Apr 21, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sebastienros Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

tommasodotNET Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tommasodotNET commented Apr 21, 2026 •

edited

Loading

github-actions Bot commented Apr 21, 2026 •

edited

Loading