Swarmマルチエージェントワークフロー
このチュートリアルでは、ShannonのSwarmWorkflowを使用して、Agent間メッセージングと共有ワークスペースを備えた永続的で協調するAgentをデプロイする方法を紹介します。学べること
- APIとPython SDKでSwarmタスクを送信する方法
- 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":"Assigning a team of agents"}
data: {"type":"PROGRESS","agent_id":"swarm-supervisor","message":"Planning approach"}
data: {"type":"PROGRESS","agent_id":"swarm-supervisor","message":"Assigning 3 agents"}
data: {"type":"AGENT_STARTED","agent_id":"takao","message":"Agent takao started"}
data: {"type":"AGENT_STARTED","agent_id":"mitaka","message":"Agent mitaka started"}
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":"AGENT_COMPLETED","agent_id":"mitaka","message":"Agent mitaka completed"}
data: {"type":"AGENT_COMPLETED","agent_id":"kichijoji","message":"Agent kichijoji completed"}
data: {"type":"PROGRESS","agent_id":"swarm-supervisor","message":"Combining findings from 3 agents"}
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,
"agents": [
{"agent_id": "takao", "iterations": 8, "tokens": 12400, "success": true, "model": "gpt-5-mini-2025-08-07"},
{"agent_id": "mitaka", "iterations": 6, "tokens": 9800, "success": true, "model": "gpt-5-mini-2025-08-07"},
{"agent_id": "kichijoji", "iterations": 7, "tokens": 11200, "success": true, "model": "gpt-5-mini-2025-08-07"}
]
}
}
送信 + ストリーミングを一回で
フロントエンドアプリケーションでは、送信とストリーミングを統合するエンドポイントを使用します:Python SDK
基本的な使用方法
ストリーミング付き
カスタムコンテキスト
Agentの協調方法
チームロスター
各AgentはすべてのAgentとその担当を示すチームロスターを受け取ります。これにより、特定の情報について誰に連絡すべきかを把握できます:発見の公開
Agentは共有ワークスペースを通じて発見を共有します。これらはすべてのAgentのプロンプトコンテキストに表示されます:ダイレクトメッセージの送信
Agentは特定のチームメイトにダイレクトメッセージを送信できます:ヘルプの要請
Agentが追加サポートを必要とする場合、スーパーバイザーにヘルプを要請します:設定
features.yaml
設定パラメータ
| パラメータ | デフォルト | 範囲 | 説明 |
|---|---|---|---|
enabled | true | true/false | Swarm Workflowの有効/無効 |
max_agents | 10 | 1-50 | 動的に生成されたヘルパーを含むAgent総数の上限 |
max_iterations_per_agent | 25 | 1-100 | Agentごとの推論-行動サイクルの最大回数 |
agent_timeout_seconds | 600 | 60-3600 | Agentごとのウォールクロックタイムアウト |
max_messages_per_agent | 20 | 1-100 | Agentが送信できるP2Pメッセージの上限 |
workspace_snippet_chars | 800 | 100-4000 | Agentプロンプト内のワークスペースエントリの切り詰め制限 |
workspace_max_entries | 5 | 1-20 | トピックごとに表示される最近のワークスペースエントリ数 |
実際のユースケース
市場調査
Agentを異なる市場や競合の調査に並列で割り当て、統一レポートに統合します。
技術比較
各Agentが異なるフレームワーク、ライブラリ、アーキテクチャを評価し、発見をリアルタイムで共有します。
マルチリージョン分析
Agentが異なる地域を同時に調査し、発見をクロスリージョンで共有します。
文献レビュー
Agentが研究テーマの異なる側面を探索し、ワークスペースでソースと主要な発見を共有します。
例: 技術フレームワーク比較
例: 包括的な業界分析
レスポンスメタデータの理解
Swarm WorkflowはAgentごとの詳細を含むメタデータを返します:| フィールド | 説明 |
|---|---|
workflow_type | Swarm Workflowでは常に"swarm" |
total_agents | 参加したAgent数 |
agents[].agent_id | Agentの一意の名前 |
agents[].iterations | 完了した推論-行動サイクル数 |
agents[].tokens | このAgentが消費した総トークン数 |
agents[].success | Agentが正常に完了したかどうか |
agents[].model | このAgentが使用したLLMモデル |
ヒントとベストプラクティス
- はじめに
- パフォーマンス
- Swarmを使うべきでない場合
context.force_swarm: trueを設定してSwarmWorkflowにルーティング- デフォルト設定から始め、結果に基づいて調整
- SSEイベントでAgentの動作を監視
- セッション(
session_id)を使用してマルチターンのSwarm会話を実現
トラブルシューティング
フォールバック動作
Swarm Workflowが失敗した場合(分解エラー、すべてのAgentが失敗など)、Shannonは標準のDAG/Supervisor Workflowルーティングに自動的にフォールバックします。再帰的な失敗を防ぐため、force_swarmフラグはコンテキストから除去されます。