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/responses/01-basic/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/python/hosted-agents/ in VS Code.
2. Start the agent locally following the sample's run instructions (e.g. azd ai agent run or python main.py).
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 already have LangGraph code, use the LangGraph hosting integration (langchain_azure_ai.agents.hosting) to bring it to Foundry. If you have an existing agent in another framework (e.g., CrewAI), Bring Your Own shows how to containerize and deploy it unchanged.

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. Basic agent & Multi-Turn Sessions — Deploy your first agent, have a conversation with it.
2. Tools — Add local tools to your agent.
3. MCP Tools — Connect your agent to a remote MCP server to access tools, retrieval, and more.
4. Foundry Toolbox — Wire your agent to a Foundry Toolbox for managed tool access.
5. Workflows — Compose multiple agents into sequential pipelines.
6. Files — Agent capable of manipulating files uploaded to the session.
7. Skills — Add native file-based skills to your agent and generate a colorful PDF travel guide.
8. Observability — Add logging, metrics, and distributed tracing to your agent and visualize them in Foundry.
9. Declarative Workflows — A multi-turn customer-support triage workflow defined entirely in YAML and hosted as an agent, demonstrating declarative workflow authoring with InvokeAzureAgent calls to specialist Foundry-hosted agents and conversation-aware routing.
10. Downstream Azure services — Call Azure Blob Storage and Service Bus from the agent using its per-agent Microsoft Entra identity (no connection strings).
11. A2A Delegation — Two-agent walkthrough: a hosted Responses caller delegates to a hosted Responses executor that is exposed as an A2A endpoint via Foundry's incoming A2A feature, wired together through a Foundry Toolbox a2a_preview tool over a RemoteA2A connection.

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.

Bring your existing LangGraph graphs to Foundry. These samples use langchain_azure_ai.agents.hosting (ResponsesHostServer / InvocationsHostServer) to expose LangGraph agents (create_agent) and custom StateGraphs over the hosted agent protocols, with native Foundry session, streaming, and tool wiring.

See langgraph/README.md for the full list and the local-run guide.

Already built an agent with CrewAI or your own 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.

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/responses/01-basic/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/python/hosted-agents/ in VS Code.

2. Start the agent locally with azd ai agent run or python main.py (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.

For Responses protocol agents, once the agent is deployed to Microsoft Foundry, you can interact with it using real-time voice through the Azure VoiceLive SDK. The shared Voice Live client sample, voicelive_client.py, demonstrates how to connect to your deployed agent and have a voice conversation.

python voicelive_client.py \
  --endpoint "https://<your-foundry-resource>.services.ai.azure.com" \
  --agent-name "<your-agent-name>" \
  --project-name "<your-foundry-project-name>"

The client authenticates using DefaultAzureCredential — make sure you are logged in (az login).

For Invocations protocol agents, to make the agent work with Voice Live, the agent needs:

• The agent can process voice live transcription input: {"type": "input_audio.transcription", "input": "example voice input"}
• The agent should output the text to be read as the following SSE, Voice Live will generate audio for the the delta text in the output_audio_transcription.delta event:

  data: {"type": "output_audio_transcription.delta", "delta": "The weather "}
  data: {"type": "output_audio_transcription.delta", "delta": "in Seattle "}
  data: {"type": "output_audio_transcription.delta", "delta": "is 52°F "}
  data: {"type": "output_audio_transcription.delta", "delta": "and partly cloudy."}
  data: {"type": "output_audio_transcription.done", "text": "The weather in Seattle is 52°F and partly cloudy."}
  data: {"type": "done"}
  

• The agent manifest must declare voiceLiveCompatible: "true" in the metadata section to indicate compatibility with Voice Live.

Here is a hosted agent sample with Invocations protocol that is compatible with Voice Live: hello-world-invocations-voicelive.

• 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
• Python 3.12+

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.