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

概要

Shannonは、タスク実行の可視性を提供するために、Server-Sent Events (SSE)を介してリアルタイムイベントを発信します。この文書では、プラットフォームによって実際に発信される33種類のイベント、その構造、および発生タイミングをカタログ化しています。 イベントは以下を提供します:
  • リアルタイムの進捗 - タスク実行をリアルタイムで追跡
  • デバッグの洞察 - LLMプロンプト、ツール呼び出し、エージェントの推論
  • コスト監視 - トークン使用量とコストをリアルタイムで追跡
  • マルチエージェントの調整 - チーム形成とコラボレーションの観察
  • エラー回復 - エラー処理と回復の試みを監視

イベント構造

すべてのイベントはこの基本構造に従います:
{
  "workflow_id": "wf-550e8400-e29b-41d4-a716-446655440000",
  "type": "AGENT_THINKING",
  "agent_id": "agent-001",
  "message": "タスクの複雑さを分析中...",
  "timestamp": "2024-10-27T10:00:00Z",
  "seq": 42,
  "stream_id": "stream-abc123",
  "payload": {}
}

基本フィールド

フィールド説明
workflow_idstringユニークなタスク/ワークフロー識別子
typestringイベントタイプ(下記のカタログを参照)
agent_idstringイベントを発信したエージェント
messagestring人間が読めるイベントの説明
timestampISO 8601イベントが発生した時刻
seqinteger順序付けのためのシーケンス番号
stream_idstring再接続用のストリーム識別子
payloadobjectイベント固有のペイロード(オプション;JSONではpayloadとしてシリアライズ)

イベントカテゴリ

イベントは論理的なカテゴリに整理されています:
  1. ワークフローイベント - タスクライフサイクル
  2. エージェントイベント - エージェントの実行
  3. ツールイベント - ツールの呼び出し
  4. パターンイベント - 認知パターンの実行
  5. チームイベント - マルチエージェントの調整
  6. LLMイベント - 言語モデルとのインタラクション
  7. 進捗イベント - タスクの進捗とステータス
  8. システムイベント - エラーとシステム状態

イベントタイプのクイックリファレンス

Shannonによって発信されるイベントタイプの権威あるリスト:
イベントタイプカテゴリ説明
WORKFLOW_STARTEDWorkflowタスクの実行が開始される
WORKFLOW_COMPLETEDWorkflowタスクが正常に完了する
WORKFLOW_PAUSINGWorkflow control一時停止が要求され、ワークフローが一時停止の準備をしている
WORKFLOW_PAUSEDWorkflow controlチェックポイントでワークフローが一時停止
WORKFLOW_RESUMEDWorkflow control一時停止後にワークフローが再開
WORKFLOW_CANCELLINGWorkflow controlキャンセルが要求され、ワークフローが終了の準備をしている
WORKFLOW_CANCELLEDWorkflow controlチェックポイントでワークフローがキャンセル
AGENT_STARTEDAgentエージェントが処理を開始
AGENT_THINKINGAgentエージェントの推論/計画
AGENT_COMPLETEDAgentエージェントが正常に完了
TOOL_INVOKEDToolツールが呼び出される
TOOL_OBSERVATIONToolエージェントがツールの結果を観察
TEAM_RECRUITEDTeamマルチエージェントチームが編成
TEAM_RETIREDTeamチームが解散
TEAM_STATUSTeamチーム調整の更新
DEPENDENCY_SATISFIEDTeam依存関係が解決
MESSAGE_SENTMessageエージェントがメッセージを送信
MESSAGE_RECEIVEDMessageエージェントがメッセージを受信
LLM_PROMPTLLMLLMに送信されたプロンプト
LLM_PARTIALLLM増分的なLLM出力
LLM_OUTPUTLLM最終的なLLM出力
PROGRESSProgress一般的な進捗更新
DATA_PROCESSINGProgressデータの処理/分析
WAITINGProgressリソースを待機中
ERROR_OCCURREDSystemエラーが発生
ERROR_RECOVERYSystemエラー回復の試み
APPROVAL_REQUESTEDSystem人間の承認が必要
APPROVAL_DECISIONSystem承認の決定がなされた
WORKSPACE_UPDATEDSystemメモリ/コンテキストが更新
ROLE_ASSIGNEDSystemエージェントの役割が割り当てられた
DELEGATIONSystemタスクが委任された
BUDGET_THRESHOLDSystem/Progressタスクの予算警告閾値に達した
STREAM_ENDStreamストリームの明示的な終了信号(このワークフローのイベントはこれ以上ありません)
合計: 33種類のイベントタイプ 注:WORKFLOW_FAILEDTASK_COMPLETEDTOOL_COMPLETEDTOOL_FAILED、およびBUDGET_UPDATEなどのイベントはストリーミングAPIによって発信されません。失敗はERROR_OCCURREDを介して表示され、完了はWORKFLOW_COMPLETEDで示されます。STREAM_ENDは、ストリーミングが終了した際のライフサイクル信号として発信されます。

ワークフローイベント

全体のタスクワークフローに関連するイベント。

WORKFLOW_STARTED

発信タイミング: タスクの実行が開始されたとき データ:
{
  "type": "WORKFLOW_STARTED",
  "message": "ワークフローが開始されました",
  "data": {
    "query": "Q4の売上データを分析",
    "mode": "STANDARD",
    "session_id": "sess-123",
    "estimated_complexity": 0.75
  }
}
フィールド:
  • query: 元のタスククエリ
  • mode: 実行モード (SIMPLE, STANDARD, COMPLEX)
  • session_id: セッション識別子
  • estimated_complexity: 複雑さスコア (0.0-1.0)

WORKFLOW_COMPLETED

発生: タスクが正常に完了したとき データ:
{
  "type": "WORKFLOW_COMPLETED",
  "message": "Workflow completed successfully",
  "data": {
    "result": "Analysis complete. Key findings: ...",
    "duration_ms": 45000,
    "total_tokens": 5420,
    "total_cost_usd": 0.0814,
    "agents_used": 3,
    "tools_invoked": 7
  }
}
フィールド:
  • result: 最終タスク結果
  • duration_ms: 総実行時間
  • total_tokens: 累積トークン使用量
  • total_cost_usd: 総コスト
  • agents_used: 呼び出されたエージェントの数
  • tools_invoked: 呼び出されたツールの数

選択された例

AGENT_THINKING

{
  "type": "AGENT_THINKING",
  "agent_id": "researcher",
  "message": "Analyzing data structure...",
  "timestamp": "2025-01-20T10:00:02Z"
}

TOOL_INVOKED / TOOL_OBSERVATION

{ "type": "TOOL_INVOKED", "message": "web_search: q=\"LLM caching\"" }
{ "type": "TOOL_OBSERVATION", "message": "web_search: 12 results" }

LLM_OUTPUT

{
  "type": "LLM_OUTPUT",
  "message": "Final summary of findings..."
}

ERROR_OCCURRED

{
  "type": "ERROR_OCCURRED",
  "message": "Provider rate limit exceeded",
  "data": { "error": "RATE_LIMIT", "retry_after": 30 }
}

APPROVAL_REQUESTED

{
  "type": "APPROVAL_REQUESTED",
  "message": "Delete temporary files older than 30 days?",
  "data": { "approval_id": "appr-456" }
}
一般的なエラータイプ:
  • BUDGET_EXCEEDED - コスト/トークン制限に達した
  • TIMEOUT - 実行タイムアウト
  • TOOL_EXECUTION_FAILED - ツールエラー
  • LLM_ERROR - LLMプロバイダーエラー
  • INVALID_INPUT - 不正なリクエスト

エージェントイベント

個々のエージェント実行に関連するイベント。

AGENT_STARTED

発生: エージェントが処理を開始したとき データ:
{
  "type": "AGENT_STARTED",
  "agent_id": "data-analyst",
  "message": "Agent started",
  "data": {
    "role": "data-analyst",
    "subtask": "Analyze revenue trends",
    "tools_available": ["csv_loader", "pandas", "matplotlib"]
  }
}

AGENT_THINKING

発生: エージェントが推論/処理中(最も頻繁なイベント) データ:
{
  "type": "AGENT_THINKING",
  "agent_id": "data-analyst",
  "message": "Analyzing data structure...",
  "data": {
    "thought": "I need to first load the CSV and examine column types",
    "next_action": "invoke_tool",
    "confidence": 0.85
  }
}
使用法: ユーザーへの進捗インジケーターとして表示

AGENT_COMPLETED

発生: エージェントがサブタスクを完了したとき データ:
{
  "type": "AGENT_COMPLETED",
  "agent_id": "data-analyst",
  "message": "Agent completed successfully",
  "data": {
    "result": "Revenue increased 15% YoY",
    "tokens_used": 1200,
    "cost_usd": 0.018,
    "duration_ms": 8000
  }
}

AGENT_FAILED

発生: エージェントがエラーに遭遇したとき データ:
{
  "type": "AGENT_FAILED",
  "agent_id": "data-analyst",
  "message": "Agent failed: Tool execution error",
  "data": {
    "error": "TOOL_EXECUTION_FAILED",
    "error_message": "CSV file not found",
    "recoverable": true
  }
}

ツールイベント

ツール呼び出しに関連するイベント。

TOOL_INVOKED

発生: ツールが呼び出されたとき データ:
{
  "type": "TOOL_INVOKED",
  "message": "Invoking tool: csv_loader",
  "data": {
    "tool_name": "csv_loader",
    "tool_args": {
      "file_path": "sales_q4.csv"
    },
    "timeout_seconds": 30
  }
}

TOOL_OBSERVATION

発生: エージェントがツールの結果を観察したとき データ:
{
  "type": "TOOL_OBSERVATION",
  "message": "Tool result: csv_loader",
  "data": {
    "tool_name": "csv_loader",
    "result": {
      "rows": 15000,
      "columns": 12,
      "sample": ["date", "product", "revenue", "..."]
    },
    "duration_ms": 450,
    "truncated": false
  }
}
フィールド:
  • tool_name: 呼び出されたツールの名前
  • result: ツール出力(構造化データまたはテキスト)
  • duration_ms: ツール実行時間
  • truncated: 結果が切り捨てられたかどうか(2000文字を超える場合はtrue)
注意: 大きなツール結果は、ストリーミング接続を圧倒しないようにUTF-8安全で2000文字に自動的に切り捨てられます。truncatedフィールドは、これが発生したかどうかを示します。完全な結果は常にタスク完了レスポンスで利用可能です。

パターンイベント

パターン選択および分解イベントは公開ストリーミングスキーマの一部ではなく、簡潔さのために省略されています。

チームイベント

複数のエージェントのチーム調整と管理。

TEAM_RECRUITED

発生: エージェントのチームが実行のために編成されたとき データ:
{
  "type": "TEAM_RECRUITED",
  "message": "Team recruited: 3 agents",
  "data": {
    "team_size": 3,
    "agents": [
      {
        "agent_id": "data-analyst",
        "role": "analyst",
        "capabilities": ["data_loading", "analysis"]
      },
      {
        "agent_id": "visualizer",
        "role": "visualization",
        "capabilities": ["charts", "graphs"]
      },
      {
        "agent_id": "writer",
        "role": "report_generation",
        "capabilities": ["summarization", "writing"]
      }
    ]
  }
}

TEAM_RETIRED

発生: タスク完了後にチームが解散されたとき データ:
{
  "type": "TEAM_RETIRED",
  "message": "Team retired after task completion",
  "data": {
    "team_size": 3,
    "duration_ms": 45000,
    "total_tokens": 8000,
    "reason": "task_completed"
  }
}

TEAM_STATUS

発生: マルチエージェントチームの調整に関する定期的な更新 データ:
{
  "type": "TEAM_STATUS",
  "message": "Team progress update",
  "data": {
    "active_agents": 2,
    "idle_agents": 1,
    "tasks_completed": 5,
    "tasks_remaining": 3,
    "coordination_mode": "parallel"
  }
}

DEPENDENCY_SATISFIED

発生: タスクの依存関係が解決され、実行が進められるとき データ:
{
  "type": "DEPENDENCY_SATISFIED",
  "message": "Dependencies satisfied for subtask-3",
  "data": {
    "subtask_id": "subtask-3",
    "satisfied_dependencies": ["subtask-1", "subtask-2"],
    "can_proceed": true
  }
}

メッセージイベント

エージェント間の通信。

MESSAGE_SENT

発生: エージェントが別のエージェントにメッセージを送信 データ:
{
  "type": "MESSAGE_SENT",
  "agent_id": "supervisor",
  "message": "Message sent to data-analyst",
  "data": {
    "to": "data-analyst",
    "content": "Please analyze revenue trends",
    "message_type": "DELEGATION"
  }
}

MESSAGE_RECEIVED

発生: エージェントがメッセージを受信 データ:
{
  "type": "MESSAGE_RECEIVED",
  "agent_id": "data-analyst",
  "message": "Message received from supervisor",
  "data": {
    "from": "supervisor",
    "content": "Please analyze revenue trends",
    "acknowledged": true
  }
}

LLMイベント

デバッグと監視のための言語モデルのインタラクションイベント。

LLM_PROMPT

発生: プロンプトがLLMに送信されたとき(プライバシーのためにサニタイズ済み) データ:
{
  "type": "LLM_PROMPT",
  "message": "Sending prompt to LLM",
  "data": {
    "model": "gpt-5",
    "prompt_length": 1200,
    "max_tokens": 2000,
    "temperature": 0.7,
    "sanitized_prompt": "Analyze the provided data..."
  }
}

LLM_PARTIAL

発生: ストリーミング中のLLM出力のインクリメンタルチャンク データ:
{
  "type": "LLM_PARTIAL",
  "message": "Received partial LLM output",
  "data": {
    "chunk": "Based on the analysis",
    "chunk_index": 5,
    "total_tokens_so_far": 50
  }
}

LLM_OUTPUT

発生: ステップの最終LLM出力 データ:
{
  "type": "LLM_OUTPUT",
  "message": "LLM output complete",
  "data": {
    "output": "Analysis complete. Revenue increased 15% YoY...",
    "model": "gpt-5",
    "provider": "openai",
    "usage": {
      "total_tokens": 350,
      "input_tokens": 200,
      "output_tokens": 150
    },
    "cost_usd": 0.0105,
    "duration_ms": 2000
  }
}
フィールド:
  • output: 完全なLLM応答テキスト
  • model: 使用されたモデル(正式名称)
  • provider: LLMプロバイダー(openai, anthropic, google, xaiなど)
  • usage: OpenAI互換の使用オブジェクトを含む:
    • total_tokens: 総トークン(入力 + 出力)
    • input_tokens: 入力/プロンプトトークン
    • output_tokens: 生成されたトークン
  • cost_usd: USDでの推定コスト
  • duration_ms: リクエストの所要時間(ミリ秒)
注意: 使用メタデータはOpenAIの標準フォーマットに従い、OpenAI、Anthropic、Google、Groq、xAI、OpenAI互換のエンドポイントを含むすべてのプロバイダーで利用可能です。usageオブジェクトの構造は、シームレスな統合のためにOpenAIのストリーミング応答フォーマットに一致します。

TOOL_OBSERVATION

発生: エージェントによるツール結果の観察 データ:
{
  "type": "TOOL_OBSERVATION",
  "message": "Agent observed tool result",
  "data": {
    "tool_name": "web_search",
    "observation": "Found 10 relevant results about AI trends",
    "relevance_score": 0.85
  }
}

進捗イベント

ユーザーのフィードバックのためのタスクの進捗とステータスの更新。

PROGRESS

発生: 実行中の一般的な進捗更新 データ:
{
  "type": "PROGRESS",
  "message": "Progress: 60% complete",
  "data": {
    "percentage": 60,
    "current_step": 3,
    "total_steps": 5,
    "current_task": "Generating visualizations"
  }
}

DATA_PROCESSING

発生: エージェントがデータを処理または分析中 データ:
{
  "type": "DATA_PROCESSING",
  "message": "Processing sales data",
  "data": {
    "operation": "data_analysis",
    "records_processed": 15000,
    "total_records": 15000,
    "processing_stage": "aggregation"
  }
}

WAITING

発生: エージェントがリソースまたは応答を待機中 データ:
{
  "type": "WAITING",
  "message": "Waiting for dependencies",
  "data": {
    "waiting_for": "subtask-2",
    "wait_reason": "dependency_not_satisfied",
    "estimated_wait_seconds": 10
  }
}

システムイベント

システムレベルのイベントとエラー。

ERROR_OCCURRED

発生: 実行中のシステムエラー データ:
{
  "type": "ERROR_OCCURRED",
  "message": "Database connection failed",
  "data": {
    "error_type": "DATABASE_ERROR",
    "error_message": "Connection timeout",
    "recoverable": true,
    "retry_count": 2,
    "max_retries": 3
  }
}

ERROR_RECOVERY

発生: システムがエラーから回復中 データ:
{
  "type": "ERROR_RECOVERY",
  "message": "データベース接続エラーから回復中",
  "data": {
    "error_type": "DATABASE_ERROR",
    "recovery_action": "retry_connection",
    "attempt": 2,
    "max_attempts": 3,
    "success": true
  }
}

APPROVAL_REQUESTED

発生: 続行するために人間の承認が必要 データ:
{
  "type": "APPROVAL_REQUESTED",
  "message": "ファイルシステムアクセスの承認を要求",
  "data": {
    "approval_id": "appr-123",
    "tool_name": "file_system",
    "operation": "write",
    "risk_level": "HIGH",
    "timeout_seconds": 7200,
    "details": {
      "file_path": "/data/critical.db",
      "action": "delete"
    }
  }
}

APPROVAL_DECISION

発生: 人間が承認の決定を下した データ:
{
  "type": "APPROVAL_DECISION",
  "message": "承認されました",
  "data": {
    "approval_id": "appr-123",
    "decision": "approved",
    "approved_by": "user-456",
    "timestamp": "2024-10-27T10:05:00Z",
    "comments": "アクションが必要であることを確認"
  }
}
決定値:
  • approved - アクションが続行可能
  • denied - アクションがブロックされました
  • timeout - タイムアウト期間内に決定が下されなかった

WORKSPACE_UPDATED

発生: 作業メモリ/コンテキストが更新されました データ:
{
  "type": "WORKSPACE_UPDATED",
  "message": "ワークスペースが更新されました",
  "data": {
    "key": "loaded_datasets",
    "value": ["sales_q4.csv"],
    "action": "ADD"
  }
}

ROLE_ASSIGNED

発生: 実行中にエージェントの役割が割り当てられました データ:
{
  "type": "ROLE_ASSIGNED",
  "agent_id": "agent-002",
  "message": "役割が割り当てられました: data-analyst",
  "data": {
    "role": "data-analyst",
    "capabilities": ["data_loading", "analysis", "visualization"],
    "tools": ["csv_loader", "pandas", "matplotlib"]
  }
}

DELEGATION

発生: タスクが別のエージェントに委任されました データ:
{
  "type": "DELEGATION",
  "agent_id": "supervisor",
  "message": "data-analystに委任されました",
  "data": {
    "to_agent": "data-analyst",
    "task": "収益トレンドの分析",
    "priority": "HIGH"
  }
}

BUDGET_THRESHOLD

発生: トークン予算が警告閾値に達しました(通常は制限の80%) データ:
{
  "type": "BUDGET_THRESHOLD",
  "message": "予算閾値に達しました: 80%",
  "data": {
    "threshold_percentage": 80,
    "tokens_used": 8000,
    "tokens_limit": 10000,
    "tokens_remaining": 2000,
    "cost_usd": 0.24,
    "estimated_cost_at_limit": 0.30
  }
}
フィールド:
  • threshold_percentage: 警告閾値(例: 80)
  • tokens_used: これまでに消費されたトークンの累計
  • tokens_limit: タスクに対して許可される最大トークン数
  • tokens_remaining: 制限前に残っているトークン
  • cost_usd: 現在のコスト(USD)
  • estimated_cost_at_limit: 制限に達した場合の予測コスト
使用法: このイベントを監視して、ハード予算制限に達する前にユーザーに警告し、優雅な劣化や早期終了の決定を可能にします。

イベントの順序

イベントは厳密に順序付けられています(シーケンス番号 seq による):
{"seq": 1, "type": "WORKFLOW_STARTED"}
{"seq": 2, "type": "AGENT_STARTED"}
{"seq": 3, "type": "AGENT_THINKING"}
{"seq": 4, "type": "TOOL_INVOKED"}
{"seq": 5, "type": "LLM_OUTPUT"}
{"seq": 6, "type": "WORKFLOW_COMPLETED"}
プロパティ:
  • シーケンス番号は単調増加
  • シーケンスにギャップなし(1からNまでのすべての番号)
  • 同じワークフローからのイベントは常に正しく順序付けられています

一般的なイベントフロー(簡略化)

1. WORKFLOW_STARTED
2. AGENT_STARTED
3. AGENT_THINKING
4. TOOL_INVOKED (オプション)
5. LLM_OUTPUT (最終回答)
6. WORKFLOW_COMPLETED

イベントの永続性

イベントは以下に保存されます:
  • PostgreSQL: 永続的なイベントログ
  • Redis: 最近のイベント(ホットキャッシュ)
  • リアルタイム: SSEストリーム
過去のイベントの取得:
# タスクのすべてのイベントを取得
GET /api/v1/tasks/{task_id}/events?limit=1000

イベントの信頼性と保証

順序保証

Shannonは単一のワークフロー内で厳密な順序を提供します:
  • イベントはシーケンシャルに番号付けされています(seqフィールド)
  • シーケンス番号にギャップなし(1, 2, 3, …)
  • 同じワークフローからのイベントは常に順序通りに到着します
  • 異なるワークフローからのイベントは交互に到着する可能性があります

配信保証

  • 少なくとも1回の配信: イベントは複数回配信される可能性があります(重複排除には seq を使用)
  • イベントの永続性: すべてのイベントはPostgreSQLの event_logs テーブルに保存されます
  • ホットキャッシュ: 最近のイベントはRedisにキャッシュされ、迅速に取得可能
  • 過去のアクセス: REST APIを介して過去のイベントをクエリ可能

ストリーム再接続

SSE接続が切断された場合:
# 再接続し、最後のシーケンス番号から再開
last_seq = 42  # 最後に受信したイベント
for event in client.stream_events(workflow_id, from_seq=last_seq + 1):
    process_event(event)

イベント保持

ストレージ保持期間目的イベントタイプ
Redis24時間リアルタイムストリーミングすべてのイベント
PostgreSQL90日(デフォルト)歴史的クエリ重要なイベントのみ*
アーカイブ1年以上(オプション)長期監査設定可能
PostgreSQLの選択的永続性: データベースのパフォーマンスを最適化するために、重要なイベントのみがPostgreSQLに永続化されます。これには、WORKFLOW_COMPLETEDAGENT_COMPLETEDTOOL_INVOKEDLLM_OUTPUT、および ERROR_OCCURRED が含まれます。LLM_PARTIALHEARTBEAT、および AGENT_THINKING のような一時的なイベントはデータベースへの書き込みから除外され(書き込み負荷を約92%削減)、リアルタイムのSSEストリーミングとRedisキャッシュを介して完全に利用可能です。 イベントストレージの詳細については、Database Schemaを参照してください。

関連トピック