Claude on 鬼哥的空间

别让 Fable/Opus 干杂活：Agent 系统的省钱架构

Thu, 09 Jul 2026 00:00:00 +0000

你开发 Agent 的时候，是不是也干过这种事：

不管任务大还是小，先把 Fable/Opus 请出来，一路从查网页、搬数据、整理表格，撸到最后写报告。

鬼哥以前也经常这么干。刚开始是图省事，也确实希望结果尽量好。至于更深层的原因，大概是经验不足，手艺还菜，这句不要外传。

直到后来看到 API 账单，整个人就清醒了。

开法拉利去跑货拉拉，当然快。但快归快，油钱是真的遭不住。

用 Fable/Opus 去读网页、搬资料、整理表格，也有点像拿炮弹打苍蝇。不是打不中，而是太贵、太吵，还容易把桌子一起掀了。

所以我最近翻了几篇 Anthropic 关于 Advisor Tool、Managed Agents 和 multi-agent workflow 的技术文章，发现它们表面上是在讲 Claude 的新能力，底层其实在讲一件更工程化的事：

Agent 系统的成本，不只取决于你用了哪个模型，更取决于你有没有把任务拆对。

这篇文章不做文档复读。我们直接把它抽象成一套可复用的 Agent 省钱架构。

先看一个调研任务：拿 Opus 打苍蝇是怎么发生的

假设你要做一个知识调研：

对比 10 个 AI 编程工具的 Agent 架构、定价、上下文管理、工具调用能力，并给出选型建议。

很多人的第一反应是：直接丢给 Fable/Opus。

1
2


Fable/Opus 单体 Agent：
搜索网页 -> 阅读文档 -> 抽取事实 -> 整理表格 -> 对比分析 -> 写最终报告

这当然能做。

但你仔细看一下任务链条，会发现里面大量步骤其实不需要顶级推理能力：

步骤	需要什么能力	是否值得用 Fable/Opus
搜索官网和文档	覆盖率、耐心、工具调用	不太值
读取定价页	信息抽取	不太值
整理上下文长度、工具能力	结构化归纳	不太值
交叉验证来源	仔细、可重复	通常不需要
判断适合什么团队	产品判断、架构取舍	值
识别长期风险	深度推理、经验迁移	值

也就是说，80% 的 token 可能烧在“搬信息”上，但真正需要 Fable/Opus 的，是最后 20% 的判断。

更合理的拆法应该是这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


Sonnet coordinator：
 设计调研维度，拆分任务，规定输出格式，验收结果

Haiku / cheaper workers：
 并行搜索、读取网页、抽取事实、保留来源

Sonnet executor：
 合并结构化结果，发现冲突，要求补查

Fable/Opus advisor：
 在最终选型、风险分析、架构判断时介入

这不是为了“少用好模型”，而是为了把好模型用在刀刃上。

Fable/Opus 应该像会议室里最后拍板的专家，而不是从早到晚跑腿打印材料的人。

Advisor Tool：Sonnet 干活，Fable/Opus 把关

第一种实现手段，是 Advisor Tool。

它的模式很简单：

1
2
3
4


Sonnet executor
 -> 遇到复杂判断
 -> 调用 Fable/Opus advisor
 -> Sonnet 继续执行

这像什么？

像一个靠谱的项目经理在推进日常工作，遇到架构选型、安全边界、产品取舍这种“错了会很贵”的节点，再把资深专家叫进来。

Advisor 不是另一个执行员，也不是全程陪跑的老板。它更像关键决策时被请进会议室的人。

适合它的任务有几类：

Sonnet 能稳定推进，但中间有少数非显然设计决策
任务链很长，全程用 Fable/Opus 成本过高
需要在关键节点做风险审查、策略纠偏、方案选择
coding agent、computer use、多步研究这类“执行量大、判断点少”的任务

反过来，不适合的场景也很明确：

单轮问答
每一步都需要强推理
任务太小，advisor 调用成本超过收益
executor 还没收集上下文，就急着问 advisor

这里最重要的实践不是“能不能调用更强模型”，而是什么时候调用。

我的判断标准是：

如果这个决策错了，后面会产生大量返工，就值得问 Fable/Opus；如果只是搬资料、改格式、补字段，交给 Sonnet 或更便宜的模型就够了。

Advisor Tool 的价值，正在于它把模型能力做了纵向分层：

角色	适合模型	主要职责
Executor	Sonnet	推进任务、调用工具、落地修改
Advisor	Fable/Opus	复杂判断、风险提示、策略纠偏
User	人	目标定义、偏好确认、最终接受

一句话总结：

Sonnet 负责把车开起来，Fable/Opus 负责在岔路口提醒你别开进沟里。

Managed Agents：把一个大任务拆成一支小队

第二种实现手段，是 Managed Agents。

Advisor 是纵向升级，Managed Agents 是横向分工。

它的基本结构是：

1
2
3
4
5
6


Sonnet coordinator
 -> research worker A
 -> research worker B
 -> validation worker C
 -> review worker D
 -> coordinator 综合结果

每个 worker 有自己的上下文、工具和任务边界。它不需要知道全局目标的所有细节，只要把自己那一小块做好。

这件事非常关键。

很多单体 Agent 的失败，不是因为模型笨，而是因为上下文被污染了：

读了太多网页，噪音进入上下文
工具输出太长，关键信息被淹没
前面一个错误判断影响后面所有步骤
权限全开，风险边界变大
最后模型已经分不清哪些是事实，哪些是推测

Managed Agents 的价值，不是“模型数量变多所以更聪明”，而是三件事：

价值	解释
上下文隔离	每个 worker 只看自己需要看的材料
并行吞吐	多个资料源、多份文件、多条事实可以同时处理
权限隔离	调研 worker 不一定需要写文件，代码 worker 不一定需要外网

回到前面的 AI 编程工具调研案例。

你可以让每个 worker 只负责两个工具：

1
2
3
4
5


Worker A：调研 Cursor、Windsurf
Worker B：调研 Claude Code、Codex
Worker C：调研 Devin、OpenHands
Worker D：调研 Replit Agent、Gemini CLI
Worker E：交叉检查定价和上下文窗口

每个 worker 的输出必须结构化，比如：

1
2
3
4
5
6
7
8
9


工具名称：
官方链接：
Agent 架构：
上下文管理：
工具调用能力：
定价：
适合人群：
不确定点：
引用来源：

这样 coordinator 拿到的不是一堆网页碎片，而是一组可比较的事实卡片。

这就是多 Agent 的正确姿势：worker 负责吞吐，coordinator 负责验收，不要让最终答案变成 worker 摘要的简单拼接。

Plan Big, Execute Small：真正值得偷走的范式

第三篇 cookbook 里最值得记住的，不是那个具体案例，而是它背后的范式：

1
2
3
4
5
6
7
8


Plan Big：
 Sonnet / Fable / Opus 制定计划、定义维度、设计验收标准

Execute Small：
 Haiku / cheaper workers 并行搜索、读取、抽取、验证

Review Hard：
 Sonnet 汇总冲突，Fable/Opus 做最终判断或策略建议

翻译成人话就是：

大模型负责问题定义，小模型负责信息吞吐，强模型负责判断和验收。

这套模式特别适合几类任务：

多网页知识调研
多文件代码库扫描
多产品竞品分析
多事实交叉验证
长文档消化和结构化摘要
“先查很多东西，再做少数关键判断”的工作流

它为什么有效？

因为很多复杂任务的成本结构并不均匀。

你以为最难的是“写最终报告”，其实最费 token 的往往是：

把 20 个网页读完
从文档里抠出字段
对齐不同来源的说法
反复检查链接和引用
整理成统一格式

这些事情需要耐心、覆盖率和结构化输出，但不一定需要 Fable/Opus 级别的判断力。

不过，多 Agent 也不是银弹。

最容易踩的坑有四个：

坑	结果
拆得太碎	调度成本超过收益
worker 输出太自由	coordinator 难以比较和验收
coordinator 只拼接	错误会被包装成“综合结论”
关键证据不保留	最终判断无法追溯

所以，Plan Big, Execute Small 不是“把任务随便丢给一堆小模型”，而是要先设计好三件事：

拆分边界：每个 worker 负责什么，不负责什么。
输出格式：worker 必须交付什么字段、证据和不确定性。
验收标准：coordinator 如何发现冲突、追问缺口、决定是否升级给 Fable/Opus。

怎么选架构：别先问模型，先问任务

很多人在设计 Agent 系统时，第一句就是：

我该用 Sonnet，还是直接上 Opus？

这个问题问早了。

更好的顺序是：

这个任务里，哪些步骤只是读取、搜索、抽取？
哪些节点需要真正的判断？
哪些子任务可以并行？
worker 的输出如何验收？
如果判断错了，返工成本高不高？
Fable/Opus 应该在哪些位置介入，才最值？

你可以用这张表快速判断：

任务类型	推荐方案
单轮问答	直接 Sonnet 或 Fable/Opus
普通工具执行 + 少数复杂判断	Sonnet executor + Fable/Opus advisor
大量网页、文件、事实调研	Sonnet coordinator + cheaper workers
高价值研究报告	Sonnet coordinator + workers + Fable/Opus final review
代码库大规模扫描	Coordinator + specialized workers
每一步都需要深推理	直接 Fable/Opus，少拆
小任务	不要多 Agent，调度成本不值

这里的关键不是“多 Agent 一定比单 Agent 好”，而是：

当任务可以拆、证据可以结构化、验收标准可以定义时，多 Agent 才有意义。

如果任务本身是连续推理，比如数学证明、复杂算法设计、哲学论证，你硬拆成一堆 worker，反而可能把思路打碎。

真正的省钱架构：让每个模型做它最值钱的事

回到开头那个比喻。

Fable/Opus 当然可以读网页、搬资料、整理表格。就像炮弹当然可以打苍蝇。

问题是：你为什么要这么打？

好的 Agent 系统，不是把所有事情都交给最强模型，而是把任务拆成三层：

层级	职责	典型模型
吞吐层	搜索、读取、抽取、初步整理	Haiku / cheaper workers
执行层	调度、工具调用、合并、落地	Sonnet
判断层	架构取舍、风险分析、最终审查	Fable/Opus

最后留下一个很实用的判断：

如果一个步骤没有明显的判断成本，就不要默认交给最贵的模型。
如果一个决策会影响后面大量工作，就不要吝啬请 Fable/Opus 把关。

这才是 Agent 系统真正的省钱架构。

不是不用强模型，而是让强模型出现在它最值钱的位置。

参考资料

别再调教模型了：聪明人都在设计循环

Wed, 10 Jun 2026 00:00:00 +0000

Anthropic 的工程师 Boris Cherny 有一句话被反复引用：「我的工作就是写循环（My job is to write loops）。」

这句话第一次听像段子，听第二遍你会发现它在描述一个范式转移。过去我们用大模型，本能是去「调教」它——改 prompt、加 few-shot、写一长串「你必须……你不能……」的规则。但当模型本身已经足够强，真正决定产出质量的，往往不再是你怎么指挥它，而是你给它套了一个什么样的循环。

Anthropic 的 Lance Martin 最近分享了他用新一代 Claude 模型（内部代号 Fable 5，Mythos 级别）做实验的两个心得。两个都不是 prompt 技巧，而是关于怎么设计循环。下面我把它整理成中文，并加上我自己的一些体感。

为什么是「循环」，而不是「prompt」

先说清楚这个范式差在哪。

传统用法是一次性的：你写一个尽可能完美的 prompt，模型吐一个答案，好不好全看这一发。这本质上是在赌模型的「直觉」。

循环用法是迭代式的：你不再追求一发命中，而是给模型套一个「跑 → 拿反馈 → 自我纠正 → 再跑」的环，让它在一个评判标准（goal 或 rubric）上不断爬坡，直到达标才停。

	一次性 prompt	设计循环
你优化的对象	prompt 本身	环境与反馈信号
模型的角色	一次输出	反复试错、自我修正
决定质量的关键	你的措辞	评判标准设计得好不好
适合的任务	简单、确定性强	长程、可验证、能爬坡

Claude Code 里的 /goal 和 Claude Managed Agents（CMA）里的 Outcomes，就是把这套通用配方变成了你能直接用的原语。它们的本质都是：给环境注入一个反馈信号，让模型自己跟这个信号死磕。

第一招：自我纠正循环

新模型一个被反复验证的特性是——它特别擅长在循环里自我纠正。一个设计良好的 goal 或 rubric，相当于给 Claude 运行的环境加了一个反馈源：它跑一轮、通过 goal/rubric 收集反馈、修正自己，然后继续，直到标准被满足。

这里有一个最容易被忽略、却最关键的点：谁来当裁判。

直觉上你可能觉得，让模型自己检查自己的输出不就行了？但 Anthropic 的实验反复发现，模型在「自我批判」上是有系统性缺陷的——它很难客观地挑自己输出的毛病（Prithvi Rajasekaran 在 Anthropic 工程博客里专门写过这个现象）。

解法是：用一个独立的 verifier 子 agent 来打分，而不是让主 agent 自我批判。 因为打分是在一个独立的上下文窗口里完成的，不受主 agent 思路的污染，效果明显更好。CMA 的 Outcomes 就是帮你自动 spawn 一个 grader 子 agent 来做这件事。

下面这张表把两种实现方式拆得很清楚——无论是 Claude Code 的 /goal 还是 CMA 的 Outcomes，骨架都是一样的五件套：目标、裁判、循环、边界、退出条件。

注意「裁判（The judge）」这一行：/goal 用一个独立的 grader 模型（Haiku），CMA 用一个独立的 grader 子 agent——两者都刻意把评判放到了主流程之外。 这不是实现细节，这是这套方法能 work 的核心原因。

Parameter Golf：一个能跑 8 小时的玩具实验

Lance 用了一个开源的 ML 工程挑战 Parameter Golf 来测试：在 8 张 H100 上、10 分钟内，训练出一个能塞进 16MB 的最强模型。

这个挑战很像 Karpathy 的 autoresearch 项目——它考验的不是模型会不会写代码，而是一个 agent 能不能像研究员一样工作：改训练代码（一个 train_gpt.py 文件）、启动训练、轮询日志、读分数、然后决定下一个实验做什么。这是一个典型的长程、可验证、能爬坡的任务，正好是循环的主场。

他给了一个有 9 条可检查标准的 rubric（比如「跑一个 baseline」「跑 20 个实验」），让 Parameter Golf 最多跑 8 小时，由 Outcomes 的 grader 确认所有标准都满足后才允许 Claude 停手。结果：

Fable 5 把训练 pipeline 优化了约 6 倍于 Opus 4.7。 但比这个数字更有意思的是两个模型的实验风格差异：

Fable 5 敢下「结构性」的大注（比如改架构：TRAIN_SEQ_LEN=2048 带来 −0.0179、overlapped sliding-window eval 带来 −0.0207），而且有韧性——它甚至顶着一次量化回退继续推，最后拿到了最大的一次提升。
Opus 4.7 第一个实验拿了个小赢，然后几乎所有后续实验都在复制同一个模板：调一个标量、测一下、有正收益就留下。稳，但天花板低。

看图里那条蓝线（Fable 5）是怎么一个台阶一个台阶往下砸的，红线（Opus 4.7）则基本是平的——这就是「敢赌结构性改动」和「只敢调标量」的区别。循环给了模型试错的空间，而更强的模型会用这个空间去下更大的注。

第二招：记忆——跨会话的外层循环

如果说自我纠正是单次会话内的内层循环，那记忆就是跨会话的外层循环：Claude 在一次会话里把经验写进记忆，这些记忆能在未来的会话里被取回。

Lance 用 Continual Learning Bench 1.0 里的一个任务来测：给 agent 一个 SQL 数据库，让它回答一连串问题。每个问题是一个独立的 agent 会话，会话之间靠记忆来传递经验。他用 CMA 的记忆功能给每个 agent 挂载一个可跨会话共享的文件系统。

他观察到，有效使用记忆是有梯度的，从低到高是这么一条进阶链：

失败（fail）：做错了，把它记下来
调查（investigate）：在继续之前，搞清楚为什么错
验证（verify）：把诊断变成一个被核实过的事实
提炼（distill）：把验证结果升华成一条通用规则
查阅（consult）：下次直接读这条规则，而不是重新推导一遍

三个模型卡在了不同的台阶上，差距非常直观：

模型	卡在哪一步	表现
Sonnet 4.6	第 1 步（失败）	记忆只是一堆失败笔记和没验证的猜测（「也许是 prc 不是 prc_usd？」），几乎不回头查阅。得分 0.330，跟无记忆的 baseline 几乎没差
Opus 4.7	第 3 步（验证）	会建带不确定标记的 schema 参考（「可能是以分为单位？待验证」），但验证覆盖率低，只有 7–33%（中位数约 17%）。得分 0.700
Fable 5	走完全程	最强的几次运行里验证覆盖率高达 73%（30 题里验证了 22 题），并能把学到的东西提炼成通用规则，反哺未来任务。得分 0.839

看右边那张收敛曲线特别有感觉：带记忆的实线和无记忆的虚线，差距随着问题数累积越拉越大。 记忆不是「记下来」就完事了，关键在于你的 agent 能不能走完「失败 → 调查 → 验证 → 提炼 → 查阅」这条链。Sonnet 4.6 停在记笔记，Fable 5 在建知识库——这就是 0.330 和 0.839 的差距。

一个实操提醒：如果你的模型只走到第 1 步（像 Sonnet 4.6 那样），你需要给它针对具体任务的记忆指令来往上推。记忆这东西，模型越弱越需要你手把手教它怎么用。

我的体感：这其实是在重新分配「智能」

整理完这两个实验，我自己最大的感受是：Agent 工程正在从「怎么问」转向「怎么搭环境」。

过去一年我自己用 Claude Code 的体验也印证了这点。早期我花大量时间打磨 prompt，恨不得把每一步都写死。但模型一强，这套做法的边际收益就崩了——你写的规则越细，反而越限制它。真正让产出质变的，是另外两件事：

给它一个可验证的目标，然后闭嘴让它自己跑。/goal 这类原语的价值就在这——你定义「什么叫做完了」，剩下的交给循环。
让它管理自己的上下文，包括往记忆里写、从记忆里读。你不需要每次都把背景重新喂一遍。

Lance 那句话我很认同：与其直接 prompt 和 steer 模型，不如设计循环，让模型自己根据环境反馈做自我纠正（比如 /goal 或 Outcomes），并管理自己的上下文（比如记忆）。

换个角度说，你作为工程师的「智能」，正在从「写在 prompt 里」迁移到「写在循环结构里」。前者是一次性的指令，后者是可复利的系统。

Takeaway：下次构建 Agent，先问自己四个问题

如果你也想用循环的思路构建 agent，把下面四个问题贴在显示器上：

目标可验证吗？ 能不能写出一个 rubric / goal，让一个独立的裁判明确判断「做完了没有」？如果不能，先把任务拆到能验证为止。
裁判独立吗？ 千万别让主 agent 自我批判。用一个独立的 grader 模型或子 agent，在干净的上下文里打分。
循环有边界吗？ max_iterations、时间上限、退出条件——别让它无限跑。
记忆走完链路了吗？ 检查你的 agent 是停在「记笔记」，还是真的在「失败 → 调查 → 验证 → 提炼 → 查阅」。停在第一步的记忆约等于没有。

想上手的话，可以直接问最新版的 Claude Code——它能用内置的 /claude-api skill 告诉你 Fable 5 的 prompting 最佳实践、/goal、Claude Managed Agents 这些 API 特性怎么用。

说到底，写 prompt 是在赌一次直觉，设计循环是在搭一套能自我改进的系统。 模型越强，后者的回报越高。

参考资料

原推文：Lance Martin (@RLanceMartin) — Designing loops with Fable 5
Parameter Golf：开源 ML 工程挑战（16MB 模型，10 分钟，8×H100）
Continual Learning Bench 1.0：跨会话记忆基准

Claude-Cookbooks 全景导航：被 README 藏起来的另一半

Sat, 18 Apr 2026 00:00:00 +0000

最近 AI 的发展真的是日行千里。

每天打开手机开源社区、翻公众号、过一遍 GitHub Trending——新模型、新工具、新系统、新应用，再加上无数业内高人分享的实践经验，内容浩如烟海，百家争鸣，百家齐放。

说实话，我自己看着都眼花缭乱。有时候晚上躺下想到"今天又没来得及看那几篇论文、那几个新项目"，连睡觉都觉得是在浪费学习时间。

这种状态持续久了，人是会焦虑的。鬼哥每天拼命学习, 拼命实践, 都快忘了自己还是个吉他手, 也得花时间练琴了.

但前阵子我沉下心来，花了一段时间认真翻了一遍 Anthropic 官方的这份 claude-cookbooks——翻完之后我反倒松了一口气。

这份仓库里的内容，积累了 Anthropic 工程师过去三年对 AI 工程化的思考。覆盖面非常全：从 API 最基础的用法，到 Prompt Caching 的成本优化，到 Tool Use 的各种进阶模式，再到 Agent SDK、Managed Agents、Skills 这些最近才成型的产品形态——几乎把"怎么用好 Claude 做一个能上生产的 AI 应用"这件事，从头到尾挨个讲了一遍。

宝藏是真的多，内容也真的多。想用一两篇文章讲清楚根本不现实。

所以我决定先写这一篇——给这份指南做一个大致的梳理，整理出一份索引地图。 后面每个具体话题，再单独开长文展开。

也建议你把这份 cookbook 当作一份可以反复查、反复学的学习地图：不需要一次读完，但值得在接下来几个月里反复回来翻。

你打开 anthropics/claude-cookbooks 的 README，看到的大概是十几条链接——分类、RAG、摘要、几个 tool use 示例、一篇 prompt caching。

如果你只看 README，会以为这就是一份写了两年没人管的老项目。

但你往目录里翻一下就会发现——这份仓库里塞着接近一百篇 notebook，README 里能看到的，大概只占三分之一。

被 README 藏起来的另一半，恰恰是这两年 Anthropic 官方重点推进的东西：Claude Agent SDK 教程、Managed Agents 的 CMA 系列、Skills 技能包、Tool Use 的进阶玩法、Extended Thinking 和 Tool Search 的新模式……这些内容散落在 claude_agent_sdk/、managed_agents/、skills/、patterns/agents/ 这些 README 完全没提的目录下。

这篇文章做的事很简单：把这份 repo 按主题重新整理成一张可以反复查的索引地图。 每个模块一句话定位、列出具体 notebook 文件名、说清楚什么时候该看它——后面想逐篇深入的时候，翻这一页就知道从哪下手。

不做深度拆解，只做导航。真正的"为什么要这么设计"那种长文，留给后面每个主题单开一篇来写。

一、先把这份 repo 的定位搞清楚

在往下看之前，先明确一件事：claude-cookbooks 不是文档的补充，而是可跑的工程示例库。

Anthropic 官方的内容资源现在大致分成三层：

资源	角色	面向
docs.claude.com	权威文档	查 API 参数、模型特性
anthropics/courses	入门课程	第一次接触 API 的开发者
anthropics/claude-cookbooks	工程菜谱	已经会调 API、想把某个具体场景做好的人

Cookbook 是"可执行的最佳实践"：每个 notebook 就是一个最小可跑的场景，装完依赖、填上 API key 就能复现。它的价值不在于"教你 Claude 是什么"，而在于"别人做过这件事，代码给你抄走"。

换句话说，文档告诉你某个 API 参数是什么意思，cookbook 告诉你在真实场景里这个参数应该怎么配、还要和哪几件事配合用。这两者是互补的——文档适合查细节，cookbook 适合找套路。

这也解释了为什么它的更新节奏跟着 Anthropic 的产品线走——每出一个新产品或新能力，这里就会多一个目录。Claude Agent SDK 发布之后有了 claude_agent_sdk/，Managed Agents 发布之后有了 managed_agents/，Skills 功能上线之后有了 skills/。所以它也是观察 Anthropic 官方工程重点转向的一个风向标。

一个小提醒：README 里的链接还是旧的 anthropic-cookbook 仓库路径（目录名对，仓库名已改成 claude-cookbooks）。clone 的时候用新名字，跟着链接点进去会被 GitHub 自动重定向，不影响看内容，但会让你怀疑自己是不是 clone 错了库。

二、一张总览图：20 多个目录怎么归类

仓库里大大小小二十多个目录，我按"使用场景"把它们重新归了一下组：

大类	涉及目录	解决的问题
基础能力	`capabilities/` `multimodal/` `extended_thinking/`	Claude API 开箱即用能做的事
Tool Use	`tool_use/`	让模型调用外部工具
性能与成本	`misc/`（caching/batch 部分） `observability/`	Prompt caching、批处理、用量监控
Agent 三条路径	`patterns/agents/` `claude_agent_sdk/` `managed_agents/`	从模式→SDK→托管运行时的递进
Skills 技能包	`skills/`	打包专业能力给 Claude 调用
第三方集成	`third_party/`	Pinecone / Voyage / Mongo / Wolfram 等八家
评估与微调	`tool_evaluation/` `finetuning/` `misc/building_evals.ipynb`	Prompt eval、工具 eval、Bedrock 微调
工程实践（meta）	整个仓库的组织方式	uv / ruff / registry / slash commands

接下来按这个骨架一层层往里翻。

三、基础能力层：Claude API 开箱即用能做什么

3.1 `capabilities/` — 经典的 NLP 任务

这是整个 cookbook 里最"传统"的一块，也是大部分教程会从这里开始的原因——这些任务不依赖任何高级特性，一个 API key 就能跑：

classification/ — 文本分类。几个 prompt 模式对比，从 zero-shot 到 few-shot 到带 chain-of-thought 的长 prompt。
summarization/ — 摘要。包括长文分块摘要、多文档合并摘要、以及"按角色视角写摘要"这种进阶玩法。
retrieval_augmented_generation/ — RAG。从最基础的"向量检索 + 拼 prompt"到带 rerank、混合检索的几种设计。
contextual-embeddings/ — 这是比较新的一篇，讲 Anthropic 自己提出的"给每个 chunk 加一段上下文描述再 embed"的做法，在某些场景上能显著提升召回。
text_to_sql/ — 自然语言转 SQL，包括 schema 注入、错误恢复、结果校验。
knowledge_graph/ — 用 Claude 从文本抽取三元组、构建图谱。

如果你是刚开始用 Claude API 做项目，这块是"背景知识"——不是每篇都要精读，但至少扫一遍标题，知道什么场景能在这里找到参考实现。

contextual-embeddings/ 这篇值得单独提一下。传统 RAG 的 embedding 过程是直接把 chunk 扔进 embedding 模型，但很多 chunk 脱离上下文后其实没法检索——比如一段"它在第三季度增长了 12%"，没有"哪家公司 / 哪个产品"的上下文，embedding 向量就很泛。Anthropic 的做法是先用 Claude 给每个 chunk 生成一段上下文描述（“这段来自 XXX 公司 2024 Q3 财报的营收章节”），再和原文拼在一起去 embed。实测在有些场景上能把召回率提升 35% 以上，代价是 embedding 阶段的 prompt caching 必须做好，不然成本会飙。

3.2 `multimodal/` — 视觉能力

Claude 的 vision 能力现在已经是基础配置，这个目录把"怎么用好它"讲了一圈：

getting_started_with_vision.ipynb — 入门。base64 编码、URL 传图、多图一起传的几种姿势。
best_practices_for_vision.ipynb — 最佳实践。图片放在 prompt 的哪个位置、多图之间怎么编号、什么时候该先 OCR 再喂文字。
reading_charts_graphs_powerpoints.ipynb — 图表解读。财报柱状图、流程图、PPT 截图的实战。
how_to_transcribe_text.ipynb — 表单/手写稿 OCR。
crop_tool.ipynb — 让 Claude 自己决定"先裁图再看细节"的分步处理。
using_sub_agents.ipynb — 用 Haiku 做前置视觉处理，Opus 做最终决策的 sub-agent 模式。

3.3 `extended_thinking/` — 让模型"想得更久"

Extended Thinking 是 Claude 4 系列引入的能力，让模型在给出答案前先做一段内部推理：

extended_thinking.ipynb — 基础用法。怎么打开、thinking budget 怎么设、拿到的 thinking block 长什么样。
extended_thinking_with_tool_use.ipynb — 和 tool use 结合。这个组合比较微妙——model 在 tool call 之间保留 thinking context 的方式跟普通对话不一样，这一篇讲清楚了边界。

四、Tool Use 专题：整个 cookbook 最密的一块

tool_use/ 目录是更新最频繁、内容也最厚的一块。里面的 notebook 粗粗可以分成"基础用法"和"进阶玩法"两层：

基础几篇，先过一遍：

calculator_tool.ipynb — 第一次接触 tool use 必看，一个最简单的计算器示例。
tool_choice.ipynb — auto / any / tool（强制某个具体工具）三种模式的区别。
parallel_tools.ipynb — 一次响应里并发调多个工具。
extracting_structured_json.ipynb — 用 tool use 强制返回结构化 JSON，比裸 prompt 稳定得多。
tool_use_with_pydantic.ipynb — 直接用 Pydantic 模型定义 tool schema。
customer_service_agent.ipynb — 经典的客服机器人综合示例。

进阶部分，每篇都是一个独立课题：

memory_cookbook.ipynb + memory_tool.py — Claude 的 memory tool，让模型能读写自己的记忆文件。
programmatic_tool_calling_ptc.ipynb — PTC（Programmatic Tool Calling）。让 Claude 生成一段小代码来决定怎么调用一组工具，而不是一个个手动编排。
automatic-context-compaction.ipynb — 自动上下文压缩。长对话里如何在触发上限前让模型自己"总结前面然后丢掉"。这一篇和我之前写过的 Session 管理文章其实是同一套思路的底层实现。
tool_search_with_embeddings.ipynb + tool_search_alternate_approaches.ipynb — 工具太多塞不进 prompt 的时候怎么办。用 embedding 召回最相关的工具再喂给模型。
vision_with_tools.ipynb — 把 vision 输入和 tool use 混在一起用的注意事项。
threat_intel_enrichment_agent.ipynb — 威胁情报富化 Agent，一个比较完整的垂直场景实战。
context_engineering/ 子目录 — 专门讲上下文工程的一组 notebook，是相对独立的小专题。

这个目录是我个人会反复回来查的。基本上做任何一个需要"让模型调用外部能力"的项目，都能在这里找到至少一个相近的参考实现。

特别想点名 PTC 和 Tool Search 这两篇。 PTC（Programmatic Tool Calling）解决的是"工具编排逻辑比工具本身还复杂"的场景——比如你有 10 个工具需要按特定顺序调用并做中间结果处理，与其让模型一轮一轮 tool call，不如让它一次性生成一段编排代码，由你在沙箱里执行。这种做法在复杂工作流里能把 round-trip 次数从十几轮压到两三轮，延迟和成本都是数量级的改善。

Tool Search 解决的是另一类问题：工具数量多到塞不进 prompt。一个大型 Agent 系统可能挂了几百个 MCP 工具，全部塞进去既超 token 又污染模型判断。用 embedding 预先对工具做语义索引，按用户 query 召回 top-K 工具再喂给模型，是目前比较成熟的解法。这一篇讲清楚了实现细节和几种 trade-off。

五、性能与成本优化

做 Demo 的时候钱和速度都不敏感，但一旦到线上，成本和延迟立刻就会成为第一优先级问题。 这块内容散落在几个目录里，我挑出来单独放一节：

misc/prompt_caching.ipynb — Prompt caching 的基础用法。配合我之前那篇 Prompt Caching 深度拆解一起看效果最好：那篇讲"为什么要这么做"和底层 KV cache 原理，这篇告诉你"具体几行代码怎么写"。
misc/speculative_prompt_caching.ipynb — 推测式缓存。不等用户发消息，提前把可能的下一轮 prompt 预热进缓存。在某些低延迟场景下能把首 token 延迟打下去很多。
misc/batch_processing.ipynb — Message Batches API。离线批处理的价格是实时请求的 50%，跑评测、做回填数据时能省很多。
misc/session_memory_compaction.ipynb — 会话记忆压缩。和 tool use 里的 automatic-context-compaction 是配套关系，一个讲工具侧，一个讲消息侧。
observability/usage_cost_api.ipynb — Usage & Cost API。用来做团队用量看板、成本归因报表。
misc/using_citations.ipynb — Citations 功能。让 Claude 在回答里标注"这句话来自文档的哪一段"，做 RAG 产品时非常有用。
misc/sampling_past_max_tokens.ipynb — 当输出被 max_tokens 截断时怎么优雅续写。

这几篇单独看每一个都不长，但组合起来基本就是一个"线上项目优化清单"。上线前对着这张清单过一遍，能省下不少成本和踩坑时间。

有一个非常容易被忽略的组合用法：prompt caching + batch processing。Batch API 本身就打 5 折，再加上 caching 命中的部分又打 1 折左右，叠加下来做离线大规模推理时的成本可以比天真实现低 85% 以上。如果你在做评估、数据标注、回填历史数据这类离线任务，这个组合的经济性优势非常大，但大多数人做 MVP 时根本不会想到要用它。

六、Agent 的三条进阶路径

这是整个 cookbook 里我认为最值得花时间的一块，也是 README 最没讲清楚的一块。

Anthropic 把"怎么构建 Agent"拆成了三个层次递进的目录：

1
2
3


patterns/agents/ ← 模式层：概念和套路（轻量）
claude_agent_sdk/ ← SDK 层：用 Agent SDK 自己组装（中等）
managed_agents/ ← 托管层：用 Managed Agents 托管运行时（重型）

从左到右是"自由度递减、工程量递减"的关系。 哪一层适合你，取决于你要做的系统规模和运行需求。

6.1 模式层 `patterns/agents/` — 先把套路搞清楚

这个目录对应的是 Anthropic 那篇著名博客 Building Effective Agents 里提的几种基础模式的可运行版本：

basic_workflows.ipynb — Prompt chaining / Routing / Parallelization 三种基础工作流模式。
evaluator_optimizer.ipynb — 评估者-优化者模式。一个 Agent 输出、另一个 Agent 打分并反馈，循环到满足条件为止。
orchestrator_workers.ipynb — 编排者-工人模式。主 Agent 拆任务，子 Agent 并发执行。

这三篇是"概念打底"。哪怕你最后不用 Agent SDK，看一遍这三个模式，再去评估任何第三方 Agent 框架的设计，心里都会有一把尺子。

6.2 SDK 层 `claude_agent_sdk/` — 官方的 Agent 教程

这是 Anthropic 最近重点推进的一块，基于 claude-agent-sdk-python，六篇 notebook 是一条渐进式的教学路径：

#	文件	学到什么
00	`00_The_one_liner_research_agent.ipynb`	一行 `query()` 起一个研究 Agent，理解异步迭代和基础概念
01	`01_The_chief_of_staff_agent.ipynb`	CEO 助理 Agent——Memory、Output Styles、Plan Mode、Slash Commands、Hooks、子 Agent 编排全家桶
02	`02_The_observability_agent.ipynb`	可观测性 Agent，需要 GitHub Token + Docker
03	`03_The_site_reliability_agent.ipynb`	SRE Agent，处理告警和事故
04	`04_migrating_from_openai_agents_sdk.ipynb`	从 OpenAI Agents SDK 迁移过来的映射指南——有存量代码的团队重点看这篇
05	`05_Building_a_session_browser.ipynb`	Session 浏览器 demo，可视化 Agent 会话

这一条路径的隐含逻辑是：“你如果已经在用 Claude Code，那 Claude Code 背后的 Agent 内核就是 Agent SDK，你可以用同样的工具链做任何 Agent 应用，而不只是软件开发”。

01 这篇 Chief of Staff 我单独推荐——它是整个教程里最接近"生产级 Agent 到底长什么样"的那篇。里面把持久化记忆（CLAUDE.md 机制）、输出风格切换（给 CEO 发邮件 vs 给团队发内部备忘是两种语气）、Plan Mode（复杂任务先产出方案再执行）、Slash Commands（把高频操作做成可复用快捷方式）、Hooks（每次工具调用都自动写审计日志）、Subagent 编排（法务/财务/战略三个专项 Agent 分工协作）这一整套都串起来了。看完之后你会意识到，“Agent” 这个概念背后其实是一组工程约束的组合，单独拎出任何一个都不够，组合起来才是真正可以上生产的东西。

6.3 托管层 `managed_agents/` — Claude Managed Agents (CMA)

Managed Agents 是 Anthropic 相对较新的一个产品形态：服务端托管的 Agent 运行时，带沙箱、会话持久化、文件状态保留，你只要定义 Agent 和环境，剩下的交给托管服务。

这个目录分成两组：

三个应用型示例（适合先看，建立直觉）：

data_analyst_agent.ipynb — CSV 进、HTML 分析报告出的数据分析 Agent。
slack_data_bot.ipynb — 把上面那个分析 Agent 包成 Slack Bot。
sre_incident_responder.ipynb — 告警→调查→PR→人审→合并的完整 SRE 流程。

六个教程型 notebook（以 CMA_ 开头，建议按顺序读）：

Notebook	主题
`CMA_iterate_fix_failing_tests.ipynb`	入门。引入 agent / environment / session、文件挂载、流式事件循环
`CMA_orchestrate_issue_to_pr.ipynb`	issue → 修复 → PR → CI → 人审 → 合并的完整编排
`CMA_explore_unfamiliar_codebase.ipynb`	在陌生代码库里探索，含"过期文档陷阱"演示
`CMA_gate_human_in_the_loop.ipynb`	人类审批关卡，用自定义工具的 `decide()` / `escalate()` 模式
`CMA_prompt_versioning_and_rollback.ipynb`	提示词版本化与回滚——生产 Agent 的脆弱环节，中文圈讲得很少
`CMA_operate_in_production.ipynb`	生产部署：MCP 工具集、vault 存 per-user 凭证、webhook idle 模式

这一组是目前 cookbook 里最贴近"企业级 Agent 运营"的内容。如果你在做 B 端 Agent 产品，哪怕不用 Managed Agents，也强烈建议看一遍 prompt versioning 和 operate in production 这两篇——它们把"Agent 上线之后你还要做哪些事"讲得最清楚。

稍微展开一下 CMA_prompt_versioning_and_rollback.ipynb 为什么特别值得看：传统软件工程里代码改动有 Git、有 CI、有灰度发布，但 prompt 的改动目前很多团队还靠 Excel 或 Notion 维护。Prompt 不是代码但比代码更脆弱——同一个字改一下，模型行为可能完全变样。这篇 notebook 给出的答案是把 prompt 也纳入版本化体系：服务端存版本、每个 session 可以绑定到特定版本、用标注过的测试集做版本对比、发现回归可以按 session ID 批量回滚。这套工作流不依赖 Managed Agents 本身也能借鉴——核心思路是把 prompt 当成一等公民的配置来治理。

七、Skills 技能包

skills/ 目录对应的是 Claude 的 Skills 功能——打包好的"专业能力"，Claude 在需要的时候自动发现并加载。

核心理念是 Progressive Disclosure：技能定义不在每轮对话里都加载，只在模型判断"这个任务需要 Excel 能力"时才把 Excel skill 拉进来，从而节省 token。

这个目录下有三篇 notebook：

notebooks/01_skills_introduction.ipynb — 基础：加 beta header、创建第一个 Excel/PPT/PDF。
notebooks/02_skills_financial_applications.ipynb — 金融场景：投资组合报告、多格式工作流（CSV → Excel → PPT → PDF）。
notebooks/03_skills_custom_development.ipynb — 自定义 skill 开发：金融比率计算器、品牌指南 skill。

Skills 这个功能对应的是你在 Claude.ai 里看到的"Claude 帮你直接生成 Excel/PPT"那个能力。如果你想做类似的"让 Claude 产出真正可用的办公文档"的产品，这是唯一的官方路径。

Progressive Disclosure 这个机制值得单独理解一下。传统做法里，你要给模型扩展能力，通常是把所有工具定义、system prompt、知识都塞进每一轮对话——结果是你挂的能力越多，token 成本越高，而且大部分 token 根本用不上。Skills 的思路是把能力拆成有元数据的"技能包"，只在模型判断当前任务需要时才动态加载对应的代码和指令，本质上是一种 lazy loading + capability routing。这个设计思路在做大型 Agent 平台时非常关键，哪怕你不用 Skills 产品本身，理解它的机制对你设计自己的能力注入系统也有参考价值。

八、第三方集成一览

third_party/ 下有八家集成，都是最小可跑的对接示例：

目录	角色	典型场景
`Pinecone/`	向量数据库	RAG 召回
`VoyageAI/`	Embedding 模型	RAG、语义搜索
`MongoDB/`	文档数据库 + 向量搜索	一体化 RAG 后端
`LlamaIndex/`	RAG 框架	和 Claude 一起用的完整 pipeline
`Wikipedia/`	知识源	实时查询百科做事实补充
`WolframAlpha/`	计算/数学	精确数值计算、公式求解
`Deepgram/`	语音转文字	音频输入场景
`ElevenLabs/`	文字转语音	语音输出场景

这块适合按需查阅——你项目里用到哪家就去看哪篇，不需要通读。

九、评估与微调

这两块相对偏"工程化"，但一旦你开始做严肃点的 AI 产品就绕不过去：

misc/building_evals.ipynb — 自动化评估。用 Claude 当 judge 给自己的 prompt 打分。
misc/generate_test_cases.ipynb — 用 Claude 生成测试用例来做对抗性评估。
tool_evaluation/tool_evaluation.ipynb — 工具级评估。Agent 系统里每个 tool 调用是否正确、参数是否合理的专项评估。
misc/metaprompt.ipynb — Metaprompt：让 Claude 帮你写/优化 prompt。
misc/building_moderation_filter.ipynb — 用 Claude 搭内容审核过滤器。
finetuning/finetuning_on_bedrock.ipynb — 在 AWS Bedrock 上微调 Claude，附 datasets/ 示例数据。

微调这块目前官方只出了 Bedrock 路径的教程，直接从 Anthropic API 做 fine-tuning 目前还不是公开能力。

十、仓库工程实践：这本身就是一份"怎么管理 Notebook 项目"的样板

这一节是给另一类读者的——那些在自己团队里也要维护大量 notebook / 示例代码的工程师。

claude-cookbooks 这个 repo 本身的组织方式，其实是一份挺成熟的范本：

用 uv 做包管理。有 uv.lock 和 uv.toml，uv sync --all-extras 一键把所有依赖装齐。相比 pip install -r requirements.txt，速度快一个数量级，也更容易复现。
ruff 做 lint 和 format。行长 100、双引号。Notebook 里放宽了 E402（中间 import）、F811（重定义）、N803/N806（变量命名），这几条放宽对 notebook 写作很实用——Jupyter 里本来就会有大量这种"不优雅但可读"的写法。
pre-commit + Makefile + tox。make check / make fix / make test 三条命令覆盖日常。
registry.yaml + authors.yaml。每篇 notebook 在 registry.yaml 里登记标题、路径、作者、分类，方便后续站点化检索。这是一个很聪明的做法——内容和元数据分离，让 notebook 集合可以被当成一个可查询的数据库来对待。
.claude/ 目录 + 自定义 slash commands。/notebook-review（检查 notebook 质量）、/model-check（校验模型 ID 是不是用了非推荐的日期版本）、/link-review（检查死链）。这几个 slash command 既给人用，也给 CI 用。
lychee.toml。专门的死链检查配置，比自己手写正则靠谱。
CLAUDE.md 里写死模型 ID 规范。明确规定永远用非日期别名（如 claude-sonnet-4-6）而不是 claude-sonnet-4-6-20250514。这种小约定写在 CLAUDE.md 里，让 Claude Code 或其他 Agent 在写示例代码时不会跑偏。

这些细节如果你自己维护过一个 notebook 集合，应该能立刻 get 到它们的价值。我之前维护过几套内部示例代码，最大的痛点就是时间一长没人管，示例里的 API 调用方式和模型名全都过时了。claude-cookbooks 用 CI + slash command + 自动化校验把这件事从"靠人自觉"变成"靠流程保证"，是很值得抄的做法。

另一个细节是 registry.yaml 里每篇 notebook 都登记了分类标签和作者。这看起来只是一个 meta 索引文件，但它背后其实是一个内容运营思路：让示例集合既能被人读，也能被机器查询。未来如果要做一个"按类目筛选的交互式站点"或者"根据用户目标推荐 notebook 的 Agent"，registry.yaml 就是现成的数据源。把内容和元数据分开，永远比把元数据硬编码进 README 要更灵活。

十一、我接下来会按什么顺序往里钻

最后给自己留一份阅读路线图，也供参考：

如果你是第一次用 Claude API：

misc/prompt_caching.ipynb — 先把成本大头的底子打好
tool_use/calculator_tool.ipynb + tool_choice.ipynb — Tool use 基础
capabilities/retrieval_augmented_generation/ — 如果你要做 RAG
multimodal/getting_started_with_vision.ipynb — 如果涉及图像

如果你已经在用 Claude Code，想扩展到自定义 Agent：

patterns/agents/ 三篇 — 先把概念过一遍
claude_agent_sdk/00 → 01 → 04 — 沿着教程走
tool_use/memory_cookbook.ipynb + automatic-context-compaction.ipynb — 长会话 Agent 必备
managed_agents/CMA_operate_in_production.ipynb — 想上线再看这篇

如果你在做 B 端 Agent 产品：

managed_agents/ 全套六篇 CMA 教程
tool_evaluation/tool_evaluation.ipynb + misc/building_evals.ipynb — 评估不能缺
observability/usage_cost_api.ipynb — 成本监控
managed_agents/CMA_prompt_versioning_and_rollback.ipynb — 运营侧

结尾：这只是起点

写到这里回头看，这份 cookbook 里随便挑一个模块展开，都够单独写一篇长文：

Agent SDK 的六篇 notebook 值得一篇一篇拆，特别是 Chief of Staff 那篇里塞了一整套生产级 Agent 该有的能力
Managed Agents 这个新产品形态本身就值得一篇"它和 Agent SDK 到底什么区别"的分析
Tool Use 里的 PTC、Tool Search with Embeddings、Memory Tool 每一个单拿出来都能写一篇技术拆解
Skills 的 Progressive Disclosure 机制和它对 token 经济的影响，是个完整的专题
patterns/agents/ 对应的那三种设计模式，配合实际项目经验聊一聊会很有意思

这些我都打算一篇一篇写。这份导航文章就当是书签——以后每完成一篇深度拆解，就回来把对应的链接加上，让这里慢慢长成一张真正可用的学习路线图。

如果你也在看这份 cookbook，欢迎告诉我你最关心哪个模块，我排序的时候可以参考一下。

参考资料

anthropics/claude-cookbooks — 本文索引的主体
anthropics/claude-agent-sdk-python — Agent SDK 本体
anthropics/courses — 如果你还在更早的阶段，先看这个
Building Effective Agents — Anthropic 官方 Agent 设计方法论
Equipping agents for the real world with Skills — Skills 的设计理念

Claude Managed Agents：从聊天机器人到自主 Agent 的一步之遥

Thu, 09 Apr 2026 00:00:00 +0000

150 行代码就能造一个"数字分身"，但它只会聊天，不会做事。

如果它能帮你写代码、搜资料、跑脚本呢？

两个月前，我给博客做了一个 AI 数字分身——guige_avatar。访客点击右下角的聊天按钮，就能和"鬼哥"的 AI 分身聊技术、聊 AI、聊生活。

整个后端只有 150 行 JavaScript，部署在 Vercel 上，用的是 OpenAI 的 GPT-4.1-nano。它很轻量，也确实能用——但说实话，它只是一个穿了马甲的 Chat Completion API。

2026 年 4 月，Anthropic 推出了 Claude Managed Agents——一个托管式的 Agent 运行时平台。看完文档后我意识到：如果用 Managed Agents 重构鬼哥分身，它能从一个只会聊天的机器人，进化成一个真正能做事的自主 Agent。

本文就以这个真实案例为主线，带你理解 Managed Agents 到底是什么、能做什么、以及什么时候该用它。

一、手搓版：guige_avatar 架构剖析

先看看现在的数字分身长什么样。注意截图右下角那个小对话气泡——那就是访客与鬼哥 AI 分身聊天的入口。

1.1 整体架构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


访客浏览器 Vercel Serverless
┌─────────────┐ POST ┌──────────────────┐ ┌─────────┐
│ 博客首页 │ ─────────→ │ api/chat.js │ ───→ │ OpenAI │
│ 聊天面板(JS) │ ←───────── │ (~150 行) │ ←─── │ API │
└─────────────┘ JSON │ │ └─────────┘
 │ ↓ fire-and-forget│
 │ Telegram 通知 │
 └──────────────────┘
 ↑
 data/persona.yaml
 (人设 YAML ~200行)

1.2 核心代码：就这么简单

后端的核心逻辑可以浓缩成这几步：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


// 1. 加载人设 YAML → 构建 system prompt
const persona = yaml.load(fs.readFileSync('data/persona.yaml'));
const systemPrompt = buildSystemPrompt(persona);

// 2. 拼接历史（最多 10 轮）+ 当前消息
const messages = [
 { role: 'system', content: systemPrompt },
 ...history.slice(-10),
 { role: 'user', content: userMessage }
];

// 3. 一次 API 调用，返回结果
const response = await openai.chat.completions.create({
 model: 'gpt-4.1-nano',
 messages
});

没有 agent loop，没有工具调用，没有自主决策。每次请求就是一次单轮 LLM 推理。

1.3 人设工程：它的真正价值

guige_avatar 最精巧的部分不是代码，而是 persona.yaml——一个约 200 行的人设定义文件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


personality:
 traits: ["技术极客", "偶尔幽默", "喜欢深度思考"]
 speaking_style: "口语化但有技术深度"
 
knowledge:
 expertise: ["大数据", "AI/LLM", "分布式系统"]
 current_projects: ["Claude Code 源码分析", "博客写作"]
 
boundaries:
 forbidden_topics: ["政治敏感", "个人隐私"]
 fallback: "这个话题我不太方便聊，换个有趣的话题吧？"

这种"人设工程"确实让对话体验很自然。但问题是——人设再好，它也只能聊天，不能做事。

1.4 手搓版的天花板

能力	状态
闲聊	✅ 流畅自然
回答技术问题	✅ 基于人设知识
搜索最新信息	❌ 无网络访问
查看博客文章	❌ 无文件读取
帮访客写代码	❌ 无代码执行
记住上次对话	❌ 刷新即丢失
自主完成任务	❌ 无 agent loop

这就是一个典型的聊天机器人——能对话，但不能行动。

二、Managed Agents：它到底是什么？

2.1 一句话定义

Managed Agents = Anthropic 托管的 Agent 运行时。

你不需要自己搭 agent loop、沙箱、工具执行层。Anthropic 提供一个完整的云端容器环境，Claude 在里面自主运行 bash、读写文件、搜索网页、执行代码。

如果 Messages API 是"你调用模型，模型返回文本"，那 Managed Agents 就是"你定义 Agent，Agent 自主完成任务"。

2.2 与 Messages API 的定位差异

	Messages API	Managed Agents
本质	直接模型调用	预构建的 Agent 运行时
适合	自定义 agent loop、精细控制	长时间异步任务、最小化基础设施
工具执行	你的代码负责执行	Anthropic 云端容器执行
类比	买 CPU 自己组电脑	买整机开箱即用

2.3 核心概念四件套

Managed Agents 的整个模型围绕四个概念：

概念	说明	类比
Agent	模型 + system prompt + 工具 + MCP servers	一个人的"能力定义"
Environment	云端容器模板：预装包、网络规则	这个人的"工作环境"
Session	运行中的 Agent 实例，绑定 Agent + Environment	一次具体的"工作会话"
Events	应用与 Agent 之间的消息流（SSE）	你和这个人之间的"对话"

工作流程：

1
2
3
4
5
6
7
8
9


创建 Agent（一次性） → 创建 Environment（一次性）
 ↘ ↙
 创建 Session（每次任务）
 ↓
 发送 Event（用户消息）
 ↓
 流式接收 Agent 响应（SSE）
 ↓
 可中途引导或中断

三、Case Study：数字分身 v1（手搓）vs v2（Managed Agents）

这是本文最核心的部分。我们来看，如果用 Managed Agents 重构鬼哥分身，会发生什么变化。

3.1 对话 → 能动手：工具能力

v1（手搓版）：只能基于 system prompt 中的静态知识回答。

1
2
3


访客：你最近写了什么文章？
鬼哥分身：我最近在写 Agent Skills 和 Gemma 4 的分析文章...
（这是 persona.yaml 里预写的，不是实时查的）

v2（Managed Agents 版）：有完整的工具链。

1
2
3
4
5
6
7
8


访客：你最近写了什么文章？
鬼哥分身：[使用 bash] ls content/post/ | tail -5
 [使用 read] 读取最近 5 篇文章的 frontmatter
 我最近写了这些文章：
 1. Agent Skills 深度解析（4月7日）
 2. Gemma 4 深度分析（4月5日）
 3. Karpathy 的 LLM Wiki（4月2日）
 ...每篇都有链接，要看哪篇？

Managed Agents 的内置工具：

工具	能力	数字分身的用途
Bash	执行 shell 命令	列出文章、统计数据
Read / Write / Edit	文件读写	查看博客内容、生成草稿
Glob / Grep	文件搜索	搜索特定话题的文章
Web Search / Fetch	网络搜索	查最新技术动态

3.2 内存级历史 → 持久化会话

v1：对话历史存在前端 JavaScript 内存中，刷新页面就没了。

1
2


// v1：前端维护历史，刷新即丢失
let history = []; // 🔥 页面刷新 = 失忆

v2：Session 天然持久化，Event 历史服务端保存。

1
2
3
4
5
6
7
8


# v2：Session 持久化，随时可恢复
session = client.beta.sessions.create(
 agent=avatar_agent.id,
 environment_id=env.id,
 title="访客 A 的对话"
)
# 下次访问，用同一个 session_id 继续
# 完整的对话历史都在服务端

更关键的是，Managed Agents 有 Memory（研究预览阶段）——跨会话的长期记忆。这意味着鬼哥分身可以记住：“上次这个访客问过 Spark 调优，他应该是做大数据的。”

3.3 单轮推理 → 多步 Agent Loop

这是最本质的差异。

v1：一问一答，没有中间推理步骤。

1

用户消息 → LLM 生成回复 → 返回

v2：Agent 可以自主规划多步执行。

1
2


用户消息 → Claude 思考 → 调用工具 A → 分析结果 
 → 调用工具 B → 综合判断 → 生成回复 → 返回

比如访客问"帮我分析一下你这个博客的技术栈"：

v1：只能背 persona.yaml 里预写的答案
v2：grep -r "hugo" config/ → cat themes/hugo-theme-stack/... → ls layouts/ → 基于实际代码给出准确分析

3.4 无沙盒 → 云端容器

v1：代码在 Vercel Serverless Function 里跑，只有 150ms 的冷启动预算，不能装额外的包。

v2：完整的云端容器。

1
2
3
4
5
6
7
8
9


environment = client.beta.environments.create(
 name="guige-avatar-env",
 config={
 "type": "cloud",
 "networking": {"type": "unrestricted"},
 # 可以预装任何包
 # Python, Node.js, Go, Hugo...
 },
)

容器意味着：

可以预装 Hugo 来本地构建预览
可以跑 Python 脚本分析数据
可以 git clone 仓库来读取最新代码
网络不受限，可以访问外部 API

3.5 单 Agent → 多 Agent 编排

v1：一个 function 处理所有事情。

v2：可以按职责拆分为多个专精 Agent。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


# 主 Agent：鬼哥分身（对话协调者）
avatar = client.beta.agents.create(
 name="鬼哥分身",
 model="claude-sonnet-4-6",
 system="你是鬼哥的数字分身...",
 tools=[{"type": "agent_toolset_20260401"}],
 callable_agents=[
 {"type": "agent", "id": blog_agent.id, ...},
 {"type": "agent", "id": code_agent.id, ...},
 ]
)

# Sub-Agent 1：博客助手（搜索和推荐文章）
blog_agent = client.beta.agents.create(
 name="博客助手",
 model="claude-haiku-4-5", # 用小模型节省成本
 system="你负责搜索和推荐鬼哥的博客文章...",
 tools=[{"type": "agent_toolset_20260401"}],
)

# Sub-Agent 2：代码助手（分析代码、写 demo）
code_agent = client.beta.agents.create(
 name="代码助手",
 model="claude-sonnet-4-6",
 system="你负责帮访客分析代码和写 demo...",
 tools=[{"type": "agent_toolset_20260401"}],
)

当访客问文章相关的问题时，主 Agent 委托给博客助手；问代码问题时，委托给代码助手。各司其职，成本可控。

四、完整对比：手搓 vs 托管

维度	v1 手搓版	v2 Managed Agents
本质	Chat Completion 包装器	自主 Agent 平台
Agent Loop	无，单轮 request-response	有，多步推理 + 工具调用循环
工具能力	无	Bash、文件操作、Web 搜索、MCP
代码执行	不可能	云端容器沙盒
对话记忆	前端内存，刷新丢失	服务端持久化 Session
长期记忆	无	Memory（研究预览）
多 Agent	不可能	Coordinator + Sub-agents
后端代码	~150 行 JS	~50 行 Python（SDK 调用）
基础设施	Vercel function（自己维护）	Anthropic 全托管
模型	GPT-4.1-nano（OpenAI）	Claude Sonnet/Haiku（Anthropic）
成本	API 调用费 + Vercel 免费层	API 调用费 + Session 运行费
开发周期	1 天	1 天（SDK 很简洁）
适合场景	轻量级人设聊天	需要工具和自主性的场景

五、SDK 实战：5 分钟跑通 Managed Agents

5.1 安装

1
2


pip install anthropic
export ANTHROPIC_API_KEY="your-key"

5.2 创建 Agent + Environment + Session

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


from anthropic import Anthropic

client = Anthropic()

# 1. 创建 Agent
agent = client.beta.agents.create(
 name="鬼哥分身 v2",
 model="claude-sonnet-4-6",
 system="""你是鬼哥（luoli523）的数字分身。
 
性格：技术极客，偶尔幽默，喜欢深度思考。
擅长：大数据、AI/LLM、分布式系统、Claude Code。
说话风格：口语化但有技术深度，喜欢用类比解释复杂概念。

你可以使用工具来查看博客文章、搜索信息、执行代码。
当访客问到你不确定的事情时，先搜索再回答，不要编造。""",
 tools=[
 {"type": "agent_toolset_20260401"},
 ],
)

# 2. 创建 Environment
environment = client.beta.environments.create(
 name="avatar-env",
 config={
 "type": "cloud",
 "networking": {"type": "unrestricted"},
 },
)

# 3. 创建 Session
session = client.beta.sessions.create(
 agent=agent.id,
 environment_id=environment.id,
 title="访客对话",
)

print(f"Agent: {agent.id}")
print(f"Environment: {environment.id}")
print(f"Session: {session.id}")

5.3 发消息 + 流式接收

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


with client.beta.sessions.events.stream(session.id) as stream:
 # 发送用户消息
 client.beta.sessions.events.send(
 session.id,
 events=[{
 "type": "user.message",
 "content": [{
 "type": "text",
 "text": "帮我看看你博客最近写了什么文章"
 }],
 }],
 )

 # 流式处理响应
 for event in stream:
 match event.type:
 case "agent.message":
 for block in event.content:
 print(block.text, end="")
 case "agent.tool_use":
 print(f"\n[🔧 使用工具: {event.name}]")
 case "session.status_idle":
 print("\n\n✅ 完成")
 break

输出可能长这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


让我看看最近的文章...
[🔧 使用工具: bash]
[🔧 使用工具: read]

最近写了这几篇：
1. **Agent Skills 深度解析**（4月7日）— 拆解 Addy Osmani 的 19 个 AI Agent skill
2. **Gemma 4 深度分析**（4月5日）— Google 开源模型的架构和应用
3. **Karpathy 的 LLM Wiki**（4月2日）— 从零理解 LLM 的百科全书

要看哪篇的详细内容？

✅ 完成

5.4 TypeScript 版本

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46


import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

// 创建 Agent
const agent = await client.beta.agents.create({
 name: "鬼哥分身 v2",
 model: "claude-sonnet-4-6",
 system: "你是鬼哥的数字分身...",
 tools: [{ type: "agent_toolset_20260401" }],
});

// 创建 Environment
const env = await client.beta.environments.create({
 name: "avatar-env",
 config: { type: "cloud", networking: { type: "unrestricted" } },
});

// 创建 Session
const session = await client.beta.sessions.create({
 agent: agent.id,
 environment_id: env.id,
});

// 发消息 + 流式响应
const stream = await client.beta.sessions.events.stream(session.id);

await client.beta.sessions.events.send(session.id, {
 events: [{
 type: "user.message",
 content: [{ type: "text", text: "你最近在研究什么？" }],
 }],
});

for await (const event of stream) {
 if (event.type === "agent.message") {
 for (const block of event.content) {
 process.stdout.write(block.text);
 }
 } else if (event.type === "agent.tool_use") {
 console.log(`\n[🔧 ${event.name}]`);
 } else if (event.type === "session.status_idle") {
 console.log("\n\n✅ Done");
 break;
 }
}

六、工具配置：精细控制

默认的 agent_toolset_20260401 启用全部工具。但你也可以按需开关：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# 只开 bash 和文件操作，关掉网络
agent = client.beta.agents.create(
 name="安全受限的分身",
 model="claude-sonnet-4-6",
 tools=[{
 "type": "agent_toolset_20260401",
 "default_config": {"enabled": False},
 "configs": [
 {"name": "bash", "enabled": True},
 {"name": "read", "enabled": True},
 {"name": "glob", "enabled": True},
 {"name": "grep", "enabled": True},
 # web_fetch 和 web_search 保持关闭
 ]
 }],
)

还支持自定义工具——你定义接口，Claude 决定何时调用，你的代码执行后把结果返回：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


agent = client.beta.agents.create(
 name="带自定义工具的分身",
 model="claude-sonnet-4-6",
 tools=[
 {"type": "agent_toolset_20260401"},
 {
 "type": "custom",
 "name": "get_blog_stats",
 "description": "获取博客的访问统计数据",
 "input_schema": {
 "type": "object",
 "properties": {
 "period": {
 "type": "string",
 "description": "统计周期：today, week, month"
 }
 },
 "required": ["period"]
 }
 }
 ],
)

七、手搓 vs 托管：什么时候用哪个？

这两种方案不是非此即彼的关系，而是不同复杂度和需求下的最优选择。

用手搓版（Messages API / 自建）

需求简单：纯聊天，不需要工具调用
成本敏感：Vercel 免费层 + 便宜的小模型就够了
完全控制：你需要自定义每一个细节
已有基础设施：你的团队已经有成熟的 agent 框架
离线场景：需要本地部署

用 Managed Agents

需要工具能力：Agent 需要执行代码、搜索网页、读写文件
长时间任务：任务可能运行几分钟甚至几小时
零基础设施：不想自己维护沙盒和 agent loop
多 Agent 编排：任务需要多个专精 Agent 协作
持久化会话：需要跨请求保持上下文和文件状态

混合方案：最佳实践

实际上，鬼哥分身最可能的进化路径是混合方案：

1
2
3
4
5
6
7


访客消息
 ↓
前端（博客首页）
 ↓
轻量网关（Vercel / Cloudflare Worker）
 ├── 简单闲聊 → 直接 Messages API（省钱）
 └── 复杂任务 → 转发到 Managed Agents Session

简单问答（“你是谁？““你喜欢什么？"）走便宜的 Messages API；需要搜索、执行代码、多步推理的任务走 Managed Agents。按需升级，不浪费。

八、Beta 注意事项

Managed Agents 目前是 Beta 状态（managed-agents-2026-04-01），几个关键信息：

所有 API 账户默认可用，无需单独申请
SDK 自动设置 beta header，直接用就行
Research Preview 功能（Outcomes、Multi-agent、Memory）需要单独申请
Rate Limit：创建操作 60 req/min，读取操作 600 req/min
支持 7 种 SDK：Python、TypeScript、Go、Java、C#、Ruby、PHP
还有 CLI 工具 ant（Homebrew 安装）

品牌规范提醒：如果你在产品中集成 Managed Agents，可以用 “Claude Agent” 命名，但不能用 “Claude Code” 或 “Claude Cowork” 的名称和视觉元素。

总结

从 guige_avatar 到 Managed Agents，本质上是从 “调用模型生成文本” 到 “委托 Agent 完成任务” 的范式转移。

从	到
Chat Completion	Agent Session
单轮推理	多步 Agent Loop
无工具	Bash + 文件 + Web + 自定义
前端内存	服务端持久化
单一 Agent	多 Agent 编排
自建一切	托管运行时

Managed Agents 本质上是 “Claude Code as a Service”——把 Claude Code 的核心能力（bash、文件操作、web 搜索、agent loop）包装成云端 API，让开发者在自己的产品中嵌入 Claude 级别的 Agent 能力。

对于鬼哥分身来说，150 行手搓版已经够用了。但当某天访客说"帮我写一个 Spark 调优的 demo"时，Managed Agents 版本会回答：

1
2
3
4


好的，让我帮你写一个...
[🔧 使用工具: write] 创建 spark_tuning_demo.py
[🔧 使用工具: bash] python spark_tuning_demo.py
脚本已经写好并测试通过了，关键的调优点是...

从"我告诉你"到"我帮你做”——这就是一步之遥。

Claude on 鬼哥的空间

别让 Fable/Opus 干杂活：Agent 系统的省钱架构

先看一个调研任务：拿 Opus 打苍蝇是怎么发生的

Advisor Tool：Sonnet 干活，Fable/Opus 把关

Managed Agents：把一个大任务拆成一支小队

Plan Big, Execute Small：真正值得偷走的范式

怎么选架构：别先问模型，先问任务

真正的省钱架构：让每个模型做它最值钱的事

参考资料

别再调教模型了：聪明人都在设计循环

为什么是「循环」，而不是「prompt」

第一招：自我纠正循环

Parameter Golf：一个能跑 8 小时的玩具实验

第二招：记忆——跨会话的外层循环

我的体感：这其实是在重新分配「智能」

Takeaway：下次构建 Agent，先问自己四个问题

参考资料

Claude-Cookbooks 全景导航：被 README 藏起来的另一半

一、先把这份 repo 的定位搞清楚

二、一张总览图：20 多个目录怎么归类

三、基础能力层：Claude API 开箱即用能做什么

3.1 capabilities/ — 经典的 NLP 任务

3.2 multimodal/ — 视觉能力

3.3 extended_thinking/ — 让模型"想得更久"

四、Tool Use 专题：整个 cookbook 最密的一块

五、性能与成本优化

六、Agent 的三条进阶路径

6.1 模式层 patterns/agents/ — 先把套路搞清楚

6.2 SDK 层 claude_agent_sdk/ — 官方的 Agent 教程

6.3 托管层 managed_agents/ — Claude Managed Agents (CMA)

七、Skills 技能包

八、第三方集成一览

九、评估与微调

十、仓库工程实践：这本身就是一份"怎么管理 Notebook 项目"的样板

十一、我接下来会按什么顺序往里钻

结尾：这只是起点

参考资料

Claude Managed Agents：从聊天机器人到自主 Agent 的一步之遥

一、手搓版：guige_avatar 架构剖析

1.1 整体架构

1.2 核心代码：就这么简单

1.3 人设工程：它的真正价值

1.4 手搓版的天花板

二、Managed Agents：它到底是什么？

2.1 一句话定义

2.2 与 Messages API 的定位差异

2.3 核心概念四件套

三、Case Study：数字分身 v1（手搓）vs v2（Managed Agents）

3.1 对话 → 能动手：工具能力

3.2 内存级历史 → 持久化会话

3.3 单轮推理 → 多步 Agent Loop

3.4 无沙盒 → 云端容器

3.5 单 Agent → 多 Agent 编排

四、完整对比：手搓 vs 托管

五、SDK 实战：5 分钟跑通 Managed Agents

5.1 安装

5.2 创建 Agent + Environment + Session

5.3 发消息 + 流式接收

5.4 TypeScript 版本

六、工具配置：精细控制

七、手搓 vs 托管：什么时候用哪个？

用手搓版（Messages API / 自建）

用 Managed Agents

混合方案：最佳实践

八、Beta 注意事项

总结

参考资料

3.1 `capabilities/` — 经典的 NLP 任务

3.2 `multimodal/` — 视觉能力

3.3 `extended_thinking/` — 让模型"想得更久"

6.1 模式层 `patterns/agents/` — 先把套路搞清楚

6.2 SDK 层 `claude_agent_sdk/` — 官方的 Agent 教程

6.3 托管层 `managed_agents/` — Claude Managed Agents (CMA)