> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shannon.run/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Lead Agentによる自律的なマルチエージェント協調のためのShannonのSwarm Workflowの理解

## Swarmモードとは？

Swarmモードは、複数の永続的な自律Agentを並列にデプロイし、複雑なタスクを協力して解決します。LLMを搭載した**Lead Agent**がチームを動的に調整します。タスクの計画、Agentの生成、作業の再割り当て、リアルタイムイベントに基づく意思決定を行います。

タスクが事前に分解されて変更されない静的なオーケストレーションとは異なり、Lead Agentは進捗を継続的に監視し、状況の変化に応じて新しいタスクの作成、冗長な作業のキャンセル、アイドルAgentの再割り当てを行います。

## 仕組み

ShannonのSwarm Workflowは**イベント駆動のLead Agentループ**で動作します：

### Lead Agentイベントループ

Lead Agentは特定のイベントで起動し、次のアクションを決定します：

```text theme={null}
Leadを起動するイベント:
├── agent_idle       — Agentが現在のタスクを完了し、利用可能になった
├── agent_completed  — Agentが最終出力を生成した
├── help_request     — AgentがLeadにヘルパーの生成を要求した
├── checkpoint       — 定期タイマー（120秒ごと）で全体の進捗をレビュー
└── human_input      — ユーザーが実行中に新しい指示を送信した
```

各起動時に、Leadはチーム全体のステータス（Agent、タスク、予算）を受け取り、1つ以上のアクションを選択します。

### ライフサイクルの概要

1. **初期計画** -- Leadがユーザーのクエリを受け取り、オプションで依存チェーンを持つ初期タスクセットを作成
2. **Agent生成** -- Leadが依存順序を尊重してAgentを生成し、タスクを割り当て
3. **イベント駆動の調整** -- Agentが作業を完了したり、アイドルを報告したり、チェックポイントに到達した際に、Leadが動的にタスクを再割り当て、計画を修正、または新しいAgentを生成
4. **統合** -- すべてのタスクが完了すると、Leadは専用の統合Agentを生成するか、`done`を宣言して最終レスポンスを生成

### タスク依存関係 (DAG)

タスクは他のタスクへの依存関係を宣言でき、有向非巡回グラフ（DAG）を形成します：

```text theme={null}
Tasks:
├── task-1: "Research US AI chip market"        (depends_on: [])
├── task-2: "Research Japan AI chip market"     (depends_on: [])
├── task-3: "Research South Korea AI chip market" (depends_on: [])
└── task-4: "Write comparative analysis"        (depends_on: [task-1, task-2, task-3])
```

システムは依存順序を強制します。`task-4`は3つのリサーチタスクがすべて完了するまで割り当てられません。Leadは`revise_plan`を通じて新しい依存チェーンを動的に作成できます。

## Lead Agentアクション

Leadが起動するたびに、1つ以上のアクションを選択します：

| アクション            | 説明                                 |
| ---------------- | ---------------------------------- |
| `spawn_agent`    | 特定のタスク用に新しいAgentを作成                |
| `assign_task`    | 保留中のタスクをアイドルAgentに割り当て             |
| `revise_plan`    | 新しいタスクを動的に作成、または既存のタスクをキャンセル       |
| `send_message`   | 特定のAgentにメッセージを送信                  |
| `broadcast`      | すべてのAgentにメッセージを送信                 |
| `file_read`      | ワークスペースファイルを読み取り（LLMコストゼロ、最大3ラウンド） |
| `shutdown_agent` | 特定のAgentを終了                        |
| `interim_reply`  | ユーザーに進捗更新をプッシュ                     |
| `noop`           | 何もしない（現在アクション不要）                   |
| `done`           | すべての作業の完了を宣言し、クロージングフェーズに進む        |
| `reply`          | ユーザーに最終回答を直接返す（クロージングフェーズのみ）       |
| `synthesize`     | 直接回答する代わりに合成パイプラインをトリガー            |

## Agentアクション

各イテレーションで、Agentは1つのアクションを選択します：

| アクション          | 説明                         |
| -------------- | -------------------------- |
| `tool_call`    | ツールを実行（Web検索、ファイル読み取りなど）   |
| `publish_data` | ワークスペースを通じてチームに発見を共有       |
| `send_message` | 特定のチームメイトにダイレクトメッセージを送信    |
| `request_help` | Leadに新しいヘルパーAgentの生成を要請    |
| `idle`         | 現在のタスクが完了したことを通知し、再割り当てを待つ |
| `done`         | 最終レスポンスを返す（自動的に`idle`に変換）  |

<Note>
  Agentは自分自身を終了できません。Agentが`done`を返すと、自動的に`idle`ステータスに変換されます。`shutdown_agent`でAgentを終了できるのはLead Agentのみです。これにより、Leadがチーム構成の完全な制御を維持します。
</Note>

## Agent間通信

Swarm Agentは2つのメカニズムで協調します：

### P2Pメッセージング

AgentはRedisベースのメールボックスを通じて特定のチームメイトにダイレクトメッセージを送信します。メッセージタイプには`request`、`offer`、`accept`、`delegation`、`info`があります。

各LLM呼び出し前に、Agentのメールボックスで新しいメッセージがチェックされます。受信メッセージはAgentのプロンプトコンテキストに表示されます。

### 共有ワークスペース

Agentはトピックベースのワークスペースリストに発見を公開します。各イテレーション前に、すべてのAgentがすべてのトピックから最新のワークスペースエントリを取得し、チーム全体が集合的な進捗を把握します。

```text theme={null}
Shared Workspace:
├── Topic: "findings"
│   ├── Agent-Takao: "NVIDIA dominates US with 80% market share..."
│   └── Agent-Mitaka: "Japan focuses on edge AI chips..."
└── Topic: "sources"
    └── Agent-Kichijoji: "Samsung foundry plans announced..."
```

## 知識重複排除

Shannonは3層の重複排除メカニズムでAgent間の冗長な作業を防止します：

<AccordionGroup>
  <Accordion title="L1: Agent単位のURLフェッチキャッシュ">
    各AgentはすでにフェッチしたURLをキャッシュします。同じAgentループ内で同じURLが再度リクエストされた場合、ネットワーク呼び出しなしでキャッシュされたコンテンツが返されます。
  </Accordion>

  <Accordion title="L2: Agent間共有URLメタデータ">
    URLメタデータ（タイトル、要約、主要な事実）はチーム内のすべてのAgent間で共有されます。Agent BがAgent Aがすでに処理したURLをフェッチしようとすると、再フェッチではなくキャッシュされたメタデータを受け取ります。これにより時間とトークンの両方を節約できます。
  </Accordion>

  <Accordion title="L3: 検索オーバーラップ検出">
    全Agent間で発見された検索結果URLを追跡します。新しい検索で返されたURLの70%以上が他のAgentにより既に発見されている場合、システムは新しいアングルを探すよう警告を注入します。さらに、検索飽和検出器がJaccard単語レベル類似度（しきい値0.7、3クエリのウィンドウ）を使用して最近のクエリを比較し、重複検索をフラグします。
  </Accordion>
</AccordionGroup>

## 収束検出

3つのメカニズムでAgentが無期限に実行されることを防止します：

<AccordionGroup>
  <Accordion title="進捗なし検出">
    Agentが3回連続で意味のあるアクションを実行しなかった場合（空または認識不能なaction）、収束と見なされidleステータスに遷移します。`tool_call`、`send_message`、`publish_data`はこのカウンターをリセットします。
  </Accordion>

  <Accordion title="連続エラー中止">
    3回連続で永続的なツールエラーが発生した場合（レートリミットなどの一時的エラーを除く）、Agentは中止し、失敗を報告します。
  </Accordion>

  <Accordion title="最大イテレーション強制完了">
    最後のイテレーションでAgentが`done`または`idle`を呼び出していない場合、Workflowが強制完了し、直近のイテレーションからサマリーを構築します。
  </Accordion>
</AccordionGroup>

一時的なエラー（レートリミット、タイムアウト、503）は自動リトライをトリガーし、バックオフが段階的に増加します（5秒刻み、最大30秒）。これらは中止しきい値にカウントされません。

## グローバル予算制御

Swarmの実行は3層の予算制約でコストの暴走を防止します：

| 予算層                      | デフォルト       | 説明                      |
| ------------------------ | ----------- | ----------------------- |
| `max_total_llm_calls`    | `200`       | すべてのAgent全体のLLM呼び出し最大回数 |
| `max_total_tokens`       | `1,000,000` | すべてのAgent全体の最大トークン消費量   |
| `max_wall_clock_minutes` | `30`        | Swarm全体の最大ウォールクロック時間    |

Lead Agentはコンテキストで予算情報（残りの呼び出し回数、トークン、時間）を受け取り、コスト意識の高い意思決定を行います。例えば、予算が厳しい場合に低優先度のAgentをシャットダウンしたり、オプションのタスクをスキップしたりします。

## Swarmと他のWorkflowの使い分け

| シナリオ                            | 推奨Workflow        |
| ------------------------------- | ----------------- |
| シンプルなQ\&A、単一ステップのタスク            | Simple / DAG      |
| 引用付きのマルチステップリサーチ                | Research Workflow |
| マルチAgentコードレビュー、テスト、修正          | **Swarm**         |
| 多角的な金融分析（ファンダメンタル、テクニカル、センチメント） | **Swarm**         |
| Python/Bash実行によるデータ処理パイプライン     | **Swarm**         |
| Agentが中間的な発見を共有する必要があるタスク       | **Swarm**         |
| 動的なサブタスク発見を伴う長時間の探索             | **Swarm**         |
| サブタスク間の複雑な依存チェーンを持つタスク          | **Swarm**         |

<Note>
  Swarmモードは各Agentが複数のLLMイテレーションを実行し、Lead Agentの調整決定もトークンを消費するため、標準Workflowよりも多くのトークンを消費します。永続的で協調的なマルチAgent実行から本当に恩恵を受けるタスクに使用してください。
</Note>

## 設定

Swarmの動作は`config/features.yaml`で制御されます：

| パラメータ                            | デフォルト     | 説明                       |
| -------------------------------- | --------- | ------------------------ |
| `swarm.enabled`                  | `true`    | Swarm Workflowの有効/無効     |
| `swarm.max_agents`               | `10`      | Agent総数の上限（初期 + 動的）      |
| `swarm.max_iterations_per_agent` | `25`      | Agentごとの推論-行動ループの最大回数    |
| `swarm.agent_timeout_seconds`    | `1800`    | Agentごとのタイムアウト（30分）      |
| `swarm.max_messages_per_agent`   | `20`      | AgentごとのP2Pメッセージ上限       |
| `swarm.workspace_snippet_chars`  | `800`     | プロンプト内のワークスペースエントリの最大文字数 |
| `swarm.workspace_max_entries`    | `5`       | 各Agentに表示される最近のエントリ数     |
| `swarm.max_total_llm_calls`      | `200`     | Swarm全体のグローバルLLM呼び出し予算   |
| `swarm.max_total_tokens`         | `1000000` | Swarm全体のグローバルトークン予算      |
| `swarm.max_wall_clock_minutes`   | `30`      | Swarmの最大ウォールクロック時間       |

## ストリーミングイベント

Swarm Workflowはリアルタイム監視用のSSEイベントを発行します：

| イベントタイプ              | Agent ID                          | タイミング                           |
| -------------------- | --------------------------------- | ------------------------------- |
| `WORKFLOW_STARTED`   | `swarm-supervisor`                | Workflow開始時                     |
| `PROGRESS`           | `swarm-lead` / `swarm-supervisor` | 計画、生成、再割り当て                     |
| `LEAD_DECISION`      | `swarm-lead`                      | Leadが計画決定を行った（生成、割り当て、修正など）     |
| `TASKLIST_UPDATED`   | `swarm-lead`                      | タスク依存グラフが変更された（タスクの作成またはキャンセル）  |
| `TEAM_STATUS`        | `swarm-lead`                      | チーム構成が変更された（Agentの生成またはシャットダウン） |
| `AGENT_STARTED`      | Agent名                            | Agentが最初のイテレーションを開始             |
| `AGENT_COMPLETED`    | Agent名                            | Agentが完了                        |
| `WORKFLOW_COMPLETED` | `swarm-supervisor`                | 最終統合完了                          |

## 次のステップ

<CardGroup cols={2}>
  <Card title="Swarmチュートリアル" icon="users" href="/ja/tutorials/swarm-workflow">
    Swarm Workflowのステップバイステップガイド
  </Card>

  <Card title="WorkflowとPattern" icon="diagram-project" href="/ja/quickstart/concepts/workflows">
    他のWorkflowタイプと認知パターン
  </Card>

  <Card title="ストリーミング" icon="stream" href="/ja/quickstart/concepts/streaming">
    リアルタイムイベントストリーミング
  </Card>

  <Card title="コスト管理" icon="dollar-sign" href="/ja/quickstart/concepts/cost-control">
    マルチAgentタスクの予算管理
  </Card>
</CardGroup>