Claude Agent SDK 入门：把 Claude Code 安全嵌入应用

如果你已经把 Claude Code 当作终端里的开发助手，下一步通常是把它接进内部工具、CI、PR 预审、内容发布检查或客服排障面板。这个场景现在应该看 Claude Agent SDK，而不是旧文章里常见的 @anthropic-ai/claude-code 示例。

截至 2026 年 6 月，官方文档把 TypeScript 包写为 @anthropic-ai/claude-agent-sdk，Python 包写为 claude-agent-sdk。旧名称、旧 API、旧迁移前的 ClaudeCodeOptions 仍然会出现在搜索结果里，所以发布前应以官方 Agent SDK overview 和 Migration Guide 为准。

本文不是做一个聊天机器人 demo，而是从实务角度说明如何让代理读取文件、搜索代码、调用 MCP 工具、在受限范围内修改代码、运行指定测试，并把结果交给人审查。

现在应该怎样理解 Agent SDK

Claude Agent SDK 让你在自己的 TypeScript 或 Python 程序中使用 Claude Code 的 agent loop。agent loop 可以理解为“代理的工作循环”：Claude 先判断下一步该用什么工具，读取工具结果，再决定是否继续。它和一次普通 API 调用不同，因为一次任务中可能发生多轮文件读取、搜索、编辑和命令执行。

主题	当前建议
TypeScript 包	使用 @anthropic-ai/claude-agent-sdk
Python 包	使用 claude-agent-sdk
CLI 与 SDK	CLI 适合人交互，SDK 适合应用和自动化
Client SDK 与 Agent SDK	Client SDK 需要自己实现工具循环，Agent SDK 使用 Claude Code 的内置循环
最大风险	权限越宽，自动化越强，误操作风险也越高

TypeScript SDK 通常会通过 optional dependency 带上平台对应的 Claude Code 原生二进制，因此不一定需要单独安装 CLI。但如果你的包管理器跳过 optional dependencies，就可能出现找不到 native binary 的错误。这时要修正安装策略，或把单独安装的 claude 路径传给 pathToClaudeCodeExecutable。

可复制的最小项目

下面用 TypeScript 和 tsx，不先做复杂构建，直接运行示例。

mkdir claude-agent-sdk-demo
cd claude-agent-sdk-demo
npm init -y
npm install @anthropic-ai/claude-agent-sdk zod
npm install -D typescript tsx @types/node

把 package.json 调整为这个形状：

{
  "type": "module",
  "scripts": {
    "audit": "tsx src/read-only-audit.ts",
    "runbook": "tsx src/runbook-agent.ts",
    "fix": "tsx src/safe-fix.ts"
  },
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "latest",
    "zod": "latest"
  },
  "devDependencies": {
    "@types/node": "latest",
    "tsx": "latest",
    "typescript": "latest"
  }
}

API key 只放在环境变量里，不要写进仓库、文章示例、CI 日志或截图。

export ANTHROPIC_API_KEY="sk-ant-..."

Windows PowerShell 可以这样设置：

$env:ANTHROPIC_API_KEY = "sk-ant-..."

先创建一个只读代理 src/read-only-audit.ts。它只能读文件和搜索，不能编辑，也不能执行 Bash。

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

const prompt = [
  "请以只读模式检查这个 repository。",
  "找出 TODO 注释、陈旧依赖和测试薄弱的位置。",
  "按优先级输出，并尽量包含具体文件路径。",
].join("\n");

for await (const message of query({
  prompt,
  options: {
    cwd: process.cwd(),
    allowedTools: ["Read", "Glob", "Grep"],
    maxTurns: 4,
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

运行：

npm run audit

先从只读开始非常重要。等你确认输出有用，再考虑允许 Edit、Write 或 Bash。

3 个以上值得自动化的场景

Claude Agent SDK 适合需要观察、使用工具、再做判断的任务。Masa 在内容站和开发流程里更愿意优先用在这些地方：

场景	工具	产出	护栏
PR 合并前预审	Read, Glob, Grep	风险列表、缺失测试、review 重点	最终评论由人确认
小范围修复	Read, Edit, Bash(npm test)	最小 diff 和测试结果	禁止 push、deploy 和删除命令
事故初查	MCP runbook、日志搜索	假设、相关日志、下一步确认	生产工具保持只读
多语言内容 QA	Read, Grep	乱码、缺 CTA、旧链接候选	自然语言仍需人工读

站内延伸可读 Claude Code 权限指南、MCP 服务器指南 和 Claude Code 生产力技巧。这些内容能帮助你把 SDK 代理放进可审计的日常流程，而不是让自动化悄悄运行。

用 MCP 暴露 Runbook 工具

MCP 是 Model Context Protocol，可以把外部工具和数据源暴露给代理。通俗地说，它是 Claude 可以安全调用的工具入口。官方 MCP guide 说明了如何在 Agent SDK 中接入 MCP server。你也可以在同一个进程里定义小工具。

下面的例子提供一个只读 runbook 查询工具。真实项目中可以接内部 Wiki 或事故数据库，这里用本地对象保证可复制。

import {
  createSdkMcpServer,
  query,
  tool,
} from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const runbooks: Record<string, string> = {
  billing: "检查支付失败率、Stripe webhook 和最新 deploy。",
  search: "检查 index 更新时间、Algolia task status 和 API 限制。",
  content: "检查 CMS 同步、locale slug 和 hero image 是否存在。",
};

const lookupRunbook = tool(
  "lookup_runbook",
  "根据服务名返回只读运维 Runbook",
  { service: z.string().min(1) },
  async ({ service }) => {
    const text = runbooks[service] ?? "没有找到对应 Runbook。";
    return { content: [{ type: "text", text }] };
  },
  { annotations: { readOnlyHint: true, openWorldHint: false } },
);

const runbookServer = createSdkMcpServer({
  name: "runbook",
  version: "1.0.0",
  tools: [lookupRunbook],
});

for await (const message of query({
  prompt: "content 发布事故发生时，请建议最先检查的事项。",
  options: {
    mcpServers: { runbook: runbookServer },
    allowedTools: ["mcp__runbook__lookup_runbook"],
    maxTurns: 3,
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

常见错误是工具名写错。MCP 工具在 allowedTools 中要写成 mcp__服务器名__工具名。只写 lookup_runbook 并不会批准调用。

允许编辑时要收窄权限

如果只读审计有价值，可以继续允许小范围修复。但要把边界写死。官方 permissions guide 值得在上线前完整读一遍。

创建 src/safe-fix.ts：

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

const prompt = [
  "只修复 src 下面一个小的 TypeScript 错误。",
  "修复后运行 npm test，并报告 diff 摘要和测试结果。",
  "禁止大规模重构，也不要新增依赖。",
].join("\n");

for await (const message of query({
  prompt,
  options: {
    cwd: process.cwd(),
    allowedTools: [
      "Read",
      "Glob",
      "Grep",
      "Edit",
      "Bash(npm test)",
    ],
    disallowedTools: [
      "Bash(git push)",
      "Bash(git commit)",
      "Bash(rm -rf *)",
    ],
    permissionMode: "default",
    maxTurns: 6,
  },
})) {
  if (message.type === "result") {
    console.log(message.subtype, message.result ?? "");
  }
}

这不是“让代理随便改”的模式，而是让它产生可 review 的小 diff 和测试证据。团队环境里，push、deploy、release、账单、客户数据工具都应该留在更严格的流程里。

失败模式和坑点

第一，包名过期。看到 @anthropic-ai/claude-code、claude-code-sdk 或 ClaudeCodeOptions 时，不要直接复制，先查官方迁移文档。

第二，Bash 权限过宽。只写 Bash 可能让代理考虑清理、安装依赖、git 操作或 deploy。优先写 Bash(npm test) 这种具体命令。

第三，cwd 不明确。本地、CI、后台 worker 的启动目录可能不同。生产代码里必须明确目标 repository。

第四，把 Agent SDK 当成普通聊天 SDK。代理可能读很多文件、走多轮工具调用，成本和时间都不同。上线前阅读官方 cost tracking guide，记录 usage，并设置上限。

第五，自定义工具描述太模糊。工具名、说明、输入 schema、是否只读都要清楚，否则 Claude 很难判断何时调用。

发布前检查清单与 CTA

• API key 和外部 token 不出现在日志里
• 第一次运行只允许 Read, Glob, Grep
• 允许写入时设置 cwd、allowedTools、disallowedTools、maxTurns
• MCP 工具把只读查询和破坏性操作分开
• 测试命令具体，不给宽泛 shell 权限
• 合并前由人检查 diff 和测试输出
• 发布模板前再次确认官方文档和 changelog

Claude Agent SDK 的价值不在于“能自动化多少”，而在于“边界是否让结果可审查”。这对工程团队和内容变现都重要。文章更新、CTA、产品链接、analytics event 和咨询表单都可能在一次自动化里被改动，边界不清就会影响收入路径。

个人使用可以从免费 Claude Code cheatsheet开始；需要提示词、设置模板和复用资料时，看产品模板；团队要设计权限、MCP、CI review gate 和安全 rollout 时，建议从Claude Code 培训与咨询进入。

实际验证记录

这次刷新时，我对照了官方 Agent SDK overview、TypeScript reference、MCP guide、permissions guide、migration guide 和 cost tracking 文档，把旧式 Claude Code Agent SDK 示例改成当前 @anthropic-ai/claude-agent-sdk。最有用的实践变化是：第一个示例只读运行。读者可以先用 npm run audit 观察效果，再逐步加入 MCP、编辑和测试执行。这个阶段化方式也更适合真实 repository。