The first time it breaks is when an agent needs more: a follow-up question for the user, additional context from another specialist, or a realization mid-turn that the request belongs somewhere else entirely. At that point, a fixed pipeline or one-shot router isn\u2019t enough. What you need is a small, bounded graph where agents themselves decide who should speak next, without losing conversation context or violating guardrails.<\/span><\/p>\n Handoff Orchestration<\/strong>\u00a0in Microsoft Agent Framework is the pattern built for that case. The developer declares the participating agents and the directed edges between them, and the framework injects the tool calls each agent uses to transfer control along those edges. Routing decisions stay with the agents; topology and guardrails stay with the developer.<\/p>\n Handoff is a good fit when:<\/p>\n This post is a practical tour of the Handoff orchestration pattern. It explains how Handoff works, what shapes of agent topologies it enables, and how conversation flows, routing, and termination behave at runtime. Through progressively richer examples, it shows how Handoff supports shared context, asymmetric routing, and human\u2011in\u2011the\u2011loop interactions\u2014and how it provides a natural evolution path from simple pipelines once a workflow grows beyond a fixed sequence.<\/span><\/p>\n A handoff workflow is decentralized routing. The developer declares a graph of agents and the directed edges between them; the framework gives each agent a synthetic handoff tool per outbound edge so it can pass control by calling one. That single mechanic gives the authoring model three properties that matter day-to-day:<\/p>\n These three properties are what make Handoff a good fit for conversational, agent-driven topologies. The remainder of the post stays at the authoring level: what topology can be expressed, how user input flows, how termination works, and when to choose Handoff over Sequential or a workflow built with explicit branching.<\/p>\n In .NET, the workflow is constructed from a static factory by adding edges. Agents are anything that implements\u00a0 The same workflow in Python is shaped almost identically:<\/p>\n Participants and the start agent are passed up front rather than threaded through a factory, but the resulting graph is the same.<\/p>\n The canonical handoff diagram is a star: a single triage agent at the center with arrows out to specialists, optionally with arrows back. The next example is an e-commerce support workflow with four agents and asymmetric edges:<\/p>\n Two characteristics distinguish this topology from the simple star:<\/p>\n The .NET wiring is direct.\u00a0 Three behaviors are worth highlighting in this example:<\/p>\n The Python build of the same topology is the same set of declarations:<\/p>\n Both definitions describe the same graph and the same terminal\u00a0 When does a Sequential workflow want to become a Handoff one? The most common trigger is “someone needs to ask the user a question.” Consider a content pipeline: This works well when each agent can complete its step from the original input. But Sequential has no built-in pause: the\u00a0 Path 1: build the routing yourself.<\/strong>\u00a0Drop down to\u00a0 For the content-pipeline case, the wiring looks roughly like this (schematic; see note below):<\/p>\n This snippet is schematic because workflow agents speak chat protocol ( Path 2: switch to Handoff.<\/strong> Promote the agents into a small graph and let them decide where to route:<\/p>\n What changed:<\/p>\n The Sequential version is shorter. The Handoff version is appropriate the first time the writer needs to revisit research, or the editor needs to consult the user before publishing. The structure is still declarative; the difference is that the graph contains a back-edge, and the routing decision along that edge is delegated to the agents.<\/p>\n Python callout.<\/strong>\u00a0Python’s\u00a0\n
What Handoff Actually Is<\/h2>\n
\n
The Smallest Possible Handoff<\/h2>\n
AIAgent<\/code>, typically created with\u00a0IChatClient.AsAIAgent<\/code>:<\/p>\nusing Microsoft.Agents.AI;\r\nusing Microsoft.Agents.AI.Workflows;\r\n\r\nAIAgent triage = chatClient.AsAIAgent(\r\n instructions: \"You receive a user request and route it to the right specialist.\",\r\n name: \"Triage\");\r\n\r\nAIAgent billing = chatClient.AsAIAgent(\r\n instructions: \"You handle billing questions.\",\r\n name: \"Billing\");\r\n\r\nAIAgent tech = chatClient.AsAIAgent(\r\n instructions: \"You handle technical support questions.\",\r\n name: \"Tech\");\r\n\r\nWorkflow workflow = AgentWorkflowBuilder\r\n .CreateHandoffBuilderWith(triage)\r\n .WithHandoff(triage, billing)\r\n .WithHandoff(triage, tech)\r\n .Build();<\/code><\/pre>\nBuild()<\/code>\u00a0returns a\u00a0Workflow<\/code>\u00a0that can be driven with\u00a0InProcessExecution.OpenStreamingAsync<\/code>. Each user message is fed to\u00a0triage<\/code>, which sees two synthetic handoff tools (one per declared edge) whose descriptions tell the model what each target is for. If\u00a0triage<\/code>\u00a0answers the user directly, the conversation pauses for the next user turn. If it calls a handoff tool, control moves to the target.<\/p>\nfrom agent_framework_orchestrations import HandoffBuilder\r\n\r\nworkflow = (\r\n HandoffBuilder(participants=[triage, billing, tech])\r\n .with_start_agent(triage)\r\n .add_handoff(triage, [billing, tech])\r\n .build()\r\n)\r\n<\/code><\/pre>\nWorkshop: A Topology That Isn’t Just a Star<\/h2>\n
![\"e-Commerce](\"https:\/\/devblogs.microsoft.com\/agent-framework\/wp-content\/uploads\/sites\/78\/2026\/05\/ECommerceWorkflow.webp\")
<\/a><\/p>\n\n
Returns<\/code>\u00a0\u2194\u00a0Orders<\/code>\u00a0is a side edge.<\/strong>\u00a0A user who started with a return may need a replacement order, or a user who started with an order may want to convert it to a refund. Routing through\u00a0Triage<\/code>\u00a0again would cost a turn and risk losing context.<\/li>\nReturns \u2192 Fraud<\/code>\u00a0is one-way, and\u00a0Fraud<\/code>\u00a0is terminal.<\/strong>\u00a0The returns specialist can escalate when a request looks suspicious, but\u00a0Fraud<\/code>\u00a0has no outbound handoffs of its own. Once control rests there, the workflow stops routing and the conversation drains to output.<\/li>\n<\/ul>\nWithHandoffs<\/code>\u00a0is used for the runs of edges that use default target-derived reasons, and the single\u00a0WithHandoff<\/code>\u00a0call is reserved for the one edge that needs a custom reason:<\/p>\nHandoffWorkflowBuilder builder = AgentWorkflowBuilder\r\n .CreateHandoffBuilderWith(triage)\r\n .WithHandoffs(triage, [returns, orders]) \/\/ star\r\n .WithHandoffs(returns, [triage, orders]) \/\/ back-edge + side edge\r\n .WithHandoffs(orders, [triage, returns]) \/\/ back-edge + side edge\r\n .WithHandoff(returns, fraud, \/\/ one-way escalation\r\n handoffReason: \"Suspected return fraud or abuse.\")\r\n .EnableReturnToPrevious(); \/\/ follow-ups go to last specialist\r\n\r\nWorkflow workflow = builder.Build();\r\n<\/code><\/pre>\n\n
WithHandoff(from, to, handoffReason?)<\/code>\u00a0call is attached to the source-to-target edge: different sources can use different reasons for the same target. The default reason is the target agent’s\u00a0Description<\/code>\u00a0(or its name); the explicit reason on\u00a0Returns \u2192 Fraud<\/code>\u00a0is what teaches the model when escalation is appropriate without putting that logic in\u00a0Returns<\/code>‘s system prompt.<\/li>\nEnableReturnToPrevious()<\/code><\/strong>\u00a0changes which agent receives the\u00a0next user message<\/em>. Without it, every user turn returns to\u00a0Triage<\/code>. With it, follow-up questions land on the specialist that was last speaking, which matches the user’s expectation mid-conversation.<\/li>\nWithHandoff<\/code>.<\/strong>\u00a0No special API is needed. The workflow’s\u00a0HandoffEndExecutor<\/code>\u00a0yields a\u00a0List<ChatMessage><\/code>\u00a0as the workflow output once\u00a0Fraud<\/code>\u00a0finishes a turn.<\/li>\n<\/ol>\nworkflow = (\r\n HandoffBuilder(participants=[triage, returns, orders, fraud])\r\n .with_start_agent(triage)\r\n .add_handoff(triage, [returns, orders])\r\n .add_handoff(returns, [triage, orders])\r\n .add_handoff(orders, [triage, returns])\r\n .add_handoff(\r\n returns, [fraud],\r\n description=\"Suspected return fraud or abuse.\",\r\n )\r\n .build()\r\n)\r\n<\/code><\/pre>\nfraud<\/code>\u00a0node. Follow-up user turns are routed to the most recent specialist on both runtimes: in .NET this is enabled by\u00a0EnableReturnToPrevious()<\/code>, and in Python it is the default behavior once a start agent is set.<\/p>\nWorkshop: From Sequential to Handoff for HITL<\/h2>\n
<\/a>In .NET:<\/p>\nWorkflow pipeline = AgentWorkflowBuilder.BuildSequential(researcher, writer, editor);\r\n<\/code><\/pre>\nWriter<\/code>\u00a0cannot ask the\u00a0Researcher<\/code>\u00a0for an additional source, and the\u00a0Editor<\/code>\u00a0cannot stop and ask the user “Did you want this in British or American English?” before publishing. To add either, there are two paths.<\/p>\nWorkflowBuilder<\/code>\u00a0and use typed conditional edges or\u00a0AddSwitch<\/code>, the same primitives Kinfey Lo’s\u00a0Multi-Agent Orchestration post<\/a>\u00a0uses for the Conditional pattern. The decision executor, branch predicates, and owning agent are all chosen explicitly. The result is total control over routing at the cost of writing the bridging code, including the prompt engineering needed for the agent to format its decision in a way the predicate can read.<\/p>\nWorkflow pipeline = new WorkflowBuilder(researcher)\r\n .AddEdge(researcher, writer)\r\n .AddSwitch(writer, sw => sw\r\n .AddCase<DraftReview>(d => d.NeedsMoreSources, researcher)\r\n .WithDefault(editor))\r\n .Build();\r\n<\/code><\/pre>\nList<ChatMessage><\/code>\u00a0and\u00a0TurnToken<\/code>), not typed application payloads such as\u00a0DraftReview<\/code>. Adding a typed switch on the writer’s output requires inserting a custom executor (for example, one derived from\u00a0ChatProtocolExecutor<\/code>) that converts the writer’s chat output into a\u00a0DraftReview<\/code>\u00a0before the switch can inspect it. The agents themselves are the same as in the Sequential pipeline; what differs is that the routing decision now lives in\u00a0NeedsMoreSources<\/code>\u00a0(a typed predicate over the writer’s output) and in the adapter executor that produces the\u00a0DraftReview<\/code>\u00a0payload. That is the tradeoff: explicit branch logic, typed edges, and the bridging code in the developer’s hands, instead of agent-driven routing.<\/p>\n<\/a><\/p>\nWorkflow pipeline = AgentWorkflowBuilder\r\n .CreateHandoffBuilderWith(researcher)\r\n .WithHandoff(researcher, writer)\r\n .WithHandoff(writer, editor)\r\n .WithHandoff(writer, researcher,\r\n handoffReason: \"Need additional research, sources, or fact-checking.\")\r\n .EnableReturnToPrevious()\r\n .Build();\r\n<\/code><\/pre>\n\n
Writer \u2192 Researcher<\/code>\u00a0is a back-edge<\/strong>\u00a0with an explicit description. The\u00a0Writer<\/code>\u00a0model now sees a synthetic handoff tool described as “Need additional research…” and can call it whenever it notices a gap. No decision executor is required.<\/li>\nEditor<\/code>\u00a0is terminal<\/strong>\u00a0(no outbound handoffs). When the editor finishes a turn, the workflow yields its conversation as output and pauses for the next user message.<\/li>\nEnableReturnToPrevious()<\/code>\u00a0keeps the workflow HITL-friendly with no additional code.<\/strong>\u00a0When the workflow pauses after the editor, the user’s next message (“Make it more formal”) goes to the editor rather than back to the researcher. Conversational follow-ups land where the user expects.<\/li>\n<\/ul>\nSequentialBuilder<\/code>\u00a0already exposes per-step HITL via\u00a0.with_request_info(agents=[...])<\/code>, which pauses the chain for user input between steps. That is a different shape of HITL than what Handoff provides: it is a fixed pause point, not a routing decision the agent makes. Use it when the human should always inspect the result before the next step; choose Handoff when the agent should decide whether the human (or another agent) needs to weigh in.<\/p><\/blockquote>\nWhen to Pick Which<\/h2>\n