@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