The Gap Between a Demo and a Production Agent
Let's be honest. Getting an AI agent to work in a demo takes an afternoon. Getting it to work reliably in production, tested, containerised, deployed, observable, and maintainable by a team. is a different problem entirely.
Most tutorials stop at the point where the agent prints a response in a terminal. They don't show you how to structure your code, cover your tools with tests, wire up CI, or deploy to a managed runtime with a proper lifecycle. That gap between prototype and production is where developer teams lose weeks.
Microsoft Foundry Hosted Agents close that gap with a managed container runtime for your own custom agent code. And the Hosted Agents Workshop for .NET gives you a complete, copy-paste-friendly path through the entire journey. from local run to deployed agent to chat UI, in six structured labs using .NET 10.
This post walks you through what the workshop delivers, what you will build, and why the patterns it teaches matter far beyond the workshop itself.
What Is a Microsoft Foundry Hosted Agent?
Microsoft Foundry supports two distinct agent types, and understanding the difference is the first decision you will make as an agent developer.
- Prompt agents are lightweight agents backed by a model deployment and a system prompt. No custom code required. Ideal for simple Q&A, summarisation, or chat scenarios where the model's built-in reasoning is sufficient.
- Hosted agents are container-based agents that run your own code .NET, Python, or any framework you choose inside Foundry's managed runtime. You control the logic, the tools, the data access, and the orchestration.
When your scenario requires custom tool integrations, deterministic business logic, multi-step workflow orchestration, or private API access, a hosted agent is the right choice. The Foundry runtime handles the managed infrastructure; you own the code.
For the official deployment reference, see Deploy a hosted agent to Foundry Agent Service on Microsoft Learn.
What the Workshop Delivers
The Hosted Agents Workshop for .NET is a beginner-friendly, hands-on workshop that takes you through the full development and deployment path for a real hosted agent. It is structured around a concrete scenario: a Hosted Agent Readiness Coach that helps delivery teams answer questions like:
- Should this use case start as a prompt agent or a hosted agent?
- What should a pilot launch checklist include?
- How should a team troubleshoot common early setup problems?
The scenario is purposefully practical. It is not a toy chatbot. It is the kind of tool a real team would build and hand to other engineers, which means it needs to be testable, deployable, and extensible.
The workshop covers:
- Local development and validation with .NET 10
- Copilot-assisted coding with repo-specific instructions
- Deterministic tool implementation with xUnit test coverage
- CI pipeline validation with GitHub Actions
- Secure deployment to Azure Container Registry and Microsoft Foundry
- Chat UI integration using Blazor
What You Will Build
By the end of the workshop, you will have a code-based hosted agent that exposes an OpenAI Responses-compatible /responses endpoint on port 8088.
The agent is backed by three deterministic local tools, implemented in WorkshopLab.Core:
- RecommendImplementationShape — analyses a scenario and recommends hosted or prompt agent based on its requirements
- BuildLaunchChecklist — generates a pilot launch checklist for a given use case
- TroubleshootHostedAgent — returns structured troubleshooting guidance for common setup problems
These tools are deterministic by design, no LLM call required to return a result. That choice makes them fast, predictable, and fully testable, which is the right architecture for business logic in a production agent.
The end-to-end architecture looks like this:
The Hands-On Journey: Lab by Lab
The workshop follows a deliberate build → validate → ship progression. Each lab has a clear outcome. You do not move forward until the previous checkpoint passes.
Lab 0 — Setup and Local Run
Open the repo in VS Code or a GitHub Codespace, configure your Microsoft Foundry project endpoint and model deployment name, then run the agent locally. By the end of Lab 0, your agent is listening on http://localhost:8088/responses and responding to test requests.
dotnet restore
dotnet build
dotnet run --project src/WorkshopLab.AgentHostTest it with a single PowerShell call:
Invoke-RestMethod -Method Post `
-Uri "http://localhost:8088/responses" `
-ContentType "application/json" `
-Body '{"input":"Should we start with a hosted agent or a prompt agent?"}'Lab 1 — Copilot Customisation
Configure repo-specific GitHub Copilot instructions so that Copilot understands the hosted-agent patterns used in this project. You will also add a Copilot review skill tailored to hosted agent code reviews. This step means every code suggestion you receive from Copilot is contextualised to the workshop scenario rather than giving generic .NET advice.
Lab 2 — Tool Implementation
Extend one of the deterministic tools in WorkshopLab.Core with a real feature change. The suggested change adds a stronger recommendation path to RecommendImplementationShape for scenarios that require all three hosted-agent strengths simultaneously.
// In RecommendImplementationShape — add before the final return:
if (requiresCode && requiresTools && requiresWorkflow)
{
return string.Join(Environment.NewLine,
[
$"Recommended implementation: Hosted agent (full-stack)",
$"Scenario goal: {goal}",
"Why: the scenario requires custom code, external tool access, and " +
"multi-step orchestration — all three hosted-agent strengths.",
"Suggested next step: start with a code-based hosted agent, register " +
"local tools for each integration, and add a workflow layer."
]);
}You then write an xUnit test to cover it, run dotnet test, and validate the change against a live /responses call. This is the workshop's most important teaching moment: every tool change is covered by a test before it ships.
Lab 3 — CI Validation
Wire up a GitHub Actions workflow that builds the solution, runs the test suite, and validates that the agent container builds cleanly. No manual steps — if a change breaks the build or a test, CI catches it before any deployment happens.
Lab 4 — Deployment to Microsoft Foundry
Use the Azure Developer CLI (azd) to provision an Azure Container Registry, publish the agent image, and deploy the hosted agent to Microsoft Foundry. The workshop separates provisioning from deployment deliberately: azd owns the Azure resources; the Foundry control plane deployment is an explicit, intentional final step that depends on your real project endpoint and agent.yaml manifest values.
Lab 5 — Chat UI Integration
Connect a Blazor chat UI to the deployed hosted agent and validate end-to-end responses. By the end of Lab 5, you have a fully functioning agent accessible through a real UI, calling your deterministic tools via the Foundry control plane.
Key Concepts to Take Away
The workshop teaches concrete patterns that apply well beyond this specific scenario.
Code-first agent design
Prompt-only agents are fast to build but hard to test and reason about at scale. A hosted agent with code-backed tools gives you something you can unit test, refactor, and version-control like any other software.
Deterministic tools and testability
The workshop explicitly avoids LLM calls inside tool implementations. Deterministic tools return predictable outputs for a given input, which means you can write fast, reliable unit tests for them. This is the right pattern for business logic. Reserve LLM calls for the reasoning layer, not the execution layer.
CI/CD for agent systems
AI agents are software. They deserve the same build-test-deploy discipline as any other service. Lab 3 makes this concrete: you cannot ship without passing CI, and CI validates the container as well as the unit tests.
Deployment separation
The workshop's split between azd provisioning and Foundry control-plane deployment is not arbitrary. It reflects the real operational boundary: your Azure resources are long-lived infrastructure; your agent deployment is a lifecycle event tied to your project's specific endpoint and manifest. Keeping them separate reduces accidents and makes rollbacks easier.
Observability and the validation mindset
Every lab ends with an explicit checkpoint. The culture the workshop builds is: prove it works before moving on. That mindset is more valuable than any specific tool or command in the labs.
Why Hosted Agents Are Worth the Investment
The managed runtime in Microsoft Foundry removes the infrastructure overhead that makes custom agent deployment painful. You do not manage Kubernetes clusters, configure ingress rules, or handle TLS termination. Foundry handles the hosting; you handle the code.
This matters most for teams making the transition from demo to production. A prompt agent is an afternoon's work. A hosted agent with proper CI, tested tools, and a deployment pipeline is a week's work done properly once, instead of several weeks of firefighting done poorly repeatedly.
The Foundry agent lifecycle —> create, update, version, deploy —>also gives you the controls you need to manage agents in a real environment: staged rollouts, rollback capability, and clear separation between agent versions. For the full deployment guide, see Deploy a hosted agent to Foundry Agent Service.
From Workshop to Real Project
This workshop is not just a learning exercise. The repository structure, the tooling choices, and the CI/CD patterns are a reference implementation.
The patterns you can lift directly into a production project include:
- The
WorkshopLab.Core/WorkshopLab.AgentHostseparation between business logic and agent hosting - The
agent.yamlmanifest pattern for declarative Foundry deployment - The GitHub Actions workflow structure for build, test, and container validation
- The
azd+ ACR pattern for image publishing without requiring Docker Desktop locally - The Blazor chat UI as a starting point for internal tooling or developer-facing applications
The scenario, a readiness coach for hosted agents. This is also something teams evaluating Microsoft Foundry will find genuinely useful. It answers exactly the questions that come up when onboarding a new team to the platform.
Common Mistakes When Building Hosted Agents
Having run workshops and spoken with developer teams building on Foundry, a few patterns come up repeatedly:
- Skipping local validation before containerising. Always validate the
/responsesendpoint locally first. Debugging inside a container is slower and harder than debugging locally. - Putting business logic inside the LLM call. If the answer to a user query can be determined by code, use code. Reserve the model for reasoning, synthesis, and natural language output.
- Treating CI as optional. Agent code changes break things just like any other code change. If you do not have CI catching regressions, you will ship them.
- Conflating provisioning and deployment. Recreating Azure resources on every deploy is slow and error-prone. Provision once with
azd; deploy agent versions as needed through the Foundry control plane. - Not having a rollback plan. The Foundry agent lifecycle supports versioning. Use it. Know how to roll back to a previous version before you deploy to production.
Get Started
The workshop is open source, beginner-friendly, and designed to be completed in a single day. You need a .NET 10 SDK, an Azure subscription, access to a Microsoft Foundry project, and a GitHub account.
Clone the repository, follow the labs in order, and by the end you will have a production-ready reference implementation that your team can extend and adapt for real scenarios.
Clone the workshop repository →
Here is the quick start to prove the solution works locally before you begin the full lab sequence:
git clone https://github.com/microsoft/Hosted_Agents_Workshop_dotNET.git
cd Hosted_Agents_Workshop_dotNET
# Set your Foundry project endpoint and model deployment
$env:AZURE_AI_PROJECT_ENDPOINT = "https://<resource>.services.ai.azure.com/api/projects/<project>"
$env:MODEL_DEPLOYMENT_NAME = "gpt-4.1-mini"
# Build and run
dotnet restore
dotnet build
dotnet run --project src/WorkshopLab.AgentHostThen send your first request:
Invoke-RestMethod -Method Post `
-Uri "http://localhost:8088/responses" `
-ContentType "application/json" `
-Body '{"input":"Should we start with a hosted agent or a prompt agent?"}'When the agent answers as a Hosted Agent Readiness Coach, you are ready to begin the labs.
Key Takeaways
- Hosted agents in Microsoft Foundry let you run custom .NET code in a managed container runtime — you own the logic, Foundry owns the infrastructure.
- Deterministic tools are the right pattern for business logic in production agents: fast, testable, and predictable.
- CI/CD is not optional for agent systems. Build it in from the start, not as an afterthought.
- Separate your provisioning (
azd) from your deployment (Foundry control plane) — it reduces accidents and simplifies rollbacks. - The workshop is a reference implementation, not just a tutorial. The patterns are production-grade and ready to adapt.
References
Microsoft