Claude 智能体教程：Agent SDK 和托管智能体

Agent SDK 把 Claude Code 的工具、循环和上下文管理做成了一个库，可以放进你自己的 Python 或 TypeScript 程序。本站从安装开始实测：二十行代码跑通第一个智能体，看清一次运行里收到哪些消息、结果有哪些字段、出错怎么判断。要留意：allowed_tools 不是白名单。

内置工具只会读写文件和跑命令。要让智能体查订单、办退款，得把你自己的函数做成工具。本站用 Python 实测了一个只用自定义工具的客服助手：三个工具、七组运行，包括订单号不存在、工具内部抛异常、退款没被批准。两点要留意：没接住的异常会把内部信息带到回答里；去掉内置工具后一次运行只要两分钱。

智能体要改数据、要花钱的时候，放不放行不能只靠模型自己判断。本站用 Python 实测了三种把关的办法：权限模式和规则、让调用停下来等程序批准的审批回调、在工具运行前后插入检查的 hooks。小额退款自动批准、大额拒绝、冻结的订单拦下、每次调用记日志，都跑通了。附一次调用依次要过哪几道关。

把一次性的问答变成能放进应用的东西，要补三样：记住前面聊过的、文字边生成边显示、返回程序能直接用的数据。本站用 Python 实测了多轮对话、换进程恢复、分支、逐字输出和按 JSON 结构返回，附各自的坑：不给 ID 接着聊可能接错会话，有工具调用时第一个字照样要等。

脚本在终端里能跑，放到服务器上给别人用还要多想几件事。本站实测了前半部分：每个会话是一个约 240 MB 的子进程，预算上限会超一点，3 秒的超时实际要 8 秒多才退出，花费怎么记才不重复，目录里的 CLAUDE.md 默认会被读进去。容器、代理和密钥部分整理自官方文档。

子代理、skills、插件这三样在 SDK 里都能用。本站用 Python 逐样实测：三个子代理并行时，一次 query() 先后来了四个结果消息，第一个只是“它们还在跑”；这个小任务上用子代理比主代理自己做慢一倍、贵三倍多；子代理的模型别名在中转站上不一定有。skill 默认就会被发现，插件一行配置加载。

做应用迟早碰到的三件事，本站用 Python 逐样实测。工具搜索通过中转站默认是关的，打开之后如果像前几篇那样写了 tools=[]，它照样不生效，而且没有任何提示。文件检查点能把编辑工具改过的文件退回去，用 Bash 改的退不回来。任务清单在新模型上默认不开，开了它也不一定用，用了轮数是原来的三倍多。

这个系列前面都用 Python。本站把同一个订单助手用 TypeScript 重写并实测：自定义工具、出错处理、审批回调和 hooks、会话、逐字输出、结构化结果。多数只是换个名字，不同的有几处：参数用 Zod 写；没有保持会话的客户端对象；审批回调更省事；env 是整个替换，漏写之后 Bash 里连 ls 都找不到。

Claude Managed Agents 把智能体的循环、工具执行和会话状态放到 Anthropic 那边运行。本文按官方文档整理它的四个概念、最小流程、工具和权限策略、事件怎么收发，以及从自己写的循环迁过来要改什么。中转站没有这组接口，全文未实测。

托管智能体跑起来以后要解决的事：沙箱能访问哪些网站、文件和代码怎么放进去、第三方服务的密钥怎么不让它看到、怎么跨会话记东西、怎么定义做完的标准、怎么给花费封顶、怎么定时跑。按官方文档整理，全文未实测。

一个智能体忙不过来时，可以让它把活派给子智能体，或者自己写一段工作流让几百个智能体在后台跑；数据不能出内网时，可以把工具的执行搬到自己的机器上。本文按官方文档整理这两部分的用法、上限和安全分工，全文未实测。