トラジェクトリービューと停止

トラジェクトリーは、1つのLLM作業フローに参加したトランザクションをmtid基準でまとめた単位です。トランザクションが複数まとめられていても、フローが複数のプロセスを経由しても、1つのトラジェクトリーとして扱います。

このドキュメントでは、実行中のトラジェクトリーをリストと実行フローチャートで確認する方法と、問題のあるトラジェクトリーを画面から停止する方法を案内します。

ノート

トラジェクトリーの停止は、Python SDK 2.2.1以降で使用できます。Java SDKは停止をサポートしていません。

アクセス方法

画面	開き方
アクティブトラジェクトリーリスト	総合状況ダッシュボードやAIエージェントメインダッシュボードのアクティブトラジェクトリーウィジェットで、軌道チャート(リスト全体)、等級の行(該当等級のリスト)、ヘッダーの詳細アイコン(リスト全体)をクリックします。ダッシュボードがリアルタイムの場合にのみ開くことができ、件数が0の等級はクリックできません。
トラジェクトリービュー	アクティブトラジェクトリーリストでグループヘッダーやトランザクション行をクリックするか、アクティブLLM APIウィジェットの実行中の呼び出しリストで呼び出しを選択します。
トラジェクトリービュータブ	LLMトレース詳細でトラジェクトリービュータブを選択します。該当トランザクションが属するトラジェクトリーを表示します。

ダッシュボードから開いたリストとビューは、ウィンドウ(モーダル)で開きます。ウィンドウヘッダーの新しいウィンドウを開くボタンをクリックすると別ウィンドウで表示でき、等級で絞り込んだリストは別ウィンドウでも同じ等級で開きます。別ウィンドウで表示したリストでトラジェクトリーを選択すると、同じウィンドウがトラジェクトリービューに切り替わり、戻るボタンをクリックするとリストに戻ります。

アクティブトラジェクトリーリスト

現在実行中のトランザクションをトラジェクトリーごとにまとめて表示するリストです。ウィンドウのタイトルは「アクティブトラジェクトリー」と表示されます。

• リストの上部に、トラジェクトリー数とトランザクション数、CSVダウンロードボタン、検索入力欄(名前 / ユーザー / セッション)があります。検索語は、トランザクション名、ユーザー、セッション、mtidから検索します。

• トラジェクトリーごとにグループヘッダーがあり、その下にまとめられたトランザクションが行として表示されます。グループヘッダーやトランザクション行をクリックすると、そのトラジェクトリーのトラジェクトリービューが開きます。

• リストは、トラジェクトリーごとのステップ合計が多い順に並べ替えられて開きます。トランザクションは最大100件まで照会されます。

• 進行中のトランザクションのみを表示します。終了したトランザクションはリストから除外されます。

グループヘッダー

項目	説明
等級	Light、Middle、Heavy。トラジェクトリー全体に付ける等級であり、速度や実行時間を意味しません。等級の境界値は、SDKオプションに設定した基準に従います。等級情報がない場合はUnknownと表示します。
mtid	トラジェクトリーをまとめるキー。mtidがない単独フローは「単独実行」と表示します。
tx N	まとめられたトランザクション数。検索で絞り込んだ場合は、残ったトランザクション数です。
ユーザー、セッション	ログに付与されたuser_id、session_id。値がない場合は-と表示します。
停止	トラジェクトリーを停止します。トラジェクトリーの停止を参照してください。

トランザクション行

カラム	説明
トランザクション	トランザクション名。[Workflow]、[Agent]などの接頭辞を含む原文です。
ステップ	トランザクションが実行したステップ数
エージェント	トランザクションが実行したAIサブエージェント数。ない場合は-と表示します。
LLM呼び出し数	トランザクション内で発生したLLM呼び出し数
経過	トランザクション開始後の経過時間

ノート

CSVファイルには、画面のカラムに加えてステータス、mtid、ユーザー、セッションのカラムが行ごとに含まれます。ステータスの値は進行状態ではなく、そのトランザクションが属するトラジェクトリーの等級(Light、Middle、Heavy、Unknown)です。

時間コントロール

リストは、開いた時点で停止した状態で開きます。リストを読んでいる間に並び順が変わらないようにするためです。

• 再生ボタンをクリックすると、設定した周期ごとにリストを更新します。もう一度クリックすると、その時点で停止します。

• 更新ボタンをクリックすると、現在の時点で一度だけ更新します。

• 設定ボタンをクリックして**自動更新(秒)**の値を変更すると、更新周期を10～30秒(5秒単位、デフォルト10秒)に設定できます。

トラジェクトリービュー

1つのトラジェクトリーの実行フローをチャートで表示する画面です。ウィンドウのタイトルは「トラジェクトリービュー」と表示されます。

• 上部ツール: プロジェクト選択と時間コントロールがあります。プロジェクト選択では、現在のプロジェクトと併せて照会するAI Agent Observabilityプロジェクトを選択できます。時間コントロールは、リストと同様に開いた時点で停止した状態で開きます。トラジェクトリーが終了すると、時間選択と更新周期の設定が無効になり、完了または失敗のタグが付きます。

• ヘッダー: ルートトランザクション名、ステータスタグ(実行中、完了、失敗)、停止ボタンがあります。

• 情報行: mtid(ない場合は単独実行)、ユーザー、セッション、経過時間を表示します。ユーザーとセッションは、値がある場合にのみ表示します。

実行フローチャート

• 縦軸は時間、横軸は委任の深さです。長い空白区間は折りたたんで表示します。

• カード1つがトランザクション1つです。カードには、種類(WORKFLOW、AGENT、LLM API)、名前、経過時間、ステップ数、ステータス(実行中、完了、エラー、未収集)が表示されます。種類タグがないトランザクションもAGENTと表示されます。

• 同じ親の下で同時に開始したトランザクション、または順番に続いたトランザクションが4件以上ある場合、あるいは下位の委任が4段階以上続く場合は、最初の3件のみをカードで表示し、残りは「+N · 同時」、「+N · 順次」、「+N · 下位委任」のタイルに折りたたみます。タイルをクリックすると展開され、「トランザクション N · 折りたたむ」をクリックすると再び折りたたまれます。

• 親トランザクションが収集されていない場合は、その位置に「(未収集)」カードを表示します。照会結果で下位トランザクションの一部が省略された場合は、その親の下に「+N件 非表示」カードを表示します。

• トラジェクトリーが見つからない場合は、「トラジェクトリーが見つかりません。」と表示されます。

• すでに終了したトラジェクトリーは、チャートの代わりにトランザクションを表示ボタンが表示され、クリックするとLLMトレース詳細が開きます。LLMトレース詳細のトラジェクトリービュータブでは、終了したトラジェクトリーもチャートで表示します。

ステップ詳細

チャートでカードをクリックすると、右側にそのトランザクションのステップ詳細が開きます。詳細が開いている間も、背後のチャートをクリックしたりスクロールしたりできます。

• 進行中のトランザクションはテーブルビュータブ1つのみを表示し、最後の行に「進行中」と表示されます。カードをクリックした時点の内容であり、自動では更新されません。

• 進行状況を継続して追跡するには、詳細ヘッダーの新しいウィンドウを開くボタンをクリックしてください。「トラジェクトリー詳細」ウィンドウが開き、このウィンドウの時間コントロールで更新できます。

• 終了したトランザクションは、LLMトレース詳細と同様にレコード要約、テーブルビュータブを表示します。

• テーブルビューのLLM APIステップには、直前の呼び出しと比較したプロンプトの変化(プロンプトデルタ)が併せて表示されます。詳細はプロンプトデルタを参照してください。

トラジェクトリーの停止

実行中のトラジェクトリーを画面から停止できます。繰り返しの呼び出しでコストが増え続ける場合や、誤ったリクエストで開始されたフローを断ち切る場合に使用します。停止はトラジェクトリー単位でリクエストし、画面に表示されたそのトラジェクトリーの進行中のトランザクションが停止の対象です。

停止される範囲

• 進行中のLLM呼び出しを切断し、該当トランザクションを終了します。

• 以降、同じトラジェクトリーで発生するLLM呼び出しもブロックします。

• 停止箇所は、トランザクショントレースにWhaTap: LLM trajectory stopped by controlメッセージステップとして記録されるため、アプリケーションのエラーと区別できます。LLMトレース詳細のテーブルビューで確認してください。

注意

停止は元に戻せません。確認ウィンドウで対象のトラジェクトリーとトランザクション数を確認してから実行してください。

停止する

1. 次のいずれかで停止ボタンをクリックします。

   • アクティブトラジェクトリーリスト: トラジェクトリーのグループヘッダーの右端

   • トラジェクトリービュー: タイトル行の右端

   • LLMトレース詳細のトラジェクトリービュータブ: タイトル行の右端(同じトラジェクトリーに進行中のトランザクションがある場合)

2. 「トラジェクトリー停止」確認ウィンドウで、対象の名前とmtid · tx Nを確認します。Nは、実際に停止リクエストを送信するトランザクション数です。

3. シークレットキーを入力します。目のアイコンをクリックすると、入力したキーを確認できます。

4. 停止をクリックします。入力欄でEnterキーを押しても実行されます。

5. 結果に関係なくウィンドウが閉じ、画面上部に結果メッセージが表示されます。

アクティブLLM APIウィジェットの実行中の呼び出しリストには、停止ボタンがありません。リストで呼び出しを選択してトラジェクトリービューに移動した後、停止してください。

結果メッセージ

結果	メッセージ	意味と対処
成功	成功	すべての対象が停止を受け入れたか、すでに停止中です。
未確認	停止をリクエストしましたが、SDKから確認が得られませんでした。リストを更新して確認してください。	リクエストはSDKに送信されましたが、3秒以内に応答がありませんでした。実際には停止している可能性があり、再試行しても問題ありません。Java SDKでは常にこのメッセージが表示されます。
キーエラー	セキュリティキーが正しくありません。	SDKがシークレットキーを拒否しました。キーを確認して再試行してください。
対象なし	アクティブなトランザクションがありません。	SDKに対象のトランザクションがありません。その間にトランザクションが終了した可能性があります。
送信失敗	SDKと接続されていないため、停止リクエストを送信できませんでした。SDKの状態を確認してから再試行してください。	リクエストがSDKに送信されなかったため、停止されていません。SDKの状態を確認してから再試行してください。
その他の失敗	不明なエラーが発生しました。	サーバーがリクエストを拒否したか、SDKで例外が発生したか、リクエストがサーバーに送信されませんでした。

• サーバーがリクエストを拒否した場合やリクエストがサーバーに送信されなかった場合を除き、失敗と警告のメッセージの末尾には、該当するアプリケーション名が括弧付きで表示されます。

• 対象が複数ある場合は、最も悪い結果1つのみを表示します。一部のみ停止された場合は、成功と表示しません。

停止ボタンが表示されない、または無効な場合

状態	原因
ボタンが表示されない	mtidがない単独フロー(単独実行)であるか、進行中の所属トランザクションがありません。
ボタンが無効(グレー)	現在のプロジェクトに修正権限がありません。ボタンにマウスオーバーすると「修正権限がありません。」と表示されます。

注意事項

• リストで検索語により絞り込んだ状態で停止すると、画面に残ったトランザクションのみが対象になります。

• トラジェクトリービューで複数のプロジェクトを併せて選択した場合は、停止リクエストをプロジェクトごとに分けて送信します。そのうち1つでもリクエストが拒否されると、残りのリクエストが受け入れられていても「不明なエラーが発生しました。」と表示されます。

• SDKは停止を非同期で処理するため、成功した後もリストやビューからすぐには除外されない場合があります。

• 停止されたトラジェクトリーに、別途「停止済み」の状態はありません。以降は完了または失敗と表示されるため、停止したかどうかはLLMトレース詳細のメッセージステップで確認してください。

参考: ユーザーブロックとの違い

特定ユーザーのLLM呼び出しを防ぐユーザーブロックも、Python SDK 2.2.1以降でサポートしています。2つの機能は、対象、時点、動作が異なります。

区分	トラジェクトリーの停止	ユーザーブロック
対象	実行中のトラジェクトリー1つ	指定したユーザーIDのすべてのLLM呼び出し
方法	画面の停止ボタン	SDKオプションllm_blocked_users
時点	実行中のフローを事後に断ち切る	呼び出し前にブロック
動作	進行中のLLM呼び出しを切断してトランザクションを終了し、以降の同じトラジェクトリーのLLM呼び出しをブロック	該当ユーザーのLLM呼び出しをブロックし、LLMクライアントライブラリの接続エラー(例: APIConnectionError)として返す
トレースの記録	WhaTap: LLM trajectory stopped by control	WhaTap: LLM call blocked for user …

ユーザーブロックの設定は、Python SDK設定を参照してください。