Claude Code SDK (Claude Agent SDK): руководство по Python и TypeScript

Содержание

Основные выводы
Что такое Claude Code SDK?
Claude Code SDK против Anthropic Client SDK: когда что использовать
Установка Claude Agent SDK
Шаг 1: Настройка аутентификации
Шаг 2: Выполнение первого запроса агента
Шаг 3: Управление разрешениями с помощью allowedTools
Шаг 4: Использование хуков для контроля жизненного цикла
Шаг 5: Возобновление работы с помощью сессий
Шаг 6: Делегирование задач с помощью подагентов
Шаг 7: Подключение внешних систем через MCP
Использование Novita AI в качестве бэкенда для моделей
Claude Code SDK в пайплайнах CI/CD
Устранение неполадок
FAQ
Рекомендуемые статьи

Claude Code SDK, переименованный в Claude Agent SDK в рамках релиза агентского SDK от Anthropic, — это библиотека для Python и TypeScript, позволяющая запускать автономные агенты кодирования внутри вашего приложения. Она обрабатывает чтение файлов, команды, редактирование кода, вызовы инструментов и многошаговые итерации без необходимости вручную реализовывать цикл инструментов. С помощью совместимой с Anthropic конечной точки Novita AI тот же SDK может также запускать поддерживаемые модели с открытым весом, предоставляя командам возможность выбора модели и контроля затрат, выходящую за рамки стандартного бэкенда Anthropic.

Это руководство охватывает всё, что нужно разработчикам для начала работы: установку, основной 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	Выполняет shell-команды, скрипты, операции git
Glob	Находит файлы по шаблону (`*/.ts`, `src/*/.py`)
Grep	Ищет содержимое файлов с помощью регулярных выражений
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

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

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

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 в качестве бэкенда для моделей

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

Ограничения SDK permission_mode="acceptEdits" и allowed_tools делают его практичным для запуска агентов без присмотра в 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 и обновите при необходимости.

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 использовать модели, отличные от Claude от Anthropic?

Установив 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.

С какой документации по anthropic claude agent sdk начать?

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

Claude Code SDK (Claude Agent SDK): руководство по Python и TypeScript

Основные выводы

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

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

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

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

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

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

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

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

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

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

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

Claude Code SDK в пайплайнах CI/CD

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

FAQ

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

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

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

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

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

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

Можно ли использовать Agent SDK с Amazon Bedrock или Vertex AI?

С какой документации по anthropic claude agent sdk начать?

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

Product

RESOURCES

Partners

Company

Основные выводы

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

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

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

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

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

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

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

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

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

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

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

Claude Code SDK в пайплайнах CI/CD

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

FAQ

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

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

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

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

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

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

Можно ли использовать Agent SDK с Amazon Bedrock или Vertex AI?

С какой документации по anthropic claude agent sdk начать?

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

Похожие статьи

Product

RESOURCES

Partners

Company