トレーシング

セッションは、エージェントの会話と作業をひとまとめにします。セッションには、作業のサイクルにあたるターンを複数含めることができます。トレースには、モデルの応答、ツール呼び出し、他のエージェントに委任した作業など、1 つのターン内のステップが表示されます。

トレーシングダッシュボードには、各ステップで記録された入力、出力、所要時間、稼働状況など、エージェントが実行した内容が表示されます。

API を通じてセッションの稼働状況、ライブイベント、保存された出力、使用量を確認するには、まずオブザーバビリティを参照してください。

新しいセッションでは、トレーシングがデフォルトで有効になっています。トレースはダッシュボードで確認するか、API を通じてエクスポートできます。

トレースの表示

1. ログ → エージェントを開き、エージェントを実行したプロジェクトを選択します。
2. ログを検索でセッションを探します。フィルターを追加を使うと、モデル、稼働状況、日付で絞り込めます。
3. セッションを選択して、タイムラインとターンの一覧を開きます。
4. ターンを展開し、タイムラインまたはイベント一覧でステップを選択すると、詳細を確認できます。

セッションの概要には、稼働状況、モデル、開始時刻、最後のアクティビティ、ターン数、記録されたトークン使用量が表示されます。

トレースの見方

まずセッションを確認し、次にターンの詳細を見ていきます。

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

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

エージェント

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

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

• エージェントの種類：ルートエージェント（root）またはサブエージェント（subagent）
• エージェント：記録されている場合は、その ID、名前、モデル、指示
• 使用量：そのエージェントについて記録されたトークン数です。この数値はエージェント自身の使用量を表し、サブエージェントの使用量は含みません。
• 所要時間と結果の状態：記録された作業にかかった時間と、完了、失敗、未完了のいずれかを示す状態

生成

生成スパンは、記録されたモデルの入力と出力をまとめます。各ターンには、複数の生成が含まれることがあります。

推論中、モデルは入力を読み取り、応答を生成します。その応答でツールの使用をリクエストすることがあります。ツールから結果が返ると、モデルは新たな生成で次の応答を出力できます。

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

ツール

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

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

• 呼び出し：ツールへのリクエスト。ツール名と引数がある場合は、それらも含まれます
• 結果：取得できる場合は、記録されたツールの応答
• 結果の状態とエラー：記録されている場合は、実行結果とエラーの詳細

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

実行タイミングと稼働状況

タイムラインには、ステップの順序と、実行時間が重なっているステップが表示されます。拡大では、短時間のステップをより詳しく確認できます。タイムライン全体を表示では、セッション全体を確認できます。

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

エージェントスパンの所要時間には、子ステップの実行時間も含まれます。ステップの実行時間は重なることがあります。たとえば、2 つのサブエージェントが同時に 10 秒間実行された場合、実際の経過時間は約 10 秒です。

トークン使用量

セッションの概要のトークンには、セッションの使用量が表示されます。エージェントスパンの使用量には、そのエージェントについて記録されたトークン数が表示されます。

使用量は、ターンの終了後に届くことがあります。値が空欄または 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 トークンが表示されます。セッションの稼働状況は待機中で、ターン 1 は完了しており、所要時間は 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

モデルの処理と作業の委任

ルートエージェントの最初の生成では、入力にユーザーのメッセージが含まれます。出力には、メッセージと 2 つの spawn_agent_call 項目が含まれます。これらの呼び出しはツールスパンとしても表示され、呼び出しによって作成されたサブエージェントは、ルートエージェント配下のエージェントスパンとして表示されます。

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

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

MCP ツール呼び出し

ルートエージェントの demo_capability_probe スパンは、所要時間が 87 ミリ秒の完了済みツールスパンです。ツールの種類は mcp_call です。

呼び出しパネルには、次のフィールドが含まれます。

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

この抜粋は、記録された呼び出しの一部です。同じパネルには、呼び出しの arguments と、output に格納された MCP 応答が含まれます。別に表示される結果パネルは null です。このスパンの親スパンは、ルートエージェントを指します。

サブエージェント B の 2 つの notion.fetch スパンも同じ構造です。ツールの種類は mcp_call で、呼び出しに MCP 応答が含まれ、親はサブエージェントです。

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

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

各エージェントスパンの使用量パネルには、そのエージェント自身の記録済みトークン数が表示されます。

この記録済みセッションでは、3 つのエージェントのトークン数を合計すると、セッションヘッダーに表示されている 252,468 トークンになります。