Claude Agent SDK：把 Claude Code 封装进你自己程序的正确姿势

为什么建议你认真学一下 Claude Agent SDK

Claude Code 很强，但很多人只把它当「对话工具」用。其实 Anthropic 早就留了一扇门——Claude Agent SDK，让你把 Claude Code 的能力封装进自己的程序里，随意编排、自动运行、持久化状态。

最近我在翻一个叫 claude-agent-sdk 的 Skill（来自 Jackspace/ClaudeSkillz 技能库），发现它把这个 SDK 的核心用法全拆解了一遍，堪称目前最完整的实操参考。

它到底能干啥？

说白了，SDK 给你三个核心能力：

• query() 流式接口：像用 CLI 一样调 Claude Code，但返回的是流式消息，你可以实时处理、随时中断。
• tool() 自定义工具：用 Zod 写类型安全的 schema，定义自己的 MCP 工具，注册进 Agent 的工具链。
• 子 Agent 编排：创建多个专业 Agent 协同工作，分配不同权限，控制工具访问范围。

上手有多快？

官方给的最小例子就几行：

import { query } from "@anthropic-ai/claude-agent-sdk";

const res = query({
  prompt: "分析这个代码库并提出改进建议",
  options: {
    model: "sonnet",
    workingDirectory: process.cwd(),
    allowedTools: ["Read", "Grep", "Glob"]
  }
});

for await (const msg of res) {
  if (msg.type === "assistant") console.log(msg.message.content);
}

装好 SDK、设好 API Key，照着这个模板改 prompt，5 分钟跑起来没难度。

哪些场景最值得用？

• SRE / 运维自动化：写个巡逻 Agent，自动巡检服务器、查日志、出报告。
• 代码审查 Bot：PR 来了自动跑审查 Agent，评论直接打回 GitHub。
• 安全审计：受限工具集 + 子 Agent 分工，模拟红队攻击路径。
• CI/CD 流水线：在构建失败时触发 Claude 分析错误原因，推送修复建议。

跟直接调 API 有啥区别？

最大的区别是 SDK 版本内置了工具执行上下文。你不需要自己写 Tool Use 的解析循环，SDK 帮你处理消息流、权限校验、会话恢复这些繁琐的事。尤其是会话持久化——跑一半断了，下次能接上。

加上 Zod 验证的输入 schema，生产环境里那种「LLM 乱传参数」的毛病直接被治了。

怎么装？

一个命令搞定：

npx skillscat add jackspace/claudeskillz/claude-agent-sdk

装完它会给你一份完整的 API 参考、错误排查文档，还有 12+ 个生产级模板。比起自己啃官方文档，至少省 3-4 小时。

总结

如果你在做 AI 原生应用，需要 Claude 的能力但又想自己掌控流程——别光调 API，去看看 Claude Agent SDK。这个 Skill 把它所有关键路径都整理好了，直接当手册用就行。

GitHub：https://github.com/jackspace/ClaudeSkillz

GitHub: https://github.com/jackspace/ClaudeSkillz