MadoHub で構築するマルチエージェントワークフロー

1 つの AI エージェントを動かすのは簡単です。互いの出力に依存する 5 つのエージェントを動かすと、話が面白くなり、ほとんどのツールがそこで力尽きます。

この投稿では、タイルの配置からルーティングルールの設定まで、MadoHub でマルチエージェントワークフローを構築する方法を説明します。

出力から始める

キャンバスにタイルを置く前に、最終的にどんな出力が欲しいのかを決めましょう。結果から逆算すると、どの中間ステップが必要かを考えやすくなります。

たとえば、テスト済みでドキュメント付きの API エンドポイントを生成したいとします。最終出力は、実装、テスト、ドキュメントを含む pull request です。そこから逆算すると次のようになります。

• PR composer エージェントが最終成果物をまとめる
• test writer エージェントがテストファイルを作る
• docs writer エージェントが API ドキュメントを生成する
• code generator エージェントが実装を書く
• spec parser エージェントが自然言語の要件を抽出する

キャンバスにタイルを配置する

各エージェントにはタイルを割り当てます。MadoHub では、タイルは独立した実行環境です。それぞれが独自のコンテキスト、モデル設定、system prompt で動きます。

spec parser をキャンバスの左側、PR composer を右側に置きます。中間のエージェントは、その間におおむね実行順で並べます。この左から右へのレイアウトは、システム内のデータフローをそのまま反映しています。

接続を定義する

接続は、タイル間の有向エッジです。spec parser の出力ポートから code generator の入力ポートへ接続を引くと、MadoHub に対して、解析済み仕様をコード生成プロンプトへ渡すよう指示していることになります。

1 つのタイルは複数入力を持てます。たとえば test writer は、解析済み仕様と生成コードの両方を受け取り、仕様に合うテストを書きつつ、実装そのものも呼び出せます。

ルーティング戦略

上流の出力が現れた瞬間にすべての接続が発火すべきではありません。MadoHub の各接続には trigger があります。

• on-complete: 上流エージェントのセッションが完了したと検知された時点で発火
• on-idle: 上流エージェントのターミナルがアイドルになった時点で発火
• on-keyword: 上流の出力に設定済みのキーワードが現れた時点で発火
• always: 完了シグナルを必要とせず、新しい出力チャンクが来るたびに発火

内部的には、on-complete と on-idle は同じ仕組みで扱われます——どちらも、トリガーとなるシグナルの後に短いアイドルタイマー（約 8 秒）を待ってからルーティングします。2 つの独立した戦略というより、開始理由が違うだけの同じ一時停止だと考えてください。

各接続には transform もあり、実際に下流へ送られる内容を制御します: raw（直近の数行をそのまま）、summary（AI が生成した要約）、full-output（より広い直近のウィンドウ）、prompt-wrap（{output} や {round} のような変数を使う独自テンプレート）、ai-routing（AI が生成する文脈認識プロンプトで、API key の設定が必要）。

この API ワークフローでは、spec parser から code generator への接続を on-complete トリガー・full-output transform に設定し、code generator から test writer と docs writer への接続をどちらも on-complete トリガー・raw transform に設定するとよいでしょう——code generator のセッションが完了を報告した時点で、両方の下流エージェントが同じ直近の出力をもとにすぐ動き出します。

失敗の扱い

エージェントは失敗します。モデルは幻覚を見ます。出力が常に期待通りとは限りません。堅牢なマルチエージェントワークフローには、ルーティングされたループが無限に回り続けないためのガードレールが必要です。

MadoHub のループ保護は、出力の検証ではなくラウンド数ベースで機能します。ルーティングされた各接続には maxRounds の上限（デフォルト 5、1〜20 の範囲で設定可能）と、ラウンド間の cooldown（デフォルト 3 秒、最大 30 秒まで設定可能）があり、下流エージェントが現実的に応答できる速度より速く再トリガーされないようになっています。stopKeyword（大文字小文字を区別しない任意の部分文字列、例えば "LGTM"）を設定することもでき、エージェントの出力にそれが含まれた時点でループは停止します。

これはまさに MadoHub 組み込みの Peer review flow の仕組みです。Claude Code の author と Codex の reviewer がループ状に接続され、stopKeyword は "LGTM" に設定されています——reviewer はそう言うまでフィードバックを送り続け、そこでループが止まります。組み込みの Pipeline flow はよりシンプルです。最初のエージェントの full-output が完了時に 2 番目のエージェントへ渡される、2 段階の受け渡しです。組み込みの Watcher flow は最初から最後までキーワード駆動で、ai-routing transform を使ってマッチしたフレーズを文脈認識のフォローアッププロンプトへ変換します。

反復こそが本質

キャンバスベースのマルチエージェントワークフローの本当の利点は、反復の速さです。たとえば code generator と PR composer の間に security reviewer を追加したくなったとします。それは数秒で済みます。タイルを 1 つ置き、2 本の接続を引けば、ワークフローは更新されます。

これを pipeline-as-code でやろうとすると大変です。設定ファイルを編集し、プロセスを再起動し、スキーマがまだ通るか祈ることになります。キャンバスでは、フィードバックループがすぐに回ります。