Swarmマルチエージェントワークフロー
このチュートリアルでは、ShannonのSwarmWorkflowを使用して、LLMを搭載したLead Agentが調整する永続的で協調するAgentをデプロイする方法を紹介します。Agentは並列で作業し、Agent間メッセージング、共有ワークスペース、動的タスク再割り当てをサポートします。学べること
- APIとPython SDKでSwarmタスクを送信する方法
- Lead Agentがイベントを通じてAgentを調整する仕組み
- SSEストリーミングでAgentの進捗を監視する方法
- Swarmパラメータと予算制御の設定方法
- 実際のユースケースとベストプラクティス
前提条件
- Shannonスタックが稼働中(Docker Compose)
http://localhost:8080でゲートウェイにアクセス可能config/features.yamlでSwarmが有効(デフォルトで有効)- 認証のデフォルト:
- Docker Compose: 認証はデフォルトで無効(
GATEWAY_SKIP_AUTH=1)。 - ローカルビルド: 認証はデフォルトで有効。認証を無効にするには
GATEWAY_SKIP_AUTH=1を設定するか、APIキーヘッダー-H "X-API-Key: $API_KEY"を含めます。
- Docker Compose: 認証はデフォルトで無効(
クイックスタート
curl -X POST http://localhost:8080/api/v1/tasks \
-H "Content-Type: application/json" \
-d '{
"query": "Compare AI chip markets across US, Japan, and South Korea",
"session_id": "swarm-demo-001",
"context": {
"force_swarm": true
}
}'
{
"task_id": "task-abc123...",
"status": "STATUS_CODE_OK",
"message": "Task submitted successfully",
"created_at": "2025-11-10T10:00:00Z"
}
data: {"type":"WORKFLOW_STARTED","agent_id":"swarm-supervisor","message":"Lead Agent initializing team"}
data: {"type":"LEAD_DECISION","agent_id":"swarm-lead","message":"Creating initial plan with 3 tasks"}
data: {"type":"TASKLIST_UPDATED","agent_id":"swarm-lead","message":"Task graph updated: 4 tasks (3 research + 1 synthesis)"}
data: {"type":"TEAM_STATUS","agent_id":"swarm-lead","message":"Spawned agent takao"}
data: {"type":"AGENT_STARTED","agent_id":"takao","message":"Agent takao started"}
data: {"type":"TEAM_STATUS","agent_id":"swarm-lead","message":"Spawned agent mitaka"}
data: {"type":"AGENT_STARTED","agent_id":"mitaka","message":"Agent mitaka started"}
data: {"type":"TEAM_STATUS","agent_id":"swarm-lead","message":"Spawned agent kichijoji"}
data: {"type":"AGENT_STARTED","agent_id":"kichijoji","message":"Agent kichijoji started"}
data: {"type":"PROGRESS","agent_id":"takao","message":"Agent takao progress: iteration 1/25, action: tool_call"}
data: {"type":"AGENT_COMPLETED","agent_id":"takao","message":"Agent takao completed"}
data: {"type":"LEAD_DECISION","agent_id":"swarm-lead","message":"Assigning synthesis task to takao"}
data: {"type":"AGENT_COMPLETED","agent_id":"mitaka","message":"Agent mitaka completed"}
data: {"type":"AGENT_COMPLETED","agent_id":"kichijoji","message":"Agent kichijoji completed"}
data: {"type":"LEAD_DECISION","agent_id":"swarm-lead","message":"All tasks complete, finalizing"}
data: {"type":"WORKFLOW_COMPLETED","agent_id":"swarm-supervisor","message":"All done"}
{
"task_id": "task-abc123...",
"status": "TASK_STATUS_COMPLETED",
"result": "## AI Chip Market Comparison\n\n### United States\nThe US market is dominated by NVIDIA...\n\n### Japan\nJapan focuses on edge AI...\n\n### South Korea\nSouth Korea leverages Samsung...",
"metadata": {
"workflow_type": "swarm",
"total_agents": 3,
"total_tokens": 598235,
"model_breakdown": [
{
"model": "claude-haiku-4-5-20251001",
"provider": "anthropic",
"executions": 38,
"tokens": 297524,
"cost_usd": 0.372
},
{
"model": "shannon_web_search",
"provider": "shannon-scraper",
"executions": 12,
"tokens": 90000,
"cost_usd": 0.048
}
]
},
"usage": {
"input_tokens": 289164,
"output_tokens": 309071,
"total_tokens": 598235,
"estimated_cost": 0.780
}
}
送信 + ストリーミングを一回で
フロントエンドアプリケーションでは、送信とストリーミングを統合するエンドポイントを使用します:Python SDK
基本的な使用方法
ストリーミング付き
カスタムコンテキスト
Agentの協調方法
Lead Agentによる調整
Lead Agentはイベント駆動のコーディネーターとして機能します。タスクを直接実行するのではなく、イベントに基づいて計画、割り当て、作業の再割り当てを行います:- Agentがidleになると、Leadは依存関係が満たされた保留中のタスクを確認し、次のタスクを割り当て
- Agentが完了すると、Leadは再割り当て、シャットダウン、または計画の修正を評価
- 定期的なチェックポイント(120秒ごと)で、Leadは全体の進捗をレビューし、計画を調整可能
- アイドルAgentがなく、アクション可能な保留タスクもない場合、Leadは不要なLLM呼び出しをスキップ
チームロスター
各AgentはすべてのAgentとその担当を示すチームロスターを受け取ります。これにより、特定の情報について誰に連絡すべきかを把握できます:発見の公開
Agentは共有ワークスペースを通じて発見を共有します。これらはすべてのAgentのプロンプトコンテキストに表示されます:ダイレクトメッセージの送信
Agentは特定のチームメイトにダイレクトメッセージを送信できます:ヘルプの要請
Agentが追加サポートを必要とする場合、Lead Agentにヘルプを要請します:設定
features.yaml
設定パラメータ
| パラメータ | デフォルト | 範囲 | 説明 |
|---|---|---|---|
enabled | true | true/false | Swarm Workflowの有効/無効 |
max_agents | 10 | 1-50 | 動的に生成されたAgentを含むAgent総数の上限 |
max_iterations_per_agent | 25 | 1-100 | Agentごとの推論-行動サイクルの最大回数 |
agent_timeout_seconds | 1800 | 60-7200 | Agentごとのウォールクロックタイムアウト |
max_messages_per_agent | 20 | 1-100 | Agentが送信できるP2Pメッセージの上限 |
workspace_snippet_chars | 800 | 100-4000 | Agentプロンプト内のワークスペースエントリの切り詰め制限 |
workspace_max_entries | 5 | 1-20 | トピックごとに表示される最近のワークスペースエントリ数 |
max_total_llm_calls | 200 | 10-1000 | Swarm内のすべてのAgentにわたる最大LLM呼び出し回数 |
max_total_tokens | 1000000 | 10000-10000000 | すべてのAgentが消費する最大トークン数 |
max_wall_clock_minutes | 30 | 1-120 | Swarm実行全体の最大ウォールクロック時間 |
実際のユースケース
コラボレーティブコーディング
Agentが協調してコードレビュー、実装、テストを実行。サンドボックス実行対応。
金融分析
ブル/ベアアナリスト、センチメントAgent、ポートフォリオマネージャーが投資インサイトを統合。
データ処理
サンドボックスPython実行、JSONクエリ、統計分析による並列データパイプライン。
競合インテリジェンス
競合のWebサイト、価格、SNSを同時監視し、発見を自動的にクロス共有。
例: コラボレーティブコードレビュー
developerロールのAgentを割り当て、すべてのレビュー完了に依存する最終統合タスクを作成します。
例: マルチサイト価格モニタリング
レスポンスメタデータの理解
Swarm Workflowはモデルごとの実行内訳とトークン使用量を含むメタデータを返します:| フィールド | 説明 |
|---|---|
metadata.workflow_type | Swarm Workflowでは常に"swarm" |
metadata.total_agents | 参加したAgent総数 |
metadata.total_tokens | Swarm全体で消費された総トークン数 |
metadata.model_breakdown[] | モデルごとの実行サマリー |
metadata.model_breakdown[].model | モデル識別子 |
metadata.model_breakdown[].provider | プロバイダー名 |
metadata.model_breakdown[].executions | このモデルのLLM呼び出し回数 |
metadata.model_breakdown[].tokens | このモデルが消費したトークン数 |
metadata.model_breakdown[].cost_usd | 推定コスト(USD) |
usage.input_tokens | 全Agentの入力トークン総数 |
usage.output_tokens | 全Agentの出力トークン総数 |
usage.total_tokens | トークン総数(入力 + 出力) |
usage.estimated_cost | 合計推定コスト(USD) |
ヒントとベストプラクティス
- はじめに
- パフォーマンス
- 予算制御
- Swarmを使うべきでない場合
context.force_swarm: trueを設定してSwarmWorkflowにルーティング- デフォルト設定から始め、結果に基づいて調整
- SSEイベントでLead Agentの決定とAgentの動作を監視
- セッション(
session_id)を使用してマルチターンのSwarm会話を実現 LEAD_DECISIONイベントに注目して調整ロジックを理解
トラブルシューティング
フォールバック動作
Swarm Workflowが失敗した場合(計画エラー、すべてのAgentが失敗など)、Shannonは標準のDAG/Supervisor Workflowルーティングに自動的にフォールバックします。再帰的な失敗を防ぐため、force_swarmフラグはコンテキストから除去されます。
次のステップ
Swarmコンセプト
Swarmアーキテクチャの詳細
ディープリサーチ
引用付きのマルチステージリサーチ
APIリファレンス
完全なAPIドキュメント