feat(adapters/langgraph): allow ManagerWorkers members and flow steps in a Swarm

[spichen]

Summary

Third of three PRs split out of #19. Base is feat/managerworkers-adapter (#30), which it depends on for the ManagerWorkers compiler.

Swarm was already supported in the LangGraph adapter — top-level, made of plain Agents. This closes three gaps, none of which needed the Swarm compiler to change shape.

ManagerWorkers as a Swarm member

A member had to be a plain Agent; anything else raised. A ManagerWorkers can decide a handoff too — its group manager is the LLM that emits the transfer tool call — so it's now accepted.

It can't use langgraph_swarm.create_handoff_tool: that tool's Command(graph=PARENT) lands on the ManagerWorkers graph, one level short of the Swarm, and is dropped. Instead the manager gets synthetic transfer_to_<sibling> tools, and the MW parent graph grows a __handoff__ node that re-emits the handoff upward.

Transcript validity is the subtle part: the MW graph exits via the PARENT command rather than its own END, so its internal messages don't merge into the shared Swarm conversation. The node therefore forwards the transfer AIMessage plus a ToolMessage answering every still-open tool call on it — including delegations emitted in the same turn — so the Swarm sees a well-formed call/result sequence. An orphan ToolMessage would 400 the next member's LLM.

A member that is neither an Agent nor a ManagerWorkers (a Flow, a nested Swarm) now raises NotImplementedError rather than ValueError — there's no single "decide-the-handoff" LLM to attach transfer tools to.

Swarm as a flow step

An AgentNode wrapping a Swarm raised TypeError from AgentNodeExecutor. It now compiles through the same composite-graph path as ManagerWorkers, with node inputs rendered into the first_agent prompt.

Swarm input/output inference

Swarm now infers its inputs/outputs from first_agent, so a flow AgentNode wrapping one exposes input ports and a DataFlowEdge into it resolves at load. Symmetric with the ManagerWorkers change in #30.

Note on the routing helper

_route_manager_to_worker_or_end gains the handoff branch and is renamed to _route_manager_to_worker_handoff_or_end. Handoff wins over delegation within a turn, since it transfers the whole conversation; same-turn delegations are answered-and-dropped by the handoff node.

Testing

tests/adapters/langgraph, tests/serialization, tests/validation with SKIP_LLM_TESTS=1, in a venv pinned to constraints/constraints.txt: identical results to the original unsplit #19 branch. black / isort / pyflakes clean on the changed files.

The tip of this branch is byte-identical to #19's head, so the three-way split is lossless.

⚠️ Same coverage gap as #30: all of flows/test_swarm_node.py is skipped under SKIP_LLM_TESTS=1 (the tests/adapters/conftest.py LLM guard fires on config construction), so the Swarm flow-step path is unverified in offline CI. Worth fixing separately.

🤖 Generated with Claude Code