multi-agent-orchestration

マルチエージェントのオーケストレーション

専門性や安全な並列処理によるメリットが、調整コストを上回る場合にのみ、複数のエージェントを使用してください。

使用する場面

• 大きな目標を、独立して検証可能な作業ストリームに分割します。
• 異なるツール、権限、またはコンテキストを必要とする専門家を連携させます。
• ワーカーとレビュアー、プランナーと実行担当者、マップリデュース、または範囲を限定したディベートのパターンを実行します。
• 重複作業、編集の競合、不十分な引き継ぎ、または停滞した依存関係を診断します。

エージェント数を増やすことだけを目的として、密接に関連する小規模なタスクや、本質的に逐次的なタスクを委任しないでください。

入力

目標、完了基準、タスクグラフ、利用可能なエージェントとツール、同時実行の制限、共有ファイルやシステム、権限の境界、期限、予算、最終的な意思決定者を収集します。前提と未解決の依存関係を明記します。

出力要件

次の内容を作成します。

1. 分解の根拠と、明示的な対象外事項。
2. すべてのタスクについて、担当者、依存関係、入力、出力要件、書き込み範囲、検証方法を記載した有向非巡回タスクグラフ。
3. 引き継ぎプロトコルと共有状態のポリシー。
4. 承認ポイント、タイムアウトと再試行の上限、エスカレーション経路、停止条件。
5. 意見の相違を解決し、統合後の成果を検証する統合計画。
6. 根拠、残る不確実性、未使用または失敗した作業ブランチを記載した完了報告。

ワークフロー

1. 作業を割り当てる前に、測定可能な目標を1つ定義し、権限の境界を明確にします。
2. 曖昧な役割ではなく、分離可能な成果物ごとに分解します。可変の共有状態は最小限に抑え、密接に関連する手順は1人の担当者に任せます。
3. 依存関係を図示し、クリティカルパスを特定します。入力が独立し、副作用が重複しないタスクのみを並列化します。トポロジーを選ぶ際は、orchestration-patterns.md を参照してください。
4. タスクごとに、説明責任を負う担当者を1人割り当てます。入力、成果物の形式、書き込み範囲、検証方法、期限またはタイムアウト、エスカレーションが必要となる条件を指定します。
5. 各エージェントには、必要最小限のコンテキストと権限を与えます。独立した判断が重要な場合は、隠された結論ではなく、ソースとなる成果物を含めます。
6. 構造化された引き継ぎを必須とします。状況、結果、根拠、変更された状態、前提、リスク、次の依存関係を記載します。後続の変更を行う前に、受領を確認します。
7. 依存関係の状態と有用な進捗を監視します。再試行や議論に上限を設け、明確な処理能力と責任のモデルなしに再帰的な委任を行わないでください。
8. 一元的に、または指名された統合担当者を通じて統合します。一次資料に基づいて相反する主張を解決し、統合チェックを実行して、元の完了基準を満たしていることを確認します。
9. 使用しない作業を終了またはキャンセルし、未解決のリスクを記録して、最終的な意思決定者に制御を戻します。

実行前に python3 scripts/validate_plan.py plan.json --strict を使用します。このコマンドは、依存関係、循環、担当者、承認参照、数値による実行上限を構造的にチェックします。厳格モードでは、完全に一致する並列書き込み競合、タイムアウトや再試行の上限の欠落、不完全な再試行要件など、警告がある場合も失敗します。検証対象は宣言のみです。実行時の分離、認可、承認の真正性、実際のタスクの動作は検証できません。

安全性と権限

• 委任によって権限が拡大することはありません。依頼者が許可していない操作を子エージェントに実行させないでください。
• 外部へのメッセージ送信、購入、デプロイ、破壊的な操作、認証情報へのアクセス、本番環境の変更は、明示的な承認ポイントでのみ許可します。
• 役割ごとに認証情報と機密性の高いコンテキストを分離します。共有状態や引き継ぎを通じて秘密情報を広く共有しないでください。
• 変更可能なリソースには、単独の書き込み担当者、ブランチ、トランザクション、またはロックを使用します。
• ユーザーが所有する変更を保持し、キャンセルから復旧できるようにします。

検証

• 計画が非循環であり、すべての依存関係と承認参照が解決されることを確認します。重大な作業には consequential、deploy、または external-mutation のタグを付け、そのタスク固有の approval_ref が、そのタスクの承認ポイントを指定するようにします。
• 同時に実行可能なタスクが、同じファイル、レコード、ブランチ、または環境に書き込まないことを確認します。
• 依存タスクのブロックを解除する前に、すべての引き継ぎ内容が出力契約を満たしていることを確認します。
• 統合後に、エンドツーエンドテストまたはエビデンスチェックを再実行します。個々のタスクが成功しただけでは不十分です。
• 最終報告で、すべてのタスクが完了、失敗、キャンセル、または置き換えのいずれかとして記録されていることを確認します。

失敗への対処

• エージェントが停止した場合は、最後のエビデンスを確認します。失敗が一時的な場合に限り一度だけ再試行し、その後、タスクを再割り当てするか統合します。
• エージェント間で意見が分かれた場合は、それぞれにソースに基づく主張を求め、指名されたインテグレーターに裁定させます。互換性のない回答を平均してはいけません。
• 共有状態が競合した場合は、書き込みを一時停止し、両方のバージョンを保持したうえで、単一の担当者を通じて調整します。
• 依存関係が失敗した場合は、入力を捏造して後続作業を進めるのではなく、ブロックするか再設計します。
• 調整のオーバーヘッドが残りの作業量を上回る場合は、委任を停止し、単一の担当者のもとでクリティカルパスを完了します。

例

「クロスプラットフォーム認証の変更を準備して実装する」場合は、アーキテクチャと統合を単一の担当者のもとで管理し、独立して行える脅威モデリングとテストフィクスチャの設計を委任します。インターフェースを確定した後にのみ、互いに重複しない実装ファイルを割り当て、各引き継ぎに変更したパスとテストエビデンスを含めるよう求めます。本番環境の設定には承認を必須とし、完了を宣言する前に、インテグレーターが完全なテストスイートを実行し、セキュリティ上の指摘を調整します。