高手进阶（七）：Claude Agent SDK完全指南：TypeScript/Python双语言实战还在手写API调A

Agent SDK 入门——用代码构建自己的 Claude 代理-可调用函数智能体

Windows 10/11 · Claude Code v2.1.32+ · @anthropic-ai/claude-agent-sdk v0.2.136 / claude-agent-sdk v0.1.77 · 🟢 常青 · 最后更新 2026-05-11

一、这篇教程解决什么问题

一句话定位：读完本篇，你会用 TypeScript 或 Python 的 Agent SDK 把 Claude Code 变成可编程的函数调用——写一个自动代码审查 CLI、做一个批量迁移脚本、用子代理并行分析整个代码库——不再是在终端里跟 Claude 聊天，而是在代码里调用它。

跳读指南：如果你只关心 TypeScript 怎么用，跳到第三节。想用 Python，跳到第四节。想直接看实战项目，跳到第七节。搞不清楚 Skill 和 SDK 什么时候用哪个，跳到第十节。

阅读前提（硬条件，可逐条验证）：

TypeScript（Node.js 18+）或 Python（3.10+）至少会一种，能写基本的 async 函数
Claude Code CLI 已安装并能正常启动（claude --version 验证）
了解 Claude Code 的基本工具（Read、Write、Edit、Bash、Glob、Grep）
读过《新手上路（一）》了解权限模式（allowedTools 在 SDK 中对应 allowed_tools 字段）
读过《高手进阶（六）》了解 Headless 模式（SDK 本质上是 Headless 模式的编程接口）

DeepSeek 用户注意：Agent SDK 全部可用。只需在 ClaudeAgentOptions 中配置 env: {"ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic"} 即可。本文所有代码示例同时标注 Anthropic API 和 DeepSeek 两种配置方式。

读完能得到什么：

TypeScript 和 Python 两套 SDK 的完整基础用法——从安装到第一个 agent 跑通
自定义工具的写法——用 @tool 装饰器给 Claude 装上你自己的 API
Hooks 拦截器的配置——在 Claude 执行工具前后插入你自己的逻辑
子代理编排的实现——一个主代理调度多个子代理并行干活
三个开箱即用的实战工具——代码审查 CLI / 批量迁移 / 文档生成器
安全与成本控制清单——max_turns、max_budget_usd、allowed_tools 的正确用法
Skill vs SDK 决策树——一眼判断该写 Skill 还是写代码
5 个真实 Debug 场景的五段式排查

二、Agent SDK 是什么：从 CLI 到代码的跨越

2.1 调用 Claude Code 的三种方式

在接触 SDK 之前，你已经有两种方式：交互模式（claude 打开 REPL）和 Headless 模式（claude -p "..." 非交互执行）。两者共同特点：通过命令行调用，输入字符串，输出文本。

Agent SDK 提供了第三种方式：query(prompt="...", options={...})，把 Claude Code 变成一个 TypeScript/Python 函数——配置类型安全、流式处理响应、拦截每次工具调用、编排子代理并行干活。

2.2 SDK 不是什么

为了避免你用错，先明确 SDK 的边界：

不是 Anthropic API 的封装——如果你只需要 /v1/messages 的 HTTP 调用，用 anthropic 这个 npm/PyPI 包，不需要 Agent SDK
不含重试/持久化/多租户——SDK 不提供生产级的容错基础设施，这些需要你自己在外层实现
不含 Agent Teams——多代理并行协调是 CLI 侧的功能，SDK 提供的是子代理机制（见第六节）

SDK 适合什么：你想在自己的 Node.js 或 Python 应用里嵌入 Claude Code 的代码理解+编辑能力，而不是另外起一个 CLI 进程。

2.3 调用链路

SDK 内置了 Claude Code CLI，不需要单独安装。调用链路：你的代码 → SDK → Claude Code CLI（内置）→ Anthropic API（或 DeepSeek 兼容端点）。

2.4 两个 SDK：TypeScript 和 Python

	TypeScript	Python
包名	`@anthropic-ai/claude-agent-sdk`	`claude-agent-sdk`
最新版（2026-05）	v0.2.136	v0.1.77
安装	`npm install @anthropic-ai/claude-agent-sdk`	`pip install claude-agent-sdk`
入口函数	`query()`	`query()`
多轮对话	`query()` 支持 session	`ClaudeSDKClient`
自定义工具	通过 MCP 配置	`@tool` 装饰器 + `create_sdk_mcp_server()`
运行环境	Node.js 18+	Python 3.10+
异步模型	`for await...of`	`async for` + `anyio`

历史注：早期版本叫 @anthropic-ai/claude-code（npm）和 claude-code-sdk（PyPI），均已弃用。如果看到旧文档里的 claude() 函数或 ClaudeCodeOptions 类，那对应的是新版 query() 和 ClaudeAgentOptions。

三、TypeScript SDK：`query()` 与异步消息流

3.1 安装与最小可运行示例

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

第一个程序——让 Claude 分析当前目录：

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

async function main() {
  for await (const message of query({
    prompt: "列出当前目录的所有 .ts 文件，并简要说明每个文件的作用",
    options: {
      model: "sonnet",
      allowedTools: ["Glob", "Read"],
      maxTurns: 5,
    },
  })) {
    if (message.type === "assistant") {
      for (const block of message.message.content) {
        if ("text" in block) {
          console.log(block.text);
        }
      }
    }
    if (message.type === "result") {
      console.log("完成:", message.subtype);
      if (message.total_cost_usd) {
        console.log(`费用: $${message.total_cost_usd}`);
      }
    }
  }
}

main();

运行：

npx tsx agent.ts

3.2 `query()` 返回的消息类型

query() 返回一个 AsyncIterator，每次 yield 一种消息。你需要根据 message.type 分流处理：

`message.type`	含义	关键字段
`"assistant"`	Claude 的一轮回复	`message.message.content[]` — 文本块 / 工具调用块
`"user"`	用户输入回显	`message.message.content[]`
`"result"`	任务完成	`subtype`（成功/失败原因）、`total_cost_usd`、`session_id`
`"system"`	系统通知	初始化信息、session 恢复等

每条 AssistantMessage 的 content 是混合数组：

type ContentBlock =
  | { type: "text"; text: string }
  | { type: "tool_use"; id: string; name: string; input: object }
  | { type: "tool_result"; tool_use_id: string; content: string };

3.3 `ClaudeAgentOptions`——所有配置的入口

TypeScript 的配置对象叫 ClaudeAgentOptions（注意：不是旧版的 ClaudeCodeOptions）：

const options = {
  // 模型选择
  model: "sonnet",                // "opus" | "sonnet" | "haiku"

  // 权限控制
  allowedTools: ["Read", "Glob", "Grep", "Bash"],
  disallowedTools: ["Bash(sudo *)", "Write(/etc/*)"],
  permissionMode: "acceptEdits",  // "default" | "acceptEdits" | "plan" | "bypassPermissions"

  // 安全边界
  maxTurns: 10,                   // 必设！无默认值，不设可能无限循环
  maxBudgetUsd: 0.50,            // 单次调用费用上限

  // 工作目录
  cwd: "/path/to/project",

  // 系统提示词
  systemPrompt: "你是一个代码审查专家。只做只读分析，不要修改任何文件。",

  // 环境变量（DeepSeek 用户必修）
  env: {
    ANTHROPIC_BASE_URL: "https://api.deepseek.com/anthropic",
    ANTHROPIC_API_KEY: "sk-你的DeepSeek-API-Key",
  },

  // 子代理定义（见第六节）
  agents: { /* ... */ },

  // MCP 服务器
  mcpServers: { /* ... */ },
};

3.4 流式输出示例

for await (const msg of query({
  prompt: "审查 src/auth.ts 中的安全问题",
  options: { model: "sonnet", allowedTools: ["Read"], maxTurns: 3 },
})) {
  if (msg.type === "assistant") {
    for (const block of msg.message.content) {
      if ("text" in block) process.stdout.write(block.text);  // 逐字流式
    }
  }
  if (msg.type === "result") {
    console.log(`\n完成 · 费用: $${msg.total_cost_usd}`);
  }
}

更多实战示例见第七节。

四、Python SDK：`query()` 与 `ClaudeSDKClient`

4.1 安装与最小示例

pip install claude-agent-sdk

Python SDK 内置了 Claude Code CLI（~60MB wheel），不需要单独 npm install -g。

import anyio
from claude_agent_sdk import query, AssistantMessage, TextBlock

async def main():
    async for message in query(prompt="列出当前目录的文件结构"):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text)

anyio.run(main)

关键差异：Python SDK 用 anyio 而不是 asyncio。不要用 asyncio.run()，否则会遇到事件循环冲突。

4.2 `ClaudeAgentOptions`（Python 版）

Python 版与 TypeScript 版的字段一一对应，命名风格从 camelCase 变为 snake_case：

from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(
    model="sonnet",
    allowed_tools=["Read", "Glob", "Grep", "Bash"],
    disallowed_tools=["Bash(sudo *)"],
    permission_mode="acceptEdits",
    max_turns=10,
    max_budget_usd=0.50,
    cwd="/home/user/project",
    system_prompt="你是一个代码审查专家。",
    env={  # DeepSeek 配置
        "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
        "ANTHROPIC_API_KEY": "sk-你的DeepSeek-API-Key",
    },
    agents={},          # 子代理（见第六节）
    mcp_servers={},     # MCP 服务器
)

4.3 `ClaudeSDKClient`：多轮对话与自定义工具

query() 适合一次问答。如需持续对话或自定义工具，用 ClaudeSDKClient：

import anyio
from claude_agent_sdk import (
    ClaudeSDKClient, ClaudeAgentOptions,
    tool, create_sdk_mcp_server,
)

@tool("get_weather", "获取指定城市的天气",
      {"type": "object", "properties": {"city": {"type": "string"}},
       "required": ["city"]})
async def get_weather(args: dict) -> dict:
    return {"content": [{"type": "text",
            "text": f"{args['city']}：晴，22°C"}]}

server = create_sdk_mcp_server(name="weather", version="1.0.0",
                                tools=[get_weather])

async def main():
    async with ClaudeSDKClient(options=ClaudeAgentOptions(
        mcp_servers={"weather": server},
        allowed_tools=["mcp__weather__get_weather", "Read"],
        max_turns=5,
    )) as client:
        await client.query("北京今天天气怎么样？")
        async for msg in client.receive_response():
            print(msg)
        await client.query("那上海呢？")  # 保留上下文
        async for msg in client.receive_response():
            print(msg)

anyio.run(main)

query() vs ClaudeSDKClient：

	`query()`	`ClaudeSDKClient`
适用场景	一次性问答	多轮对话、自定义工具、Hooks
自定义工具 / Hooks	不支持	支持
会话管理	自动关闭	`async with` 手动管理
子代理	支持	支持

五、Hooks 系统：在工具执行前后插入逻辑

Hooks 是 SDK 最强的控制点——拦截危险操作、记录审计日志、动态决定权限。仅在 Python SDK 的 ClaudeSDKClient 中可用。

5.1 PreToolUse：执行前拦截

from claude_agent_sdk import HookMatcher, ClaudeSDKClient

async def pre_tool_guard(input_data, tool_use_id, context):
    tool_name = input_data.get("tool_name", "")
    tool_input = input_data.get("tool_input", {})

    if tool_name == "Bash":
        command = tool_input.get("command", "")
        for pattern in ["rm -rf /", "mkfs.", "dd if=/dev/zero"]:
            if pattern in command:
                return {"hookSpecificOutput": {
                    "hookEventName": "PreToolUse",
                    "permissionDecision": "deny",
                    "permissionDecisionReason": f"拦截：'{pattern}' 不允许",
                }}
    return {}  # 空字典 = 放行

5.2 PostToolUse：执行后审计

import json, logging

async def post_tool_audit(input_data, tool_use_id, context):
    logging.getLogger("claude-audit").info("AUDIT: %s", json.dumps({
        "tool": input_data.get("tool_name"),
        "input": str(input_data.get("tool_input", {}))[:200],
    }))
    return {}

5.3 接入 Agent

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Edit", "Bash", "Glob", "Grep"],
    permission_mode="acceptEdits",
    hooks={
        "PreToolUse": [
            HookMatcher(matcher="Bash", hooks=[pre_tool_guard]),
            HookMatcher(matcher="Write|Edit", hooks=[pre_tool_guard]),
        ],
        "PostToolUse": [HookMatcher(hooks=[post_tool_audit])],
    },
)

HookMatcher(matcher="Bash|Write|Edit", ...) 使用正则表达式匹配工具名。

六、子代理与多代理编排

6.1 子代理是什么

SDK 支持在主代理（orchestrator）下定义多个子代理（sub-agents），每个子代理有独立的工具集和系统提示词。当主代理遇到子代理专长范围内的任务时，会自动通过 Task 工具派发给它。

6.2 TypeScript 子代理示例

const options = {
  model: "opus",
  allowedTools: ["Read", "Glob", "Grep", "Task"],
  agents: {
    "code-analyzer": {
      description: "代码分析专家。分析结构和依赖。",
      tools: ["Read", "Grep", "Glob"],
      prompt: "你是代码分析专家。返回结构化分析：模块、依赖、问题。",
    },
    "security-scanner": {
      description: "安全扫描专家。搜索漏洞。",
      tools: ["Read", "Grep", "Glob"],
      prompt: "你是安全扫描专家。扫描 SQL 注入、XSS、硬编码密钥。",
    },
  },
  systemPrompt: "你是协调员。先派 code-analyzer 分析，再派 security-scanner 扫描，汇总报告。",
};

6.3 Python 子代理示例

from claude_agent_sdk import ClaudeAgentOptions, AgentDefinition

options = ClaudeAgentOptions(
    model="opus",
    allowed_tools=["Read", "Glob", "Grep", "Task"],
    agents={
        "docs-writer": AgentDefinition(
            description="文档撰写专家。",
            tools=["Read", "Glob", "Grep"],
            prompt="你是技术文档专家。根据代码生成 Markdown 文档。",
        ),
    },
    max_turns=20,
)

6.4 子代理工作机制

主代理收到 prompt → 分析任务 → 派给子代理（各自隔离上下文运行）→ 子代理返回摘要 → 主代理汇总输出。关键特性：上下文隔离、只返回摘要（省钱）、可并行、主子代理可用不同模型（主 Opus，子 Haiku）。

七、实战：构建三个工具

7.1 工具一：自动代码审查 CLI（TypeScript）

完整可运行的审查工具，输入文件路径，输出审查报告。

// code-reviewer.ts
import { query } from "@anthropic-ai/claude-agent-sdk";
import * as fs from "fs";

async function reviewFile(filePath: string) {
  const code = fs.readFileSync(filePath, "utf-8");
  const lang = filePath.endsWith(".ts") ? "TypeScript"
    : filePath.endsWith(".py") ? "Python"
    : filePath.endsWith(".go") ? "Go" : "code";

  const prompt = `审查以下 ${lang} 文件。按以下维度分析：

1. **安全性** — SQL 注入、XSS、密钥泄露、不安全加密
2. **正确性** — 逻辑错误、空值处理、边界条件
3. **可维护性** — 命名、函数长度、重复代码
4. **性能** — 不必要的循环、同步阻塞、内存泄漏

每条发现标注：严重程度（严重/中等/建议）、所在行号、问题描述、修复建议。

文件：${filePath}
\`\`\`${lang}
${code}
\`\`\``;

  console.log(`\n审查 ${filePath}...\n`);

  for await (const msg of query({
    prompt,
    options: {
      model: "sonnet",
      allowedTools: [],
      maxTurns: 1,
      systemPrompt: "你是资深代码审查专家。用中文回复。",
    },
  })) {
    if (msg.type === "assistant") {
      for (const block of msg.message.content) {
        if ("text" in block) process.stdout.write(block.text);
      }
    }
    if (msg.type === "result") {
      console.log(`\n---\n费用: $${msg.total_cost_usd} | 状态: ${msg.subtype}`);
    }
  }
}

// CLI 入口
const target = process.argv[2];
if (!target) {
  console.log("用法: npx tsx code-reviewer.ts <文件路径>");
  process.exit(1);
}
reviewFile(target);

使用：

npx tsx code-reviewer.ts src/auth/login.ts

7.2 工具二：批量代码迁移助手（Python）

扫描所有 JS 文件，逐个让 Claude 按规则迁移（CommonJS→ESM、var→const/let、==→===、回调→async/await），输出覆盖原文件：

import anyio
from pathlib import Path
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock

RULES = "1. require→import(ESM) 2. var→const/let 3. ==→=== 4. 回调→async/await"

async def migrate_file(path: str):
    code = open(path, encoding="utf-8").read()
    prompt = f"{RULES}\n\n迁移以下文件，输出完整代码：\n```js\n{code}\n```"
    text = ""
    async for msg in query(prompt=prompt, options=ClaudeAgentOptions(
        model="sonnet", allowed_tools=[], max_turns=1,
        system_prompt="只输出迁移后的代码，不要解释。",
    )):
        if isinstance(msg, AssistantMessage):
            for block in msg.content:
                if isinstance(block, TextBlock): text += block.text
    # 提取代码块
    if "```" in text:
        text = text.split("```")[1]
        if text.startswith("js"): text = text[2:]
        text = text.split("```")[0]
    open(path, "w", encoding="utf-8").write(text.strip() + "\n")
    print(f"  已迁移: {path}")

async def main():
    root = Path(".")
    files = [f for f in list(root.rglob("*.js")) + list(root.rglob("*.mjs"))
             if "node_modules" not in str(f)]
    print(f"找到 {len(files)} 个文件，开始迁移...")
    for f in files: await migrate_file(str(f))
    print(f"\n完成！请用 git diff 检查后提交。")

anyio.run(main)

7.3 工具三：从代码生成文档（TypeScript）

利用 SDK 的 Read/Glob 工具先分析项目结构，再生成 README。核心思路是两阶段调用：

// 第一阶段：分析项目结构
let analysis = "";
for await (const msg of query({
  prompt: `探索 ${projectDir} 的项目结构。列出所有 src/ 下的模块及其职责。`,
  options: { model: "sonnet", allowedTools: ["Glob", "Read", "Grep"],
             cwd: projectDir, maxTurns: 5 },
})) {
  if (msg.type === "assistant")
    for (const block of msg.message.content)
      if ("text" in block) analysis += block.text;
}

// 第二阶段：基于分析生成文档
let docs = "";
for await (const msg of query({
  prompt: `基于分析生成 README.md：\n${analysis}`,
  options: { model: "sonnet", allowedTools: [], maxTurns: 1 },
})) {
  if (msg.type === "assistant")
    for (const block of msg.message.content)
      if ("text" in block) docs += block.text;
}
fs.writeFileSync("README.md", docs, "utf-8");

完整版（含 CLI 参数解析和代码块清洗）参见前两个工具的完整结构。

八、DeepSeek 配置指南

Agent SDK 完全兼容 DeepSeek V4 系列。只需在 env 中设置两个字段（TS 和 Python 相同）：

env: {
  ANTHROPIC_BASE_URL: "https://api.deepseek.com/anthropic",
  ANTHROPIC_API_KEY: "sk-你的DeepSeek-API-Key",
}

场景	推荐模型	估算成本/次
复杂分析	DeepSeek V4-Pro（`model: "sonnet"`）	~$0.03-0.08
简单任务	DeepSeek V4-Flash（`model: "haiku"`）	~$0.003-0.01
子代理批量	全部用 Flash	~$0.01/子代理

对比 Anthropic 原生 Claude Opus 4.7（$0.30-3.00/次），DeepSeek 约 1/10 ~ 1/30 成本。注意：DeepSeek V4 是纯文本模型，不支持图片输入。

九、安全与成本控制清单

9.1 三个必须设置的参数

maxTurns: 10,          // ① 必设！无默认值 = 可能无限循环
maxBudgetUsd: 0.50,    // ② 到达预算自动停止——最后安全网
allowedTools: ["Read","Glob","Grep"],  // ③ 白名单：只开放必要的

9.2 按场景推荐配置

场景	`allowed_tools`	`max_turns`	`max_budget_usd`	`permission_mode`
只读审查	`["Read","Glob","Grep"]`	3	0.20	`"default"`
代码生成	`["Read","Write","Edit","Glob","Grep"]`	10	0.50	`"acceptEdits"`
项目重构	`["Read","Write","Edit","Bash","Glob","Grep"]`	20	1.00	`"acceptEdits"`
批量迁移	`["Read","Write","Edit","Glob","Grep"]`	5	0.30	`"acceptEdits"`

9.3 API Key 管理

// 永远从环境变量读取，不要硬编码
env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY }

十、Skill vs SDK：什么时候用哪个

读完《高手进阶（四）》和本篇，你手里有两个"自定义能力"的武器：Skill 和 SDK。它们的适用边界如下：

维度	Skill（CLI 扩展）	Agent SDK（编程调用）
创建方式	Markdown + YAML	TypeScript / Python 代码
触发方式	Claude 自动匹配 + `/command`	应用代码调用 `query()`
使用场景	Claude Code 对话增强	嵌入自己的应用、脚本、服务
自定义工具/子代理	MCP/YAML frontmatter	`@tool`/`AgentDefinition`（代码）
分发方式	Git 仓库 / 插件市场	npm / PyPI 包
适合人群	Claude Code 用户	开发者（需要写代码）

决策树：

你想做什么？
├── 让 Claude Code 对话中自动识别场景并调用
│   └── 写 Skill（见高手进阶（四））
├── 在自己的 Node.js/Python 应用里嵌入 Claude 能力
│   └── 用 Agent SDK（本篇）
├── 做一个 CI/CD 管道的自动化步骤
│   └── 用 Headless 模式 claude -p（见高手进阶（六））
└── 需要 24/7 定时运行、非事件驱动
    └── 用 Routines（见高手进阶（二））

Debug #1 — `CLINotFoundError`：找不到 Claude Code CLI

报错：claude_agent_sdk.CLINotFoundError: Claude Code not found.

根因：Python SDK 内置 CLI 二进制。wheel 安装中断或 cli_path 路径错误会触发此错误。

场景	原因	表现
pip 安装完整	CLI 在 wheel 中	正常
pip 网络中断	二进制残缺	首次调用报错
自定义 cli_path	路径错误	每次调用报错

修复：pip uninstall claude-agent-sdk -y && pip install claude-agent-sdk（重装）。或手动指定 cli_path="C:/Users/<用户名>/AppData/Roaming/npm/claude.cmd"。

验证：运行 query(prompt="回复 OK") 确认不再报错。

Debug #2 — `max_turns` 达到上限，任务未完成

报错：ResultMessage(subtype="max_turns") 或 { type: "result", subtype: "max_turns" }

根因：maxTurns 限制工具调用轮数。多步操作（读→分析→改→验证）每步消耗 1-2 轮。

max_turns	能完成	不能完成
1	纯文本问答	读文件
3	读 1-2 文件+分析	跨目录搜索
5	多文件+报告	修改+验证
10	修改+迭代	大规模重构

修复：maxTurns: taskNeedsEditing ? 10 : 3，同时加 maxBudgetUsd: 0.50 双重保险。

验证：增加 maxTurns 后重跑。若仍超限，精简 prompt——精确 prompt 比大 maxTurns 更省钱。

Debug #3 — 权限被拒绝，工具无法执行

报错：Permission denied: tool "Write" requires explicit approval.

根因：SDK 权限两层：allowed_tools（自动批准）+ permission_mode（未列出的工具怎么处理）。工具不在白名单且 permission_mode="default" → 拒绝。

allowed_tools	permission_mode	Write 行为
`["Read","Glob"]`	`"default"`	拒绝
`["Read","Glob"]`	`"acceptEdits"`	自动批准
`["Read","Write"]`	`"default"`	自动批准（已在白名单）

修复：将需要的工具加入 allowed_tools，设置 permission_mode="acceptEdits"。

验证：运行需要写入的任务，确认不再出现 Permission denied。

Debug #4 — JSON 解析失败

报错：CLIJSONDecodeError 或 SyntaxError: Unexpected token '' in JSON`

根因：Claude 返回的 JSON 被 Markdown 代码块包裹（```json\n{...}\n```）。prompt 不够明确时 Claude 会加"人类友好"包装。

prompt	Claude 输出	能否直接 parse
"输出 JSON"	```json\n{...}\n```	不能
"输出纯 JSON，不要代码块"	`{...}`	能

修复（TS）：text.replace(/^```(?:json)?\s*\n?/gm,"").replace(/\n?```\s*$/gm,"").trim()

修复（Python）：先用 json.loads(text) 尝试，失败后用 re.search(r"```(?:json)?\s*\n?(.*?)\n?```", text, re.DOTALL) 提取。

验证：运行同一查询，确认清洗函数能正确返回解析后的对象。

Debug #5 — DeepSeek Base URL 不生效

报错：CLIConnectionError: Connection timed out to api.anthropic.com（请求仍发到 Anthropic）

根因：系统环境变量 ANTHROPIC_API_KEY 与 SDK env 配置冲突。

配置方式	优先级	可靠性
SDK `env` 字段	最高	推荐
系统环境变量	中	可能冲突
`settings.json`	低	SDK 不读取

修复：在 env 中同时显式设置 ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN: ""，避免系统变量干扰。

验证：运行简单 query，在 DeepSeek 后台确认请求发到 api.deepseek.com。

速查卡

路径汇总

内容	路径
TS SDK 安装	`npm install @anthropic-ai/claude-agent-sdk`
Python SDK 安装	`pip install claude-agent-sdk`（内置 CLI ~60MB）
Anthropic API	`https://api.anthropic.com`
DeepSeek 兼容端点	`https://api.deepseek.com/anthropic`

核心 API（TS name / Python name）

操作	TS	Python
单次调用	`query({prompt,options})`	`query(prompt,options)`
多轮对话	session 参数	`ClaudeSDKClient`
自定义工具	MCP 配置	`@tool` + `create_sdk_mcp_server()`
子代理	`agents:{name:{...}}`	`agents={"name":AgentDefinition(...)}`
Hooks	不支持	`hooks={"PreToolUse":[...]}`
最大轮数/费用	`maxTurns` / `maxBudgetUsd`	`max_turns` / `max_budget_usd`
工具白/黑名单	`allowedTools` / `disallowedTools`	`allowed_tools` / `disallowed_tools`
工作目录/提示词	`cwd` / `systemPrompt`	`cwd` / `system_prompt`

报错速查

报错	根因	解决
`CLINotFoundError`	CLI 未安装或路径错误	重装 SDK
`max_turns` 超限	任务步数超限	增大限制或精简 prompt
`Permission denied`	工具不在白名单	加白名单或改 `permission_mode`
`CLIJSONDecodeError`	输出被 Markdown 包裹	清洗掉 ``` 标记后解析
`CLIConnectionError`	网络或 Base URL 错误	检查端点和代理
`ProcessError`	CLI 进程异常退出	检查 Node.js 版本

扩展阅读

本系列相关文章：

高手进阶（四）：自定义 Skill 与插件市场 — Skill 和 SDK 的选择边界，本篇第十节提供了决策树
高手进阶（五）：子代理与并行开发 — Agent 工具和子代理协作的 CLI 版
高手进阶（六）：Headless 模式与 CI/CD 集成 — Headless 模式是 SDK 的底层基础
新手上路（四）：MCP 协议实战 — SDK 中自定义工具基于 MCP 协议
新手上路（一）：六种权限模式 — SDK 的 permission_mode 与 CLI 权限模式一一对应

参考文献

@anthropic-ai/claude-agent-sdk — npm — TypeScript SDK 官方包
claude-agent-sdk — PyPI — Python SDK 官方包
Claude Agent SDK for Python — GitHub — Python SDK 源码和示例
Claude Agent SDK — TypeScript — GitHub — TypeScript SDK 源码
Claude Code 程序化调用完全指南 — CSDN 上的 SDK 中文教程
Claude Agent SDK: Agent Loops, Tool Calls, and Multi-Step Workflows — SDK 工具调用机制详解
Claude Agent SDK in Python: First Agent to Workflows — Python SDK 工作流教程

高手进阶（七）：Claude Agent SDK完全指南：TypeScript/Python双语言实战