用 Claude Agent SDK 构建自己的智能体

Claude Agent SDK 把 Claude Code 的智能体循环变成一个库——用在你自己的程序里,而不只是现成的 CLI 工具。

SDK 是什么

Claude Agent SDK 是一个面向 Python 和 TypeScript 的库。它提供和 Claude Code 背后完全相同的智能体循环、相同的内置工具、相同的上下文管理——但可以在你自己的代码里编程调用,而不局限于终端。

智能体循环是现成的

通常使用 LLM 时,你得自己搭一个循环:发送请求、检查模型是否想用工具、执行工具、把结果发回去、再重复。用了 SDK 之后,这一切由 Claude 接管:你只需调用 query() 并传入一个提示词(Prompt),回复就会以消息流的形式返回——思考过程、工具调用、工具结果——直到任务完成为止。

定义工具

Read、Write、Edit、Bash、Glob、Grep、WebSearch 等内置工具开箱即用,不需要你自己实现。通过 allowed_tools 设定智能体可以使用哪些工具,通过 permission_mode 控制需要多少授权。如果智能体需要连接外部系统,还可以接入自定义的 MCP 服务器。

SDK 还是现成的 CLI?

对于交互式开发和一次性任务,用 Claude Code 的 CLI 就够了。SDK 是为 CI/CD 流水线、自建应用和生产环境自动化而设计的——能力相同,只是嵌入在你自己的程序里,而不是在终端中运行。

示例

在你自己的代码中调用:`query(prompt="读取 README.md 并总结三个最重要的要点", options=ClaudeAgentOptions(allowed_tools=["Read"]))` —— 智能体会自己读取文件,并以消息流的形式作答。

🛠️ 练习——自己动手试试

用 Claude Agent SDK(Python 或 TypeScript)构建一个小型智能体,让它读取一个带有故意植入的 bug 的文件并修复它。

安装 SDK(pip install claude-agent-sdk 或 npm install @anthropic-ai/claude-agent-sdk),并设置好你的 ANTHROPIC_API_KEY。
写一个带有明显 bug 的小文件(比如除以零),然后用 allowed_tools=["Read","Edit"] 调用 query()。
跟着消息流观察智能体如何读取、思考并修改文件——而这整个过程你完全没有自己写过工具循环。

✅ 自查清单

☐ 你有没有在哪里自己写过处理工具调用的循环——还是这一切都由 SDK 接管了?
☐ 如果把 permission_mode 设为 "plan" 而不是 "acceptEdits",会发生什么?
☐ 同样的任务,你什么时候会选择用 Claude Code 的 CLI 而不是 SDK?

小测验

Claude Agent SDK 会自动帮你处理哪一部分,而如果只用原始 API 自己搭建方案,你就必须自己编写这部分代码?