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

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

Обзор

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

Переходите с OpenAI Agents SDK? Рецепт миграции OpenAI Agents SDK отображает каждый примитив на Claude 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:

Если @anthropic-ai/claude-code всё ещё указан в вашем package.json, замените его на @anthropic-ai/claude-agent-sdk и также обновите диапазон версий, например с "^0.0.42" на "^0.3.0".

5. Ознакомьтесь с критическими изменениями

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

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

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

pip uninstall -y claude-code-sdk

Если старый пакет не установлен, pip выведет WARNING: Skipping claude-code-sdk as it is not installed. Это нормально, и вы можете перейти к следующему этапу.

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

pip install claude-agent-sdk

Если claude-code-sdk указан в вашем requirements.txt или pyproject.toml, замените его на 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. Ознакомьтесь с критическими изменениями

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

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

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

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

Миграция:

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

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

# AFTER (claude-agent-sdk)
from claude_agent_sdk import query, ClaudeAgentOptions

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

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

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

Миграция:

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

// BEFORE (v0.0.x) - Used Claude Code's system prompt by default
const before = query({ prompt: "Hello" });

// AFTER (v0.1.0) - Uses minimal system prompt by default
// To get the old behavior, explicitly request Claude Code's preset:
const presetResult = query({
prompt: "Hello",
options: {
systemPrompt: { type: "preset", preset: "claude_code" }
}
});

// Or use a custom system prompt:
const customResult = query({
prompt: "Hello",
options: {
systemPrompt: "You are a helpful coding assistant"
}
});

from claude_agent_sdk import query, ClaudeAgentOptions
import asyncio


async def main():
# BEFORE (v0.0.x) - Used Claude Code's system prompt by default
async for message in query(prompt="Hello"):
print(message)

# AFTER (v0.1.0) - Uses minimal system prompt by default
# To get the old behavior, explicitly request Claude Code's preset:
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
system_prompt={"type": "preset", "preset": "claude_code"}  # Use the preset
),
):
print(message)

# Or use a custom system prompt:
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),
):
print(message)


asyncio.run(main())

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

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

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

Для работы в изоляции от параметров файловой системы передайте settingSources: [] или setting_sources=[] в Python. См. Control filesystem settings with settingSources для информации о том, что загружает каждый источник.

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

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

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