[docs] Document asHostedAgentWithProtocol for polyglot hosted agents

[aspire-repo-bot]

Documents changes from microsoft/aspire#18980

@sebastienros

Targeting release/13.5 based on the source PR milestone 13.5 (exact match on microsoft/aspire.dev).

Why

microsoft/aspire#18980 restores ATS compatibility for the polyglot asHostedAgent(project, options?) capability by defaulting it to the Responses protocol version 2.0.0, and introduces a new additive asHostedAgentWithProtocol capability for polyglot hosts that need to select an explicit protocol/version (mirroring the existing C# AsHostedAgent(project, protocol, protocolVersion, ...) overload). The Azure AI Foundry hosting integration reference page documented AsHostedAgent/asHostedAgent but had no mention of protocol selection at all, so the new capability and its C# equivalent overload were undocumented.

What changed

Added a new "Select a hosted agent protocol" subsection to azure-ai-foundry-host.mdx, immediately after the existing "Add a hosted agent to Azure AI Foundry" section, covering:

• That AsHostedAgent/asHostedAgent default to Responses 2.0.0.
• How to select an explicit protocol/version: the C# AsHostedAgent(project, protocol, protocolVersion) overload, and the polyglot asHostedAgentWithProtocol(project, protocol, protocolVersion) capability.
• That both the defaulted and explicit-protocol entry points are exported to polyglot app hosts, so existing AppHosts calling asHostedAgent(project, options?) keep working unchanged.

Files modified

• src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host.mdx (existing page updated, no new pages created)

Generated by PR Documentation Check · auto · 67 AIC · ⌖ 7.03 AIC · ⊞ 19.6K · ◷

[aspire-repo-bot]

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1475. 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.

[Copilot]

Pull request overview

This PR updates the Azure AI Foundry hosting integration documentation to cover protocol selection for hosted agents, aligning the docs with the recently introduced asHostedAgentWithProtocol capability and the C# AsHostedAgent(project, protocol, protocolVersion) overload.

Changes:

• Adds a new “Select a hosted agent protocol” subsection describing the default Responses 2.0.0 protocol behavior.
• Documents how to explicitly select a protocol/version in both C# and TypeScript, including an example using the Invocations protocol.
• Clarifies that existing polyglot AppHosts using asHostedAgent(project, options?) continue to work unchanged with the default protocol/version.

Suppressed comments (1)

src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host.mdx:495

• For consistency with the rest of the docs, consider capitalizing “AppHosts” here as well (this appears to be used as a proper term throughout the site).

The defaulted `asHostedAgent` entry point and the explicit `asHostedAgentWithProtocol` entry point are both exported to polyglot app hosts, so existing AppHosts that call `asHostedAgent(project, options?)` continue to work unchanged with the Responses `2.0.0` default. Reach for `asHostedAgentWithProtocol` only when you need a protocol or version other than the default.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Adam Ratzman (adamint)]

"..\\agent" is a literal backslash path on macOS/Linux, so this C# sample fails to find the parent agent directory there. Could we use "../agent", matching the TypeScript sample? The earlier C# sample has the same issue.

[Alistair Matthews (alistairmatthews)]

Please consider my suggestion.

[David Pine (IEvangelist)]

🤖 Automated docs-accuracy review

Source of truth: microsoft/aspire branch release/13.5 @ 8ab6999850d96e0023670799edbd4bdc245ad63c

• Phase A — Claims verification (read microsoft/aspire): 7 claims extracted → ✅ 4 verified · ❌ 2 contradicted · ⚪ 1 narrative (not blocking).
• Phase B — doc-tester (blind user, no source consulted): exercised /integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host/#select-a-hosted-agent-protocol, rendered locally from this PR''s head. Page renders cleanly (0 console errors/warnings). 0 critical · 2 warnings/knowledge-gaps.

Verdict: 🔴 Request changes. The C# tab and the "defaults to Responses 2.0.0" statements are accurate and verified. However, the TypeScript example and the sentence claiming both entry points are "exported to polyglot AppHosts" document an API (asHostedAgentWithProtocol + the HostedAgentProtocol enum) that is not present in the generated polyglot surface on release/13.5. See the two inline comments.

---

Phase A — Claim verification

Inline comments are anchored to the two contradicted locations (the TypeScript sample and the "both exported to polyglot" paragraph).

✅ Verified & verified-with-nuance claims (4) — evidence

#	Claim	Verdict	Evidence (microsoft/aspire@8ab6999850)
C1	AsHostedAgent (C#) and asHostedAgent (polyglot) default to the Responses protocol version 2.0.0.	✅ verified	HostedAgent/HostedAgentBuilderExtension.cs:92 & :145-146 (ConfigureAsHostedAgent(..., HostedAgentProtocol.Responses, AzureHostedAgentResource.DefaultResponsesProtocolVersion, ...)); HostedAgent/AzureHostedAgentResource.cs:32 (DefaultResponsesProtocolVersion = "2.0.0"); api/Aspire.Hosting.Foundry.ats.txt:253 (asHostedAgent(project, options?)).
C2	The HostedAgentProtocol enum exposes Responses and Invocations.	✅ verified	HostedAgent/HostedAgentProtocol.cs:9-20 (enum HostedAgentProtocol { Responses, Invocations }).
C3	C# AsHostedAgent(project, HostedAgentProtocol.Invocations, "1.0.0") overload exists, and the AddPythonApp(...).WithReference(...).AsHostedAgent(...) chain compiles.	✅ verified	Public overload AsHostedAgent<T>(IResourceBuilder<AzureCognitiveServicesProjectResource>?, HostedAgentProtocol, string, Action<HostedAgentConfiguration>? = null) at HostedAgent/HostedAgentBuilderExtension.cs:194-203. PythonAppResource : ExecutableResource which implements IResourceWithEndpoints, IResourceWithEnvironment, IComputeResource — satisfies the generic constraint.
C4	"Pass a protocol and version explicitly in C#."	✅ verified	Same overload as C3.

⚪ Narrative (1) — noted, not blocking

• C7 — "the Invocations protocol used by some Microsoft Agent Framework (MAF) agents." The HostedAgentProtocol.Invocations value exists, but the MAF association is prose not verifiable from source. Not blocking.

---

Phase B — doc-tester results (blind-user pass, no source code consulted)

Route exercised: /integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host/#select-a-hosted-agent-protocol (rendered locally via astro dev from this PR''s head content).

Rendering: Clean. The new ### Select a hosted agent protocol section appears in the On this page TOC; the C#/TypeScript tabs render and sync via aspire-lang; 0 console errors, 0 warnings.

✅ Passed checks

• Section renders and its anchor navigates correctly.
• Prose clearly states the Responses 2.0.0 default and when to override it.
• The C# and TypeScript tabs are parallel and structurally consistent.
• The project / chat variables used in both samples are established earlier on the page, so a reader following top-to-bottom has them in scope.

⚠️ Warnings / knowledge gaps

1. The TypeScript snippet uses HostedAgentProtocol.Invocations and asHostedAgentWithProtocol but shows no import statement, and — unlike the page''s other TypeScript AppHost examples (which are twoslash and import from ./.aspire/modules/aspire.mjs) — this block is not twoslash, so it is not type-checked by the site and a polyglot reader cannot tell where HostedAgentProtocol comes from. (This is the visible symptom of the Phase A contradiction.)
2. No cross-reference/link to an API-reference entry for asHostedAgentWithProtocol / HostedAgentProtocol that would let a reader confirm the surface.

Knowledge boundary: As a blind user I could not compile the TypeScript block (not type-checked on the site) nor run an Azure Foundry hosted-agent deployment in this environment, so the TypeScript example could not be validated from the docs alone — flagged rather than filled.

Critical issues: none from the rendering/blind-user pass.

---

_{Automated hourly docs-accuracy reviewer. Phase A verifies claims against microsoft/aspire source; Phase B validates the rendered docs blind to source; this review merges both.}

[David Pine (IEvangelist)]

❌ Contradicted (Phase A) — polyglot API not in the generated surface

This TypeScript sample calls asHostedAgentWithProtocol(...) and references HostedAgentProtocol.Invocations, but neither is present in the polyglot/TypeScript surface on release/13.5:

• The C# source does declare [AspireExport("asHostedAgentWithProtocol")] (src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentBuilderExtension.cs:162) — but the generated capability dump src/Aspire.Hosting.Foundry/api/Aspire.Hosting.Foundry.ats.txt (header: Generated by: aspire sdk dump --format ci) lists only asHostedAgent(project, options?) (line 253); asHostedAgentWithProtocol is absent.
• The HostedAgentProtocol enum is not projected to polyglot — the file''s "Enum Types" section exposes only FoundryRole. So HostedAgentProtocol.Invocations isn''t available to TypeScript AppHosts.
• Source and baseline were committed together (0028557bee), so the baseline is not stale. This repo''s own generated TS bindings agree: src/frontend/src/data/twoslash/aspire.d.ts and src/frontend/src/data/ts-modules/Aspire.Hosting.Foundry.*.json contain asHostedAgent but zero references to asHostedAgentWithProtocol or HostedAgentProtocol.

As written, this snippet won''t resolve for a polyglot AppHost. Please verify against the generated ats.txt / TS bindings: if the export is intended for polyglot, the HostedAgentProtocol enum must be exposed and the bindings regenerated; otherwise correct the TypeScript example. (The C# tab above is accurate.)

[David Pine (IEvangelist)]

❌ Contradicted (Phase A) — "both exported to polyglot AppHosts"

The asHostedAgent(project, options?) half is correct: it is exported and defaults to Responses 2.0.0 — verified (api/Aspire.Hosting.Foundry.ats.txt:253; AsHostedAgentForExport, HostedAgent/HostedAgentBuilderExtension.cs:132-148).

But asHostedAgentWithProtocol is not in the generated polyglot capability dump on release/13.5 — only the C# [AspireExport] attribute exists in source (see the inline comment on the TypeScript sample above). So the statement that both entry points "are both exported to polyglot AppHosts" is not accurate for this branch. Consider scoping explicit protocol selection to C#, or confirm/regenerate the polyglot bindings first.

[David Pine (IEvangelist)]

🤖 Docs-accuracy review — automated (Phase A: claims vs. source · Phase B: doc-tester)

Phase A source of truth: microsoft/aspire @ branch release/13.5, SHA 8ab6999850d96e0023670799edbd4bdc245ad63c
Claims extracted: 9 total (8 non-narrative) — ✅ 7 verified · 🟡 1 verified-with-nuance · ❔ 0 unverifiable · ❌ 0 contradicted · 📝 1 narrative
Phase B (doc-tester): exercised /integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host/ (#select-a-hosted-agent-protocol), served locally from the PR head — 0 critical · 1 warning · 2 knowledge gaps.

Verdict: COMMENT. Every verifiable API claim in the new section matches release/13.5. The only item worth surfacing is a naming/clarity nuance: the intro prose tells readers to "use AsHostedAgentWithProtocol", but that PascalCase name is not a callable public C# API and does not appear in the C# example — it exists only as the camelCase polyglot export asHostedAgentWithProtocol (used correctly in the TypeScript tab). No factual contradictions and no critical rendering issues.

---

Phase A — Claim verification

Source PR is microsoft/aspire#18980; the described surface is present on release/13.5. Evidence paths below are in microsoft/aspire at the SHA above.

Every API/behavior claim checks out:

• Default = Responses 2.0.0 — the parameterless-project overload calls ConfigureAsHostedAgent(..., HostedAgentProtocol.Responses, AzureHostedAgentResource.DefaultResponsesProtocolVersion, ...) (src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentBuilderExtension.cs:86-92), and DefaultResponsesProtocolVersion is the literal "2.0.0" (AzureHostedAgentResource.cs:32).
• C# AsHostedAgent(project, HostedAgentProtocol.Invocations, "1.0.0") — public overload AsHostedAgent<T>(builder, project, HostedAgentProtocol protocol, string protocolVersion, Action<HostedAgentConfiguration>? configure = null) (HostedAgentBuilderExtension.cs:194-203); the exact call appears in playground/FoundryAgents/FoundryAgents.AppHost/AppHost.cs:70.
• Polyglot asHostedAgentWithProtocol(project, protocol, version) — [AspireExport("asHostedAgentWithProtocol")] on AsHostedAgentWithProtocolForExport(builder, project, HostedAgentProtocol protocol, string protocolVersion, HostedAgentOptions? options = null) (HostedAgentBuilderExtension.cs:162-168).
• HostedAgentProtocol.Invocations / .Responses — public enum HostedAgentProtocol { Responses, Invocations } (HostedAgent/HostedAgentProtocol.cs:9-21).
• Both entry points exported to polyglot hosts — [AspireExport("asHostedAgent", …)] at :132 and [AspireExport("asHostedAgentWithProtocol")] at :162.
• Existing asHostedAgent(project, options?) unchanged, Responses 2.0.0 default — exported asHostedAgent(project, HostedAgentOptions? options = null) resolves to Responses + DefaultResponsesProtocolVersion (:132-148); the in-source comment at :116-120 confirms the original capability "retains its Responses/2.0.0 defaults."

🟡 One nuance (see the inline comment on line 469): the prose's AsHostedAgentWithProtocol (PascalCase) is not a public C# method. In C# the entry point is the AsHostedAgent(project, protocol, protocolVersion) overload; AsHostedAgentWithProtocol exists only as the internal AsHostedAgentWithProtocolForExport surfaced to polyglot hosts under the camelCase export name asHostedAgentWithProtocol. The code samples themselves are correct per language — only the prose naming is imprecise.

Full claim catalog with verdicts & evidence (9 claims)

#	Type	Claim	Verdict	Evidence (microsoft/aspire@release/13.5)
C1	api-behavior	AsHostedAgent defaults to Responses 2.0.0	✅ verified	HostedAgentBuilderExtension.cs:86-92; AzureHostedAgentResource.cs:32 (DefaultResponsesProtocolVersion = "2.0.0")
C2	api-shape	C# AsHostedAgent(project, HostedAgentProtocol.Invocations, "1.0.0") overload	✅ verified	HostedAgentBuilderExtension.cs:194-203; playground/FoundryAgents/FoundryAgents.AppHost/AppHost.cs:70
C3	api-shape	TS asHostedAgentWithProtocol(project, protocol, version)	✅ verified	HostedAgentBuilderExtension.cs:162-168 ([AspireExport("asHostedAgentWithProtocol")])
C4	api-shape	HostedAgentProtocol.Invocations (and .Responses) enum	✅ verified	HostedAgent/HostedAgentProtocol.cs:9-21
C5	api-behavior	Both asHostedAgent & asHostedAgentWithProtocol exported to polyglot hosts	✅ verified	HostedAgentBuilderExtension.cs:132 & :162
C6	api-behavior	Existing asHostedAgent(project, options?) still works, Responses 2.0.0 default	✅ verified	HostedAgentBuilderExtension.cs:132-148; comment :116-120
C7	api-shape	Prose: "use AsHostedAgentWithProtocol"	🟡 verified-with-nuance	No public C# AsHostedAgentWithProtocol; C# uses AsHostedAgent(project,protocol,version) (:194), polyglot export is camelCase asHostedAgentWithProtocol (:162)
C8	api-shape	AddPythonApp(name, appDirectory, scriptPath)	✅ verified	src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs:68-69. Note: "main:app" is an ASGI module:app spec passed to the scriptPath parameter (the API's own example uses "main.py"); the parameter accepts any string, so not a contradiction
C9	narrative	"some MAF agents use the Invocations protocol"	📝 narrative	Non-blocking; consistent with the Invocations enum member

---

Phase B — Doc-tester results (blind-user, docs-only view)

Served the PR head locally (http://localhost:4321/) and exercised the affected route with a browser only — no source code consulted in this phase.

Route exercised: /integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host/ → section #select-a-hosted-agent-protocol.

✅ Passed checks

• Page renders at the expected route; the new "Select a hosted agent protocol" H3 appears with a working table-of-contents entry and a self-anchor (#select-a-hosted-agent-protocol).
• Section is placed logically, immediately after "Add a hosted agent to Azure AI Foundry" and before "Add and publish a prompt agent."
• The C# and TypeScript tabs both render, switch, and stay in sync via the ?aspire-lang= query param; both code blocks display fully and are copyable.
• No console errors on load (0 errors / 0 warnings).

⚠️ Warning (1)

• Prose ↔ example naming mismatch (C#). The intro sentence (line 469) reads: "…use AsHostedAgentWithProtocol or pass a protocol and version explicitly." But the C# tab below it calls .AsHostedAgent(project, HostedAgentProtocol.Invocations, "1.0.0") — the name AsHostedAgentWithProtocol never appears in the C# example. Only the TypeScript tab uses asHostedAgentWithProtocol. A reader following the C# path can reasonably look for a AsHostedAgentWithProtocol method that the example doesn't show. Suggest clarifying that C# selects a protocol via the AsHostedAgent(project, protocol, version) overload, while asHostedAgentWithProtocol is the polyglot/TypeScript capability.

❔ Knowledge gaps (2)

• The samples reference a chat variable (.WithReference(chat) / .withReference(chat)) that isn't defined within this snippet; a copy-paste reader wouldn't know what chat is from the section alone.
• Neither tab shows the import/namespace needed to reference the HostedAgentProtocol enum (e.g., the Aspire.Hosting.Foundry namespace in C#, or the equivalent TypeScript import), so a new user copying the example may not know how to resolve HostedAgentProtocol.

Recommendations

• Align the intro prose with the C# example (make the C#-vs-polyglot naming explicit).
• Optionally note the namespace/import for HostedAgentProtocol.

---

_{Automated review. Phase A read microsoft/aspire@release/13.5 (8ab69998); Phase B used the doc-tester skill against the PR head served locally, blind to source code.}

[David Pine (IEvangelist)]

🟡 verified-with-nuance — AsHostedAgentWithProtocol (PascalCase) is not a callable public C# API on microsoft/aspire@release/13.5. The C# entry point for explicit protocol selection is the AsHostedAgent(project, protocol, protocolVersion) overload (src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentBuilderExtension.cs:194-203) — which is exactly what the C# tab below uses. AsHostedAgentWithProtocol exists only as the internal AsHostedAgentWithProtocolForExport (:163), surfaced to polyglot hosts under the camelCase export name asHostedAgentWithProtocol ([AspireExport("asHostedAgentWithProtocol")], :162), as the TypeScript tab correctly shows.

Since this sentence sits directly above a C# example that never uses AsHostedAgentWithProtocol, consider making the C#-vs-polyglot naming explicit — e.g. "in C#, pass a protocol and version to the AsHostedAgent(project, protocol, protocolVersion) overload; polyglot AppHosts use the asHostedAgentWithProtocol capability." (Non-blocking.)