Agentic Mermaid

Start with setup or examples; keep reading for the typed-edit guide. Op shapes and warning codes are pinned by capabilities.json.

Start here


See one typed edit

Change the review label while keeping the same three node identities and two connections. Replay the results below, generated by the real API during the site build.

mutate(diagram, {"kind":"set_label","target":"Review","label":"Approved"})
Review workflowDraft flows through review to publication. Draft Review Publish
Before: Draft flows through Review to Publish.
Mermaid source
flowchart LR
accTitle: Review workflow
accDescr: Draft flows through review to publication.
  Draft[Draft] --> Review[Review] --> Publish[Publish]

Open original diagram in the editor

Original diagram verified: 0 warnings.

Guide: editing a diagram without regenerating it

A render-only tool makes an agent rebuild the whole diagram to move one node. Agentic Mermaid keeps the diagram structured, so an edit is five small steps, and verify gates the last one.

Most diagram tools render and stop. You hand them source, they hand back a picture, and to change one node you send the whole source again. That is fine for a person editing by hand and wasteful for an agent editing in a loop, where every regeneration risks moving nodes that were already correct.

The fix is to treat an existing diagram as structured data, not a string. A typed surface exposes source nodes, edges and other family-specific objects an agent can name and change, and refuses edits it cannot make safely. These source objects are distinct from drawing parts; see the shared vocabulary. The loop has five steps.

1 · Parse

Read the source into its family model. Inspect the parsed body and diagnostics before choosing an edit.Preserved source and structured edit support are different capabilities. A preserved body can round-trip without exposing typed operations.

2 · Narrow

Select the typed family, such as Flowchart or Sequence, before applying its operations.Narrowing identifies the available operations. An edit can recompute layout; unchanged elements are not guaranteed to keep their coordinates.

Agentic Mermaid edit loop Source flows through parse, narrow, mutate, verify, and serialize to render, with warnings routed back for another edit. ok warnings Source .mmd parse narrow mutate verify serialize → render
The five-step loop. verify sits between mutate and serialize; a warning sends the work back to narrow.

3 · Mutate

Apply a named operation to the typed family value. The operation returns a new typed model; it does not rewrite the source by hand.

mutate(diagram, { kind: "add_edge", from: "V", to: "R", label: "ok" })
// returns { ok: true, value: ValidDiagram } or a structured error

4 · Verify

Inspect verifyMermaid's ok, warning codes, severities and check evidence. Errors block a successful return; warnings still need judgement. Verification does not prove that an explanation is true or that every source edit is lossless. Use semantic facts for task-critical meaning and review the artifact when appearance matters. The library reference describes result shapes and recovery.

5 · Serialize

Write the typed model back to Mermaid source. serializeMermaid does not run verification; inspect the result of verifyMermaid before saving, sending or showing the edit. Render only when an artifact is needed.Layout is deterministic for the same source and resolved options. Styles can change paint without changing geometry; a byte diff is not necessarily a layout change.

Return verification findings when an edit cannot be completed. Preserve the previous source and explain the failed operation instead of fabricating a successful result.

Use this loop for existing source edits. New diagrams can start as Mermaid text, and artifact-only tasks can call the renderer directly. See the library reference for both paths.


More in the manual

Docs index