Перейти к основному содержанию
Agent SDK предоставляет вам те же инструменты, цикл агента и управление контекстом, которые питают Claude Code. Он доступен как CLI для скриптов и CI/CD, или как пакеты Python и TypeScript для полного программного управления.
CLI ранее назывался “headless mode”. Флаг -p и все параметры CLI работают так же.
Чтобы запустить Claude Code программно из CLI, передайте -p с вашим запросом и любыми параметрами CLI: 
claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"
На этой странице рассматривается использование Agent SDK через CLI (claude -p). Для пакетов Python и TypeScript SDK со структурированными выходами, обратными вызовами одобрения инструментов и собственными объектами сообщений см. полную документацию Agent SDK.

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

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

​
Примеры

Эти примеры выделяют общие паттерны CLI.

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

Используйте --output-format для управления тем, как возвращаются ответы:
  • text (по умолчанию): простой текстовый вывод
  • json: структурированный JSON с результатом, ID сессии и метаданными
  • stream-json: JSON с разделением по строкам для потоковой передачи в реальном времени
Этот пример возвращает сводку проекта в виде JSON с метаданными сессии, с текстовым результатом в поле result: 
claude -p "Summarize this project" --output-format json
Чтобы получить вывод, соответствующий определённой схеме, используйте --output-format json с --json-schema и определением JSON Schema. Ответ включает метаданные о запросе (ID сессии, использование и т.д.) со структурированным выводом в поле structured_output. Этот пример извлекает имена функций и возвращает их как массив строк: 
claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'
Используйте инструмент вроде jq для анализа ответа и извлечения определённых полей:
# Extract the text result
claude -p "Summarize this project" --output-format json | jq -r '.result'

# Extract structured output
claude -p "Extract function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

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

Используйте --output-format stream-json с --verbose и --include-partial-messages для получения токенов по мере их генерации. Каждая строка — это объект JSON, представляющий событие: 
claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages
Следующий пример использует jq для фильтрации текстовых дельт и отображения только потокового текста. Флаг -r выводит необработанные строки (без кавычек), а -j объединяет без новых строк, чтобы токены передавались непрерывно: 
claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'
Для программной потоковой передачи с обратными вызовами и объектами сообщений см. Stream responses in real-time в документации Agent SDK.

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

Используйте --allowedTools для разрешения Claude использовать определённые инструменты без запроса. Этот пример запускает набор тестов и исправляет ошибки, позволяя Claude выполнять команды Bash и читать/редактировать файлы без запроса разрешения: 
claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

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

Этот пример проверяет поставленные в очередь изменения и создаёт коммит с соответствующим сообщением: 
claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"
Флаг --allowedTools использует синтаксис правил разрешений. Завершающий * включает сопоставление префиксов, поэтому Bash(git diff *) разрешает любую команду, начинающуюся с git diff. Пробел перед * важен: без него Bash(git diff*) также совпадал бы с git diff-index.
Вызываемые пользователем skills вроде /commit и встроенные команды доступны только в интерактивном режиме. В режиме -p опишите задачу, которую вы хотите выполнить.

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

Используйте --append-system-prompt для добавления инструкций при сохранении поведения Claude Code по умолчанию. Этот пример передаёт diff PR в Claude и инструктирует его проверить на уязвимости безопасности: 
gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json
См. флаги системного запроса для получения дополнительных параметров, включая --system-prompt для полной замены запроса по умолчанию.

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

Используйте --continue для продолжения самого последнего разговора или --resume с ID сессии для продолжения определённого разговора. Этот пример запускает проверку, а затем отправляет дополнительные запросы: 
# First request
claude -p "Review this codebase for performance issues"

# Continue the most recent conversation
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue
Если вы запускаете несколько разговоров, захватите ID сессии для возобновления определённого: 
session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

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

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