Skip to content

.NET: Add source (ZIP) deploy oriented hosted agent samples - #7372

Merged
rogerbarreto merged 23 commits into
microsoft:mainfrom
rogerbarreto:hosted-agent-zip-samples
Jul 29, 2026
Merged

.NET: Add source (ZIP) deploy oriented hosted agent samples#7372
rogerbarreto merged 23 commits into
microsoft:mainfrom
rogerbarreto:hosted-agent-zip-samples

Conversation

@rogerbarreto

@rogerbarreto rogerbarreto commented Jul 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Motivation & Context

Source (code / ZIP) deploy is now the default for Python and .NET hosted agents: you upload your sources and the platform builds and runs them, with no Dockerfile to author and no container registry to manage. The .NET samples still only showed the container path, so this change reorients them around ZIP deploy and makes deploying an Agent Framework hosted agent a much simpler experience.

Description & Review Guide

  • What are the major changes?

    Hosted-ChatClientAgent now deploys from source through a single unified azure.yaml, and a sibling Hosted-ChatClientAgent-Dockerfile keeps the container path for anyone who needs control over the runtime image.

    Along the way, a few quality and simplicity improvements:

    • AddFoundryResponses binds Kestrel to FoundryEnvironment.Port (PORT, default 8088). Without it a source deploy listens on the ASP.NET default and every invoke returns HTTP 424 session_not_ready.
    • Removed the deprecated agent.yaml and agent.manifest.yaml, plus both Dockerfiles, from the source-deploy sample.
    • Added scripts/Add-LocalFrameworkFeed.ps1 and scripts/add-local-framework-feed.sh: contributors follow the same flow as end users and deploy their own framework build in a single extra step.
    • SimpleAgent REPL gained --local and --remote, and now reaches a local server through the standard POST /responses route.
    • Documented the stale-conversation 404 in the sample READMEs that use azd ai agent invoke.

  • What is the impact of these changes?

    Inside a Foundry container, a plain WebApplication host calling AddFoundryResponses now listens on FoundryEnvironment.Port. Override with PORT. Hosts using AgentHostBuilder already behaved this way, and a host running outside Foundry keeps the addresses it resolved from configuration.

  • What do you want reviewers to focus on?

    The listen-port gate: it keys off FOUNDRY_HOSTING_ENVIRONMENT, read directly rather than through the cached FoundryEnvironment.IsHosted. Inside Foundry it cannot be guarded on ASPNETCORE_URLS (the .NET base image always sets it to port 80) nor on the presence of PORT (the platform sets that only for a non-default port).

Contribution Checklist

  • The code builds clean without any errors or warnings
  • All unit tests pass, and I have added new tests where possible
  • The PR follows the Contribution Guidelines
  • This is not a breaking change.

@rogerbarreto
Add zip/code-deploy POC for Hosted-ChatClientAgent (.NET)
57bfb8f 
Migrate the sample to Foundry source (ZIP) deployment as the default: add azure.yaml with codeConfiguration (remote_build, dotnet_10) and the tool-generated .agentignore, make the csproj self-contained (single target, CPM off, published PackageReferences), and simplify Program.cs to the pristine end-user hosting path. Container files are kept for now; contributor and remaining samples handled in follow-ups.
@rogerbarreto
.NET: Auto-bind Foundry hosted port for zip/code deploy; migrate Host…
a4e02e0 
…ed-ChatClientAgent to source (ZIP)

Foundry.Hosting: AddFoundryResponses now binds Kestrel to FoundryEnvironment.Port (the PORT env var, default 8088) for a plain WebApplication.CreateBuilder (Tier 3) host, mirroring AgentHostBuilder. This lets a source/ZIP-deployed .NET agent pass the readiness probe with no Dockerfile. It respects an explicit ASPNETCORE_URLS override and is idempotent. Adds FoundryListenPortTests plus a serialized env-var collection.

Hosted-ChatClientAgent: migrate to source (ZIP) deploy as the default. Add azure.yaml with codeConfiguration (remote_build, dotnet_10) and the tool-generated .agentignore, make the csproj self-contained (single target, CPM off) with a local Directory.Packages.props, embed the local-dev per-agent route so the Using-Samples REPL can reach the local server, and rewrite the README around the azd flow. Documents AZURE_TOKEN_CREDENTIALS=dev for local runs.

Using-Samples/SimpleAgent: fix the per-agent endpoint scheme rewrite so the local HTTP dev port is preserved (the policy now lives on the per-agent ProjectOpenAIClientOptions that actually serves the request).
@rogerbarreto
.NET: Bind Foundry hosted port unconditionally; drop container files …
c760aa3 
…and the local-only agent route

Zip/code deploy runs the sample as a plain ASP.NET app, so the Foundry readiness
port was never bound and every invoke returned HTTP 424 session_not_ready. The
first attempt skipped the binding when ASPNETCORE_URLS was already set, but the
.NET base image always sets it to port 80, so the skip always tripped. Kestrel
ListenAnyIP overrides ASPNETCORE_URLS, so the binding is now unconditional and
PORT stays the only knob.

Sample cleanup for zip deploy:
* Remove Dockerfile, Dockerfile.contributor, agent.manifest.yaml and agent.yaml.
  Source deploy needs none of them.
* Remove LocalDevEndpoint.cs and the invented per-agent local route. The local
  server already serves the standard POST /responses route, so the client can
  reach it directly.
* Trim .env.example: the port and environment variables are no longer needed.
* Exclude .checkpoints/ from the upload so local session state does not ship.

SimpleAgent now asks at startup whether to chat with the local server or the
deployed agent, the same choice azd ai agent invoke exposes through --local.
Local uses an OpenAI responses client pointed at http://localhost:8088; Foundry
uses the per-agent endpoint.

Add scripts/New-ContributorStage.ps1, which stages a sample to a temp folder with
the local Agent Framework source packed into a feed inside the upload, so
contributors can deploy framework changes through the same azd flow end users run.
@rogerbarreto
Pin hosted agent listen port in azure.yaml
ea1b14a
@rogerbarreto
Use the documented env map in azure.yaml
b331394
@rogerbarreto
Make the contributor flow an extra step inside the end-user flow
c9c70e8
@rogerbarreto
Keep contributor scaffolding out of the sample project file
a8b505d
@rogerbarreto
Document the full deploy walkthrough and add a bash contributor script
e374758
@rogerbarreto
Trim troubleshooting detail from the sample README
335e822
@rogerbarreto
Pass the model deployment name to the hosted container
01d050c
@rogerbarreto
Add --local and --remote flags to the SimpleAgent REPL
ab98c2f
@rogerbarreto
Use central package management in the hosted sample
c42887e
@rogerbarreto
Clarify where the contributor step fits in the deploy walkthrough
ce1d993
@rogerbarreto
Restore the HTTP scheme rewrite for local AIProjectClient runs
fce7016
@rogerbarreto
Keep the sample package versions in the project file
7b2b72f
@rogerbarreto
Drop the sample Directory.Packages.props
f3e3a81
@rogerbarreto
Add a container deploy variant of the hosted chat client agent sample
114af90
@rogerbarreto
Treat a blank model deployment variable as unset
d892540
@rogerbarreto
Let azd prompt for the Foundry project and expand the contributor sec…
568bcc5 
…tion
@rogerbarreto
Document the stale conversation 404 in the hosted agent samples
2e3b46f
@rogerbarreto
Remove using directives already covered by global usings
3ac87c3
Copilot AI review requested due to automatic review settings July 28, 2026 19:56
@agent-framework-automation agent-framework-automation Bot added documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs .NET Usage: [Issues, PRs], Target: .Net labels Jul 28, 2026
Copilot AI reviewed Jul 28, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Pull request overview

Reorients the .NET Foundry hosted-agent samples around source (ZIP/code) deployment (now the default path), while preserving a parallel container/Dockerfile-based sample for scenarios requiring image control. It also updates the Foundry hosting library to bind Kestrel to the Foundry runtime port so source-deployed agents pass readiness probing without requiring a Dockerfile.

Changes:

  • Updated AddFoundryResponses to configure Kestrel to listen on FoundryEnvironment.Port, with new unit tests covering port binding behavior and idempotency.
  • Reworked Hosted-ChatClientAgent sample to use unified azure.yaml source deploy and added a sibling Hosted-ChatClientAgent-Dockerfile sample for container deploy.
  • Added contributor scripts to pack and inject a local Agent Framework NuGet feed into scaffolded (azd-initialized) hosted-agent folders; updated the SimpleAgent REPL to support --local/--remote targeting.

Reviewed changes

Copilot reviewed 39 out of 39 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
dotnet/tests/Microsoft.Agents.AI.Foundry.Hosting.UnitTests/FoundryListenPortTests.cs Adds tests verifying Kestrel listen-port binding behavior from AddFoundryResponses.
dotnet/tests/Microsoft.Agents.AI.Foundry.Hosting.UnitTests/AspNetCoreUrlsEnvFixture.cs Serializes tests that mutate ASPNETCORE_URLS to prevent flakiness.
dotnet/src/Microsoft.Agents.AI.Foundry.Hosting/ServiceCollectionExtensions.cs Applies Foundry listen-port binding via KestrelServerOptions when registering Responses hosting.
dotnet/samples/04-hosting/FoundryHostedAgents/scripts/Add-LocalFrameworkFeed.ps1 Adds PowerShell helper to pack local framework and inject a folder feed + nuget.config into a scaffolded agent.
dotnet/samples/04-hosting/FoundryHostedAgents/scripts/add-local-framework-feed.sh Adds bash helper mirroring the PowerShell local-feed wiring flow.
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent/SimpleAgent.csproj Updates dependencies to support local targeting via OpenAI Responses client and adds OpenAI project reference.
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent/README.md Documents local vs Foundry targeting and adds azd ai agent invoke stale-conversation troubleshooting.
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent/Program.cs Adds --local/--remote selection and implements local target via POST /responses using OpenAI Responses client.
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/README.md Expands guidance on local HTTP dev and clarifies scheme-rewrite behavior.
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Simple/README.md Adds troubleshooting note for azd ai agent invoke conversation reuse (404).
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Handoff/README.md Adds troubleshooting note for azd ai agent invoke conversation reuse (404).
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ToolboxMcpSkills/README.md Adds troubleshooting note for azd ai agent invoke conversation reuse (404).
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox/README.md Adds troubleshooting note for azd ai agent invoke conversation reuse (404).
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox-AuthPaths/README.md Adds troubleshooting row for azd ai agent invoke conversation reuse (404).
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-TextRag/README.md Adds troubleshooting note for azd ai agent invoke conversation reuse (404).
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Observability/README.md Adds troubleshooting note for azd ai agent invoke conversation reuse (404).
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-McpTools/README.md Adds troubleshooting note for azd ai agent invoke conversation reuse (404).
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalTools/README.md Adds troubleshooting note for azd ai agent invoke conversation reuse (404).
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalCodeAct/README.md Adds troubleshooting note for azd ai agent invoke conversation reuse (404).
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-FoundryAgent/README.md Adds troubleshooting note for azd ai agent invoke conversation reuse (404).
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/README.md Rewrites the sample for source/ZIP deploy flow, adds contributor local-feed section and troubleshooting.
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/Program.cs Updates sample host to use DefaultAzureCredential and model selection via non-blank env var fallback.
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/HostedChatClientAgent.csproj Makes the project ZIP-deploy friendly (self-contained, explicit versions, central package mgmt disabled).
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/Dockerfile.contributor Removes contributor-only Dockerfile path from the source-deploy sample.
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/Dockerfile Removes container-based Dockerfile from the source-deploy sample.
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/azure.yaml Adds unified azure.yaml for hosted agent source/ZIP deploy configuration.
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/agent.yaml Removes deprecated hosted-agent spec file from the sample.
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/agent.manifest.yaml Removes deprecated manifest-based init path from the sample.
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/.env.example Updates local configuration template (deployment name + local dev credential guidance).
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/.agentignore Adds ZIP upload ignore rules for code deploy (excluding secrets/build output, keeping contributor feed files).
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent-Dockerfile/README.md Introduces container-deploy variant sample documentation and flow.
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent-Dockerfile/Program.cs Adds container-deploy variant agent host using Responses protocol.
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent-Dockerfile/HostedChatClientAgentDocker.csproj Adds container-deploy variant self-contained project definition.
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent-Dockerfile/Dockerfile Adds container image build/publish steps and pins listen port to 8088.
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent-Dockerfile/azure.yaml Adds unified azure.yaml selecting docker/container deploy mode.
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent-Dockerfile/.env.example Adds container variant local configuration template.
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent-Dockerfile/.dockerignore Prevents local secrets/build artifacts from entering the Docker build context.
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/README.md Adds troubleshooting note for azd ai agent invoke conversation reuse (404).
dotnet/agent-framework-dotnet.slnx Adds the new container-deploy sample project to the solution structure.
Comments suppressed due to low confidence (2)

dotnet/samples/04-hosting/FoundryHostedAgents/scripts/Add-LocalFrameworkFeed.ps1:88

  • $packagePropsPath is constructed with a Windows-only child path ('nuget\nuget-package.props'), and the VersionPrefix parse assumes Select-String always matches (Matches[0]). If the file path is wrong or the XML changes, this throws an unhelpful index error. Build the path with Join-Path segments and add a clear failure when VersionPrefix cannot be read.
    dotnet/samples/04-hosting/FoundryHostedAgents/scripts/Add-LocalFrameworkFeed.ps1:99
  • $projectPath is built with an embedded backslash ("$project$project.csproj"), which breaks on PowerShell 7 on macOS/Linux because '' is not a path separator there. Construct the path using Join-Path segments so it works cross-platform.

Comment thread dotnet/src/Microsoft.Agents.AI.Foundry.Hosting/ServiceCollectionExtensions.cs
Comment thread dotnet/samples/04-hosting/FoundryHostedAgents/scripts/Add-LocalFrameworkFeed.ps1
@rogerbarreto rogerbarreto self-assigned this Jul 28, 2026
peibekwe
peibekwe reviewed Jul 29, 2026
View reviewed changes
Comment thread dotnet/src/Microsoft.Agents.AI.Foundry.Hosting/ServiceCollectionExtensions.cs Outdated
peibekwe
peibekwe reviewed Jul 29, 2026
View reviewed changes
Comment thread dotnet/tests/Microsoft.Agents.AI.Foundry.Hosting.UnitTests/FoundryListenPortTests.cs Outdated
@rogerbarreto
rogerbarreto added this pull request to the merge queue Jul 29, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Jul 29, 2026
@rogerbarreto
rogerbarreto added this pull request to the merge queue Jul 29, 2026
Merged via the queue into microsoft:main with commit 0ca6a3e Jul 29, 2026
28 checks passed
This was referenced Jul 30, 2026
Open
Merged
Open
Open
Closed
Closed
Open
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@github-actions github-actions[bot] github-actions[bot] left review comments
Copilot code review Copilot Copilot left review comments
@SergeyMenshykh SergeyMenshykh SergeyMenshykh approved these changes
@peibekwe peibekwe peibekwe approved these changes
@westey-m westey-m westey-m approved these changes

Assignees

@rogerbarreto rogerbarreto

Labels

documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs .NET Usage: [Issues, PRs], Target: .Net

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@rogerbarreto @SergeyMenshykh @peibekwe @westey-m