Миграция на Claude Agent SDK

Руководство по миграции Claude Code TypeScript и Python SDK на Claude Agent SDK

Обзор

Claude Code SDK был переименован в Claude Agent SDK, и его документация была переорганизована. Это изменение отражает более широкие возможности SDK для создания AI-агентов, выходящих за рамки только задач кодирования.

Что изменилось

Аспект	Старое	Новое
Имя пакета (TS/JS)	`@anthropic-ai/claude-code`	`@anthropic-ai/claude-agent-sdk`
Python пакет	`claude-code-sdk`	`claude-agent-sdk`
Расположение документации	Claude Code документация	API Guide → Agent SDK раздел

Шаги миграции

Для проектов TypeScript/JavaScript

1. Удалите старый пакет:

npm uninstall @anthropic-ai/claude-code

2. Установите новый пакет:

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

3. Обновите ваши импорты:

Измените все импорты с @anthropic-ai/claude-code на @anthropic-ai/claude-agent-sdk:

// До
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";

// После
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

4. Обновите зависимости в package.json:

Если у вас есть пакет в вашем package.json, обновите его:

До:

{
  "dependencies": {
    "@anthropic-ai/claude-code": "^0.0.42"
  }
}

После:

{
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.2.0"
  }
}

5. Просмотрите критические изменения

Внесите необходимые изменения в код для завершения миграции.

Для Python проектов

1. Удалите старый пакет:

pip uninstall claude-code-sdk

2. Установите новый пакет:

pip install claude-agent-sdk

3. Обновите ваши импорты:

Измените все импорты с claude_code_sdk на claude_agent_sdk:

# До
from claude_code_sdk import query, ClaudeCodeOptions

# После
from claude_agent_sdk import query, ClaudeAgentOptions

4. Обновите имена типов:

Измените ClaudeCodeOptions на ClaudeAgentOptions:

# До
from claude_code_sdk import query, ClaudeCodeOptions

options = ClaudeCodeOptions(model="claude-opus-4-7")

# После
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(model="claude-opus-4-7")

5. Просмотрите критические изменения

Внесите необходимые изменения в код для завершения миграции.

Критические изменения

Python: ClaudeCodeOptions переименован в ClaudeAgentOptions

Что изменилось: Тип Python SDK ClaudeCodeOptions был переименован в ClaudeAgentOptions.

Миграция:

# ДО (claude-code-sdk)
from claude_code_sdk import query, ClaudeCodeOptions

options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

# ПОСЛЕ (claude-agent-sdk)
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

Почему это изменилось: Имя типа теперь соответствует брендингу "Claude Agent SDK" и обеспечивает согласованность в соглашениях об именовании SDK.

Системный промпт больше не используется по умолчанию

Что изменилось: SDK больше не использует системный промпт Claude Code по умолчанию.

Миграция:

import { query } from "@anthropic-ai/claude-agent-sdk";

// ДО (v0.0.x) - Использовал системный промпт Claude Code по умолчанию
const before = query({ prompt: "Hello" });

// ПОСЛЕ (v0.1.0) - Использует минимальный системный промпт по умолчанию
// Чтобы получить старое поведение, явно запросите предустановку Claude Code:
const presetResult = query({
prompt: "Hello",
options: {
systemPrompt: { type: "preset", preset: "claude_code" }
}
});

// Или используйте пользовательский системный промпт:
const customResult = query({
prompt: "Hello",
options: {
systemPrompt: "You are a helpful coding assistant"
}
});

# ДО (v0.0.x) - Использовал системный промпт Claude Code по умолчанию
async for message in query(prompt="Hello"):
print(message)

# ПОСЛЕ (v0.1.0) - Использует минимальный системный промпт по умолчанию
# Чтобы получить старое поведение, явно запросите предустановку Claude Code:
from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
system_prompt={"type": "preset", "preset": "claude_code"}  # Используйте предустановку
),
):
print(message)

# Или используйте пользовательский системный промпт:
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),
):
print(message)

Почему это изменилось: Обеспечивает лучший контроль и изоляцию для приложений SDK. Теперь вы можете создавать агентов с пользовательским поведением без наследования инструкций, ориентированных на CLI Claude Code.

Значения по умолчанию для источников настроек

Это значение по умолчанию было кратко изменено в v0.1.0, а затем восстановлено, поэтому никаких действий по миграции не требуется.

Текущее поведение: Пропуск settingSources в query() загружает пользовательские, проектные и локальные настройки файловой системы, соответствуя CLI. Это включает ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, файлы CLAUDE.md и пользовательские команды.

Для запуска в изоляции от настроек файловой системы передайте пустой массив:

import { query } from "@anthropic-ai/claude-agent-sdk";

const isolatedResult = query({
prompt: "Hello",
options: {
settingSources: [] // Настройки файловой системы не загружаются
}
});

// Или загрузите только определённые источники:
const projectOnlyResult = query({
prompt: "Hello",
options: {
settingSources: ["project"] // Только настройки проекта
}
});

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(setting_sources=[]),  # Настройки файловой системы не загружаются
):
print(message)

# Или загрузите только определённые источники:
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
setting_sources=["project"]  # Только настройки проекта
),
):
print(message)

Изоляция особенно важна для конвейеров CI/CD, развёрнутых приложений, тестовых сред и многопользовательских систем, где локальные настройки не должны просачиваться.

Почему переименование?

Claude Code SDK был первоначально разработан для задач кодирования, но он превратился в мощную платформу для создания всех типов AI-агентов. Новое имя "Claude Agent SDK" лучше отражает его возможности:

Создание бизнес-агентов (помощники по правовым вопросам, финансовые консультанты, поддержка клиентов)
Создание специализированных агентов кодирования (боты SRE, рецензенты безопасности, агенты проверки кода)
Разработка пользовательских агентов для любой области с использованием инструментов, интеграции MCP и многого другого

Получение помощи

Если вы столкнулись с какими-либо проблемами во время миграции:

Для TypeScript/JavaScript:

Проверьте, что все импорты обновлены для использования @anthropic-ai/claude-agent-sdk
Убедитесь, что ваш package.json содержит новое имя пакета
Запустите npm install, чтобы убедиться, что зависимости обновлены

Для Python:

Проверьте, что все импорты обновлены для использования claude_agent_sdk
Убедитесь, что ваш requirements.txt или pyproject.toml содержит новое имя пакета
Запустите pip install claude-agent-sdk, чтобы убедиться, что пакет установлен

Следующие шаги

Изучите Обзор Agent SDK, чтобы узнать о доступных функциях
Ознакомьтесь со Справочником TypeScript SDK для подробной документации API
Просмотрите Справочник Python SDK для документации, специфичной для Python
Узнайте о Пользовательских инструментах и Интеграции MCP

agent-sdk/migration-guide.md +13 −7

12 12

13Claude Code SDK был переименован в **Claude Agent SDK**, и его документация была переорганизована. Это изменение отражает более широкие возможности SDK для создания AI-агентов, выходящих за рамки только задач кодирования.13Claude Code SDK был переименован в **Claude Agent SDK**, и его документация была переорганизована. Это изменение отражает более широкие возможности SDK для создания AI-агентов, выходящих за рамки только задач кодирования.

14 14

~~15<h2 id="what-s-changed">~~15<h2 id="what’s-changed">

16 Что изменилось16 Что изменилось

17</h2>17</h2>

18 18

82}82}

83```83```

84 84

~~85Вот и всё! Никаких других изменений кода не требуется.~~85**5. Просмотрите [критические изменения](#breaking-changes)**

87Внесите необходимые изменения в код для завершения миграции.

86 88

87<h3 id="for-python-projects">89<h3 id="for-python-projects">

88 Для Python проектов90 Для Python проектов

172 174

173<CodeGroup>175<CodeGroup>

174 ```typescript TypeScript theme={null}176 ```typescript TypeScript theme={null}

177 import { query } from "@anthropic-ai/claude-agent-sdk";

178

175 // ДО (v0.0.x) - Использовал системный промпт Claude Code по умолчанию179 // ДО (v0.0.x) - Использовал системный промпт Claude Code по умолчанию

176 const result = query({ prompt: "Hello" });180 const before = query({ prompt: "Hello" });

177 181

178 // ПОСЛЕ (v0.1.0) - Использует минимальный системный промпт по умолчанию182 // ПОСЛЕ (v0.1.0) - Использует минимальный системный промпт по умолчанию

179 // Чтобы получить старое поведение, явно запросите предустановку Claude Code:183 // Чтобы получить старое поведение, явно запросите предустановку Claude Code:

180 const result = query({184 const presetResult = query({

181 prompt: "Hello",185 prompt: "Hello",

182 options: {186 options: {

183 systemPrompt: { type: "preset", preset: "claude_code" }187 systemPrompt: { type: "preset", preset: "claude_code" }

185 });189 });

186 190

187 // Или используйте пользовательский системный промпт:191 // Или используйте пользовательский системный промпт:

188 const result = query({192 const customResult = query({

189 prompt: "Hello",193 prompt: "Hello",

190 options: {194 options: {

191 systemPrompt: "You are a helpful coding assistant"195 systemPrompt: "You are a helpful coding assistant"

233 237

234<CodeGroup>238<CodeGroup>

235 ```typescript TypeScript theme={null}239 ```typescript TypeScript theme={null}

236 const result = query({240 import { query } from "@anthropic-ai/claude-agent-sdk";

241

242 const isolatedResult = query({

237 prompt: "Hello",243 prompt: "Hello",

238 options: {244 options: {

239 settingSources: [] // Настройки файловой системы не загружаются245 settingSources: [] // Настройки файловой системы не загружаются

241 });247 });

242 248

243 // Или загрузите только определённые источники:249 // Или загрузите только определённые источники:

244 const result = query({250 const projectOnlyResult = query({

245 prompt: "Hello",251 prompt: "Hello",

246 options: {252 options: {

247 settingSources: ["project"] // Только настройки проекта253 settingSources: ["project"] // Только настройки проекта

agent-sdk/migration-guide.md 2026-06-16 21:57 UTC to 2026-06-17 17:02 UTC

Миграция на Claude Agent SDK

Обзор

Что изменилось

Шаги миграции

Для проектов TypeScript/JavaScript

Для Python проектов

Критические изменения

Python: ClaudeCodeOptions переименован в ClaudeAgentOptions

Системный промпт больше не используется по умолчанию

Значения по умолчанию для источников настроек

Почему переименование?

Получение помощи

Следующие шаги