feat(adapters/langgraph): compile ManagerWorkers into a hierarchical graph

[spichen]

ManagerWorkers had no LangGraph support: converting one fell through _convert and raised. This compiles it into a hierarchical graph.

                ┌─ delegate_to_w1 ─→ worker_1 ─┐
START → manager ┤                              ├→ manager (loop)
                └─ delegate_to_w2 ─→ worker_2 ─┘
                        │
                        └─ no tool_call ─→ END

The manager becomes a react agent holding one synthetic delegate_to_<worker> tool per worker. The parent graph intercepts that tool call in a conditional edge and fans out one Send per delegation, so a single manager turn can delegate to several workers at once. Each worker runs in an isolated message context and replies with a ToolMessage matched to its tool_call_id. Every call gets answered independently, since an unanswered one leaves a dangling call in the manager's next turn.

Workers are converted recursively into their own CompiledStateGraph and added as subgraph nodes, so astream_events still shows the parent/child boundary (subgraph=True) for tracing and SSE streaming. Nested ManagerWorkers compose through convert with no extra work.

ManagerWorkers now infers its inputs and outputs from the group manager, so it can sit inside a flow: an AgentNode wrapping one exposes input ports, and a DataFlowEdge into it resolves. The graph runs over MessagesState, which can't carry structured inputs inward, so node inputs are rendered into the group-manager prompt and the satisfied ports are dropped. AgentNodeExecutor compiles and caches that graph by rendered prompt, the same key it already uses for plain react agents.

The delegation protocol is deliberately visible: delegate_to_<worker> calls and their lifecycle events stream like any other tool call, because "the manager handed task X to worker Y" is usually the most informative thing a run produces. Nothing wraps astream_events to scrub it. A consumer that would rather not render the routing plumbing can recognize it with is_delegation_tool_name.

Structure

Helpers live in a new _managerworkers.py rather than growing _langgraphconverter.py; _manager_workers_convert_to_langgraph stays on the converter next to its siblings, and the flow-step compile sits on AgentNodeExecutor next to its react-agent equivalent.

Wrapping stream/astream in an execution span was already duplicated between the Agent and Flow paths, and ManagerWorkers needed a third copy. That wrapper is now a single patch_with_execution_span in _execution_span.py, parameterized by span and event factories, and all three paths call it.

Swarm is untouched.

Testing

tests/adapters/langgraph, tests/serialization and tests/validation with SKIP_LLM_TESTS=1, in a venv pinned to constraints/constraints.txt. The only failures are the pre-existing ones that need a live model endpoint. ruff is clean on the changed files.

The 25 ManagerWorkers tests all run offline, including the five flow-step ones in flows/test_managerworkers_node.py. They opt out of the blanket SKIP_LLM_TESTS construction guard via a new allow_llm_config_construction fixture — that guard skips a test the moment it builds an LLM config, which is right for tests that go on to call a model but hides tests that only need a config object and stub the conversion.

🤖 Generated with Claude Code