There’s no standard way to describe an agentic system with a flow.
Ask ten teams how they document their agent architecture and you’ll get ten screenshots of different styles. Which is fine - but those files don’t live in your repo, they don’t version well, and they mean nothing to a tool.
I wanted something better for Agentic Diagrams, so I built one. And now it’s yours: @agenticdiagrams/schema on npm, MIT licensed.
The format is .agentic.yaml. YAML-first, lives next to your code, commits to version control like anything else. The package ships TypeScript types, a JSON Schema at https://agenticdiagrams.com/schemas/agentic/0.1.json, and a validate() function you can drop into CI if you want.
It covers 29 node types (agent, tool, memory, router, guardrail, environment, model, knowledge_base, and more), 7 edge types (request, response, async, streaming, event, error, default), scenarios for animated flow sequences, layouts, and linked drill-down diagrams.
Here’s a real example completely generated by AI btw, no edits, working ond the default positioning!! This was a session external to the system itself, all I did was give it the schema.
A Customer Support Multi-Agent System. User comes in, a router classifies intent, routes to a specialist agent (Billing, Technical, or General). Each agent has its own model, hits a legacy database via an MCP tool, queries product docs from a knowledge base, and reads conversation history from a vector store. The Technical agent gets a sandbox environment for running diagnostics. An output guardrail filters everything before it goes back to the user.
That whole architecture, in one .agentic.yaml:
agentic: '0.1'
diagram:
name: Customer Support Multi-Agent System
description: Intent-routing support system with specialist agents, guardrails, and conversation memory
active_scenario: billing-query
nodes:
customer:
type: user
label: Customer
edges:
- to: router
type: request
label: Support request
router:
type: router
sub_type: llm_router
label: Intent Router
sub_title: Intent classification
edges:
- to: billing-agent
type: request
label: Billing query
- to: technical-agent
type: request
label: Technical issue
- to: general-agent
type: request
label: General enquiry
billing-agent:
type: agent
label: Billing Agent
edges:
- to: billing-model
type: request
animated: true
- to: legacy-db
type: request
label: Query records
- to: product-docs
type: request
label: Lookup docs
- to: conv-memory
type: async
label: Fetch history
- to: output-guard
type: request
technical-agent:
type: agent
label: Technical Agent
edges:
- to: technical-model
type: request
animated: true
- to: legacy-db
type: request
label: Query records
- to: product-docs
type: request
label: Lookup docs
- to: conv-memory
type: async
label: Fetch history
- to: sandbox
type: request
label: Run diagnostics
- to: output-guard
type: request
general-agent:
type: agent
label: General Agent
edges:
- to: general-model
type: request
animated: true
- to: product-docs
type: request
label: Lookup docs
- to: conv-memory
type: async
label: Fetch history
- to: output-guard
type: request
billing-model:
type: model
sub_type: llm
label: claude-sonnet-4-6
provider: Anthropic
technical-model:
type: model
sub_type: llm
label: claude-sonnet-4-6
provider: Anthropic
general-model:
type: model
sub_type: llm
label: claude-sonnet-4-6
provider: Anthropic
legacy-db:
type: tool
sub_type: mcp
label: Legacy Database
sub_title: MCP Server
product-docs:
type: knowledge_base
sub_type: documents
label: Product Docs
conv-memory:
type: memory
sub_type: vector
label: Conversation Memory
sandbox:
type: environment
sub_type: sandbox
label: Diagnostic Sandbox
output-guard:
type: guardrail
sub_type: output_filter
label: Output Guardrail
edges:
- to: customer
type: response
label: Verified response
scenarios:
billing-query:
name: Billing Query
description: Customer asks about a double charge
steps:
- from: customer
to: router
label: 'Why was I charged twice this month?'
- from: router
to: billing-agent
label: Billing intent detected
- from: billing-agent
to: conv-memory
type: async
label: Load conversation history
- from: billing-agent
to: legacy-db
label: Query billing records
payload: '{"customer_id": "cust_123", "period": "2026-03"}'
- from: legacy-db
to: billing-agent
type: return
label: Invoice records
- from: billing-agent
to: billing-model
label: Generate explanation
- from: billing-model
to: billing-agent
type: return
label: Draft response
- from: billing-agent
to: output-guard
label: Submit for review
- from: output-guard
to: customer
type: return
label: "Here's why you were charged..."That file is the source of truth. Commit it. Review it in PRs.
Import it into the app and you get a visual diagram you can share, present as slides, and step through the flow.
Hit Remix to fork it and build on top.
The schema being open source means you’re not locked to the app. Validate in CI with validate(), generate diagrams programmatically, build tooling that actually understands your system topology. The app renders it nicely - but the file is yours.
Try it:
- Install:
npm install @agenticdiagrams/schema - Repo + issues: github.com/agenticdiagrams/schema
- Remix the example: https://app.agenticdiagrams.com/view/Kfq7LGRUogd6
- The app: https://app.agenticdiagrams.com
If the spec’s missing something, file an issue. It’s 0.1 for a reason ;-)