← Back to Home

Agent Framework: 4 Orchestrations, 6 Silent Traps

agent-frameworkorchestrationmulti-agent

Most framework comparisons ask whether a tool supports handoffs or parallelism. The problems that cost me a rewrite were different: the code finished, the exit code was 0, nothing in the log looked like an error, and the output was either wrong or empty.

I tested the four built-in orchestrations in Microsoft Agent Framework 1.25.0 (the orchestration subpackage is agent_framework_orchestrations 1.4.2) without connecting a single language model. There are no affiliate links in this article, and every number below can be reproduced on your own machine with the harness in the middle of this post.

Four orchestrations are four answers to "who owns control"

The official documentation lists five built-in patterns: sequential, concurrent, handoff, group chat, and magentic. The first four differ in one sentence each:

That split matters because every trap below comes from this design choice, not from a bug. The overview page at https://learn.microsoft.com/en-us/agent-framework/workflows/orchestrations/ gives you the comparison table but not the defaults, and the defaults are where people get hurt.

If you have not touched the workflow layer yet, read the earlier Agent Framework 1.25.0 wiring test first. That one covers type contracts between executors and edges; this one starts one level up, at the orchestrators.

A harness that needs no model

You do not need a real model to observe orchestration behaviour. BaseChatClient has exactly one method you must override, and it can return fixed text.

import asyncio
from agent_framework import BaseChatClient, ChatResponse, Message

class ScriptedClient(BaseChatClient):
    def __init__(self, tag, delay=0.0):
        super().__init__()
        self.tag = tag
        self.delay = delay
        self.calls = 0

    async def _inner_get_response(self, *, messages, stream, options, **kwargs):
        self.calls += 1
        await asyncio.sleep(self.delay)
        return ChatResponse(messages=[Message('assistant', [f'{self.tag}#{self.calls}'])])

def agent(client, name):
    return client.as_agent(name=name, instructions=name)

The calls counter is the important part. It answers "how many times was this participant actually invoked", which is usually the only evidence you get at a failure site.

Reproduction environment: Windows 11, CPython 3.13.14, agent-framework==1.25.0, agent-framework-orchestrations==1.4.2. I installed into an isolated directory so the main environment stayed clean:

pip install --target ./tmp/w46-af agent-framework-orchestrations

Then put that directory on PYTHONPATH at runtime. Note that --target does not execute .pth files, so any subpackage that registers paths that way will fail at import time, and that failure looks exactly like "the upstream package is broken".

Sequential: by default you only get the last participant

Three participants, 0.20 s of fake latency each, three runs:

SER 0.646s out=['Z#1']  calls=[1, 1, 1]
SER 0.645s out=['Z#1']  calls=[1, 1, 1]
SER 0.644s out=['Z#1']  calls=[1, 1, 1]

All three were invoked (calls is 1 for each), yet the output event contains only Z#1. The replies from A and B do not exist in the orchestration result.

This is not a bug. It is the default meaning of output_from: only the last participant's response counts as terminal output, and everything earlier lives in the internal conversation history. If you want to post-process intermediate results, you have to opt in:

from agent_framework_orchestrations import SequentialBuilder

wf = SequentialBuilder(
    participants=[a1, a2, a3],
    intermediate_output_from='all',
).build()

But there is a counter-intuitive consequence. After setting intermediate_output_from to 'all', the event stream became three intermediate events and zero output events:

[('intermediate', 'A#1'), ('intermediate', 'B#1'), ('intermediate', 'C#1')]

Everything got demoted, and no terminal output is left. This is the same rule the handoff docs describe as "the demotion is silent and intentional", just applied where it is easier to trip over. The check is simple: the number of output events must equal the number of terminal results you expect. Zero means you wrote it wrong.

Concurrent: the parallelism is real, the concatenation order is not

Same three participants at 0.20 s each, three runs, median reported:

PAR 0.207s / 0.213s / 0.214s
median parallel=0.213s serial=0.645s speedup=3.03x saving=67.0%

The parallelism is genuine: wall clock equals the slowest participant, not the sum, and the 3.03x speedup matches the participant count.

The trap is ordering. I set the three delays to 0.30 / 0.05 / 0.01 seconds, so completion order has to be fast, mid, slow. The output event text was:

ORDER slow#1mid#1fast#1 [0, 6, 11] decl-order
declaration-order stable 3/3

Results are concatenated in declaration order, with no relation to completion order, 3 out of 3 runs. That has a direct downstream consequence: if you feed concurrent results to a summarizer in output order, the summarizer sees a stable ordering that has nothing to do with latency. If your downstream logic needs "first to finish wins", you must carry a timestamp yourself rather than rely on event order.

This is also the same mechanism behind the fan-in behaviour measured in the 11-08 article: the framework barriers at superstep level and flushes one batch at a time, so the declared order wins.

Handoff: no routing rules means everyone can route

The first obstacle in handoff orchestration is not at runtime, it is at build():

from agent_framework_orchestrations import HandoffBuilder

wf = (
    HandoffBuilder(participants=[triage, specialist])
    .with_start_agent(triage)
    .build()
)

That code raises immediately:

ValueError: Handoff workflows require all participant agents to have
'require_per_service_call_history_persistence=True'. The following agents are
missing this setting: triage, specialist. Set this flag when constructing each
Agent to ensure local history stays consistent with the service across handoff
tool-call short-circuits.

The reason is stated plainly: handoff is implemented as a tool-call short-circuit, so local history must stay in step with the service. Every participant needs the flag:

triage = triage_client.as_agent(
    name='triage',
    instructions='triage',
    require_per_service_call_history_persistence=True,
)

The second obstacle is routing. The official handoff page says "By default, all agents can handoff to each other", and one line later: "Even with custom handoff rules, all agents are still connected in a mesh topology... The handoff rules only govern which agents can take over the conversation next."

I confirmed the default empirically. With no add_handoff call at all, a handoff_to_specialist call from triage still succeeded: HandoffSentEvent(source='triage', target='specialist') appeared and the specialist was invoked once. So "no routing configured" does not mean "cannot transfer"; it means "anyone can transfer to anyone". To actually narrow the topology you write it out:

wf = (
    HandoffBuilder(participants=[triage, specialist])
    .with_start_agent(triage)
    .add_handoff(triage, [specialist], description='escalate to specialist')
    .build()
)

And the moment you configure only one direction (triage can reach specialist, specialist cannot return), the log says:

No handoff configuration found for agent 'specialist'. This agent will not be
able to hand off to any other agents and your workflow may get stuck.

That warning is the only signal, and it does not stop execution.

Group chat: max_rounds counts turns, not full rounds

GroupChatBuilder needs a decision-maker on top of the participants. Leave it out and you get:

ValueError: No orchestrator has been configured. Pass orchestrator_agent,
orchestrator, or selection_func to the constructor.

Give it a selector that always returns the same agent and set max_rounds to 3:

from agent_framework_orchestrations import GroupChatBuilder

wf = GroupChatBuilder(
    participants=[x, y],
    selection_func=lambda state: 'x',
    max_rounds=3,
).build()

The result: x was invoked 3 times, y was invoked 0 times, and the log printed GroupChatOrchestrator reached max_rounds=3; forcing completion.

So max_rounds counts turns, not "everyone spoke once". The intuitive reading ("two agents, three rounds each") is wrong: with max_rounds=3 you get three turns total. If the selector is biased, one participant may never speak, and the workflow finishes normally with a single warning line.

Six traps that do not raise

Ranked by damage:

1. No add_handoff gives you a full mesh, not "no transfers". A narrowed topology must be declared.

2. A plain BaseChatClient cannot execute handoff tools. My first harness was a plain BaseChatClient: triage was invoked once, specialist 0 times, zero handoff events, the output event's data was an empty string, and the workflow then parked on request_info waiting for user input. The only signal was one logger.warning, with no exception. The framework checks isinstance(client, FunctionInvocationLayer) before executing tools and silently skips when it fails. Making the client inherit FunctionInvocationLayer made the specialist run once and produced a handoff event on the same script.

3. Handoff tool names are silently truncated to 64 characters. The handoff page states the name "limits the result to 64 characters. The resulting name must be unique." I tested two agent ids that differ only at character 80:

   from agent_framework_orchestrations._handoff import get_handoff_tool_name
   long_id = 'specialist-' + 'x' * 80
   get_handoff_tool_name(long_id) == get_handoff_tool_name(long_id + 'A')  # True

Two different targets map to one tool name, and the framework performs no collision check. Long ids (tenant-prefixed, for example) need shortening on your side.

4. Sequential orchestration returns only the last participant by default; earlier replies never reach output.

5. intermediate_output_from='all' drives terminal output to zero, leaving only intermediate events.

6. Concurrent results are concatenated in declaration order, unrelated to completion order; downstream code that needs ordering must carry its own timestamp.

Troubleshooting: four real errors and their fixes

All four below are literal output from my machine, not a reconstructed "typical error".

Error 1: handoff requires the history persistence flag at build time

Symptom: HandoffBuilder(...).build() raises the ValueError: Handoff workflows require all participant agents to have 'require_per_service_call_history_persistence=True' shown above, listing every participant that is missing the flag.

Cause: handoff is implemented as a tool-call short-circuit, so local history must match the service turn by turn.

Fix: pass require_per_service_call_history_persistence=True to as_agent(...) for each participant.

Error 2: the second argument of add_handoff is a list of agents, not a config object

Symptom:

TypeError: 'HandoffConfiguration' object is not iterable

Cause: the signature is add_handoff(self, source, targets, *, description=None), and targets takes a sequence of agents. HandoffConfiguration is an internal structure, not an input.

Fix: add_handoff(triage_agent, [specialist_agent], description='...').

Error 3: the handoff source must be an agent instance

Symptom:

TypeError: Invalid starting agent reference: HandoffConfiguration

Cause: passing a HandoffConfiguration as the source. The resolver only accepts a string or an agent, and raises this when neither matches.

Fix: pass agent instances for both source and targets, and express routing through the second argument.

Error 4: group chat has two required pieces

Symptom one, no participants:

ValueError: Either participants or participant_factories must be provided.

Symptom two, no selector:

ValueError: No orchestrator has been configured. Pass orchestrator_agent,
orchestrator, or selection_func to the constructor.

Cause: "who speaks next" must be decided externally; the framework ships no default policy.

Fix: use participant_factories when participants must be rebuilt (stateful agents), otherwise pass participants. Then pick one of the three selector options, and the cheapest is selection_func.

Three semantic differences from LangGraph

This site already covered LangGraph's supervisor and swarm topologies in six differences between supervisor and swarm, so I will not repeat internals. Only the semantics that change when you switch frameworks:

Decision tree: ask who decides the next step

Skip the feature matrix and ask four questions:

1. Is the next step a fixed order? Then sequential. Every step is deterministic and the logs are the easiest to read.

2. Does the next step need all previous results? Then run concurrent and aggregate, but remember the concatenation order is declaration order.

3. Should the current handler decide? Then handoff, and accept that it is interactive: when an agent does not hand off, the workflow hands control back to the user (or continues automatically under autonomous mode, 50 turns by default).

4. Do several parties need to keep talking about one issue? Then group chat, where max_rounds is a total-turn budget and the quality of the selector determines fairness.

One prerequisite people skip: once you pass four participants, the default full mesh becomes risky. Every extra participant grows the routing combinations quadratically, and the default topology will never tell you.

FAQ

Q: Can I observe all of this without a model?

Yes. Every result here comes from a scripted client. Orchestration behaviour is decided by framework code, not model quality. The model only affects whether tool calls are emitted, which is exactly why you want a script to control that.

Q: Why is my output event an empty string?

Check whether the client inherits FunctionInvocationLayer first. With a plain BaseChatClient, the agent response contains a tool call and no text, so output.data is empty and the workflow parks on request_info.

Q: How does max_rounds actually count?

By turns, not by full rounds. Set max_rounds=3 for two participants and you get at most three turns, possibly all from one agent.

Q: Is handoff the same thing as LangGraph's handoff?

Same name, different semantics. Agent Framework's handoff is "an agent calls a tool and hands control over", with a full mesh by default. LangGraph's handoff is closer to a state transition whose destination you define as a node.

Pre-flight checklist

Run this list before shipping and you avoid five of the six traps:

If you are comparing orchestration semantics across frameworks, treat these as a parity table: run the same business flow through all four patterns and watch which defaults quietly decide things for you. That layer is where a framework switch actually costs you a rewrite. For the packaging side of the same series, continue with how to read the 31 subpackages.

👉 Join Xiaomi MiMo Platform: Leading AI model platform with cost-effective inference

👉 Join Aliyun AI: Top AI products with exclusive coupons for business innovation

📌 This article was AI-assisted generated and human-reviewed | TechPassive — An AI-driven content testing site focused on real tool reviews

🔗 Recommended Tools

These are carefully selected tools. Using our affiliate links supports us to keep producing quality content:

As an Amazon Associate, I earn from qualifying purchases at no extra cost to you.

☁️ DigitalOcean Cloud ⚡ Vultr VPS 🤖 QoderWork CN (Refer & Earn) ☁️ Aliyun AI Products 📚 WordPress Books 🧠 AI & LLM Books 🏗️ System Design Books 🐳 Docker & K8s Books 🐧 Linux Admin Books 🐍 Python Books 🗄️ Database Books 🚀 DevOps & SRE Books 🤖 Xiaomi MiMo Platform
← Back to Home