Claude Agent SDK

CLI 是给人用的，SDK 是给程序用的。当你想把 Claude Code 嵌进自己的应用、写自定义自动化工作流、或者构建专门的 agent 产品时，命令行 + flag 的方式不够灵活——你需要的是一个可编程的接口。

Claude Agent SDK 就是这个接口。它把 Claude Code 的全部能力——agent loop、内置工具、上下文管理、hooks、subagents、MCP、权限、sessions——作为 Python 和 TypeScript 的库暴露出来，让你在自己的代码里调用。

两个语言 SDK

语言	包名
TypeScript	`@anthropic-ai/claude-agent-sdk`
Python	`claude-agent-sdk`

TypeScript SDK 把 Claude Code 原生 binary 作为可选依赖打进包里，所以不需要单独装 Claude Code。Python SDK 要求 Python 3.10+。

安装

# TypeScript
npm install @anthropic-ai/claude-agent-sdk

# Python
pip install claude-agent-sdk

配 API key

从 Console 拿一个 API key，设到环境变量：

export ANTHROPIC_API_KEY=your-api-key

SDK 不会自动加载 .env 文件——如果你把 key 存在那里，自己用 dotenv 之类的包加载。SDK 还支持第三方 provider：

Amazon Bedrock：设 CLAUDE_CODE_USE_BEDROCK=1，配 AWS 凭证
Claude Platform on AWS：设 CLAUDE_CODE_USE_ANTHROPIC_AWS=1 + ANTHROPIC_AWS_WORKSPACE_ID
Google Vertex AI：设 CLAUDE_CODE_USE_VERTEX=1，配 GCP 凭证
Microsoft Azure：设 CLAUDE_CODE_USE_FOUNDRY=1，配 Azure 凭证

除非 Anthropic 事先批准，第三方开发者不得在自家产品里提供 claude.ai 登录或 rate limit——SDK 应用要走 API key 鉴权。

第一个 agent

经典的「找 bug 修 bug」例子。先建一个有 bug 的文件 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()  # user 为 None 会 TypeError

然后写 agent 让它自己读、自己分析、自己改：

Python

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def main():
    # agentic loop：Claude 工作时持续吐消息
    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)         # Claude 的推理
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")  # 调用的工具
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")    # 最终结果

asyncio.run(main())

TypeScript

import { query, type AssistantMessage, type ResultMessage } from "@anthropic-ai/claude-agent-sdk";

const stream = query({
  prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.",
  options: {
    allowedTools: ["Read", "Edit", "Glob"],
    permissionMode: "acceptEdits",
  },
});

for await (const message of stream) {
  if (message instanceof AssistantMessage) {
    for (const block of message.content) {
      if ("text" in block) console.log(block.text);
      else if ("name" in block) console.log(`Tool: ${block.name}`);
    }
  } else if (message instanceof ResultMessage) {
    console.log(`Done: ${message.subtype}`);
  }
}

跑起来后，agent 会自主完成三步：

Read utils.py 理解代码
分析逻辑，识别会崩的边界情况
Edit 文件，加上空列表和 null user 的处理

跑完检查 utils.py，会看到防御性代码已就位。SDK 自己执行工具——你不用写「调用 Read 怎么读」「调用 Edit 怎么写」的实现。

三大组件

代码三部分：

query：主入口，启动 agentic loop。返回 async iterator，用 async for / for await 流式消费消息
prompt：要 Claude 干什么。Claude 根据任务自己挑工具
options：agent 配置——allowedTools 预批准工具、permissionMode 权限模式、systemPrompt 自定义系统提示、mcpServers MCP 服务器等

内置工具清单

SDK 自带这些工具，agent 开箱即用：

工具	作用
`Read`	读工作目录里任意文件
`Write`	创建新文件
`Edit`	精确编辑现有文件
`Bash`	跑终端命令、脚本、git 操作
`Monitor`	监听后台脚本，每行输出当一个事件
`Glob`	按 pattern 找文件（`*/.ts`）
`Grep`	用 regex 搜文件内容
`WebSearch`	搜网络拿当前信息
`WebFetch`	抓取并解析网页
`AskUserQuestion`	多选项的方式问用户澄清问题

不需要你实现工具执行——SDK 自己处理。

SDK 能力

Claude Code 的全部能力都在 SDK 里：

Hooks：在 agent 生命周期关键点跑自定义代码——PreToolUse、PostToolUse、Stop、SessionStart、SessionEnd、UserPromptSubmit 等
Subagents：在 SDK 里调用子代理
MCP：连外部工具系统
Permissions：细粒度控制 agent 能干什么
Sessions：会话持久化、恢复、外部存储

例如，用 PreToolUse hook 把每次文件改动记到审计日志：

import asyncio
from datetime import datetime
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher

async def log_file_change(input_data, tool_use_id, context):
    file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
    with open("./audit.log", "a") as f:
        f.write(f"{datetime.now()}: modified {file_path}\n")
    return {}

用途

SDK 的甜区是自定义自动化工作流——CLI flag 不够灵活时：

场景	SDK 怎么用
自定义 CI bot	写自己的 GitHub/GitLab 集成，逻辑超出 Actions 默认能力
邮件助手 / 研究代理	完整 agent 产品，把 Claude Code 当核心引擎
多步骤工作流编排	用代码控制 loop、branch、中间结果存哪
嵌进现有应用	把 agent 作为某个功能模块嵌入
自定义权限策略	在 hook 里写复杂鉴权逻辑

GitHub Actions 本身就是基于 SDK 构建的——anthropics/claude-code-action 内部用 SDK 调用 Claude Code。需要超出 Actions 默认能力的自动化时，直接用 SDK 写。

SDK Examples 与迁移

官方维护了 github.com/anthropics/claude-agent-sdk-demos——里面是真实可跑的 agent 示例：邮件助手、研究代理等，适合学习模式。

从老版本迁移看官方的 Migration Guide（在 SDK 文档侧栏的 Migration Guide 链接）——它列出了 breaking changes 和升级步骤。早期还有 TypeScript V2 preview（已移除），老用户需要迁移到当前 SDK。

Quickstart 流程

完整起步步骤：

# 1. 建项目
mkdir my-agent && cd my-agent

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

# 或 Python
python -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

# 3. 配 API key
export ANTHROPIC_API_KEY=your-api-key

# 4. 写 agent（见上文 agent.ts / agent.py）

# 5. 跑
npx tsx agent.ts
# 或
python agent.py

前提：Node.js 18+ 或 Python 3.10+，以及一个 Anthropic 账号。

一句话总结

Claude Agent SDK 把 Claude Code 从「CLI 工具」变成「可编程的库」——query 是入口，prompt 是指令，options 是配置，内置工具开箱即用。CLI 不够灵活时，用 SDK 写自己的 agent 应用或自动化工作流。

下一篇看定时任务与批处理，把 headless + SDK 能力接到 cron / systemd / GitHub Actions schedule 上做周期性自动化。⏰