@agenticdiagrams/schema

TypeScript types, JSON Schema, and validation for .agentic.yaml diagram files.

Install

npm install @agenticdiagrams/schema

Usage

Types

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

Validation

Validate a parsed YAML object against the 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

Use the JSON Schema directly for editor support or other tools:

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

Or reference it by URL: https://agenticdiagrams.com/schemas/agentic/0.1.json

What's in the box

Export	Description
AgenticYaml	Root document type
AgenticNode	Node definition
AgenticEdge	Edge (connection) definition
AgenticScenario	Flow scenario with steps
AgenticLayout	Layout hints (positions, sizes, styles)
validate()	Structural validation against JSON Schema

Spec

See the full Agentic YAML Specification v0.1.

Examples

The examples/ directory contains complete .agentic.yaml files:

• simple-agent — Support bot with knowledge base search
• multi-agent-with-guardrails — Pipeline with input/output guardrails and human approval
• kitchen-manager — Multi-agent system with MCP tools and parallel scenarios

Minimum valid document

agentic: '0.1'

A practical minimum:

agentic: '0.1'
nodes:
  my-agent:
    type: agent
    edges:
      - to: my-tool
  my-tool:
    type: tool
    sub_type: mcp

License

MIT