Mermaid diagrams for AI agents: map a workflow inside OpenClaw chat

Mermaid diagrams for AI agents are useful when a workflow has become too dense to review as a paragraph. A diagram can show where a request enters, which tool call needs approval, where a retry belongs, and who receives the final result. In OpenClaw v2026.9.1, Mermaid blocks render directly in the Control UI and the native macOS, iOS, and Android apps, so the map can stay beside the conversation that produced it.

That sounds cosmetic until you are debugging an agent that touches a calendar, a browser, and a GitHub repository in one run. A text transcript tells you what happened. A diagram makes the control flow visible enough to question it.

Table of contents

Start with the decision the diagram must support

An AI agent diagram should answer one question for one reader. Good examples include:

  • Where does an inbound message cross into a tool-enabled session?
  • Which steps can run in parallel, and which must wait for an earlier result?
  • Where does the workflow require a person to approve a write or restart?
  • What happens when a model call, browser task, or external API fails?

Do not begin by diagramming every package and event. That produces a poster, not a working tool. Microsoft makes a similar point in its guide to AI agent orchestration patterns: use the lowest level of agent complexity that meets the requirement. The diagram should make that choice easier to inspect.

For a personal agent, the first useful diagram is often a small flowchart of a real task. It should show the user request, the session, any decision point, the action, and the final delivery. That is enough to expose a missing approval boundary or an unnecessary handoff.

A Mermaid diagram for a reviewable agent workflow

Mermaid flowcharts are made from nodes and edges. The Mermaid flowchart syntax supports directional graphs, labeled arrows, and decision nodes, which makes it a good fit for a compact agent workflow map.

Here is a deliberately small example. It does not describe every OpenClaw component. It describes a decision: whether a requested action needs review before a tool runs.

flowchart TD
    Request[User request] --> Session[Resolve session and policy]
    Session --> Plan[Plan next action]
    Plan --> NeedsApproval{Writes or external side effect?}
    NeedsApproval -->|Yes| Approval[Ask for approval]
    Approval -->|Approved| Tool[Run approved tool]
    Approval -->|Rejected| Explain[Explain what was not run]
    NeedsApproval -->|No| Tool
    Tool --> Result[Return result to the originating chat]

The important design choice is the diamond, not the styling. It forces a team to name the condition that separates a safe read from an action that changes something. If nobody can write that condition plainly, the workflow is not ready to automate.

OpenClaw’s latest release makes this practical in the place where the work is discussed. According to the v2026.9.1 release notes, completed Mermaid fences render in chat with the source, copy controls, enlargement, and a mobile retry path. You can ask for a map, inspect it with the agent, then revise the same conversation instead of exporting the workflow to a separate diagram tool.

Use the right diagram for the agent behavior

A flowchart is not the right answer for every AI agent diagram. Match the format to the behavior you need to inspect.

If you need to reviewUseWhat it should make clear
Branching, approvals, and tool choicesFlowchartConditions, allowed paths, and failure exits
Calls that happen over timeSequence diagramWho calls whom, ordering, timeouts, and callbacks
Durable session behaviorState diagramLegal states, transitions, and recovery paths
Stable systems and integrationsArchitecture sketchBoundaries, ownership, data stores, and external services

A sequence diagram is better than a flowchart when the order of calls is the risk. For example, a GitHub write should follow authentication and approval, then produce a receipt back to the originating session. A state diagram is better when a task can pause, resume, fail, or wait for a person.

The habit that saves time is naming the diagram before writing it. “Show the retry path after the browser step fails” yields a reviewable artifact. “Draw our agent architecture” usually yields a vague inventory.

Keep execution boundaries visible

A diagram can make unsafe design look neat, so give it enough detail to be audited. For an agent that uses tools, include:

  1. The trigger: a chat message, cron run, webhook, or manual command.
  2. The session or queue that owns the work.
  3. Each tool boundary, especially browser, shell, file, or remote API actions.
  4. The approval or policy check before irreversible work.
  5. The delivery target for success, rejection, and failure.

Those boundaries matter in a self-hosted setup because the agent can touch real systems. The OpenClaw AI agent architecture guide explains how the Gateway, channels, sessions, models, and skills are separated. Use that system map for the stable components. Use a smaller Mermaid diagram to review one live workflow within those components.

This separation is also useful when work fails. A failure node should name what happens next: retry with a limit, ask for an approval, stop and report, or route the task to a human. “Handle error” hides the decision that needs review.

A practical chat loop for building diagrams

OpenClaw’s in-chat rendering shortens a simple loop:

  1. Describe the task and the reader’s question.
  2. Ask for a Mermaid flowchart, sequence diagram, or state diagram with named boundaries.
  3. Check the map for missing approval, ownership, retry, and delivery paths.
  4. Ask for a smaller revision if it tries to capture the whole system.
  5. Put the accepted diagram next to the workflow specification or pull request.

For example, a scheduled research workflow might start as: “Map the path from scheduled trigger to source collection, citation review, draft generation, and delivery. Show where publication requires approval and where a failed source fetch stops the run.” The output gives you something more concrete to challenge than a prose plan.

If the workflow eventually becomes a scheduled job, read how OpenClaw works alongside the diagram. If you are still deciding whether to keep the workflow self-hosted, why OpenClaw outlines the ownership tradeoffs. Check that the diagram’s trigger, execution location, and final delivery route match the real deployment rather than an imagined one.

What Mermaid diagrams do not solve

A diagram does not validate permissions, test a retry, or prove that a tool call is safe. It is a design and review artifact. Keep the source readable, test the workflow with harmless inputs, and make operational policy live in configuration and approvals rather than in a colored box.

It also should not become permanent documentation by accident. When a workflow changes, update the diagram in the same pull request. Mermaid has an advantage here: the diagram source is text, so reviewers can see what changed. A screenshot can look current while describing a flow that no longer exists.

FAQ

Can OpenClaw render Mermaid diagrams inside a chat?

Yes. OpenClaw v2026.9.1 added direct Mermaid rendering in the Control UI and native macOS, iOS, and Android apps. The release notes describe source, copy, preview, enlargement, and mobile retry behavior for completed Mermaid fences.

Which Mermaid diagram should I use for an AI agent?

Use a flowchart for choices and approvals, a sequence diagram for ordered calls, and a state diagram for lifecycle and recovery. Start with the narrowest diagram that answers the review question.

Should an AI agent diagram include every tool and model detail?

Usually no. Show tool boundaries and decisions that change risk or behavior. Leave implementation detail in the specification or code unless it changes the reader’s decision.

Make the agent workflow easy to challenge

Mermaid diagrams for AI agents work best as a review surface. They make the invisible parts of a workflow visible: a missing approval, a retry with no limit, a session that has no clear owner, or a final result with nowhere reliable to go.

Start with one task you already run. Map the smallest useful version in chat, challenge the branches, then keep the accepted source with the workflow. That is a better use of diagrams than drawing a more impressive version of an unclear system.

Sources: OpenClaw v2026.9.1 release notes, Mermaid flowchart syntax, Microsoft AI agent orchestration patterns