openai-agents-python 使用量追踪完全指南从 Run 上下文到会话与检查点的 Token 计量【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-pythonopenai-agents-pythonAgents SDK为每一次 Agent 运行自动追踪 token 用量开发者可通过运行上下文读取这些数据用于成本监控、限额控制和数据分析。本文基于 docs/usage.md 及其韩语译本 docs/ko/usage.md 的系统讲解并结合仓库源码 src/agents/usage.py、src/agents/run_context.py 与 src/agents/model_settings.py 的实现细节带读者完整掌握追踪什么、如何读取、如何精细化计量这条主线读完后可以立即在真实项目中落地 token 用量统计。追踪了哪些指标SDK 在每次运行中自动维护一个聚合的Usage对象其核心字段如下字段含义requests发起的 LLM API 调用次数input_tokens发送的总输入 token 数output_tokens接收到的总输出 token 数total_tokens输入 输出request_usage_entries每次请求的用量明细列表RequestUsage对象details嵌套字段input_tokens_details.cached_tokens、input_tokens_details.cache_write_tokens、output_tokens_details.reasoning_tokens其中details部分与 OpenAI Responses API 的 usage 细节结构对齐cached_tokens表示命中缓存的输入 tokencache_write_tokens表示写入缓存的 tokenreasoning_tokens表示推理模型用于思考过程的 token。从源码看Usage的__post_init__会把缺失的可选细节字段统一规范化为0而不是None避免后续相加时出现TypeErroradd()方法则负责把单次模型调用的用量累加到运行总量上并自动在request_usage_entries中保留逐请求的明细。requests的计数口径值得一提适配器可以通过_mark_requests_completed_without_usage()见 src/agents/usage.py显式登记完成了但没有用量的物理请求次数也就是说即使某些提供方不返回 usage调用次数依然会被如实计入。从一次运行中读取用量Runner.run(...)执行完毕后通过result.context_wrapper.usage即可访问本次运行聚合后的用量result await Runner.run(agent, Whats 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)这里的context_wrapper是RunContextWrapper它除了携带你传入的context业务对象外还维护一个usage: Usage字段注释明确说明这是到目前为止该 agent 运行的用量对于流式响应该值在流的最后一个 chunk 处理完成前是滞后的。需要强调的聚合范围是用量横跨运行期间发生的所有模型调用包括触发工具调用tool call或交接handoff的那些模型调用。也就是说一个 Agent 内部多次请求 LLM、调用子 Agent、执行交接最终拿到的usage都是这些请求的总和。自动压缩会话的用量归并当使用OpenAIResponsesCompactionSession且其在运行结束前自动压缩历史记录时responses.compact请求上报的用量也会被加进同一运行的合计中。反过来如果在运行之外手动调用run_compaction()由于没有包裹它的运行上下文它不会去更新之前运行返回的 usage 对象。更完整的说明见 OpenAI Responses 压缩会话。第三方适配器下启用用量上报用量上报行为因第三方适配器与提供方后端而异。当通过第三方适配器访问模型、又需要准确的result.context_wrapper.usage值时注意以下两点使用AnyLLMModel只要上游提供方返回用量就会被自动透传但通过 Chat Completions 后端流式响应时可能需要ModelSettings(include_usageTrue)才会产生用量 chunk。使用LitellmModel部分提供方后端默认不上报用量因此常常需要设置ModelSettings(include_usageTrue)。include_usage字段定义于ModelSettings注释标明仅适用于 Chat Completions API——这是流式场景下能否拿到 usage chunk 的关键开关。具体部署前建议对照 Models 指南中的第三方适配器一节并在目标提供方后端上实测用量上报是否准确。逐请求用量追踪SDK 会自动把每一次 API 请求的用量记录在request_usage_entries中这对精细化的成本计算和上下文窗口占用监控非常有价值result await Runner.run(agent, Whats the weather in Tokyo?) for i, request in enumerate(result.context_wrapper.usage.request_usage_entries): print(fRequest {i 1}: {request.input_tokens} in, {request.output_tokens} out)每个条目是一个RequestUsage对象包含该单次请求的input_tokens、output_tokens、total_tokens以及各自的 details。聚合与明细的关系在源码 docstring 里有直观的例子一次运行发起 3 次 API 调用、输入分别为 100K / 150K / 80K token则聚合的input_tokens是 330K而request_usage_entries保留[100K, 150K, 80K]的分解便于逐项核算与上下文窗口管理。add()的合并逻辑src/agents/usage.py保证了明细不被吞掉如果被合并的Usage自带request_usage_entries则深拷贝后追加否则当它代表单次请求且有 token时会现场合成一个RequestUsage条目再追加。保留提供方原始用量载荷SDK 默认会把各提供方的用量统一规范化为跨模型一致的Usage字段。当应用需要保留提供方特有的 usage 字段或者需要区分字段缺失与提供方上报为 0时把ModelSettings.preserve_raw_usage设为Truefrom agents import Agent, ModelSettings, Runner agent Agent( nameAssistant, model_settingsModelSettings(preserve_raw_usageTrue), ) result await Runner.run(agent, Whats the weather in Tokyo?) for response in result.raw_responses: print(response.raw_usage)机制层面的要点如下每个ModelResponse.raw_usage保存的是该次模型调用提供方载荷的一份分离的、JSON 兼容的快照由_raw_usage_snapshot()在规范化之前抓取见 src/agents/usage.py。SDK不跨运行聚合raw_usage。当保存被禁用、提供方未返回用量载荷或上游适配器已经丢弃了原始字段存在性信息时该值保持为None。快照抓取失败例如无法 JSON 序列化的适配器特有值不会让一次本应成功的模型调用失败而是静默返回None——因为用量保留本质是诊断元数据。需要特别注意的是preserve_raw_usage只保留到达模型适配器的用量载荷它本身并不会向提供方请求用量。因此当流式 Chat Completions 提供方要求显式请求用量时还需要同时设置ModelSettings(include_usageTrue)。适配器差异LitellmModel 的原始用量限制当前LitellmModel在流式与非流式运行中都不会填充ModelResponse.raw_usage所以对LitellmModel而言preserve_raw_usageTrue无效。使用该适配器时请继续使用规范化的Usage字段若确需提供方特有的字段存在性信息则应选择支持原始用量保留的适配器。结合会话Session使用使用Session例如SQLiteSession时每次Runner.run(...)都会返回该次运行专属的用量。会话只为上下文保留对话历史但各次运行的用量相互独立session SQLiteSession(my_conversation) first await Runner.run(agent, Hi!, sessionsession) print(first.context_wrapper.usage.total_tokens) # Usage for first run second await Runner.run(agent, Can you elaborate?, sessionsession) print(second.context_wrapper.usage.total_tokens) # Usage for second run一个容易忽略的细节会话虽然保留了运行之间的对话上下文但历史消息会作为输入被重新喂给后续的每次运行因此后续轮次的输入 token 数会随之增长——这也是多轮对话成本持续攀升的根源。RunState 检查点中的用量RunResult.to_state()会捕获截至当前已累计用量的一份独立快照。从该检查点恢复的运行以捕获的总量为起点再累加自己模型调用的用量恢复后的运行不会把新合计写回原RunResult也不会写回由该结果派生的其他检查点first await Runner.run(agent, First request) checkpoint_a first.to_state() checkpoint_b first.to_state() resumed_a await Runner.run(agent, checkpoint_a) resumed_b await Runner.run(agent, checkpoint_b) assert resumed_a.context_wrapper.usage is not first.context_wrapper.usage assert resumed_b.context_wrapper.usage is not resumed_a.context_wrapper.usage这种隔离同样作用于Usage内部的request_usage_entries列表。唯一的例外是恢复后的嵌套Agent.as_tool()运行其恢复后的模型用量会被有意地聚合进外部活跃运行的用量中与其恢复前的模型调用行为保持一致——即嵌套运行始终并入最外层运行的独立记账。在 Hook 中利用用量使用RunHooks时每个 hook 收到的context对象都带有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)这适用于所有传入RunContextWrapper的 hook 回调例如 agent 结束、交接、工具调用等时机。值得注意的是RunContextWrapper.usage本身就是整个运行过程中被持续累加的那个字段因此 hook 里读到的就是到目前为止的真实用量非常适合做单次运行的成本审计日志。序列化与追踪集成除了在代码中读取Usage还提供了一组序列化辅助src/agents/usage.py供存储与追踪系统复用serialize_usage()把Usage转成 JSON 友好的字典包含request_usage_entries完整明细deserialize_usage()从序列化数据重建Usage兼容历史快照例如旧版本缺少cache_write_tokens字段并做了容错兜底model_usage_to_span_usage()为追踪 span 输出完整的逐模型调用用量total_usage_to_span_metadata()/turn_usage_to_span_data()/task_usage_to_span_data()为追踪元数据输出聚合计数含cached_input_tokens、cache_write_input_tokens。这意味着你可以把每次运行的用量落库做长期成本分析也可以直接与 docs/tracing.md 描述的追踪链路打通在 span 元数据中看到每次任务/轮次的 token 消耗。API 参考速查Usage— 用量追踪数据结构聚合总量 逐请求明细 token 细节RequestUsage— 单次请求的用量详情RunContextWrapper— 从运行上下文访问用量RunHooks— 接入用量追踪生命周期on_agent_end等回调ModelSettings.preserve_raw_usage— 保留提供方原始用量载荷ModelResponse.raw_usage— 单次模型调用的原始用量快照总结用量追踪的五个实用心法默认可用result.context_wrapper.usage开箱即得聚合用量无需任何配置request_usage_entries天然保留逐请求明细。流式场景记得开include_usageChat Completions 后端流式响应、以及LitellmModel下的多数提供方都需要ModelSettings(include_usageTrue)才会回报用量。原始载荷按需开启需要提供方特有字段或区分缺失 vs 为 0时用preserve_raw_usageTrue但它不主动向提供方要数据且对LitellmModel无效。会话与检查点各自独立会话只共享对话历史不共享用量to_state()产生的检查点携带用量快照恢复后的运行从快照继续累加。hook 是轻量计费点在RunHooks回调里通过context.usage记录每个生命周期节点的用量配合序列化辅助即可落地完整的成本分析链路。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考