Edges

Edges define connections between nodes. They can be declared inline on a node or at the top level.

Inline edges

Edges defined directly on a node infer from as that node:

nodes:
  orchestrator:
    type: agent
    edges:
      - to: inventory-agent
        label: Check stock
      - to: recipe-agent
      - to: streaming-service
        type: streaming
        animated: true

Top-level edges

Edges in the top-level edges array specify both from and to explicitly:

edges:
  - from: inventory-agent
    to: orchestrator
    type: response

Both forms produce identical results and can be mixed freely.

Properties

Property	Type	Required	Default	Description
`from`	string	top-level only	—	Source node id (inferred when inline)
`to`	string	yes	—	Target node id
`type`	string	no	`request`	Edge type (see below)
`label`	string	no	—	Edge label
`animated`	boolean	no	`false`	Show animated flow on connection
`arrows`	string	no	`end`	Arrowheads: `none`, `start`, `end`, `both`
`path`	string	no	`bezier`	Path rendering style
`source_handle`	string	no	—	Connection point on source node (see below)
`target_handle`	string	no	—	Connection point on target node (see below)
`metadata`	object	no	—	Presentation hints for the edge (see below)

Arrows

arrows controls which ends of the edge show an arrowhead. It defaults to end (an arrow at the target), matching the most common request/response direction.

Value	Meaning
`none`	No arrowheads
`start`	Arrow at the source end
`end`	Arrow at the target end (default)
`both`	Arrows at both ends (bidirectional)

edges:
  - from: service-a
    to: service-b
    label: syncs with
    arrows: both

Edge metadata

metadata carries freeform presentation hints set by the editor. Known keys are typed; unknown keys are allowed so the editor can stash additional cosmetics without a schema change.

Key	Type	Description
`label_pos`	number	Label position along the edge as a fraction of its length (0 = source end, 1 = target end). Default 0.5.

edges:
  - from: gw
    to: plan
    type: data
    label: issue
    metadata:
      label_pos: 0.72 # slide the label 72 % along the edge

Edge types

Type	Meaning
`request`	Synchronous request (default)
`response`	Response to a request
`async`	Asynchronous message
`streaming`	Streaming data flow
`event`	Event-driven trigger
`error`	Error / exception path
`default`	Generic untyped connection

Path types

Value	Description
`bezier`	Curved line (default)
`straight`	Straight line
`step`	Right-angle steps
`smooth_step`	Smooth right-angle steps
`simple_bezier`	Simple bezier curve

Handle positions

source_handle and target_handle accept two forms:

Plain side name — connects at the centre of that side:

source_handle: bottom
target_handle: top

Slot form — places the anchor at a specific percentage along the side, in 10 % increments (10–90):

source_handle: bottom-20   # 20 % from the left edge of the bottom side
target_handle: top-80-t    # 80 % from the left edge of the top side

The -t suffix on target slot IDs distinguishes them from source slots when both are present on the same side. It is added automatically on export and must be preserved when hand-editing.

When handles are omitted the editor uses direction-aware defaults (bottom/top for TB, right/left for LR, etc.).