Claude Code Agent SDK 完整开发者指南 2026

2026 年 Claude Code Agent SDK 的完整开发者指南。了解安装、Agent 循环、工具、子代理、MCP 集成，以及如何用内置运行时补齐能力缺口。

带有发光 AI agent SDK 代码的代码编辑器窗口，背景是带电路板纹理的深蓝与紫色渐变

Anthropic 的 Agent SDK 将 Claude Code 从终端助手变成了可编程、可自动化的 AI 代理，你可以把它嵌入自己的工作流中。本指南涵盖从安装、agent 循环、工具集成、MCP 服务器、子代理编排，到面向生产环境需要补齐的能力缺口。

什么是 Claude Code Agent SDK？

Claude Code Agent SDK，也称为 Claude Agent SDK 或 Claude Code SDK，是 Anthropic 用于构建由 Claude 驱动的自治 AI 代理的 Python 和 TypeScript 库。它封装了支撑 Claude Code CLI 的同一套 agent 循环、工具系统和沙箱执行环境，并将其作为可由你自己代码调用的 SDK 提供出来。

该 SDK 于 2026 年初发布，是 Anthropic 推动让 AI 代理不仅能交互，还能被程序化控制的一部分。

它和直接使用 Claude API 有什么不同

功能	Claude API	Claude Agent SDK
Agent 循环	你自己构建	内置：规划 → 执行 → 观察 → 重复
文件系统访问	没有	读取、写入、编辑文件
Shell 执行	没有	在沙箱中执行 Bash 命令
工具调用	手动定义函数	内置工具 + 支持 MCP 服务器
子代理	不可用	可启动并行代理工作线程
上下文管理	手动	自动压缩与摘要

如果你现在正在使用 Claude API，并且自己编写带有手动工具处理的 agent 循环，那么 Agent SDK 可以替你省去数百行样板代码。

安装与设置

前提条件

Python 3.10+ 或 TypeScript/Node.js 20+
Anthropic API key 或 Claude Code Pro/Max/Enterprise 订阅
已安装 Claude Code CLI，因为 SDK 会把它当作运行时使用

第一步：安装 Claude Code CLI

npm install -g @anthropic-ai/claude-code

或者使用 claude.ai/download 提供的原生安装程序。

第二步：安装 Agent SDK

Python：

pip install claude-agent-sdk

TypeScript：

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

第三步：完成认证

claude login

按照 OAuth 流程完成登录。你的 API key 会保存在本地，并由 SDK 自动使用。

你的第一个代理：漏洞扫描器

下面是一个最小化的 Python 代理，用于扫描目录中的 bug：

from claude_agent_sdk import Agent, tool

@tool
def read_file(path: str) -> str:
    """读取文件并返回其内容。"""
    with open(path, 'r') as f:
        return f.read()

@tool  
def list_files(directory: str = ".") -> list:
    """列出目录中的所有文件。"""
    import os
    return os.listdir(directory)

agent = Agent(
    system_prompt="你是一名代码审查员。请找出 bug 并提出修复建议。",
    tools=[read_file, list_files],
    model="claude-sonnet-4-20250514"
)

result = agent.run("审查 ./src 中的代码，查找安全问题")
print(result.output)

底层发生了什么

代理接收任务并读取你的系统提示词
它调用 list_files("./src") 来发现代码库
它对每个源文件调用 read_file(path)
它使用 Claude 的推理能力分析代码
它返回带有行号和修复建议的结果

SDK 会处理整个循环，因此你无需自己编写计划-执行-观察逻辑。

核心概念

Agent 循环

任务 → 规划 → 工具调用 → 观察结果 → 重新规划 → ... → 最终答案

每次迭代：

Claude 决定下一步做什么
根据需要调用工具
接收工具输出
决定继续还是结束

SDK 通过压缩机制，也就是对较早轮次进行摘要，以及子代理委派，自动管理上下文窗口限制。

工具与 tool 装饰器

工具就是你暴露给代理的函数。SDK 提供了若干内置工具：

# 内置文件操作，自动可用
agent = Agent(
    tools=["read", "write", "edit", "glob", "grep", "bash", "task"]
)

自定义工具使用 @tool 装饰器：

from claude_agent_sdk import tool

@tool
def search_docs(query: str, max_results: int = 5) -> str:
    """在内部文档中搜索给定查询。"""
    # 你的搜索实现
    return results

agent = Agent(tools=[search_docs])

子代理：并行处理

子代理可以让你启动独立的 Claude 实例来并行工作：

agent = Agent(
    system_prompt="你是一名审查代码库的技术负责人。",
    tools=["task"]  # 启用子代理启动
)

result = agent.run("""
    并行审查 ./frontend/ 和 ./backend/。
    对每个目录使用子代理，然后汇总发现。
""")

子代理在隔离的上下文中运行，并独立返回结果。这也是 Claude Code 自身处理大规模操作的方式。

MCP 服务器集成

SDK 支持 Model Context Protocol 服务器，也就是向代理暴露工具的外部服务：

agent = Agent(
    mcp_servers=[
        {
            "command": "npx",
            "args": ["-y", "@anthropic-ai/mcp-server-filesystem"],
            "env": {"ALLOWED_DIRECTORIES": "/project"}
        }
    ]
)

MCP 服务器可以增加数据库访问、API 集成、第三方服务等等。

Agent SDK 不能做什么，以及如何补齐缺口

Claude Code Agent SDK 让你的代理具备文件访问、Shell 执行和代码操作能力。但它有 五个主要能力缺口：

1. 图像生成

你的代理可以编写调用图像 API 的代码，但不能直接生成或查看图像。对于构建 UI、进行设计原型或制作文档的代理来说，这是真实限制。

解决方案：给代理配一个处理图像生成的能力运行时。只需一行配置，你的代理就能从文本生成图像、迭代设计并嵌入结果。

2. 视频生成

视频能力更远。你的代理可以编写 ffmpeg 命令，但不能生成新的视频内容。

3. 带有依据的网页搜索

Claude Code 代理可以使用 curl 或 fetch API，但不能执行带有依据和引用的语义化网页搜索。对于研究代理、内容代理以及任何需要最新信息的工作流，这一点很重要。

4. 云存储与文件共享

SDK 的文件系统访问只限本地。对于需要保存输出、与人共享文件或跨会话持久化数据的代理，你需要云存储。

5. 发布与部署

你的代理可以产出制品，但要把它上线，比如网页、可共享报告或已部署应用，就需要单独的基础设施。

一条命令的解决方案

与其配置五个独立的 MCP 服务器，每个都有自己的 API key、维护成本和 token 开销，不如使用一个 能力运行时，也就是把图像生成、视频、网页搜索、云存储和发布打包到同一端点的单个 CLI 工具。

例如，AnyCap 在一个 CLI 里提供五种能力：图像生成、视频、网页搜索、云存储和页面发布，让你只需几分钟完成配置，而不是几个小时。

生产环境考虑

上下文窗口管理

Agent SDK 会自动处理上下文压缩，但对于运行超过 100 轮的长生命周期代理，你应该：

使用子代理 来处理大型并行任务，而不是顺序处理
保持系统提示词简洁，系统提示词中的每个 token 在每一轮都会产生开销
避免把大文件加载进上下文，当工具可以返回摘要时更应如此

成本控制

一次典型的 SDK 代理会话成本大约在 0.50 到 3.00 美元之间，具体取决于任务复杂度。要控制成本：

设置 max_turns 防止无限循环
简单子代理使用 Haiku，主代理使用 Sonnet
通过 Anthropic 控制台仪表板监控使用情况

安全性

SDK 在沙箱中运行命令，但你仍然应该：

使用 ALLOWED_DIRECTORIES 限制文件系统访问
永远不要让生产代理访问凭证或 .env 文件
在非交互模式下审查代理动作

Claude Code SDK vs Claude Agent SDK：有什么区别？

这些术语经常混用，但它们之间有区别：

	Claude Code SDK	Claude Agent SDK
范围	与 Claude Code 交互的较低层 API	更高层的代理框架
Python 包	`claude-agent-sdk` 的一部分	主要接口就是 `claude-agent-sdk`
使用场景	对 Claude Code 会话进行程序化控制	构建自治代理
文档	code.claude.com/docs/en/agent-sdk	code.claude.com/docs/en/agent-sdk/overview

实际上，大多数开发者会把 Agent SDK 作为入口。更底层的 SDK API 则用于自定义会话管理等高级场景。

什么时候使用 Agent SDK，而不是 Claude Code CLI

场景	使用
交互式编码会话	Claude Code CLI
一次性代码审查	Claude Code CLI
自动化 PR 审查流水线	Agent SDK
定时数据处理	Agent SDK
CI/CD 集成	Agent SDK
多步骤研究代理	Agent SDK
在 Claude 之上构建产品	Agent SDK

经验法则很简单：如果你在输入命令，就用 CLI。如果你在编写需要调用 Claude 的代码，就用 SDK。

总结

Claude Code Agent SDK 将 Claude 从终端伙伴变成了可编程的代理运行时。借助内置文件操作、Shell 访问、子代理编排和 MCP 服务器支持，它承担了代理基础设施中最繁重的部分。

但只能读文件和运行 bash 的代理，只算半个代理。要构建能够搜索网页、生成图像和视频、把输出存到云端并发布结果的代理，你需要一层能力层。SDK 给代理大脑；像 AnyCap 这样的能力运行时则给它眼睛、手和声音。

Claude Code Agent SDK：2026 完整开发者指南