Agent Framework 1.25.0: six silent traps in the workflow wiring layer
I started reading the Microsoft Agent Framework workflow docs expecting a thin graph runner: executors are nodes, edges are wires, send_message passes data along, yield_output produces the result. Then I actually ran it. The problem with this layer is not the errors it raises. It is the errors it does not raise. Change one type annotation, or one keyword argument, and the workflow still exits clean and still hands you a result — except the result is empty.
Ground rules first: every number below comes from output I produced on this machine, not from reading documentation. Environment is Windows 11 with CPython 3.13.14, package installed with pip install --target into an isolated directory, version agent-framework 1.25.0 per PyPI (uploaded 2026-11-07 15:42 UTC, the newest release as of writing). Anything I did not run is listed in "Where this stops" at the end.
Start with the version: the docs are half a step ahead
This is not a style complaint. If you copy the official example, it fails on the first line.
The WorkflowBuilder API page on learn.microsoft.com lists 13 methods. I checked each one with hasattr against a 1.25.0 instance: only 7 exist, 6 do not — a 46.2% miss rate.
| Listed in the docs, missing in 1.25.0 | Docs and package agree |
|---|---|
add_agent, register_agent, register_executor | add_edge, add_chain, build |
set_max_iterations, set_start_executor, with_checkpointing | add_fan_in_edges, add_fan_out_edges, add_switch_case_edge_group, add_multi_selection_edge_group |
The sharper cut: every doc example opens with a no-argument WorkflowBuilder(). The real signature is WorkflowBuilder(*, max_iterations=100, name, description, start_executor, checkpoint_storage, output_from, intermediate_output_from, output_executors), and start_executor is a required keyword-only argument. So the first line of the official sample gives you:
TypeError: WorkflowBuilder.__init__() missing 1 required keyword-only argument: 'start_executor'
The only form that runs is this:
workflow = WorkflowBuilder(start_executor=upper, max_iterations=5).add_edge(upper, lower).build()
I will not guess which branch the docs were built from; I only report what is reproducible. The release cadence explains why this is easy to hit: on PyPI, 1.20 shipped 10-02, 1.21 on 10-08, 1.22 on 10-15, 1.23 on 10-22, 1.24 on 10-30, 1.25 on 11-07 — roughly one release a week, while the documentation site is not bound to the package version number. Take the version from PyPI, and take method existence from hasattr.
The smallest working loop: two nodes, nine events
You need a baseline that works, otherwise every "what's missing" below has nothing to compare against.
from typing import Never
from agent_framework import Executor, WorkflowBuilder, WorkflowContext, handler
class Upper(Executor):
@handler
async def process(self, text: str, ctx: WorkflowContext[str]) -> None:
await ctx.send_message(text.upper())
class Reverse(Executor):
@handler
async def process(self, text: str, ctx: WorkflowContext[Never, str]) -> None:
await ctx.yield_output(text[::-1])
up, rv = Upper(id="upper"), Reverse(id="reverse")
wf = WorkflowBuilder(start_executor=up).add_edge(up, rv).build()
result = await wf.run("hello")
print(result.get_outputs()) # ['OLLEH']
The two type parameters of WorkflowContext[Send, Yield] are the entire contract: what you send downstream, and what becomes the workflow result. Never means "this node sends nothing in that direction" — it is not decoration.
One run emits 9 events across two supersteps:
superstep_started -> executor_invoked('hello') -> executor_completed(['HELLO']) -> superstep_completed
superstep_started -> executor_invoked('HELLO') -> output('OLLEH') -> executor_completed(['OLLEH']) -> superstep_completed
Two details worth remembering: yield_output produces events of type output, and the order inside get_outputs() is node completion order. Also executor_completed.data is always a list, even when you sent a single message.
Six failures that raise nothing
All six build cleanly, run cleanly, and hand you an empty list or a partial result. I ran a control for each one to rule out my own mistakes.
One, no output annotation means type validation is skipped. If a source handler writes plain WorkflowContext without generics, the build-time compatibility check is skipped entirely, leaving one warning in the log:
Executor 'S' has no output type annotations. Type compatibility validation will be skipped for edges from this executor.
After that, mismatched messages get swallowed at runtime. I had the source send a float while the target declared handlers for str and int only. The target was never invoked, get_outputs() returned [], and nothing raised.
Two, a union type passes the build and still loses the message. The source declares WorkflowContext[str | int], the target handler accepts str. The build-time rule asks whether any source output type is compatible with any target input type — str is in the union, so it passes. But I actually sent 7, and the target received nothing:
build: OK (union contains str, validation passes)
run: OK target received=[] outputs=[]
This is the one I would worry about most. Static validation hands you a green light while the runtime branch takes the other arm of the union.
Three, one missing fan-in branch means the whole workflow "succeeds" with nothing. Fan out to two branches, fan in to one aggregator. If one branch does not send this time — a condition failed, or the handler returned early — the aggregator is never invoked, run() returns normally, outputs=[], and nothing warns:
both branches send OK joiner calls=1 batches=[['A(fan:go)', 'B(fan:go)']] out=["batch=..."]
A silent, B sends OK joiner calls=0 batches=[] out=[]
both silent OK joiner calls=0 batches=[] out=[]
The official wording is that the target "will only be executed once all source executors have completed." It omits the second half: a branch that never completes means the joiner never runs, and the workflow considers that a normal finish. If your joiner writes to a database or sends a notification, that is a silent data loss.
Four, writing output_from hides every node you did not list. Three nodes chained A to B to C, each calling yield_output. Seven variants measured:
| Configuration | get_outputs() | get_intermediate_outputs() |
|---|---|---|
| Neither argument passed | ['A-out','B-out','C-out'] | [] |
output_from="all" | ['A-out','B-out','C-out'] | [] |
output_from=[C] | ['C-out'] | [] |
output_from=[C] + intermediate="all_other" | ['C-out'] | ['A-out','B-out'] |
intermediate_output_from="all_other" | [] | ['A-out','B-out','C-out'] |
output_from=[] + intermediate="all_other" | [] | ['A-out','B-out','C-out'] |
output_from=[C] + intermediate=[B] | ['C-out'] | ['B-out'] |
2 of the 7 variants (28.6%) always return an empty output list. The rule is binary: pass neither argument and every yield is an output; pass either one and you are in explicit mode, where an unlisted node's yield goes to neither bucket and simply disappears. If you want "only the last node counts as the result", write output_from=[C] — not intermediate_output_from="all_other" alone.
Five, a constant-false edge condition is equivalent to no edge. add_edge(a, b, condition=lambda msg: False) builds, runs, and returns []. The condition is plain Python; a falsy return drops the message with no fallback warning. Branch routing needs an else path, or at minimum an explicit agreement about what the output is when nothing matches.
Six, an executor you never wired is not in the graph at all. Construct an executor and never add an edge, and you do not get an "isolated node" error, because it was never registered — get_executors_list() only contains nodes reachable from start_executor. That is different from an isolated node that is inside the graph, which does raise GraphConnectivityError.
Four real exceptions, copy-ready
Errors exist; they concentrate in the structural layer. All four reproduced on 1.25.0, messages verbatim.
First, TypeCompatibilityError, raised at build time — which is the good outcome. Source sends int, target accepts str only:
[TYPE_COMPATIBILITY] Type incompatibility between executors 'src' -> 'sink'.
Source executor outputs types ["<class 'int'>"] but target executor can only handle types ["<class 'str'>"].
The same exception produces a self-contradictory message in fan-in. The fan-in target must be annotated list[T] (the docs say it "must be compatible with a list of the output types of the source executors"). Write it as plain str out of habit and you get:
[TYPE_COMPATIBILITY] Type incompatibility between executors 'A' -> 'J'.
Source executor outputs types ["<class 'str'>"] but target executor can only handle types ["<class 'str'>"].
Source says str, target says str, and it still calls them incompatible. The validator wraps the source type in a list for fan-in groups, so the target has to accept list[str]. When you see this message, do not change the data type first — check whether the target is a fan-in join.
Second, EdgeDuplicationError. Add the same edge twice:
[EDGE_DUPLICATION] Duplicate edge detected: src->sink. Each edge in the workflow must be unique.
Third, GraphConnectivityError. Every fan-in source must be reachable from the start node:
[GRAPH_CONNECTIVITY] The following executors are unreachable from the start executor 'A': ['B'].
So a fan-in cannot introduce a new starting point. Fan out (or add plain edges) until every source has an inbound edge.
Fourth, WorkflowConvergenceException, default cap 100. A cycle with no termination condition throws after the hundredth iteration:
Runner did not converge after 100 iterations.
What max_iterations actually counts was worth a boundary test (self-loop, +1 per pass). There is no off-by-one; the cap equals the number of invocations:
max_iterations | Actual invocations | Outcome |
|---|---|---|
| 1 | 1 | raises |
| 2 | 2 | raises |
| 3 | 3 | raises |
| 5 | 5 | raises |
| 5 (terminates exactly on call 5) | 5 | succeeds, ['stopped@5'] |
| 3 (terminates exactly on call 3) | 3 | succeeds, ['stopped@3'] |
So "at most N steps" is calculable: set N to your intended maximum node invocations, and finishing exactly on the Nth call will not throw. A self-loop also only prints a note at build time rather than blocking:
Self-loop detected: Executor 'bump' connects to itself. This may cause infinite recursion if not properly handled with conditions.
Fan-in ordering: two tutorials disagree, measurement gives a third answer
This deserves its own section because I found two opposite claims in third-party write-ups: one says the joined list "reflects concurrent completion order, so it can vary run to run", the other says "in source-id order". Neither matched.
Design: three workers with ids Z, A, M, declared as fan-in sources [Z, A, M], with a 30–60 ms delay added to one of them.
declared [Z, A, M] delay={Z:0, A:0.06} -> join received ['Z', 'A', 'M']
declared [Z, A, M] delay={Z:0.06, A:0} -> join received ['Z', 'A', 'M']
declared [M, Z, A] delay={all 0} -> join received ['M', 'Z', 'A']
Delay in the middle, delay at the front — output does not move. Change the declaration to [M, Z, A] and the output follows immediately. Five consecutive runs were stable; 8 of 8 runs agreed. The conclusion: order is the order of the sources list you pass to add_fan_in_edges, not completion order, and not id sort order (that would have been A, M, Z).
The model explains it: fan-in is a per-superstep barrier. Every source finishes within the same superstep, then the runtime flushes in declaration order. Both tutorials' advice to sort inside the joiner is correct, but the reason is not "concurrency is nondeterministic" — it is that this order was never a contract you should rely on. I sort aggregated results purely to keep logs readable.
A wiring checklist
Condensed into something you can walk through in code review:
1. Annotate every handler with the full WorkflowContext[Send, Yield], using Never where nothing is sent. No generics means skipped validation means messages can vanish at runtime.
2. Fan-in targets must be declared list[T], never T; and a join node cannot mix a plain edge with a fan-in group — that fails at build time.
3. Every fan-in source needs an inbound edge, or you get GraphConnectivityError.
4. Use exactly one output mode: either pass neither argument so every yield is a result, or list every node explicitly. Half-and-half produces "I yielded it but it is not in the results."
5. With a cycle, set max_iterations explicitly and compute your intended maximum invocation count (measured 1:1).
6. Give conditional edges a default path; a falsy condition drops the message and the downstream node may never receive anything.
7. Use the three read-only inspectors: wf.input_types, wf.output_types, wf.get_output_executors(). The first two tell you the entry type and the set of result types; the third lists whose yield becomes a result — and that one catches failure number four before you ship.
Troubleshooting: three errors you get by copying the docs
Error one, TypeError: object NoneType can't be used in 'await' expression. A class-based handler written as a plain sync function (no async) is not rejected by @handler and not rejected by build(); it blows up at runtime. The trap is asymmetric: the functional @executor decorator does support sync functions (the docs state they run in a thread pool), so "can I use a sync function here" has two different answers depending on whether your node is class-based or function-based. Fix: always async def for class-based handlers.
Error two, TypeError: WorkflowBuilder expected designation entries to be Executor or SupportsAgentRun instances; got str. output_from accepts executor instances, not id strings. You may expect output_from=["C"] as in some other frameworks; you need output_from=[c].
Error three, RuntimeError: Start executor 'a' cannot handle input of type 'str'. Expected input types: [<class 'int'>]. The value passed to wf.run(...) must match the start handler's first positional parameter type. At least this one is explicit — a lot better than the six failures above.
Where this stops
- One version only, 1.25.0, no cross-version regression. Behavior tracks versions; when in doubt trust your local
hasattrand your own run output. - Pure Python executors only, no model calls. Agent nodes, MCP tools, streaming, sub-workflows, checkpoints and resume,
add_switch_case_edge_groupandadd_multi_selection_edge_groupare all untested here. - The docs-versus-package delta is reported only where reproducible (
hasattrresults, verbatim messages). I do not claim which unreleased branch the docs mirror. - Version and upload date per PyPI; 1.25.0 was the newest release as of writing.
One comparison worth stating: this layer resembles LangGraph's superstep model — both advance in supersteps, both cap cycles — but their strictness runs opposite. LangGraph barely inspects types on an edge; Agent Framework inspects them hard, then leaks in exactly two places: missing annotations and union types. If you read my earlier LangGraph streaming entry points test, treat this piece as a second implementation of the same execution model.
No affiliate links in this article, and no product recommendations. Every snippet ran on this machine; every exception block is pasted from terminal output. If you cannot reproduce a result, the version is the first thing to check — print agent_framework.__version__ before anything else. Two related measurements in the same family of "green checks, wrong result": gRPC defaults covers protocol-level defaults, and seven silent unittest.mock traps covers test doubles that pass without testing anything.
👉 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.