{"slug": "aisop-define-ai-agent-workflows-as-mermaid-or-json-flow-graphs", "title": "Aisop – Define AI agent workflows as Mermaid or JSON flow graphs", "summary": "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.", "body_md": "**An open protocol for defining structured AI programs using Mermaid or JSON flow graphs.**\n\nAISOP 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.\n\n| Approach | Definition | Portable | Machine-readable | Token-efficient |\n|---|---|---|---|---|\n| Natural language prompts | Free text | Yes | No | No |\n| Python / YAML workflows | Code / config | No | Partially | No |\n| Visual builders (Dify, etc.) | Proprietary | No | No | No |\nAISOP |\nMermaid + JSON |\nYes |\nYes |\nYes |\n\nAISOP 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.\n\n```\n[\n  { \"role\": \"system\", \"content\": { \"protocol\": \"AISOP V1.0.0\", ... } },\n  { \"role\": \"user\",   \"content\": { \"instruction\": \"...\", \"aisop\": { ... }, \"functions\": { ... } } }\n]\n```\n\n| Element | Purpose |\n|---|---|\n`system` |\nProgram metadata (identity, version, description) |\n`user` |\nInstruction, flow graph, and function definitions |\n\n```\n[\n  {\n    \"role\": \"system\",\n    \"content\": {\n      \"protocol\": \"AISOP V1.0.0\",\n      \"axiom_0\": \"Human_Sovereignty_and_Wellbeing\",\n      \"id\": \"greeting_assistant\",\n      \"name\": \"Greeting Assistant\",\n      \"version\": \"1.0.0\",\n      \"summary\": \"Classify user intent and respond\",\n      \"flow_format\": \"mermaid\"\n    }\n  },\n  {\n    \"role\": \"user\",\n    \"content\": {\n      \"instruction\": \"RUN aisop.main\",\n      \"user_input\": \"{user_input}\",\n      \"aisop\": {\n        \"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\"\n      },\n      \"functions\": {\n        \"greet\":    { \"step1\": \"Say hello to the user\" },\n        \"classify\": { \"step1\": \"Classify user intent as 'question' or 'chat'\" },\n        \"search\":   { \"step1\": \"Search for relevant info\" },\n        \"reply\":    { \"step1\": \"Generate a friendly reply\" },\n        \"end_node\": { \"step1\": \"Output final response\" }\n      }\n    }\n  }\n]\n```\n\nThe flow graph (Mermaid format):\n\n``` php\ngraph 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\n```\n\n**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`\n\n+ named sub-tasks via delegate nodes or step-level`RUN aisop.<sub>`\n\n**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.*`\n\nSystem Calls`sys.io.confirm`\n\n), I/O, assertions, model invocation, code execution, and state management (see §6)**Error Handling**— Mermaid`-.->`\n\nerror edge + function-level`on_error`\n\ntype routing + 6 sys.* error types**Variable Substitution**—`{system_prompt}`\n\n,`{user_input}`\n\nreplaced 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\n\nAISOP supports two flow graph formats. Both can coexist in the same program.\n\n| Shape | Syntax | Meaning |\n|---|---|---|\n| Rectangle | `name[text]` |\nProcess — execute and proceed |\n| Diamond | `name{text}` |\nDecision — conditional branching |\n| Circle | `name((text))` |\nEnd — terminate task |\n| Rectangle | `name[aisop.sub]` |\nDelegate — call sub-task |\n\n| Edge | Syntax | Meaning |\n|---|---|---|\n| Solid arrow | `-->` |\nNormal flow (next) |\n| Labeled arrow | `-->|label|` |\nBranch (conditional) |\n| Dashed arrow | `-.->` |\nError routing |\n\n| Field | Type | Meaning |\n|---|---|---|\n`next` |\nstring[] | Next node(s). 1 = sequential, 2+ = parallel fork |\n`branches` |\nobject | Conditional branching: `{label: target}` |\n`error` |\nstring | Error handler node |\n`delegate_to` |\nstring | Call a sub-task by name |\n`wait_for` |\nstring[] | Wait for nodes before proceeding (join) |\n`{}` |\n— | End — terminate task |\n\n| Pattern | Mermaid (§4.2) | JSON Flow (§4.3) | Functions (§5) / sys (§6) |\n|---|---|---|---|\n| Sequential | `A --> B` |\n`\"next\": [\"B\"]` |\n— |\n| If/else | `A -->|yes| B` , `A -->|no| C` |\n`\"branches\": {\"yes\": \"B\", \"no\": \"C\"}` |\n— |\n| Switch (N-way) | `A -->|label| B` , ... |\n`\"branches\": {\"label\": \"B\", ...}` |\n— |\n| Parallel fork | `A --> B` , `A --> C` |\n`\"next\": [\"B\", \"C\"]` |\n— |\n| Parallel join | `B --> D` , `C --> D` |\n`\"wait_for\": [\"B\", \"C\"]` |\n`\"join\": {\"merge_strategy\": \"array\"}` |\n| Loop | Branch target → earlier node | Branch target → earlier node | — |\n| Sub-task | `A[aisop.sub]` |\n`\"delegate_to\": \"sub\"` |\n— |\n| Convergence | Multiple → same target | Multiple → same target | — |\n| Error routing | `A -.-> E` |\n`\"error\": \"E\"` |\n`\"on_error\": {\"timeout\": \"t\"}` |\n| Batch iterate | — | — | `\"map\": {\"items_path\": \"...\"}` |\n| Retry | — | — | `\"retry_policy\": {\"max_attempts\": 3}` |\n| Data isolation | — | — | `\"context_filter\": {\"include\": [...]}` |\n| Step-level sub | — | — | step text: `RUN aisop.sub` |\n| Agent dispatch | — | — | `\"execute_mode\": \"agent\"` |\n| HITL confirmation | — | — | `sys.io.confirm('...')` (§6.2) |\n| Runtime assertion | — | — | `sys.assert('...', '...')` (§6.5) |\n| Background job | — | — | `sys.run.bg('...')` (§6.4) |\n\n**Python:**\n\n```\ncd reference/python\npython run.py example.aisop.json\npython test_all.py\n```\n\n**JavaScript:**\n\n```\ncd reference/javascript\nnode run.js example.aisop.json\nnode test_all.js\nAISOP-Protocol/\n  specification/\n    aisop-spec.md              # Protocol specification (V1.0.0)\n    aisop-spec_CN.md           # Protocol specification — Chinese\n  reference/\n    python/\n      flow_runtime.py                # Python reference implementation\n      example.aisop.json             # Example flow definition\n      example_syscalls.aisop.json    # Advanced example with sys.* calls\n      test_all.py                    # Test suite (44 tests)\n      run.py                         # CLI tool\n      pyproject.toml                 # Python package metadata\n      LICENSE                        # Apache 2.0 license (per-package)\n      NOTICE                         # Apache 2.0 attribution notice (per-package)\n      README.md                      # Implementation guide\n    javascript/\n      flow_runtime.js                # JavaScript reference implementation\n      example.aisop.json             # Example flow definition\n      example_syscalls.aisop.json    # Advanced example with sys.* calls\n      test_all.js                    # Test suite (44 tests)\n      run.js                         # CLI tool\n      package.json                   # npm package metadata\n      LICENSE                        # Apache 2.0 license (per-package)\n      NOTICE                         # Apache 2.0 attribution notice (per-package)\n      README.md                      # Implementation guide\n  docs/\n    index.md                                  # Documentation site home\n    topics/\n      what-is-aisop.md                        # Introduction and rationale\n      comparison-mermaid-vs-jsonflow.md       # Mermaid vs JSON Flow comparison\n      comparison-mermaid-vs-jsonflow_CN.md    # Comparison — Chinese\n      performance-mermaid-vs-jsonflow.md      # Performance analysis\n      performance-mermaid-vs-jsonflow_CN.md   # Performance analysis — Chinese\n    adrs/\n      adr-001-mermaid-as-primary-format.md    # ADR mirror (mkdocs site)\n      adr-002-sys-io-confirm-immutability.md  # ADR mirror (mkdocs site)\n  adrs/\n    adr-template.md                # ADR template\n    adr-001-mermaid-as-primary-format.md       # Format choice rationale\n    adr-002-sys-io-confirm-immutability.md     # Axiom 0 enforcement decision\n  README.md\n  README_CN.md\n  CONTRIBUTING.md                # Contribution guidelines\n  CONTRIBUTING_CN.md             # 贡献指南\n  CODE_OF_CONDUCT.md             # Community standards (Axiom 0 pledge)\n  GOVERNANCE.md                  # Tripartite Chain governance model\n  SECURITY.md                    # Vulnerability reporting policy\n  LICENSE                        # Apache 2.0 license\n  NOTICE                         # Apache 2.0 attribution notice\n  CHANGELOG.md                   # Release notes\n  mkdocs.yml                     # MkDocs documentation site config\n```\n\n## AIXP Labs [aixp.dev](https://aixp.dev)\n\nAIXP Labs develops and maintains the following core projects:\n\n| Project | Description | Website |\n|---|---|---|\n|\n\n[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.\n\nSee [CONTRIBUTING.md](/AIXP-Labs/AISOP/blob/main/CONTRIBUTING.md) for guidelines / 见 [CONTRIBUTING_CN.md](/AIXP-Labs/AISOP/blob/main/CONTRIBUTING_CN.md) 了解贡献指南。\n\n[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`\n\nimmutability[Architecture Decision Records](/AIXP-Labs/AISOP/blob/main/adrs)— Design rationale for major decisions\n\nThis 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).\n\n[Apache License 2.0](/AIXP-Labs/AISOP/blob/main/LICENSE) - Copyright 2026 AIXP Labs AIXP.dev | AISOP.dev\n\nAlign Axiom 0: Human Sovereignty and Wellbeing. Version: AISOP V1.0.0. [www.aisop.dev](http://www.aisop.dev)", "url": "https://wpnews.pro/news/aisop-define-ai-agent-workflows-as-mermaid-or-json-flow-graphs", "canonical_source": "https://github.com/AIXP-Labs/AISOP", "published_at": "2026-06-05 02:28:02+00:00", "updated_at": "2026-06-05 02:46:30.141096+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "ai-infrastructure", "ai-products"], "entities": ["AISOP", "Dify", "Mermaid"], "alternates": {"html": "https://wpnews.pro/news/aisop-define-ai-agent-workflows-as-mermaid-or-json-flow-graphs", "markdown": "https://wpnews.pro/news/aisop-define-ai-agent-workflows-as-mermaid-or-json-flow-graphs.md", "text": "https://wpnews.pro/news/aisop-define-ai-agent-workflows-as-mermaid-or-json-flow-graphs.txt", "jsonld": "https://wpnews.pro/news/aisop-define-ai-agent-workflows-as-mermaid-or-json-flow-graphs.jsonld"}}