教程

Claude Agent SDK 入门:用几行代码写一个会修 bug 的 AI 助手

Claude Code 进阶第 8 课:Claude Agent SDK 是什么、什么时候用,用 Python 或 TypeScript 从安装到运行写出第一个会自己读代码、修 bug 的助手,以及做成产品前要知道的规定。

灵点AI 约 9 分钟读完 最后验证 2026.10.18
本篇目录

本文按 Claude Agent SDK 官方文档整理,2026 年 10 月核对。如有出入,以官方的 Agent SDK 概览和快速上手为准。

Claude Agent SDK 入门

Agent SDK 是什么

前面七课,都是你和 Claude Code 对话,让它干活。Agent SDK 换了个方向:把 Claude Code 的「大脑和双手」做成一个库,让你写进自己的程序里。

Claude Code 能读文件、改文件、跑命令、查资料,还会自己决定下一步做什么,这一整套循环就是 Agent SDK 提供的东西。你不用自己实现「调用工具 → 看结果 → 决定下一步」这些逻辑,写几行代码就能得到一个会干活的 AI 助手。

它有 Python 和 TypeScript 两个版本,用法几乎一样。上一课的 GitHub Action,底层用的就是它。

命令行、SDK 与 API 的区别

什么时候用它

  • 只是自己写代码:用 Claude Code 命令行或编辑器插件就够了,不需要 SDK
  • 想做一个自动跑的工具:比如每晚自动检查日志、批量整理文档、给内部系统加一个能动手的助手,用 SDK
  • 只要一问一答的文字:直接调用 Claude API 更简单,SDK 的长处在于能自己用工具、多步完成任务

准备工作

  • Python 3.10 以上,或 Node.js 18 以上
  • 一个 Claude Console 账号,在里面创建一个 API Key

SDK 自带了 Claude Code 的运行程序,大多数情况下不用另外安装 Claude Code。

第一步:建项目、装 SDK

Python(用 pip):

mkdir my-agent && cd my-agent
python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

TypeScript:

mkdir my-agent && cd my-agent
npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

然后在同一个终端里设置 API Key:

export ANTHROPIC_API_KEY=你的 API Key

SDK 只从环境变量里读这个 Key,不会自动读 .env 文件。如果你习惯用 .env,要自己先加载。

第二步:准备一个有 bug 的文件

在 my-agent 文件夹里新建 utils.py,故意留两个会崩溃的问题:

def calculate_average(numbers):
total = 0
for num in numbers:
total += num
return total / len(numbers)
def get_user_name(user):
return user["name"].upper()

传入空列表时,第一个函数会除以零;传入 None 时,第二个函数会报错。

第三步:写一个会修 bug 的助手

新建 agent.py:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage
async def main():
async for message in query(
prompt="检查 utils.py 里会导致崩溃的 bug,并修好它们。",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob"],
permission_mode="acceptEdits",
),
):
if isinstance(message, AssistantMessage):
for block in message.content:
if hasattr(block, "text"):
print(block.text)
elif hasattr(block, "name"):
print(f"调用工具:{block.name}")
elif isinstance(message, ResultMessage):
print(f"完成:{message.subtype}")
asyncio.run(main())

用 TypeScript 的话,新建 agent.ts:

import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "检查 utils.py 里会导致崩溃的 bug,并修好它们。",
options: {
allowedTools: ["Read", "Edit", "Glob"],
permissionMode: "acceptEdits"
}
})) {
if (message.type === "assistant" && message.message?.content) {
for (const block of message.message.content) {
if ("text" in block) console.log(block.text);
else if ("name" in block) console.log(`调用工具:${block.name}`);
}
} else if (message.type === "result") {
console.log(`完成:${message.subtype}`);
}
}

第四步:运行

python agent.py

TypeScript 用 npx tsx agent.ts。

你会看到它边想边做:先读 utils.py,找出两个问题,再动手改,最后打印 完成:success。打开 utils.py,会看到空列表和空用户都有了保护。

如果报 Not logged in 或 Invalid API key,多半是 ANTHROPIC_API_KEY 没在当前这个终端里设置。

看懂这段代码

整段代码只有三个关键部分:

  • query:入口。它启动一个循环,Claude 每想一步、每用一次工具,都会吐出一条消息,你用 async for 一条条接住
  • prompt:你要它做的事。用哪些工具、按什么顺序,它自己决定
  • options:给它定规矩。allowed_tools 列出不用问就能用的工具,permission_mode="acceptEdits" 表示改文件不用问

循环里的那些判断,只是把消息里人能看懂的部分打印出来。去掉它们,你会看到完整的原始消息,调试时很有用。

换几个参数试试

工具决定了它能做什么,按需加减:

  • 只读分析:Read、Glob、Grep
  • 分析并修改:Read、Edit、Glob
  • 还能跑命令:再加上 Bash,就可以让它「写单元测试、运行、把失败的修好」
  • 能上网查:再加上 WebSearch

给它一个固定身份,用 system_prompt(TypeScript 里是 systemPrompt):

options = ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob"],
permission_mode="acceptEdits",
system_prompt="你是一位资深 Python 工程师,代码遵循 PEP 8 规范。",
)

再往后,SDK 还支持第 5 课讲过的那些扩展:MCP 连外部系统、钩子、子代理、Skill,以及多轮对话的会话管理,都在官方文档里有详细说明。

做成产品前要知道的

  • 认证用 API Key:给别人用的产品,必须用 API Key(或 Amazon Bedrock、Google Cloud 等云平台)认证,不能让用户用 claude.ai 账号登录,除非事先获得 Anthropic 批准
  • 名字别叫 Claude Code:你的产品可以写「Powered by Claude」,但不能叫 Claude Code,也不能模仿它的品牌
  • 权限要收紧:自动运行的程序没人盯着,只给它完成任务需要的工具,Bash 这类能力能不给就不给

这一课学到的

  • Agent SDK 把 Claude Code 的工具和自主循环做成了 Python / TypeScript 库
  • 安装:pip install claude-agent-sdk 或 npm install @anthropic-ai/claude-agent-sdk,用环境变量 ANTHROPIC_API_KEY 认证
  • 核心就是 query(prompt, options),用 async for 接收它每一步的消息
  • allowed_tools 决定它能做什么,permission_mode 决定要不要问你
  • 做成给别人用的产品时,用 API Key 认证,不能叫 Claude Code

本系列

「Claude Code 上手」一共 8 课:前 5 课是基础,第 6 到 8 课是进阶篇,建议按顺序看:

还没装好?先看 10 分钟装好 Claude Code。