[docs] Foundry hosted agent protocol selection

[aspire-repo-bot]

Documents changes from microsoft/aspire#17732 by @davidfowl.

Targeting release/13.4 based on the source PR milestone 13.4.

Why this PR is needed

PR microsoft/aspire#17732 adds first-class protocol selection for Microsoft Foundry hosted agents. Users can now configure whether their hosted agent uses the responses or invocations protocol via AsHostedAgent/asHostedAgent. This selection affects both run-mode behavior (dashboard URLs, the Send Message command path) and publish-mode output (container_protocol_versions in the Foundry hosted agent definition). The existing docs hardcoded /responses and did not document how to change the protocol.

What was changed

• Added a new Select the hosted agent protocol subsection under Publish a hosted agent to Azure AI Foundry in azure-ai-foundry-host.mdx, with C# and TypeScript code examples showing how to configure ContainerProtocolVersions / protocols.
• Updated the Invoke agents from the Aspire dashboard section to note that the dashboard endpoint and Send Message command use the configured protocol path (/responses or /invocations) rather than always /responses.

Files changed

• src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host.mdx — updated existing page

Generated by PR Documentation Check for issue #17732 · ● 18M · ◷

[Copilot]

Pull request overview

This PR updates the Azure AI Foundry hosting documentation to describe hosted agent protocol selection and how it affects dashboard routing and publish output.

Changes:

• Adds a new hosted agent protocol selection subsection with C# and TypeScript examples.
• Updates dashboard invocation guidance to describe /responses vs /invocations protocol endpoints.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[David Pine (IEvangelist)]

Thanks for checking this. I’m leaving the C# snippet as-is because the source-of-truth branch confirms this API exists: microsoft/aspire@2574ef57e97fc393aff67592fd442afca6a6d02f (release/13.4) exposes AsHostedAgent<T>(..., Action<HostedAgentConfiguration>? configure = null) at src/Aspire.Hosting.Foundry/api/Aspire.Hosting.Foundry.cs:99-101, and HostedAgentConfiguration.ContainerProtocolVersions at src/Aspire.Hosting.Foundry/api/Aspire.Hosting.Foundry.cs:981-982. The docs metadata appears stale for this C# surface, but the checked-out source branch confirms the PR text is correct.

[David Pine (IEvangelist)]

Updating the source-truth citation for this rejection: microsoft/aspire@9c260c29a6c3f9a63750a518a56440a3d855fb8f on release/13.4 includes the C# API in src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentBuilderExtension.cs; AsHostedAgent accepts configuration that updates ContainerProtocolVersions, and src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentOptions.cs exposes the corresponding protocol options. The PR text for the C# sample remains correct as written, so I am leaving this unresolved for reviewer follow-up.

[David Pine (IEvangelist)]

Automated docs-accuracy review

Phase A source of truth: microsoft/aspire branch release/13.4 @ 9c260c29a6c3f9a63750a518a56440a3d855fb8f (PR head 69a496f9). Top commit on release/13.4 is Add Foundry hosted agent protocol selection (#17732), which is the source PR documented here.

Phase A — Claim verification: 13 claims extracted → 10 verified, 3 verified-with-nuance, 0 contradicted, 0 unverifiable.

Phase B — Doc-tester (Playwright on local aspire run build of the docs site): exercised /integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host/ (C# and TypeScript tabs, in-page anchor #select-the-hosted-agent-protocol) → 1 critical issue, 1 warning, 1 reasserted-nuance.

Verdict: COMMENT (a critical Phase B issue is flagged inline below for follow-up; Phase A had no contradictions, so I'm not blocking the merge with REQUEST_CHANGES — but the inline TS-error finding is worth addressing before publish).

---

Phase A — Claim verification details

All non-narrative claims map cleanly to source on release/13.4. No contradictions or unverifiable items.

Verified claims (10)

#	Claim	Evidence (microsoft/aspire@release/13.4)
C1	Default protocol is responses	src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentConfiguration.cs:51-53 — ContainerProtocolVersions = [new ProtocolVersionRecord(ProjectsAgentProtocol.Responses, "1.0.0")]
C3	C# example .AsHostedAgent(project, configuration => { configuration.ContainerProtocolVersions.Clear(); configuration.ContainerProtocolVersions.Add(new ProtocolVersionRecord(ProjectsAgentProtocol.Invocations, "1.0.0")); });	Exact match in tests/Aspire.Hosting.Foundry.Tests/HostedAgentExtensionTests.cs:91-96; overload defined at src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentBuilderExtension.cs:91-98
C4	TS example asHostedAgent(project, { protocols: [{ protocol: 'invocations', version: '1.0.0' }] })	Matches tests/PolyglotAppHosts/Aspire.Hosting.Foundry/TypeScript/apphost.mts:118-125; DTO at HostedAgentOptions.cs:58 (IList<HostedAgentProtocolVersion> Protocols)
C5	"First entry selects the endpoint"	HostedAgentBuilderExtension.cs:333 — return configuration.ContainerProtocolVersions.FirstOrDefault()?.Protocol.ToString();
C6	Labels run-mode endpoint "Invocations Endpoint"	HostedAgentBuilderExtension.cs:438 — EndpointDisplayText = "Invocations Endpoint"
C7	Routes dashboard URL to /invocations instead of /responses	HostedAgentBuilderExtension.cs:197, 428, 437 — Path = protocol.Path and the two HostedAgentRunProtocol definitions
C8	Send Message command POSTs to the protocol path	HostedAgentBuilderExtension.cs:200-206 — WithHttpCommand(path: protocol.Path, displayName: "Send Message", commandOptions: new() { Method = HttpMethod.Post, ... })
C10	Multiple versions: first used in run mode, all forwarded in publish mode	HostedAgentBuilderExtension.cs:333 (first only) + HostedAgentConfiguration.cs:121-122 (whole list passed to HostedAgentDefinition)
C11	C# AppHosts use AsHostedAgent with Action<HostedAgentConfiguration> to expose ContainerProtocolVersions, Tools, ContentFilterConfiguration	HostedAgentBuilderExtension.cs:91-98 + HostedAgentConfiguration public surface
C12	TS/polyglot AppHosts use protocols property on options object	HostedAgentOptions.cs:58 Protocols with [AspireDto] → camelCased protocols

Verified with nuance (3)

C2 — "Selection affects publish mode (the container_protocol_versions field)"

• Run-mode portion verified in HostedAgentBuilderExtension.cs:174-309.
• The exact wire field name container_protocol_versions belongs to Azure.AI.Projects.Agents.HostedAgentDefinition (Azure SDK type) and is not in the microsoft/aspire source. The C# call site at HostedAgentConfiguration.cs:121 passes the list as new HostedAgentDefinition(ContainerProtocolVersions, ...). Snake-case is plausible per Foundry REST conventions but I couldn't verify the wire field literal from this repo.

C9 — "Emits protocol versions in container_protocol_versions field at publish time"

• The list is passed to HostedAgentDefinition via HostedAgentConfiguration.cs:121-127, called from AzureHostedAgentResource.cs:156-162 (DeployAsync → CreateAgentVersionAsync).
• Strictly speaking this happens during the deploy pipeline step, not at aspire publish manifest emission (the manifest writer at AzureHostedAgentResource.cs:127-136 only writes kind: hosted and target). "Publish mode" reasonably spans both phases in Aspire vocabulary, so this is fine, just imprecise.

C13 — Edited line ~610: "dashboard links for the protocol endpoint, /liveness, and /readiness"

• The highlighted Send Message command and the dashboard URL for the protocol endpoint are verified (HostedAgentBuilderExtension.cs:200-209, and WithUrls at 187-199 sets only the "http" endpoint URL to the protocol path).
• No code in AsHostedAgent adds /liveness or /readiness as dashboard URLs. Those paths are only implemented by the agent itself (e.g. playground/FoundryAgents/DotNetHostedAgent/Program.cs:67-68).
• This phrasing also appears in an unchanged pre-existing sentence (line 459: "In run mode, Aspire also adds dashboard URLs for /responses, /liveness, and /readiness...") so the PR isn't introducing it, only re-asserting it in the rewritten paragraph. Worth tightening, but not a blocker.

---

Phase B — Doc-tester findings (Playwright, no source-code reads)

Pages exercised

• http://localhost:53174/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host/ (rendered from the PR branch via local aspire run)
• Both C# and TypeScript tabs of the new Select the hosted agent protocol section
• Direct anchor navigation: #select-the-hosted-agent-protocol — link works
• Cross-checked the surrounding pre-existing TS twoslash samples on the same page (no errors in any of them)

Summary

Category	Passed	Failed	Warnings
Page renders / anchor / tab sync	4	0	0
Code samples (rendered)	1 (C#)	1 (TS)	1
Surrounding prose clarity	2	0	1

🚨 Critical — TypeScript sample renders a visible TS type error

The new TypeScript snippet in Select the hosted agent protocol is marked twoslash, so Astro runs it through the TS compiler at build time and overlays compiler diagnostics in the rendered page. The page shows a red error annotation directly under the .asHostedAgent(...) line:

Error ts(2339) ― Property 'asHostedAgent' does not exist on type 'ProjectResource'.

The same .asHostedAgent(project, { protocols: [...] }) shape compiles cleanly when run against the polyglot apphost in microsoft/aspire (Phase A C4), so the method itself exists — the issue appears to be that this snippet's imports are insufficient to bring the Foundry-specific extension into scope. The only import is:

import { createBuilder } from './.aspire/modules/aspire.mjs';

Other TS twoslash samples on the same page render with no errors. This is the only snippet with a visible TS error.

Impact on a new user: anyone landing on the new section sees a red Error ts(2339) annotation embedded in the very code they're being told to copy. It looks like the documented API is broken or the example is wrong.

Evidence: see the inline review comment on the TS code fence (lines 497–518 of the .mdx).

⚠️ Warning — Missing C# using directives in the example

The C# snippet uses three types that the docs don't tell the reader where to import:

• ProtocolVersionRecord
• ProjectsAgentProtocol
• Projects.Agent (the <Projects.Agent> generic argument on AddProject)

A new user pasting this into an AppHost will get unresolved-type errors and won't know which using to add. Comparable snippets elsewhere on the page tend to also omit usings, so this isn't unique to the PR — but the new sample introduces two new types (ProtocolVersionRecord, ProjectsAgentProtocol) that aren't referenced anywhere else on the page, so the knowledge gap is sharper here.

Suggestion: either add a one-line using Azure.AI.Projects.Agents; (or the correct namespace — verify against the Foundry hosting package) on the snippet, or add a sentence in the prose pointing users at the namespace that ships these types.

ℹ️ Pre-existing nuance carried into the edited "Invoke agents from the Aspire dashboard" paragraph

Line 610 (edited by this PR) re-asserts that the dashboard exposes "dashboard links for the protocol endpoint, /liveness, and /readiness". As a doc-tester I can't confirm from the rendered page who actually wires up the /liveness and /readiness dashboard links — see Phase A C13 for the source-of-truth nuance: the AsHostedAgent extension wires the protocol endpoint URL; /liveness and /readiness are paths the agent implements but aren't separately added as dashboard URLs by the extension. The sentence reads as though all three are added by Aspire. The PR didn't introduce this wording, but rewording it slightly while you're in the area would tighten the doc.

✅ Passed

• Tab sync (syncKey='aspire-lang') works: switching to TypeScript on the new section keeps the rest of the page on TypeScript.
• The in-page TOC entry Select the hosted agent protocol scrolls to the heading.
• Heading hierarchy ### Select the hosted agent protocol fits cleanly under the existing ## Publish a hosted agent to Azure AI Foundry ancestor.
• :::note admonition explaining the C# Action<HostedAgentConfiguration> vs. TS protocols split renders correctly.
• The C# example renders cleanly — no syntax-highlighting glitches, no overlong copy button text.

Knowledge gaps

• TS extension import: the note says polyglot AppHosts "use the protocols property on the hosted agent options object" but doesn't say what makes .asHostedAgent available on ProjectResource in TS. Given the rendered TS error, this is now an actively confusing gap — a new user can't tell whether they need an additional import, an aspire add step, or whether the example is just wrong.
• container_protocol_versions wire format: the prose references this snake-case field as the publish-mode payload but doesn't tell users where they'd see it (manifest? deployed Foundry agent definition? Azure portal?). Not blocking, but a "see also" link would help.

---

Recommendation

Fix the TypeScript twoslash error before publishing — it's the kind of thing that will be the first impression for anyone reading the new section. Everything else above is COMMENT-level.

[aspire-repo-bot]

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1141. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

This comment updates automatically when a new frontend build artifact is uploaded.