One graph, not two products
The canvas, the workflow JSON, and the node registry describe one thing. A second editor should never mean a second product.
- SDK
- Builder
Status: today you author workflows in the visual builder. The TypeScript SDK starts runs and reads their results; it does not write graphs. The rule below, one definition and never two, is the one any second editor will have to follow.
Teams split here for no good reason. One group wants a canvas. The other wants a file in git. Those are two editors. They are not two products.
We keep one graph: the same nodes, the same registry, the same run. That graph is the workflow — the versioned executable behind the agent you ship. The builder draws it. The host executes that JSON. If two editors ever produced different graphs, you would operate two products. We will not ship that.
One document
This is the thing the builder saves and the host runs. The canvas is a view of it. The run does not care how you drew it.
JSON
{
"version": 1,
"trigger": { "type": "webhook" },
"entryNodeId": "fetch",
"nodes": [
{
"id": "fetch",
"type": "http",
"config": { "method": "GET", "url": "https://billing.internal/invoices" }
},
{
"id": "reason",
"type": "ai",
"config": { "prompt": "Explain the failed invoice in one paragraph." }
}
],
"edges": [{ "from": "fetch", "to": "reason" }]
}The useful test is boring. Can you open a run and see the same nodes you drew, the same checkpoints, the same replay target? If not, the product has split, even if the marketing has not.
Who authors what
| Surface | You use it when | It writes |
|---|---|---|
| Builder | You want to see the path | The same workflow JSON |
| SDK | Your app starts a run | No graph; it calls the host |
| Host | A trigger fires | A run against that JSON |
Whatever draws the graph, the checkpoint and the replay loop stay the same.
More on that in Why replay needs the checkpoint.
