Agent Import and DSL Compatibility#

Overview#

The agent canvas uses a single canonical DSL wire format for all operations (create, save, export, import). All DSL transformation logic lives in dsl-bridge.ts, which exposes four public functions: initialEmptyDsl, importDsl, dslToGraph, and graphToDsl. The frontend rebuilds components from graph on every save; the backend reads components only and ignores graph 1.

DSL Wire Shape#

The canonical DSL shape 2:

{
  "globals": {...},
  "graph": { "nodes": [...], "edges": [...] },
  "variables": {...},
  "components": { "<Name>:<UUID>": { "downstream": [...], "upstream": [...], "obj": {...} } },
  "path": [...], "retrieval": {...}, "history": [...]
}

• graph is the React-Flow layout surface (positions, handles) — the single source of truth for import/export.
• components is the execution topology consumed by the backend engine.

importDsl — Strict-Graph Contract#

importDsl(rawParsed, isAgent) 3 accepts a parsed JSON object and returns a renderable DSL. Only payloads with raw.graph.nodes (non-empty array) are rendered as-is. All other inputs fall through to the empty seed:

Tests for all four cases are in 4.

When graph.nodes is present but components is absent, importDsl reconstructs topology via buildDslComponentsByGraph 5. This was the bug fixed in PR #13992: imported DSLs were not correctly rebuilding their components from the graph structure.

Backward Compatibility#

_layout field (legacy v1 exports)#

Earlier v1 export files carried canvas positions in a _layout field. The _layout field is intentionally not consumed — it was a one-shot import-time hint and is no longer part of the wire contract since the v1/v2 split was removed 6. A payload with only _layout renders as an empty canvas 7.

Iteration node type migration ('group' → 'iterationNode')#

Old agent exports used type: 'group' for Iteration nodes. normalizeGraphNodes automatically rewrites these to type: 'iterationNode' during both importDsl and dslToGraph, so legacy canvases render correctly without manual migration. Test coverage is at 8.

Canvas type detection#

inferIsAgentFromImport detects whether an imported JSON is a dataflow or agent canvas by checking whether graph.nodes includes both File and Parser operators. It defaults to agent when ambiguous or when no graph block is present.

Placeholder Node Edge Rendering (PR #10485)#

Connection lines to placeholder nodes were not displaying correctly because rendering depended on a global highlightedPlaceholderEdgeId store state that wasn't properly managed. PR #10485 replaced the global state with an on-the-fly computation (isTargetPlaceholder = getOperatorTypeFromId(target) === Operator.Placeholder), removing the highlightedPlaceholderEdgeId state and its setters entirely. graphToDsl also filters out placeholder nodes and their edges before serializing 9.

Go/Python Runtime Parity (PR #16225)#

PR #16225 aligned the Go agent runtime with Python behavior across components, tools, and the canvas engine. Key DSL-related changes:

• DSL normalization (internal/agent/dsl/normalize.go): v1↔v2 collapsed into a single wire format so both runtimes consume the same stored JSON 10.
• Switch component: Added multi-target routing, legacy clauses→items parameter normalization, and default fallback logic 10.
• Canvas state reset (internal/agent/dsl/reset.go): Per-run state reset matches Python's Canvas.reset() semantics 10.

The retrieval component alignment was intentionally deferred to a follow-up PR 10.

Key Source Files#