Зачем это нужно#

До сих пор мы использовали Claude Code интерактивно — вводили команды и получали ответы. Но что, если вам нужно:

• 🔄 Запускать Claude Code из своих скриптов автоматически
• 📊 Получать результат в структурированном формате (JSON)
• 🏭 Встроить Claude Code в конвейер обработки данных
• 🤖 Создать своего агента на базе Claude Code

Agent SDK — это набор инструментов для программного управления Claude Code. Он доступен как:

• CLI-режим (claude -p) — для скриптов и командной строки
• Python SDK — для программ на Python
• TypeScript SDK — для программ на TypeScript/JavaScript

Базовое использование: режим CLI#

Запуск с промптом#

Самый простой способ — флаг -p (или --print):

# Задаём вопрос о проекте
claude -p "Что делает файл auth.py?"

# Результат выводится в терминал и Claude завершается

В отличие от обычного режима, -p работает неинтерактивно — Claude выполняет задачу и завершается. Это идеально для скриптов.

Получение JSON-ответа#

claude -p "Опиши структуру проекта" --output-format json

Результат будет содержать:

{
  "result": "Описание проекта...",
  "session_id": "abc123",
  "usage": { "input_tokens": 500, "output_tokens": 200 }
}

Структурированный вывод по схеме#

Вы можете указать, в каком формате хотите получить ответ:

claude -p "Найди все функции в auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

Результат будет строго по вашей схеме:

{
  "structured_output": {
    "functions": ["login", "logout", "verify_token", "refresh_token"]
  }
}

Потоковый вывод (стриминг)#

Для получения ответа по мере генерации:

claude -p "Напиши подробный README" \
  --output-format stream-json \
  --verbose \
  --include-partial-messages

Управление инструментами#

Разрешение определённых инструментов#

# Разрешаем только чтение, редактирование и выполнение команд
claude -p "Исправь баг в auth.py" --allowedTools "Read,Edit,Bash"

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

# Первый запрос
claude -p "Найди баг в auth.py" --output-format json > result.json

# Продолжаем с того же места
claude -p "Теперь исправь этот баг" --continue --output-format json

Примеры скриптов#

Скрипт: проверка всех файлов в папке#

#!/bin/bash
# review-all.sh — проверяет каждый файл на ошибки

for file in src/*.py; do
  echo "Проверяю: $file"
  claude -p "Проверь файл $file на ошибки и проблемы безопасности. Дай краткий отчёт." \
    --allowedTools "Read" \
    --output-format json | jq -r '.result'
  echo "---"
done

Скрипт: генерация документации#

#!/bin/bash
# generate-docs.sh — создаёт документацию для проекта

claude -p "Проанализируй все файлы в src/ и создай файл DOCUMENTATION.md с описанием каждого модуля, его функций и примерами использования." \
  --allowedTools "Read,Write" \
  --output-format json | jq -r '.result'

Пример на Python (используя subprocess)#

import subprocess
import json

def ask_claude(prompt, tools="Read"):
    """Запускает Claude Code и возвращает результат."""
    result = subprocess.run(
        ["claude", "-p", prompt, 
         "--allowedTools", tools,
         "--output-format", "json"],
        capture_output=True, text=True
    )
    return json.loads(result.stdout)

# Использование
response = ask_claude("Что делает функция main() в app.py?")
print(response["result"])

Плагин agent-sdk-dev#

В репозитории Claude Code есть плагин agent-sdk-dev, который помогает создавать проекты с Agent SDK:

Команда /new-sdk-app#

claude --plugin-dir ./plugins/agent-sdk-dev
> /agent-sdk-dev:new-sdk-app my-agent

Эта команда:

1. Спросит язык (Python или TypeScript)
2. Спросит тип агента (кодирование, бизнес, кастомный)
3. Создаст все необходимые файлы
4. Установит последнюю версию SDK
5. Проверит настройку

Агенты-верификаторы#

Плагин включает агентов для проверки правильности настройки:

• agent-sdk-verifier-py — для Python-проектов
• agent-sdk-verifier-ts — для TypeScript-проектов

Когда использовать Agent SDK#

Итоги урока#

• Agent SDK позволяет использовать Claude Code программно, не в интерактивном режиме
• Флаг claude -p запускает Claude Code в неинтерактивном режиме
• --output-format json возвращает структурированный результат
• --json-schema позволяет задать точный формат ответа
• --allowedTools ограничивает доступные инструменты
• --continue позволяет продолжить предыдущий разговор
• Плагин agent-sdk-dev помогает создавать проекты с Agent SDK
• Для полноценного SDK доступны пакеты на Python и TypeScript