[feat][GraphWorkflow] Add workflow serialization via to_spec() / from_spec() for JSON persistence

[kyegomez]

Summary

GraphWorkflow has no serialization or deserialization support. Users cannot save a workflow definition, version it in git, share it, or reconstruct it from config — they must always build it programmatically.

Proposed Enhancement

Add a to_spec() method that serializes the graph structure (without requiring Agent objects to be serializable):

def to_spec(self) -> Dict[str, Any]:
    return {
        "name": self.name,
        "description": self.description,
        "max_loops": self.max_loops,
        "nodes": [
            {"id": node_id, "agent_name": node.agent.agent_name}
            for node_id, node in self.nodes.items()
        ],
        "edges": [
            {"source": e.source, "target": e.target, "metadata": e.metadata}
            for e in self.edges
        ],
        "entry_points": self.entry_points,
        "end_points": self.end_points,
    }

def to_json(self, path: str) -> None:
    with open(path, "w") as f:
        json.dump(self.to_spec(), f, indent=2)

And a from_spec() classmethod that reconstructs the graph topology given a pre-built agent registry:

@classmethod
def from_spec(cls, spec: Dict[str, Any], agent_registry: Dict[str, Agent]) -> "GraphWorkflow":
    ...

Use Cases

• Version-control workflow definitions alongside code.
• Share workflow configs between teams without sharing agent implementation details.
• Reconstruct a workflow from a database or config file at runtime.
• Diff workflow changes in PRs.

File

swarms/structs/graph_workflow.py