Claude Code SDK: руководство разработчика по Python и TypeScript

Claude Code SDK — теперь официально называемый Claude Agent SDK — это библиотека для Python и TypeScript, которая позволяет запускать Claude в качестве автономного агента внутри вашего собственного приложения. Вы даете ему запрос, а он делает всё остальное: читает файлы, выполняет команды, редактирует код и повторяет действия, пока задача не будет выполнена. Никакого цикла инструментов для написания, никакой обработки потоковой передачи.

Это руководство охватывает всё, что нужно разработчикам для начала работы: установку, основной API query(), встроенные инструменты, хуки, сессии, субагенты, интеграцию с MCP и использование LLM API Novita AI в качестве модели-бэкенда.

Ключевые выводы

• Claude Code SDK теперь называется Claude Agent SDK (claude-agent-sdk для Python, @anthropic-ai/claude-agent-sdk для TypeScript).
• Одна функция query() заменяет ручной цикл выполнения инструментов, который потребовался бы с Anthropic Client SDK.
• Встроенные инструменты охватывают чтение файлов, редактирование, выполнение bash, поиск в Интернете и многое другое — без необходимости реализации.
• Сессии позволяют агентам возобновлять работу через несколько вызовов с полным сохранением контекста.
• Хуки позволяют проверять, логировать или блокировать вызовы инструментов на определенных этапах жизненного цикла.
• Совместимый с Anthropic эндпоинт Novita AI (https://api.novita.ai/anthropic) позволяет использовать высококачественные модели с открытыми весами с тем же кодом SDK.

Что такое Claude Code SDK?

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

Anthropic переименовал его в Claude Agent SDK, начиная с поколения 4.6, но оригинальный поисковый запрос “claude code sdk” по-прежнему точно описывает его суть: это уровень SDK, который находится поверх Claude Code и позволяет автоматизировать задачи агента в программном обеспечении.

Для чего он подходит:

• Автоматизированное рецензирование кода, рефакторинг или генерация тестов в CI/CD
• Агенты, которые читают и изменяют файлы, запускают скрипты или ищут информацию в Интернете от вашего имени
• Многоагентные конвейеры, где координатор делегирует подзадачи специализированным агентам
• Любые рабочие процессы, где требуется, чтобы Claude предпринимал автономные многошаговые действия, а не просто отвечал на запрос

Для чего он не подходит: Если вам нужен прямой контроль над каждым сообщением, структурированный вывод из одного вызова или потоковые ответы для чат-интерфейса, лучше подойдет Anthropic Client SDK.

Claude Code SDK против Anthropic Client SDK: что и когда использовать

Оба SDK основаны на Claude, но решают разные задачи.

	Claude Agent SDK	Anthropic Client SDK
Выполнение инструментов	Выполняется автономно Claude	Вы реализуете цикл инструментов
Интерфейс	query() возвращает асинхронный итератор	client.messages.create() возвращает объект ответа
Встроенные инструменты	Read, Write, Edit, Bash, Grep, Glob, WebSearch и другие	Нет — вы определяете и выполняете все инструменты самостоятельно
Сессии	Встроенные — возобновление по ID сессии	Ручные — управление историей разговора вручную
Лучше всего подходит для	Агентских конвейеров, CI/CD, операций с файлами	Чат-приложений, структурированного вывода, точного контроля

Если вы хотите, чтобы Claude сам определял, какие файлы читать и редактировать их автономно: используйте Agent SDK. Если вы хотите, чтобы Claude отвечал на конкретный запрос и возвращал значение, которое вы обрабатываете: используйте Client SDK.

Установка Claude Agent SDK

Python (требуется Python 3.10+):

pip install claude-agent-sdk

TypeScript / Node.js:

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

Пакет TypeScript включает встроенный нативный бинарный файл Claude Code для вашей платформы в качестве опциональной зависимости. Устанавливать Claude Code отдельно не требуется.

Чтобы проверить версию Python перед установкой:

python3 --version  # macOS/Linux
py --version       # Windows

Если pip сообщает No matching distribution found for claude-agent-sdk, ваш интерпретатор Python младше версии 3.10.

Шаг 1: Настройка аутентификации

Установите ваш API-ключ Anthropic в качестве переменной окружения:

export ANTHROPIC_API_KEY=your-api-key

SDK также поддерживает Amazon Bedrock, Google Vertex AI и Azure AI Foundry для команд, которые используют облачных провайдеров:

# Amazon Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
# плюс стандартные учётные данные AWS

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
# плюс GOOGLE_CLOUD_PROJECT и учётные данные gcloud

# Microsoft Azure AI Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
# плюс учётные данные Azure

Шаг 2: Выполните ваш первый запрос агента

Весь SDK построен вокруг одной функции: query(). Она принимает запрос и параметры и возвращает асинхронный итератор событий сообщений.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="List all Python files in this directory",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

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

for await (const message of query({
  prompt: "List all Python files in this directory",
  options: { allowedTools: ["Bash", "Glob"] }
})) {
  if ("result" in message) console.log(message.result);
}

Итератор возвращает несколько типов сообщений. Два самых полезных:

• ResultMessage (или сообщения с полем result) — окончательный ответ агента
• SystemMessage с subtype === "init" — содержит session_id для возобновления работы позже

Шаг 3: Управление разрешениями с помощью allowedTools

SDK поставляется с предварительно реализованными инструментами. Вы объявляете, какие инструменты может использовать агент; Claude занимается выполнением.

Инструмент	Что делает
Read	Чтение любого файла в рабочем каталоге
Write	Создание новых файлов
Edit	Целевые правки существующих файлов
Bash	Выполнение команд оболочки, скриптов, операций git
Glob	Поиск файлов по шаблону (**/*.ts, src/**/*.py)
Grep	Поиск содержимого файлов с помощью regex
WebSearch	Поиск в Интернете актуальной информации
WebFetch	Загрузка и разбор содержимого веб-страниц
Monitor	Наблюдение за фоновым скриптом и реакция на строки вывода
AskUserQuestion	Запрос уточняющих вопросов у пользователя в процессе задачи
Agent	Вызов определённого субагента

Комбинации Bash + Read + Edit достаточно для большинства задач автоматизации кода. Добавьте WebSearch или WebFetch, когда агенту нужны внешние данные.

allowed_tools (Python) / allowedTools (TypeScript) предварительно одобряет конкретные инструменты без дополнительных запросов. Ограничение набора инструментов также ограничивает то, что агент может сделать непреднамеренно — полезная защита для автоматизированных конвейеров.

Агент рецензирования кода только для чтения:

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="Review this codebase for security issues and code smell",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep"],
    ),
):
    if hasattr(message, "result"):
        print(message.result)

Агент полного редактирования (предварительно одобряет запись файлов):

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Edit", "Bash"],
    permission_mode="acceptEdits",
)

permission_mode="acceptEdits" автоматически одобряет правки файлов без интерактивного запроса, что требуется при выполнении в CI.

Шаг 4: Использование хуков для управления жизненным циклом

Хуки позволяют запускать пользовательский код в определённых точках выполнения агента. Вы можете логировать действия, проверять входные данные, блокировать опасные операции или обновлять внешнее состояние.

Доступные события хуков: PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStop, SubagentStart, PreCompact, Notification, PermissionRequest

В этом примере записывается журнал аудита каждый раз, когда агент редактирует или создаёт файл:

import asyncio
from datetime import datetime
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher

async def log_file_change(input_data, tool_use_id, context):
    file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
    with open("./audit.log", "a") as f:
        f.write(f"{datetime.now().isoformat()}: modified {file_path}\n")
    return {}

async def main():
    async for message in query(
        prompt="Refactor auth.py to use dataclasses",
        options=ClaudeAgentOptions(
            permission_mode="acceptEdits",
            hooks={
                "PostToolUse": [
                    HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
                ]
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

import { query, HookCallback } from "@anthropic-ai/claude-agent-sdk";
import { appendFile } from "fs/promises";

const logFileChange: HookCallback = async (input) => {
  const filePath = (input as any).tool_input?.file_path ?? "unknown";
  await appendFile("./audit.log", `${new Date().toISOString()}: modified ${filePath}\n`);
  return {};
};

for await (const message of query({
  prompt: "Refactor auth.ts to use interfaces",
  options: {
    permissionMode: "acceptEdits",
    hooks: {
      PostToolUse: [{ matcher: "Edit|Write", hooks: [logFileChange] }]
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

Хук PreToolUse, возвращающий { block: true }, полностью предотвратит вызов инструмента — полезно для обеспечения политик, таких как “никогда не удалять файлы” в автоматизированных сценариях.

Шаг 5: Возобновление работы с помощью сессий

Сессии сохраняют полный контекст агента — какие файлы он прочитал, что он нашёл, историю разговора — между несколькими вызовами query(). Это позволяет разбить длинную задачу на шаги или продолжить работу, которая была прервана.

Чтобы возобновить сессию, запишите session_id из события инициализации SystemMessage, а затем передайте его в resume:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage, ResultMessage

async def main():
    session_id = None

    # Первый запрос: чтение и анализ кодовой базы
    async for message in query(
        prompt="Read the authentication module and identify all external dependencies",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
    ):
        if isinstance(message, SystemMessage) and message.subtype == "init":
            session_id = message.data["session_id"]

    # Второй запрос: продолжение с полным контекстом из первого
    async for message in query(
        prompt="Now check if any of those dependencies have known vulnerabilities",
        options=ClaudeAgentOptions(
            resume=session_id,
            allowed_tools=["Read", "Bash", "WebSearch"],
        ),
    ):
        if isinstance(message, ResultMessage):
            print(message.result)

asyncio.run(main())

Второй запрос использует “those dependencies” — ссылка, которая имеет смысл только потому, что сессия хранит контекст из первого вызова. Без resume Claude не знал бы, о чём речь.

Шаг 6: Делегирование задач с помощью субагентов

Субагенты — это специализированные агенты, которых ваш основной агент может вызывать с помощью инструмента Agent. Основной агент координирует; субагенты выполняют целенаправленную работу. Результаты возвращаются в основной контекст.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Review this codebase: use the security-auditor agent for auth files and the style-checker agent for everything else",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            agents={
                "security-auditor": AgentDefinition(
                    description="Specialist in authentication and authorization security.",
                    prompt="Audit auth-related code for OWASP Top 10 vulnerabilities. Be specific about line numbers and risk severity.",
                    tools=["Read", "Glob", "Grep"],
                ),
                "style-checker": AgentDefinition(
                    description="Code style and maintainability reviewer.",
                    prompt="Check code for naming conventions, complexity, and documentation gaps.",
                    tools=["Read", "Glob"],
                ),
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Включите "Agent" в allowed_tools, чтобы предварительно одобрить вызовы субагентов. Сообщения от субагента содержат поле parent_tool_use_id, чтобы вы могли отследить, какой вывод от какого субагента.

Шаг 7: Подключение внешних систем через MCP

Протокол контекста модели (MCP) позволяет добавлять агенту внешние возможности — базы данных, браузеры, внутренние API — без написания пользовательских инструментов. Агент обрабатывает инструменты MCP так же, как и встроенные.

В этом примере добавляется автоматизация браузера через сервер Playwright MCP:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Open https://example.com and describe the page structure",
        options=ClaudeAgentOptions(
            mcp_servers={
                "playwright": {
                    "command": "npx",
                    "args": ["@playwright/mcp@latest"]
                }
            }
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Параметр mcp_servers принимает любой сервер, соответствующий спецификации MCP. Реестр сообщества MCP на github.com/modelcontextprotocol/servers содержит сотни интеграций, включая Postgres, Puppeteer, Slack, GitHub и варианты файловых систем.

Использование Novita AI в качестве бэкенда модели

SDK Claude Agent SDK по умолчанию использует API Anthropic, но вы можете направить его на совместимый с Anthropic эндпоинт Novita AI, чтобы использовать экономичные модели с открытыми весами — без изменений в коде.

Эндпоинт Novita AI повторяет формат API Anthropic:

https://api.novita.ai/anthropic

Установите эти две переменные окружения перед запуском агента:

export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_API_KEY="your-novita-api-key"

Ваши существующие вызовы query() будут работать без изменений. SDK автоматически считывает ANTHROPIC_BASE_URL.

Novita AI размещает ряд моделей — включая Kimi K2.5, GLM 5.2, MiniMax M2.1 и Qwen 3.5 — которые доступны через этот эндпоинт. Для команд, создающих агентские конвейеры, выполняющие тысячи задач, разница в стоимости за токен может быть значительной. См. Novita AI LLM API для текущего каталога моделей и цен.

Если вам нужно развернуть агента в изолированной песочнице — полезно для агентского выполнения кода, когда вы не хотите, чтобы агент касался вашей хост-файловой системы — Novita Agent Sandbox предоставляет среду выполнения, совместимую с E2B, специально созданную для агентов на базе Claude Agent SDK.

Claude Code SDK в конвейерах CI/CD

permission_mode="acceptEdits" и ограничения allowed_tools в SDK делают практичным запуск агентов без присмотра в CI. Типичный шаблон для GitHub Actions:

- name: Run automated code review
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    python review_agent.py

Где review_agent.py содержит что-то вроде:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Review all changed Python files in this PR for correctness and test coverage gaps. Output a JSON report.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Bash"],
            permission_mode="acceptEdits",
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Для агентов, которые записывают изменения обратно в репозиторий (автоматический рефакторинг, генерация документации), используйте хук PostToolUse, который проверяет изменения перед тем, как они попадут в git.

Устранение неполадок

No matching distribution found for claude-agent-sdk Версия Python ниже 3.10. Выполните python3 --version и обновите Python при необходимости.

ANTHROPIC_API_KEY is not set SDK требует переменную окружения. Экспортируйте её в оболочку или файл .env перед запуском.

TypeScript-агент завершается до окончания работы Убедитесь, что вы await-ите полный цикл итератора. SDK должен обработать все сообщения, прежде чем процесс завершится.

Агент использует неожиданные инструменты Используйте allowed_tools, чтобы явно ограничить набор инструментов. Если вы не укажете его, агент получит доступ ко всем встроенным инструментам.

Сообщения субагентов не отображаются в выводе Фильтруйте сообщения, у которых установлено parent_tool_use_id, чтобы отделить вывод субагента от основного агента.

Сессия не возобновляется корректно Записывайте session_id из SystemMessage с subtype === "init" в начале первого запроса, а не из сообщения результата.

FAQ

В чем разница между Claude Code SDK и Anthropic SDK?

Claude Agent SDK (ранее Claude Code SDK) предоставляет автономного агента, который автоматически управляет выполнением инструментов. Anthropic Client SDK предоставляет прямой доступ к API, где вы реализуете цикл инструментов самостоятельно. Используйте Agent SDK для агентских конвейеров; используйте Client SDK для прямых вызовов модели с точным контролем.

Какая версия Python требуется для claude-agent-sdk?

Python 3.10 или новее. Пакет не установится на Python 3.9 или старше.

Нужно ли устанавливать Claude Code CLI для использования TypeScript SDK?

Нет. Пакет @anthropic-ai/claude-agent-sdk включает собственный нативный бинарный файл Claude Code в качестве опциональной зависимости.

Может ли Claude Agent SDK использовать модели, отличные от Anthropic Claude?

Установив ANTHROPIC_BASE_URL на совместимый с Anthropic эндпоинт, например https://api.novita.ai/anthropic, вы можете использовать любую модель, которую размещает этот провайдер — включая модели с открытыми весами от Kimi, GLM, MiniMax или Qwen.

Чем Agent SDK отличается от Claude Managed Agents?

Managed Agents — это хостинговый REST API, где Anthropic запускает агента в своей инфраструктуре. Agent SDK — это библиотека, которая запускает цикл агента в вашем собственном процессе, в вашей собственной файловой системе. Agent SDK лучше подходит для локальной разработки и агентов, которым нужен доступ к вашим личным файлам или сервисам.

Поддерживает ли Claude Agent SDK потоковый вывод?

Функция query() возвращает асинхронный итератор, который выдает сообщения по мере работы агента. Это дает поведение, похожее на потоковую передачу — вы видите промежуточные результаты до финального ответа.

Могу ли я использовать Agent SDK с Amazon Bedrock или Vertex AI?

Да. Установите CLAUDE_CODE_USE_BEDROCK=1 и учётные данные AWS для Bedrock, или CLAUDE_CODE_USE_VERTEX=1 и учётные данные Google Cloud для Vertex AI.

Какую документацию по claude agent sdk следует прочитать в первую очередь?

Официальная документация находится по адресу code.claude.com/docs/en/agent-sdk/overview. Начните с краткого руководства, затем прочитайте руководства по сессиям и хукам, когда у вас появится работающий агент.

Рекомендуемые статьи

• Документация Claude Code CLI: настройка, слэш-команды и интеграция LLM API
• Vercel AI SDK: полное руководство разработчика по созданию AI-приложений
• Как развернуть и разместить Claude Agent SDK с помощью Novita Sandbox

---

Источники проверены 3 июля 2026: Claude Agent SDK docs, Novita AI LLM API