Agentic YAML Schema

An open specification for describing AI agent architectures as human-readable YAML.

File extension: .agentic.yaml or .agentic.yml

Install

npm install @agenticdiagrams/schema

Quick start

A minimal document:

agentic: "0.1"

A practical starting point:

agentic: "0.1"
diagram:
  name: My Agent System

nodes:
  support-bot:
    type: agent
    edges:
      - to: kb-search

  kb-search:
    type: tool
    sub_type: mcp

Usage

TypeScript types

import type { AgenticYaml, AgenticNode } from '@agenticdiagrams/schema';

Validation

Validate a parsed YAML object against the JSON Schema:

import * as yaml from 'js-yaml';
import { validate } from '@agenticdiagrams/schema';

const doc = yaml.load(yamlString);
const result = validate(doc);

if (!result.valid) {
  console.error(result.errors);
}

JSON Schema

Reference the schema directly for editor support:

https://agenticdiagrams.com/schemas/agentic/0.1.json

Or import it from the package:

import schema from '@agenticdiagrams/schema/schema.json';

Top-level structure

Key	Type	Required	Description
`agentic`	string	yes	Spec version (`"0.1"`)
`diagram`	object	no	Diagram metadata
`nodes`	map	no	Node definitions (id → node)
`edges`	array	no	Connections between nodes
`scenarios`	map	no	Flow definitions (id → scenario)
`layout`	object	no	Visual/rendering hints

Defaults

Property	Default	Notes
`diagram.name`	`"Untitled"`	Name of the diagram
Node `label`	node id	`my-agent` → displays as “my-agent”
Edge `type`	`request`	Most common in agent diagrams
Step `type`	`call`	Most common in flows
`layout.direction`	`TB`	Top to bottom

Resources

Spec Reference — Full specification details
Node Types — All 29 node types
Edges — Connection types and properties
Scenarios — Flow sequences with fragments and notes
Layout — Positions, sizes, and visual styles
JSON Schema — Machine-readable schema
npm Package — TypeScript types + validation
GitHub — Source, examples, and issues