Skip to content

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

Open
spichen wants to merge 3 commits into
oracle:mainfrom
spichen:feat/managerworkers-adapter
Open

feat(adapters/langgraph): compile ManagerWorkers into a hierarchical graph#211
spichen wants to merge 3 commits into
oracle:mainfrom
spichen:feat/managerworkers-adapter

Conversation

@spichen

@spichen spichen commented Jul 25, 2026

Copy link
Copy Markdown
Contributor

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

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.

@spichen
spichen requested a review from a team July 25, 2026 20:26
@oracle-contributor-agreement oracle-contributor-agreement Bot added the OCA Verified All contributors have signed the Oracle Contributor Agreement. label Jul 25, 2026
…nagerWorkers

Quality pass over the ManagerWorkers adapter. No behaviour change intended.

Wrapping stream/astream in an execution span was already duplicated between the
Agent and Flow paths, and ManagerWorkers added a third near-verbatim copy. Extract
one `patch_with_execution_span` into `_execution_span.py`, parameterized by span and
event factories, and route all three through it. The `except NotImplementedError`
fallback ladder for the async span protocol was written 12 times; it is now one
helper.

Move the flow-step compile onto `AgentNodeExecutor` as
`_create_manager_workers_with_given_input_values`, next to its react-agent twin.
It was living in `_managerworkers.py` while importing the converter and taking the
executor's private cache as a parameter.

Replace the six per-worker closures in `_wrap_worker_for_subgraph` with module-level
helpers and a `_WorkerSubgraphNode` holding only the graph, so a long-lived node no
longer pins the whole factory frame. Memoize `_make_worker_delegation_tool`, which
depends only on the node name yet re-ran the `@tool` decorator on every compile.

In the converter, collapse the parallel worker list and dict into one list of pairs,
hoist the repeated conversion kwargs, and use the module's existing lazy
`langgraph_graph` instead of a local `MessagesState` import.

Drop `is_delegation_event`: no callers, not exported, unreachable through any
supported import path. `is_delegation_tool_name` stays.

Tests: collapse six copies of the loader and double-patch stack into one
`_load_with_fake_llms` helper, and drop assertions in the roster test that compared
a locally computed string against itself.

Add an `allow_llm_config_construction` fixture so tests that only build an LLM
config and stub the conversion are not skipped by the blanket SKIP_LLM_TESTS guard.
This un-skips the three flow-step tests that the guard was hiding.
…h codebase style

Trim reviewer-directed comments to codebase density; drop the lru_cache on the
delegation-tool factory, the _WorkerSubgraphNode class (now closures) and the
dict-or-object tool-call shim. Rewrite the tests to repo conventions: module-level
pyagentspec imports, a shared _agent() helper, pytestmark instead of an empty
autouse fixture, no section dividers, and behavior-level coverage instead of
micro-tests of private helpers.

Also fix a real bug the flow-step test exposed: the ManagerWorkers parent graph
runs over MessagesState, so a structured_response can never reach the node
executor and any declared output raised ValueError. A ManagerWorkers flow step
now answers its single string output with the manager's final message, and
rejects other output shapes with NotImplementedError.
@cesarebernardis
cesarebernardis self-requested a review August 10, 2026 08:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

OCA Verified All contributors have signed the Oracle Contributor Agreement.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant