トレーシング

セッションには、エージェントとの会話と、その中でエージェントが行った処理がまとまっています。セッションには複数のターンを含めることができ、各ターンが一連の処理に対応します。トレースには、モデルの応答、ツール呼び出し、他のエージェントに委任した処理など、1 ターン内の各ステップが表示されます。

トレーシングダッシュボードでは、エージェントが行った処理と、各ステップに記録された入力、出力、所要時間、ステータスを確認できます。

API でセッションのステータス、リアルタイムのイベント、保存された出力、使用量を確認するには、まずオブザーバビリティを参照してください。

新しいセッションでは、トレーシングがデフォルトで有効です。トレースはダッシュボードで確認でき、API からエクスポートすることもできます。

トレースの開き方

1. Logs → Agents を開き、エージェントを実行したプロジェクトを選択します。
2. Search logs でセッションを検索します。Add filter を使うと、モデル、ステータス、日付で絞り込めます。
3. セッションを選択して、タイムラインとターンの一覧を開きます。
4. ターンを展開し、タイムラインまたはイベント一覧でステップを選択すると、詳細が表示されます。

セッションの概要には、ステータス、モデル、開始時刻、最後に処理を行った時刻、ターン数、記録されたトークン使用量が表示されます。

トレースの読み方

まずセッションを開き、ターンごとに処理の詳細を確認します。

1. セッション：Logs → Agents の各項目がセッションに対応します。セッションを開くと、タイムラインとターンの一覧が表示されます。たとえば、ユーザーは注文について質問し、同じセッションで追加の質問ができます。
2. ターン：ターンを展開すると、そのターンで行われた処理を確認できます。1 つのターンに複数のモデル応答やツール呼び出しが含まれることがあります。ターンの終了後に追加のメッセージを送ると、同じセッションで次のターンが始まります。
3. ターン内のステップ：トレースでは、モデル応答とツール呼び出しが、それぞれを実行したルートエージェントまたはサブエージェントの下にまとめて表示されます。記録された個々のステップをスパンと呼びます。

スパンを選択すると、ステータス、所要時間、開始時刻、終了時刻、記録されたデータを確認できます。

Agent

エージェントスパンには、ルートエージェントまたはサブエージェントが行った処理がまとめられます。サブエージェントとは、タスクの一部を任された別のエージェントです。モデル応答とツール呼び出しは、それぞれを実行したエージェントの下に表示されます。

詳細パネルには次の項目が表示されます。

• Agent type：ルートエージェント（root）またはサブエージェント（subagent）
• Agent：エージェントの ID、名前、モデル、指示（記録されている場合）
• Usage：そのエージェントに記録されたトークン数です。エージェント自身の使用分のみが対象で、配下のサブエージェントの使用分は含まれません。
• Duration と Outcome status：記録された処理にかかった時間と、その処理が完了、失敗、未完了のいずれであるか

Generation

生成スパンには、記録されたモデルの入力と出力がまとめられます。1 ターンで複数回の生成が行われることがあります。

推論時に、モデルは入力を読み取って応答を生成します。その応答でツールの呼び出しを要求することがあります。ツールが結果を返すと、モデルは次の生成で新たな応答を返せます。

• Input：ユーザーメッセージやツールの結果など、その応答に関連して記録された入力
• Output：回答のテキストやツール呼び出しなど、モデルが生成し、記録された項目
• Model：応答に使用されたモデル（記録されている場合）

Tool

ツールスパンには、ツール呼び出しと、記録された結果が表示されます。

ツールスパンには、独自の関数の呼び出しや、MCP（Model Context Protocol） サーバー上のツールの呼び出しが含まれます。ウェブ検索やコマンドの実行もツールスパンとして表示されることがあります。

• Call：ツールへのリクエスト。ツール名や引数がある場合は、それらも含まれます。
• Result：記録されたツールの応答（取得できた場合）
• Outcome status と Error：記録された実行結果のステータスとエラーの詳細（該当する場合）

MCP ツール呼び出しの場合、Call にはサーバーラベル（server_label）、ツール名（name）、引数（arguments）が含まれます。応答とエラーがある場合は、同じパネルにそれぞれ output と error として記録されます。別に表示される Result パネルは空の場合があります。MCP の応答は Call に保存されるためです。

実行時間とステータス

タイムラインでは、ステップの実行順序と、どのステップが並行して実行されたかを確認できます。Zoom in で拡大すると、短時間で終わったステップも詳しく確認できます。Fit timeline を選択すると、セッション全体が表示されます。

各スパンには所要時間と実行結果のステータスが表示されます。失敗したスパンには、記録されたエラーの詳細が含まれることもあります。

エージェントスパンの所要時間には、配下のステップの実行時間も含まれます。複数のステップが並行して実行されることもあります。たとえば、2 つのサブエージェントが同時に 10 秒間動作した場合、経過時間は約 10 秒です。

トークン使用量

セッションの概要にある Tokens には、セッション全体の使用量が表示されます。エージェントスパンの Usage には、そのエージェントに記録されたトークン数が表示されます。

使用量はターンの終了後に反映されることがあります。値が空欄または null の場合、トークン数は不明です。エージェントの使用量がゼロだったという意味ではありません。使用量のデータが追加されるとトークン数が変わることがあり、この値は最終的な請求額を示すものではありません。

トレースを確認できるタイミング

トレースはターンの終了後に作成されます。トレースやトークン使用量を確認できるようになる前に、エージェントの回答が表示されることがあります。

エージェントが処理を続けている間は、リアルタイムのセッションイベントで進捗を確認できます。

セッショントレースのエクスポート

セッションのトレースをダウンロードすると、別のトレーシングツールで確認できます。エンドポイント GET /v1/agents/sessions/{session_id}/traces は、OpenTelemetry Protocol（OTLP）の JSON データを含むトレースを 1 ページ分返します。

OPENAI_API_KEY を設定し、sess_123 をセッション ID に置き換えます。この例では、cURL と jq を使って 1 ページ分のデータを traces.otlp.json に保存します。

1
2
3
4
5
6curl --fail-with-body \
  "https://api.openai.com/v1/agents/sessions/sess_123/traces?limit=20&order=asc" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: agents=v1" \
  --output trace-page.json && \
jq '{resourceSpans: [.data[].otlp.resourceSpans[]]}' trace-page.json > traces.otlp.json

このコマンドは、そのページに含まれるトレースを 1 つの OTLP ペイロードにまとめます。トレーシングプロバイダーの認証方式を使って、プロバイダーの OTLP/HTTP エンドポイントにペイロードを送信してください。

セッション全体をエクスポートするには、trace-page.json を確認します。has_more が true の場合は、last_id を after に指定し、order は同じ値のまま次のページをリクエストします。次のページを取得する前に、取得済みのページを保存またはアップロードしてください。has_more が false になるまで繰り返します。

エクスポートの対象は、各リクエストの時点で取得できるトレースのみです。過去のセッションをエクスポートする場合は、そのセッションの各ターンが終了し、トレースが表示されるまで待ってください。エクスポートを実行しても、今後のトレースの自動配信は設定されません。

エージェント単位でのトレースのエクスポート

エージェントの複数のセッションからトレースをエクスポートするには、まずセッションの一覧を取得する際に agent_id フィルターを指定します。agent_123 は対象のエージェントの ID に置き換えてください。

1
2
3
4curl --fail-with-body \
  "https://api.openai.com/v1/agents/sessions?agent_id=agent_123&limit=100&order=asc" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: agents=v1"

1. data に含まれる各セッションの id を使い、前述の手順に従って、そのセッションのトレースを全ページ分エクスポートします。
2. セッション一覧に has_more: true が含まれている場合は、その一覧の last_id を after に指定して次のページを取得します。agent_id と order には同じ値を使います。
3. セッション一覧に has_more: false が返るまで繰り返します。

このフィルターは、指定したエージェントがルートエージェントであるセッションに一致します。セッション一覧のカーソルと、各セッションのトレースを取得するためのカーソルは別々に管理してください。

例：2 つのサブエージェントを含む 1 ターン

この例では、実際に記録されたセッションを取り上げます。ルートエージェントが MCP ツールを呼び出している間に、2 つのサブエージェントがそれぞれコマンドの実行とドキュメントの取得を行います。以下ではサブエージェントの名前を簡略化していますが、件数と所要時間にはトレースに記録された値を使用しています。

セッションとターン

セッションのヘッダーには、1 ターン、ツール呼び出し 10 回、252,468 トークンと表示されます。セッションのステータスは Idle です。ターン 1 のステータスは Completed で、所要時間は 1 分 37 秒です。

ターンを展開すると、ルートエージェントとその配下のステップが表示されます。トレースには、エージェントスパンが 3 件（ルートエージェントと 2 つのサブエージェント）、生成スパンが 11 件、ツールスパンが 10 件含まれています。

以下のツリーでは、繰り返し行われた生成とツール呼び出しをまとめています。ステップ間の親子関係はツリーで、各ステップの実行時刻はタイムラインで確認できます。

Session: Idle
└── Turn 1: Completed                              1m 37s
    └── Root agent                                1m 37s
        ├── 6 generations
        ├── 2 tools: spawn_agent_call
        ├── Subagent A                               24s
        │   ├── 2 generations
        │   └── Tool: command_execution               2s
        ├── Subagent B                               21s
        │   ├── 3 generations
        │   ├── 2 tools: notion.fetch              2s each
        │   └── Tool: send_input_call                 0ms
        ├── Tool: demo_capability_probe              87ms
        └── 3 tools: wait_for_agents_call

モデルの処理とタスクの委任

ルートエージェントの最初の Generation では、Input にユーザーのメッセージが含まれています。Output にはメッセージと 2 件の spawn_agent_call が含まれています。これらの呼び出しは Tool スパンとしても表示され、呼び出しによって起動したサブエージェントは、ルートエージェントの下に Agent スパンとして表示されます。

サブエージェント A には、独自の生成スパンと command_execution のツール呼び出しがあります。サブエージェント B には、3 回の生成、notion.fetch の MCP 呼び出し 2 回、send_input_call の呼び出し 1 回があります。モデル応答とツール呼び出しは、それぞれを実行したサブエージェントのスパンに属します。

ルートエージェントには、wait_for_agents_call のツールスパンも 3 件あります。最後の生成スパンにはメッセージが含まれており、記録された所要時間は 6 秒です。

MCP ツール呼び出し

ルートエージェントの demo_capability_probe スパンは、完了した Tool スパンで、所要時間は 87 ミリ秒です。Tool type は mcp_call です。

Call パネルには次のフィールドが含まれています。

123456{
  "type": "mcp_call",
  "server_label": "demo_local",
  "name": "demo_capability_probe",
  "status": "completed"
}

この抜粋は、記録された呼び出しの一部です。同じパネルには arguments も含まれ、output に MCP の応答が記録されています。別に表示される Result パネルの値は null です。このスパンの Parent span はルートエージェントを指しています。

サブエージェント B の 2 件の notion.fetch スパンも同じ構造です。ツールの種類は mcp_call で、MCP の応答は Call に記録されます。どちらのスパンもサブエージェント B を親とします。

このセッションの実行時間と使用量

タイムラインでは、2 つのサブエージェントのスパンが時間的に重なっています。サブエージェント A の所要時間は 24 秒、サブエージェント B は 21 秒で、どちらもルートエージェントの 1 分 37 秒のスパン内で実行されています。ダッシュボードでは、これらの所要時間を丸めて表示します。

各エージェントスパンの Usage パネルには、そのエージェントに記録されたトークン数が表示されます。

このセッションでは、3 つのエージェントの合計トークン数を足すと、セッションのヘッダーに表示される 252,468 トークンと一致します。