Swarm Workflow API

概要

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_swarm`	boolean	`false`	Swarmワークフローをトリガーするために必須
`model_tier`	string	（自動）	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
    }
  }'

from shannon import ShannonClient

client = ShannonClient(base_url="http://localhost:8080")
handle = client.submit_task(
    "Compare AI chip markets across US, Japan, and South Korea",
    force_swarm=True,
    session_id="swarm-demo",
)

import httpx

response = httpx.post(
    "http://localhost:8080/api/v1/tasks",
    json={
        "query": "Compare AI chip markets across US, Japan, and South Korea",
        "session_id": "swarm-demo",
        "context": {"force_swarm": True},
    },
)
task = response.json()
print(f"Task ID: {task['task_id']}")

レスポンス

{
  "task_id": "task-abc123...",
  "status": "STATUS_CODE_OK",
  "message": "Task submitted successfully. Session: swarm-demo",
  "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

from shannon import ShannonClient

client = ShannonClient(base_url="http://localhost:8080")
handle, stream_url = client.submit_and_stream(
    "Analyze competitive landscape of major cloud AI platforms",
    force_swarm=True,
)
print(f"Stream URL: {stream_url}")

レスポンス（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_STARTED`	`swarm-supervisor`	Swarmワークフローが初期化された
`PROGRESS`（計画）	`swarm-supervisor`	タスク分解が進行中
`LEAD_DECISION`	`swarm-lead`	Leadが調整決定を行った（生成、割り当て、修正など）
`TASKLIST_UPDATED`	`swarm-lead`	タスク依存グラフが変更された
`TEAM_STATUS`	`swarm-lead`	チーム構成が変更された（Agentの生成または停止）
`AGENT_STARTED`	Agent名（例：`takao`）	個別のAgentが実行を開始
`PROGRESS`（イテレーション）	Agent名	Agentのイテレーション進捗
`AGENT_COMPLETED`	Agent名	個別のAgentが完了
`PROGRESS`（統合）	`swarm-supervisor`	すべてのAgentの結果を統合中
`WORKFLOW_COMPLETED`	`swarm-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...",
  "workflow_id": "task-abc123...",
  "status": "TASK_STATUS_COMPLETED",
  "result": "## AI Chip Market Comparison\n\n...",
  "query": "Compare AI chip markets across US, Japan, and South Korea",
  "session_id": "swarm-demo",
  "mode": "standard",
  "model_used": "claude-haiku-4-5-20251001",
  "provider": "anthropic",
  "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
  }
}

メタデータフィールド

フィールド	タイプ	説明
`metadata.workflow_type`	string	Swarmワークフローでは常に`"swarm"`
`metadata.total_agents`	integer	参加したAgent総数（初期 + 動的）
`metadata.total_tokens`	integer	すべてのAgentで消費された総トークン数
`metadata.model_breakdown`	array	モデルごとの実行サマリー
`metadata.model_breakdown[].model`	string	モデル識別子
`metadata.model_breakdown[].provider`	string	プロバイダー名
`metadata.model_breakdown[].executions`	integer	このモデルでのLLM呼び出し回数
`metadata.model_breakdown[].tokens`	integer	このモデルで消費されたトークン数
`metadata.model_breakdown[].cost_usd`	number	推定コスト（USD）

サーバー設定

Swarmパラメータはconfig/features.yamlのworkflows.swarmで設定されます：

workflows:
  swarm:
    enabled: true                     # Swarmルーティングの有効/無効
    max_agents: 10                    # Agent総数の上限（初期 + 動的）
    max_iterations_per_agent: 25      # Agentごとの推論-行動ループの最大回数
    agent_timeout_seconds: 1800       # Agentごとのウォールクロックタイムアウト（30分）
    max_messages_per_agent: 20        # AgentごとのP2Pメッセージ上限
    workspace_snippet_chars: 800      # プロンプト内のワークスペースエントリの最大文字数
    workspace_max_entries: 5          # トピックごとの最近のエントリ表示数
    max_total_llm_calls: 200          # グローバルLLM呼び出し予算
    max_total_tokens: 1000000         # グローバルトークン予算（1M）
    max_wall_clock_minutes: 30        # 最大ウォールクロック時間

パラメータ	デフォルト	説明
`enabled`	`true`	`force_swarm`を機能させるには`true`が必要
`max_agents`	`10`	動的に生成されたヘルパーを含む総上限
`max_iterations_per_agent`	`25`	Agentごとのイテレーション制限
`agent_timeout_seconds`	`1800`	Agentごと30分のタイムアウト
`max_messages_per_agent`	`20`	P2Pメッセージの氾濫を防止
`workspace_snippet_chars`	`800`	ワークスペースコンテキストからのトークン使用量を制御
`workspace_max_entries`	`5`	Agentプロンプト内のトピックごとのワークスペースエントリを制限
`max_total_llm_calls`	`200`	すべてのAgentにわたるLLM呼び出しの最大数
`max_total_tokens`	`1000000`	すべてのAgentにわたる最大トークン消費量
`max_wall_clock_minutes`	`30`	Swarm全体の最大ウォールクロック時間

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

部分的な失敗

一部の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,
    "total_tokens": 45200,
    "cost_usd": 0.058
  }
}

自動フォールバック

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

タスク送信

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

ステータス取得

GET /api/v1/tasks/

ストリームイベント

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

タスクキャンセル

POST /api/v1/tasks//cancel

はじめに

タスク

ストリーミング

エージェント

セッション

Swarm

スキル

スケジュール

HITLレビュー

Channels

Tools

Daemon WebSocket

リファレンス

Swarm Workflow API

概要

Swarmタスクの送信

エンドポイント

リクエストボディ

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

例：基本的なSwarmタスク

レスポンス

送信 + ストリーミング

Swarm進捗の監視

SSEイベントストリーム

Swarm固有のイベント

SSE出力例

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

Swarmメタデータ

メタデータフィールド

サーバー設定

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

部分的な失敗

自動フォールバック

関連エンドポイント

タスク送信

ステータス取得

ストリームイベント

タスクキャンセル

​概要

​Swarmタスクの送信

​エンドポイント

​リクエストボディ

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

​例：基本的なSwarmタスク

​レスポンス

​送信 + ストリーミング

​Swarm進捗の監視

​SSEイベントストリーム

​Swarm固有のイベント

​SSE出力例

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

​Swarmメタデータ

​メタデータフィールド

​サーバー設定

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

​部分的な失敗

​自動フォールバック

​関連エンドポイント

タスク送信

ステータス取得

ストリームイベント

タスクキャンセル

概要

Swarmタスクの送信

エンドポイント

リクエストボディ

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

例：基本的なSwarmタスク

レスポンス

送信 + ストリーミング

Swarm進捗の監視

SSEイベントストリーム

Swarm固有のイベント

SSE出力例

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

Swarmメタデータ

メタデータフィールド

サーバー設定

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

部分的な失敗

自動フォールバック

関連エンドポイント