Skip to main content
Agent SDK предоставляет вам те же инструменты, цикл агента и управление контекстом, которые питают Claude Code. Он доступен как CLI для скриптов и CI/CD, или как пакеты Python и TypeScript для полного программного управления. Чтобы запустить Claude Code в неинтерактивном режиме, передайте -p с вашим запросом и любыми параметрами CLI:
На этой странице рассматривается использование Agent SDK через CLI (claude -p). Для пакетов Python и TypeScript SDK со структурированными выходами, обратными вызовами одобрения инструментов и собственными объектами сообщений см. полную документацию Agent SDK.

Базовое использование

Добавьте флаг -p (или --print) к любой команде claude для запуска её в неинтерактивном режиме. Все параметры CLI работают с -p, включая: Этот пример задаёт Claude вопрос о вашей кодовой базе и выводит ответ:

Начните быстрее с режимом bare

Добавьте --bare для сокращения времени запуска путём пропуска автоматического обнаружения hooks, skills, plugins, MCP серверов, автоматической памяти и CLAUDE.md. Без этого claude -p загружает тот же контекст, что и интерактивная сессия, включая всё, что настроено в рабочем каталоге или ~/.claude. Режим bare полезен для CI и скриптов, где вам нужен одинаковый результат на каждой машине. Hook в ~/.claude коллеги или MCP сервер в .mcp.json проекта не будут запущены, потому что режим bare никогда их не читает. Действуют только явно переданные флаги. Этот пример запускает одноразовую задачу суммирования в режиме bare и предварительно одобряет инструмент Read, чтобы вызов завершился без запроса разрешения:
В режиме bare Claude имеет доступ к инструментам Bash, чтения файлов и редактирования файлов. Передайте любой необходимый контекст с флагом: Режим bare пропускает OAuth и чтение из связки ключей. Аутентификация Anthropic должна поступать из ANTHROPIC_API_KEY или apiKeyHelper в JSON, переданном в --settings. Amazon Bedrock, Google Cloud’s Agent Platform и Microsoft Foundry используют обычные учётные данные поставщика.
--bare — это рекомендуемый режим для скриптовых и SDK вызовов, и он станет режимом по умолчанию для -p в будущем выпуске.

Фоновые задачи при выходе

Если Claude запускает фоновую задачу Bash во время выполнения claude -p, например сервер разработки или сборку с отслеживанием, эта задача завершается примерно через пять секунд после того, как Claude вернул свой окончательный результат и stdin закрыт. Период ожидания позволяет задаче, которая завершается сразу после результата, всё ещё доставить свой вывод. До версии v2.1.163 никогда не завершающийся фоновый процесс держал бы вызов claude -p открытым неопределённо долго. Фоновые подагенты и рабочие процессы освобождены от пятисекундного периода ожидания, потому что их результат является частью окончательного вывода, поэтому claude -p ждёт их завершения. Начиная с версии v2.1.182, это ожидание ограничено десятью минутами по умолчанию, чтобы застрявший фоновый агент не мог держать процесс открытым неопределённо долго. Отрегулируйте ограничение с помощью CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS или установите его на 0, чтобы ждать без ограничений.

Примеры

Эти примеры выделяют общие паттерны CLI. Для CI и других скриптовых вызовов добавьте --bare, чтобы они не подхватывали то, что случайно настроено локально.

Передача данных через Claude

Неинтерактивный режим читает stdin, поэтому вы можете передавать данные и перенаправлять ответ, как любой другой инструмент командной строки. Этот пример передаёт журнал сборки в Claude и записывает объяснение в файл:
С --output-format json полезная нагрузка ответа включает total_cost_usd и разбивку затрат по моделям, поэтому скриптовые вызывающие стороны могут отслеживать расходы на вызов без обращения к панели использования.
Начиная с Claude Code v2.1.128, piped stdin ограничен 10MB. Если вы превысите лимит, Claude Code выходит с чётким сообщением об ошибке и ненулевым статусом. Для работы с большими входными данными запишите содержимое в файл и ссылайтесь на путь файла в вашем запросе вместо передачи через pipe.

Добавление Claude в скрипт сборки

Вы можете обернуть неинтерактивный вызов в скрипт, чтобы использовать Claude как проектный линтер или рецензент. Этот скрипт package.json передаёт diff относительно main в Claude и просит его сообщить об опечатках. Передача diff означает, что Claude не нуждается в разрешении Bash для его чтения, а экранированные двойные кавычки делают скрипт портативным для Windows:

Получение структурированного вывода

Используйте --output-format для управления тем, как возвращаются ответы:
  • text (по умолчанию): простой текстовый вывод
  • json: структурированный JSON с результатом, ID сессии и метаданными
  • stream-json: JSON с разделением по строкам для потоковой передачи в реальном времени
Этот пример возвращает сводку проекта в виде JSON с метаданными сессии, с текстовым результатом в поле result:
Чтобы получить вывод, соответствующий определённой схеме, используйте --output-format json с --json-schema и определением JSON Schema. Ответ включает метаданные о запросе (ID сессии, использование и т.д.) со структурированным выводом в поле structured_output. Этот пример извлекает имена функций и возвращает их как массив строк:
Если значение не является действительной JSON Schema, claude выходит с Error: --json-schema is not a valid JSON Schema, за которым следует диагностика валидатора. Claude Code принимает схемы, которые используют ключевое слово format, такие как "format": "email", но рассматривает format как аннотацию и не применяет его. До версии v2.1.205 Claude Code молча игнорировал недействительную схему и возвращал неструктурированный текст, а также рассматривал любую схему, содержащую format, как недействительную.
Используйте инструмент вроде jq для анализа ответа и извлечения определённых полей:

Потоковая передача ответов

Используйте --output-format stream-json с --verbose и --include-partial-messages для получения токенов по мере их генерации. Каждая строка — это объект JSON, представляющий событие:
Последняя строка потока — это сообщение result с финальным текстом ответа, стоимостью и метаданными сессии. До версии v2.1.208 передача большого ответа могла обрезать финальную строку и опустить сообщение result. Следующий пример использует jq для фильтрации текстовых дельт и отображения только потокового текста. Флаг -r выводит необработанные строки (без кавычек), а -j объединяет без новых строк, чтобы токены передавались непрерывно:
Когда запрос API завершается с повторяемой ошибкой, Claude Code выдаёт событие system/api_retry перед повторной попыткой. Вы можете использовать это для отображения прогресса повторной попытки или реализации пользовательской логики отката. Событие system/init сообщает метаданные сессии, включая модель, инструменты, MCP серверы и загруженные плагины. Это первое событие в потоке, если не установлены события запуска:
  • события plugin_install, когда установлена CLAUDE_CODE_SYNC_PLUGIN_INSTALL.
  • события hook_started, hook_progress и hook_response, пока работает настроенный hook SessionStart или Setup. Они передаются потоком по мере их создания. Claude Code v2.1.169 через v2.1.203 доставлял их одной партией после завершения hook, всё ещё впереди system/init; v2.1.204 восстановил живую доставку.
Событие также содержит опциональный массив capabilities строк, называющих поведения протокола, которые реализует эта версия Claude Code, такие как interrupt_receipt_v1. Проверьте его для обнаружения функций вместо сравнения строк версий и игнорируйте значения, которые вы не распознаёте. Поле требует Claude Code v2.1.205 или позже и отсутствует в более ранних версиях. См. SDKSystemMessage для списка возможностей. Используйте поля плагина для отказа CI, когда плагин не загрузился: Когда установлена CLAUDE_CODE_SYNC_PLUGIN_INSTALL, Claude Code выдаёт события system/plugin_install во время установки плагинов marketplace перед первым ходом. Используйте их для отображения прогресса установки в вашем собственном пользовательском интерфейсе. Для программной потоковой передачи с обратными вызовами и объектами сообщений см. Stream responses in real-time в документации Agent SDK.

Автоматическое одобрение инструментов

Используйте --allowedTools для разрешения Claude использовать определённые инструменты без запроса. Этот пример запускает набор тестов и исправляет ошибки, позволяя Claude выполнять команды Bash и читать/редактировать файлы без запроса разрешения:
Чтобы установить базовый уровень для всей сессии вместо перечисления отдельных инструментов, передайте режим разрешений. dontAsk отклоняет всё, что не входит в ваши правила permissions.allow или набор команд только для чтения, что полезно для заблокированных CI запусков. AskUserQuestion, инструменты соединителя которые ваша организация установила на ask и MCP инструменты, отмеченные requiresUserInteraction, отклоняются даже когда правило разрешения совпадает. acceptEdits позволяет Claude писать файлы без запроса и также автоматически одобряет общие команды файловой системы, такие как mkdir, touch, mv и cp. Другие команды оболочки и сетевые запросы по-прежнему требуют записи --allowedTools или правила permissions.allow, иначе запуск прерывается при попытке выполнить одну из них:

Создание коммита

Этот пример проверяет поставленные в очередь изменения и создаёт коммит с соответствующим сообщением:
Флаг --allowedTools использует синтаксис правил разрешений. Завершающий * включает сопоставление префиксов, поэтому Bash(git diff *) разрешает любую команду, начинающуюся с git diff. Пробел перед * важен: без него Bash(git diff*) также совпадал бы с git diff-index.
Вызываемые пользователем skills и пользовательские команды работают в режиме -p: включите /skill-name в строку запроса, и Claude Code развернёт её перед запуском. Встроенные команды, которые только работают в интерфейсе терминала, такие как /login, недоступны в режиме -p. /model, /effort, /fast, /color и /rename принимают значение как аргумент, например /model sonnet, и /mcp без аргумента выводит текстовую сводку статуса сервера; эти формы требуют Claude Code v2.1.205 или позже и следуют примечаниям доступности каждой команды. Чтобы изменить параметр из вызова -p, передайте key=value в /config, например /config thinking=false.

Настройка системного запроса

Используйте --append-system-prompt для добавления инструкций при сохранении поведения Claude Code по умолчанию. Этот пример передаёт diff PR в Claude и инструктирует его проверить на уязвимости безопасности:
См. флаги системного запроса для получения дополнительных параметров, включая --system-prompt для полной замены запроса по умолчанию.

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

Используйте --continue для продолжения самого последнего разговора или --resume с ID сессии для продолжения определённого разговора. Этот пример запускает проверку, а затем отправляет дополнительные запросы:
Если вы запускаете несколько разговоров, захватите ID сессии для возобновления определённого:
Запустите обе команды из одного каталога: поиск ID сессии ограничен текущим каталогом проекта и его git worktrees. См. Resume a session для полного набора правил области видимости.

Следующие шаги

  • Agent SDK quickstart: создайте своего первого агента с помощью Python или TypeScript
  • CLI reference: все флаги и параметры CLI
  • GitHub Actions: используйте Agent SDK в рабочих процессах GitHub
  • GitLab CI/CD: используйте Agent SDK в конвейерах GitLab