Claude Agent SDK (ранее Claude Code 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
Устранение неполадок
Часто задаваемые вопросы
Рекомендуемые статьи

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

Это руководство охватывает всё, что нужно разработчикам для начала работы: установка, основное 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, но в виде библиотеки, которую вы импортируете и вызываете из своего кода. О правилах и области видимости на уровне проекта см. Claude Code rules и CLAUDE.md.

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	Ищет содержимое файлов с помощью 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

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

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 и обновитесь при необходимости.

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

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

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

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

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

Часто задаваемые вопросы

В чём разница между 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 лучше подходит для локальной разработки и агентов, которым нужен достуn к вашим частным файлам или сервисам.

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

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

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

Да. Установите CLAUDE_CODE_USE_BDROCK=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 Agent SDK (ранее Claude Code 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

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

Часто задаваемые вопросы

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

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

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

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

Чем 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

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

Часто задаваемые вопросы

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

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

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

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

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

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

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

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

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

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

Product

RESOURCES

Partners

Company