Справочник по Python SDK

Функции

`query()`

Основная асинхронная функция для взаимодействия с Claude Code. Возвращает асинхронный итератор, который выдает сообщения по мере их поступления.

async def query(
    *,
    prompt: str | AsyncIterable[dict[str, Any]],
    options: ClaudeCodeOptions | None = None
) -> AsyncIterator[Message]

Параметры

Параметр	Тип	Описание
`prompt`	`str \| AsyncIterable[dict]`	Входной запрос как строка или асинхронный итерируемый объект для потокового режима
`options`	`ClaudeCodeOptions \| None`	Необязательный объект конфигурации (по умолчанию `ClaudeCodeOptions()` если None)

Возвращает

Возвращает AsyncIterator[Message], который выдает сообщения из разговора.

Пример - Простой запрос

import asyncio
from claude_code_sdk import query

async def main():
    async for message in query(prompt="Сколько будет 2+2?"):
        print(message)

asyncio.run(main())

Пример - С опциями


import asyncio
from claude_code_sdk import query, ClaudeCodeOptions

async def main():
    options = ClaudeCodeOptions(
        system_prompt="Вы эксперт-разработчик Python",
        permission_mode='acceptEdits',
        cwd="/home/user/project"
    )

    async for message in query(
        prompt="Создайте веб-сервер на Python",
        options=options
    ):
        print(message)


asyncio.run(main())

`tool()`

Декоратор для определения MCP инструментов с типобезопасностью.

def tool(
    name: str,
    description: str,
    input_schema: type | dict[str, Any]
) -> Callable[[Callable[[Any], Awaitable[dict[str, Any]]]], SdkMcpTool[Any]]

Параметры

Параметр	Тип	Описание
`name`	`str`	Уникальный идентификатор для инструмента
`description`	`str`	Человекочитаемое описание того, что делает инструмент
`input_schema`	`type \| dict[str, Any]`	Схема, определяющая входные параметры инструмента (см. ниже)

Опции схемы ввода

Простое сопоставление типов (рекомендуется):
```
{"text": str, "count": int, "enabled": bool}
```

Формат JSON Schema (для сложной валидации):

{
    "type": "object",
    "properties": {
        "text": {"type": "string"},
        "count": {"type": "integer", "minimum": 0}
    },
    "required": ["text"]
}

Возвращает

Функцию-декоратор, которая оборачивает реализацию инструмента и возвращает экземпляр SdkMcpTool.

Пример

from claude_code_sdk import tool
from typing import Any

@tool("greet", "Поприветствовать пользователя", {"name": str})
async def greet(args: dict[str, Any]) -> dict[str, Any]:
    return {
        "content": [{
            "type": "text",
            "text": f"Привет, {args['name']}!"
        }]
    }

`create_sdk_mcp_server()`

Создать внутрипроцессный MCP сервер, который работает внутри вашего Python приложения.

def create_sdk_mcp_server(
    name: str,
    version: str = "1.0.0",
    tools: list[SdkMcpTool[Any]] | None = None
) -> McpSdkServerConfig

Параметры

Параметр	Тип	По умолчанию	Описание
`name`	`str`	-	Уникальный идентификатор для сервера
`version`	`str`	`"1.0.0"`	Строка версии сервера
`tools`	`list[SdkMcpTool[Any]] \| None`	`None`	Список функций инструментов, созданных с декоратором `@tool`

Возвращает

Возвращает объект McpSdkServerConfig, который можно передать в ClaudeCodeOptions.mcp_servers.

Пример

from claude_code_sdk import tool, create_sdk_mcp_server

@tool("add", "Сложить два числа", {"a": float, "b": float})
async def add(args):
    return {
        "content": [{
            "type": "text",
            "text": f"Сумма: {args['a'] + args['b']}"
        }]
    }

@tool("multiply", "Умножить два числа", {"a": float, "b": float})
async def multiply(args):
    return {
        "content": [{
            "type": "text",
            "text": f"Произведение: {args['a'] * args['b']}"
        }]
    }

calculator = create_sdk_mcp_server(
    name="calculator",
    version="2.0.0",
    tools=[add, multiply]  # Передать декорированные функции
)

# Использовать с Claude
options = ClaudeCodeOptions(
    mcp_servers={"calc": calculator},
    allowed_tools=["mcp__calc__add", "mcp__calc__multiply"]
)

Классы

`ClaudeSDKClient`

Клиент для двунаправленных интерактивных разговоров с Claude Code. Предоставляет полный контроль над потоком разговора с поддержкой потоковой передачи, прерываний и динамической отправки сообщений.

class ClaudeSDKClient:
    def __init__(self, options: ClaudeCodeOptions | None = None)
    async def connect(self, prompt: str | AsyncIterable[dict] | None = None) -> None
    async def query(self, prompt: str | AsyncIterable[dict], session_id: str = "default") -> None
    async def receive_messages(self) -> AsyncIterator[Message]
    async def receive_response(self) -> AsyncIterator[Message]
    async def interrupt(self) -> None
    async def disconnect(self) -> None

Методы

Метод	Описание
`__init__(options)`	Инициализировать клиент с необязательной конфигурацией
`connect(prompt)`	Подключиться к Claude с необязательным начальным запросом или потоком сообщений
`query(prompt, session_id)`	Отправить новый запрос в потоковом режиме
`receive_messages()`	Получить все сообщения от Claude как асинхронный итератор
`receive_response()`	Получать сообщения до и включая ResultMessage
`interrupt()`	Отправить сигнал прерывания (работает только в потоковом режиме)
`disconnect()`	Отключиться от Claude

Поддержка контекстного менеджера

Клиент может использоваться как асинхронный контекстный менеджер для автоматического управления соединением:

async with ClaudeSDKClient() as client:
    await client.query("Привет Claude")
    async for message in client.receive_response():
        print(message)

Важно: При итерации по сообщениям избегайте использования break для раннего выхода, так как это может вызвать проблемы с очисткой asyncio. Вместо этого позвольте итерации завершиться естественно или используйте флаги для отслеживания того, когда вы нашли то, что нужно.

Пример - Интерактивный разговор

import asyncio
from claude_code_sdk import ClaudeSDKClient, AssistantMessage, TextBlock, ResultMessage

async def main():
    async with ClaudeSDKClient() as client:
        # Отправить начальное сообщение
        await client.query("Давайте решим математическую задачу пошагово")
        
        # Получить и обработать ответ
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Ассистент: {block.text[:100]}...")
            elif isinstance(message, ResultMessage):
                print("Ответ завершен")
        
        # Отправить дополнительный вопрос на основе ответа
        await client.query("Сколько составляет 15% от 80?")

asyncio.run(main())

Типы

`SdkMcpTool`

Определение для SDK MCP инструмента, созданного с декоратором @tool.

@dataclass
class SdkMcpTool(Generic[T]):
    name: str
    description: str
    input_schema: type[T] | dict[str, Any]
    handler: Callable[[T], Awaitable[dict[str, Any]]]

Свойство	Тип	Описание
`name`	`str`	Уникальный идентификатор для инструмента
`description`	`str`	Человекочитаемое описание
`input_schema`	`type[T] \| dict[str, Any]`	Схема для валидации ввода
`handler`	`Callable[[T], Awaitable[dict[str, Any]]]`	Асинхронная функция, которая обрабатывает выполнение инструмента

`ClaudeCodeOptions`

Класс данных конфигурации для запросов Claude Code.

@dataclass
class ClaudeCodeOptions:
    allowed_tools: list[str] = field(default_factory=list)
    max_thinking_tokens: int = 8000
    system_prompt: str | None = None
    append_system_prompt: str | None = None
    mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)
    permission_mode: PermissionMode | None = None
    continue_conversation: bool = False
    resume: str | None = None
    max_turns: int | None = None
    disallowed_tools: list[str] = field(default_factory=list)
    model: str | None = None
    permission_prompt_tool_name: str | None = None
    cwd: str | Path | None = None
    settings: str | None = None
    add_dirs: list[str | Path] = field(default_factory=list)
    env: dict[str, str] = field(default_factory=dict)
    extra_args: dict[str, str | None] = field(default_factory=dict)

Свойство	Тип	По умолчанию	Описание
`allowed_tools`	`list[str]`	`[]`	Список разрешенных имен инструментов
`max_thinking_tokens`	`int`	`8000`	Максимальное количество токенов для процесса размышления
`system_prompt`	`str \| None`	`None`	Полностью заменить системный запрос по умолчанию
`append_system_prompt`	`str \| None`	`None`	Текст для добавления к системному запросу по умолчанию
`mcp_servers`	`dict[str, McpServerConfig] \| str \| Path`	`{}`	Конфигурации MCP серверов или путь к файлу конфигурации
`permission_mode`	`PermissionMode \| None`	`None`	Режим разрешений для использования инструментов
`continue_conversation`	`bool`	`False`	Продолжить самый последний разговор
`resume`	`str \| None`	`None`	ID сессии для возобновления
`max_turns`	`int \| None`	`None`	Максимальное количество ходов разговора
`disallowed_tools`	`list[str]`	`[]`	Список запрещенных имен инструментов
`model`	`str \| None`	`None`	Модель Claude для использования
`permission_prompt_tool_name`	`str \| None`	`None`	Имя MCP инструмента для запросов разрешений
`cwd`	`str \| Path \| None`	`None`	Текущий рабочий каталог
`settings`	`str \| None`	`None`	Путь к файлу настроек
`add_dirs`	`list[str \| Path]`	`[]`	Дополнительные каталоги, к которым Claude может получить доступ
`extra_args`	`dict[str, str \| None]`	`{}`	Дополнительные аргументы CLI для передачи напрямую в CLI
`can_use_tool`	`CanUseTool \| None`	`None`	Функция обратного вызова для разрешений инструментов
`hooks`	`dict[HookEvent, list[HookMatcher]] \| None`	`None`	Конфигурации хуков для перехвата событий

`PermissionMode`

Режимы разрешений для управления выполнением инструментов.

PermissionMode = Literal[
    "default",           # Стандартное поведение разрешений
    "acceptEdits",       # Автоматически принимать редактирование файлов
    "plan",              # Режим планирования - без выполнения
    "bypassPermissions"  # Обходить все проверки разрешений (используйте с осторожностью)
]

`McpSdkServerConfig`

Конфигурация для SDK MCP серверов, созданных с create_sdk_mcp_server().

class McpSdkServerConfig(TypedDict):
    type: Literal["sdk"]
    name: str
    instance: Any  # Экземпляр MCP сервера

`McpServerConfig`

Тип объединения для конфигураций MCP серверов.

McpServerConfig = McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig

`McpStdioServerConfig`

class McpStdioServerConfig(TypedDict):
    type: NotRequired[Literal["stdio"]]  # Необязательно для обратной совместимости
    command: str
    args: NotRequired[list[str]]
    env: NotRequired[dict[str, str]]

`McpSSEServerConfig`

class McpSSEServerConfig(TypedDict):
    type: Literal["sse"]
    url: str
    headers: NotRequired[dict[str, str]]

`McpHttpServerConfig`

class McpHttpServerConfig(TypedDict):
    type: Literal["http"]
    url: str
    headers: NotRequired[dict[str, str]]

Типы сообщений

`Message`

Тип объединения всех возможных сообщений.

Message = UserMessage | AssistantMessage | SystemMessage | ResultMessage

`UserMessage`

Сообщение пользовательского ввода.

@dataclass
class UserMessage:
    content: str | list[ContentBlock]

`AssistantMessage`

Сообщение ответа ассистента с блоками содержимого.

@dataclass
class AssistantMessage:
    content: list[ContentBlock]
    model: str

`SystemMessage`

Системное сообщение с метаданными.

@dataclass
class SystemMessage:
    subtype: str
    data: dict[str, Any]

`ResultMessage`

Финальное сообщение результата с информацией о стоимости и использовании.

@dataclass
class ResultMessage:
    subtype: str
    duration_ms: int
    duration_api_ms: int
    is_error: bool
    num_turns: int
    session_id: str
    total_cost_usd: float | None = None
    usage: dict[str, Any] | None = None
    result: str | None = None

Типы блоков содержимого

`ContentBlock`

Тип объединения всех блоков содержимого.

ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock

`TextBlock`

Блок текстового содержимого.

@dataclass
class TextBlock:
    text: str

`ThinkingBlock`

Блок содержимого размышления (для моделей с возможностью размышления).

@dataclass
class ThinkingBlock:
    thinking: str
    signature: str

`ToolUseBlock`

Блок запроса использования инструмента.

@dataclass
class ToolUseBlock:
    id: str
    name: str
    input: dict[str, Any]

`ToolResultBlock`

Блок результата выполнения инструмента.

@dataclass
class ToolResultBlock:
    tool_use_id: str
    content: str | list[dict[str, Any]] | None = None
    is_error: bool | None = None

Типы ошибок

`ClaudeSDKError`

Базовый класс исключений для всех ошибок SDK.

class ClaudeSDKError(Exception):
    """Базовая ошибка для Claude SDK."""

`CLINotFoundError`

Возникает, когда Claude Code CLI не установлен или не найден.

class CLINotFoundError(CLIConnectionError):
    def __init__(self, message: str = "Claude Code не найден", cli_path: str | None = None):
        """
        Args:
            message: Сообщение об ошибке (по умолчанию: "Claude Code не найден")
            cli_path: Необязательный путь к CLI, который не был найден
        """

`CLIConnectionError`

Возникает, когда подключение к Claude Code не удается.

class CLIConnectionError(ClaudeSDKError):
    """Не удалось подключиться к Claude Code."""

`ProcessError`

Возникает, когда процесс Claude Code завершается с ошибкой.

class ProcessError(ClaudeSDKError):
    def __init__(self, message: str, exit_code: int | None = None, stderr: str | None = None):
        self.exit_code = exit_code
        self.stderr = stderr

`CLIJSONDecodeError`

Возникает, когда парсинг JSON не удается.

class CLIJSONDecodeError(ClaudeSDKError):
    def __init__(self, line: str, original_error: Exception):
        """
        Args:
            line: Строка, которую не удалось разобрать
            original_error: Исходное исключение декодирования JSON
        """
        self.line = line
        self.original_error = original_error

Типы хуков

`HookEvent`

Поддерживаемые типы событий хуков. Обратите внимание, что из-за ограничений настройки Python SDK не поддерживает хуки SessionStart, SessionEnd и Notification.

HookEvent = Literal[
    "PreToolUse",      # Вызывается перед выполнением инструмента
    "PostToolUse",     # Вызывается после выполнения инструмента
    "UserPromptSubmit", # Вызывается когда пользователь отправляет запрос
    "Stop",            # Вызывается при остановке выполнения
    "SubagentStop",    # Вызывается когда субагент останавливается
    "PreCompact"       # Вызывается перед сжатием сообщений
]

`HookCallback`

Определение типа для функций обратного вызова хуков.

HookCallback = Callable[
    [dict[str, Any], str | None, HookContext],
    Awaitable[dict[str, Any]]
]

Параметры:

input_data: Входные данные, специфичные для хука (см. документацию по хукам)
tool_use_id: Необязательный идентификатор использования инструмента (для хуков, связанных с инструментами)
context: Контекст хука с дополнительной информацией

Возвращает словарь, который может содержать:

decision: "block" для блокировки действия
systemMessage: Системное сообщение для добавления в транскрипт
hookSpecificOutput: Выходные данные, специфичные для хука

`HookContext`

Контекстная информация, передаваемая в обратные выз

`HookMatcher`

Конфигурация для сопоставления хуков с конкретными событиями или инструментами.

@dataclass
class HookMatcher:
    matcher: str | None = None        # Имя инструмента или шаблон для сопоставления (например, "Bash", "Write|Edit")
    hooks: list[HookCallback] = field(default_factory=list)  # Список обратных вызовов для выполнения

Пример использования хуков

from claude_code_sdk import query, ClaudeCodeOptions, HookMatcher, HookContext
from typing import Any

async def validate_bash_command(
    input_data: dict[str, Any],
    tool_use_id: str | None,
    context: HookContext
) -> dict[str, Any]:
    """Валидировать и потенциально блокировать опасные bash команды."""
    if input_data['tool_name'] == 'Bash':
        command = input_data['tool_input'].get('command', '')
        if 'rm -rf /' in command:
            return {
                'hookSpecificOutput': {
                    'hookEventName': 'PreToolUse',
                    'permissionDecision': 'deny',
                    'permissionDecisionReason': 'Опасная команда заблокирована'
                }
            }
    return {}

async def log_tool_use(
    input_data: dict[str, Any],
    tool_use_id: str | None,
    context: HookContext
) -> dict[str, Any]:
    """Логировать все использование инструментов для аудита."""
    print(f"Использован инструмент: {input_data.get('tool_name')}")
    return {}

options = ClaudeCodeOptions(
    hooks={
        'PreToolUse': [
            HookMatcher(matcher='Bash', hooks=[validate_bash_command]),
            HookMatcher(hooks=[log_tool_use])  # Применяется ко всем инструментам
        ],
        'PostToolUse': [
            HookMatcher(hooks=[log_tool_use])
        ]
    }
)

async for message in query(
    prompt="Проанализируйте эту кодовую базу",
    options=options
):
    print(message)

Типы ввода/вывода инструментов

Документация схем ввода/вывода для всех встроенных инструментов Claude Code. Хотя Python SDK не экспортирует их как типы, они представляют структуру входов и выходов инструментов в сообщениях.

Task

Имя инструмента: Task Ввод:

{
    "description": str,      # Краткое (3-5 слов) описание задачи
    "prompt": str,           # Задача для выполнения агентом
    "subagent_type": str     # Тип специализированного агента для использования
}

Вывод:

{
    "result": str,                    # Финальный результат от субагента
    "usage": dict | None,             # Статистика использования токенов
    "total_cost_usd": float | None,  # Общая стоимость в USD
    "duration_ms": int | None         # Длительность выполнения в миллисекундах
}

Bash

Имя инструмента: Bash Ввод:

{
    "command": str,                  # Команда для выполнения
    "timeout": int | None,           # Необязательный таймаут в миллисекундах (макс 600000)
    "description": str | None,       # Четкое, краткое описание (5-10 слов)
    "run_in_background": bool | None # Установить в true для запуска в фоне
}

Вывод:

{
    "output": str,              # Объединенный вывод stdout и stderr
    "exitCode": int,            # Код выхода команды
    "killed": bool | None,      # Была ли команда убита из-за таймаута
    "shellId": str | None       # ID оболочки для фоновых процессов
}

Edit

Имя инструмента: Edit Ввод:

{
    "file_path": str,           # Абсолютный путь к файлу для изменения
    "old_string": str,          # Текст для замены
    "new_string": str,          # Текст для замены на него
    "replace_all": bool | None  # Заменить все вхождения (по умолчанию False)
}

Вывод:

{
    "message": str,      # Сообщение подтверждения
    "replacements": int, # Количество произведенных замен
    "file_path": str     # Путь к файлу, который был отредактирован
}

MultiEdit

Имя инструмента: MultiEdit Ввод:

{
    "file_path": str,     # Абсолютный путь к файлу для изменения
    "edits": [            # Массив операций редактирования
        {
            "old_string": str,          # Текст для замены
            "new_string": str,          # Текст для замены на него
            "replace_all": bool | None  # Заменить все вхождения
        }
    ]
}

Вывод:

{
    "message": str,       # Сообщение об успехе
    "edits_applied": int, # Общее количество примененных правок
    "file_path": str      # Путь к файлу, который был отредактирован
}

Read

Имя инструмента: Read Ввод:

{
    "file_path": str,       # Абсолютный путь к файлу для чтения
    "offset": int | None,   # Номер строки для начала чтения
    "limit": int | None     # Количество строк для чтения
}

Вывод (Текстовые файлы):

{
    "content": str,         # Содержимое файла с номерами строк
    "total_lines": int,     # Общее количество строк в файле
    "lines_returned": int   # Фактически возвращенные строки
}

Вывод (Изображения):

{
    "image": str,       # Данные изображения в кодировке Base64
    "mime_type": str,   # MIME тип изображения
    "file_size": int    # Размер файла в байтах
}

Write

Имя инструмента: Write Ввод:

{
    "file_path": str,  # Абсолютный путь к файлу для записи
    "content": str     # Содержимое для записи в файл
}

Вывод:

{
    "message": str,        # Сообщение об успехе
    "bytes_written": int,  # Количество записанных байт
    "file_path": str       # Путь к файлу, который был записан
}

Glob

Имя инструмента: Glob Ввод:

{
    "pattern": str,       # Шаблон glob для сопоставления файлов
    "path": str | None    # Каталог для поиска (по умолчанию cwd)
}

Вывод:

{
    "matches": list[str],  # Массив совпадающих путей к файлам
    "count": int,          # Количество найденных совпадений
    "search_path": str     # Используемый каталог поиска
}

Grep

Имя инструмента: Grep Ввод:

{
    "pattern": str,                    # Шаблон регулярного выражения
    "path": str | None,                # Файл или каталог для поиска
    "glob": str | None,                # Шаблон glob для фильтрации файлов
    "type": str | None,                # Тип файла для поиска
    "output_mode": str | None,         # "content", "files_with_matches", или "count"
    "-i": bool | None,                 # Поиск без учета регистра
    "-n": bool | None,                 # Показать номера строк
    "-B": int | None,                  # Строки для показа перед каждым совпадением
    "-A": int | None,                  # Строки для показа после каждого совпадения
    "-C": int | None,                  # Строки для показа до и после
    "head_limit": int | None,          # Ограничить вывод первыми N строками/записями
    "multiline": bool | None           # Включить многострочный режим
}

Вывод (режим content):

{
    "matches": [
        {
            "file": str,
            "line_number": int | None,
            "line": str,
            "before_context": list[str] | None,
            "after_context": list[str] | None
        }
    ],
    "total_matches": int
}

Вывод (режим files_with_matches):

{
    "files": list[str],  # Файлы, содержащие совпадения
    "count": int         # Количество файлов с совпадениями
}

NotebookEdit

Имя инструмента: NotebookEdit Ввод:

{
    "notebook_path": str,                     # Абсолютный путь к блокноту Jupyter
    "cell_id": str | None,                    # ID ячейки для редактирования
    "new_source": str,                        # Новый исходный код для ячейки
    "cell_type": "code" | "markdown" | None,  # Тип ячейки
    "edit_mode": "replace" | "insert" | "delete" | None  # Тип операции редактирования
}

Вывод:

{
    "message": str, # Сообщение об успехе
    "edit_type": "replaced" | "inserted" | "deleted",  # Тип выполненного редактирования
    "cell_id": str | None,                       # ID ячейки, которая была затронута
    "total_cells": int                           # Общее количество ячеек в блокноте после редактирования
}

WebFetch

Имя инструмента: WebFetch Ввод:

{
    "url": str,     # URL для получения содержимого
    "prompt": str   # Запрос для выполнения на полученном содержимом
}

Вывод:

{
    "response": str,           # Ответ ИИ модели на запрос
    "url": str,                # URL, который был получен
    "final_url": str | None,   # Финальный URL после перенаправлений
    "status_code": int | None  # HTTP код состояния
}

WebSearch

Имя инструмента: WebSearch Ввод:

{
    "query": str,                        # Поисковый запрос для использования
    "allowed_domains": list[str] | None, # Включать результаты только с этих доменов
    "blocked_domains": list[str] | None  # Никогда не включать результаты с этих доменов
}

Вывод:

{
    "results": [
        {
            "title": str,
            "url": str,
            "snippet": str,
            "metadata": dict | None
        }
    ],
    "total_results": int,
    "query": str
}

TodoWrite

Имя инструмента: TodoWrite Ввод:

{
    "todos": [
        {
            "content": str, # Описание задачи
            "status": "pending" | "in_progress" | "completed",  # Статус задачи
            "activeForm": str                            # Активная форма описания
        }
    ]
}

Вывод:

{
    "message": str,  # Сообщение об успехе
    "stats": {
        "total": int,
        "pending": int,
        "in_progress": int,
        "completed": int
    }
}

BashOutput

Имя инструмента: BashOutput Ввод:

{
    "bash_id": str,       # ID фоновой оболочки
    "filter": str | None  # Необязательное регулярное выражение для фильтрации строк вывода
}

Вывод:

{
    "output": str, # Новый вывод с последней проверки
    "status": "running" | "completed" | "failed",       # Текущий статус оболочки
    "exitCode": int | None # Код выхода при завершении
}

KillBash

Имя инструмента: KillBash Ввод:

{
    "shell_id": str  # ID фоновой оболочки для завершения
}

Вывод:

{
    "message": str,  # Сообщение об успехе
    "shell_id": str  # ID завершенной оболочки
}

ExitPlanMode

Имя инструмента: ExitPlanMode Ввод:

{
    "plan": str  # План для выполнения пользователем для одобрения
}

Вывод:

{
    "message": str,          # Сообщение подтверждения
    "approved": bool | None  # Одобрил ли пользователь план
}

ListMcpResources

Имя инструмента: ListMcpResources Ввод:

{
    "server": str | None  # Необязательное имя сервера для фильтрации ресурсов
}

Вывод:

{
    "resources": [
        {
            "uri": str,
            "name": str,
            "description": str | None,
            "mimeType": str | None,
            "server": str
        }
    ],
    "total": int
}

ReadMcpResource

Имя инструмента: ReadMcpResource Ввод:

{
    "server": str,  # Имя MCP сервера
    "uri": str      # URI ресурса для чтения
}

Вывод:

{
    "contents": [
        {
            "uri": str,
            "mimeType": str | None,
            "text": str | None,
            "blob": str | None
        }
    ],
    "server": str
}

Примеры использования

Основные операции с файлами

from claude_code_sdk import query, ClaudeCodeOptions, AssistantMessage, ToolUseBlock
import asyncio

async def create_project():
    options = ClaudeCodeOptions(
        allowed_tools=["Read", "Write", "Bash"],
        permission_mode='acceptEdits',
        cwd="/home/user/project"
    )
    
    async for message in query(
        prompt="Создайте структуру проекта Python с setup.py",
        options=options
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, ToolUseBlock):
                    print(f"Использование инструмента: {block.name}")

asyncio.run(create_project())

Обработка ошибок

from claude_code_sdk import (
    query,
    CLINotFoundError,
    ProcessError,
    CLIJSONDecodeError
)

try:
    async for message in query(prompt="Привет"):
        print(message)
except CLINotFoundError:
    print("Пожалуйста, установите Claude Code: npm install -g @anthropic-ai/claude-code")
except ProcessError as e:
    print(f"Процесс завершился с кодом выхода: {e.exit_code}")
except CLIJSONDecodeError as e:
    print(f"Не удалось разобрать ответ: {e}")

Потоковый режим с клиентом

from claude_code_sdk import ClaudeSDKClient
import asyncio

async def interactive_session():
    async with ClaudeSDKClient() as client:
        # Отправить начальное сообщение
        await client.query("Какая сегодня погода?")
        
        # Обработать ответы
        async for msg in client.receive_response():
            print(msg)
        
        # Отправить дополнительный вопрос
        await client.query("Расскажите мне больше об этом")
        
        # Обработать ответ на дополнительный вопрос
        async for msg in client.receive_response():
            print(msg)

asyncio.run(interactive_session())

Использование пользовательских инструментов

from claude_code_sdk import (
    query,
    ClaudeCodeOptions,
    tool,
    create_sdk_mcp_server,
    AssistantMessage,
    TextBlock
)
import asyncio
from typing import Any

# Определить пользовательские инструменты с декоратором @tool
@tool("calculate", "Выполнить математические вычисления", {"expression": str})
async def calculate(args: dict[str, Any]) -> dict[str, Any]:
    try:
        result = eval(args["expression"], {"__builtins__": {}})
        return {
            "content": [{
                "type": "text",
                "text": f"Результат: {result}"
            }]
        }
    except Exception as e:
        return {
            "content": [{
                "type": "text",
                "text": f"Ошибка: {str(e)}"
            }],
            "is_error": True
        }

@tool("get_time", "Получить текущее время", {})
async def get_time(args: dict[str, Any]) -> dict[str, Any]:
    from datetime import datetime
    current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
    return {
        "content": [{
            "type": "text",
            "text": f"Текущее время: {current_time}"
        }]
    }

async def main():
    # Создать SDK MCP сервер с пользовательскими инструментами
    my_server = create_sdk_mcp_server(
        name="utilities",
        version="1.0.0",
        tools=[calculate, get_time]
    )
    
    # Настроить опции с сервером
    options = ClaudeCodeOptions(
        mcp_servers={"utils": my_server},
        allowed_tools=[
            "mcp__utils__calculate",
            "mcp__utils__get_time"
        ]
    )
    
    # Запросить Claude с доступными пользовательскими инструментами
    async for message in query(
        prompt="Сколько будет 123 * 456 и который сейчас час?",
        options=options
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text)

asyncio.run(main())

См. также

Руководство по Python SDK - Учебник и примеры
Обзор SDK - Общие концепции SDK
Справочник по TypeScript SDK - Документация TypeScript SDK
Справочник по CLI - Интерфейс командной строки
Общие рабочие процессы - Пошаговые руководства

Начало работы

Создавайте с Claude Code

Claude Code SDK

Развертывание

Администрирование

Конфигурация

Справочник

Ресурсы

​Функции

​query()

​Параметры

​Возвращает

​Пример - Простой запрос

​Пример - С опциями

​tool()

​Параметры

​Опции схемы ввода

​Возвращает

​Пример

​create_sdk_mcp_server()

​Параметры

​Возвращает

​Пример

​Классы

​ClaudeSDKClient

​Методы

​Поддержка контекстного менеджера

​Пример - Интерактивный разговор

​Типы

​SdkMcpTool

​ClaudeCodeOptions

​PermissionMode

​McpSdkServerConfig

​McpServerConfig

​McpStdioServerConfig

​McpSSEServerConfig

​McpHttpServerConfig

​Типы сообщений

​Message

​UserMessage

​AssistantMessage

​SystemMessage

​ResultMessage

​Типы блоков содержимого

​ContentBlock

​TextBlock

​ThinkingBlock

​ToolUseBlock

​ToolResultBlock

​Типы ошибок

​ClaudeSDKError

​CLINotFoundError

​CLIConnectionError

​ProcessError

​CLIJSONDecodeError

​Типы хуков

​HookEvent

​HookCallback

​HookContext

​HookMatcher

​Пример использования хуков

​Типы ввода/вывода инструментов

​Task

​Bash

​Edit

​MultiEdit

​Read

​Write

​Glob

​Grep

​NotebookEdit

​WebFetch

​WebSearch

​TodoWrite

​BashOutput

​KillBash

​ExitPlanMode

​ListMcpResources

​ReadMcpResource

​Примеры использования

Функции

`query()`

Параметры

Возвращает

Пример - Простой запрос

Пример - С опциями

`tool()`

Параметры

Опции схемы ввода

Возвращает

Пример

`create_sdk_mcp_server()`

Параметры

Возвращает

Пример

Классы

`ClaudeSDKClient`

Методы

Поддержка контекстного менеджера

Пример - Интерактивный разговор

Типы

`SdkMcpTool`

`ClaudeCodeOptions`

`PermissionMode`

`McpSdkServerConfig`

`McpServerConfig`

`McpStdioServerConfig`

`McpSSEServerConfig`

`McpHttpServerConfig`

Типы сообщений

`Message`

`UserMessage`

`AssistantMessage`

`SystemMessage`

`ResultMessage`

Типы блоков содержимого

`ContentBlock`

`TextBlock`

`ThinkingBlock`

`ToolUseBlock`

`ToolResultBlock`

Типы ошибок

`ClaudeSDKError`

`CLINotFoundError`

`CLIConnectionError`

`ProcessError`

`CLIJSONDecodeError`

Типы хуков

`HookEvent`

`HookCallback`

`HookContext`

`HookMatcher`

Пример использования хуков

Типы ввода/вывода инструментов

Task

Bash

Edit

MultiEdit

Read

Write

Glob

Grep

NotebookEdit

WebFetch

WebSearch

TodoWrite

BashOutput

KillBash

ExitPlanMode

ListMcpResources

ReadMcpResource

Примеры использования

Основные операции с файлами

Обработка ошибок

Потоковый режим с клиентом

Использование пользовательских инструментов

См. также