2026 Q1 正式更名

Claude Agent SDK 开发指南

原 Claude Code SDK 正式更名为 Claude Agent SDK，提供更完整的 AI Agent 构建体验。本指南涵盖 Python/TypeScript 快速入门、核心概念与企业级最佳实践。

Python & TypeScript 2026 Q1 正式更名兼容 QCode.cc 代理

什么是 Claude Agent SDK

seo_agent_sdk.rename_title

Claude Code SDK Claude Agent SDK

seo_agent_sdk.rename_desc

seo_agent_sdk.why_rename_title

seo_agent_sdk.why_rename_desc

统一工具接口

与 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

pip install anthropic-agent-sdk

步骤 2：创建 Agent

from anthropic_agent_sdk import Agent, tool

@tool
def get_weather(city: str) -> str:
    """Get current weather for a city"""
    return f"Weather in {city}: 22°C, sunny"

agent = Agent(
    model="claude-opus-4-7",
    tools=[get_weather],
    base_url="https://api.qcode.cc",  # QCode.cc proxy
    api_key="your-api-key",
)

result = agent.run("What's the weather in Beijing and Shanghai?")
print(result.output)

步骤 3：定义自定义工具

from anthropic_agent_sdk import Agent, tool
import requests

@tool
def search_web(query: str, max_results: int = 5) -> list[dict]:
    """Search the web and return results"""
    # Your search implementation here
    response = requests.get(f"https://api.search.example.com?q={query}&n={max_results}")
    return response.json()["results"]

@tool
def read_file(path: str) -> str:
    """Read contents of a local file"""
    with open(path, "r") as f:
        return f.read()

agent = Agent(
    model="claude-opus-4-7",
    tools=[search_web, read_file],
    base_url="https://api.qcode.cc",
    api_key="your-api-key",
    system="You are a helpful research assistant.",
)

result = agent.run("Search for recent news about Claude Agent SDK and summarize")
print(result.output)

TypeScript 快速入门

Node.js / Bun 环境下的 Claude Agent 开发，完整类型支持。

步骤 1：安装 SDK

npm install @anthropic-ai/agent-sdk

步骤 2：创建 Agent

import { Agent, tool } from '@anthropic-ai/agent-sdk';

const getWeather = tool({
  name: 'get_weather',
  description: 'Get current weather for a city',
  parameters: { city: { type: 'string' } },
  execute: async ({ city }) => `Weather in ${city}: 22°C, sunny`,
});

const agent = new Agent({
  model: 'claude-opus-4-7',
  tools: [getWeather],
  baseURL: 'https://api.qcode.cc',
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const result = await agent.run("What's the weather in Beijing?");
console.log(result.output);

步骤 3：完整示例

import { Agent, tool } from '@anthropic-ai/agent-sdk';

const searchWeb = tool({
  name: 'search_web',
  description: 'Search the web for information',
  parameters: {
    query: { type: 'string', description: 'Search query' },
    maxResults: { type: 'number', description: 'Max results', default: 5 },
  },
  execute: async ({ query, maxResults = 5 }) => {
    const res = await fetch(`https://api.search.example.com?q=${query}&n=${maxResults}`);
    const data = await res.json();
    return data.results;
  },
});

const agent = new Agent({
  model: 'claude-opus-4-7',
  tools: [searchWeb],
  baseURL: 'https://api.qcode.cc',
  apiKey: process.env.ANTHROPIC_API_KEY,
  systemPrompt: 'You are a helpful research assistant.',
  maxTurns: 10,
});

// Streaming support
for await (const event of agent.stream("Research the latest AI agent frameworks")) {
  if (event.type === 'text') process.stdout.write(event.text);
}

Agent SDK vs Managed Agents

seo_agent_sdk.vs_col_feature	seo_agent_sdk.vs_col_sdk	seo_agent_sdk.vs_col_managed
seo_agent_sdk.vs_row1_feature	自托管（本地/自有服务器）	Anthropic 云端托管
seo_agent_sdk.vs_row2_feature	手动管理实例	自动弹性伸缩
seo_agent_sdk.vs_row3_feature	原型开发、高度定制场景	企业生产级 Agent 部署

seo_agent_sdk.vs_managed_link

通过 QCode.cc 使用

将 ANTHROPIC_BASE_URL 设为 QCode.cc 端点，Agent SDK 的所有功能均可在国内稳定使用，无需科学上网。

.env

# Python SDK
ANTHROPIC_BASE_URL=https://api.qcode.cc
ANTHROPIC_API_KEY=your-qcode-api-key

# TypeScript SDK
ANTHROPIC_BASE_URL=https://api.qcode.cc
ANTHROPIC_API_KEY=your-qcode-api-key

# Or set inline
agent = Agent(
    base_url="https://api.qcode.cc",
    api_key="your-qcode-api-key",
)

所有 Claude 模型（Opus 4.7 / Sonnet 4.6 / Haiku 4.5）均可用

工具调用（Function Calling）完整支持

流式输出（Streaming）支持

与 Managed Agents API 完全兼容

立即开始构建 AI Agent

seo_agent_sdk.cta_btn_signup seo_agent_sdk.cta_btn_pricing