Add Foundry hosted agent protocol selection - #17732
Merged
David Fowler (davidfowl) merged 4 commits intoMay 31, 2026
Merged
Conversation
Support configuring Foundry hosted agent protocols for publish output and local run-mode dashboard commands, including TypeScript AppHost coverage for the exported DTO shape. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
David Fowler (davidfowl)
requested a review
from Sébastien Ros (sebastienros)
as a code owner
May 30, 2026 16:03
Contributor
|
🚀 Dogfood this PR with:
curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 17732Or
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 17732" |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds first-class protocol selection for Microsoft Foundry hosted agents so the selected ingress protocol is carried through both local run-mode dashboard interactions and publish output, enabling validation for either the responses or invocations protocol (including from TypeScript/polyglot AppHosts).
Changes:
- Adds protocol-aware run-mode URL labeling, HTTP command path selection, and request/response handling for hosted agents.
- Extends the polyglot-exported hosted agent options DTO with
protocolsand maps it toContainerProtocolVersionsfor publish output. - Adds coverage in Foundry hosting tests and the TypeScript validation AppHost for the invocations protocol path.
Show a summary per file
| File | Description |
|---|---|
| tests/PolyglotAppHosts/Aspire.Hosting.Foundry/TypeScript/apphost.mts | Adds /invocations endpoint handling and sets protocols in the exported hosted agent options for validation. |
| tests/Aspire.Hosting.Foundry.Tests/HostedAgentExtensionTests.cs | Adds run-mode and options-mapping tests validating invocations protocol selection. |
| src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentOptions.cs | Introduces Protocols DTO and maps it onto Azure SDK ContainerProtocolVersions with validation. |
| src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentBuilderExtension.cs | Makes run-mode commands/URLs protocol-aware and threads configuration through run/publish paths. |
Copilot's findings
- Files reviewed: 4/4 changed files
- Comments generated: 3
Improve hosted agent protocol validation parameter names and add run-mode context when configuration callbacks fail during protocol inference. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Jose Perez Rodriguez (joperezr)
approved these changes
May 30, 2026
Collaborator
Author
PR #17732 Foundry hosted-agent deployment validationPR build under test
ScenarioCreated a temporary C# file-based AppHost using the PR build and configuration.ContainerProtocolVersions.Clear();
configuration.ContainerProtocolVersions.Add(new ProtocolVersionRecord(ProjectsAgentProtocol.Invocations, "1.0.0"));Deployment result
The first attempt in VerificationListed the deployed agents through the Foundry Agents REST API: {
"id": "hosted-agent-ha:2",
"status": "active",
"protocols": [
{
"protocol": "invocations",
"version": "1.0.0"
}
]
}Invoked the deployed hosted agent through the Foundry invocations endpoint: POST /agents/hosted-agent-ha/endpoint/protocols/invocations?api-version=v1
HTTP/2 200
{"response":"hello from deployed PR 17732 hosted agent"}Checked that the responses endpoint is not exposed for the invocations-only agent: POST /agents/hosted-agent-ha/endpoint/protocols/openai/responses?api-version=v1
HTTP/2 400The service returned: Cleanup statusTemporary Azure resources created for this validation were deleted after the run. |
Update hosted agent deployment to patch the Foundry agent endpoint protocols after creating a hosted-agent version, so endpoint routing matches the configured container protocol versions. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Collaborator
Author
PR Testing ReportPR Information
CLI Version Verification
Changes AnalyzedFiles Changed
Change Categories
Test App Code UsedTypeScript AppHostimport { AzureContainerRegistryRole, createBuilder } from './.aspire/modules/aspire.mjs';
const builder = await createBuilder();
const registry = await builder.addAzureContainerRegistry('registry');
const foundry = await builder.addFoundry('foundry');
const project = foundry.addProject('project');
project.withAzureContainerRegistry(registry);
project.addContainerRegistryConnection(registry);
project.withContainerRegistryRoleAssignments(registry, [AzureContainerRegistryRole.AcrPull]);
const hostedAgent = builder
.addDockerfile('agent-ha', './agent')
.withHttpEndpoint({ targetPort: 8088, env: 'DEFAULT_AD_PORT' });
hostedAgent.asHostedAgent(project, {
protocols: [{ protocol: 'invocations', version: '1.0.0' }]
});
await builder.build().runAsync();Hosted agent containerFROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY main.py .
EXPOSE 8088
CMD ["python", "main.py"]azure-ai-agentserver-invocations==1.0.0b4from azure.ai.agentserver.invocations import AsyncAgentsApp, Request, Response, StreamingResponse
app = AsyncAgentsApp()
@app.task_route()
async def invoke(request: Request) -> Response:
message = request.data.get("message", "")
return Response(data={
"protocol": "invocations",
"scenario": "pr-17732-typescript-apphost",
"value": f"TypeScript hosted agent processed: {message}"
})
@app.task_route(streaming=True)
async def invoke_streaming(request: Request) -> StreamingResponse:
async def stream():
yield {"delta": request.data.get("message", "")}
return StreamingResponse(data=stream())
if __name__ == "__main__":
app.run()Test Scenarios ExecutedScenario 1: TypeScript AppHost deploys an invocations hosted agentObjective: Verify a TypeScript AppHost can configure a Foundry hosted agent with Steps:
Evidence:
Scenario 2: Deploy synchronizes endpoint routing from a stale protocol stateObjective: Verify deployment updates the existing hosted-agent endpoint protocol metadata instead of only creating a version with Steps:
Expected Unhappy-Path Outcome: Deployment should recover from stale endpoint metadata by restoring the endpoint to Evidence:
Scenario 3: Responses route is safely rejected for an invocations-only hosted agentObjective: Verify the hosted agent does not accept the OpenAI responses protocol when the AppHost selected only Steps:
Expected Unhappy-Path Outcome: The responses route should return a non-success status for an invocations-only agent. Evidence:
Summary
Cleanup
Overall ResultPR VERIFIED The TypeScript AppHost scenario validates the new polyglot |
Contributor
|
Re-running the failed jobs in the CI workflow for this pull request because 2 jobs were identified as retry-safe transient failures in the CI run attempt.
Matched test failure patterns (1 test)
|
Salman Quazi (splusq)
approved these changes
May 31, 2026
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
|
Re-running the failed jobs in the CI workflow for this pull request because 1 job was identified as retry-safe transient failures in the CI run attempt.
|
Contributor
|
❓ CLI E2E Tests unknown — 110 passed, 0 failed, 2 unknown (commit View all recordings
📹 Recordings uploaded automatically from CI run #26700080433 |
Collaborator
Author
PR #17732 e2e validation: Foundry invocations hosted agentsValidated the PR dogfood build end to end for Foundry hosted agents using the Build under test
Scenario 1: TypeScript AppHost configures an invocations hosted agentA TypeScript AppHost configured the hosted agent with: await hostedAgent.asHostedAgent(project, {
protocols: [{ protocol: 'invocations', version: '1.0.0' }]
});Result: passed. The deployed hosted-agent version had the expected container protocol configuration, and the agent endpoint metadata advertised only Scenario 2: Endpoint protocol metadata is synchronized during deployA previous deploy produced a hosted-agent version with Result: passed. The endpoint changed from stale Scenario 3: Minimal Python
|
David Fowler (davidfowl)
merged commit May 31, 2026
9c260c2
into
release/13.4
610 of 617 checks passed
aspire-repo-bot Bot
added a commit
to microsoft/aspire.dev
that referenced
this pull request
May 31, 2026
Documents the new protocol selection feature added in microsoft/aspire#17732. Adds a 'Select the hosted agent protocol' subsection showing how to configure ContainerProtocolVersions (C#) and protocols (TypeScript) on AsHostedAgent/asHostedAgent. Updates the dashboard section to reflect that the Send Message command and endpoint URLs adapt to the selected protocol (responses vs. invocations). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
|
Pull request created: #1141
|
Contributor
|
📝 Documentation has been drafted in microsoft/aspire.dev#1141 targeting Updated
Note This draft PR needs human review before merging. |
This was referenced May 31, 2026
14 tasks
Jose Perez Rodriguez (joperezr)
added a commit
that referenced
this pull request
Jun 2, 2026
The merge auto-pulled release/13.4's api/*.cs and api/*.ats.txt baselines for 56 pre-existing
packages. These baselines no longer match main's source code (e.g., Foundry's source has
[AspireExport("asHostedAgent")] from #17671 but the release baseline says "asHostedAgentExecutable",
and the release baseline still references the WithComputeEnvironment method that was renamed to
the AsHostedAgent overloads in #17732).
Per repo convention (.github/copilot-instructions.md): api files are regenerated as part of the
release process, not during individual PRs. Reverting to main's state matches what @davidfowl's
forward-port PR #17775 does, and lets the next release run regenerate them.
The 2 net-new api files for the new Aspire.Hosting.Blazor and Aspire.Hosting.Go integrations
are kept as-is (they didn't exist on main).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
pull Bot
pushed a commit
to tooniez/aspire
that referenced
this pull request
Jun 2, 2026
Brings 43 release-branch commits forward onto main now that 13.4.0 has shipped. This PR replaces the original automated merge (microsoft#17804) which had to be closed so that conflict resolution and post-merge cleanups could be made on a non-protected branch. Conflict resolution summary (33 files): * Equivalent backports (took main's commit identity): ChannelUpdateWorkflowTests, LoggingHelpersTests, the four extension test files, AspireEditorCommandProvider, appHostDiscovery. * Release-only forwards (preserved): microsoft#17732 / microsoft#17756 Foundry hosted-agent protocol selection and cross-compute-environment endpoint references, microsoft#17573 stabilize PrebuiltAppHostServer staging globalPackagesFolder path, microsoft#17743 staging-identity CLI darc feed routing. * Main-only forwards (preserved): microsoft#17506 Show discovered AppHosts in Aspire pane, microsoft#17547 Localize Aspire skills metadata errors, microsoft#17801 VS Code v1.12.0, microsoft#17297 Aspire CLI npm package release integration, microsoft#17576 TerminalRun IAsyncDisposable, microsoft#17721 / microsoft#17723 VS Code telemetry, microsoft#17671 ATS baseline fix (re-applied manually on top of Foundry source taken from release). * Hybrid (manually spliced): docs/contributing.md - kept main's restructured layout and inserted release's staging-validation paragraph; HostedAgentBuilder- Extension - took release base then re-applied microsoft#17671 asHostedAgent rename; UpdateCommandTests - took main and injected microsoft#17743's OverrideCliInformationalVersionConfigKey block. Post-merge cleanups included in this PR: * eng/Versions.props: revert StabilizePackageVersion to false (was flipped to true on release/13.4 by microsoft#17520 for shipping 13.4.0; main must stay in preview mode). * .github/workflows/generate-api-diffs.yml: retarget back to main (was pointed at release/13.4 by microsoft#17696 release prep). * .github/workflows/backmerge-release.yml: update from release/13.3 to release/13.4 (was stale - missed the 13.4 release-time bump). * .github/workflows/milestone-assignment.yml: audited - already correct (main -> 13.5, release/13.4 -> 13.4.x); no change. This merge commit must be preserved - do not squash on merge. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Foundry hosted agents need to carry the selected protocol through both local development and Azure publish output so users can validate agents that use either the responses or invocations protocol. This adds protocol-aware run-mode dashboard commands and publishes configured
container_protocol_versions, while keeping C# on the existingAction<HostedAgentConfiguration>configuration path.TypeScript/polyglot AppHosts can set protocols through the exported hosted agent options DTO because that path cannot expose Azure SDK types directly.
User-facing usage
C# AppHost:
TypeScript AppHost:
Validation
Fixes #17730
Checklist
<remarks />and<code />elements on your triple slash comments?