Claude Code Agent SDK入门 ― 快速构建自主智能代理

什么是Agent SDK？

Claude Code Agent SDK是一个以Claude模型为核心构建自主代理的框架。与简单的API调用不同，代理接收目标后会自行选择工具、评估结果，并执行多步推理循环来达成目标。

传统聊天机器人以”提问→回答”的单次往返完成交互。使用Agent SDK后，您可以用一条指令完成复杂的工作流——读取文件、识别问题、应用修复、运行测试并报告结果。

环境搭建

初始化项目并安装SDK。

mkdir my-agent && cd my-agent
npm init -y
npm install @anthropic-ai/claude-code --save

如果使用TypeScript开发，还需添加类型定义。

npm install typescript @types/node --save-dev
npx tsc --init

设置环境变量ANTHROPIC_API_KEY即可开始。

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

最简代理

以下是一个可以操作文件系统的简单代理示例。

import { Claude } from "@anthropic-ai/claude-code";

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  maxTurns: 10,
});

async function main() {
  const result = await agent.run(
    "列出src目录中的所有TODO注释，并按优先级排序"
  );
  console.log(result.text);
}

main();

maxTurns限制代理可执行的最大步数。务必设置此参数以防止无限循环。

定义自定义工具

Agent SDK的真正威力在于自定义工具。通过为代理提供外部API或数据库访问权限，可以实现更实用的自动化。

import { Claude, Tool } from "@anthropic-ai/claude-code";

const fetchIssueTool: Tool = {
  name: "fetch_github_issue",
  description: "获取GitHub Issue",
  parameters: {
    type: "object",
    properties: {
      owner: { type: "string", description: "仓库所有者" },
      repo: { type: "string", description: "仓库名称" },
      number: { type: "number", description: "Issue编号" },
    },
    required: ["owner", "repo", "number"],
  },
  async execute({ owner, repo, number }) {
    const res = await fetch(
      `https://api.github.com/repos/${owner}/${repo}/issues/${number}`,
      { headers: { Authorization: `token ${process.env.GITHUB_TOKEN}` } }
    );
    return await res.json();
  },
};

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  tools: [fetchIssueTool],
  maxTurns: 15,
});

定义后，代理会根据需要调用fetch_github_issue，并根据获取的信息决定下一步操作。

多步执行流程

Agent SDK的代理在内部运行以下循环：

1. 计划（Planning） ― 将用户指令分解为必要步骤
2. 工具选择（Tool Selection） ― 从可用工具中选择最优工具
3. 执行（Execution） ― 运行工具并获取结果
4. 评估（Evaluation） ― 检查是否已达成目标
5. 重复或完成 ― 未完成则返回步骤1，已完成则生成最终回答

此循环无需预先硬编码所有步骤，实现了根据情况灵活处理的能力。

实践：自动化PR审查代理

让我们构建一个实际用例——Pull Request自动审查代理。

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  tools: [fetchIssueTool, readFileTool, postCommentTool],
  maxTurns: 20,
  systemPrompt: `你是代码审查专家。
阅读PR差异并从以下角度进行审查：
- 潜在的Bug
- 安全风险
- 性能问题
- 改进建议`,
});

const result = await agent.run(
  "审查PR #42，如有问题请留下评论"
);

通过在systemPrompt中明确代理的角色和评判标准，可以实现一致且可靠的审查。

错误处理与重试

生产环境中，健壮的错误处理不可或缺。

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  maxTurns: 10,
  onError: (error, context) => {
    console.error(`步骤${context.turn}出错:`, error.message);
    if (context.turn >= 3) {
      return "abort"; // 失败3次后中止
    }
    return "retry"; // 其他情况重试
  },
});

总结与下一步

使用Agent SDK，您可以自动化跨多个步骤的复杂任务，而非依赖单次AI响应。建议从小任务（文件整理或日志分析等）开始，逐步添加工具来扩展代理的能力。

有关Claude Code的基本用法，请参阅入门指南。关于API开发方法，请查看API开发指南。CLI工具集成请参考CLI工具开发。

更多详细信息请访问Anthropic官方文档和Claude Code GitHub仓库。