Claude Agent SDK 使用说明

简介

Claude Agent SDK 是面向 Claude Agent / Claude Code 的软件开发工具包，用于以编程方式构建、调用、编排 Claude 智能体，支持自定义工具、会话管理、子代理调度、MCP 服务集成。

适用场景：后端服务嵌入 Claude Agent、批量任务自动化、自定义智能体工作流、封装 Claude Code 能力到自有系统
语言：主要支持 TypeScript / Python
与 Claude Code 区别：Claude Code 是命令行 / IDE 交互式工具；Agent SDK 是代码库，用于程序调用智能体能力。

前置准备

环境要求

Python 3.10+ 或 Node.js 18+
Anthropic API Key（具备 Claude Agent 权限）
网络可访问 Anthropic API

安装

Python

pip install anthropic

TypeScript / Node.js

npm install @anthropic-ai/sdk

基础示例：创建并调用 Agent

Python 示例

from anthropic import Anthropicclient = Anthropic(api_key="YOUR_API_KEY")
response = client.messages.create(
    model="claude-3-5-sonnet-latest",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "你是一个代码审查智能体，帮我审查这段Python代码"}
    ]
)
print(response.content)

TypeScript 示例

import Anthropic from "@anthropic-ai/sdk";const anthropic = new Anthropic({
  apiKey: "YOUR_API_KEY",
});
const msg = await anthropic.messages.create({
  model: "claude-3-5-sonnet-latest",
  max_tokens: 1024,
  messages: [{ role: "user", content: "你是代码审查智能体，检查代码漏洞" }],
});
console.log(msg.content);

核心能力

1. 自定义工具（Tool）

SDK 支持定义工具结构，Agent 可自主选择调用工具，类似 Claude Code 的 MCP。

定义工具名称、描述、入参 JSON Schema
Agent 输出工具调用请求
你的程序执行工具逻辑，把结果回传给 Agent

2. 会话与上下文管理

保留历史消息数组，维持多轮对话上下文
手动截断、压缩上下文，控制 token 成本
支持创建会话检查点，保存/恢复 Agent 状态

3. 子代理编排

SDK 可启动多个独立 Agent 实例，实现并行子任务：

主 Agent 拆分任务，调用多个子 Agent
收集子代理结果，汇总输出
控制并发数量，防止 API 限流

4. 流式输出（Stream）

支持流式返回，实时接收 Agent 输出，适合前端展示长文本、代码生成。

Python 流式：

stream = client.messages.stream(
    model="claude-3-5-sonnet-latest",
    max_tokens=1024,
    messages=[{"role":"user","content":"写一个Vue组件"}]
)
for event in stream:
    print(event)

集成 MCP

Agent SDK 可对接 MCP（Model Context Protocol）服务：

启动本地/远程 MCP Server
在 SDK 中注册 MCP 工具列表
Agent 自动发现并调用 MCP 能力（文件读写、浏览器、Git 等）

提示：Claude Code 内置 MCP；SDK 中需要手动接入 MCP 客户端。

配置项说明

参数	说明
model	模型版本，推荐 `claude-3-5-sonnet-latest`
max_tokens	最大输出 token
temperature	随机性，0~1；代码类任务建议 0.2~0.4
tools	自定义工具数组
system	系统提示词，定义 Agent 角色与规则

安全最佳实践

不要硬编码 API Key，使用环境变量
工具调用增加权限白名单，限制文件读写、系统命令
对用户输入做过滤，防止提示注入
增加请求限流与超时，避免高额账单
生产环境开启日志审计，记录工具调用记录

常见问题

Q：Agent SDK 和 Claude Code 能不能互通？
A：会话上下文不能直接互通。Claude Code 是本地交互式工具；SDK 是程序调用接口。可以在同一项目共用 CLAUDE.md 作为智能体规则。
Q：子代理并发太高会报错？
A：Anthropic API 存在速率限制，需要增加并发队列、重试机制。
Q：怎么使用 CLAUDE.md 给 SDK Agent 加载规则？
A：程序读取项目内 CLAUDE.md 文件，将内容放入 system 系统提示词。

小结

Claude Agent SDK 用于代码化构建智能体，适合把 Claude 能力嵌入自有应用；支持自定义工具、流式输出、子代理编排，可对接 MCP。和 Claude Code 搭配时，可共用项目规则文档 CLAUDE.md。

简介