Agent SDK 是什么：Claude Code 作为库

官方定义里，Agent 是「自己规划步骤、调用工具读文件、跑命令、改代码来完成任务的应用」。 Claude Code 终端里那套能力——工具执行、代理循环、上下文管理——Agent SDK 原样提供成库， 当前支持 Python 和 TypeScript 两种语言。你不再需要手写 「请求 → 解析 tool_use → 执行 → 回传 → 再请求」的循环。

两个 SDK 都内置捆绑了原生 Claude Code 二进制，大多数安装不需要单独装 Claude Code。两个已知例外：pip 安装到源码分发平台（如 ARM64 Windows）时没有捆绑二进制，需原生安装 Claude Code 让 SDK 从 PATH 找到；npm 用 --omit=optional 跳过可选依赖时也拿不到二进制，需重装或用pathToClaudeCodeExecutable 指定路径。

四种造 Agent 的方式：先想清楚再选

选型的关键是拆开两个问题：谁提供执行框架（循环 + 上下文管理），谁负责部署。

方式你写什么框架 / 部署适合
API 手写循环整个 while 循环都是你要完全控制每一步的场景
API + Tool Runner只写工具函数SDK 提供循环，你部署自定义工具的智能体，不想手写循环
Managed AgentsAgent 配置 + 自有工具结果Anthropic 提供框架和每会话沙箱托管、定时、长时任务，免运维
Agent SDKprompt + optionsSDK 提供 Claude Code 全套框架，你部署要现成文件/命令/搜索工具的编码智能体

容易混淆的一对是 Tool Runner 和 Agent SDK：前者是 Anthropic API SDK（@anthropic-ai/sdk）里的循环辅助器， 只循环你定义的工具，没有内置工具和文件系统；后者是独立的包，自带 Read / Write / Edit / Bash / Glob / Grep / Web 搜索等全套内置工具。名字像，包不同。

安装与第一个 Agent

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

export ANTHROPIC_API_KEY=你的密钥

注意一个常踩的坑：SDK 从运行进程的环境变量读 key，不会自动加载 .env 文件。 用 .env 管理密钥的话，需要自己先用 dotenv 之类加载。存量 CommonJS 项目把脚本命名为agent.mts 即可用顶层 await，不必整体迁移 ES Modules。

官方 Quickstart 的修 bug Agent，完整可跑（npx tsx agent.ts）：

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

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"], // 预授权的工具
    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("Tool: " + block.name);
    }
  } else if (message.type === "result") {
    console.log("Done: " + message.subtype);
  }
}

Python

# Python 3.10+；推荐 uv，也可 pip install claude-agent-sdk
uv init && uv add claude-agent-sdk
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def main():
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        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 isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")

asyncio.run(main())

query 返回异步迭代器：每轮产出一条消息——推理文本、工具调用、工具结果或最终结果。 循环在任务完成或出错时结束，编排、工具执行、上下文管理和重试都由 SDK 处理。

能力矩阵：Claude Code 有的它都有

能力说明
内置工具读写编辑文件、执行命令、搜索网页
Hooks在代理生命周期关键节点运行自定义代码
Subagents为聚焦子任务派生专用子智能体
MCP通过 Model Context Protocol 接外部工具与数据源
Permissions控制哪些工具自动执行、哪些需要审批
Sessions跨轮保持上下文，可恢复、可分叉
Skills / Commands / Memory自动加载项目 .claude/ 与 ~/.claude/，和 Claude Code 行为一致
Plugins打包技能、代理、hooks 和 MCP 服务器，按本地路径加载

「自动加载 .claude/」这条是双刃剑：省配置，但也意味着 SDK 进程会继承运行目录里的 hooks 和 MCP 服务器。生产部署时把工作目录当成权限面的一部分来审计。

权限：默认从最小集开始

  • SDK 默认可访问运行目录及其子目录的文件，从任务需要的最小 allowedTools 白名单起步。
  • permissionMode 按场景选：交互产品用回调审批；批处理用 acceptEdits 放行文件编辑，Bash 仍单独授权。
  • 需要外部系统时优先接只读 MCP 工具，写操作保留审批，这与 Claude Code 桌面端的最佳实践一致。

计费与合规：这条红线别踩

官方文档在 overview 和 Quickstart 里各强调了一次：未经事先批准，Anthropic 不允许第三方开发者在自己的产品里提供 claude.ai 登录或订阅额度，包括基于 Agent SDK 构建的智能体，请使用 API key 认证。也就是说「让用户登录自己的 Pro / Max 账号来跑你的产品」不是合规路径； 你自己开发调试时用什么认证是你的事，分发给用户的产品要走 API 计费（Claude API，或 Bedrock / Vertex / Foundry 等云厂商通道，用环境变量 CLAUDE_CODE_USE_BEDROCK=1 等切换）。

品牌规范同样明确：产品里可以写「Claude Agent」或「Powered by Claude」， 但不能自称 Claude Code或使用 Claude Code 风格的视觉元素。商用受 Anthropic Commercial Terms 管辖。

非 Python / TS 技术栈：CLI 子进程

Java、Go、Rust 等语言想用同一套引擎，官方路径是把 CLI 当子进程跑：

claude -p "Find and fix the bug in auth.py" \
  --allowedTools "Read,Edit,Bash" \
  --output-format json

JSON 输出里带最终结果、会话 ID 和成本元数据，任何语言解析都容易。细节见我们的 无头模式与 CI 自动化一文。

上线前检查表

  1. 认证：生产环境 API key 从密钥管理系统注入进程环境，不进代码库。
  2. 权限：allowedTools 按任务收敛；审计运行目录里会被自动加载的 .claude/ 内容。
  3. 成本：记录每次运行的用量元数据，为长任务设预算与轮次上限。
  4. 错误处理：处理结果消息里的失败 subtype，为网络与超时准备重试策略。
  5. 合规：确认没有向终端用户暴露 claude.ai 登录；品牌措辞符合官方规范。

Agent SDK 把「做一个能干活的智能体」的工程门槛降到了一个 query 调用，真正的工作量转移到了 权限设计、成本控制和任务定义上——这正是它和玩具 demo 的分界线。