[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.

[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)]

🤖 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.}

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Note

This error may be related to your runner configuration. You can now configure runners for Copilot code review separately from Copilot cloud agent by creating a copilot-code-review.yml file with your setup steps. Read the docs for details.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (2)

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

• This section is intended to document explicit protocol selection for polyglot AppHosts (per PR description), but it only mentions asHostedAgent(project, options?) and never mentions the new asHostedAgentWithProtocol(...) capability. As written, readers have no documented way to select a non-default protocol from TypeScript/polyglot hosts.

Polyglot AppHosts expose `asHostedAgent(project, options?)`; existing callers continue to use the Responses protocol version `2.0.0` by default.

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

• The overload signature is described as AsHostedAgent(project, protocol, version), but the surrounding text refers to a protocol version. Using protocolVersion here is clearer and matches the terminology used elsewhere in the PR description.

`AsHostedAgent` defaults to the Responses protocol version `2.0.0`. In C#, if your hosted agent implements a different protocol or protocol version, use the `AsHostedAgent(project, protocol, version)` overload. For example, some Microsoft Agent Framework (MAF) agents use the Invocations protocol:

[David Pine (IEvangelist)]

Docs accuracy review

Source of truth: microsoft/aspire release/13.5 @ 45f7776
Claims: 10 total (9 verifiable + 1 narrative) — 8 verified, 1 verified-with-nuance, 0 unverifiable, 0 contradicted
Blind docs test: PR head d6802557 served locally (http://localhost:4321); /integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host/#select-a-hosted-agent-protocol exercised — 0 critical, 0 blocking warnings (2 knowledge gaps).

Phase A — Claim verification

Every protocol-selection API the new "Select a hosted agent protocol" section documents exists on release/13.5 exactly as written: the asHostedAgentWithProtocol polyglot export, the C# AsHostedAgent(project, protocol, version) overload, the HostedAgentProtocol.Invocations enum value, and the Responses 2.0.0 default. No contradictions and nothing unverifiable, so there are no inline blocking comments.

Verified & verified-with-nuance claims (evidence)

• A-1 — Verified: AsHostedAgent/asHostedAgent default to Responses protocol version 2.0.0. The C# convenience overload defaults to HostedAgentProtocol.Responses, AzureHostedAgentResource.DefaultResponsesProtocolVersion in HostedAgentBuilderExtension.cs#L86-L93, and that constant is "2.0.0" in AzureHostedAgentResource.cs#L32.
• A-2 — Verified: The C# AsHostedAgent(project, protocol, version) overload exists — HostedAgentBuilderExtension.cs#L194-L200 (IResourceBuilder<AzureCognitiveServicesProjectResource>? project, HostedAgentProtocol protocol, string protocolVersion, Action<HostedAgentConfiguration>? configure = null). The 3-argument call in the docs is valid because configure is optional.
• A-3 — Verified: The polyglot/TypeScript asHostedAgentWithProtocol(project, protocol, version) export exists — HostedAgentBuilderExtension.cs#L162-L168 [AspireExport("asHostedAgentWithProtocol")].
• A-4 — Verified: HostedAgentProtocol.Invocations exists — HostedAgentProtocol.cs#L9-L20 (enum { Responses, Invocations }); imported and used in TypeScript at apphost.mts#L132.
• A-6 — Verified: The C# example call .AsHostedAgent(project, HostedAgentProtocol.Invocations, "1.0.0") is used verbatim in the product playground FoundryAgents.AppHost/AppHost.cs#L69-L70.
• A-7 — Verified: The TypeScript example call .asHostedAgentWithProtocol(project, HostedAgentProtocol.Invocations, '1.0.0') matches the polyglot test host apphost.mts#L132.
• A-8 — Verified: Both the defaulted asHostedAgent and the explicit asHostedAgentWithProtocol are exported to polyglot AppHosts, and asHostedAgent(project, options?) keeps the Responses 2.0.0 default — exports at HostedAgentBuilderExtension.cs#L132-L148 and #L162.
• A-9 — Verified: The polyglot asHostedAgent(project, options?) shape — [AspireExport("asHostedAgent")] with (project, HostedAgentOptions? options = null) at HostedAgentBuilderExtension.cs#L132-L137.
• A-5 — Narrative: "some Microsoft Agent Framework (MAF) agents use the Invocations protocol" — non-code prose; noted, not blocking.
• A-10 — Verified with nuance: AddPythonApp("agent-python", "../agent", "main:app") — the overload AddPythonApp(name, appDirectory, scriptPath, params scriptArgs) exists (PythonAppResourceBuilderExtensions.cs#L181-L182). Nuance: "main:app" is a module:attribute reference, not a scriptPath file, so that line is illustrative rather than runnable as-is. It matches the pre-existing "Add a hosted agent to Azure AI Foundry" example already on the page (unchanged by this PR), so it isn't newly introduced by this change.

Phase B — Documentation Test Report

Focus Area: Azure AI Foundry hosting — Select a hosted agent protocol
Date: 2026-08-17
Tester: doc-tester agent (blind to source code; playwright-cli against a local pnpm dev server)
Served: PR head d6802557 at http://localhost:4321
Route exercised: /integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host/#select-a-hosted-agent-protocol

Summary

Category	Passed	Failed	Warnings
Content Accuracy	4	0	0
Code Examples (rendering)	2	0	0
CLI Commands	0	0	0
Links / Navigation	3	0	0

Critical Issues

None.

Warnings

None blocking — see the knowledge gaps below.

Passed Checks

• The page renders with no browser console errors or warnings (0 errors / 0 warnings).
• The new "Select a hosted agent protocol" heading renders as an <h3> with the anchor #select-a-hosted-agent-protocol.
• The subsection appears in the "On this page" TOC, correctly nested under "Add a hosted agent to Azure AI Foundry", and its self-link resolves.
• The C# and TypeScript tabs render, switch, and stay synchronized through the aspire-lang query parameter (the URL updates to ?aspire-lang=typescript after switching).
• The C# code block matches exactly and the copy button returns the same text:
  builder.AddPythonApp("agent-python", "../agent", "main:app") .WithReference(project) .WithReference(chat) .AsHostedAgent(project, HostedAgentProtocol.Invocations, "1.0.0");
• The TypeScript code block matches exactly:
  await builder .addPythonApp('agent-python', '../agent', 'main:app') .withReference(project) .withReference(chat) .asHostedAgentWithProtocol(project, HostedAgentProtocol.Invocations, '1.0.0');
• The prose accurately states the Responses 2.0.0 default and when to reach for asHostedAgentWithProtocol. The new section contains no hyperlinks, so there are no links to break.

Recommendations

1. Consider naming where HostedAgentProtocol comes from (namespace / import) or listing its values (Responses, Invocations), so a reader can complete the snippet without prior knowledge. (This is consistent with the rest of the page, which also omits imports.)
2. Optionally note the minimum 13.5 package that first contains asHostedAgentWithProtocol / HostedAgentProtocol, so readers know which build makes the example runnable.

Knowledge Gap: Import/namespace for HostedAgentProtocol

What I needed to know: Which namespace/import surfaces HostedAgentProtocol for the C#/TS snippets.
Source of my knowledge: Not stated in the rendered docs; not filled from built-in product knowledge.
User impact: A new user copying only the tab fragment could hit an unresolved-name error until they discover the import.
Recommendation: Reasonable to assume given the page's fragment-style conventions, but a short note (or an explicit using/import) would remove the guesswork.

Knowledge Gap: Runnable package validation not performed

What I needed to know: Whether the C#/TS examples compile against the currently available 13.5 package.
Source of my knowledge: This run validated rendering and tab behavior in the browser only; I did not scaffold and build an AppHost.
User impact: Copy-paste compilability with the current matching package is unverified in this review.
Recommendation: Confirm the examples build against the first 13.5 package that ships these APIs before/at merge.

---

Verdict: COMMENT — all documented protocol-selection APIs verify against release/13.5 and the blind docs test found no critical issues. Only minor, non-blocking nuances and knowledge gaps remain to consider.

[David Pine (IEvangelist)]

⚠️ This review supersedes my earlier automated comment on this PR. The PR head advanced to 14b753c8 ("Correct hosted agent protocol guidance") while my previous pass was mid-run. That commit removed the TypeScript tab and the asHostedAgentWithProtocol guidance, so my earlier comment (which describes the prior revision d6802557) is stale — please disregard it in favor of this one.

Docs accuracy review

Source of truth: microsoft/aspire release/13.5 @ 45f7776
Reviewed PR head: 14b753c8
Claims: 6 total (5 verifiable + 1 narrative) — 4 verified, 1 verified-with-nuance, 0 unverifiable, 0 contradicted
Blind docs test: head 14b753c8 served locally (http://localhost:4321); /integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host/#select-a-hosted-agent-protocol exercised — 0 critical, 0 blocking warnings (2 knowledge gaps).

Phase A — Claim verification

Every API the current "Select a hosted agent protocol" section documents exists on release/13.5 exactly as written: the Responses 2.0.0 default, the C# AsHostedAgent(project, protocol, version) overload, the HostedAgentProtocol.Invocations enum value, and the polyglot asHostedAgent(project, options?) export. No contradictions and nothing unverifiable, so there are no inline blocking comments.

Verified & verified-with-nuance claims (evidence)

• N-1 — Verified: AsHostedAgent defaults to the Responses protocol version 2.0.0. The C# convenience overload defaults to HostedAgentProtocol.Responses, AzureHostedAgentResource.DefaultResponsesProtocolVersion in HostedAgentBuilderExtension.cs#L86-L93; that constant is "2.0.0" in AzureHostedAgentResource.cs#L32.
• N-2 — Verified: The C# AsHostedAgent(project, protocol, version) overload exists — HostedAgentBuilderExtension.cs#L194-L200 (IResourceBuilder<AzureCognitiveServicesProjectResource>? project, HostedAgentProtocol protocol, string protocolVersion, Action<HostedAgentConfiguration>? configure = null); the 3-argument call is valid because configure is optional. The exact call .AsHostedAgent(project, HostedAgentProtocol.Invocations, "1.0.0") is used verbatim in the product playground FoundryAgents.AppHost/AppHost.cs#L69-L70.
• N-3 — Verified: HostedAgentProtocol.Invocations exists — HostedAgentProtocol.cs#L9-L20 (enum { Responses, Invocations }).
• N-6 — Verified: "Polyglot AppHosts expose asHostedAgent(project, options?); existing callers continue to use the Responses protocol version 2.0.0 by default." The [AspireExport("asHostedAgent")] adapter has the signature (project, HostedAgentOptions? options = null) and applies the Responses 2.0.0 default — HostedAgentBuilderExtension.cs#L132-L148.
• N-4 — Narrative: "some Microsoft Agent Framework (MAF) agents use the Invocations protocol" — non-code prose; noted, not blocking.
• N-5 — Verified with nuance: AddPythonApp("agent-python", "../agent", "main:app") — the overload AddPythonApp(name, appDirectory, scriptPath, params scriptArgs) exists (PythonAppResourceBuilderExtensions.cs#L181-L182). Nuance: "main:app" is a module:attribute reference, not a scriptPath file, so that line is illustrative rather than runnable as-is. It matches the pre-existing "Add a hosted agent to Azure AI Foundry" example already on the page (unchanged by this PR).

Non-blocking observation: The explicit-protocol polyglot export asHostedAgentWithProtocol does exist in the product (HostedAgentBuilderExtension.cs#L162-L168). This revision now documents explicit protocol selection only for C#, so polyglot readers no longer have a documented way to select a non-default protocol. Everything the page claims is accurate — this is purely a coverage note, not a correctness issue.

Phase B — Documentation Test Report

Focus Area: Azure AI Foundry hosting — Select a hosted agent protocol
Date: 2026-08-17
Tester: doc-tester agent (blind to source code; playwright-cli against a local pnpm dev server)
Served: head 14b753c8 at http://localhost:4321
Route exercised: /integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host/#select-a-hosted-agent-protocol

Summary

Category	Passed	Failed	Warnings
Content Accuracy	3	0	0
Code Examples (rendering)	1	0	0
CLI Commands	0	0	0
Links / Navigation	3	0	0

Critical Issues

None.

Warnings

None blocking — see the knowledge gaps below.

Passed Checks

• The page renders with no browser console errors or warnings (0 errors / 0 warnings).
• The "Select a hosted agent protocol" heading renders as an <h3> with the anchor #select-a-hosted-agent-protocol.
• The subsection appears in the "On this page" TOC, correctly nested under "Add a hosted agent to Azure AI Foundry", and its self-link resolves.
• The single C# code block renders and its copy button returns the exact text:
  builder.AddPythonApp("agent-python", "../agent", "main:app") .WithReference(project) .WithReference(chat) .AsHostedAgent(project, HostedAgentProtocol.Invocations, "1.0.0");
• The prose accurately states the Responses 2.0.0 default, the C# overload for explicit protocol selection, and the polyglot asHostedAgent(project, options?) default behavior. The section contains no hyperlinks, so there are no links to break.

Recommendations

1. Consider naming where HostedAgentProtocol comes from (namespace / import) or listing its values (Responses, Invocations), so a reader can complete the snippet without prior knowledge. (Consistent with the rest of the page, which also omits imports.)
2. Optionally note the minimum 13.5 package that first contains HostedAgentProtocol / the protocol overload, so readers know which build makes the example runnable.

Knowledge Gap: Import/namespace for HostedAgentProtocol

What I needed to know: Which namespace/import surfaces HostedAgentProtocol for the C# snippet.
Source of my knowledge: Not stated in the rendered docs; not filled from built-in product knowledge.
User impact: A new user copying only the snippet could hit an unresolved-name error until they discover the import.
Recommendation: Reasonable to assume given the page's fragment-style conventions, but a short note (or an explicit using) would remove the guesswork.

Knowledge Gap: Runnable package validation not performed

What I needed to know: Whether the C# example compiles against the currently available 13.5 package.
Source of my knowledge: This run validated rendering and behavior in the browser only; I did not scaffold and build an AppHost.
User impact: Copy-paste compilability with the current matching package is unverified in this review.
Recommendation: Confirm the example builds against the first 13.5 package that ships these APIs before/at merge.

---

Verdict: COMMENT — every documented API in the current revision verifies against release/13.5, and the blind docs test found no critical issues. Only minor, non-blocking nuances and knowledge gaps remain to consider.

[David Pine (IEvangelist)]

Docs-accuracy review — PR #1475 (revision 0adc0548)

Phase A source of truth: microsoft/aspire release/13.5 @ 45f7776ddb51ba976a32ece224ef8b23ed989a91
Claims extracted: 7 · verified 7 · verified-with-nuance 0 · contradicted 0 · unverifiable 0
Phase B (doc-tester, blind): 1 route exercised (/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host/) — 0 critical, 0 warnings, 6 passed checks.

This review is pinned to the current head 0adc0548, which re-adds the C#/TypeScript tabs for the "Select a hosted agent protocol" section. It supersedes my earlier reviews on this PR (a05775c5, 5316c7f5, 14b753c8), which were written against superseded revisions.

Verdict: APPROVE — every non-narrative claim verifies against release/13.5, and both tabs render correctly with working copy buttons and no console errors.

---

Phase A — Claim verification

All 7 claims verified (evidence in src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentBuilderExtension.cs unless noted)

#	Claim	Evidence
1	AsHostedAgent defaults to Responses 2.0.0	:92,145-146 HostedAgentProtocol.Responses, DefaultResponsesProtocolVersion; AzureHostedAgentResource.cs:32 DefaultResponsesProtocolVersion = "2.0.0"
2	C# AsHostedAgent(project, protocol, version) overload	:194-202 AsHostedAgent<T>(this, project, HostedAgentProtocol protocol, string protocolVersion, [configure])
3	C# example .AsHostedAgent(project, HostedAgentProtocol.Invocations, "1.0.0")	enum HostedAgentProtocol.Invocations exists; matches overload (playground AppHost.cs:70 uses the same call)
4	Polyglot asHostedAgentWithProtocol export	:162 [AspireExport("asHostedAgentWithProtocol")], sig (project, HostedAgentProtocol protocol, string protocolVersion, HostedAgentOptions? options = null) :162-168
5	TS example .asHostedAgentWithProtocol(project, HostedAgentProtocol.Invocations, '1.0.0')	3 args → (project, protocol, version); enum flows to the polyglot surface via the exported signature
6	Polyglot asHostedAgent(project, options?), Responses 2.0.0 default	:132 [AspireExport("asHostedAgent")], sig (project, HostedAgentOptions? options = null) :132-136, defaults :145-146
7	Prose: both entry points exported; existing asHostedAgent(project, options?) callers unchanged with Responses 2.0.0	:132,162

Narrative (not blocking): ../agent / main:app in AddPythonApp/addPythonApp are illustrative user-supplied values.

---

Phase B — Doc-tester results (blind to source)

Route: /integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host/ → "Select a hosted agent protocol" (#select-a-hosted-agent-protocol).

Metric	Count
Critical issues	0
Warnings	0
Passed checks	6
Knowledge gaps	0

Passed checks

1. Section heading renders (h3) with self-anchor #select-a-hosted-agent-protocol and a matching TOC/nav link.
2. <Tabs syncKey="aspire-lang"> renders a tablist with C# and TypeScript tabs.
3. TypeScript panel renders …asHostedAgentWithProtocol(project, HostedAgentProtocol.Invocations, '1.0.0') with a working copy button.
4. C# panel (after selecting the C# tab) renders …AsHostedAgent(project, HostedAgentProtocol.Invocations, "1.0.0") with a working copy button; syncKey switches all page tabs together.
5. Prose renders correct inline code (AsHostedAgent, 2.0.0, AsHostedAgent(project, protocol, version), asHostedAgentWithProtocol, asHostedAgent(project, options?)).
6. Console clean across interactions: 0 errors, 0 warnings.

No critical issues, warnings, or knowledge gaps.