Aisop – Define AI agent workflows as Mermaid or JSON flow graphs

AISOP launched an open protocol that defines AI agent workflows using Mermaid or JSON flow graphs, enabling multi-step programs with branching, parallel execution, and error handling in a single portable JSON format. The protocol supports 14 control flow patterns and three-layer separation of metadata, flow graph, and function definitions, making AI programs token-efficient and readable by any language. This standard aims to replace proprietary visual builders and non-portable code-based workflows with a machine-readable, version-controllable format optimized for LLM comprehension.

An open protocol for defining structured AI programs using Mermaid or JSON flow graphs. AISOP enables defining multi-step AI programs with visual Mermaid or structural JSON control flow — branching, parallel execution, sub-tasks, and error handling — all in a single portable JSON format. | Approach | Definition | Portable | Machine-readable | Token-efficient | |---|---|---|---|---| | Natural language prompts | Free text | Yes | No | No | | Python / YAML workflows | Code / config | No | Partially | No | | Visual builders Dify, etc. | Proprietary | No | No | No | AISOP | Mermaid + JSON | Yes | Yes | Yes | AISOP files are plain JSON with flow graphs Mermaid or JSON — readable by any language, editable in any editor, versionable in git, and optimized for LLM comprehension. { "role": "system", "content": { "protocol": "AISOP V1.0.0", ... } }, { "role": "user", "content": { "instruction": "...", "aisop": { ... }, "functions": { ... } } } | Element | Purpose | |---|---| system | Program metadata identity, version, description | user | Instruction, flow graph, and function definitions | { "role": "system", "content": { "protocol": "AISOP V1.0.0", "axiom 0": "Human Sovereignty and Wellbeing", "id": "greeting assistant", "name": "Greeting Assistant", "version": "1.0.0", "summary": "Classify user intent and respond", "flow format": "mermaid" } }, { "role": "user", "content": { "instruction": "RUN aisop.main", "user input": "{user input}", "aisop": { "main": "graph TD\n greet Greet -- classify{Classify}\n classify -- |question| search Search \n classify -- |chat| reply Reply \n search -- end node End \n reply -- end node" }, "functions": { "greet": { "step1": "Say hello to the user" }, "classify": { "step1": "Classify user intent as 'question' or 'chat'" }, "search": { "step1": "Search for relevant info" }, "reply": { "step1": "Generate a friendly reply" }, "end node": { "step1": "Output final response" } } } } The flow graph Mermaid format : php graph TD greet Greet -- classify{Classify} classify -- |question| search Search classify -- |chat| reply Reply search -- end node End reply -- end node Dual Flow Format — Mermaid string AI-native or JSON flow object code-native , mixable in the same program 14+ Control Flow Patterns — sequential, decision, parallel fork/join, delegate, loop, convergence, error routing, batch iterate, retry, data isolation, step-level sub-task, agent dispatch, HITL confirmation, runtime assertion Three-Layer Separation — metadata, flow graph, function definitions Topology / Behavior Split — flow graph defines connections, functions define runtime behavior Sub-task Support — main + named sub-tasks via delegate nodes or step-level RUN aisop.<sub Reserved Keys — 8 runtime behavior keys in functions join, map, on error, retry policy, context filter, output mapping, constraints, execute mode — 24 protocol-reserved system calls for human confirmation 🔒 inviolable sys. System Calls sys.io.confirm , I/O, assertions, model invocation, code execution, and state management see §6 Error Handling — Mermaid -.- error edge + function-level on error type routing + 6 sys. error types Variable Substitution — {system prompt} , {user input} replaced at runtime Token Efficient — Mermaid uses ~50% fewer tokens than JSON flow format Zero Dependencies — Reference implementations in Python and JavaScript, stdlib only AI-Agnostic — Works with any AI runtime AISOP supports two flow graph formats. Both can coexist in the same program. | Shape | Syntax | Meaning | |---|---|---| | Rectangle | name text | Process — execute and proceed | | Diamond | name{text} | Decision — conditional branching | | Circle | name text | End — terminate task | | Rectangle | name aisop.sub | Delegate — call sub-task | | Edge | Syntax | Meaning | |---|---|---| | Solid arrow | -- | Normal flow next | | Labeled arrow | -- |label| | Branch conditional | | Dashed arrow | -.- | Error routing | | Field | Type | Meaning | |---|---|---| next | string | Next node s . 1 = sequential, 2+ = parallel fork | branches | object | Conditional branching: {label: target} | error | string | Error handler node | delegate to | string | Call a sub-task by name | wait for | string | Wait for nodes before proceeding join | {} | — | End — terminate task | | Pattern | Mermaid §4.2 | JSON Flow §4.3 | Functions §5 / sys §6 | |---|---|---|---| | Sequential | A -- B | "next": "B" | — | | If/else | A -- |yes| B , A -- |no| C | "branches": {"yes": "B", "no": "C"} | — | | Switch N-way | A -- |label| B , ... | "branches": {"label": "B", ...} | — | | Parallel fork | A -- B , A -- C | "next": "B", "C" | — | | Parallel join | B -- D , C -- D | "wait for": "B", "C" | "join": {"merge strategy": "array"} | | Loop | Branch target → earlier node | Branch target → earlier node | — | | Sub-task | A aisop.sub | "delegate to": "sub" | — | | Convergence | Multiple → same target | Multiple → same target | — | | Error routing | A -.- E | "error": "E" | "on error": {"timeout": "t"} | | Batch iterate | — | — | "map": {"items path": "..."} | | Retry | — | — | "retry policy": {"max attempts": 3} | | Data isolation | — | — | "context filter": {"include": ... } | | Step-level sub | — | — | step text: RUN aisop.sub | | Agent dispatch | — | — | "execute mode": "agent" | | HITL confirmation | — | — | sys.io.confirm '...' §6.2 | | Runtime assertion | — | — | sys.assert '...', '...' §6.5 | | Background job | — | — | sys.run.bg '...' §6.4 | Python: cd reference/python python run.py example.aisop.json python test all.py JavaScript: cd reference/javascript node run.js example.aisop.json node test all.js AISOP-Protocol/ specification/ aisop-spec.md Protocol specification V1.0.0 aisop-spec CN.md Protocol specification — Chinese reference/ python/ flow runtime.py Python reference implementation example.aisop.json Example flow definition example syscalls.aisop.json Advanced example with sys. calls test all.py Test suite 44 tests run.py CLI tool pyproject.toml Python package metadata LICENSE Apache 2.0 license per-package NOTICE Apache 2.0 attribution notice per-package README.md Implementation guide javascript/ flow runtime.js JavaScript reference implementation example.aisop.json Example flow definition example syscalls.aisop.json Advanced example with sys. calls test all.js Test suite 44 tests run.js CLI tool package.json npm package metadata LICENSE Apache 2.0 license per-package NOTICE Apache 2.0 attribution notice per-package README.md Implementation guide docs/ index.md Documentation site home topics/ what-is-aisop.md Introduction and rationale comparison-mermaid-vs-jsonflow.md Mermaid vs JSON Flow comparison comparison-mermaid-vs-jsonflow CN.md Comparison — Chinese performance-mermaid-vs-jsonflow.md Performance analysis performance-mermaid-vs-jsonflow CN.md Performance analysis — Chinese adrs/ adr-001-mermaid-as-primary-format.md ADR mirror mkdocs site adr-002-sys-io-confirm-immutability.md ADR mirror mkdocs site adrs/ adr-template.md ADR template adr-001-mermaid-as-primary-format.md Format choice rationale adr-002-sys-io-confirm-immutability.md Axiom 0 enforcement decision README.md README CN.md CONTRIBUTING.md Contribution guidelines CONTRIBUTING CN.md 贡献指南 CODE OF CONDUCT.md Community standards Axiom 0 pledge GOVERNANCE.md Tripartite Chain governance model SECURITY.md Vulnerability reporting policy LICENSE Apache 2.0 license NOTICE Apache 2.0 attribution notice CHANGELOG.md Release notes mkdocs.yml MkDocs documentation site config AIXP Labs aixp.dev https://aixp.dev AIXP Labs develops and maintains the following core projects: | Project | Description | Website | |---|---|---| | AILP https://ailp.dev AIVP https://aivp.dev AIRP https://airp.dev AIBP https://aibp.dev AIAP https://aiap.dev AISOP https://aisop.dev SoulBot https://soulbot.dev SoulACP https://soulacp.dev AISOP is grounded in Axiom 0: Human Sovereignty and Wellbeing — AI systems exist to serve humanity, not replace or dominate it. All implementations must enforce this axiom at the highest execution priority. See §0 of the specification /AIXP-Labs/AISOP/blob/main/specification/aisop-spec.md for the full text. See CONTRIBUTING.md /AIXP-Labs/AISOP/blob/main/CONTRIBUTING.md for guidelines / 见 CONTRIBUTING CN.md /AIXP-Labs/AISOP/blob/main/CONTRIBUTING CN.md 了解贡献指南。 Code of Conduct /AIXP-Labs/AISOP/blob/main/CODE OF CONDUCT.md — Community standards aligned with Axiom 0 Governance /AIXP-Labs/AISOP/blob/main/GOVERNANCE.md — Tripartite Chain model Seed / Authority / Executor Security Policy /AIXP-Labs/AISOP/blob/main/SECURITY.md — Vulnerability reporting and sys.io.confirm immutability Architecture Decision Records /AIXP-Labs/AISOP/blob/main/adrs — Design rationale for major decisions This protocol specification and the reference implementations are provided for research and educational purposes only . They are experimental and not intended for production use. Use at your own risk. The authors assume no liability for any damages arising from use of this software. See LICENSE /AIXP-Labs/AISOP/blob/main/LICENSE for full terms Apache 2.0 . Apache License 2.0 /AIXP-Labs/AISOP/blob/main/LICENSE - Copyright 2026 AIXP Labs AIXP.dev | AISOP.dev Align Axiom 0: Human Sovereignty and Wellbeing. Version: AISOP V1.0.0. www.aisop.dev http://www.aisop.dev