agent-swarm-deployer

Agent Swarm Deployer

大量の独立したデータタスク（ドキュメント、レコード、行、項目）を処理し、結果を集約するために、並列サブエージェントのスウォームをデプロイします。データ操作にはこれを使用し、コード変更には agent-army を使用してください。

内容

• references/overview.md -- スウォームとアーミーの比較、ユースケース、アーキテクチャ図
• references/swarm-design.md -- 入出力スキーマ、バッチサイズとスウォームサイズの計算式、スケーリングのガイドライン
• references/agent-brief.md -- エージェントブリーフのテンプレート、データの分配方法、進捗の追跡
• references/aggregation-recovery.md -- マージロジック、完全性の検証、再試行戦略、エラー処理の表
• references/output-formats.md -- CSV／JSON／Markdown／個別ファイルの出力、最終サマリーレポート
• references/task-configs.md -- 感情分析、リードスコアリング、コンテンツ生成、要約用のすぐに使える設定

ワークフロー

1. タスクを理解します。何かをデプロイする前に、データソース、各項目に対する操作、出力形式、出力先、品質／検証要件の5点を明確にします。曖昧な点があれば、まずユーザーに確認してください。仕様を誤ると、すべてのエージェントの計算リソースが無駄になります。

2. 入力の確認と一覧作成を行います。Glob／Bash で項目の場所を特定して件数を数えます。構造を把握するために、サンプルを3～5件読みます。項目あたりと全体のトークン数を見積もります。入力概要（ソース、総件数、項目の形式、サンプルの構造、トークン数の見積もり）を報告します。

3. 入力スキーマを検出し、出力スキーマを定義します。サンプルから入力スキーマを導き出し、タスクに必要な出力スキーマを正確に定義します。references/swarm-design.md を参照してください。

4. スウォームを設計します。トークン予算（エージェントあたり利用可能な約200Kのコンテキストの70％）からバッチサイズを計算し、総項目数からスウォームサイズを計算します。1ウェーブあたり最大20エージェントとし、それを超える場合は複数のウェーブに分割します。スウォーム計画とエージェントの割り当てを提示し、承認を得てください。references/swarm-design.md を参照してください。

5. エージェントブリーフを準備します。役割、タスク、入力データ、例を含む出力スキーマ、品質ルール、エラープロトコル、厳密な JSON 出力形式を含む、エージェントごとの自己完結したブリーフを作成します。references/agent-brief.md を参照してください。

6. データを分配してデプロイします。ソースの種類に応じて分配方法を選びます（Bash で CSV／JSON を事前に分割する、小規模なセットはインラインで埋め込む、ディレクトリの場合はファイルパスを渡す）。Agent ツールを使い、run_in_background: true で最大20エージェントを並列起動し、すべての呼び出しを1つのメッセージで送信します。前のウェーブが完了したら、次のウェーブを実行します。references/agent-brief.md を参照してください。

7. 進捗を追跡します。エージェントから結果が返るたびに、ステータス、処理済み件数、累積カバレッジを記録します。references/agent-brief.md を参照してください。

8. 収集して集約します。各エージェントの JSON を解析し、スキーマ、完全性、重複を検証します。結果を1つの順序付き出力にマージし、失敗を抽出します。カバレッジの確認と失敗分析を含む集約概要を報告します。references/aggregation-recovery.md を参照してください。

9. 失敗から復旧します。失敗した項目とスキップされた項目をすべて再試行キューに入れ、指示を強化した再試行用エージェントをデプロイします。再試行は最大2回とし、残った項目には「回復不能」の印を付けます。回復不能な項目が10％を超える場合は、ユーザーに通知します。references/aggregation-recovery.md を参照してください。

10. 出力を書き込み、要約します。要求された形式（CSV、JSON、Markdown、または個別ファイル）を作成し、実行内容、結果、品質指標、観察されたパターン、コストをまとめた最終サマリーを作成します。references/output-formats.md を参照してください。

避けるべきアンチパターン

1. 順次処理が必要なタスクにスウォームを使わないでください。項目 N が項目 N-1 に依存する場合は、チェーンを使用します。
2. 項目ごとにエージェントを1つデプロイしないでください。項目をバッチにまとめます。エージェント1つにつき1項目では、オーバーヘッドが無駄になります。
3. スキーマ定義を省略しないでください。スキーマがなければ、多数のエージェントの結果を信頼性高くマージできません。
4. 失敗を無視しないでください。成功率が99％でも、10,000項目の1％は依然として100件の失敗です。必ず再試行してください。
5. サンプル実行なしでデプロイしないでください。規模を拡大する前に、まず5項目を手動で処理し、タスクと出力品質を検証します。