Claude Code SDK - Anthropic

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

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

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

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

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

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

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

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

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

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

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

Установите SDK

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

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

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

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

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

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

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

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

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

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

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

Анализировать промпт, используя возможности рассуждения 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-tool`	MCP инструмент для обработки промптов разрешений (только с `--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, который мы будем использовать для проверки того, предоставляет ли пользователь модели разрешения на вызов данного инструмента. Когда модель вызывает инструмент, происходит следующее:

Сначала мы проверяем настройки разрешений: все файлы settings.json, а также --allowedTools и --disallowedTools, переданные в SDK; если одна из этих настроек разрешает или запрещает вызов инструмента, мы продолжаем с вызовом инструмента
В противном случае мы вызываем инструмент 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 минут"
```
Соблюдайте ограничения скорости при выполнении нескольких запросов, добавляя задержки между вызовами

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

Использование CLI и элементы управления - Полная документация CLI
Интеграция с GitHub Actions - Автоматизируйте ваш рабочий процесс GitHub с Claude
Общие рабочие процессы - Пошаговые руководства для общих случаев использования

Release Notes

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

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

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

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

​Обзор

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

​API ключ Anthropic

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

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

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

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

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

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

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

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

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

​JSON вывод

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Обзор

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

API ключ Anthropic

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

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

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

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

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

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

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

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

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

JSON вывод

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

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

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

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

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

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

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

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

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

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

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

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

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

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