Build on Microsoft Agent Framework
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.
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.
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. |
How it reaches AMC
- Build an
Agentor aWorkflowwithFoundryChatClient-backed agents. - Write a
main.pythat wraps it inResponsesHostServer. It serves/responsesand a health probe on port8088. A workflow is wrapped withworkflow.as_agent(name=...)first. - Deploy the folder to Foundry as a hosted agent version and route traffic to it.
- Register it in AMC. AMC calls it over the Responses protocol by its agent name.
- 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 has the code. The general rules every agent meets are in the integration contract and 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 |
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: client, tools, MCP servers, structured output, streaming.
- Build a workflow: executors, edges, fan-out and fan-in, routing, loops.
- Orchestrations, human input and checkpoints: the high-level builders,
as_agent(), pauses and resume. - Host and deploy on Foundry:
main.py, the container, and the deploy script. - Harden an agent or workflow for AMC: the marker helpers and process-loss recovery.
- Report steps, tokens and human input: what AMC reads and how it shows it.
- Register and test in AMC and Troubleshooting.
Related
Last updated 2026-10-21