Claude Agent SDK 从零跑通第一个 Agent：quickstart 里那几步分别在干什么

2026-08-18

照着 quickstart 敲完能跑，但过两周想改点东西就懵——因为跑通的时候没搞清楚哪一行对应哪个概念。这篇就是把官方 quickstart 那几步拆开：每一步动的是哪个 API、哪个配置项，以及哪些地方文档专门写了例外。

一、这几步到底在解决什么

先说清楚它跟”直接调 API”的差别在哪。Agent SDK overview 页有一张四选一的对照表，原话意思是：如果你要自己实现工具循环，用的是 Client SDK；如果你要在终端做交互式开发或跑一次性任务，用的是 Claude Code CLI；如果你不想自己管 sandbox 和 session 基础设施、要跑长时间的异步 agent，那是 Managed Agents（文档明确写它是与 Agent SDK 不同的另一个产品，由 Anthropic 托管运行）；而 Agent SDK 的定位是”在你自己的进程里跑 agent loop 的一个库”。

换句话说，你写这段代码不是为了发一次请求，而是为了让模型自己决定读哪个文件、改哪一行，你只负责消费它吐出来的消息流。这个差别 quickstart 页在跑通之后专门点了一句：Agent SDK 与众不同的地方在于 Claude 直接执行工具，而不是让你去实现这些工具；overview 页则是从反面写的——选 Client SDK 意味着”工具循环由你自己实现”。

overview 页还列了 SDK 里可用的能力大类：内置工具、hooks、subagent、MCP、权限、会话、skills 与命令与记忆、plugin。其中 skills、命令、记忆这一条写明是从项目的 .claude/ 与 ~/.claude/ 自动加载的，跟 Claude Code 走同一套。这个信息在第一次跑通时很关键——你的项目目录里如果已经有 .claude/，它不是摆设。

二、前置条件：这一段别跳

quickstart 的 Prerequisites 只有两行：Node.js 18+ 或 Python 3.10+，以及一个 Anthropic 账号。但真正容易踩的是安装那一步的 Note，它讲的是”自带二进制”这件事。

文档写明：TypeScript 和 Python 两个 SDK 都会捆绑一个原生的 Claude Code 二进制，所以大多数安装场景不需要单独装 Claude Code。但它同时列出了两种拿不到这个二进制的情况：

pip 装到的是 Python SDK 的源码分发包而不是平台 wheel 时（文档举的例子就是 ARM64 Windows），没有捆绑二进制。这时要按官方 setup 文档单独安装 Claude Code，Python SDK 会从 PATH 上找它。
TypeScript SDK 的二进制是通过 npm 的可选依赖装的，所以任何跳过可选依赖的安装方式（文档举的例子是 npm ci --omit=optional）都拿不到二进制，即便平台是受支持的。处理办法是重装时别跳过可选依赖，或者单独装 Claude Code 再把 pathToClaudeCodeExecutable 设成它的路径。

pathToClaudeCodeExecutable 这个配置项在 TypeScript SDK 参考页的 Options 表里也有一行，说明是”仅在安装时跳过了可选依赖，或你的平台不在受支持集合内时才需要”。ARM64 Windows 这条对本站读者不算冷门，值得在开工前先确认一下自己 pip 装到的是 wheel 还是源码包。

还有一条容易被忽略的账号侧限制：quickstart 与 overview 两页都写了同一段 Note——除非事先获得批准，Anthropic 不允许第三方开发者在自己的产品里提供 claude.ai 登录或使用其速率额度，包括基于 Claude Agent SDK 构建的 agent，要求改用文档里描述的 API key 认证方式。也就是说，你做对外产品时不能把用户的 claude.ai 账号接进来当作认证入口。

三、四步，每步在改什么

第 1 步：建目录

mkdir my-agent
cd my-agent

这一步不只是”找个地方放文件”。quickstart 写明：你可以从任意目录跑 SDK，它默认能访问该目录及其子目录中的文件。所以工作目录本身就是一条默认的访问边界。在 TypeScript SDK 参考页里，与之对应的配置项是 cwd（默认取 process.cwd()），另有 additionalDirectories 用于追加 Claude 可访问的目录。

第 2 步：装包

TypeScript 新项目：

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

文档解释了这两行配置的用途：在 package.json 里设 "type": "module" 是为了让 agent 脚本能用顶层 await，tsx 用来直接运行 TypeScript 文件。

如果是已有的 TypeScript 项目，只装那两个包即可；但文档补了一条：项目若使用 CommonJS，就把脚本命名为 agent.mts 而不是 agent.ts——.mts 扩展名让 tsx 把它当 ES module 处理，从而在不改造整个项目的前提下用上顶层 await。后面创建与运行的步骤都相应换成 agent.mts。

Python 侧分两条路。用 uv：

uv init
uv add claude-agent-sdk

用 pip 的话，macOS / Linux 与 Windows 的命令是分开写的。macOS 或 Linux：

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

Windows：

py -m venv .venv
.venv\Scripts\Activate.ps1
pip install claude-agent-sdk

Windows 这一侧文档还带了一句处置：如果 PowerShell 因执行策略报错、拦住了 Activate.ps1，先运行 Set-ExecutionPolicy -Scope Process RemoteSigned。注意它用的是 -Scope Process，作用范围只在当前进程。

第 3 步：设 API key

macOS / Linux：

export ANTHROPIC_API_KEY=your-api-key

Windows（PowerShell）：

$env:ANTHROPIC_API_KEY = "your-api-key"

实际使用时把值换成你自己的 <YOUR_API_KEY>，不要把它写进会提交的文件里。

这一步有个反直觉的点，文档专门点了出来：SDK 从”运行你 agent 的那个进程”的环境里读取这个 key，它不会自动加载 .env 文件。如果你习惯把 key 放 .env，就得自己在调用 SDK 之前加载（文档举的例子是用 dotenv 包）。文档在设置这一步的措辞是”在你将要运行 agent 的那个 shell 里”设置环境变量，这句限定不是随口一提——按文档这个口径，key 设在 A 终端、agent 跑在 B 终端时，进程环境里就没有它。

除直连之外，quickstart 还列了几种第三方 API provider 的认证方式，每种对应一个环境变量开关：Amazon Bedrock 用 CLAUDE_CODE_USE_BEDROCK=1 并配置 AWS 凭证；Claude Platform on AWS 用 CLAUDE_CODE_USE_ANTHROPIC_AWS=1 加 ANTHROPIC_AWS_WORKSPACE_ID，再配置 AWS 凭证；Google Cloud’s Agent Platform 用 CLAUDE_CODE_USE_VERTEX=1 并配置 Google Cloud 凭证；Microsoft Foundry 用 CLAUDE_CODE_USE_FOUNDRY=1 并配置 Azure 凭证。各自的细节文档指向了对应的 setup 页。

第 4 步：写 agent，触发第一次工具调用

quickstart 先让你造一个带 bug 的 utils.py（一个除零、一个空对象取值），再写 agent 脚本。TypeScript 版：

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

// Agentic loop: streams messages as Claude works
for await (const message of query({
  prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.",
  options: {
    allowedTools: ["Read", "Edit", "Glob"], // Auto-approve these tools
    permissionMode: "acceptEdits" // Auto-approve file edits
  }
})) {
  // Print human-readable output
  if (message.type === "assistant" && message.message?.content) {
    for (const block of message.message.content) {
      if ("text" in block) {
        console.log(block.text); // Claude's reasoning
      } else if ("name" in block) {
        console.log(`Tool: ${block.name}`); // Tool being called
      }
    }
  } else if (message.type === "result") {
    console.log(`Done: ${message.subtype}`); // Final result
  }
}

Python 版对应的是 query、ClaudeAgentOptions、AssistantMessage、ResultMessage，参数名换成蛇形：allowed_tools、permission_mode，配合 async for 消费。

文档把这段代码拆成三块，正好就是”每一步在改什么”的答案：

query：入口，创建 agent loop，返回一个异步迭代器，所以要用 async for 流式消费消息。TypeScript SDK 参考页给的签名是 query({ prompt, options })，prompt 可以是字符串，也可以是 AsyncIterable<SDKUserMessage>。
prompt：你要它做什么。用哪些工具是 Claude 自己判断的，你不指定。
options：agent 的配置。这个例子用 allowedTools 预先放行 Read、Edit、Glob，用 permissionMode: "acceptEdits" 自动批准文件改动。文档还提到 systemPrompt、mcpServers 等其它选项。

第一次工具调用就发生在这条链路上：query 建立循环 → 模型基于 prompt 决定调 Read → 该调用命中 allowedTools 被自动放行 → 工具结果回到循环 → 模型决定调 Edit，由 permissionMode: "acceptEdits" 放行。文档对循环本身的描述是：async for 会一直转，Claude 思考、调工具、观察结果、决定下一步，每次迭代产出一条消息——推理、工具调用、工具结果或最终结果；编排、工具执行、上下文管理与重试由 SDK 负责，你只消费这个流；循环在任务完成或出错时结束。

运行命令按语言分：TypeScript 是 npx tsx agent.ts（脚本名为 agent.mts 时改成 npx tsx agent.mts），uv 是 uv run agent.py，pip 路线在虚拟环境仍激活的状态下跑 python agent.py。

quickstart 还给了几个改 options 的变体，都是往 allowedTools 里加名字：加 WebSearch 得到联网检索能力，加 Bash 得到执行命令的能力；另一个变体是给 systemPrompt 传一段自定义提示。加 Bash 意味着模型可以在你的机器上执行命令，这一步的后果和加个只读工具完全不是一个量级，放行前自己掂量。以上为按官方文档中的参数语义组合的示例，未经实测，以官方文档与 --help 的实际输出为准。

四、边界：文档明说的限制

语言只有两种。 overview 页写明 SDK 只作为 Python 和 TypeScript 的库提供；要从其它语言驱动同一套 agent loop，做法是把 CLI 当子进程跑，用 -p 参数配合 --output-format json。
allowedTools 不是白名单。 TypeScript SDK 参考页在这一项的说明里写得很直白：它用于免提示自动批准，并不把 Claude 限制在这些工具之内；未列出的其它工具会落到 permissionMode 和 canUseTool 上去判定；要真正屏蔽工具得用 disallowedTools。这一条和 quickstart 代码注释里的”Auto-approve these tools”配着读才不会误解。
权限模式不止 quickstart 用的那一个。 PermissionMode 这个类型在 TypeScript SDK 参考页里是一个联合类型，共六档：default、acceptEdits、bypassPermissions、plan、dontAsk、auto。quickstart 只说”权限模式控制你想要多少人工介入”，并把完整说明指向了权限页与 agent loop 页。
.env 不自动加载（见上文），这是官方明确写出来的行为，不是 bug。
品牌用法有限制。 overview 页写明：接入 Claude Agent SDK 的合作方，不得使用 “Claude Code” 或 “Claude Code Agent” 这类命名，也不得使用模仿 Claude Code 的 ASCII art 或视觉元素；允许的写法是 “Claude Agent” 等几种。做对外产品时这条要提前看。
至于这套 SDK 在各种平台上的实际稳定性、耗时、生成质量——官方文档没有说明这一点，我们也没有做过实测，这篇不给任何这方面的判断。

五、怎么确认真的跑通了

quickstart 给的验证信号有三层，建议按顺序看：

安装层：文档写明 npm 安装成功时会打印 added N packages。TypeScript SDK 参考页则写明，如果包管理器跳过了可选依赖，SDK 会抛出 Native CLI binary for <platform> not found——看到这条报错就直接去查第二节那两种例外情况。
运行层：agent 工作时会打印它的推理与每一次调用的工具，最后以 Done: success 结束。这个 success 就是结果消息的 subtype。在 TypeScript SDK 参考页里，SDKResultMessage 是个联合类型，成功那一支的 subtype 是 "success"，失败那一支的 subtype 取 "error_max_turns"、"error_during_execution"、"error_max_budget_usd"、"error_max_structured_output_retries" 之一。所以你打印出来的那个字符串本身就是最直接的诊断入口。
结果层：跑完去看 utils.py。quickstart 描述的预期是文件里出现了处理空列表与空用户的防御性代码，agent 自主完成的三件事是：Read 读文件、分析出会崩的边界情况、Edit 加上错误处理。

如果看到 “API key not found”，quickstart 的处置很明确：确认你在运行 agent 的那个 shell 里设了 ANTHROPIC_API_KEY，并再次提醒 SDK 不会自动加载 .env。Windows 上尤其注意 $env:ANTHROPIC_API_KEY 只在当前 PowerShell 会话有效，换一个窗口就没了。

最后提醒一句口径问题：quickstart 是入门页，很多细节它只给一句话加一个链接（权限如何评估、流式与单轮模式的取舍、结果消息里的各种诊断字段），真正的完整定义在 Python / TypeScript 的 API 参考页与权限页上。两处措辞对不上时，以参考页和你本地 --help 的实际输出为准。

本文依据 Claude Code 官方文档（code.claude.com/docs）于 2026-08-17 的公开内容整理。该产品闭源，本文只复述官方文档写明的机制，不推断其内部实现； 我们没有对文中涉及的功能做过实测，因此不涉及界面外观、操作手感与运行速度的任何描述。该产品迭代频繁，文中涉及的命令、配置项与默认值随版本变动，请以官方文档最新内容为准。本文不涉及价格、额度与限流的具体数值，相关信息请以官方定价与用量说明页为准。安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。