概要
Shannonは、タスク実行の可視性を提供するために、Server-Sent Events (SSE)を介してリアルタイムイベントを発信します。この文書では、プラットフォームによって実際に発信される33種類のイベント、その構造、および発生タイミングをカタログ化しています。 イベントは以下を提供します:- リアルタイムの進捗 - タスク実行をリアルタイムで追跡
- デバッグの洞察 - LLMプロンプト、ツール呼び出し、エージェントの推論
- コスト監視 - トークン使用量とコストをリアルタイムで追跡
- マルチエージェントの調整 - チーム形成とコラボレーションの観察
- エラー回復 - エラー処理と回復の試みを監視
イベント構造
すべてのイベントはこの基本構造に従います:基本フィールド
| フィールド | 型 | 説明 |
|---|---|---|
workflow_id | string | ユニークなタスク/ワークフロー識別子 |
type | string | イベントタイプ(下記のカタログを参照) |
agent_id | string | イベントを発信したエージェント |
message | string | 人間が読めるイベントの説明 |
timestamp | ISO 8601 | イベントが発生した時刻 |
seq | integer | 順序付けのためのシーケンス番号 |
stream_id | string | 再接続用のストリーム識別子 |
payload | object | イベント固有のペイロード(オプション;JSONではpayloadとしてシリアライズ) |
イベントカテゴリ
イベントは論理的なカテゴリに整理されています:- ワークフローイベント - タスクライフサイクル
- エージェントイベント - エージェントの実行
- ツールイベント - ツールの呼び出し
- パターンイベント - 認知パターンの実行
- チームイベント - マルチエージェントの調整
- LLMイベント - 言語モデルとのインタラクション
- 進捗イベント - タスクの進捗とステータス
- システムイベント - エラーとシステム状態
イベントタイプのクイックリファレンス
Shannonによって発信されるイベントタイプの権威あるリスト:| イベントタイプ | カテゴリ | 説明 |
|---|---|---|
WORKFLOW_STARTED | Workflow | タスクの実行が開始される |
WORKFLOW_COMPLETED | Workflow | タスクが正常に完了する |
WORKFLOW_PAUSING | Workflow control | 一時停止が要求され、ワークフローが一時停止の準備をしている |
WORKFLOW_PAUSED | Workflow control | チェックポイントでワークフローが一時停止 |
WORKFLOW_RESUMED | Workflow control | 一時停止後にワークフローが再開 |
WORKFLOW_CANCELLING | Workflow control | キャンセルが要求され、ワークフローが終了の準備をしている |
WORKFLOW_CANCELLED | Workflow control | チェックポイントでワークフローがキャンセル |
AGENT_STARTED | Agent | エージェントが処理を開始 |
AGENT_THINKING | Agent | エージェントの推論/計画 |
AGENT_COMPLETED | Agent | エージェントが正常に完了 |
TOOL_INVOKED | Tool | ツールが呼び出される |
TOOL_OBSERVATION | Tool | エージェントがツールの結果を観察 |
TEAM_RECRUITED | Team | マルチエージェントチームが編成 |
TEAM_RETIRED | Team | チームが解散 |
TEAM_STATUS | Team | チーム調整の更新 |
DEPENDENCY_SATISFIED | Team | 依存関係が解決 |
MESSAGE_SENT | Message | エージェントがメッセージを送信 |
MESSAGE_RECEIVED | Message | エージェントがメッセージを受信 |
LLM_PROMPT | LLM | LLMに送信されたプロンプト |
LLM_PARTIAL | LLM | 増分的なLLM出力 |
LLM_OUTPUT | LLM | 最終的なLLM出力 |
PROGRESS | Progress | 一般的な進捗更新 |
DATA_PROCESSING | Progress | データの処理/分析 |
WAITING | Progress | リソースを待機中 |
ERROR_OCCURRED | System | エラーが発生 |
ERROR_RECOVERY | System | エラー回復の試み |
APPROVAL_REQUESTED | System | 人間の承認が必要 |
APPROVAL_DECISION | System | 承認の決定がなされた |
WORKSPACE_UPDATED | System | メモリ/コンテキストが更新 |
ROLE_ASSIGNED | System | エージェントの役割が割り当てられた |
DELEGATION | System | タスクが委任された |
BUDGET_THRESHOLD | System/Progress | タスクの予算警告閾値に達した |
STREAM_END | Stream | ストリームの明示的な終了信号(このワークフローのイベントはこれ以上ありません) |
WORKFLOW_FAILED、TASK_COMPLETED、TOOL_COMPLETED、TOOL_FAILED、およびBUDGET_UPDATEなどのイベントはストリーミングAPIによって発信されません。失敗はERROR_OCCURREDを介して表示され、完了はWORKFLOW_COMPLETEDで示されます。STREAM_ENDは、ストリーミングが終了した際のライフサイクル信号として発信されます。
ワークフローイベント
全体のタスクワークフローに関連するイベント。WORKFLOW_STARTED
発信タイミング: タスクの実行が開始されたとき データ:query: 元のタスククエリmode: 実行モード (SIMPLE, STANDARD, COMPLEX)session_id: セッション識別子estimated_complexity: 複雑さスコア (0.0-1.0)
WORKFLOW_COMPLETED
発生: タスクが正常に完了したとき データ:result: 最終タスク結果duration_ms: 総実行時間total_tokens: 累積トークン使用量total_cost_usd: 総コストagents_used: 呼び出されたエージェントの数tools_invoked: 呼び出されたツールの数
選択された例
AGENT_THINKING
TOOL_INVOKED / TOOL_OBSERVATION
LLM_OUTPUT
ERROR_OCCURRED
APPROVAL_REQUESTED
BUDGET_EXCEEDED- コスト/トークン制限に達したTIMEOUT- 実行タイムアウトTOOL_EXECUTION_FAILED- ツールエラーLLM_ERROR- LLMプロバイダーエラーINVALID_INPUT- 不正なリクエスト
エージェントイベント
個々のエージェント実行に関連するイベント。AGENT_STARTED
発生: エージェントが処理を開始したとき データ:AGENT_THINKING
発生: エージェントが推論/処理中(最も頻繁なイベント) データ:AGENT_COMPLETED
発生: エージェントがサブタスクを完了したとき データ:AGENT_FAILED
発生: エージェントがエラーに遭遇したとき データ:ツールイベント
ツール呼び出しに関連するイベント。TOOL_INVOKED
発生: ツールが呼び出されたとき データ:TOOL_OBSERVATION
発生: エージェントがツールの結果を観察したとき データ:tool_name: 呼び出されたツールの名前result: ツール出力(構造化データまたはテキスト)duration_ms: ツール実行時間truncated: 結果が切り捨てられたかどうか(2000文字を超える場合はtrue)
truncatedフィールドは、これが発生したかどうかを示します。完全な結果は常にタスク完了レスポンスで利用可能です。
パターンイベント
パターン選択および分解イベントは公開ストリーミングスキーマの一部ではなく、簡潔さのために省略されています。チームイベント
複数のエージェントのチーム調整と管理。TEAM_RECRUITED
発生: エージェントのチームが実行のために編成されたとき データ:TEAM_RETIRED
発生: タスク完了後にチームが解散されたとき データ:TEAM_STATUS
発生: マルチエージェントチームの調整に関する定期的な更新 データ:DEPENDENCY_SATISFIED
発生: タスクの依存関係が解決され、実行が進められるとき データ:メッセージイベント
エージェント間の通信。MESSAGE_SENT
発生: エージェントが別のエージェントにメッセージを送信 データ:MESSAGE_RECEIVED
発生: エージェントがメッセージを受信 データ:LLMイベント
デバッグと監視のための言語モデルのインタラクションイベント。LLM_PROMPT
発生: プロンプトがLLMに送信されたとき(プライバシーのためにサニタイズ済み) データ:LLM_PARTIAL
発生: ストリーミング中のLLM出力のインクリメンタルチャンク データ:LLM_OUTPUT
発生: ステップの最終LLM出力 データ:output: 完全なLLM応答テキストmodel: 使用されたモデル(正式名称)provider: LLMプロバイダー(openai, anthropic, google, xaiなど)usage: OpenAI互換の使用オブジェクトを含む:total_tokens: 総トークン(入力 + 出力)input_tokens: 入力/プロンプトトークンoutput_tokens: 生成されたトークン
cost_usd: USDでの推定コストduration_ms: リクエストの所要時間(ミリ秒)
usageオブジェクトの構造は、シームレスな統合のためにOpenAIのストリーミング応答フォーマットに一致します。
TOOL_OBSERVATION
発生: エージェントによるツール結果の観察 データ:進捗イベント
ユーザーのフィードバックのためのタスクの進捗とステータスの更新。PROGRESS
発生: 実行中の一般的な進捗更新 データ:DATA_PROCESSING
発生: エージェントがデータを処理または分析中 データ:WAITING
発生: エージェントがリソースまたは応答を待機中 データ:システムイベント
システムレベルのイベントとエラー。ERROR_OCCURRED
発生: 実行中のシステムエラー データ:ERROR_RECOVERY
発生: システムがエラーから回復中 データ:APPROVAL_REQUESTED
発生: 続行するために人間の承認が必要 データ:APPROVAL_DECISION
発生: 人間が承認の決定を下した データ:approved- アクションが続行可能denied- アクションがブロックされましたtimeout- タイムアウト期間内に決定が下されなかった
WORKSPACE_UPDATED
発生: 作業メモリ/コンテキストが更新されました データ:ROLE_ASSIGNED
発生: 実行中にエージェントの役割が割り当てられました データ:DELEGATION
発生: タスクが別のエージェントに委任されました データ:BUDGET_THRESHOLD
発生: トークン予算が警告閾値に達しました(通常は制限の80%) データ:threshold_percentage: 警告閾値(例: 80)tokens_used: これまでに消費されたトークンの累計tokens_limit: タスクに対して許可される最大トークン数tokens_remaining: 制限前に残っているトークンcost_usd: 現在のコスト(USD)estimated_cost_at_limit: 制限に達した場合の予測コスト
イベントの順序
イベントは厳密に順序付けられています(シーケンス番号seq による):
- シーケンス番号は単調増加
- シーケンスにギャップなし(1からNまでのすべての番号)
- 同じワークフローからのイベントは常に正しく順序付けられています
一般的なイベントフロー(簡略化)
イベントの永続性
イベントは以下に保存されます:- PostgreSQL: 永続的なイベントログ
- Redis: 最近のイベント(ホットキャッシュ)
- リアルタイム: SSEストリーム
イベントの信頼性と保証
順序保証
Shannonは単一のワークフロー内で厳密な順序を提供します:- イベントはシーケンシャルに番号付けされています(
seqフィールド) - シーケンス番号にギャップなし(1, 2, 3, …)
- 同じワークフローからのイベントは常に順序通りに到着します
- 異なるワークフローからのイベントは交互に到着する可能性があります
配信保証
- 少なくとも1回の配信: イベントは複数回配信される可能性があります(重複排除には
seqを使用) - イベントの永続性: すべてのイベントはPostgreSQLの
event_logsテーブルに保存されます - ホットキャッシュ: 最近のイベントはRedisにキャッシュされ、迅速に取得可能
- 過去のアクセス: REST APIを介して過去のイベントをクエリ可能
ストリーム再接続
SSE接続が切断された場合:イベント保持
| ストレージ | 保持期間 | 目的 | イベントタイプ |
|---|---|---|---|
| Redis | 24時間 | リアルタイムストリーミング | すべてのイベント |
| PostgreSQL | 90日(デフォルト) | 歴史的クエリ | 重要なイベントのみ* |
| アーカイブ | 1年以上(オプション) | 長期監査 | 設定可能 |
WORKFLOW_COMPLETED、AGENT_COMPLETED、TOOL_INVOKED、LLM_OUTPUT、および ERROR_OCCURRED が含まれます。LLM_PARTIAL、HEARTBEAT、および AGENT_THINKING のような一時的なイベントはデータベースへの書き込みから除外され(書き込み負荷を約92%削減)、リアルタイムのSSEストリーミングとRedisキャッシュを介して完全に利用可能です。
イベントストレージの詳細については、Database Schemaを参照してください。