# Build on Microsoft Agent Framework

Agent Mission Control developer docs > Microsoft Agent Framework (Python)

> When to build a single agent or a multi-agent workflow on Microsoft Agent Framework, which versions to pin, and how either one reaches AMC.

**Before you start:** Python 3.11 or later, a Microsoft Foundry project with a deployed chat model, and the Azure CLI.

In this build path the framework does the reasoning. Microsoft Agent Framework for Python runs the model loop, calls your tools and MCP servers, and streams the result. You deploy the agent or workflow to Microsoft Foundry as a **hosted agent**, and AMC runs it over the Foundry Responses protocol.

If you want a Claude skill to do the reasoning and only use Agent Framework as the host, this is the wrong path. See [Choose a build path](https://www.agentmissioncontrol.ai/developers/choose-a-build-path/).

## Agent or workflow

| You need | Build |
| --- | --- |
| One model turn with tools does the whole job | A single agent: one `Agent`, served directly. |
| Several agents or functions that hand work to each other | A workflow: executors connected by edges with `WorkflowBuilder`. |
| Each stage shown as its own step in AMC | A workflow. Every executor reports as a step. A single agent reports as one step. |
| A deterministic check between model calls | A workflow with a plain Python executor in the middle. |
| Parallel branches joined at the end | A workflow with fan-out and fan-in edges. |
| A pause for a person mid-run | A workflow that calls `ctx.request_info(...)`. |
| A run that survives the serving process stopping | A workflow. Process-loss recovery (`resilient_background`) is workflow-only. |

> **Note:** A single agent cannot get process-loss recovery. If a single-agent job needs it, build it as a one-node workflow instead.

## How it reaches AMC

1. Build an `Agent` or a `Workflow` with `FoundryChatClient`-backed agents.
2. Write a `main.py` that wraps it in `ResponsesHostServer`. It serves `/responses` and a health probe on port `8088`. A workflow is wrapped with `workflow.as_agent(name=...)` first.
3. Deploy the folder to Foundry as a hosted agent version and route traffic to it.
4. Register it in AMC. AMC calls it over the Responses protocol by its agent name.
5. While it runs, AMC reads steps, tokens, model, failures and human-input requests from the stream.

The hosted Responses stream flattens a workflow into one agent stream, and its run-level `usage` block is always empty. So the agent or workflow reports what AMC needs itself, on informational `function_call` markers. [Harden an agent or workflow for AMC](https://www.agentmissioncontrol.ai/developers/af-amc-hardening/) has the code. The general rules every agent meets are in [the integration contract](https://www.agentmissioncontrol.ai/developers/integration-contract/) and [how agents connect](https://www.agentmissioncontrol.ai/developers/how-agents-connect/).

## Versions this section targets

Agent Framework's Python API has changed across releases. The skills this section is based on verify their APIs against `agent-framework` **1.11.0**. Process-loss recovery needs the newer core **1.19.0** line. Pin exact versions in a container image, and don't install with `--pre`, which pulls pre-releases over the stable line.

| Package | Single agent | Workflow with recovery | Provides |
| --- | --- | --- | --- |
| `agent-framework-core` | `1.11.0` | `1.19.0` | `Agent`, `Executor`, `WorkflowBuilder`, `Content`, `Message`. 1.19 adds the checkpoint allow-list. |
| `agent-framework-foundry` | `1.10.1` | `1.13.1` | `FoundryChatClient`, `FoundryAgent`, `to_prompt_agent` |
| `agent-framework-foundry-hosting` | `1.0.0a260709` | `1.0.0b260918` | `ResponsesHostServer`, `CheckpointStoreProvider` |
| `azure-ai-agentserver-responses` | Pulled in by hosting | `>=2.2.0b1,<3` | `ResponsesServerOptions` |
| `azure-ai-projects` | `>=2.3.0` | `>=2.3.0` | Deploy and invoke hosted agents |
| `azure-identity` | `>=1.19.0` | `>=1.19.0` | `DefaultAzureCredential` |

> **Important:** Don't depend on the `agent-framework` meta-package in anything Foundry builds. It resolves to `agent-framework-core[all]`, which pulls in `agent-framework-hyperlight` and `hyperlight-sandbox-backend-wasm`. That package has no installable distribution for Foundry's Linux remote build, so the build fails with pip `ResolutionImpossible`. Depend on `agent-framework-core`, `agent-framework-foundry` and `agent-framework-foundry-hosting` directly.

### Older examples you will find

Many published examples use an earlier SDK surface. Map them to the 1.11.0 surface like this:

| Older examples | 1.11.0 |
| --- | --- |
| `from agent_framework.azure import AzureAIAgentsProvider` | Not present. Use `from agent_framework.foundry import FoundryChatClient` for a local agent, or `FoundryAgent` to connect to an existing hosted agent. |
| `provider.create_agent(...)` | `Agent(client=FoundryChatClient(...), ...)`. To publish a persistent prompt agent, `AIProjectClient.agents.create_version(name, definition=to_prompt_agent(agent))`. |
| `provider.get_agent(agent_id)` | `FoundryAgent(project_endpoint=..., agent_name=..., credential=...)`. It connects to an existing agent and never creates one. Omit `agent_version` for the latest. |
| Get-or-create by name | `AIProjectClient.agents.get(name)`, and on `ResourceNotFoundError` call `agents.create_version(name, definition=...)`. |
| `agent.run_stream(...)` | `agent.run(..., stream=True)`, an async iterator of `AgentResponseUpdate`. |
| Reading usage with `getattr` | `AgentResponse.usage_details` is a dict. Read `input_token_count`, `output_token_count` and `total_token_count` with `.get`. |

## In this section

- [Build a single agent](https://www.agentmissioncontrol.ai/developers/af-build-an-agent/): client, tools, MCP servers, structured output, streaming.
- [Build a workflow](https://www.agentmissioncontrol.ai/developers/af-build-a-workflow/): executors, edges, fan-out and fan-in, routing, loops.
- [Orchestrations, human input and checkpoints](https://www.agentmissioncontrol.ai/developers/af-orchestration-and-checkpoints/): the high-level builders, `as_agent()`, pauses and resume.
- [Host and deploy on Foundry](https://www.agentmissioncontrol.ai/developers/af-host-and-deploy/): `main.py`, the container, and the deploy script.
- [Harden an agent or workflow for AMC](https://www.agentmissioncontrol.ai/developers/af-amc-hardening/): the marker helpers and process-loss recovery.
- [Report steps, tokens and human input](https://www.agentmissioncontrol.ai/developers/af-report-to-amc/): what AMC reads and how it shows it.
- [Register and test in AMC](https://www.agentmissioncontrol.ai/developers/af-register-and-test/) and [Troubleshooting](https://www.agentmissioncontrol.ai/developers/af-troubleshooting/).

## Related

- [Build a single agent](https://www.agentmissioncontrol.ai/developers/af-build-an-agent/)
- [Build a workflow](https://www.agentmissioncontrol.ai/developers/af-build-a-workflow/)
- [Harden an agent or workflow for AMC](https://www.agentmissioncontrol.ai/developers/af-amc-hardening/)

---
Source: https://www.agentmissioncontrol.ai/developers/af-overview/ · Last updated 2026-10-21 · Full index: https://www.agentmissioncontrol.ai/llms.txt