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

Полный справочник API для Python Agent SDK, включая все функции, типы и классы.

Установка

Установите пакет в виртуальное окружение. На недавних установках Debian, Ubuntu и Homebrew Python запуск pip install для системного Python завершается ошибкой error: externally-managed-environment.

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

Для uv, Windows PowerShell и настройки API ключа см. Начало работы в быстром старте Agent SDK.

Выбор между `query()` и `ClaudeSDKClient`

Python SDK предоставляет два способа взаимодействия с Claude Code:

Используйте ClaudeSDKClient для интерактивных приложений, таких как интерфейсы чата, или когда следующее действие зависит от ответа Claude.

Функции

`query()`

Создает новый сеанс для каждого взаимодействия с Claude Code по умолчанию. Возвращает асинхронный итератор, который выдает сообщения по мере их поступления. Каждый вызов query() начинается с нуля без памяти о предыдущих взаимодействиях, если вы не передадите continue_conversation=True или resume в ClaudeAgentOptions. См. Sessions.

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

Параметры

Возвращаемое значение

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

Пример - С параметрами

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    options = ClaudeAgentOptions(
        system_prompt="You are an expert Python developer",
        permission_mode="acceptEdits",
    )

    async for message in query(prompt="Create a Python web server", options=options):
        print(message)


asyncio.run(main())

`tool()`

Декоратор для определения MCP tools с проверкой типов.

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

Параметры

Варианты схемы ввода

1. Простое сопоставление типов (рекомендуется):

   {"text": str, "count": int, "enabled": bool}
   

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

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

Возвращаемое значение

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

Пример

from claude_agent_sdk import tool
from typing import Any


@tool("greet", "Greet a user", {"name": str})
async def greet(args: dict[str, Any]) -> dict[str, Any]:
    return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]}

`ToolAnnotations`

Подсказки поведения для инструмента, передаваемые как аргумент annotations функции tool(). ToolAnnotations расширяет mcp.types.ToolAnnotations SDK MCP с полем maxResultSizeChars, и вы можете писать каждую подсказку в camelCase или snake_case: ToolAnnotations(readOnlyHint=True) и ToolAnnotations(read_only_hint=True) эквивалентны. Вы также можете передать простой mcp.types.ToolAnnotations везде, где SDK принимает аннотации.

Имена snake_case и типизированное поле maxResultSizeChars требуют Python Agent SDK 0.2.140 или позже. Версии 0.1.31 по 0.2.139 переэкспортируют mcp.types.ToolAnnotations без изменений. В версиях 0.1.55 по 0.2.139 вы все еще можете передать maxResultSizeChars как аргумент ключевого слова: класс MCP принимает дополнительные поля, и SDK пересылает значение в Claude Code.

Все поля являются дополнительными. Клиенты не должны полагаться на подсказки для решений безопасности.

from claude_agent_sdk import tool, ToolAnnotations
from typing import Any


@tool(
    "search",
    "Search the web",
    {"query": str},
    annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
)
async def search(args: dict[str, Any]) -> dict[str, Any]:
    return {"content": [{"type": "text", "text": f"Results for: {args['query']}"}]}

`create_sdk_mcp_server()`

Создайте встроенный MCP server, который работает в вашем приложении Python.

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

Параметры

Возвращаемое значение

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

Пример

from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions


@tool("add", "Add two numbers", {"a": float, "b": float})
async def add(args):
    return {"content": [{"type": "text", "text": f"Sum: {args['a'] + args['b']}"}]}


@tool("multiply", "Multiply two numbers", {"a": float, "b": float})
async def multiply(args):
    return {"content": [{"type": "text", "text": f"Product: {args['a'] * args['b']}"}]}


calculator = create_sdk_mcp_server(
    name="calculator",
    version="2.0.0",
    tools=[add, multiply],  # Pass decorated functions
)

# Use with Claude
options = ClaudeAgentOptions(
    mcp_servers={"calc": calculator},
    allowed_tools=["mcp__calc__add", "mcp__calc__multiply"],
)

`list_sessions()`

Выводит список прошлых сеансов с метаданными. Фильтруйте по каталогу проекта или выводите сеансы во всех проектах. Синхронно; возвращается немедленно.

def list_sessions(
    directory: str | None = None,
    limit: int | None = None,
    offset: int = 0,
    include_worktrees: bool = True
) -> list[SDKSessionInfo]

Параметры

Тип возвращаемого значения: `SDKSessionInfo`

Пример

Выведите 10 самых последних сеансов для проекта. Результаты отсортированы по last_modified в убывающем порядке, поэтому первый элемент - самый новый. Опустите directory, чтобы искать во всех проектах.

from claude_agent_sdk import list_sessions

for session in list_sessions(directory="/path/to/project", limit=10):
    print(f"{session.summary} ({session.session_id})")

`get_session_messages()`

Извлекает сообщения из прошлого сеанса. Синхронно; возвращается немедленно.

def get_session_messages(
    session_id: str,
    directory: str | None = None,
    limit: int | None = None,
    offset: int = 0
) -> list[SessionMessage]

Параметры

Тип возвращаемого значения: `SessionMessage`

Пример

from claude_agent_sdk import list_sessions, get_session_messages

sessions = list_sessions(limit=1)
if sessions:
    messages = get_session_messages(sessions[0].session_id)
    for msg in messages:
        print(f"[{msg.type}] {msg.uuid}")

`get_session_info()`

Читает метаданные для одного сеанса по ID без сканирования полного каталога проекта. Синхронно; возвращается немедленно.

def get_session_info(
    session_id: str,
    directory: str | None = None,
) -> SDKSessionInfo | None

Параметры

Возвращает SDKSessionInfo или None, если сеанс не найден.

Пример

Найдите метаданные одного сеанса без сканирования каталога проекта. Полезно, когда у вас уже есть ID сеанса из предыдущего запуска.

from claude_agent_sdk import get_session_info

info = get_session_info("550e8400-e29b-41d4-a716-446655440000")
if info:
    print(f"{info.summary} (branch: {info.git_branch}, tag: {info.tag})")

`rename_session()`

Переименовывает сеанс, добавляя запись с пользовательским названием. Повторные вызовы безопасны; побеждает самое последнее название. Синхронно.

def rename_session(
    session_id: str,
    title: str,
    directory: str | None = None,
) -> None

Параметры

Вызывает ValueError, если session_id не является допустимым UUID или title пуст; FileNotFoundError, если сеанс не найден.

Пример

Переименуйте самый последний сеанс, чтобы его было легче найти позже. Новое название появляется в SDKSessionInfo.custom_title при последующих чтениях.

from claude_agent_sdk import list_sessions, rename_session

sessions = list_sessions(directory="/path/to/project", limit=1)
if sessions:
    rename_session(sessions[0].session_id, "Refactor auth module")

`tag_session()`

Помечает сеанс. Передайте None для очистки тега. Повторные вызовы безопасны; побеждает самый последний тег. Синхронно.

def tag_session(
    session_id: str,
    tag: str | None,
    directory: str | None = None,
) -> None

Параметры

Вызывает ValueError, если session_id не является допустимым UUID или tag пуст после очистки; FileNotFoundError, если сеанс не найден.

Пример

Пометьте сеанс, затем отфильтруйте по этому тегу при последующем чтении. Передайте None для очистки существующего тега.

from claude_agent_sdk import list_sessions, tag_session

# Tag the most recent session
sessions = list_sessions(directory="/path/to/project", limit=1)
if sessions:
    tag_session(sessions[0].session_id, "needs-review")

# Later: find all sessions with that tag
for session in list_sessions(directory="/path/to/project"):
    if session.tag == "needs-review":
        print(session.summary)

Классы

`ClaudeSDKClient`

Поддерживает сеанс разговора через несколько обменов. Это эквивалент Python того, как функция query() TypeScript SDK работает внутри - она создает объект клиента, который может продолжать разговоры. См. сравнение с query().

class ClaudeSDKClient:
    def __init__(self, options: ClaudeAgentOptions | None = None, transport: Transport | 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 set_permission_mode(self, mode: PermissionMode) -> None
    async def set_model(self, model: str | None = None) -> None
    async def rewind_files(self, user_message_id: str) -> None
    async def get_mcp_status(self) -> McpStatusResponse
    async def reconnect_mcp_server(self, server_name: str) -> None
    async def toggle_mcp_server(self, server_name: str, enabled: bool) -> None
    async def stop_task(self, task_id: str) -> None
    async def get_server_info(self) -> dict[str, Any] | None
    async def disconnect(self) -> None

Методы

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

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

import asyncio
from claude_agent_sdk import ClaudeSDKClient


async def main():
    async with ClaudeSDKClient() as client:
        await client.query("Hello Claude")
        async for message in client.receive_response():
            print(message)


asyncio.run(main())

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

Пример - Продолжение разговора

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


async def main():
    async with ClaudeSDKClient() as client:
        # First question
        await client.query("What's the capital of France?")

        # Process response
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Claude: {block.text}")

        # Follow-up question - the session retains the previous context
        await client.query("What's the population of that city?")

        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Claude: {block.text}")

        # Another follow-up - still in the same conversation
        await client.query("What are some famous landmarks there?")

        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Claude: {block.text}")


asyncio.run(main())

Пример - Потоковый ввод с ClaudeSDKClient

import asyncio
from claude_agent_sdk import ClaudeSDKClient


async def message_stream():
    """Generate messages dynamically."""
    yield {
        "type": "user",
        "message": {"role": "user", "content": "Analyze the following data:"},
    }
    await asyncio.sleep(0.5)
    yield {
        "type": "user",
        "message": {"role": "user", "content": "Temperature: 25°C, Humidity: 60%"},
    }
    await asyncio.sleep(0.5)
    yield {
        "type": "user",
        "message": {"role": "user", "content": "What patterns do you see?"},
    }


async def main():
    async with ClaudeSDKClient() as client:
        # Stream input to Claude
        await client.query(message_stream())

        # Process response
        async for message in client.receive_response():
            print(message)

        # Follow-up in same session
        await client.query("Should we be concerned about these readings?")

        async for message in client.receive_response():
            print(message)


asyncio.run(main())

Пример - Использование прерываний

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, ResultMessage


async def interruptible_task():
    options = ClaudeAgentOptions(allowed_tools=["Bash"], permission_mode="acceptEdits")

    async with ClaudeSDKClient(options=options) as client:
        # Start a long-running task
        await client.query("Count from 1 to 100 slowly, using the bash sleep command")

        # Let it run for a bit
        await asyncio.sleep(2)

        # Interrupt the task
        await client.interrupt()
        print("Task interrupted!")

        # Drain the interrupted task's messages (including its ResultMessage)
        async for message in client.receive_response():
            if isinstance(message, ResultMessage):
                print(f"Interrupted task: terminal_reason={message.terminal_reason!r}")
                # terminal_reason is "aborted_streaming" or "aborted_tools"
                # for interrupted turns

        # Send a new command
        await client.query("Just say hello instead")

        # Now receive the new response
        async for message in client.receive_response():
            if isinstance(message, ResultMessage) and message.subtype == "success":
                print(f"New result: {message.result}")


asyncio.run(interruptible_task())

Пример - Расширенное управление разрешениями

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from claude_agent_sdk.types import (
    PermissionResultAllow,
    PermissionResultDeny,
    ToolPermissionContext,
)


async def custom_permission_handler(
    tool_name: str, input_data: dict, context: ToolPermissionContext
) -> PermissionResultAllow | PermissionResultDeny:
    """Custom logic for tool permissions."""

    # Block writes to system directories
    if tool_name == "Write" and input_data.get("file_path", "").startswith("/system/"):
        return PermissionResultDeny(
            message="System directory write not allowed", interrupt=True
        )

    # Redirect sensitive file operations
    if tool_name in ["Write", "Edit"] and "config" in input_data.get("file_path", ""):
        safe_path = f"./sandbox/{input_data['file_path']}"
        return PermissionResultAllow(
            updated_input={**input_data, "file_path": safe_path}
        )

    # Allow everything else
    return PermissionResultAllow(updated_input=input_data)


async def main():
    # Don't also list the gated tools in allowed_tools: allow rules approve calls before can_use_tool runs
    options = ClaudeAgentOptions(can_use_tool=custom_permission_handler)

    async with ClaudeSDKClient(options=options) as client:
        await client.query("Update the system config file")

        async for message in client.receive_response():
            # Will use sandbox path instead
            print(message)


asyncio.run(main())

Типы

`SdkMcpTool`

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

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

`Transport`

Абстрактный базовый класс для пользовательских реализаций транспорта. Используйте это для связи с процессом Claude через пользовательский канал (например, удаленное соединение вместо локального подпроцесса).

from abc import ABC, abstractmethod
from collections.abc import AsyncIterator
from typing import Any


class Transport(ABC):
    @abstractmethod
    async def connect(self) -> None: ...

    @abstractmethod
    async def write(self, data: str) -> None: ...

    @abstractmethod
    def read_messages(self) -> AsyncIterator[dict[str, Any]]: ...

    @abstractmethod
    async def close(self) -> None: ...

    @abstractmethod
    def is_ready(self) -> bool: ...

    @abstractmethod
    async def end_input(self) -> None: ...

Импорт: from claude_agent_sdk import Transport

`ClaudeAgentOptions`

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

@dataclass
class ClaudeAgentOptions:
    tools: list[str] | ToolsPreset | None = None
    allowed_tools: list[str] = field(default_factory=list)
    system_prompt: str | SystemPromptPreset | SystemPromptCustom | SystemPromptFile | None = None
    mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)
    strict_mcp_config: bool = False
    permission_mode: PermissionMode | None = None
    continue_conversation: bool = False
    resume: str | None = None
    session_id: str | None = None
    max_turns: int | None = None
    max_budget_usd: float | None = None
    disallowed_tools: list[str] = field(default_factory=list)
    model: str | None = None
    fallback_model: str | None = None
    betas: list[SdkBeta] = field(default_factory=list)
    output_format: dict[str, Any] | None = None
    permission_prompt_tool_name: str | None = None
    cwd: str | Path | None = None
    cli_path: 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)
    max_buffer_size: int | None = None
    debug_stderr: Any = sys.stderr  # Deprecated
    stderr: Callable[[str], None] | None = None
    can_use_tool: CanUseTool | None = None
    hooks: dict[HookEvent, list[HookMatcher]] | None = None
    user: str | None = None
    include_partial_messages: bool = False
    include_hook_events: bool = False
    forward_subagent_text: bool = False
    fork_session: bool = False
    resume_session_at: str | None = None
    resume_drops_turn: str | None = None
    agents: dict[str, AgentDefinition] | None = None
    setting_sources: list[SettingSource] | None = None
    skills: list[str] | Literal["all"] | None = None
    sandbox: SandboxSettings | None = None
    plugins: list[SdkPluginConfig] = field(default_factory=list)
    max_thinking_tokens: int | None = None  # Deprecated: use thinking instead
    thinking: ThinkingConfig | None = None
    effort: EffortLevel | None = None
    enable_file_checkpointing: bool = False
    session_store: SessionStore | None = None
    session_store_flush: SessionStoreFlushMode = "batched"
    load_timeout_ms: int = 60_000
    task_budget: TaskBudget | None = None

Обработка медленных или зависших ответов API

Подпроцесс CLI читает несколько переменных окружения, которые управляют тайм-аутами API и обнаружением зависания. Передайте их через ClaudeAgentOptions.env:

from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(
    env={
        "API_TIMEOUT_MS": "120000",
        "CLAUDE_CODE_MAX_RETRIES": "2",
        "CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS": "120000",
    },
)

• API_TIMEOUT_MS: тайм-аут для каждого запроса на клиенте Anthropic в миллисекундах. По умолчанию 600000. Применяется к основному циклу и всем subagents.

• CLAUDE_CODE_MAX_RETRIES: максимальное количество повторных попыток API. По умолчанию 10, ограничено 15. Каждая повторная попытка получает свое собственное окно API_TIMEOUT_MS, поэтому наихудшее время стены примерно API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1) плюс отступ. Для автоматических запусков, которым нужно ждать через более длительные сбои, установите CLAUDE_CODE_RETRY_WATCHDOG=1: он повторяет ошибки емкости бесконечно и, на Claude Code v2.1.199 или позже, повышает значение по умолчанию для других переходных ошибок до 300 и удаляет ограничение на эту переменную.

• CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS: сторожевой таймер зависания для subagents. Пока сторожевой таймер потока включен, значение по умолчанию составляет CLAUDE_STREAM_IDLE_TIMEOUT_MS плюс 5 минут, что составляет 600000, если вы не повысите эту переменную. Со сторожевым таймером потока выключенным, значение по умолчанию составляет 600000. До v2.1.257 значение по умолчанию всегда было 600000.

  Таймер сбрасывается при каждом событии потока. При зависании Claude Code прерывает subagent и сообщает о зависании родителю. Для фонового subagent он также отмечает задачу как неудачную и прикрепляет любой частичный результат.

• CLAUDE_ENABLE_STREAM_WATCHDOG с CLAUDE_STREAM_IDLE_TIMEOUT_MS: сторожевой таймер потока, который прерывает запрос, когда заголовки прибыли, но тело ответа перестает потоковать. Сторожевой таймер включен по умолчанию для всех поставщиков; установите CLAUDE_ENABLE_STREAM_WATCHDOG=0 для отключения. CLAUDE_STREAM_IDLE_TIMEOUT_MS по умолчанию 300000 и зажимается до этого минимума. После прерывания, Automatic retries охватывает то, что Claude Code делает, на основе того, как далеко прошел ответ.

  Пока сторожевой таймер ждет ответа, который шлюз позади ANTHROPIC_BASE_URL держит открытым с помощью ping-пингов keep-alive, хост, который устанавливает include_partial_messages, продолжает получать ping StreamEvent сообщения. Читайте эти кадры как живость, а не тайм-аут сеанса на молчание. До v2.1.257 кадры останавливались через 5 минут после последнего реального события потока.

`OutputFormat`

Конфигурация для валидации структурированного вывода. Передайте это как dict в поле output_format на ClaudeAgentOptions:

# Expected dict shape for output_format
{
    "type": "json_schema",
    "schema": {...},  # Your JSON Schema definition
}

`SystemPromptPreset`

Конфигурация для использования предустановленной системной подсказки Claude Code с дополнительными добавлениями.

class SystemPromptPreset(TypedDict):
    type: Literal["preset"]
    preset: Literal["claude_code"]
    append: NotRequired[str]
    exclude_dynamic_sections: NotRequired[bool]
    snapshot: NotRequired[bool]

`SystemPromptCustom`

Пользовательская системная подсказка в форме объекта, эквивалентная передаче строки как system_prompt, которая также может установить snapshot. Требует claude-agent-sdk v0.2.153 или позже.

class SystemPromptCustom(TypedDict):
    type: Literal["custom"]
    prompt: str
    snapshot: NotRequired[bool]

`SystemPromptFile`

Конфигурация для загрузки пользовательской системной подсказки из файла вместо передачи ее в виде строки. SDK сопоставляет это с флагом CLI --system-prompt-file. Используйте форму файла, когда подсказка большая: SDK передает строку system_prompt в argv подпроцесса CLI, что подвергается ограничениям длины командной строки ОС перед отправкой SDK любого запроса API. На Linux один аргумент длиннее примерно 128 КБ не работает при порождении процесса с Argument list too long. На Windows вся командная строка ограничена примерно 32 КБ, поэтому форма строки не работает при более низком пороге.

class SystemPromptFile(TypedDict):
    type: Literal["file"]
    path: str

`SettingSource`

Управляет тем, какие источники конфигурации на основе файловой системы загружает SDK.

SettingSource = Literal["user", "project", "local"]

Поведение по умолчанию

Когда setting_sources опущено или None и skills не установлен, query() загружает те же параметры файловой системы, что и Claude Code CLI: пользовательские, проектные и локальные. С skills установленным, строка setting_sources описывает текущее значение по умолчанию. Управляемые параметры политики загружаются во всех случаях; параметры, управляемые сервером, загружаются, когда сеанс аутентифицируется с учетными данными организации на подходящей конфигурации. Для получения дополнительной информации см. What settingSources does not control.

Почему использовать setting\_sources

Отключить параметры файловой системы:

# Do not load user, project, or local settings from disk
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Analyze this code",
        options=ClaudeAgentOptions(
            setting_sources=[]
        ),
    ):
        print(message)


asyncio.run(main())

Загрузить только определенные источники параметров:

# Load only project settings, ignore user and local
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Run CI checks",
        options=ClaudeAgentOptions(
            setting_sources=["project"]  # Only .claude/settings.json
        ),
    ):
        print(message)


asyncio.run(main())

Приложения только SDK:

# Define everything programmatically.
# Pass [] to opt out of filesystem setting sources.
import asyncio
from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions, query


async def main():
    async for message in query(
        prompt="Review this PR",
        options=ClaudeAgentOptions(
            setting_sources=[],
            agents={
                "code-reviewer": AgentDefinition(
                    description="Reviews code changes",
                    prompt="You are a code reviewer. Report issues in the diff.",
                ),
            },
            allowed_tools=["Read", "Grep", "Glob"],
        ),
    ):
        print(message)


asyncio.run(main())

Для загрузки инструкций проекта CLAUDE.md включите "project" в setting_sources. См. Modify system prompts для того, как загрузка CLAUDE.md взаимодействует с опциями системной подсказки.

Приоритет параметров

Когда загружаются несколько источников, параметры объединяются с этим приоритетом (от наивысшего к наименьшему):

1. Локальные параметры (.claude/settings.local.json)
2. Параметры проекта (.claude/settings.json)
3. Параметры пользователя (~/.claude/settings.json)

Программные опции, такие как agents, allowed_tools и settings, переопределяют параметры пользователя, проекта и локальной файловой системы. Управляемые параметры политики имеют приоритет над программными опциями.

`AgentDefinition`

Конфигурация для subagent, определенного программно.

@dataclass
class AgentDefinition:
    description: str
    prompt: str
    tools: list[str] | None = None
    disallowedTools: list[str] | None = None
    model: str | None = None
    skills: list[str] | None = None
    memory: Literal["user", "project", "local"] | None = None
    mcpServers: list[str | dict[str, Any]] | None = None
    initialPrompt: str | None = None
    maxTurns: int | None = None
    background: bool | None = None
    effort: EffortLevel | int | None = None
    permissionMode: PermissionMode | None = None

`PermissionMode`

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

PermissionMode = Literal[
    "default",  # Standard permission behavior
    "acceptEdits",  # Auto-accept file edits
    "plan",  # Planning mode - explore without editing
    "dontAsk",  # Deny anything not pre-approved instead of prompting
    "bypassPermissions",  # Bypass permission checks; explicit ask rules still prompt (use with caution)
    "auto",  # Model classifier approves or denies permission prompts
]

`EffortLevel`

Уровни усилий для руководства глубиной мышления.

EffortLevel = Literal[
    "low",  # Minimal thinking, fastest responses
    "medium",  # Moderate thinking
    "high",  # Deep reasoning
    "xhigh",  # Extended reasoning; falls back to "high" on models that don't support it
    "max",  # Maximum effort
]

`CanUseTool`

Псевдоним типа для функций обратного вызова разрешения инструмента.

CanUseTool = Callable[
    [str, dict[str, Any], ToolPermissionContext], Awaitable[PermissionResult]
]

Обратный вызов получает:

• tool_name: Имя вызываемого инструмента
• input_data: Входные параметры инструмента
• context: ToolPermissionContext с дополнительной информацией

Возвращает PermissionResult (либо PermissionResultAllow, либо PermissionResultDeny).

Обратный вызов - это замена SDK для интерактивной подсказки разрешения: он вызывается только когда permission evaluation flow разрешается в подсказку. Вызовы инструментов, уже одобренные записью allowed_tools, правилом параметров разрешения или режимом разрешения, таким как acceptEdits или bypassPermissions, никогда его не вызывают. Правило разрешения не предварительно одобряет действия, которые ни один режим не одобряет автоматически; см. How permissions are evaluated для того, какие из них достигают обратного вызова и что происходит в режиме dontAsk и auto. Чтобы контролировать каждый вызов инструмента, используйте вместо этого hook PreToolUse.

`ToolPermissionContext`

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

@dataclass
class ToolPermissionContext:
    signal: Any | None = None  # Future: abort signal support
    suggestions: list[PermissionUpdate] = field(default_factory=list)
    tool_use_id: str | None = None
    agent_id: str | None = None
    blocked_path: str | None = None
    decision_reason: str | None = None
    title: str | None = None
    display_name: str | None = None
    description: str | None = None

`PermissionResult`

Тип объединения для результатов обратного вызова разрешения.

PermissionResult = PermissionResultAllow | PermissionResultDeny

`PermissionResultAllow`

Результат, указывающий, что вызов инструмента должен быть разрешен.

@dataclass
class PermissionResultAllow:
    behavior: Literal["allow"] = "allow"
    updated_input: dict[str, Any] | None = None
    updated_permissions: list[PermissionUpdate] | None = None

`PermissionResultDeny`

Результат, указывающий, что вызов инструмента должен быть отклонен.

@dataclass
class PermissionResultDeny:
    behavior: Literal["deny"] = "deny"
    message: str = ""
    interrupt: bool = False

`PermissionUpdate`

Конфигурация для программного обновления разрешений.

@dataclass
class PermissionUpdate:
    type: Literal[
        "addRules",
        "replaceRules",
        "removeRules",
        "setMode",
        "addDirectories",
        "removeDirectories",
    ]
    rules: list[PermissionRuleValue] | None = None
    behavior: Literal["allow", "deny", "ask"] | None = None
    mode: PermissionMode | None = None
    directories: list[str] | None = None
    destination: (
        Literal["userSettings", "projectSettings", "localSettings", "session"] | None
    ) = None

`PermissionRuleValue`

Правило для добавления, замены или удаления в обновлении разрешений.

@dataclass
class PermissionRuleValue:
    tool_name: str
    rule_content: str | None = None

`ToolsPreset`

Конфигурация предустановленных инструментов для использования набора инструментов Claude Code по умолчанию.

class ToolsPreset(TypedDict):
    type: Literal["preset"]
    preset: Literal["claude_code"]

`ThinkingConfig`

Управляет поведением расширенного мышления. Объединение трех конфигураций:

ThinkingDisplay = Literal["summarized", "omitted"]


class ThinkingConfigAdaptive(TypedDict):
    type: Literal["adaptive"]
    display: NotRequired[ThinkingDisplay]


class ThinkingConfigEnabled(TypedDict):
    type: Literal["enabled"]
    budget_tokens: int
    display: NotRequired[ThinkingDisplay]


class ThinkingConfigDisabled(TypedDict):
    type: Literal["disabled"]


ThinkingConfig = ThinkingConfigAdaptive | ThinkingConfigEnabled | ThinkingConfigDisabled

Дополнительное поле display управляет тем, возвращается ли текст мышления "summarized" или "omitted". На Claude Opus 4.7 и более поздних версиях API по умолчанию используется "omitted", поэтому установите "summarized" для получения содержимого мышления в выводах ThinkingBlock. Claude Code не отправляет display на Amazon Bedrock или Google Cloud's Agent Platform, поэтому на этих поставщиках Opus 4.7 и позже возвращают пустые выводы ThinkingBlock даже когда вы устанавливаете display на "summarized".

Поскольку это классы TypedDict, они являются простыми словарями во время выполнения. Либо создавайте их как литералы словарей, либо вызывайте класс как конструктор; оба создают dict. Получайте доступ к полям с помощью config["budget_tokens"], а не config.budget_tokens:

from claude_agent_sdk import ClaudeAgentOptions, ThinkingConfigEnabled

# Option 1: dict literal (recommended, no import needed)
options = ClaudeAgentOptions(thinking={"type": "enabled", "budget_tokens": 20000})

# Option 2: constructor-style (returns a plain dict)
config = ThinkingConfigEnabled(type="enabled", budget_tokens=20000)
print(config["budget_tokens"])  # 20000
# config.budget_tokens would raise AttributeError

`TaskBudget`

Бюджет задач на стороне API в токенах, используется с полем task_budget в ClaudeAgentOptions.

class TaskBudget(TypedDict):
    total: int

Поскольку это TypedDict, передайте его как простой dict, такой как ClaudeAgentOptions(task_budget={"total": 50000}).

`SdkBeta`

Тип Literal для функций бета-версии SDK.

SdkBeta = Literal["context-1m-2025-08-07"]

Используйте с полем betas в ClaudeAgentOptions для включения функций бета-версии.

`McpSdkServerConfig`

Конфигурация для SDK MCP servers, созданных с помощью create_sdk_mcp_server().

class McpSdkServerConfig(TypedDict):
    type: Literal["sdk"]
    name: str
    instance: Any  # MCP Server instance

`McpServerConfig`

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

McpServerConfig = (
    McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig
)

`McpStdioServerConfig`

class McpStdioServerConfig(TypedDict):
    type: NotRequired[Literal["stdio"]]  # Optional for backwards compatibility
    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]]

`McpServerStatusConfig`

Конфигурация MCP server, как сообщается get_mcp_status(). Это объединение всех вариантов транспорта McpServerConfig плюс вариант claudeai-proxy только для вывода для servers, проксированных через claude.ai.

McpServerStatusConfig = (
    McpStdioServerConfig
    | McpSSEServerConfig
    | McpHttpServerConfig
    | McpSdkServerConfigStatus
    | McpClaudeAIProxyServerConfig
)

McpSdkServerConfigStatus - это сериализуемая форма McpSdkServerConfig с только полями type ("sdk") и name (str); встроенный instance опущен. McpClaudeAIProxyServerConfig имеет поля type ("claudeai-proxy"), url (str) и id (str).

`McpStatusResponse`

Ответ от ClaudeSDKClient.get_mcp_status(). Оборачивает список статусов сервера под ключом mcpServers.

class McpStatusResponse(TypedDict):
    mcpServers: list[McpServerStatus]

`McpServerStatus`

Статус подключенного MCP server, содержащийся в McpStatusResponse.

class McpServerStatus(TypedDict):
    name: str
    status: McpServerConnectionStatus  # "connected" | "failed" | "needs-auth" | "pending" | "disabled"
    serverInfo: NotRequired[McpServerInfo]
    error: NotRequired[str]
    config: NotRequired[McpServerStatusConfig]
    scope: NotRequired[str]
    tools: NotRequired[list[McpToolInfo]]

`SdkPluginConfig`

Конфигурация для загрузки plugins в SDK.

class SdkPluginConfig(TypedDict):
    type: Literal["local"]
    path: str

Пример:

plugins = [
    {"type": "local", "path": "./my-plugin"},
    {"type": "local", "path": "/absolute/path/to/plugin"},
]

Для полной информации о создании и использовании plugins см. Plugins.

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

`Message`

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

Message = (
    UserMessage
    | AssistantMessage
    | SystemMessage
    | ResultMessage
    | StreamEvent
    | RateLimitEvent
    | ConversationResetMessage
)

`UserMessage`

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

@dataclass
class UserMessage:
    content: str | list[ContentBlock]
    uuid: str | None = None
    parent_tool_use_id: str | None = None
    tool_use_result: dict[str, Any] | None = None
    origin: MessageOrigin | None = None

SDK передает tool_use_result из CLI без изменений. Для инструмента на внешнем MCP сервере, результат которого содержит блоки resource_link, словарь имеет ключ resourceLinks, содержащий список словарей с ключами типа TypeScript SDKMcpResourceLink. Claude получает каждую ссылку как строку текста в результате инструмента. Для отображения файлов, возвращенных сервером, читайте resourceLinks вместо анализа этого текста. Ключ resourceLinks требует Python Agent SDK 0.2.150 или позже и Claude Code v2.1.257 или позже; CLI, поставляемый с этой версией SDK, удовлетворяет требованию Claude Code.

CLI опускает ключ, когда результат не содержит ссылок и при результатах от подагентов. CLI сохраняет максимум 50 ссылок на результат и прекращает добавление ссылок, когда список достигает 64 КиБ сериализованного JSON. Инструмент, который вы определяете внутри процесса с помощью tool(), никогда не создает ключ, потому что SDK преобразует его блоки resource_link в текст перед тем, как CLI увидит результат.

`AssistantMessage`

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

@dataclass
class AssistantMessage:
    content: list[ContentBlock]
    model: str
    parent_tool_use_id: str | None = None
    error: AssistantMessageError | None = None
    usage: dict[str, Any] | None = None
    message_id: str | None = None
    stop_reason: str | None = None
    session_id: str | None = None
    uuid: str | None = None

`AssistantMessageError`

Возможные типы ошибок для сообщений помощника.

AssistantMessageError = Literal[
    "authentication_failed",
    "billing_error",
    "rate_limit",
    "invalid_request",
    "server_error",
    "unknown",
]

Базовый процесс CLI может выдавать типы ошибок, которые этот Literal не перечисляет, такие как max_output_tokens. SDK передает значение без изменений, поэтому обрабатывайте строки вне этого списка так же, как вы обрабатываете unknown. Тип TypeScript SDKAssistantMessageError перечисляет полный набор значений, которые может выдать CLI.

`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
    stop_reason: str | None = None
    total_cost_usd: float | None = None
    usage: dict[str, Any] | None = None
    result: str | None = None
    structured_output: Any = None
    model_usage: dict[str, ModelUsage] | None = None
    permission_denials: list[Any] | None = None
    deferred_tool_use: DeferredToolUse | None = None
    errors: list[str] | None = None
    api_error_status: int | None = None
    uuid: str | None = None
    terminal_reason: str | None = None
    origin: MessageOrigin | None = None

Поле subtype определяет, какие другие поля заполнены. Это одно из "success", "error_during_execution", "error_max_turns", "error_max_budget_usd" или "error_max_structured_output_retries". Dataclass Python объединяет все варианты в одну форму, поэтому поля, которые не применяются к возвращаемому подтипу, имеют значение None.

Несколько полей содержат диагностические детали о том, как разговор закончился:

• is_error: True, когда разговор закончился в состоянии ошибки. Всегда True на подтипах error_*. На subtype="success" это True, когда финальный запрос модели не удался, что означает, что цикл агента завершился, но последний вызов API вернул ошибку.
• api_error_status: код состояния HTTP завершающей ошибки API. None, когда ход закончился без ошибки. Заполняется только на subtype="success".
• result: текст финального сообщения помощника на subtype="success" или None на подтипах error_*. Когда subtype="success" и is_error=True, это содержит строку ошибки API, если она доступна, но может быть пустой, поэтому проверьте api_error_status и предыдущее содержимое AssistantMessage для деталей.
• errors: строки ошибок уровня цикла, такие как сообщение о максимальных ходах. Заполняется только на подтипах error_*.
• terminal_reason: почему цикл запроса закончился, например "completed", "max_turns", "api_error", "aborted_streaming" или "aborted_tools". Значение "aborted_streaming" или "aborted_tools" означает, что ход был прерван до завершения. Частые причины - interrupt() и callback разрешения, возвращающий PermissionResultDeny с interrupt=True. None на версиях CLI, которые предшествуют полю, на результатах локальных команд, таких как /voice или /usage, которые обходят цикл запроса, или на синтезированных результатах ошибок, выданных при критическом отказе сеанса. Зеркалирует SDKResultMessage.terminal_reason TypeScript SDK, который перечисляет полный набор значений.
• origin: происхождение пользовательского сообщения, которое запустило этот ход. В режиме потоковой передачи входных данных проверьте это, чтобы отличить результат вашего собственного запроса, где origin равен None или {"kind": "human"}, от результата внедренного хода, такого как уведомление фоновой задачи. Требуется Python Agent SDK 0.2.137 или позже.

Словарь usage охватывает только основной цикл агента и исключает подагентов и другие вложенные или вспомогательные вызовы модели. В режиме потоковой передачи входных данных значения указаны за ход. Предпочитайте model_usage для учета токенов и стоимости. Словарь usage содержит следующие ключи, если они присутствуют:

Словарь model_usage отображает имена моделей на использование для каждой модели. Он охватывает каждый вызов модели, сделанный через конвейер запроса: основной цикл, подагентов и внутренние вызовы, такие как компактирование и агентов Workflow. Вспомогательные вызовы вне этого конвейера, такие как классификатор разрешений и запросы подсчета токенов, исключены из model_usage. Рассматривайте model_usage как оценку, а не как выписку по счету.

В режиме потоковой передачи входных данных model_usage и total_cost_usd являются кумулятивными по ходам, поэтому читайте последний результат вместо суммирования по результатам. Вызов, который возобновляет сеанс, также учитывает итоги, восстановленные из более ранних вызовов сеанса. См. Track costs in streaming input mode для сбросов и Recover totals after a session crash для обнуленных результатов.

Каждое значение в model_usage - это TypedDict ModelUsage, импортируемый через from claude_agent_sdk.types import ModelUsage. Его ключи используют camelCase, потому что SDK передает значение без изменений из базового процесса CLI, соответствуя типу TypeScript ModelUsage:

`StreamEvent`

Событие потока для частичных обновлений сообщений во время потоковой передачи. Получается только когда include_partial_messages=True в ClaudeAgentOptions. Импортируйте через from claude_agent_sdk.types import StreamEvent.

@dataclass
class StreamEvent:
    uuid: str
    session_id: str
    event: dict[str, Any]  # The raw Claude API stream event
    parent_tool_use_id: str | None = None

`RateLimitEvent`

Выдается при изменении статуса ограничения скорости (например, с "allowed" на "allowed_warning"). Используйте это для предупреждения пользователей перед достижением жесткого лимита или для отката, когда статус "rejected".

@dataclass
class RateLimitEvent:
    rate_limit_info: RateLimitInfo
    uuid: str
    session_id: str

`RateLimitInfo`

Состояние ограничения скорости, переносимое RateLimitEvent.

RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]
RateLimitType = Literal[
    "five_hour", "seven_day", "seven_day_opus", "seven_day_sonnet", "overage"
]


@dataclass
class RateLimitInfo:
    status: RateLimitStatus
    resets_at: int | None = None
    rate_limit_type: RateLimitType | None = None
    utilization: float | None = None
    overage_status: RateLimitStatus | None = None
    overage_resets_at: int | None = None
    overage_disabled_reason: str | None = None
    raw: dict[str, Any] = field(default_factory=dict)

`ConversationResetMessage`

Выдается при замене разговора без завершения соединения, например после /clear. См. Track costs in streaming input mode для того, как сброс влияет на текущие итоги на последующих объектах ResultMessage. Требуется Python Agent SDK 0.2.137 или позже.

@dataclass
class ConversationResetMessage:
    new_conversation_id: str
    uuid: str
    session_id: str

`TaskStartedMessage`

Выдается при запуске фоновой задачи. Фоновая задача - это все, что отслеживается вне основного хода: фоновая команда Bash, наблюдение Monitor, подагент, порожденный через инструмент Agent, или удаленный агент. Поле task_type говорит вам, какой. Это именование не связано с переименованием инструмента Task на Agent.

@dataclass
class TaskStartedMessage(SystemMessage):
    task_id: str
    description: str
    uuid: str
    session_id: str
    tool_use_id: str | None = None
    task_type: str | None = None

`TaskUsage`

Данные токенов и времени для фоновой задачи.

class TaskUsage(TypedDict):
    total_tokens: int
    tool_uses: int
    duration_ms: int

`TaskProgressMessage`

Выдается периодически с обновлениями прогресса для выполняющейся фоновой задачи.

@dataclass
class TaskProgressMessage(SystemMessage):
    task_id: str
    description: str
    usage: TaskUsage
    uuid: str
    session_id: str
    tool_use_id: str | None = None
    last_tool_name: str | None = None

`TaskNotificationMessage`

Выдается при завершении, сбое или остановке фоновой задачи. Фоновые задачи включают команды Bash run_in_background, наблюдения Monitor и фоновые подагенты.

@dataclass
class TaskNotificationMessage(SystemMessage):
    task_id: str
    status: TaskNotificationStatus  # "completed" | "failed" | "stopped"
    output_file: str
    summary: str
    uuid: str
    session_id: str
    tool_use_id: str | None = None
    usage: TaskUsage | None = None

Когда CLI перемещает длительный вызов инструмента MCP в фон, результат инструмента для этого вызова содержит только заполнитель, и реальный результат вызова поступает в это сообщение. При уведомлении "completed" для такого вызова CLI добавляет ключ resource_links, перечисляющий файлы, возвращенные инструментом по ссылке, с теми же записями и ограничениями, что и ключ resourceLinks на UserMessage.tool_use_result. Ключ resource_links требует Python Agent SDK 0.2.150 или позже и Claude Code v2.1.257 или позже; CLI, поставляемый с этой версией SDK, удовлетворяет требованию Claude Code.

Dataclass не имеет поля для resource_links. Читайте его из словаря data, который сообщение наследует от SystemMessage: message.data.get("resource_links"). Сопоставьте уведомление с вызовом, используя tool_use_id. CLI опускает ключ, когда результат не содержал ссылок и при уведомлениях для задач, которые не являются вызовами инструментов MCP.

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

`ContentBlock`

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

ContentBlock = (
    TextBlock
    | ThinkingBlock
    | ToolUseBlock
    | ToolResultBlock
    | ServerToolUseBlock
    | ServerToolResultBlock
)

`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

Типы ошибок

Типы ниже определяют, что ваш код перехватывает. Для записей, привязанных к сообщениям об ошибках, которые эти типы вызывают, с причиной и исправлением для каждого, см. Troubleshooting.

`ClaudeSDKError`

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

class ClaudeSDKError(Exception):
    """Base error for Claude SDK."""

Когда одноразовый query() заканчивается результатом ошибки, например ошибкой превышения лимита ходов, SDK вызывает ResultError после выдачи финального сообщения результата. Версии Python Agent SDK до 0.2.140 вызывали простое Exception, которое не было подклассом ClaudeSDKError.

`CLINotFoundError`

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

class CLINotFoundError(CLIConnectionError):
    def __init__(
        self, message: str = "Claude Code not found", cli_path: str | None = None
    ):
        """
        Args:
            message: Error message (default: "Claude Code not found")
            cli_path: Optional path to the CLI that was not found
        """

`CLIConnectionError`

Вызывается, когда соединение с Claude Code не удается.

class CLIConnectionError(ClaudeSDKError):
    """Failed to connect to 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

`ResultError`

Вызывается после финального ResultMessage, когда процесс Claude Code завершается, потому что запуск закончился результатом ошибки, таким как ошибка превышения лимита ходов или ошибка API. ResultError является подклассом ProcessError, поэтому существующий обработчик except ProcessError также его перехватывает. Его атрибуты содержат поля этого сообщения результата, поэтому вы можете разветвляться в зависимости от причины сбоя запуска без анализа текста сообщения. Требуется Python Agent SDK версии 0.2.140 или позже.

class ResultError(ProcessError):
    subtype: str | None  # "error_max_turns", "error_during_execution", ...; "success" when the run ended on a failed request
    errors: list[str]  # an empty list when the result message reported none
    result: str | None
    api_error_status: int | None
    terminal_reason: str | None  # "max_turns", "api_error", ...; check this before subtype
    session_id: str | None
    data: dict[str, Any]  # the raw result message payload

Чтобы различить сбои, проверьте terminal_reason перед subtype. Когда финальный запрос не удается, например при ошибке API, Claude Code сообщает subtype "success" с причиной в terminal_reason, например "api_error"; когда лимит, который вы установили, завершает запуск, такой как max_turns или max_budget_usd, он сообщает подтип error_*.

`CLIJSONDecodeError`

Вызывается, когда разбор JSON не удается.

class CLIJSONDecodeError(ClaudeSDKError):
    def __init__(self, line: str, original_error: Exception):
        """
        Args:
            line: The line that failed to parse
            original_error: The original JSON decode exception
        """
        self.line = line
        self.original_error = original_error

Типы hooks

Для полного руководства по использованию hooks с примерами и общими шаблонами см. Hooks guide.

`HookEvent`

Поддерживаемые типы событий hooks.

HookEvent = Literal[
    "PreToolUse",  # Called before tool execution
    "PostToolUse",  # Called after tool execution
    "PostToolUseFailure",  # Called when a tool execution fails
    "UserPromptSubmit",  # Called when user submits a prompt
    "Stop",  # Called when stopping execution
    "SubagentStop",  # Called when a subagent stops
    "PreCompact",  # Called before message compaction
    "Notification",  # Called for notification events
    "SubagentStart",  # Called when a subagent starts
    "PermissionRequest",  # Called when a permission decision is needed
]

`HookCallback`

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

HookCallback = Callable[[HookInput, str | None, HookContext], Awaitable[HookJSONOutput]]

Параметры:

• input: Строго типизированный ввод hooks с дискриминированными объединениями на основе hook_event_name (см. HookInput)
• tool_use_id: Дополнительный идентификатор использования инструмента (для hooks, связанных с инструментами)
• context: Контекст hooks с дополнительной информацией

Возвращает HookJSONOutput.

`HookContext`

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

class HookContext(TypedDict):
    signal: Any | None  # Future: abort signal support

`HookMatcher`

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

@dataclass
class HookMatcher:
    matcher: str | None = (
        None  # Tool name or pattern to match (e.g., "Bash", "Write|Edit")
    )
    hooks: list[HookCallback] = field(
        default_factory=list
    )  # List of callbacks to execute
    timeout: float | None = (
        None  # Timeout in seconds. When omitted, the per-event default applies:
        # 600 for most events, 30 for UserPromptSubmit
    )

`HookInput`

Тип объединения всех типов ввода hooks. Фактический тип зависит от поля hook_event_name.

HookInput = (
    PreToolUseHookInput
    | PostToolUseHookInput
    | PostToolUseFailureHookInput
    | UserPromptSubmitHookInput
    | StopHookInput
    | SubagentStopHookInput
    | PreCompactHookInput
    | NotificationHookInput
    | SubagentStartHookInput
    | PermissionRequestHookInput
)

`BaseHookInput`

Базовые поля, присутствующие во всех типах ввода hooks.

class BaseHookInput(TypedDict):
    session_id: str
    transcript_path: str
    cwd: str
    permission_mode: NotRequired[str]

`PreToolUseHookInput`

Входные данные для событий hooks PreToolUse.

class PreToolUseHookInput(BaseHookInput):
    hook_event_name: Literal["PreToolUse"]
    tool_name: str
    tool_input: dict[str, Any]
    tool_use_id: str
    agent_id: NotRequired[str]
    agent_type: NotRequired[str]

`PostToolUseHookInput`

Входные данные для событий hooks PostToolUse.

class PostToolUseHookInput(BaseHookInput):
    hook_event_name: Literal["PostToolUse"]
    tool_name: str
    tool_input: dict[str, Any]
    tool_response: Any
    tool_use_id: str
    agent_id: NotRequired[str]
    agent_type: NotRequired[str]

`PostToolUseFailureHookInput`

Входные данные для событий hooks PostToolUseFailure. Вызывается, когда выполнение инструмента не удается.

class PostToolUseFailureHookInput(BaseHookInput):
    hook_event_name: Literal["PostToolUseFailure"]
    tool_name: str
    tool_input: dict[str, Any]
    tool_use_id: str
    error: str
    is_interrupt: NotRequired[bool]
    agent_id: NotRequired[str]
    agent_type: NotRequired[str]

`UserPromptSubmitHookInput`

Входные данные для событий hooks UserPromptSubmit.

class UserPromptSubmitHookInput(BaseHookInput):
    hook_event_name: Literal["UserPromptSubmit"]
    prompt: str

`StopHookInput`

Входные данные для событий hooks Stop.

class StopHookInput(BaseHookInput):
    hook_event_name: Literal["Stop"]
    stop_hook_active: bool

`SubagentStopHookInput`

Входные данные для событий hooks SubagentStop.

class SubagentStopHookInput(BaseHookInput):
    hook_event_name: Literal["SubagentStop"]
    stop_hook_active: bool
    agent_id: str
    agent_transcript_path: str
    agent_type: str

`PreCompactHookInput`

Входные данные для событий hooks PreCompact.

class PreCompactHookInput(BaseHookInput):
    hook_event_name: Literal["PreCompact"]
    trigger: Literal["manual", "auto"]
    custom_instructions: str | None

`NotificationHookInput`

Входные данные для событий hooks Notification.

class NotificationHookInput(BaseHookInput):
    hook_event_name: Literal["Notification"]
    message: str
    title: NotRequired[str]
    notification_type: str

`SubagentStartHookInput`

Входные данные для событий hooks SubagentStart.

class SubagentStartHookInput(BaseHookInput):
    hook_event_name: Literal["SubagentStart"]
    agent_id: str
    agent_type: str

`PermissionRequestHookInput`

Входные данные для событий hooks PermissionRequest. Позволяет hooks программно обрабатывать решения разрешений.

class PermissionRequestHookInput(BaseHookInput):
    hook_event_name: Literal["PermissionRequest"]
    tool_name: str
    tool_input: dict[str, Any]
    permission_suggestions: NotRequired[list[Any]]
    agent_id: NotRequired[str]
    agent_type: NotRequired[str]

`HookJSONOutput`

Тип объединения для возвращаемых значений обратного вызова hooks.

HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput

`SyncHookJSONOutput`

Синхронный вывод hooks с полями управления и решения.

class SyncHookJSONOutput(TypedDict):
    # Control fields
    continue_: NotRequired[bool]  # Whether to proceed (default: True)
    suppressOutput: NotRequired[bool]  # Hide stdout from transcript
    stopReason: NotRequired[str]  # Message when continue is False

    # Decision fields
    decision: NotRequired[Literal["block"]]
    systemMessage: NotRequired[str]  # Warning message for user
    reason: NotRequired[str]  # Feedback for Claude

    # Hook-specific output
    hookSpecificOutput: NotRequired[HookSpecificOutput]

`HookSpecificOutput`

Дискриминированное объединение типов вывода, специфичных для события. Поле hookEventName определяет, какие поля действительны. Для полных деталей доступных полей для каждого события hooks см. Control execution with hooks.

class PreToolUseHookSpecificOutput(TypedDict):
    hookEventName: Literal["PreToolUse"]
    permissionDecision: NotRequired[Literal["allow", "deny", "ask", "defer"]]
    permissionDecisionReason: NotRequired[str]
    updatedInput: NotRequired[dict[str, Any]]
    additionalContext: NotRequired[str]


class PostToolUseHookSpecificOutput(TypedDict):
    hookEventName: Literal["PostToolUse"]
    additionalContext: NotRequired[str]
    updatedToolOutput: NotRequired[Any]
    updatedMCPToolOutput: NotRequired[Any]  # Deprecated: use updatedToolOutput, which works for all tools


class PostToolUseFailureHookSpecificOutput(TypedDict):
    hookEventName: Literal["PostToolUseFailure"]
    additionalContext: NotRequired[str]


class UserPromptSubmitHookSpecificOutput(TypedDict):
    hookEventName: Literal["UserPromptSubmit"]
    additionalContext: NotRequired[str]


class NotificationHookSpecificOutput(TypedDict):
    hookEventName: Literal["Notification"]
    additionalContext: NotRequired[str]


class SubagentStartHookSpecificOutput(TypedDict):
    hookEventName: Literal["SubagentStart"]
    additionalContext: NotRequired[str]


class PermissionRequestHookSpecificOutput(TypedDict):
    hookEventName: Literal["PermissionRequest"]
    decision: dict[str, Any]


HookSpecificOutput = (
    PreToolUseHookSpecificOutput
    | PostToolUseHookSpecificOutput
    | PostToolUseFailureHookSpecificOutput
    | UserPromptSubmitHookSpecificOutput
    | NotificationHookSpecificOutput
    | SubagentStartHookSpecificOutput
    | PermissionRequestHookSpecificOutput
)

`AsyncHookJSONOutput`

Асинхронный вывод hooks, который откладывает выполнение hooks.

class AsyncHookJSONOutput(TypedDict):
    async_: Literal[True]  # Set to True to defer execution
    asyncTimeout: NotRequired[int]  # Timeout in milliseconds

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

Этот пример регистрирует два hooks: один, который блокирует опасные команды bash, такие как rm -rf /, и другой, который регистрирует все использование инструментов для аудита. Hooks безопасности работает только на командах Bash (через matcher), в то время как hooks логирования работает на всех инструментах.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, 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]:
    """Validate and potentially block dangerous bash commands."""
    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": "Dangerous command blocked",
                }
            }
    return {}


async def log_tool_use(
    input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
) -> dict[str, Any]:
    """Log all tool usage for auditing."""
    print(f"Tool used: {input_data.get('tool_name')}")
    return {}


options = ClaudeAgentOptions(
    hooks={
        "PreToolUse": [
            HookMatcher(
                matcher="Bash", hooks=[validate_bash_command], timeout=120
            ),  # 2 min for validation
            HookMatcher(
                hooks=[log_tool_use]
            ),  # Applies to all tools (per-event default timeout)
        ],
        "PostToolUse": [HookMatcher(hooks=[log_tool_use])],
    }
)

async def main():
    async for message in query(prompt="Analyze this codebase", options=options):
        print(message)


asyncio.run(main())

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

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

Agent

Имя инструмента: Agent. Предыдущее имя Task по-прежнему принимается как псевдоним, и список tools в инициализации SystemMessage сообщает об этом инструменте как Task для обратной совместимости.

Ввод:

{
    "description": str,  # Краткое описание задачи (3-5 слов)
    "prompt": str,  # Задача для выполнения агентом
    "subagent_type": str | None,  # Тип специализированного агента для использования
    "model": "sonnet" | "opus" | "haiku" | "fable" | None,  # Переопределение модели для этого агента
    "run_in_background": bool | None,  # Агенты запускаются в фоне по умолчанию; установите значение False для синхронного выполнения
    "name": str | None,  # Имя для порожденного агента
    "team_name": str | None,  # Устарело; игнорируется
    "mode": "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan" | None,  # Устарело; игнорируется. Правила наследования подагента определяют режим разрешений подагента
    "isolation": "worktree" | "remote" | None,  # Режим изоляции для изменений агента
}

Запускает нового агента для автономной обработки сложных многошаговых задач.

Вывод (статус: "completed"):

{
    "status": "completed",
    "agentId": str,  # ID агента, который был запущен
    "agentType": str | None,  # Тип подагента, который обработал задачу
    "content": [  # Блоки содержимого результата
        {
            "type": "text",
            "text": str,
            "citations": list | None,
        }
    ],
    "resolvedModel": str | None,  # Модель, на которой запустился подагент
    "modelsUsed": list[str] | None,  # Модели, использованные по порядку, с коллапсированными последовательными повторениями
    "totalToolUseCount": int,  # Количество вызовов инструментов, которые сделал агент
    "totalDurationMs": int,  # Длительность выполнения в миллисекундах
    "totalTokens": int,  # Количество токенов из финального запроса API, не из всего запуска
    "usage": {  # Статистика использования токенов
        "input_tokens": int,
        "output_tokens": int,
        "cache_creation_input_tokens": int | None,
        "cache_read_input_tokens": int | None,
        "server_tool_use": {"web_search_requests": int, "web_fetch_requests": int} | None,
        "service_tier": str | None,
        "cache_creation": {"ephemeral_1h_input_tokens": int, "ephemeral_5m_input_tokens": int} | None,
        "inference_geo": str | None,
        "speed": str | None,
        "iterations": Any | None,
        "output_tokens_details": {"thinking_tokens": int | None} | None,
    },
    "toolStats": {  # Совокупная активность инструментов для запуска
        "readCount": int,
        "searchCount": int,
        "bashCount": int,
        "editFileCount": int,
        "linesAdded": int,
        "linesRemoved": int,
        "otherToolCount": int,
        "frameCount": int | None,
    } | None,
    "prompt": str,  # Подсказка, которую запустил агент
    "worktreePath": str | None,  # Присутствует, когда Claude Code сохранил worktree подагента
    "worktreeBranch": str | None,  # Присутствует, когда Claude Code создал этот worktree с git
}

Вывод (статус: "async_launched"):

{
    "status": "async_launched",
    "isAsync": bool | None,  # True при фоновых запусках
    "agentId": str,  # ID запущенного агента
    "description": str,  # Описание задачи
    "resolvedModel": str | None,  # Модель, используемая при переходе в фоновый режим
    "modelsUsed": list[str] | None,  # Модели, использованные перед фоновым режимом, по порядку, с коллапсированными последовательными повторениями
    "prompt": str,  # Подсказка, которую запускает агент
    "outputFile": str,  # Путь файла, где записывается вывод агента
    "canReadOutputFile": bool | None,  # Может ли выходной файл быть прочитан напрямую
}

Вывод (статус: "remote_launched"):

{
    "status": "remote_launched",
    "taskId": str,  # ID удаленной задачи
    "sessionUrl": str,  # Ссылка на удаленный облачный сеанс
    "description": str,  # Описание задачи
    "prompt": str,  # Подсказка, которую запускает агент
    "outputFile": str,  # Путь файла, где записывается вывод агента
}

Возвращает результат от подагента. Вывод различается по полю status: "completed" для завершенных задач, "async_launched" для фоновых задач и "remote_launched" для задач, которые Claude Code отправил в удаленный облачный сеанс, где sessionUrl ссылается на этот сеанс и taskId его идентифицирует. Если Claude Code сохранил изолированный worktree подагента, worktreePath в варианте completed — это место, где его найти, и worktreeBranch — это его ветка, когда Claude Code создал worktree с git.

В варианте completed, resolvedModel называет модель, на которой запустился подагент, которая может отличаться от запрошенного входа model, когда применяется availableModels или другое переопределение. Это поле требует Claude Code v2.1.174 или позже. В варианте async_launched, resolvedModel называет модель, используемую, когда агент перешел в фоновый режим, поэтому обмен, произошедший перед фоновым режимом, отражается там. Поле modelsUsed в обоих вариантах перечисляет использованные модели по порядку, с коллапсированными последовательными повторениями; оно устанавливается только при обмене модели во время выполнения. modelsUsed и поведение resolvedModel во время фонового режима требуют Claude Code v2.1.212 или позже.

Claude Code заполняет usage и totalTokens из финального запроса API подагента, не из всего запуска. Когда присутствует, thinking_tokens под output_tokens_details в usage — это количество выходных токенов этого запроса, которые были токенами мышления. Ключ output_tokens_details требует Python SDK v0.2.136 или позже, который поставляется с Claude Code v2.1.228.

AskUserQuestion

Имя инструмента: AskUserQuestion

Задает пользователю уточняющие вопросы во время выполнения. См. Обработка одобрений и ввода пользователя для деталей использования.

Ввод:

{
    "questions": [  # Вопросы для пользователя (1-4 вопроса)
        {
            "question": str,  # Полный вопрос для пользователя
            "header": str,  # Очень короткая метка, отображаемая как чип/тег (макс 12 символов)
            "options": [  # Доступные варианты (2-4 варианта)
                {
                    "label": str,  # Текст отображения для этого варианта (1-5 слов)
                    "description": str,  # Объяснение того, что означает этот вариант
                    "preview": str | None,  # Содержимое предпросмотра, отображаемое при фокусировке на варианте
                }
            ],
            "multiSelect": bool,  # Установите значение true, чтобы разрешить множественный выбор
        }
    ],
    "answers": dict[str, str] | None,
    # Ответы пользователя, заполненные системой разрешений. Ответы с множественным выбором
    # — это строка, объединенная запятыми из выбранных меток; список меток принимается
    # на входе и приводится к этой форме
    "annotations": dict[str, dict] | None,
    # Аннотации для каждого вопроса от пользователя, ключ — текст вопроса.
    # Каждое значение может содержать "preview" (содержимое предпросмотра выбранного варианта)
    # и "notes" (свободные заметки по выбору)
    "metadata": dict | None,  # Метаданные аналитики, такие как {"source": "remember"}; не отображается пользователю
}

Вывод:

{
    "questions": [  # Вопросы, которые были заданы
        {
            "question": str,
            "header": str,
            "options": [{"label": str, "description": str, "preview": str | None}],
            "multiSelect": bool,
        }
    ],
    "answers": dict[str, str],  # Сопоставляет текст вопроса со строкой ответа
    # Ответы с множественным выбором разделены запятыми
    "response": str | None,
    # Свободный ответ, введенный вместо ответа на вопросы; когда установлено,
    # Claude получает "The user responded: ..." вместо списка ответов
    "annotations": dict[str, dict] | None,  # Аннотации "preview" и "notes" для каждого вопроса из выборов пользователя
    "afkTimeoutMs": int | None,  # Установлено, когда диалог автоматически разрешился после этого количества миллисекунд неактивности пользователя; отсутствует, когда пользователь ответил
}

Bash

Имя инструмента: Bash

Ввод:

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

Вывод:

{
    "stdout": str,  # Вывод команды; stdout и stderr поступают объединенными в этот один чередующийся поток
    "stderr": str,  # Уведомления, которые добавляет сам инструмент, не stderr команды
    "interrupted": bool,  # Была ли команда прервана
    "isImage": bool | None,  # Содержит ли stdout данные изображения
    "backgroundTaskId": str | None,  # ID фоновой задачи, если команда выполняется в фоне
}

Monitor

Имя инструмента: Monitor

Запускает фоновый источник и доставляет каждое событие в Claude, чтобы он мог реагировать без опроса: command запускает скрипт и выдает одно событие на строку stdout, а ws открывает WebSocket и выдает одно событие на текстовый фрейм. Укажите ровно один из command или ws.

Когда Monitor запускает команду, он следует тем же правилам разрешений, что и Bash; наблюдение за WebSocket запрашивает одобрение отдельно. Источник ws требует Claude Code v2.1.195 или позже. См. Справочник инструмента Monitor для поведения и доступности поставщика.

Ввод:

{
    "command": str | None,  # Скрипт оболочки; каждая строка stdout является событием, выход завершает наблюдение
    "ws": dict | None,  # Источник WebSocket: {"url": str, "protocols": list[str] | None}; каждый текстовый фрейм является событием
    "description": str,  # Краткое описание, показываемое в уведомлениях
    "timeout_ms": int | None,  # Завершить после этого срока (по умолчанию 300000, макс 3600000; эффективный срок составляет максимум 1800000)
}

Вывод:

{
    "taskId": str,  # ID фоновой задачи мониторинга
    "timeoutMs": int,  # Эффективный срок тайм-аута в миллисекундах
    "persistent": bool | None,  # False: каждое наблюдение имеет срок
}

Edit

Имя инструмента: Edit

Ввод:

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

Вывод:

{
    "message": str,  # Сообщение подтверждения
    "replacements": 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,  # Каталог для поиска (по умолчанию текущий каталог)
}

Вывод:

{
    "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,  # Подсказка для запуска на полученном содержимом
}

Вывод:

{
    "bytes": int,  # Размер полученного содержимого в байтах
    "code": int,  # Код ответа HTTP
    "codeText": str,  # Текст кода ответа HTTP
    "result": str,  # Обработанный результат от применения подсказки к содержимому
    "durationMs": int,  # Время получения и обработки содержимого в миллисекундах
    "url": str,  # URL, который был получен
}

WebSearch

Имя инструмента: WebSearch

Ввод:

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

Вывод:

{
    "query": str,  # Поисковый запрос
    "results": list[str | {"tool_use_id": str, "content": list[{"title": str, "url": str}]}],
    "durationSeconds": float,  # Длительность поиска в секундах
}

TodoWrite

Имя инструмента: TodoWrite

Ввод:

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

Вывод:

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

TaskCreate

Имя инструмента: TaskCreate

Ввод:

{
    "subject": str,  # Краткое название задачи
    "description": str,  # Подробное описание задачи
    "activeForm": str | None,  # Метка в настоящем времени, показываемая во время выполнения
    "metadata": dict | None,  # Произвольные метаданные вызывающей стороны
}

Вывод:

{
    "task": {"id": str, "subject": str},  # Созданная задача с назначенным ID
}

TaskUpdate

Имя инструмента: TaskUpdate

Ввод:

{
    "taskId": str,  # ID задачи для обновления
    "status": Literal["pending", "in_progress", "completed", "deleted"] | None,
    "subject": str | None,
    "description": str | None,
    "activeForm": str | None,
    "addBlocks": list[str] | None,  # ID задач, которые эта задача теперь блокирует
    "addBlockedBy": list[str] | None,  # ID задач, которые теперь блокируют эту задачу
    "owner": str | None,
    "metadata": dict | None,
}

Вывод:

{
    "success": bool,
    "taskId": str,
    "updatedFields": list[str],  # Названия полей, которые изменились
    "error": str | None,
    "statusChange": {"from": str, "to": str} | None,
}

TaskGet

Имя инструмента: TaskGet

Ввод:

{
    "taskId": str,  # ID задачи для чтения
}

Вывод:

{
    "task": {
        "id": str,
        "subject": str,
        "description": str,
        "status": Literal["pending", "in_progress", "completed"],
        "blocks": list[str],
        "blockedBy": list[str],
    } | None,  # None, когда ID не найден
}

TaskList

Имя инструмента: TaskList

Ввод:

{}

Вывод:

{
    "tasks": [
        {
            "id": str,
            "subject": str,
            "status": Literal["pending", "in_progress", "completed"],
            "owner": str | None,
            "blockedBy": list[str],
        }
    ],
}

TaskOutput

Удалено в Claude Code v2.1.277. Ранее получало вывод из запущенной или завершенной фоновой задачи, с BashOutput, принимаемым как псевдоним; Claude читает выходной файл фоновой задачи с помощью Read вместо этого.

Запись disallowed_tools или правило отказа, которое по-прежнему называет любое имя, игнорируется без предупреждения.

TaskStop

Имя инструмента: TaskStop. Предыдущие имена KillShell и KillBash по-прежнему принимаются как псевдонимы.

Ввод:

{
    "task_id": str | None,  # ID фоновой задачи для остановки
    "shell_id": str | None,  # Устарело: используйте task_id вместо этого
}

Вывод:

{
    "message": str,  # Сообщение о статусе операции
    "task_id": str,  # ID остановленной задачи
    "task_type": str,  # Тип остановленной задачи
    "command": str | None,  # Команда или описание остановленной задачи
}

ExitPlanMode

Имя инструмента: ExitPlanMode

Ввод:

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

Вывод:

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

ListMcpResources

Имя инструмента: ListMcpResourcesTool

Ввод:

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

Вывод:

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

ReadMcpResource

Имя инструмента: ReadMcpResourceTool

Ввод:

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

Вывод:

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

Построение интерфейса непрерывного разговора

Следующий пример сохраняет один ClaudeSDKClient подключённым на протяжении нескольких ходов, поэтому Claude помнит предыдущие сообщения. Введите new для отключения и повторного подключения для новой сессии или exit для завершения разговора.

from claude_agent_sdk import (
    ClaudeSDKClient,
    ClaudeAgentOptions,
    AssistantMessage,
    TextBlock,
)
import asyncio


class ConversationSession:
    """Maintains a single conversation session with Claude."""

    def __init__(self, options: ClaudeAgentOptions | None = None):
        self.client = ClaudeSDKClient(options)
        self.turn_count = 0

    async def start(self):
        await self.client.connect()
        print("Starting conversation session. Claude will remember context.")
        print(
            "Commands: 'exit' to quit, 'interrupt' to stop current task, 'new' for new session"
        )

        while True:
            user_input = input(f"\n[Turn {self.turn_count + 1}] You: ")

            if user_input.lower() == "exit":
                break
            elif user_input.lower() == "interrupt":
                await self.client.interrupt()
                print("Task interrupted!")
                continue
            elif user_input.lower() == "new":
                # Disconnect and reconnect for a fresh session
                await self.client.disconnect()
                await self.client.connect()
                self.turn_count = 0
                print("Started new conversation session (previous context cleared)")
                continue

            # Send message - the session retains all previous messages
            await self.client.query(user_input)
            self.turn_count += 1

            # Process response
            print(f"[Turn {self.turn_count}] Claude: ", end="")
            async for message in self.client.receive_response():
                if isinstance(message, AssistantMessage):
                    for block in message.content:
                        if isinstance(block, TextBlock):
                            print(block.text, end="")
            print()  # New line after response

        await self.client.disconnect()
        print(f"Conversation ended after {self.turn_count} turns.")


async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Write", "Bash"], permission_mode="acceptEdits"
    )
    session = ConversationSession(options)
    await session.start()


# Example conversation:
# Turn 1 - You: "Create a file called hello.py"
# Turn 1 - Claude: "I'll create a hello.py file for you..."
# Turn 2 - You: "What's in that file?"
# Turn 2 - Claude: "The hello.py file I just created contains..." (remembers!)
# Turn 3 - You: "Add a main function to it"
# Turn 3 - Claude: "I'll add a main function to hello.py..." (knows which file!)

asyncio.run(main())

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

Следующий пример оборачивает вызов query() в обработчики для четырех из типов ошибок, которые вызывает SDK.

Этот пример перехватывает ResultError, что требует Python Agent SDK версии 0.2.140 или позже.

import asyncio

from claude_agent_sdk import (
    query,
    CLINotFoundError,
    ProcessError,
    ResultError,
    CLIJSONDecodeError,
)


async def main():
    try:
        async for message in query(prompt="Hello"):
            print(message)
    except CLINotFoundError:
        print(
            "Claude Code CLI not found. Try reinstalling: pip install --force-reinstall claude-agent-sdk"
        )
    # Catch ResultError before ProcessError, which it subclasses. Its message
    # carries the error text. A failed final request, such as an API error,
    # arrives with subtype "success", so branch on terminal_reason first.
    except ResultError as e:
        if e.terminal_reason == "api_error":
            print(f"API request failed: {e}")
        else:
            print(f"Query ended with an error result ({e.terminal_reason or e.subtype}): {e}")
    except ProcessError as e:
        print(f"Process failed with exit code: {e.exit_code}")
    except CLIJSONDecodeError as e:
        print(f"Failed to parse response: {e}")


asyncio.run(main())

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

`SandboxSettings`

Конфигурация для поведения sandbox. Используйте это для включения sandboxing команд и программной настройки ограничений сети.

class SandboxSettings(TypedDict, total=False):
    enabled: bool
    autoAllowBashIfSandboxed: bool
    excludedCommands: list[str]
    allowUnsandboxedCommands: bool
    network: SandboxNetworkConfig
    ignoreViolations: SandboxIgnoreViolations
    enableWeakerNestedSandbox: bool

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

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions

sandbox_settings = {
    "enabled": True,
    "autoAllowBashIfSandboxed": True,
    "failIfUnavailable": True,
    "network": {"allowLocalBinding": True},
}


async def main():
    try:
        async for message in query(
            prompt="Build and test my project",
            options=ClaudeAgentOptions(sandbox=sandbox_settings),
        ):
            print(message)
    except Exception as error:
        # A single-shot query() raises after yielding an error result,
        # such as when failIfUnavailable is set and the sandbox can't start.
        print(f"Session ended with an error: {error}")


asyncio.run(main())

`SandboxNetworkConfig`

Конфигурация для сети в режиме sandbox. Эти параметры применяются к sandboxed Bash командам, когда enabled имеет значение True в родительском SandboxSettings. Они не ограничивают инструмент WebFetch, который использует правила разрешений вместо этого.

class SandboxNetworkConfig(TypedDict, total=False):
    allowedDomains: list[str]
    deniedDomains: list[str]
    allowManagedDomainsOnly: bool
    allowUnixSockets: list[str]
    allowAllUnixSockets: bool
    allowLocalBinding: bool
    allowMachLookup: list[str]
    httpProxyPort: int
    socksProxyPort: int

`SandboxIgnoreViolations`

Конфигурация для игнорирования определенных нарушений sandbox.

class SandboxIgnoreViolations(TypedDict, total=False):
    file: list[str]
    network: list[str]

Fallback системы разрешений для команд без Sandbox

Когда allowUnsandboxedCommands включен, модель может запросить выполнение команд вне sandbox, установив dangerouslyDisableSandbox: True во входных данных инструмента. Эти запросы переходят к существующей системе разрешений, что означает, что ваш обработчик can_use_tool будет вызван, позволяя вам реализовать пользовательскую логику авторизации.

Ваши записи excludedCommands вместо этого выводят команду из sandbox без участия модели; sandbox.excludedCommands описывает, когда применяется запись.

Следующий пример регистрирует каждый запрос без sandbox и отклоняет его, если только ваша собственная логика авторизации не разрешит это:

import asyncio
from claude_agent_sdk import (
    query,
    ClaudeAgentOptions,
    HookMatcher,
    PermissionResultAllow,
    PermissionResultDeny,
    ToolPermissionContext,
)


def is_command_authorized(command: str | None) -> bool:
    # Replace with your own authorization logic
    return False



async def can_use_tool(
    tool: str, input: dict, context: ToolPermissionContext
) -> PermissionResultAllow | PermissionResultDeny:
    # Check if the model is requesting to bypass the sandbox
    if tool == "Bash" and input.get("dangerouslyDisableSandbox"):
        # The model is requesting to run this command outside the sandbox
        print(f"Unsandboxed command requested: {input.get('command')}")

        if is_command_authorized(input.get("command")):
            return PermissionResultAllow()
        return PermissionResultDeny(
            message="Command not authorized for unsandboxed execution"
        )
    return PermissionResultAllow()


# Required: dummy hook keeps the stream open for can_use_tool
async def dummy_hook(input_data, tool_use_id, context):
    return {"continue_": True}


async def prompt_stream():
    yield {
        "type": "user",
        "message": {"role": "user", "content": "Deploy my application"},
    }


async def main():
    async for message in query(
        prompt=prompt_stream(),
        options=ClaudeAgentOptions(
            sandbox={
                "enabled": True,
                "allowUnsandboxedCommands": True,  # Model can request unsandboxed execution
            },
            permission_mode="default",
            can_use_tool=can_use_tool,
            hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]},
        ),
    ):
        print(message)


asyncio.run(main())

См. также

• SDK overview - Общие концепции SDK
• TypeScript SDK reference - Документация TypeScript SDK
• Custom tools - Определение встроенных инструментов MCP для вызова Claude
• CLI reference - Интерфейс командной строки
• Common workflows - Пошаговые руководства