Spec Reference

The Agentic YAML spec v0.1 defines a format for describing agentic system diagrams as human-readable text.

Diagram metadata

agentic: "0.1"
diagram:
  name: My Diagram
  description: Optional description
  type: system            # system | component
  active_scenario: flow-1
  parent_diagram: parent-id
  created: "2026-03-10T21:24:34.728Z"
  updated: "2026-04-10T12:00:00.000Z"

All fields are optional. name defaults to "Untitled".

parent_diagram identifies the parent diagram when this file represents a drilled-down sub-system.

Nodes

Nodes are a map of id → definition. The id is a stable, human-readable identifier. When label is omitted, the id is used as the display name.

nodes:
  orchestrator:
    type: agent
    is_looping: true

  pantry-server:
    type: tool
    sub_type: mcp

Common properties

Property	Type	Required	Description
`type`	string	yes	Node type (see Node Types)
`label`	string	no	Display name (defaults to node id)
`sub_title`	string	no	Secondary text below label
`description`	string	no	Longer description
`sub_type`	string	no	Type-specific variant
`url`	string	no	External link
`group`	string	no	Parent group node id
`linked_diagram`	string	no	Drill-down target diagram id or path
`edges`	array	no	Inline edge definitions

Type-specific properties

Property	Type	Relevant types	Description
`is_looping`	boolean	agent	Runs in a loop
`auth`	string	agent, backend	Auth mechanism
`auth_detail`	string	agent, backend	Auth subtitle/detail
`provider`	string	model	Model provider
`content`	string	prompt, note, text_label	Text content
`example_response`	string	agent	Example agent response

Design decisions

Smart defaults — Edge type defaults to request, step type to call, label to the node id, direction to TB. A file with just agentic: "0.1" is valid.

Node IDs as map keys — Avoids repeating id: on every node. IDs must be unique, URL-safe strings.

sub_type not tool_type/memory_type/etc. — One universal field instead of type-specific fields. The node’s type already provides context.

from/to not source/target — Consistent between edges and scenario steps. More readable.

Edges as array, not map — Edge IDs aren’t meaningful to humans. Auto-generated on import.

Inline or top-level edges — Both forms produce identical results and can be mixed freely.

Layout is optional — The core spec fully describes the diagram’s meaning. Layout can be omitted and the editor will auto-arrange.