JSON Chain Definitions: Why Version-Controlled Workflows Matter

Most agent orchestration tools define workflows in code. Python classes, TypeScript functions, Go structs. The workflow is embedded in application logic, tangled with business rules and infrastructure concerns.

Mentiko defines workflows in JSON. This isn't a limitation -- it's a design choice with specific advantages.

Workflows are data, not logic

A chain definition answers simple questions: which agents, what order, what triggers. These are configuration, not computation.

{
  "name": "content-pipeline",
  "agents": [
    {"name": "researcher", "triggers": ["chain:start"], "emits": ["research:complete"]},
    {"name": "writer", "triggers": ["research:complete"], "emits": ["draft:complete"]},
    {"name": "editor", "triggers": ["draft:complete"], "emits": ["chain:complete"]}
  ]
}

This is readable by anyone on the team -- product managers, engineering leads, even non-technical stakeholders. Try that with a Python state machine.

Why version control matters

When your chain definitions are JSON files in a git repository:

You get history. git log content-pipeline.json shows every change ever made. Who changed the chain, when, and why (if they wrote a commit message).

You get diff. git diff shows exactly what changed. "The editor agent was removed" or "a new quality gate was added" is visible in the diff, not hidden in refactored Python code.

You get review. Chain changes go through pull requests. A teammate can review the new workflow structure before it runs in production.

You get rollback. A chain change broke production? git revert brings back the previous version. No code deployment needed.

You get branching. Test a new chain variant on a feature branch. Merge when it's proven. Multiple people can work on different chains simultaneously.

Code-based workflows lose these properties

When workflows are defined in Python:

Changes to the workflow are mixed with changes to business logic
Reviewing a workflow change requires reading code, not data
Rollback means reverting a code deployment, not a config change
Non-engineers can't read or understand the workflow
The workflow structure is spread across multiple files and functions

This isn't an argument against Python. Python is great for agent logic. But workflow definitions aren't agent logic -- they're configuration.

The separation principle

The cleanest architecture separates three concerns:

Agent logic (Python/TypeScript/bash) -- what each agent does
Chain definition (JSON) -- how agents connect and in what order
Infrastructure (platform) -- execution, monitoring, scheduling

Each evolves at a different rate:

Agent logic changes when you tune prompts or add capabilities
Chain definitions change when you restructure workflows
Infrastructure changes when you scale or add platform features

Mixing them means every change touches everything. Separating them means focused, reviewable, reversible changes.

Practical patterns

Environment-specific chains

chains/
  content-pipeline.json          # production
  content-pipeline.staging.json  # staging (uses cheaper models)
  content-pipeline.test.json     # test (uses mock agents)

Same workflow structure, different configurations per environment.

Chain templates

templates/
  research-and-summarize.json    # 2-agent template
  four-stage-pipeline.json       # 4-agent template
  review-loop.json               # iterative review template

Start new chains from templates. Customize the prompts, keep the structure.

Chain versioning

chains/
  v1/content-pipeline.json       # original
  v2/content-pipeline.json       # with quality gate added
  v3/content-pipeline.json       # with parallel researchers

Or just use git branches. Either way, you can run any version at any time.

The portability argument

JSON chain definitions are portable:

Export from Mentiko, import into any system that reads JSON
Share chains with teammates via git push
Publish chains to the marketplace for the community
Migrate between platforms without rewriting workflows

Code-based workflows are locked to their platform. A LangGraph state machine only runs in LangGraph. A CrewAI crew definition only runs in CrewAI. A Mentiko JSON chain can be read by anything.

Ready to version-control your workflows? Build your first chain or see the chain patterns.