Зачем использовать Claude Code SDK?

Claude Code SDK предоставляет все строительные блоки, необходимые для создания готовых к производству агентов:

  • Оптимизированная интеграция с Claude: Автоматическое кэширование промптов и оптимизация производительности
  • Богатая экосистема инструментов: Файловые операции, выполнение кода, веб-поиск и расширяемость MCP
  • Расширенные разрешения: Детальный контроль над возможностями агентов
  • Основы для производства: Встроенная обработка ошибок, управление сессиями и мониторинг

Что можно создать с помощью SDK?

Вот несколько примеров типов агентов, которых вы можете создать:

Агенты для кодирования:

  • SRE агенты, которые диагностируют и исправляют проблемы в производстве
  • Боты для проверки безопасности, которые аудируют код на уязвимости
  • Помощники дежурных инженеров, которые сортируют инциденты
  • Агенты для проверки кода, которые обеспечивают соблюдение стиля и лучших практик

Бизнес-агенты:

  • Юридические помощники, которые проверяют контракты и соответствие требованиям
  • Финансовые консультанты, которые анализируют отчеты и прогнозы
  • Агенты службы поддержки клиентов, которые решают технические проблемы
  • Помощники по созданию контента для маркетинговых команд

SDK в настоящее время доступен в TypeScript и Python, с интерфейсом командной строки (CLI) для быстрого прототипирования.

Быстрый старт

Запустите своего первого агента менее чем за 5 минут:

1

Установите SDK

Установите @anthropic-ai/claude-code из NPM:

npm install -g @anthropic-ai/claude-code
2

Установите ваш API ключ

Получите ваш API ключ из Anthropic Console и установите переменную окружения ANTHROPIC_API_KEY:

export ANTHROPIC_API_KEY="your-api-key-here"
3

Создайте своего первого агента

Создайте одного из этих примеров агентов:

# Создайте простого юридического помощника
claude -p "Проверьте эту статью контракта на потенциальные проблемы: 'Сторона соглашается на неограниченную ответственность...'" \
  --append-system-prompt "Вы юридический помощник. Выявляйте риски и предлагайте улучшения."
4

Запустите агента

Скопируйте и вставьте команду выше прямо в ваш терминал.

Каждый пример выше создает работающего агента, который будет:

  • Анализировать промпт, используя возможности рассуждения Claude
  • Планировать многошаговый подход к решению проблемы
  • Выполнять действия, используя инструменты, такие как файловые операции, bash команды и веб-поиск
  • Предоставлять практические рекомендации на основе анализа

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

Обзор

Claude Code SDK позволяет вам взаимодействовать с Claude Code в неинтерактивном режиме из ваших приложений.

Предварительные требования

  • Node.js 18+
  • @anthropic-ai/claude-code из NPM

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

Основной интерфейс командной строки для Claude Code - это команда claude. Используйте флаг --print (или -p) для запуска в неинтерактивном режиме и печати окончательного результата:

claude -p "Анализировать производительность системы" \
  --append-system-prompt "Вы инженер по производительности" \
  --allowedTools "Bash,Read,WebSearch" \
  --permission-mode acceptEdits \
  --cwd /path/to/project

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

SDK использует все опции CLI, доступные в Claude Code. Вот ключевые для использования SDK:

ФлагОписаниеПример
--print, -pЗапуск в неинтерактивном режимеclaude -p "запрос"
--output-formatУказать формат вывода (text, json, stream-json)claude -p --output-format json
--resume, -rВозобновить разговор по ID сессииclaude --resume abc123
--continue, -cПродолжить самый последний разговорclaude --continue
--verboseВключить подробное логированиеclaude --verbose
--append-system-promptДобавить к системному промпту (только с --print)claude --append-system-prompt "Пользовательская инструкция"
--allowedToolsСписок разрешенных инструментов, разделенных пробелами, или

строка со списком разрешенных инструментов, разделенных запятыми
claude --allowedTools mcp__slack mcp__filesystem

claude --allowedTools "Bash(npm install),mcp__filesystem"
--disallowedToolsСписок запрещенных инструментов, разделенных пробелами, или

строка со списком запрещенных инструментов, разделенных запятыми
claude --disallowedTools mcp__splunk mcp__github

claude --disallowedTools "Bash(git commit),mcp__github"
--mcp-configЗагрузить MCP серверы из JSON файлаclaude --mcp-config servers.json
--permission-prompt-toolMCP инструмент для обработки промптов разрешений (только с --print)claude --permission-prompt-tool mcp__auth__prompt

Для полного списка опций CLI и функций, смотрите документацию CLI reference.

Аутентификация

API ключ Anthropic

Для базовой аутентификации получите API ключ Anthropic из Anthropic Console и установите переменную окружения ANTHROPIC_API_KEY, как показано в Быстром старте.

Учетные данные сторонних API

SDK также поддерживает аутентификацию через сторонних поставщиков API:

  • Amazon Bedrock: Установите переменную окружения CLAUDE_CODE_USE_BEDROCK=1 и настройте учетные данные AWS
  • Google Vertex AI: Установите переменную окружения CLAUDE_CODE_USE_VERTEX=1 и настройте учетные данные Google Cloud

Для подробных инструкций по настройке для сторонних поставщиков, смотрите документацию Amazon Bedrock и Google Vertex AI.

Многооборотные разговоры

Для многооборотных разговоров вы можете возобновлять разговоры или продолжать с самой последней сессии:

# Продолжить самый последний разговор
claude --continue "Теперь рефакторите это для лучшей производительности"

# Возобновить конкретный разговор по ID сессии
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Обновите тесты"

# Возобновить в неинтерактивном режиме
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Исправьте все проблемы линтинга" --no-interactive

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

Режим планирования позволяет Claude анализировать код без внесения изменений, полезен для проверки кода и планирования изменений.

claude -p "Проверьте этот код" --permission-mode plan

Режим планирования ограничивает редактирование, создание файлов и выполнение команд. Смотрите режимы разрешений для деталей.

Пользовательские системные промпты

Системные промпты определяют роль, экспертизу и поведение вашего агента. Здесь вы указываете, какого типа агента вы создаете:

# Агент реагирования на инциденты SRE
claude -p "API не работает, исследуйте" \
  --append-system-prompt "Вы эксперт SRE. Диагностируйте проблемы систематически и предоставляйте практические решения."

# Агент проверки юридических документов  
claude -p "Проверьте этот контракт" \
  --append-system-prompt "Вы корпоративный юрист. Выявляйте риски, предлагайте улучшения и обеспечивайте соответствие требованиям."

# Добавить к системному промпту по умолчанию
claude -p "Рефакторите эту функцию" \
  --append-system-prompt "Всегда включайте комплексную обработку ошибок и модульные тесты."

Расширенное использование

Пользовательские инструменты через MCP

Model Context Protocol (MCP) позволяет вам предоставлять вашим агентам пользовательские инструменты и возможности. Это критически важно для создания специализированных агентов, которым нужны доменно-специфичные интеграции.

Примеры конфигураций инструментов агентов:

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {"SLACK_TOKEN": "your-slack-token"}
    },
    "jira": {
      "command": "npx", 
      "args": ["-y", "@modelcontextprotocol/server-jira"],
      "env": {"JIRA_TOKEN": "your-jira-token"}
    },
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {"DB_CONNECTION_STRING": "your-db-url"}
    }
  }
}

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

# Агент SRE с инструментами мониторинга
claude -p "Исследуйте сбой платежного сервиса" \
  --mcp-config sre-tools.json \
  --allowedTools "mcp__datadog,mcp__pagerduty,mcp__kubernetes" \
  --append-system-prompt "Вы SRE. Используйте данные мониторинга для диагностики проблем."

# Агент службы поддержки клиентов с доступом к CRM
claude -p "Помогите решить тикет клиента #12345" \
  --mcp-config support-tools.json \
  --allowedTools "mcp__zendesk,mcp__stripe,mcp__user_db" \
  --append-system-prompt "Вы специалист технической поддержки."

При использовании инструментов MCP вы должны явно разрешить их, используя флаг --allowedTools. Имена инструментов MCP следуют шаблону mcp__<serverName>__<toolName>, где:

  • serverName - это ключ из вашего файла конфигурации MCP
  • toolName - это конкретный инструмент, предоставляемый этим сервером

Эта мера безопасности гарантирует, что инструменты MCP используются только при явном разрешении.

Если вы указываете только имя сервера (т.е., mcp__<serverName>), все инструменты с этого сервера будут разрешены.

Шаблоны glob (например, mcp__go*) не поддерживаются.

Пользовательский инструмент промпта разрешений

Опционально используйте --permission-prompt-tool для передачи инструмента MCP, который мы будем использовать для проверки того, предоставляет ли пользователь модели разрешения на вызов данного инструмента. Когда модель вызывает инструмент, происходит следующее:

  1. Сначала мы проверяем настройки разрешений: все файлы settings.json, а также --allowedTools и --disallowedTools, переданные в SDK; если одна из этих настроек разрешает или запрещает вызов инструмента, мы продолжаем с вызовом инструмента
  2. В противном случае мы вызываем инструмент MCP, который вы предоставили в --permission-prompt-tool

Инструмент MCP --permission-prompt-tool получает имя инструмента и входные данные, и должен вернуть JSON-строковую полезную нагрузку с результатом. Полезная нагрузка должна быть одной из:

// вызов инструмента разрешен
{
  "behavior": "allow",
  "updatedInput": {...}, // обновленные входные данные, или просто верните обратно оригинальные входные данные
}

// вызов инструмента запрещен
{
  "behavior": "deny",
  "message": "..." // читаемая человеком строка, объясняющая, почему разрешение было отклонено
}

Примеры реализации:

# Использование с конфигурацией вашего MCP сервера
claude -p "Проанализируйте и исправьте проблемы безопасности" \
  --permission-prompt-tool mcp__security__approval_prompt \
  --mcp-config security-tools.json \
  --allowedTools "Read,Grep" \
  --disallowedTools "Bash(rm*),Write"

# С пользовательскими правилами разрешений
claude -p "Рефакторите кодовую базу" \
  --permission-prompt-tool mcp__custom__permission_check \
  --mcp-config custom-config.json \
  --output-format json

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

  • Используйте updatedInput, чтобы сказать модели, что промпт разрешений изменил ее входные данные; в противном случае установите updatedInput на оригинальные входные данные, как в примере выше. Например, если инструмент показывает пользователю diff редактирования файла и позволяет ему редактировать diff вручную, инструмент промпта разрешений должен вернуть этот обновленный diff.
  • Полезная нагрузка должна быть JSON-строковой

Форматы вывода

SDK поддерживает несколько форматов вывода:

Текстовый вывод (по умолчанию)

claude -p "Объясните файл src/components/Header.tsx"
# Вывод: Это React компонент, показывающий...

JSON вывод

Возвращает структурированные данные, включая метаданные:

claude -p "Как работает слой данных?" --output-format json

Формат ответа:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "Текст ответа здесь...",
  "session_id": "abc123"
}

Потоковый JSON вывод

Передает каждое сообщение по мере его получения:

$ claude -p "Создайте приложение" --output-format stream-json

Каждый разговор начинается с начального системного сообщения init, за которым следует список сообщений пользователя и помощника, за которым следует финальное системное сообщение result со статистикой. Каждое сообщение выдается как отдельный JSON объект.

Схема сообщений

Сообщения, возвращаемые из JSON API, строго типизированы согласно следующей схеме:

type SDKMessage =
  // Сообщение помощника
  | {
      type: "assistant";
      message: Message; // из Anthropic SDK
      session_id: string;
    }

  // Сообщение пользователя
  | {
      type: "user";
      message: MessageParam; // из Anthropic SDK
      session_id: string;
    }

  // Выдается как последнее сообщение
  | {
      type: "result";
      subtype: "success";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      result: string;
      session_id: string;
      total_cost_usd: float;
    }

  // Выдается как последнее сообщение, когда мы достигли максимального количества оборотов
  | {
      type: "result";
      subtype: "error_max_turns" | "error_during_execution";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      session_id: string;
      total_cost_usd: float;
    }

  // Выдается как первое сообщение в начале разговора
  | {
      type: "system";
      subtype: "init";
      apiKeySource: string;
      cwd: string;
      session_id: string;
      tools: string[];
      mcp_servers: {
        name: string;
        status: string;
      }[];
      model: string;
      permissionMode: "default" | "acceptEdits" | "bypassPermissions" | "plan";
    };

Мы скоро опубликуем эти типы в JSONSchema-совместимом формате. Мы используем семантическое версионирование для основного пакета Claude Code для сообщения о критических изменениях в этом формате.

Типы Message и MessageParam доступны в Anthropic SDK. Например, смотрите Anthropic TypeScript и Python SDK.

Форматы ввода

SDK поддерживает несколько форматов ввода:

Текстовый ввод (по умолчанию)

# Прямой аргумент
claude -p "Объясните этот код"

# Из stdin
echo "Объясните этот код" | claude -p

Потоковый JSON ввод

Поток сообщений, предоставляемый через stdin, где каждое сообщение представляет оборот пользователя. Это позволяет несколько оборотов разговора без перезапуска бинарного файла claude и позволяет предоставлять руководство модели во время обработки запроса.

Каждое сообщение является JSON объектом ‘Сообщение пользователя’, следующим тому же формату, что и схема выходных сообщений. Сообщения форматируются с использованием формата jsonl, где каждая строка ввода является полным JSON объектом. Потоковый JSON ввод требует -p и --output-format stream-json.

В настоящее время это ограничено только текстовыми сообщениями пользователя.

$ echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Объясните этот код"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

Примеры интеграции агентов

Бот реагирования на инциденты SRE

#!/bin/bash

# Автоматизированный агент реагирования на инциденты
investigate_incident() {
    local incident_description="$1"
    local severity="${2:-medium}"
    
    claude -p "Инцидент: $incident_description (Серьезность: $severity)" \
      --append-system-prompt "Вы эксперт SRE. Диагностируйте проблему, оцените воздействие и предоставьте немедленные пункты действий." \
      --output-format json \
      --allowedTools "Bash,Read,WebSearch,mcp__datadog" \
      --mcp-config monitoring-tools.json
}

# Использование
investigate_incident "Payment API возвращает ошибки 500" "high"

Автоматизированная проверка безопасности

# Агент аудита безопасности для pull request'ов
audit_pr() {
    local pr_number="$1"
    
    gh pr diff "$pr_number" | claude -p \
      --append-system-prompt "Вы инженер по безопасности. Проверьте этот PR на уязвимости, небезопасные паттерны и проблемы соответствия требованиям." \
      --output-format json \
      --allowedTools "Read,Grep,WebSearch"
}

# Использование и сохранение в файл
audit_pr 123 > security-report.json

Многооборотный юридический помощник

# Проверка юридических документов с постоянством сессии
session_id=$(claude -p "Начать сессию юридической проверки" --output-format json | jq -r '.session_id')

# Проверить контракт в несколько шагов
claude -p --resume "$session_id" "Проверьте contract.pdf на статьи об ответственности"
claude -p --resume "$session_id" "Проверьте соответствие требованиям GDPR" 
claude -p --resume "$session_id" "Сгенерируйте исполнительное резюме рисков"

Лучшие практики для Python

Ключевые паттерны

import asyncio
from claude_code_sdk import ClaudeSDKClient, ClaudeCodeOptions

# Всегда используйте менеджеры контекста
async with ClaudeSDKClient() as client:
    await client.query("Проанализируйте этот код")
    async for msg in client.receive_response():
        # Обработайте потоковые сообщения
        pass

# Запустите несколько агентов одновременно
async with ClaudeSDKClient() as reviewer, ClaudeSDKClient() as tester:
    await asyncio.gather(
        reviewer.query("Проверьте main.py"),
        tester.query("Напишите тесты для main.py")
    )

# Обработка ошибок
from claude_code_sdk import CLINotFoundError, ProcessError

try:
    async with ClaudeSDKClient() as client:
        # Ваш код здесь
        pass
except CLINotFoundError:
    print("Установите CLI: npm install -g @anthropic-ai/claude-code")
except ProcessError as e:
    print(f"Ошибка процесса: {e}")

# Собрать полный ответ с метаданными
async def get_response(client, prompt):
    await client.query(prompt)
    text = []
    async for msg in client.receive_response():
        if hasattr(msg, 'content'):
            for block in msg.content:
                if hasattr(block, 'text'):
                    text.append(block.text)
        if type(msg).__name__ == "ResultMessage":
            return {'text': ''.join(text), 'cost': msg.total_cost_usd}

Советы для IPython/Jupyter

# В Jupyter используйте await прямо в ячейках
client = ClaudeSDKClient()
await client.connect()
await client.query("Проанализируйте data.csv")
async for msg in client.receive_response():
    print(msg)
await client.disconnect()

# Создайте переиспользуемые вспомогательные функции
async def stream_print(client, prompt):
    await client.query(prompt)
    async for msg in client.receive_response():
        if hasattr(msg, 'content'):
            for block in msg.content:
                if hasattr(block, 'text'):
                    print(block.text, end='', flush=True)

Лучшие практики

  • Используйте формат вывода JSON для программного разбора ответов:

    # Разберите JSON ответ с jq
    result=$(claude -p "Сгенерируйте код" --output-format json)
    code=$(echo "$result" | jq -r '.result')
    cost=$(echo "$result" | jq -r '.cost_usd')
    
  • Обрабатывайте ошибки грациозно - проверяйте коды выхода и stderr:

    if ! claude -p "$prompt" 2>error.log; then
        echo "Произошла ошибка:" >&2
        cat error.log >&2
        exit 1
    fi
    
  • Используйте управление сессиями для поддержания контекста в многооборотных разговорах

  • Учитывайте таймауты для долго выполняющихся операций:

    timeout 300 claude -p "$complex_prompt" || echo "Таймаут через 5 минут"
    
  • Соблюдайте ограничения скорости при выполнении нескольких запросов, добавляя задержки между вызовами

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