Mermaid.jsで描く！最強のマルチエージェント・ワークフロー設計図【完全解説】

「昨日作ったAIエージェント、今日見たら何してるか分からない……」

こんな経験、ありませんか？

LangGraphやAutoGenで組んだ複雑なマルチエージェントシステム。コードは書いたものの、エージェント同士がどう会話して、どこでループして、いつツールを使っているのか、全体像がブラックボックス化してしまう現象です。

[!WARNING] ワークフローが可視化されていないエージェント開発は、「地図なしで樹海を歩く」 のと同じです。 バグが出たときに、どこで思考がスタックしたのか追うだけで日が暮れてしまいます。

この記事では、Mermaid.jsを使って「エージェントの思考回路」を美しく、かつ保守可能な形で可視化する方法を徹底解説します。

泥臭いドキュメント作成はもう終わり。**「コードとして管理できる設計図」**を手に入れましょう。

なぜエージェント開発に Mermaid.js なのか？

結論から言うと、エージェントの動きは「フロー」であり、Mermaidは「フローをコードで書くツール」だからです。

ExcelやPowerPointで作った図は、コードが変わるたびに作り直しになります。これは「腐敗するドキュメント」の典型です。しかし、MermaidならMarkdownの中にテキストで書けるため、コードと一緒にGitでバージョン管理できます。

つまり、**「生きた設計図」**を作れるのです。

比較：ドキュメント管理の進化

項目	❌ 従来の作図ツール (PPT/Figma)	⭕️ Mermaid.js
メンテナンス	手動で修正（面倒で放置される）	テキスト編集のみ（コードと同じ感覚）
バージョン管理	バイナリ・画像なので不可	GitでDiffが見れる
可読性	ツールを開かないと見れない	エディタやGitHubで直接プレビュー
AIとの相性	悪い	最高（AIに書かせることができる）

[!TIP] 特に「AIとの相性」が重要です。ClaudeやChatGPTに「このコードのフローをMermaidで書いて」と頼めば、一瞬で図解してくれます。

---

基本パターン①：Reflection（自己改善ループ）

まずは基本の「Reflection（反省）」パターンです。エージェントが回答を生成し、それを「批評家（Critic）」がチェックして、合格するまで書き直させるループ構造です。

これをMermaidの flowchart で書くと、思考のサイクルが一目瞭然になります。

flowchart TD
    Start([開始]) --> Draft[📝 ドラフト作成]
    Draft --> Critique{🧐 品質チェック}

    Critique -- NG: 修正指示 --> Refine[🔄 リライト]
    Refine --> Critique

    Critique -- OK: 合格 --> Final([✅ 完了])

    classDef loop stroke:#ffcc00,stroke-width:2px;
    class Refine,Critique loop

例えば、「ブログ記事を書くエージェント」なら、この図があるだけで「あ、ここで無限ループする可能性があるな」と気づき、max_iterations（最大ループ回数）の実装を思い出すことができます。

---

基本パターン②：Tool Use（ツール利用）

エージェントが「検索ツール」や「計算機」を使うフローです。ここでは sequenceDiagram（シーケンス図）が輝きます。

「誰が」「いつ」「何を」呼び出したのか、時系列で可視化しましょう。

sequenceDiagram
    participant User as 👤 ユーザー
    participant Agent as 🤖 エージェント
    participant Tool as 🛠️ 検索ツール
    participant DB as 🗄️ データベース

    User->>Agent: 「最新のiPhoneの価格は？」
    activate Agent

    Note right of Agent: 内部知識では不明と判断

    Agent->>Tool: 検索実行(query="iPhone 16 price")
    activate Tool
    Tool-->>Agent: 検索結果(JSON)
    deactivate Tool

    Agent->>Agent: 情報整理・回答生成

    Agent->>User: 回答の提示
    deactivate Agent

[!NOTE] シーケンス図は、特に**「非同期処理」や「待機時間」**を意識する際に有効です。エージェントがツールからの返答を待っている間（activate/deactivate）を可視化することで、ボトルネックを発見しやすくなります。

---

応用パターン：Hierarchical Teams（階層型マルチエージェント）

ここからが本番です。LangGraphやAutoGenでよくある「親分（Orchestrator）」と「子分（Workers）」の構成です。

親分がタスクを分解し、専門家に振り分け、最後に集約する。「会社の組織図」そのものですね。 これは subgraph を使って、チームごとの境界線を明確にすると美しくなります。

graph TB
    subgraph Manager ["🕴️ オーケストラ（監督）"]
        Planner[計画立案]
        Reviewer[最終確認]
    end

    subgraph Workers ["👷 ワーカー（実行部隊）"]
        Coder[👨‍💻 コーダー]
        Tester[🧪 テスター]
        Writer[✍️ ライター]
    end

    Input([ユーザー依頼]) --> Planner

    Planner -- "仕様書" --> Coder
    Planner -- "テスト計画" --> Tester

    Coder -- "コード" --> Reviewer
    Tester -- "レポート" --> Reviewer
    Writer -- "ドキュメント" --> Reviewer

    Reviewer -- "修正指示" --> Planner
    Reviewer --> Output([納品])

    style Manager fill:#e1f5fe,stroke:#01579b
    style Workers fill:#fff3e0,stroke:#e65100

この図解があれば、**「誰が誰に指示を出しているのか」**が一発で分かります。 もし「テスターが勝手にまたコーダーに仕事を戻す」ようなスパゲッティ状態になっていたら、図がぐちゃぐちゃになるのですぐに気づけます。

---

実践：Mermaidを書くコツ（AIに任せる）

「Mermaidの記法を覚えるのが面倒……」

そう思いましたか？ 覚える必要はありません。 私たちにはAIがいます。

以下のプロンプトを使えば、あなたのPython/TypeScriptコードから、勝手にMermaid図を生成させることができます。

魔法のプロンプト

あなたは優秀なテクニカルライターです。
以下のコード（Agentic Workflow）を分析し、その処理フローをMermaid.jsの図にしてください。

**条件:**

1. 状態遷移がある場合は `stateDiagram-v2` を使うこと。
2. エージェント間のやり取りが主なら `boundary` や `subgraph` でグループ化すること。
3. ノードには適切な絵文字（🤖, 🛠️, 📝）をつけること。
4. 色分けを行い、見やすくすること。

[ここにコードを貼り付け]

これはまさに、「コードという原材料」を「図解という料理」に変換する魔法のレシピです。

---

結論：ドキュメントは「書く」ものではなく「生成する」もの

かつて、システム設計図はCADやドローイングツールで時間をかけて描くものでした。 しかし、AIエージェントの時代において、ドキュメントはコードとセットで生き続ける動的な資産であるべきです。

1. コードを書く
2. AIに構造をMermaid化させる
3. PRのマージと同時に図も更新される

このサイクルこそが、爆速で進化するAI開発における「地図」を常に最新に保つ唯一の方法です。

さあ、あなたの持っているその複雑怪奇なエージェント・コード。 今すぐMermaidで可視化して、チーム全員が理解できる「美しい設計図」に変えてみませんか？

出典・参考

“If you can’t describe what you are doing as a process, you don’t know what you’re doing.” — W. Edwards Deming

• Mermaid.js Official Documentation
• LangGraph: Building Language Agents as Graphs
• Microsoft AutoGen

関連記事

• AIエージェントとは？自律的に思考・行動するAIの仕組み — [基礎知識]
• 【随時更新】Agentic Design Patterns (AIエージェント設計パターン) まとめ — [デザインパターン]
• AutoGenのワークフローパターンを徹底解説 — [フレームワーク]