GRAPH.md v1.1.0 · v1.0.0 supported · CC BY 4.0

A portable contract for the whole agent workflow.

GRAPH.md is Cromus’s deterministic, framework-neutral format for describing nodes, edges, shared state, bounded loops, and path budgets before an AI workflow runs.

Openly licensedHuman-readable YAMLZero-LLM validation

Why GRAPH.md

Govern the topology, not only the nodes.

A collection of individually valid agent files can still form an expensive, slow, or unsafe workflow. GRAPH.md makes routing, fan-out, retries, human approvals, state movement, and path-level budgets explicit enough to inspect before execution.

Framework-neutral
Normalize Graph Markdown, LangGraph, CrewAI, AutoGen, OpenAI Agents, Anthropic, Replit Agent, and MCP-linked graphs into one Graph IR.
Deterministic
Parsing, validation, scoring, and bounded path simulation do not require an LLM call.
Budget-aware
Declare per-node and per-path token or cost ceilings so governance travels with the workflow.
Portable by design
Plain Markdown and YAML remain reviewable in Git, CI, an editor, or any compatible runtime.

The v1.1.0 contract

Small enough to read. Complete enough to govern.

v1.0.0 documents remain supported unchanged. Judge nodes require an explicit v1.1.0 declaration. Documents without a version retain v1.0.0 validation with a warning.

A judge declares its seat (router, gate, selector, verifier, advisor, or triage), decision model, question and option counts, state tokens, timeout, fallback, trigger, and optional 0–1 confidence threshold. Simulation charges input only and caps each call's estimated latency at its timeout; it does not execute the judge.

The v1.1 importer also accepts explicit question and option arrays, a model_key, state_tokens under estimates, and multiple fires_on event names. The count-based form remains supported.

spec_version

The GRAPH.md contract version enforced by validators.

entry

The node where execution starts.

exits

One or more successful terminal node IDs.

nodes

Agents, tools, routers, verifiers, judges, humans, and subgraphs.

edges

Sequential, conditional, parallel, and bounded loop connections.

state

Optional shared-state declarations with token estimates.

path_budget

Optional token or cost ceiling for one entry-to-exit run.

support-triage/GRAPH.md
---
name: support-triage
spec_version: "1.1.0"
entry: route
exits: [close]
path_budget:
  cost_usd: 0.25
nodes:
  - id: route
    kind: judge
    seat: router
    decision_model: typesafe:jev-1.13
    questions: 1
    options_count: 2
    state_tokens: 500
    timeout_ms: 1000
    fallback: close
    fires_on: on_request
    confidence_threshold: 0.8
  - id: answer
    kind: agent
    model_key: openai:gpt-5-mini
  - id: close
    kind: human
edges:
  - id: route-answer
    from: route
    to: answer
    kind: conditional
    condition: known_issue
  - id: answer-close
    from: answer
    to: close
---

Published for community use.

GRAPH.md is a Cromus-defined portable format, published under CC BY 4.0. It is open for reuse and community review without claiming endorsement by an external standards body.

Run the validator
Analyze path cost and risk