Skip to content

[docs] Document asHostedAgentWithProtocol for polyglot hosted agents #1475

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aspire-repo-bot wants to merge 4 commits into
base: release/13.5
Choose a base branch
from
+30 −0
Open

[docs] Document asHostedAgentWithProtocol for polyglot hosted agents #1475

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
26a2450
docs: document asHostedAgentWithProtocol for polyglot hosted agents
aspire-repo-bot[bot] Aug 12, 2026
834ff1f
Fix AppHost terminology in hosted agent docs
IEvangelist Aug 12, 2026
a05775c
Apply suggestion from @sebastienros
sebastienros Aug 12, 2026
5316c7f
Apply suggestion from @alistairmatthews
sebastienros Aug 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions ...ontent/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -464,6 +464,36 @@ In publish mode, Aspire creates an `AzureHostedAgentResource` and publishes the

For C# AppHosts, the parameterless `AsHostedAgent()` overload reuses an existing Foundry project from the app model or creates one automatically. TypeScript AppHosts pass the project resource explicitly.

### Select a hosted agent protocol

`AsHostedAgent` defaults to the Responses protocol version `2.0.0`. If your hosted agent implements a different protocol or protocol version, use `AsHostedAgentWithProtocol` or pass a protocol and version explicitly. For example, some Microsoft Agent Framework (MAF) agents use the Invocations protocol:

@IEvangelist David Pine (IEvangelist) Aug 14, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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.)


<Tabs syncKey='aspire-lang'>
<TabItem id='csharp' label='C#'>

```csharp
builder.AddPythonApp("agent-python", "../agent", "main:app")
.WithReference(project)
.WithReference(chat)
.AsHostedAgent(project, HostedAgentProtocol.Invocations, "1.0.0");
```

</TabItem>
<TabItem id='typescript' label='TypeScript'>

```typescript
await builder
.addPythonApp('agent-python', '../agent', 'main:app')
.withReference(project)
.withReference(chat)
.asHostedAgentWithProtocol(project, HostedAgentProtocol.Invocations, '1.0.0');

@IEvangelist David Pine (IEvangelist) Aug 14, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

❌ 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.)

```

</TabItem>
</Tabs>

The defaulted `asHostedAgent` entry point and the explicit `asHostedAgentWithProtocol` entry point are both exported to polyglot AppHosts, 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.

@IEvangelist David Pine (IEvangelist) Aug 14, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


### Add and publish a prompt agent

For prompt-only scenarios, use `AddPromptAgent` on a Foundry project:
Expand Down
Loading