用错一个名字，你的Claude Agent SDK就跑不起来

你从某个技术博客抄了段代码，想用Claude Agent SDK搭建一个能自己干活的智能体。结果运行时报错，找不到包，import失败。你盯着屏幕上的“ModuleNotFoundError: No module named 'claude-code-sdk'”一头雾水。不是你写错了——是Anthropic自己把名字换了。2025年9月29日，之前叫“Claude Code SDK”的库正式更名，包名、导入路径、选项对象全变了。如果你还在用旧的名字，不跑错才奇怪。现在TypeScript的正确包名是@anthropic-ai/claude-agent-sdk，Python 3.10以上用claude-agent-sdk，入口叫query()。只要是看到“claude-code-sdk”的代码片段，直接当过期处理。这事没什么技术含量，但坑的人不少，原因很简单：SDK的定位变了，而多数人还没意识到它其实不是简单套壳。

Claude Agent SDK到底是什么？它是驱动Claude Code本身的引擎，封装成了Python和TypeScript库。不是轻量的HTTP包装，不是Claude Code的仿制品，它就是Claude Code，只是以库的形式暴露了完整的agent循环、内置工具、权限系统、子智能体机制。用这个SDK，你不需要在终端里敲提示词，而是你的代码向它描述任务，SDK负责调度模型、执行工具、把结果流式返回。整个过程里，“谁在驱动循环”这个核心问题发生了转移，而这也正是做技术选型时要判断的分水岭。

想把这件事说明白，最直接的方法是拿它和两个替代项放在一起比较：原始Messages API和Claude Code CLI。Anthropic还提供了托管的Managed Agent作为第四种形态，但多数团队卡在前三项之间的三岔口。三条路指向同一个问题——谁拥有agent循环的控制权？

走原始Messages API这条路，循环是你自己写的。发提示，检查响应里有没有tool_use块，自己执行工具，把结果追加回去，再调模型，循环往复直到模型不再要工具。示范代码看起来极其简单：while response.stop_reason == "tool_use": 执行工具，重置消息，再调client.messages.create。但在真实的生产环境里，你还得自己处理重试逻辑、上下文窗口管理、对话膨胀时的压缩、并行工具调用、错误恢复。每一项都是实打实的工程活。换句话说，这个API给了你完全的自由，也把所有的脏活累活都甩给了你。如果用的场景是单次模型调用，比如分类、提取，或者你需要一个完全由自己掌控每一步、每一token、每一次工具调用的自定义循环，原始API就一定合适。

到了Claude Agent SDK这边，角色的谱系反转了。轮到Claude来拥有循环。你的工作从写循环变成了定义任务和边界。SDK接棒后，所有工具的执行、上下文管理、权限检查、子智能体的启动都由它来完成。不需要你一行行地关心重试和压缩。这决定了它的主战场：当你需要把智能体能力产品化，或者要让它在无人值守的环境里长时间运转时，伸手拿SDK就对了。它帮开发者把“怎么跑”的问题变成了“该做什么”的问题，生产力边界一下子被推到工具侧。

不过，千万别把SDK想象成万金油。有两大易混淆的点值得单说。第一，它不是那种在Messages API外面糊一层HTTP客户端的薄封装，而是一整套智能体具现的套件。这两者的区别就像拿到了汽车的钥匙和坐进了一辆自带司机的车——驾驶位的归属变了。第二，它也不是重新实现了Claude Code，它就是把Claude Code以库的形式交给你，原汁原味。因此，理解它的本质之后，很多奇怪的兼容问题会自然消解，比如为什么不能把原始API的旧的循环代码直接扔进去用，因为控制权的交接改变了架构的基础假设。

回到技术选型的现实困扰。如果你正处于“用了SDK能不能提高效率”的纠结期，可以记住一个简单判断法：凡是你只能通过终端交互运行Claude Code来完成的复杂任务，把它搬到后台自动执行，就用SDK；凡是你只想做简单的问答、信息提取，或者有一个极其特定的工具调度顺序需要全程硬控，就不要上SDK，老老实实拥抱Messages API。这分别对应了产品化思路和工程控思路的两条线。搞反了，你会在不该造轮子的地方重复造轮子，而在需要深度控制的地方丢掉灵活性。

顺带一提Anthropic的Managed Agents。它们作为第四股力量，省去了所有基础设施的考量，但适用面窄。如果你评估后觉得代理的管理成本和运维复杂度超出了收益，那么这股力量可以拿来兜底。只是和SDK相比，又隔了一层对循环控制的让渡层级，这是另外一套决策模型了。

最后说一个看起来老生常谈但尤其容易被忽视的东西：文档和社区。SDK刚改完名那段时间，网上的信息新旧混杂，AI搜索引擎推荐的答案可能还引用着半年前的示例。查资料时注意看包名，只要不是@anthropic-ai/claude-agent-sdk或claude-agent-sdk，就马上划走。同时，Anthropic对SDK后续的发展方向也明确——架构、构建走查、成本控制、安全、部署，这些内容已经写进了他们的指南。在跳进代码之前，花半天时间把这些章节啃完，比一头扎进去一个个报错排查要划算得多。毕竟，当智能体的控制权从你手里交出去的那一瞬，对边界的理解就决定了你的系统是持续运转的机器还是一台随时抛锚的概念车。