[feat][graph_workflow][sub-workflow composition]

[kyegomez]

Problem

GraphWorkflow nodes are always individual agents. There is no way to use one GraphWorkflow as a node inside another, which rules out reusable graph modules and multi-level orchestration.

Proposed feature

A node can itself be a GraphWorkflow. The outer graph treats the inner graph as a single black-box node whose input is the node's upstream payload and whose output is the inner graph's final result.

Design sketch

• GraphWorkflow.add_node(x) accepts either an Agent or another GraphWorkflow.
• Inner graph's inputs are merged upstream outputs; inner graph's final layer output becomes the node's output.
• Topology serialization (save_spec() / from_topology_spec()) is extended to support nested specs — the inner graph's spec is embedded as {"type": "subgraph", "spec": {...}}.
• Checkpoint format stores inner-graph state under the parent node's ID for clean restart.

Tradeoff

Checkpoint format has to handle nesting. Nested topology serialization adds a small amount of parsing complexity at load time.

Files

• swarms/structs/graph_workflow.py

Why

Enables reusable graph modules — a "research pipeline" subgraph can be dropped into multiple outer workflows. Also pairs with topology serialization for shareable, composable graph libraries.

[Ddyln]

Hi, I will work on this 🙏

[kinthaiofficial]

Sub-workflow composition is the right next step. The ability to nest graphs enables building reusable agent modules.

From running 221 agents with hierarchical delegation:

What nested workflows need beyond the basic proposal:

1. Budget propagation: When the outer graph allocates a budget to the inner graph node, the inner graph must distribute that budget across its own nodes. We use pessimistic allocation: the inner graph deducts the estimated ceiling for each of its nodes from the allocated budget. If the allocated budget is insufficient for the inner graph's minimum execution, it should fail fast with a BudgetInsufficientError before starting.

2. Context scoping: The inner graph should receive only the relevant context from the outer graph, not the full outer context. This prevents context pollution and reduces token consumption. We pass a delegation_context field that includes only the task-relevant information.

3. Capability intersection: The inner graph's effective capabilities must be the intersection of the outer node's capabilities and the inner graph's own requirements. If the outer graph does not have network-access capability, the inner graph's nodes cannot make external API calls even if they individually support it.

4. Failure isolation: An inner graph failure should not crash the outer graph. The outer graph should receive a structured error with enough context to decide: retry the inner graph, route to a fallback, or fail gracefully.

5. Observability: The outer graph should be able to inspect inner graph progress (how many inner nodes completed, current status) without full visibility into inner graph internals. This respects encapsulation while enabling monitoring.

Multi-agent orchestration patterns: https://blog.kinthai.ai/221-agents-multi-agent-coordination-lessons

Multi-tenant isolation for nested workflows: https://blog.kinthai.ai/openclaw-multi-tenancy-why-vm-per-user-doesnt-scale

[adichaudhary]

Working on this