使用状況
Agents SDK は、すべての実行ごとにトークン使用状況を自動で追跡します。実行コンテキストから参照でき、コストの監視、制限の適用、またはアナリティクスの記録に利用できます。
追跡対象
- requests: 実行された LLM API 呼び出し数
- input_tokens: 送信された入力トークンの合計
- output_tokens: 受信した出力トークンの合計
- total_tokens: 入力 + 出力
- request_usage_entries: リクエストごとの使用状況内訳の一覧
- details:
input_tokens_details.cached_tokensoutput_tokens_details.reasoning_tokens
実行からの使用状況へのアクセス
Runner.run(...) の後、result.context_wrapper.usage から使用状況にアクセスします。
result=awaitRunner.run(agent,"What's the weather in Tokyo?")usage=result.context_wrapper.usageprint("Requests:",usage.requests)print("Input tokens:",usage.input_tokens)print("Output tokens:",usage.output_tokens)print("Total tokens:",usage.total_tokens)使用状況は、実行中のすべてのモデル呼び出し（ツール呼び出しや ハンドオフ を含む）を横断して集計されます。
LiteLLM モデルでの使用状況の有効化
LiteLLM プロバイダーは、デフォルトでは使用状況メトリクスを報告しません。LitellmModel を使用する場合は、ModelSettings(include_usage=True) をエージェントに渡して、LiteLLM の応答がresult.context_wrapper.usage を埋めるようにします。
fromagentsimportAgent,ModelSettings,Runnerfromagents.extensions.models.litellm_modelimportLitellmModelagent=Agent(name="Assistant",model=LitellmModel(model="your/model",api_key="..."),model_settings=ModelSettings(include_usage=True),)result=awaitRunner.run(agent,"What's the weather in Tokyo?")print(result.context_wrapper.usage.total_tokens)リクエスト単位の使用状況トラッキング
SDK は、各 API リクエストの使用状況をrequest_usage_entries に自動で記録します。詳細なコスト計算やコンテキストウィンドウ消費の監視に役立ちます。
result=awaitRunner.run(agent,"What's the weather in Tokyo?")forrequestinenumerate(result.context_wrapper.usage.request_usage_entries):print(f"Request{i+1}:{request.input_tokens} in,{request.output_tokens} out")セッションでの使用状況の取得
Session（例:SQLiteSession）を使用する場合、Runner.run(...) の各呼び出しは、その特定の実行の使用状況を返します。セッションは文脈用の会話履歴を保持しますが、各実行の使用状況は独立しています。
session=SQLiteSession("my_conversation")first=awaitRunner.run(agent,"Hi!",session=session)print(first.context_wrapper.usage.total_tokens)# Usage for first runsecond=awaitRunner.run(agent,"Can you elaborate?",session=session)print(second.context_wrapper.usage.total_tokens)# Usage for second runなお、セッションは実行間で会話コンテキストを保持しますが、各Runner.run() 呼び出しで返される使用状況メトリクスは、その実行のみを表します。セッションでは、以前のメッセージが各実行の入力として再投入される場合があり、その結果、後続ターンの入力トークン数に影響します。
フックでの使用状況の利用
RunHooks を使用している場合、各フックに渡されるcontext オブジェクトにはusage が含まれます。これにより、重要なライフサイクルの瞬間に使用状況を記録できます。
classMyHooks(RunHooks):asyncdefon_agent_end(self,context:RunContextWrapper,agent:Agent,output:Any)->None:u=context.usageprint(f"{agent.name} →{u.requests} requests,{u.total_tokens} total tokens")API リファレンス
詳細な API ドキュメントは以下をご覧ください:
Usage- 使用状況トラッキングのデータ構造RequestUsage- リクエスト単位の使用状況の詳細RunContextWrapper- 実行コンテキストから使用状況へアクセスRunHooks- 使用状況トラッキングのライフサイクルにフック