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

Обзор

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

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

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

Для проектов 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": "^1.0.0"
  }
}

// После
{
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.1.0"
  }
}

Вот и всё! Никаких других изменений кода не требуется.

Для проектов 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_agent_sdk import query, ClaudeCodeOptions

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

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

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

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

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

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

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

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

Миграция:

# ДО (v0.0.x)
from claude_agent_sdk import query, ClaudeCodeOptions

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

# ПОСЛЕ (v0.1.0)
from claude_agent_sdk import query, ClaudeAgentOptions

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

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

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

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

Миграция:

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

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

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

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

Источники параметров больше не загружаются по умолчанию

Что изменилось: SDK больше не читает параметры файловой системы (CLAUDE.md, settings.json, косые команды и т. д.) по умолчанию.

Миграция:

// ДО (v0.0.x) - Загружал все параметры автоматически
const result = query({ prompt: "Hello" });
// Читал бы из:
// - ~/.claude/settings.json (пользователь)
// - .claude/settings.json (проект)
// - .claude/settings.local.json (локальный)
// - CLAUDE.md файлы
// - Пользовательские косые команды

// ПОСЛЕ (v0.1.0) - Параметры не загружаются по умолчанию
// Чтобы получить старое поведение:
const result = query({
  prompt: "Hello",
  options: {
    settingSources: ["user", "project", "local"]
  }
});

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

Почему это изменилось: Обеспечивает предсказуемое поведение приложений SDK независимо от локальных конфигураций файловой системы. Это особенно важно для:

• Окружений CI/CD - Согласованное поведение без локальных настроек
• Развёрнутых приложений - Отсутствие зависимости от параметров файловой системы
• Тестирования - Изолированные тестовые окружения
• Многопользовательских систем - Предотвращение утечки параметров между пользователями

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

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

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

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

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

Для TypeScript/JavaScript:

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

Для Python:

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

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

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