For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
メインナビゲーション
Theme

おすすめ

Agents API

Agents SDK

ChatKit

API ダッシュボード
ChatGPT を試す

オブザーバビリティと使用量

リアルタイムの進捗、完了した作業、記録されたトークン使用量を確認します。

エージェントの動作をリアルタイムで追跡し、完了した作業や各ターンの詳細なトレースを確認できます。

  1. Platform ダッシュボードでセッションログを表示できます。
  2. イベントと保存済みの履歴からセッションの経過を追えます。
  3. ターンを調べて、委任されたコマンドをどのエージェントが実行したか特定できます。
  4. ルートエージェントとサブエージェントの各ターンに記録されたトークン使用量を確認できます。

ダッシュボードでのセッションの確認

platform.openai.com/logs?api=agents にアクセスし、エージェントタブを開きます。

セッション ID で検索すると、そのセッションのターン、ツール呼び出し、サブエージェントを確認できます。

ダッシュボードで記録済みのモデル応答、ツール呼び出し、サブエージェントの動作を確認する手順は、トレーシングガイドを参照してください。公開 API を使って、OTLP JSON 形式でセッショントレースをエクスポートすることもできます。

イベントの追跡とセッション履歴の確認

各セッションにはイベントストリームがあり、エージェントの動作をリアルタイムで確認できます。OPENAI_API_KEY を設定し、以下の例のセッション ID を保存しておいたセッション ID に置き換えてください。

セッションイベントのリアルタイム追跡
// Replace the illustrative IDs and URLs below with your own resource values.
import OpenAI from "openai";

const client = new OpenAI();
const events = await client.beta.agents.sessions.events.stream("sess_123");
try {
  for await (const event of events) {
    if (
      [
        "agent.session.turn.failed",
        "agent.session.turn.cancelled",
        "agent.session.failed",
        "agent.session.environment.failed",
        "error",
      ].includes(event.type)
    ) {
      throw new Error(`Agent lifecycle failure: ${event.type}`);
    }
    console.log(JSON.stringify(event));
  }
} finally {
  events.controller.abort();
}

アイドルイベントが発生してもストリームは開いたままなので、キューに入った作業も追跡できます。監視を終了するには Ctrl+C を押します。

セッションの実行中には、次のようなイベントが表示されます。

agent.session.environment.connected
agent.session.turn.created
agent.session.turn.in_progress
agent.session.turn.item.added
agent.session.turn.output_text.delta
agent.session.turn.completed
agent.session.idle

すでに行われた作業を確認するには、セッションに保存された項目を取得します。

保存済みのセッション項目の確認
// Replace the illustrative IDs and URLs below with your own resource values.
import OpenAI from "openai";
const client = new OpenAI();

const sessionId = "sess_123";
const items = await client.beta.agents.sessions.items.list(sessionId, {
  order: "asc",
  limit: 100,
});
console.log(items.data);

ターンの確認と委任されたコマンドの特定

セッションのターンは公開 API から取得できます。コマンド項目の turn_id と、保存しておいたセッション ID を使います。Go の例では、SDK 組み込みのページネーションを使ってルートエージェントとサブエージェントのターンを検索し、一致したターンをそのターンが属するエージェントから取得します。例にある各 ID は、自分のセッションの対応する ID に置き換えてください。cURL の例には jq が必要です。

委任されたコマンドの実行元の特定
// Replace the illustrative session and turn IDs with values from your command item.
import OpenAI from "openai";
const client = new OpenAI();

async function findTurn(sessionId, turnId) {
  for await (const turn of client.beta.agents.sessions.turns.list(sessionId, {
    limit: 100,
  })) {
    if (turn.id === turnId) {
      return client.beta.agents.sessions.turns.retrieve(turnId, {
        session_id: sessionId,
      });
    }
  }
  for await (const subagent of client.beta.agents.sessions.subagents.list(
    sessionId,
    { limit: 100 }
  )) {
    for await (const turn of client.beta.agents.sessions.subagents.turns.list(
      subagent.id,
      { session_id: sessionId, limit: 100 }
    )) {
      if (turn.id === turnId) {
        return client.beta.agents.sessions.subagents.turns.retrieve(turnId, {
          session_id: sessionId,
          subagent_id: subagent.id,
        });
      }
    }
  }
  throw new Error(`Turn ${turnId} not found in session ${sessionId}`);
}

const turn = await findTurn("sess_123", "turn_123");
console.log(turn.subagent_id || "main agent");

手動でページを取得する場合は、レスポンスに含まれる last_id を次のページの after の値に指定します。次のページがあるのは、has_more が true の場合です。Go の例では、後続のページを自動的に取得します。

コマンド項目には turn_id が含まれます。そのターンを取得し、subagent_id を確認すると、委任されたコマンドを実行したエージェントを特定できます。サブエージェント ID が null の場合は、ルートエージェントが実行した作業です。コマンド出力が切り詰められたかどうかは報告されません。

ターンのトレースの確認

Platform ダッシュボードでは、完了したターンと、そのターンでのエージェントの動作を確認できます。 公開 API から記録済みのトレースを取得するには、プロジェクトの API キーを使ってセッショントレースのエクスポート用エンドポイントを呼び出します。ダッシュボードのトレース用エンドポイントは、利用者向けにサポートされている API とは別です。

ターンリソースには、ベストエフォートで記録される usage と、作業の委任先を示す subagent_id が含まれます。使用量が不明な場合は null になることがあり、記録値は後から変わることがあります。サブエージェントのトークン使用量の確認を参照してください。

シェルコマンドの実行元を特定するには、コマンド項目の turn_id が示すターンを取得し、turn.subagent_id を確認します。利用者向け API では、コマンド出力が切り詰められたかどうかはわかりません。

エラーと復旧

エラーの内容を確認し、復旧方法を選んで安全に再試行する手順は、エラーと復旧を参照してください。

モデルの使用量とコスト

エージェントは、タスクを完了するまでにモデルを複数回呼び出すことがあります。Responses API と同様に、各呼び出しにはモデルのトークン料金とプロンプトキャッシュのルールが適用されます。コストを見積もる際は、タスクの完了に必要なすべての呼び出しを含めてください。

コストの内訳

モデルの各呼び出しでは、次のトークンを消費することがあります。

  • 入力トークン：エージェントへの指示、ツール定義、会話履歴、ユーザー入力、ファイルや画像、ツールの実行結果
  • キャッシュ済み入力トークン：プロンプトの先頭部分が一致したことで再利用された入力。モデルのキャッシュ済み入力単価で課金
  • 出力トークン：生成されたテキスト、ツール呼び出しの引数、推論

推論トークンには出力トークンの料金が適用されます。

サブエージェントもモデルを呼び出すことがあります。モデルのコストを調べる際は、ルートエージェントの作業とあわせて、サブエージェントのターンごとの使用量の記録を確認してください。

コストを見積もる際は、ルートエージェントとサブエージェントの作業にかかる費用を、再試行分も含めて計算してください。該当する場合は、ツール、サンドボックスのコンピューティングリソース、外部サービスの料金も加算します。キャッシュへの書き込みに料金が設定されているモデルでは、入力をキャッシュに書き込む際にも費用が発生します。以下に示す Agents API の使用量フィールドには、キャッシュに書き込んだトークン数が個別に表示されないため、書き込み料金が適用される場合は、これらのフィールドだけでモデルの正確な利用料金を算出することはできません。

プロンプトキャッシュ

エージェントはセッション内でコンテキストを引き継ぎます。連続するモデル呼び出しでプロンプトの先頭部分が一致すると、プロンプトキャッシュによって、その部分の処理結果を再利用できます。キャッシュを利用しても過去の回答が再生されることはなく、モデルは新しい応答を生成します。セッションを維持していても、必ずキャッシュにヒットするわけではありません。再利用できるかどうかは、プロンプトの先頭部分が一致するかどうかと、モデルごとのキャッシュの適用条件および有効期間によって決まります。

できる限り最初の指示とツール定義を変更せず、タスクに関する新しい情報は後続のメッセージに追加してください。ツール検索を使うと、見つかったツールの定義は会話の末尾に追加されるため、それまでの内容はキャッシュから再利用できます。モデルごとのルールは、プロンプトキャッシュを参照してください。

キャッシュ済み入力の割合が高くても、その割合からタスク全体のコスト削減額はわかりません。キャッシュ済み入力にも料金がかかり、呼び出しを繰り返すと、そのたびに長い会話履歴を処理することがあります。アプリケーションに必要な品質とレイテンシを満たす条件で、同じタスクを完了するまでのコストを比較してください。

トークン使用量の見方

セッションリソースとターンリソースでは、usage がベストエフォートで記録されます。使用量が不明な場合は null になることがあり、集計結果が反映されるにつれて記録値が変わることもあります。使用量の記録がなくても、使用量がゼロとは限りません。これらの数値は最終的な請求額を示すものではありません。

記録された使用量オブジェクトには、次のようにトークン数の内訳が含まれます。

{
  "input_tokens": 5000,
  "input_tokens_details": {
    "cached_tokens": 1500
  },
  "output_tokens": 900,
  "output_tokens_details": {
    "reasoning_tokens": 200
  },
  "total_tokens": 5900
}

この例では、エージェントは 5,000 個の入力トークンを処理し、900 個の出力トークンを生成しました。入力トークンのうち 1,500 個はキャッシュ済みで、出力トークンのうち 200 個は推論トークンです。

キャッシュ済みトークンは input_tokens に、推論トークンは output_tokens に含まれます。

サブエージェントのトークン使用量の確認

セッションのターンを一覧表示するか個別に取得し、各ターンの usage を確認します。subagent_id はサブエージェントを識別する ID で、ルートエージェントのターンでは null です。has_more が true の場合は、last_id を after に指定し、同じ order を使って残りのターンを取得します。

使用量はベストエフォートで記録されます。不明な場合は null になることがあり、記録値は後から変わることがあります。各エージェントの使用量の記録は、トレーシングダッシュボードでも確認できます。