Claude Code、Claude API、Agent SDK、托管智能体：四条路怎么选

这篇解决一个问题：Claude Code、Claude API、Agent SDK、托管智能体（Managed Agents），名字都见过，我该用哪个？

四样东西的文档分在两个站上（Claude Code 文档和 Claude 开发平台文档），各讲各的，很少放在一起比。这一篇把它们放进一张表，再按几种常见的情形说怎么选。

本文按官方文档整理。“通过中转站能不能用”取自本站这个月在一家中转站（酷站AI）上的实测，出处在第五节。

先说结论

你要做的事	用哪个
自己写代码时让它帮忙：读仓库、改文件、跑测试	Claude Code
在脚本或 CI 里让它跑一个任务	Claude Code 的非交互模式（claude -p）
给自己的程序加一个调模型的功能：问答、分类、抽取、总结	Claude API
做一个自己的智能体，要现成的读写文件、跑命令那一套，跑在自己的机器上	Agent SDK
做一个智能体，循环、沙箱、会话都不想自己管，任务一跑就是很久	托管智能体

一句话的区别：四条路用的是同一批模型，差别在循环谁来跑、工具在哪执行。

在国内走中转站的话，前四行都走得通，最后一行走不通，见第五节。

一、先弄清“循环”和“工具”

模型本身只做一件事：收到一段输入，给出一段输出。要它“干活”，得让它能调工具（读文件、跑命令、查数据库），并且把工具的结果送回去让它接着想。这样一圈一圈转，直到任务做完，就是所谓的智能体循环。

所以每一种用法都要回答两个问题：

• 循环谁来跑？ 是你写代码一圈一圈地发请求，还是有人替你跑。
• 工具在哪执行？ 在你的电脑上、你的服务器上，还是在 Anthropic 那边。

四条路的差别基本就是这两个问题的答案不同。

二、四条路各是什么

Claude Code：给人用的

官方的说法是一个能读你的代码库、改文件、跑命令的编程工具，在终端、IDE、桌面应用和浏览器里都能用。循环是它跑的，工具在你的机器上执行，你坐在旁边看着、批准、纠正。

它不只能交互着用。加上 -p 就是非交互模式，给一句任务，它做完把结果打印出来，适合放进脚本和 CI：

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

从哪开始：《Claude Code 安装教程》；非交互模式见《把 Claude Code 接进脚本和 CI》。

Claude API：直接调模型

你发一个请求，模型回一个响应，别的什么都没有。对话历史你自己存，每次带着重发；要用工具，就自己定义、自己执行、自己把结果送回去，循环是你写的。官方的 SDK 里有一个 Tool Runner（beta）可以替你转这个循环，但工具仍然是你的代码。

官方的表里把这条路叫 Client SDK，有 Python、TypeScript、Go、Java、C#、PHP、Ruby 七种语言，也可以不用 SDK 直接发 HTTP 请求。

它适合两种情况：一是根本不需要循环，只是调一次模型；二是你要控制循环里的每一步。

从哪开始：《第一次直接调 Claude 的接口》。

Agent SDK：把 Claude Code 当成库来用

官方的概括是“把 Claude Code 当成一个库”。它在你的程序里运行 Claude Code 的程序本体，所以 Claude Code 有的它都有：内置的读写文件和跑命令的工具、权限、会话、hooks、子代理、MCP、skills、插件。循环是 SDK 跑的，跑在你自己的进程里，工具对着你机器上的文件系统。

只有 Python 和 TypeScript 两种语言。别的语言想用同一个循环，官方的办法是把 claude -p 当子进程来调，加上 --output-format json 拿结构化的结果。

顺带一提，上面说的 claude -p，官方文档就把它称作“通过命令行使用 Agent SDK”。所以脚本和 CI 里用 Claude Code，和用 Agent SDK 写程序，是同一个东西的两种形态。

从哪开始：《Claude Agent SDK 入门》。

托管智能体：连循环和沙箱都交出去

Anthropic 替你跑循环，也替你准备执行工具的沙箱。你通过接口定义一个智能体（模型、系统提示、工具、MCP 服务器、skills），配一个环境，开一个会话，然后发事件、收事件。对话历史存在服务端。沙箱默认是 Anthropic 托管的，也可以换成你自己机器上的。

官方列的适用情形：任务要跑几分钟到几小时、需要带网络和预装软件的安全沙箱、不想自己搭循环和沙箱、需要跨多次交互保留文件和对话、要按计划定时跑。

它目前是 beta。计费有两部分：token 按模型的标价算；另加会话运行时间，每小时 0.08 美元，只在会话处于运行状态时计，等你回复的空闲时间不算。

从哪开始：《托管智能体入门》。

三、放在一张表里

	Claude Code	Claude API	Agent SDK	托管智能体
给谁用	人	你的程序	你的程序	你的程序
循环谁来跑	Claude Code	你写	SDK，在你的进程里	Anthropic
工具在哪执行	你的机器	你的环境	你的机器	托管的沙箱，或你自己的沙箱
现成的工具	读写文件、跑命令、搜索等	没有，自己定义	和 Claude Code 同一套	bash、文件操作、联网搜索和抓取、MCP
对话历史	Claude Code 管	你自己存，每次重发	SDK 管，在你这边	服务端存
用什么语言	不用写代码	七种语言的 SDK，或 HTTP	Python、TypeScript	各语言的 SDK、ant 命令行、REST
怎么计费	订阅，或按 token	按 token	按 token	按 token，另加会话运行时间
通过中转站	能用	大部分能用	能用	用不了

“Claude API”那一列的工具一行要补一句：除了自己定义的工具，接口还提供几种在 Anthropic 那边执行的工具（联网搜索、代码执行等），见《服务器端工具》。

四、几种容易选错的情形

只是调一次模型，别上智能体

给一段文字分类、从发票里抽字段、总结一篇文档，这些是一个请求就结束的事，不需要循环，也不需要 Agent SDK。用 Claude API，要固定结构的结果就用结构化输出。

要做智能体，不一定要自己写循环

很多人的第一反应是用 API 自己写一个循环。如果你的智能体要做的是读文件、跑命令、改代码这一类事，Agent SDK 已经把工具、权限、会话都做好了，自己重写一遍不划算。

自己写循环更合适的情况是：工具全是你自己的业务接口，用不上读写文件那一套；或者你要控制循环里的每一步；或者你用的语言不是 Python 和 TypeScript，又不想起子进程。

脚本和 CI，先用 claude -p

“每次提交自动审查一遍”“每天晚上跑一次检查”这类事，一条 claude -p 命令就够了，不用先学 SDK。等到需要在程序里处理它的每一步消息、用回调决定某个工具调用让不让过，再换成 SDK。

Agent SDK 和托管智能体，差在“在哪跑”

官方的迁移文档说得很直接：两者的概念是一样的（智能体、工具、会话），区别是 SDK 跑在你运维的进程里，托管智能体跑在 Anthropic 的基础设施里。

所以选哪个，看的是你愿不愿意自己管一台机器：

你的情况	更合适的
智能体要操作你机器上已有的代码和文件	Agent SDK
已经有服务器，想把它部署成自己的服务	Agent SDK，见《部署》
不想管服务器和沙箱，任务跑得久，要随时能回来看进度	托管智能体
要定时跑、要服务端存着每个会话的历史	托管智能体
走中转站	Agent SDK

做给别人用的产品，要用 API key

Agent SDK 的文档有一条说明：除非事先得到批准，Anthropic 不允许第三方开发者在自己的产品里提供 claude.ai 的登录或它的用量额度，用 Agent SDK 做的智能体也包括在内。也就是说，订阅是给你自己用 Claude Code 的；做进产品里的，走 API key、按 token 计费。

五、在国内，走中转站

本站这个月在一家中转站上把前三条路都实测过：

	通过中转站	详见
Claude Code	能用。改两个环境变量，功能大部分和直连一样	《Claude Code 接入中转站》、《通过中转站用 Claude Code》
Claude API	大部分能用。文件接口、批量、代码执行等十来项用不了，提示缓存要多做一步	《通过中转站用 Claude API》
Agent SDK	能用。它认的环境变量和 Claude Code 一样	《Claude Agent SDK 入门》
托管智能体	用不了。智能体、环境、会话等六个接口全部返回 404	《托管智能体入门》

托管智能体用不了是意料之中的：循环和沙箱都在 Anthropic 的平台上，中转站转发不了这一整套。所以走中转站又想要一个自己的智能体，路只有一条：Agent SDK 加一台自己的机器。

这是一家中转站的表现，别家可能不同。怎么测自己用的那一家，上面第二行链接的那篇里有一个自测脚本。

六、选了以后还能换

这四条路不是互斥的，也不用一次选死。

• 从手动到自动。 先在 Claude Code 里交互着把一件事做顺，再把同样的提示放进 claude -p 接到 CI 里，需要更细的控制时再换成 Agent SDK。这是本站的建议。三步用的是同一套工具；按官方文档，项目里的 CLAUDE.md、skills、hooks 这些基于文件的配置，Agent SDK 默认也会读。
• 从自己写的循环换到托管智能体。 迁移文档列了换过去之后不用再管的四件事：对话历史、工具调用的循环、跑代码的沙箱、判断任务什么时候算完。
• 从 Agent SDK 换到托管智能体。 配置基本能一一对应：每次运行时构造的选项，变成在服务端创建一次、带版本的智能体；指向本地路径的目录，变成上传或挂载的文件；CLAUDE.md 那一层层的说明，变成智能体上的一段系统提示；权限模式和回调，变成每个工具各自的权限策略。详见《托管智能体入门》的第九节。

接着看哪里

• 用 Claude Code：Claude Code 教程，从安装到自动化。
• 自己调接口：Claude API 教程，从第一个请求到工具调用。
• 做智能体：Claude 智能体教程，Agent SDK 和托管智能体都在这里。
• 国内使用：在国内用 Claude，接入中转站和辨别真假。

没有核对到的

• 全文按官方文档整理。 托管智能体本站没有用过，它目前是 beta，文档说行为还会调整。
• “通过中转站”只测了一家，时间是 2026 年 10 月。
• 价格取自官方价格页，2026-10-13 查看；中转站怎么计费以它自己的页面为准。
• Agent SDK 那条关于登录的规定是文档里的一句说明，具体怎么算“事先批准”文档没有展开，做产品之前请自己读一遍官方的条款。