cd /news/ai-agents/aisop-define-ai-agent-workflows-as-m… · home › topics › ai-agents › article
[ARTICLE · art-22103] src=github.com pub= topic=ai-agents verified=true sentiment=↑ positive

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.

read7 min publishedJun 5, 2026

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):

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 assertionThree-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-levelRUN 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 (🔒 inviolablesys.*

System Callssys.io.confirm

), I/O, assertions, model invocation, code execution, and state management (see §6)Error Handling— Mermaid-.->

error edge + function-levelon_error

type routing + 6 sys.* error typesVariable Substitution—{system_prompt}

,{user_input}

replaced at runtimeToken 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 -->
"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 #

AIXP Labs develops and maintains the following core projects:

Project Description Website

AILPAIVPAIRPAIBPAIAPAISOPSoulBotSoulACPAISOP 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 for the full text.

See CONTRIBUTING.md for guidelines / 见 CONTRIBUTING_CN.md 了解贡献指南。

Code of Conduct— Community standards aligned with Axiom 0Governance— Tripartite Chain model (Seed / Authority / Executor)Security Policy— Vulnerability reporting andsys.io.confirm

immutabilityArchitecture Decision Records— 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 for full terms (Apache 2.0).

Apache License 2.0 - Copyright 2026 AIXP Labs AIXP.dev | AISOP.dev

Align Axiom 0: Human Sovereignty and Wellbeing. Version: AISOP V1.0.0. www.aisop.dev

source & further reading
github.com — original article
── more in #ai-agents 4 stories · sorted by recency
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/aisop-define-ai-agen…] indexed:0 read:7min 2026-06-05 · —