Samples for building, deploying, and managing hosted agents on Microsoft Foundry. Each sample is a starter template — fork it, change the system prompt and tools, deploy with azd up.

Every sample includes Application Insights and OpenTelemetry tracing out of the box. You get production-ready logging, distributed traces, and metrics from the first sample you run.

Pick the tool that matches your workflow — both deploy the same sample image to the same Foundry runtime, so you can switch between them at any point.

Prerequisites: Install the Azure Developer CLI with the Foundry AI extension. See Set up azd for hosted agents if you haven't already.

mkdir my-agent && cd my-agent
azd ai agent init -m ../agent-framework/hello-world/agent.manifest.yaml
azd up

You'll have a running agent in minutes.

Prerequisites: Install the Foundry Toolkit VS Code extension and sign in to Azure.

1. Clone this repo and open a sample folder under samples/csharp/hosted-agents/ in VS Code.
2. Start the agent locally following the sample's run instructions (e.g. azd ai agent run or dotnet run).
3. Open the Command Palette (Ctrl+Shift+P) and run Foundry Toolkit: Open Agent Inspector to chat with the running agent.
4. When you're ready to deploy, run Foundry Toolkit: Deploy Hosted Agent to build the container image in ACR, register the agent version, and assign the required RBAC roles automatically.

See the VS Code quickstart for the full walkthrough.

Read on to pick the right sample for your scenario, or jump to the learning path for a guided walkthrough.

Hosted agents support two protocols. Pick the one that matches your scenario.

Still not sure? Start with Responses. You can always add an Invocations endpoint later — a hosted agent can support both protocols simultaneously by listing both in agent.yaml.

Other protocols: Hosted agents can also expose the Activity protocol (for Teams and M365 integration) and the A2A protocol (for agent-to-agent delegation).

Hosted agents run any code you can put in a container. These samples cover three frameworks — pick the one that matches where you are.

Which should I choose? If you're building a new agent — or already using AutoGen or Semantic Kernel — start with Agent Framework. It has the tightest Foundry integration, supports those orchestrators natively, and has the most samples to learn from. If you have existing .NET agent code, Bring Your Own shows how to containerize and deploy it unchanged. For LangGraph or CrewAI (Python-only frameworks), see the Python samples.

The recommended path for building hosted agents. Agent Framework gives you native session management, built-in tool wiring, streaming, and the full Foundry feature set.

Samples are split by protocol. Start with Responses (the common path) — then explore Invocations when you need full HTTP control or long-running workflows.

The platform manages conversation history, streaming lifecycle, and background execution. This is the default for most agents.

New to hosted agents? Start here and work through in order:

1. Hello World — Deploy your first agent, invoke it, see traces in App Insights.
2. Multi-Turn Sessions — Adds multi-turn conversation history.
3. Tools — Add local C# function tools to your agent.

Ready for more?

4. Knowledge Grounding — Ground answers in your own documents with TextSearchProvider.
5. MCP Tools — Connect to MCP servers using client-side and server-side MCP patterns.
6. Workflows — Compose multiple agents into sequential pipelines.
7. File Tools — Ground answers in files bundled with the agent (image-baked) or uploaded per session ($HOME), with security-scoped tool pairs per source.

Full control over the HTTP request/response cycle. You define the payload schema, manage session state, and implement polling for long-running operations. Use this when you need an arbitrary payload format or async workflows that don't fit the OpenAI /responses contract.

Every capability works with both protocols. Tools, RAG, memory, evaluations, Teams publishing, multi-agent — all of these work with Invocations. The Invocations samples below focus on the protocol mechanics (how you handle requests, streaming, sessions, and long-running tasks). To add a capability like knowledge grounding or tools, learn the Invocations pattern from these samples, then adapt the relevant Responses sample — the capability code is the same, only the HTTP handler differs.

LangGraph is Python-only. See the Python LangGraph samples for LangGraph support on Foundry. The deployment, observability, Teams publishing, and evaluation infrastructure is identical — only the agent code differs.

Already built an agent with your own .NET code? The protocol SDKs (Azure.AI.AgentServer.Responses / Azure.AI.AgentServer.Invocations) give you the hosted agent HTTP contract — they host the web server, expose the right endpoint, and handle request parsing — so you just plug in your agent logic. This is the recommended path for BYO to ensure your agent stays aligned with the platform contract as new endpoints are added. For lower-level control, the Core adapter (Azure.AI.AgentServer.Core) gives you managed hosting, OpenTelemetry tracing, and health endpoints, but you handle the protocol details yourself.

Note: If you're using AutoGen or Semantic Kernel, you don't need BYO — Agent Framework supports them natively. See the Agent Framework samples instead.

Which approach? Use the protocol SDKs (Azure.AI.AgentServer.Responses / Azure.AI.AgentServer.Invocations) — they work with any framework and keep you aligned with the platform contract. The Core adapter (Azure.AI.AgentServer.Core) is available when you need lower-level control without protocol abstractions. The Custom HTTP sample exists as a reference for what the contract looks like under the hood with no SDK at all.

What's different from Agent Framework samples: BYO samples handle their own session state and tool wiring. The protocol SDKs give you the HTTP plumbing, but the tradeoff vs. full Agent Framework is that you manage orchestration, tools, and memory in your own code. The Dockerfile, agent.yaml, and azd up deployment are the same.

Every sample deploys the same way and supports two equivalent paths. Pick the one that matches your workflow.

mkdir my-agent && cd my-agent

# Scaffold from the sample manifest — azd generates all the deployment files
azd ai agent init -m ../agent-framework/hello-world/agent.manifest.yaml

# Build, push, and deploy
azd up

# Clean up when done
azd down

The Foundry Toolkit VS Code extension has a built-in sample gallery. You can open any sample directly from the extension without cloning this repository, it scaffolds the project into a new workspace, generates agent.yaml, .env, and .vscode/tasks.json + launch.json automatically, and configures a one-click F5 debug experience.

Or, if you've already cloned this repository:

1. Open a sample folder under samples/csharp/hosted-agents/ in VS Code.

2. Start the agent locally with azd ai agent run or dotnet run (see the sample README for details). The agent runs on http://localhost:8088/.

3. Open the Command Palette (Ctrl+Shift+P) and run Foundry Toolkit: Open Agent Inspector to chat with the running agent.

4. When you're ready to deploy, run Foundry Toolkit: Deploy Hosted Agent. The extension opens a tab-based wizard and reads agent.yaml to auto-populate what it can:

   • If prompted, complete Foundry Project Setup to pick the subscription and Foundry project (or create a new one) to deploy to.
   • On the Basics tab, choose a Deployment Method (Code ZIP or Container image), pick a Code packaging option (Remote / Local) or a Container registry option (default ACR, your own ACR, or a prebuilt ACR image), and confirm the Hosted Agent Name.
   • On the Review + Deploy tab, confirm the auto-detected runtime details (language, entry point, or Dockerfile), pick a CPU and Memory size, and click Deploy.

   The extension builds the container image in ACR (or uploads the ZIP), creates the agent version, and assigns required RBAC roles automatically.

samples/dotnet/hosted-agents/
├── agent-framework/
│   ├── hello-world/                   ← Start here (Agent Framework)
│   ├── simple-agent/
│   ├── local-tools/
│   ├── mcp-tools/
│   ├── text-search-rag/
│   ├── workflows/
│   ├── file-tools/
│   └── invocations-echo-agent/
└── bring-your-own/
    ├── responses/
    │   ├── HelloWorld/                ← Start here (BYO Responses)
    │   ├── notetaking-agent/
    │   ├── background-agent/
    │   └── env-vars-agent/
    └── invocations/
        ├── HelloWorld/                ← Start here (BYO Invocations)
        ├── notetaking-agent/
        └── human-in-the-loop/

The LangGraph samples are Python-only because LangGraph is a Python-native framework, but the containerized deployment pattern is identical.

<sample-name>/
├── README.md               # What it does, prerequisites, deploy, invoke, clean up
├── Program.cs              # Agent entry point (with OpenTelemetry + App Insights init)
├── <ProjectName>.csproj    # Project file with NuGet dependencies
├── Dockerfile              # Container definition (port 8088, .NET 10 multi-stage build)
├── .dockerignore
├── agent.manifest.yaml     # Agent definition — name, protocols, environment variables
└── agent.yaml              # Deployed agent config — protocol, resources

Python samples follow the same layout with main.py, requirements.txt, and a Python-based Dockerfile.

Samples do not include azure.yaml. The azd ai agent init -m ./<sample-name>/agent.manifest.yaml command (run from the sample's parent directory, not from the sample directory itself) generates the project configuration automatically from the agent manifest.

ERROR: downloading agent.yaml: cannot copy agent files: target '...' is inside the
manifest directory '...'. Move the manifest to a separate directory containing only the
agent files.

• Azure subscription with access to Microsoft Foundry
• One of the following deploy tools:
  • Azure Developer CLI (azd) — install, or
  • Foundry Toolkit VS Code Extension — install
• .NET 10 (or Python 3.12+ for Python samples)

That's it. Both azd ai agent init and the Foundry Toolkit VS Code extension will create a Foundry project and deploy a model for you if you don't already have one. Container images are built remotely using ACR Tasks by default — Docker is not required unless you want to build locally.

• Microsoft Foundry documentation
• Hosted agents overview
• Deploy a hosted agent
• Responses protocol: Python SDK (azure-ai-agentserver-responses) · C# SDK (Azure.AI.AgentServer.Responses)
• Invocations protocol: Python SDK (azure-ai-agentserver-invocations) · C# SDK (Azure.AI.AgentServer.Invocations)
• Core adapter (BYO): Python SDK (azure-ai-agentserver-core) · C# SDK (Azure.AI.AgentServer.Core)
• Azure Developer CLI (azd)

This project welcomes contributions and suggestions.

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.