Skip to content

使用方式

Agents SDK 會自動追蹤每次執行的 token 使用情況。你可以從執行的 context 中存取這些資訊，用來監控成本、強制執行限制，或記錄分析數據。

追蹤項目

  • requests：發出的大型語言模型 (LLM) API 請求次數
  • input_tokens：傳送的總輸入 token 數量
  • output_tokens：接收的總輸出 token 數量
  • total_tokens：輸入 + 輸出 token 總數
  • details：
  • input_tokens_details.cached_tokens
  • output_tokens_details.reasoning_tokens

從執行中取得使用量

在Runner.run(...)之後，可以透過result.context_wrapper.usage來取得使用量資訊。

result = await Runner.run(agent, "What's the weather in Tokyo?")
usage = result.context_wrapper.usage

print("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) 傳遞給你的代理（agent），以便 LiteLLM 回應能夠填入 result.context_wrapper.usage。

from agents import Agent, ModelSettings, Runner
from agents.extensions.models.litellm_model import LitellmModel

agent = Agent(
    name="Assistant",
    model=LitellmModel(model="your/model", api_key="..."),
    model_settings=ModelSettings(include_usage=True),
)

result = await Runner.run(agent, "What's the weather in Tokyo?")
print(result.context_wrapper.usage.total_tokens)

使用 sessions 存取用量資訊

當你使用 Session（例如，SQLiteSession）時，每次呼叫 Runner.run(...) 都會回傳該次執行的用量資訊。Sessions 會維持對話歷史以提供上下文，但每次執行的用量資訊是獨立的。

session = SQLiteSession("my_conversation")

first = await Runner.run(agent, "Hi!", session=session)
print(first.context_wrapper.usage.total_tokens)  # Usage for first run

second = await Runner.run(agent, "Can you elaborate?", session=session)
print(second.context_wrapper.usage.total_tokens)  # Usage for second run

請注意，雖然 session（會話）能在多次執行間保留對話上下文，但每次Runner.run()呼叫所回傳的使用量指標（usage metrics）僅代表該次執行本身。在 session 中，先前的訊息可能會在每次執行時重新作為輸入，這會影響後續回合的輸入 token 數量。

在 hooks 中使用 usage

如果你正在使用RunHooks，傳遞給每個 hook 的context物件會包含usage。這讓你可以在關鍵生命週期時刻記錄使用量（usage）。

class MyHooks(RunHooks):
    async def on_agent_end(self, context: RunContextWrapper, agent: Agent, output: Any) -> None:
        u = context.usage
        print(f"{agent.name} → {u.requests} requests, {u.total_tokens} total tokens")

API 參考文件

如需詳細的 API 文件，請參閱：

  • [Usage][agents.usage.Usage] - 使用狀態追蹤資料結構
  • [RunContextWrapper][agents.run.RunContextWrapper] - 從執行上下文存取使用狀態
  • [RunHooks][agents.run.RunHooks] - 鉤入使用狀態追蹤生命週期