Agent SDK 上手：3 分钟跑通，3 天才稳

先说结论：Agent SDK 的 quickstart 真的很友好，3 分钟出效果那种。但这个 3 分钟和我后来折腾的 3 天之间，隔着一条相当宽的沟。

从一行 npx 开始

2025 年 Anthropic 把 Agent SDK 开源出来之后，我一直想找个周末摸一摸。那天晚上 10 点多，我打开终端敲了第一行：

1

npx @anthropic-ai/claude-agent

它先问我要 API key，粘进去。然后让我选个模型，我选了 claude-sonnet-4-7。接着它自己初始化了一个 .claude/ 目录，里面躺着 agents/、sessions/、tools/ 三个子目录。再然后，一个最小 agent 就跑起来了，我输入”你好”，它回了”你好，有什么可以帮你？”。

掐表 3 分 17 秒。我当时挺爽的，觉得这玩意儿是不是被吹得有点过，上手这么简单。

第二天我把它接进一个真实的爬虫后处理脚本——让 agent 读取一批 HTML，抽取关键字段，写回数据库。然后我就懵了。

3 分钟到 3 天的那条沟

第一个问题是权限。agent 调用 bash 工具的时候，它会先弹一个交互式确认。本地玩当然没问题，但我想让它在 cron 里跑啊。我翻文档翻了快一个小时，才搞明白要配 permissionMode: 'acceptEdits' 加上 allowlist。

第二个问题是工具注入。我想让 agent 直接连我本地一个 Postgres 实例，而不是每次都用 bash 拼 SQL。这就牵出自定义工具的事儿，我那天晚上写到快凌晨 1 点，一个 tool 定义写错了 schema，agent 一调用就报 ToolInputValidationError，错误信息还特别不直白。

第三个问题是上下文注入。agent 默认不知道我的项目结构，每次新 session 都从零开始。我想让它自动读 AGENTS.md（类似 CLAUDE.md 那套约定），但默认 session 不吃这个文件。后来翻源码才发现得用 systemPromptFile 参数。

第四个问题才是真要命的——环境变量。我的生产环境有 HTTP 代理，agent 启动时它自己不读 HTTPS_PROXY，得显式传 httpAgent。这个坑我踩了足足半天，以为是网络问题，还跑去抓包。

到第三天晚上，我的脚手架终于稳了：一个 agent-runner.ts，把 session 目录、工具列表、权限配置、代理、日志都封装好。从那之后跑起来就挺舒服了。

Agent SDK 到底是个什么东西

Anthropic 官方文档的定义是”用于构建 agent 应用的 TypeScript/Python SDK”。这话没错但没用。我自己理解下来，它本质上就是把 Claude Code CLI 拆出来的一个库——把里面的 session 管理、工具调用协议、hook 系统、权限系统都打包成能 import 的模块。

这意味着什么？意味着你不用再从 Anthropic 原生 SDK（@anthropic-ai/sdk）上从零手搓 agent loop 了。手搓 agent loop 看起来简单，一个 while 循环，判断 stop_reason 是不是 tool_use，然后回调工具，再把结果塞回 messages……实际做过的人都知道这里面的边界情况有多少，光 tool_use 的并行执行、错误重试、超时处理就够你写一周。

Agent SDK 把这些全帮你处理了。你只需要告诉它：”这个 agent 能用哪些工具、它的 system prompt 是什么、它遇到 X 情况怎么办”。

四个核心概念

session

session 是 agent 的一次完整执行上下文。它不只是对话历史，还包括工具调用记录、hook 触发记录、文件系统修改轨迹。session 会持久化到磁盘（默认在 .claude/sessions/），所以 agent 可以中断后 resume。

这里有个我后来踩的坑——session 会越长越大，一个跑了 4 小时的长任务 session 文件大概 83MB，resume 的时候光加载就要 6-7 秒。后面专门写了一篇讲 session 的。

agent

agent 是一个角色定义，包含 system prompt、允许使用的工具、运行策略。一个项目里可以有多个 agent，比如我现在的项目里有 reviewer、migrator、test-writer 三个角色，各自关注不同的事。

tool

tool 是 agent 能调用的能力。内置的有 bash、edit、read、write、grep、glob 那几个。自定义工具可以走 in-process（直接函数调用）或者 MCP server 的方式。

hook

hook 是在 agent 生命周期关键点触发的回调。比如 PreToolUse、PostToolUse、SessionStart、Stop 等等。hook 是可观测性金矿，线上监控 agent 基本全靠它。

那个让我卡了半天的 bash 坑

我再详细说下开头提到的”agent 一调用 bash 就卡住”的事儿。

现象是：agent 决定要跑一个 npm test，它调用了 bash 工具，然后整个进程就不动了。控制台没有任何输出，CPU 占用 0%，过了好几分钟还是没反应。

我一开始以为是 npm test 本身卡住了，手动跑了一下没问题，十几秒就出结果。后来我加了详细日志才发现——agent 在等一个交互式权限确认，但我的脚本是非交互式跑的，stdin 没人输入 y，它就一直等。

解决方式有两种：要么在启动 agent 时设置 permissionMode: 'acceptAll'（危险，只在沙箱用），要么给 bash 工具配一个 allowlist，把 npm test、npm run build 这些常用命令加进去。

我最后选了第二种，配了个 JSON：

1
2
3
4
5
6
7
8

{
  "permissions": {
    "bash": {
      "allow": ["npm test", "npm run build", "pnpm lint"],
      "deny": ["rm -rf *", "sudo *"]
    }
  }
}

权限沙箱这块其实挺复杂，我后来专门整理过一篇。

和手搓 agent 的区别

聊聊为什么我现在基本不自己手搓 agent loop 了。

手搓的好处是控制粒度细，每一步都在你手里。但代价是你得自己处理：tool_use 并发（Claude 可能一次返回 3 个 tool_use 要求并行执行）、工具错误的重试策略、token 超限的截断、cache_control 的打点、stop_reason 的各种分支、中断后的 checkpoint 保存。

这些 Agent SDK 默认全处理了。而且它的实现比我手搓的更健壮——我自己写过一版，后来对比源码发现我漏了至少 5 处边界情况，包括”tool 调用返回空字符串时怎么办”、”tool 执行超时但进程没死怎么办”。

当然 SDK 也不是银弹。它封装了很多，调试的时候你得熟悉它的日志格式。它的默认行为有时候不符合你的预期，得翻文档改配置。但整体来说，做生产级 agent 用 SDK 是明显更划算的选择。

一点小建议

我给准备上手 Agent SDK 的朋友 4 条建议：

第一，quickstart 之后别急着写业务，先把权限、代理、日志这几个基础设施搭好。这几样不弄，你业务写到一半一定会回头补。

第二，先用内置工具跑通一个端到端 demo，再碰自定义工具。自定义工具有不少坑，初期踩会特别劝退。

第三，session 目录记得加 .gitignore，里面可能有 API key 的片段和敏感数据。

第四，别低估 上下文窗口预算 这事儿。agent 跑着跑着 context 就满了，得提前规划压缩策略。