Multi-Agent | The .NET Blog

The Handoff Pattern: When One Agent Isn't Enough

Emiliano Montesdeoca — Mon, 01 Jun 2026 00:00:00 +0000

At some point every multi-agent system outgrows a simple router. The first sign is usually when a specialist agent needs to ask a follow-up question, or realizes mid-turn that another agent should continue. A fixed pipeline breaks there. A one-shot router breaks there.

That’s exactly the problem the Handoff orchestration pattern in Microsoft Agent Framework is designed for.

How Handoff Works

The developer declares a graph: here are the agents, here are the edges between them. The framework does the rest — it synthesizes a handoff tool per outbound edge and injects it into each agent. When an agent decides to pass control, it calls the tool. The framework enforces the topology.

Three things make this different from just having agents call each other:

One shared transcript — the receiving agent sees the full conversation history. No starting from scratch.
Topology enforcement — an agent can only hand off to declared targets. You catch routing bugs at authoring time, not in production.
Natural termination — when the active agent finishes its turn without calling a handoff tool, the workflow yields to the user. No polling, no explicit exit conditions.

A Minimal Example

In .NET, building a handoff workflow looks like this:

using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Workflows;

AIAgent triage = chatClient.AsAIAgent(
 instructions: "Route to the right specialist.",
 name: "Triage");

AIAgent billing = chatClient.AsAIAgent(
 instructions: "Handle billing questions.",
 name: "Billing");

AIAgent tech = chatClient.AsAIAgent(
 instructions: "Handle technical support.",
 name: "Tech");

var workflow = HandoffWorkflow.Create()
 .Add(triage, targets: [billing, tech])
 .Add(billing, targets: [triage])
 .Add(tech, targets: [triage, billing]);

Triage can send to either specialist. Both specialists can send back to triage. The graph is acyclic-friendly but supports back-edges when you need them (“I need more info” → back to research).

When to Use Handoff (and When Not To)

Handoff is a good fit when:

Ownership can change mid-conversation — an agent may realize it’s the wrong specialist
Back-edges matter — you might need to revisit an earlier step without restarting
Routing decisions are fuzzy — the choice to hand off is contextual and better made by the model than typed predicates

It’s not the right choice when:

Your pipeline is fixed and sequential — use the Sequential workflow for that
Each step is independent — agents sharing a transcript where only one of them needed it is just noise
You need strict processing guarantees — the non-determinism of model-driven routing isn’t what you want

Back-Edges and Human-in-the-Loop

One of the more interesting shapes Handoff enables is genuine back-edges. An agent can decide “I don’t have enough information” and route back to a research step, not with a hardcoded loop, but because the model decides it’s the right call.

Human-in-the-loop interactions also compose naturally. When a specialist needs user input, the workflow yields back to the user via the default turn loop, collects the response, and resumes with full context. The agent never lost the conversation.

Wrapping Up

Handoff is one of those patterns that sounds simple but enables a lot once you internalize it: decentralized routing, shared context, enforced topology, natural termination. It’s the right next step when your agents start saying “actually, someone else should handle this.”

Read the full walkthrough in the original post: A Tour of the Handoff Orchestration Pattern

Building Real-Time Multi-Agent UIs That Don't Feel Like a Black Box

Emiliano Montesdeoca — Fri, 10 Apr 2026 00:00:00 +0000

Here’s the thing about multi-agent systems: they look incredible in demos. Three agents passing work around, solving problems, making decisions. Then you try to put it in front of actual users and… silence. A spinning indicator. No idea which agent is doing what or why the system is paused. That’s not a product — that’s a trust problem.

The Microsoft Agent Framework team just published a fantastic walkthrough on pairing MAF workflows with AG-UI, an open protocol for streaming agent execution events to a frontend over Server-Sent Events. And honestly? This is the kind of bridge we’ve been missing.

Why this matters for .NET developers

If you’re building AI-powered apps, you’ve probably hit this wall. Your backend orchestration works great — agents hand off to each other, tools fire, decisions get made. But the frontend has no clue what’s happening behind the scenes. AG-UI fixes that by defining a standard protocol for streaming agent events (think RUN_STARTED, STEP_STARTED, TOOL_CALL_*, TEXT_MESSAGE_*) directly to your UI layer over SSE.

The demo they built is a customer support workflow with three agents: a triage agent that routes requests, a refund agent that handles money stuff, and an order agent that manages replacements. Each agent has its own tools, and the handoff topology is explicitly defined — no “figure it out from the prompt” vibes.

The handoff topology is the real star

What caught my eye is how HandoffBuilder lets you declare a directed routing graph between agents:

builder = HandoffBuilder(
 name="ag_ui_handoff_workflow_demo",
 participants=[triage, refund, order],
 termination_condition=termination_condition,
)

(
 builder
 .add_handoff(triage, [refund], description="Refunds, damaged-item claims...")
 .add_handoff(triage, [order], description="Replacement, exchange...")
 .add_handoff(refund, [order], description="Replacement logistics needed after refund.")
 .add_handoff(order, [triage], description="After replacement/shipping tasks complete.")
)

Each add_handoff creates a directed edge with a natural-language description. The framework generates handoff tools for each agent based on this topology. So routing decisions are grounded in your orchestration structure, not just whatever the LLM feels like doing. That’s a huge deal for production reliability.

Human-in-the-loop that actually works

The demo showcases two interrupt patterns that any real-world agent app needs:

Tool approval interrupts — when an agent calls a tool marked with approval_mode="always_require", the workflow pauses and emits an event. The frontend renders an approval modal with the tool name and arguments. No token-burning retry loops — just a clean pause-approve-resume flow.

Information request interrupts — when an agent needs more context from the user (like an order ID), it pauses and asks. The frontend shows the question, the user responds, and execution resumes from exactly where it stopped.

Both patterns stream as standard AG-UI events, so your frontend doesn’t need custom logic per agent — it just renders whatever event comes through the SSE connection.

Wiring it up is surprisingly simple

The integration between MAF and AG-UI is a single function call:

from agent_framework.ag_ui import (
 AgentFrameworkWorkflow,
 add_agent_framework_fastapi_endpoint,
)

app = FastAPI()

demo_workflow = AgentFrameworkWorkflow(
 workflow_factory=lambda _thread_id: create_handoff_workflow(),
 name="ag_ui_handoff_workflow_demo",
)

add_agent_framework_fastapi_endpoint(
 app=app, agent=demo_workflow, path="/handoff_demo",
)

The workflow_factory creates a fresh workflow per thread, so each conversation gets isolated state. The endpoint handles all the SSE plumbing automatically. If you’re already using FastAPI (or can add it as a lightweight layer), this is almost zero friction.

My take

For us .NET developers, the immediate question is: “Can I do this in C#?” The Agent Framework is available for both .NET and Python, and the AG-UI protocol is language-agnostic (it’s just SSE). So while this specific demo uses Python and FastAPI, the pattern translates directly. You could wire up an ASP.NET Core minimal API with SSE endpoints following the same AG-UI event schema.

The bigger takeaway is that multi-agent UIs are becoming a first-class concern, not an afterthought. If you’re building anything where agents interact with humans — customer support, approval workflows, document processing — this combination of MAF orchestration and AG-UI transparency is the pattern to follow.

Wrapping up

AG-UI + Microsoft Agent Framework gives you the best of both worlds: robust multi-agent orchestration on the backend and real-time visibility on the frontend. No more black-box agent interactions.

Check out the full walkthrough and the AG-UI protocol repo to dig deeper.

Microsoft Agent Framework Hits 1.0 — Here's What Actually Matters for .NET Developers

Emiliano Montesdeoca — Fri, 03 Apr 2026 00:00:00 +0000

If you’ve been following the Agent Framework journey from the early Semantic Kernel and AutoGen days, this one is significant. Microsoft Agent Framework just hit version 1.0 — production-ready, stable APIs, long-term support commitment. It’s available for both .NET and Python, and it’s genuinely ready for real workloads.

Let me cut through the announcement noise and focus on what matters if you’re building AI-powered apps with .NET.

The short version

Agent Framework 1.0 unifies what used to be Semantic Kernel and AutoGen into a single, open-source SDK. One agent abstraction. One orchestration engine. Multiple AI providers. If you’ve been bouncing between Semantic Kernel for enterprise patterns and AutoGen for research-grade multi-agent workflows, you can stop. This is the one SDK now.

Getting started is almost unfairly simple

Here’s a working agent in .NET:

// dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry;
using Azure.Identity;

var agent = new AIProjectClient(endpoint: "https://your-project.services.ai.azure.com")
 .GetResponsesClient("gpt-5.3")
 .AsAIAgent(
 name: "HaikuBot",
 instructions: "You are an upbeat assistant that writes beautifully."
 );

Console.WriteLine(await agent.RunAsync("Write a haiku about shipping 1.0."));

That’s it. A handful of lines and you have an AI agent running against Azure Foundry. The Python equivalent is equally concise. Add function tools, multi-turn conversations, and streaming as you go — the API surface scales up without getting weird.

Multi-agent orchestration — this is the real deal

Single agents are fine for demos, but production scenarios usually need coordination. Agent Framework 1.0 ships with battle-tested orchestration patterns straight from Microsoft Research and AutoGen:

Sequential — agents process in order (writer → reviewer → editor)
Concurrent — fan out to multiple agents in parallel, converge results
Handoff — one agent delegates to another based on intent
Group chat — multiple agents discuss and converge on a solution
Magentic-One — the research-grade multi-agent pattern from MSR

All of them support streaming, checkpointing, human-in-the-loop approvals, and pause/resume. The checkpointing part is crucial — long-running workflows survive process restarts. For us .NET developers who’ve built durable workflows with Azure Functions, this feels familiar.

The features that matter most

Here’s my shortlist of what’s worth knowing:

Middleware hooks. You know how ASP.NET Core has middleware pipelines? Same concept, but for agent execution. Intercept every stage — add content safety, logging, compliance policies — without touching agent prompts. This is how you make agents enterprise-ready.

Pluggable memory. Conversational history, persistent key-value state, vector-based retrieval. Choose your backend: Foundry Agent Service, Mem0, Redis, Neo4j, or roll your own. Memory is what turns a stateless LLM call into an agent that actually remembers context.

Declarative YAML agents. Define your agent’s instructions, tools, memory, and orchestration topology in version-controlled YAML files. Load and run with a single API call. This is a game-changer for teams that want to iterate on agent behavior without redeploying code.

A2A and MCP support. MCP (Model Context Protocol) lets agents discover and invoke external tools dynamically. A2A (Agent-to-Agent protocol) enables cross-runtime collaboration — your .NET agents can coordinate with agents running in other frameworks. A2A 1.0 support is coming soon.

The preview features worth watching

Some features shipped as preview in 1.0 — functional but APIs may evolve:

DevUI — a browser-based local debugger for visualizing agent execution, message flows, and tool calls in real time. Think Application Insights, but for agent reasoning.
GitHub Copilot SDK and Claude Code SDK — use Copilot or Claude as an agent harness directly from your orchestration code. Compose a coding-capable agent alongside your other agents in the same workflow.
Agent Harness — a customizable local runtime giving agents access to shell, file system, and messaging loops. Think coding agents and automation patterns.
Skills — reusable domain capability packages that give agents structured capabilities out of the box.

Migrating from Semantic Kernel or AutoGen

If you have existing Semantic Kernel or AutoGen code, there are dedicated migration assistants that analyze your code and generate step-by-step migration plans. The Semantic Kernel migration guide and AutoGen migration guide walk you through everything.

If you’ve been on the RC packages, upgrading to 1.0 is just a version bump.

Wrapping up

Agent Framework 1.0 is the production milestone that enterprise teams have been waiting for. Stable APIs, multi-provider support, orchestration patterns that actually work at scale, and migration paths from both Semantic Kernel and AutoGen.

The framework is fully open source on GitHub, and you can get started today with dotnet add package Microsoft.Agents.AI. Check out the quickstart guide and the samples to get your hands dirty.

If you’ve been waiting for the “safe to use in production” signal — this is it.

Getting Started with Microsoft Agent Framework

Emiliano Montesdeoca — Thu, 05 Mar 2026 00:00:00 +0000

The Microsoft Agent Framework (MAF) is a .NET SDK for building multi-agent AI systems. Rather than a single “do everything” prompt, you compose specialized agents — each with their own tools and instructions — and let them hand off work to each other.

This tutorial walks you through building a simple two-agent system: a triage agent that routes requests and a resolver agent that handles them.

Prerequisites

.NET 8 or later
NuGet: Microsoft.AI.Agents.Core
An Azure OpenAI or OpenAI API key

Step 1: Install packages

dotnet new console -n AgentDemo
cd AgentDemo
dotnet add package Microsoft.AI.Agents.Core
dotnet add package Microsoft.SemanticKernel

Step 2: Define your first agent

Agents are defined with a name, instructions, and a set of tools (Semantic Kernel plugins):

using Microsoft.AI.Agents.Core;
using Microsoft.SemanticKernel;

var kernel = Kernel.CreateBuilder()
 .AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!,
 apiKey: Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY")!
 )
 .Build();

var triageAgent = new ChatCompletionAgent
{
 Name = "TriageAgent",
 Instructions = """
 You are a triage agent. Classify incoming requests as either:
 - 'billing' — questions about invoices, payments, or subscriptions
 - 'technical' — questions about bugs, features, or how the product works
 Then hand off to the appropriate agent.
 """,
 Kernel = kernel
};

Step 3: Define the resolver agent

var resolverAgent = new ChatCompletionAgent
{
 Name = "ResolverAgent",
 Instructions = """
 You are a support resolver. You receive pre-triaged requests and provide
 clear, concise answers. Always end with a confirmation question.
 """,
 Kernel = kernel
};

Step 4: Set up handoff topology

MAF’s HandoffBuilder lets you declare a routing graph between agents:

var chat = new AgentGroupChat(triageAgent, resolverAgent)
{
 ExecutionSettings = new AgentGroupChatSettings
 {
 TerminationStrategy = new ApprovalTerminationStrategy()
 }
};

Step 5: Run the workflow

chat.AddChatMessage(new ChatMessageContent(
 AuthorRole.User,
 "My invoice from last month looks wrong — I was charged twice."
));

await foreach (var response in chat.InvokeAsync())
{
 Console.WriteLine($"[{response.AuthorName}]: {response.Content}");
}

MAF will call the triage agent first, which classifies the issue as “billing” and hands off to the resolver agent. You’ll see each agent’s turn in the output.

What to explore next

Tool calling — give agents access to APIs, databases, or file systems via SK plugins
Human-in-the-loop — use ApprovalTerminationStrategy to pause for human confirmation before high-risk actions
AG-UI integration — stream agent events to a frontend using the AG-UI protocol for real-time visibility
Observability — connect to Azure Monitor or OpenTelemetry to trace agent decisions

The MAF documentation and samples on GitHub cover production patterns including state persistence and long-running workflows.