メインコンテンツへスキップ

​
概要

SwarmワークフローはタスクコンテキストでSwarmを設定する force_swarm: true によってトリガーされます。他のすべてのワークフローと同じ POST /api/v1/tasks エンドポイントを使用します——個別のエンドポイントは不要です。 Swarmモードはクエリをサブタスクに分解し、Agent間メッセージングで並列に動作する永続的なAgentを生成し、結果を統一されたレスポンスに統合します。

​
Swarmタスクの送信

​
エンドポイント

POST http://localhost:8080/api/v1/tasks

​
リクエストボディ

{
  "query": "Your complex multi-faceted task",
  "session_id": "optional-session-id",
  "context": {
    "force_swarm": true
  }
}

​
Swarm固有のコンテキストパラメータ

パラメータタイプデフォルト説明
force_swarmbooleanfalseSwarmワークフローをトリガーするために必須
model_tierstring（自動）Agent実行のモデルティア：small、medium、large
すべての標準タスクパラメータ（session_id、mode、model_tier、model_override、provider_override）はSwarmタスクで使用できます。
force_swarmフラグはcontextオブジェクト内に設定する必要があり、トップレベルのパラメータではありません。また、サーバー設定でSwarmが有効（features.yamlのworkflows.swarm.enabled: true）である必要があります。

​
例：基本的なSwarmタスク

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",
    "context": {
      "force_swarm": true
    }
  }'

​
レスポンス

{
  "task_id": "task-abc123...",
  "status": "STATUS_CODE_OK",
  "message": "Task submitted successfully",
  "created_at": "2025-11-10T10:00:00Z"
}
ヘッダー：
  • X-Workflow-ID：Temporalワークフロー識別子（task_idと同一）
  • X-Session-ID：セッション識別子

​
送信 + ストリーミング

統合エンドポイントを使用して、送信とストリームURLの取得を一回で行います： 
POST http://localhost:8080/api/v1/tasks/stream

curl -s -X POST http://localhost:8080/api/v1/tasks/stream \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Analyze competitive landscape of major cloud AI platforms",
    "context": { "force_swarm": true }
  }' | jq
レスポンス（201 Created）： 
{
  "workflow_id": "task-def456...",
  "task_id": "task-def456...",
  "stream_url": "/api/v1/stream/sse?workflow_id=task-def456..."
}

​
Swarm進捗の監視

​
SSEイベントストリーム

GET http://localhost:8080/api/v1/stream/sse?workflow_id={workflow_id}

​
Swarm固有のイベント

イベントタイプagent_id説明
WORKFLOW_STARTEDswarm-supervisorSwarmワークフローが初期化された
PROGRESS（計画）swarm-supervisorタスク分解が進行中
PROGRESS（生成）swarm-supervisorAgentの割り当て中
PROGRESS（監視）swarm-supervisorAgentが並列で作業中
AGENT_STARTEDAgent名（例：takao）個別のAgentが実行を開始
PROGRESS（イテレーション）Agent名Agentのイテレーション進捗
AGENT_COMPLETEDAgent名個別のAgentが完了
PROGRESS（統合）swarm-supervisorすべてのAgentの結果を統合中
WORKFLOW_COMPLETEDswarm-supervisor最終統合完了

​
SSE出力例

data: {"type":"WORKFLOW_STARTED","agent_id":"swarm-supervisor","message":"Assigning a team of agents","timestamp":"..."}

data: {"type":"PROGRESS","agent_id":"swarm-supervisor","message":"Planning approach","timestamp":"..."}

data: {"type":"PROGRESS","agent_id":"swarm-supervisor","message":"Assigning 3 agents","timestamp":"..."}

data: {"type":"AGENT_STARTED","agent_id":"takao","message":"Agent takao started","timestamp":"..."}

data: {"type":"PROGRESS","agent_id":"takao","message":"Agent takao progress: iteration 1/25, action: tool_call","timestamp":"..."}

data: {"type":"AGENT_COMPLETED","agent_id":"takao","message":"Agent takao completed","timestamp":"..."}

data: {"type":"PROGRESS","agent_id":"swarm-supervisor","message":"Combining findings from 3 agents","timestamp":"..."}

data: {"type":"WORKFLOW_COMPLETED","agent_id":"swarm-supervisor","message":"All done","timestamp":"..."}

​
タスクステータスレスポンス

GET http://localhost:8080/api/v1/tasks/{task_id}

​
Swarmメタデータ

Swarmワークフローが完了すると、ステータスレスポンスにSwarm固有のメタデータが含まれます： 
{
  "task_id": "task-abc123...",
  "status": "TASK_STATUS_COMPLETED",
  "result": "## AI Chip Market Comparison\n\n...",
  "metadata": {
    "workflow_type": "swarm",
    "total_agents": 3,
    "agents": [
      {
        "agent_id": "takao",
        "iterations": 8,
        "tokens": 14200,
        "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"
      }
    ]
  },
  "usage": {
    "total_tokens": 35200,
    "estimated_cost": 0.042
  }
}

​
メタデータフィールド

フィールドタイプ説明
metadata.workflow_typestringSwarmワークフローでは常に"swarm"
metadata.total_agentsinteger参加したAgent総数（初期 + 動的）
metadata.agentsarrayAgentごとの実行サマリー
metadata.agents[].agent_idstring決定論的なAgent名（日本の駅名）
metadata.agents[].iterationsinteger完了した推論-行動サイクル数
metadata.agents[].tokensinteger消費された総トークン数
metadata.agents[].successbooleanAgentが正常に完了したかどうか
metadata.agents[].modelstring使用されたLLMモデル

​
サーバー設定

Swarmパラメータはconfig/features.yamlのworkflows.swarmで設定されます： 
workflows:
  swarm:
    enabled: true                     # Swarmルーティングの有効/無効
    max_agents: 10                    # Agent総数の上限（初期 + 動的）
    max_iterations_per_agent: 25      # Agentごとの推論-行動ループの最大回数
    agent_timeout_seconds: 600        # Agentごとのウォールクロックタイムアウト
    max_messages_per_agent: 20        # AgentごとのP2Pメッセージ上限
    workspace_snippet_chars: 800      # プロンプト内のワークスペースエントリの最大文字数
    workspace_max_entries: 5          # トピックごとの最近のエントリ表示数
パラメータデフォルト説明
enabledtrueforce_swarmを機能させるにはtrueが必要
max_agents10動的に生成されたヘルパーを含む総上限
max_iterations_per_agent25Agentごとのイテレーション制限
agent_timeout_seconds600Agentごと10分のタイムアウト
max_messages_per_agent20P2Pメッセージの氾濫を防止
workspace_snippet_chars800ワークスペースコンテキストからのトークン使用量を制御
workspace_max_entries5Agentプロンプト内のトピックごとのワークスペースエントリを制限

​
エラーハンドリングとフォールバック

​
部分的な失敗

一部のAgentが失敗しても少なくとも1つが成功した場合、Swarmワークフローは成功したAgentの出力を使用して結果を生成します。 すべてのAgentが失敗した場合、レスポンスにエラーが含まれます： 
{
  "task_id": "task-xyz...",
  "status": "TASK_STATUS_COMPLETED",
  "result": "",
  "error": "All 3 agents failed — no results to synthesize",
  "metadata": {
    "workflow_type": "swarm",
    "total_agents": 3,
    "agents": [
      {"agent_id": "takao", "success": false, "error": "consecutive tool errors"},
      {"agent_id": "mitaka", "success": false, "error": "LLM step failed at iteration 2"},
      {"agent_id": "kichijoji", "success": false, "error": "consecutive tool errors"}
    ]
  }
}

​
自動フォールバック

Swarmワークフロー全体が失敗した場合（分解エラー、すべてのAgentが失敗など）、Shannonは標準のワークフロールーティング（DAGまたはSupervisor）に自動的にフォールバックします。再帰的な失敗を防ぐため、force_swarmフラグはコンテキストから除去されます。

​
関連エンドポイント

タスク送信

POST /api/v1/tasks（完全なリファレンス）

ステータス取得

GET /api/v1/tasks/

ストリームイベント

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

タスクキャンセル

POST /api/v1/tasks//cancel