Claude Agent SDK 开发指南
原 Claude Code SDK 正式更名为 Claude Agent SDK，提供更完整的 AI Agent 构建体验。本指南涵盖 Python/TypeScript 快速入门、核心概念与企业级最佳实践。
更新于 2026-09-21
什么是 Claude Agent SDK
官方改名
官方迁移指南同时重组了文档，两个名字指的是同一套库（核于 2026-09-21）。
为何改名
官方给出的理由是能力范围：这套库用于编码任务之外的 AI Agent 构建（核于 2026-09-21）。
统一工具接口
与 Claude Code 共享相同的工具系统与 Agent 循环，无缝切换本地与云端部署。
生产就绪
内置错误重试、会话管理、流式输出等企业级功能，开箱即用。
多语言支持
官方维护 Python 和 TypeScript 两套 SDK，API 设计完全对称，文档齐全。
核心概念
Tools（工具）
Agent 可调用的函数集合，用装饰器声明，自动生成 JSON Schema 供 Claude 理解和调用。
Agent Loop（代理循环）
Claude 思考 → 选择工具 → 执行 → 观察结果 → 继续思考的循环，直到任务完成。
Memory / Context（记忆）
会话内短期记忆（对话历史）与跨会话长期记忆（文件/数据库持久化）的统一管理。
Permissions（权限）
细粒度权限控制：文件系统、网络、代码执行、外部 API 等访问范围均可独立配置。
Python 快速入门
三步完成第一个 Claude Agent，全程兼容 QCode.cc 订阅服务。
步骤 1：安装 SDK
python3 -m venv .venv && source .venv/bin/activate
pip install claude-agent-sdk步骤 2：创建 Agent
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
options = ClaudeAgentOptions(
system_prompt="You are an expert Python developer",
permission_mode="acceptEdits",
)
async for message in query(
prompt="Create a Python web server", options=options
):
print(message)
asyncio.run(main())步骤 3：定义自定义工具
import asyncio
from typing import Any
from claude_agent_sdk import (
ClaudeAgentOptions, create_sdk_mcp_server, query, tool
)
@tool("get_weather", "Get current weather for a city", {"city": str})
async def get_weather(args: dict[str, Any]) -> dict[str, Any]:
return {
"content": [
{"type": "text",
"text": f"Weather in {args['city']}: 22 C, sunny"}
]
}
weather_server = create_sdk_mcp_server(
name="weather",
version="1.0.0",
tools=[get_weather],
)
options = ClaudeAgentOptions(
mcp_servers={"weather": weather_server},
allowed_tools=["mcp__weather__get_weather"],
)
async def main():
async for message in query(
prompt="What's the weather in Beijing and Shanghai?",
options=options,
):
print(message)
asyncio.run(main())TypeScript 快速入门
Node.js / Bun 环境下的 Claude Agent 开发，完整类型支持。
步骤 1：安装 SDK
npm install @anthropic-ai/claude-agent-sdk步骤 2：创建 Agent
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Create a Python web server",
options: { systemPrompt: "You are an expert Python developer" },
})) {
console.log(message);
}步骤 3：完整示例
import { tool, createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";
const getTemperature = tool(
"get_temperature",
"Get the current temperature at a location",
{
latitude: z.number().describe("Latitude coordinate"),
longitude: z.number().describe("Longitude coordinate")
},
async (args) => {
return {
content: [{ type: "text", text: `Temperature at ${args.latitude}` }]
};
}
);
const weatherServer = createSdkMcpServer({
name: "weather",
version: "1.0.0",
tools: [getTemperature]
});
for await (const message of query({
prompt: "What's the temperature in Beijing?",
options: {
mcpServers: { weather: weatherServer },
allowedTools: ["mcp__weather__get_temperature"]
}
})) {
console.log(message);
}Agent SDK vs Managed Agents
| 对比维度 |
Agent SDK
|
Managed Agents
|
|---|---|---|
| 运行环境 | 自托管（本地/自有服务器） | Anthropic 云端托管 |
| 扩容方式 | 手动管理实例 | 自动弹性伸缩 |
| 适用场景 | 原型开发、高度定制场景 | 企业生产级 Agent 部署 |
通过 QCode.cc 使用
将 ANTHROPIC_BASE_URL 设为 QCode.cc 端点即可在国内直连使用 Agent SDK，无需科学上网；可调型号见 /models。Managed Agents 由 Anthropic 托管 agent（官方文档 2026-09-22 抓取），本站没在这条链路上验过，也不代它承诺。
# Python SDK
ANTHROPIC_BASE_URL=https://api.qcode.cc/api
ANTHROPIC_API_KEY=your-qcode-api-key
# TypeScript SDK
ANTHROPIC_BASE_URL=https://api.qcode.cc/api
ANTHROPIC_API_KEY=your-qcode-api-key
# Point the endpoint at your own gateway: the SDK reads it from env
from claude_agent_sdk import ClaudeAgentOptions
options = ClaudeAgentOptions(
env={
"ANTHROPIC_BASE_URL": "https://api.qcode.cc/api",
},
)所有 Claude 模型（Fable 5 / Opus 4.8 / Sonnet 4.6 / Haiku 4.5）均可用
工具调用（Function Calling）完整支持
流式输出（Streaming）支持
与官方 Messages API 同形：Agent SDK 只改 ANTHROPIC_BASE_URL