Skip to main content
需要帮助？
在 Discord 提问提交 GitHub Issue支持指南

​
摘要

这个 starter 展示一个很小的、围绕 agent runtime cost controls 组织的 提示词缓存感知型智能体循环：先放稳定提示词层，再放动态记忆，并用 一个小型 benchmark 表面比较冷启动和热启动运行元数据。

​
状态

starter 源代码：patterns/examples/prompt-cache-agent-starter

​
为什么存在

提示词缓存很容易描述，也很容易误用。构建者常常把检索记忆、 用户特定事实或当前回合输入放进同一个长前缀里，同时又期待提供方 缓存这个前缀。这样会让缓存行为更难推理。 这个 starter 把边界显式展示出来。它把工具清单、系统指令和稳定 参考上下文视为可缓存层，而把持久化记忆摘要和当前任务放在缓存 前缀之外，除非构建者有意提升它们。

​
Agent Runtime Cost Controls

最近的 agent SDK 变化再次说明，提供方的计费规则和价格表可能比一页 handbook 更新得更快。更持久的经验是把运行时成本边界保持为可检查的 对象：
  • 把工具、系统指令和共享参考上下文视为稳定前缀
  • 把用户特定记忆、当前回合任务和易变工具输出放到请求后段
  • 分开跟踪 cache write 和 cache read，这样 warm rerun 是否真的更便宜 就可以被验证，而不只是更短
  • 在把 token 计算变成预算或客户计费之前，把 SDK 侧估算与提供方侧的 使用量报告分开比较
这个 starter 仍然保持提供方无关，但 Anthropic 和 OpenAI 当前文档现在 都在强化同一个模式：稳定前缀会提高缓存复用率，运行时使用量字段会揭示 缓存命中是否真的发生，而显式成本控制应该放在 operator loop 中，而不是 靠猜测。

​
相关实验室页面

​
文件结构

​
包含的示例文件

  • src/prompt_cache_agent_starter.py：提示词层、缓存边界检测、 使用量摘要，以及冷启动和热启动对比的 typed helper
  • tests/test_prompt_cache_agent_starter.py：这个 starter 行为的可执行 冒烟测试
  • SOURCE_NOTES.md：来源脉络和归属边界

​
流程边界

这个 starter 可以：
  • 将提示词层建模为可缓存或动态
  • 计算稳定前缀在哪里结束
  • 比较缓存读取和缓存写入占比
  • 在提供当前价格值时估算输入成本
当你把它映射到真实运行时里时，请保留三类分开的检查：
  • 一个在循环跑太远之前就生效的 stop condition 或 budget control
  • 能显示重复前缀是否真的被复用的 cache-specific 使用量字段
  • 一个独立于本地估算之外的 authoritative usage export 或 admin API
这个 starter 不应：
  • 调用真实 API
  • 存储原始对话 transcript
  • 硬编码提供方价格
  • 默认把持久化记忆折叠进缓存前缀

​
快速开始

从仓库根目录运行：

​
下一步

  • 增加一个读取脱敏 Claude 使用量元数据的提供方适配器。
  • 增加一个仅用于文档报告示例的小型 JSONL fixture。
  • 如果 benchmark 流程变得更适合探索式使用，再增加配套 notebook。