[docs] Clarify Foundry project connection injection in hosted-agent publish mode#1133
Conversation
…r hosted agents Documents that in publish mode, Aspire automatically injects Foundry project connection environment variables into the deployment container (the actual workload). Previously the docs only mentioned container registry publishing; this adds the connection injection behavior fixed by microsoft/aspire#17704. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
aspire-repo-bot
Bot
added
the
docs-from-code
There was a problem hiding this comment.
Pull request overview
This PR clarifies the Azure AI Foundry hosting documentation for hosted-agent publish mode, aligning the docs with the runtime behavior from the related Aspire fix.
Changes:
- Clarifies that publish mode injects Foundry project connection environment variables into the deployment container.
- Notes examples of injected values, including the connection string and project endpoint.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
IEvangelist
left a comment
IEvangelist
left a comment
There was a problem hiding this comment.
Docs-from-code review — automated (Phase A + Phase B)
Source-of-truth branch: microsoft/aspire release/13.4 @ 64efcefb8594b066a1e36075abfa68ee62c8c31a
PR head reviewed: b720c3c8914cac977dc7d3266d23c400bd4db84f
The release/13.4 tip on microsoft/aspire is the commit being documented here (#17704, the backport of #17687).
Phase A — Claim verification
Extracted 6 claims from the 1 modified line. Verdicts: 4 verified · 1 verified-with-nuance · 1 narrative · 0 unverifiable · 0 contradicted.
Verified / verified-with-nuance claims (with evidence)
| # | Claim | Verdict | Evidence (paths in microsoft/aspire @ 64efcefb8) |
|---|---|---|---|
| C1 | In publish mode, Aspire creates an `AzureHostedAgentResource` |
verified | src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentBuilderExtension.cs:338 — var hostedAgent = new AzureHostedAgentResource(agentName, target, configure);; class declared at src/Aspire.Hosting.Foundry/HostedAgent/AzureHostedAgentResource.cs:26. |
| C2 | publishes the container to the project-associated registry | verified | HostedAgentBuilderExtension.cs:341-345 adds DeploymentTargetAnnotation with ContainerRegistry = projectResource.ContainerRegistry; src/Aspire.Hosting.Foundry/Project/ProjectResource.cs:157 exposes AzureContainerRegistryResource? ContainerRegistry. |
| C3 | Aspire automatically injects the Foundry project connection environment variables … into the deployment container | verified | New code in HostedAgentBuilderExtension.cs:332-335 calls builder.ApplicationBuilder.CreateResourceBuilder(target).WithReference(project); where target is the swapped-in deployment ContainerResource. Test AsHostedAgent_InPublishMode_AddsProjectReferenceToDeploymentTarget in tests/Aspire.Hosting.Foundry.Tests/HostedAgentExtensionTests.cs proves the env vars land on the deployment target rather than the wrapper. |
| C4 | including `ConnectionStrings__<project-name>` |
verified | Test asserts kvp.Key == "ConnectionStrings__my-project"; the ConnectionStrings__{sourceResourceName} naming contract is documented at src/Aspire.Hosting/ResourceBuilderExtensions.cs:1086. |
| C5 | and the project endpoint | verified-with-nuance | The Foundry project endpoint is injected, but as the value of the connection-string env vars (ConnectionStrings__<project-name> = Endpoint={…outputs.endpoint} and a sibling <PROJECT_NAME>_CONNECTIONSTRING env var), not as a discretely-named "endpoint" environment variable. Wording reads naturally and matches the earlier "Add a Foundry project" section ("project-specific connection properties such as the project endpoint"), so this is fine to leave as-is — flagging for awareness only. |
| C6 | so the hosted agent has access to the Foundry project at runtime | narrative | Purpose statement — not a directly verifiable code claim. |
Phase B — Doc-tester (user-perspective) results
Scope: the single section affected by the diff — /integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host/#publish-a-hosted-agent-to-azure-ai-foundry. The PR is a prose-only one-sentence addition, so no new code samples, internal links, anchors, asides, or components needed validation.
| Category | Passed | Warnings | Critical |
|---|---|---|---|
| Content accuracy | 1 | 1 | 0 |
| Code examples | n/a | n/a | n/a |
| CLI commands | n/a | n/a | n/a |
| Links / components | 1 | 0 | 0 |
Warning 1 — minor ambiguity about whether the user has to opt in
The new sentence says "Aspire also automatically injects the Foundry project connection environment variables … into the deployment container". The C# example in the same section explicitly chains .WithReference(project) before .PublishAsHostedAgent(project), so a reader trying to learn the behavior from this page alone can't tell whether the injection happens (a) because of their explicit WithReference(project) or (b) because PublishAsHostedAgent(project) wires it on the deployment target on their behalf. The source code confirms (b). Consider either:
- noting parenthetically that this happens even if you don't call
WithReference(project)yourself, or - adding a minimal example that omits the explicit
WithReference(project)so readers see the "automatic" claim demonstrated.
Passed checks
- New sentence reads cleanly in context; terminology (
ConnectionStrings__<project-name>, "deployment container", "Foundry project connection environment variables") is consistent with the earlier "Add a Foundry project" section, which already explains thatWithReference(project)"injects the standard connection string and project-specific connection properties such as the project endpoint". - No grammar/spelling issues, no duplicate Asides, no orphaned imports.
- No internal links, anchors, code samples, or components were added — link-format and code-compilation rules don't apply to this revision.
Knowledge gaps: none — every term used in the new sentence has been introduced earlier on the same page.
Verdict
COMMENT — every non-narrative claim is verified against the release/13.4 source. One verified-with-nuance claim and one Phase B warning surfaced as awareness items; neither blocks the change.
| For .NET hosted agents, add your Service Defaults project reference and call `builder.AddServiceDefaults()` in the hosted-agent app so logs, metrics, traces, HTTP instrumentation, and OTLP export flow into the Aspire dashboard. Then enable telemetry on the Foundry Responses chat client that backs the Microsoft Agent Framework (MAF) agent. | ||
|
|
||
| In publish mode, Aspire creates an `AzureHostedAgentResource` and publishes the container to the project-associated registry. | ||
| In publish mode, Aspire creates an `AzureHostedAgentResource` and publishes the container to the project-associated registry. Aspire also automatically injects the Foundry project connection environment variables — including `ConnectionStrings__<project-name>` and the project endpoint — into the deployment container so the hosted agent has access to the Foundry project at runtime. |
There was a problem hiding this comment.
Phase B warning — clarify "automatically" vs. explicit WithReference(project)
The wording "Aspire also automatically injects the Foundry project connection environment variables … into the deployment container" is technically accurate against release/13.4 (commit 64efcefb8, #17704) — PublishAsHostedAgent(project) now calls WithReference(project) on the deployment target itself (src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentBuilderExtension.cs:332-335).
However, the C# example in this same section explicitly chains .WithReference(project) before .PublishAsHostedAgent(project), so a reader can't tell from the page alone whether the injection comes from their explicit WithReference(project) or is genuinely automatic. Consider noting parenthetically — "even if you don't call WithReference(project) yourself" — to make the "automatic" wording verifiable from the docs alone.
Phase A nuance — "the project endpoint"
AzureCognitiveServicesProjectResource exposes the endpoint as the value of the connection-string env vars (ConnectionStrings__<project-name> = Endpoint={…outputs.endpoint}, plus a sibling <PROJECT_NAME>_CONNECTIONSTRING env var with the same Endpoint=… value). There is no discretely-named "endpoint" environment variable. The current phrasing matches the earlier "Add a Foundry project" section and is fine to leave as-is — flagging for awareness only.
Documents changes from microsoft/aspire#17704 —
@aspire-repo-bot[bot]Target branch: Targeting
release/13.4based on the source PR milestone13.4(exact match).Why this PR is needed
microsoft/aspire#17704 (backport of #17687) fixed a bug where Foundry hosted agents deployed in publish mode were missing the Foundry project connection environment variables on the actual deployment container. Specifically,
WithReference(project)was previously applied to theAzureHostedAgentResourcewrapper instead of the deployment target (the container resource), so the connection strings (ConnectionStrings__<project-name>, project endpoint) were not injected into the workload that runs in Azure.The fix moves the reference so Aspire now automatically injects these environment variables into the deployment container.
What changed in the docs
Updated the "Publish a hosted agent to Azure AI Foundry" section in the Azure AI Foundry hosting integration reference to clarify that in publish mode, Aspire automatically injects Foundry project connection environment variables into the deployment container — not just publishing the container to the registry.
Files modified
src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host.mdx(updated, 1 line)