Перейти к основному содержанию
Agent SDK построен на той же основе, что и Claude Code, что означает, что ваши SDK-агенты имеют доступ к тем же функциям на основе файловой системы: инструкции проекта (CLAUDE.md и правила), skills, hooks и многое другое. Когда вы опускаете settingSources, query() читает те же параметры файловой системы, что и Claude Code CLI: пользовательские, проектные и локальные параметры, файлы CLAUDE.md и skills, агенты и команды в .claude/. Чтобы запустить без них, передайте settingSources: [], что ограничивает агента только тем, что вы настраиваете программно. Параметры управляемой политики и глобальная конфигурация ~/.claude.json читаются независимо от этого параметра. См. Что settingSources не контролирует. Для концептуального обзора того, что делает каждая функция и когда её использовать, см. Расширение Claude Code.

Управление параметрами файловой системы с помощью settingSources

Параметр источников параметров (setting_sources в Python, settingSources в TypeScript) контролирует, какие параметры на основе файловой системы загружает SDK. Передайте явный список для включения определённых источников или передайте пустой массив для отключения пользовательских, проектных и локальных параметров. Этот пример загружает как пользовательские, так и проектные параметры, устанавливая settingSources на ["user", "project"]:
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async for message in query(
    prompt="Help me refactor the auth module",
    options=ClaudeAgentOptions(
        # "user" loads from ~/.claude/, "project" loads from ./.claude/ in cwd.
        # Together they give the agent access to CLAUDE.md, skills, hooks, and
        # permissions from both locations.
        setting_sources=["user", "project"],
        allowed_tools=["Read", "Edit", "Bash"],
    ),
):
    if isinstance(message, AssistantMessage):
        for block in message.content:
            if hasattr(block, "text"):
                print(block.text)
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(f"\nResult: {message.result}")
Каждый источник загружает параметры из определённого местоположения, где <cwd> — это рабочий каталог, который вы передаёте через параметр cwd, или текущий каталог процесса, если он не установлен. Для полного определения типа см. SettingSource (TypeScript) или SettingSource (Python).
ИсточникЧто он загружаетМестоположение
"project"Project CLAUDE.md, .claude/rules/*.md, project skills, project hooks, project settings.json<cwd>/.claude/ для settings.json и hooks; <cwd> и каждый родительский каталог для CLAUDE.md и rules; <cwd> и каждый родительский каталог вверх до корня репозитория для skills
"user"User CLAUDE.md, ~/.claude/rules/*.md, user skills, user settings~/.claude/
"local"CLAUDE.local.md, .claude/settings.local.json<cwd>/.claude/ для settings.local.json; <cwd> и каждый родительский каталог для CLAUDE.local.md
Опускание settingSources эквивалентно ["user", "project", "local"]. Параметр cwd определяет, где SDK ищет входные данные уровня проекта. CLAUDE.md и rules загружаются из <cwd> и из каждого родительского каталога. Skills загружаются из <cwd> и из каждого родительского каталога вверх до корня репозитория. Project settings.json и hooks загружаются только из <cwd>/.claude/ без резервного варианта для родительского каталога.

Что settingSources не контролирует

settingSources охватывает пользовательские, проектные и локальные параметры. Несколько входов читаются независимо от его значения:
ВходПоведениеДля отключения
Параметры управляемой политикиВсегда загружаются при наличии на хостеУдалите файл управляемых параметров
~/.claude.json глобальная конфигурацияВсегда читаетсяПереместите с помощью CLAUDE_CONFIG_DIR в env
Автоматическая память в ~/.claude/projects/<project>/memory/Загружается по умолчанию в системный запросУстановите autoMemoryEnabled: false в параметрах или CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 в env
claude.ai MCP connectorsЗагружаются, когда активный метод аутентификации — это подписка claude.ai. Передача mcpServers: {} их не подавляетУстановите strictMcpConfig: true или ENABLE_CLAUDEAI_MCP_SERVERS=false в env
Не полагайтесь на параметры query() по умолчанию для изоляции в многопользовательской среде. Поскольку входы выше читаются независимо от settingSources, процесс SDK может подхватить конфигурацию уровня хоста и память для каждого каталога. Для развёртываний в многопользовательской среде запустите каждого пользователя в собственной файловой системе и установите settingSources: [] плюс CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 в env. См. Безопасное развёртывание.

Инструкции проекта (CLAUDE.md и правила)

Файлы CLAUDE.md и файлы .claude/rules/*.md дают вашему агенту постоянный контекст о вашем проекте: соглашения кодирования, команды сборки, архитектурные решения и инструкции. Когда settingSources включает "project" (как в примере выше), SDK загружает эти файлы в контекст при запуске сеанса. Затем агент следует вашим соглашениям проекта без необходимости повторять их в каждом запросе.

Местоположения загрузки CLAUDE.md

УровеньМестоположениеКогда загружается
Project (root)<cwd>/CLAUDE.md или <cwd>/.claude/CLAUDE.mdsettingSources включает "project"
Project rules<cwd>/.claude/rules/*.md и .claude/rules/*.md в каждом родительском каталогеsettingSources включает "project"
Project (parent dirs)Файлы CLAUDE.md в каталогах выше cwdsettingSources включает "project", загружается при запуске сеанса
Project (child dirs)Файлы CLAUDE.md в подкаталогах cwdsettingSources включает "project", загружается по требованию, когда агент читает файл в этом поддереве
Local<cwd>/CLAUDE.local.md и CLAUDE.local.md в каждом родительском каталогеsettingSources включает "local"
User~/.claude/CLAUDE.mdsettingSources включает "user"
User rules~/.claude/rules/*.mdsettingSources включает "user"
Все уровни являются аддитивными: если существуют как проектные, так и пользовательские файлы CLAUDE.md, агент видит оба. Между уровнями нет жёсткого правила приоритета; если инструкции конфликтуют, результат зависит от того, как Claude их интерпретирует. Напишите неконфликтующие правила или явно укажите приоритет в более специфичном файле («Эти инструкции проекта переопределяют любые конфликтующие пользовательские значения по умолчанию»).
Вы также можете внедрить контекст непосредственно через systemPrompt без использования файлов CLAUDE.md. См. Изменение системных запросов. Используйте CLAUDE.md, когда вы хотите, чтобы один и тот же контекст был общим между интерактивными сеансами Claude Code и вашими SDK-агентами.
О том, как структурировать и организовать содержимое CLAUDE.md, см. Управление памятью Claude.

Skills

Skills — это файлы markdown, которые дают вашему агенту специализированные знания и вызываемые рабочие процессы. В отличие от CLAUDE.md (который загружается каждый сеанс), skills загружаются по требованию. Агент получает описания skills при запуске и загружает полное содержимое при необходимости. Skills обнаруживаются из файловой системы через settingSources. Когда параметр skills в query() опущен, обнаруженные пользовательские и проектные skills включены и инструмент Skill доступен, что соответствует поведению CLI. Для управления тем, какие skills включены, передайте skills как "all", список имён skills или [] для отключения всех. Когда skills установлен, SDK автоматически добавляет инструмент Skill в allowedTools. Если вы также передаёте явный список tools, включите "Skill" в этот список, чтобы Claude мог вызывать skills.
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

# Skills in .claude/skills/ are discovered automatically
# when settingSources includes "project"
async for message in query(
    prompt="Review this PR using our code review checklist",
    options=ClaudeAgentOptions(
        setting_sources=["user", "project"],
        skills="all",
        allowed_tools=["Read", "Grep", "Glob"],
    ),
):
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(message.result)
Skills должны быть созданы как артефакты файловой системы (.claude/skills/<name>/SKILL.md). SDK не имеет программного API для регистрации skills. См. Agent Skills в SDK для полных деталей.
Дополнительную информацию о создании и использовании skills см. в разделе Agent Skills в SDK.

Hooks

SDK поддерживает два способа определения hooks, и они работают рядом:
  • Filesystem hooks: команды оболочки, определённые в settings.json, загружаются, когда settingSources включает соответствующий источник. Это те же hooks, которые вы бы настроили для интерактивных сеансов Claude Code.
  • Programmatic hooks: функции обратного вызова, передаваемые непосредственно в query(). Они выполняются в процессе вашего приложения и могут возвращать структурированные решения. См. Управление выполнением с помощью hooks.
Оба типа выполняются во время одного и того же жизненного цикла hook. Если у вас уже есть hooks в файле .claude/settings.json вашего проекта и вы установили settingSources: ["project"], эти hooks автоматически запускаются в SDK без дополнительной конфигурации. Обратные вызовы Hook получают входные данные инструмента и возвращают словарь решения. Возврат {} означает разрешить инструменту продолжить. Чтобы заблокировать выполнение, верните объект hookSpecificOutput с permissionDecision: "deny" и permissionDecisionReason. Причина отправляется Claude как результат инструмента. Поля верхнего уровня decision и reason устарели для PreToolUse. См. руководство hooks для полной сигнатуры обратного вызова и типов возврата.
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, ResultMessage


# PreToolUse hook callback. Positional args:
#   input_data: HookInput dict with tool_name, tool_input, hook_event_name
#   tool_use_id: str | None, the ID of the tool call being intercepted
#   context: HookContext, carries session metadata
async def audit_bash(input_data, tool_use_id, context):
    command = input_data.get("tool_input", {}).get("command", "")
    if "rm -rf" in command:
        return {
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "permissionDecisionReason": "Destructive command blocked",
            }
        }
    return {}  # Empty dict: allow the tool to proceed


# Filesystem hooks from .claude/settings.json run automatically
# when settingSources loads them. You can also add programmatic hooks:
async for message in query(
    prompt="Refactor the auth module",
    options=ClaudeAgentOptions(
        setting_sources=["project"],  # Loads hooks from .claude/settings.json
        hooks={
            "PreToolUse": [
                HookMatcher(matcher="Bash", hooks=[audit_bash]),
            ]
        },
    ),
):
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(message.result)

Когда использовать какой тип hook

Тип hookЛучше всего для
Filesystem (settings.json)Совместное использование hooks между сеансами CLI и SDK. Поддерживает "command" (shell-скрипты), "http" (POST на конечную точку), "mcp_tool" (вызов инструмента подключённого MCP-сервера), "prompt" (LLM оценивает запрос) и "agent" (порождает агента-верификатора). Они срабатывают в основном агенте и любых подагентах, которые он порождает.
Programmatic (обратные вызовы в query())Логика, специфичная для приложения, структурированные решения и интеграция в процессе. Эти обратные вызовы также срабатывают внутри подагентов. Обратный вызов получает agent_id и agent_type для различения.
TypeScript SDK поддерживает дополнительные события hook помимо Python, включая SessionStart, SessionEnd, TeammateIdle и TaskCompleted. См. руководство hooks для полной таблицы совместимости событий.
Для полных деталей о programmatic hooks см. Управление выполнением с помощью hooks. Для синтаксиса filesystem hook см. Hooks.

Выбор правильной функции

Agent SDK предоставляет вам доступ к нескольким способам расширения поведения вашего агента. Если вы не уверены, какой использовать, эта таблица отображает общие цели на правильный подход.
Вы хотите…ИспользуйтеПоверхность SDK
Установить соглашения проекта, которые ваш агент всегда соблюдаетCLAUDE.mdsettingSources: ["project"] загружает его автоматически
Дать агенту справочный материал, который он загружает при необходимостиSkillssettingSources + skills опция
Запустить повторно используемый рабочий процесс (развёртывание, проверка, выпуск)User-invocable skillssettingSources + skills опция
Делегировать изолированную подзадачу свежему контексту (исследование, проверка)Subagentsпараметр agents + allowedTools: ["Agent"]
Координировать несколько экземпляров Claude Code с общими списками задач и прямой передачей сообщений между агентамиAgent teamsНе настраивается напрямую через параметры SDK. Agent teams — это функция CLI, где один сеанс действует как лидер команды, координируя работу независимых товарищей по команде
Запустить детерминированную логику на вызовах инструментов (аудит, блокировка, преобразование)Hooksпараметр hooks с обратными вызовами или shell-скрипты, загруженные через settingSources
Дать Claude структурированный доступ к инструменту для внешнего сервисаMCPпараметр mcpServers
Subagents против agent teams: Subagents являются эфемерными и изолированными: свежий разговор, одна задача, резюме возвращается родителю. Agent teams координируют несколько независимых экземпляров Claude Code, которые совместно используют список задач и обмениваются сообщениями напрямую. Agent teams — это функция CLI. См. Что наследуют subagents и сравнение agent teams для деталей.
Каждая функция, которую вы включаете, добавляет к контекстному окну вашего агента. Для затрат на функцию и того, как эти функции слоятся вместе, см. Расширение Claude Code.

Связанные ресурсы

  • Расширение Claude Code: Концептуальный обзор всех функций расширения с таблицами сравнения и анализом затрат контекста
  • Skills в SDK: Полное руководство по использованию skills программно
  • Subagents: Определение и вызов subagents для изолированных подзадач
  • Hooks: Перехват и управление поведением агента в ключевых точках выполнения
  • Permissions: Управление доступом к инструментам с помощью режимов, правил и обратных вызовов
  • System prompts: Внедрение контекста без файлов CLAUDE.md