Claude Code SDK
Создавайте пользовательских ИИ-агентов с помощью Claude Code SDK
Зачем использовать Claude Code SDK?
Claude Code SDK предоставляет все строительные блоки, необходимые для создания готовых к производству агентов:
- Оптимизированная интеграция с Claude: Автоматическое кэширование промптов и оптимизация производительности
- Богатая экосистема инструментов: Файловые операции, выполнение кода, веб-поиск и расширяемость MCP
- Расширенные разрешения: Детальный контроль над возможностями агентов
- Основы для производства: Встроенная обработка ошибок, управление сессиями и мониторинг
Что можно создать с помощью SDK?
Вот несколько примеров типов агентов, которых вы можете создать:
Агенты для кодирования:
- SRE агенты, которые диагностируют и исправляют проблемы в производстве
- Боты для проверки безопасности, которые аудируют код на уязвимости
- Помощники дежурных инженеров, которые сортируют инциденты
- Агенты для проверки кода, которые обеспечивают соблюдение стиля и лучших практик
Бизнес-агенты:
- Юридические помощники, которые проверяют контракты и соответствие требованиям
- Финансовые консультанты, которые анализируют отчеты и прогнозы
- Агенты службы поддержки клиентов, которые решают технические проблемы
- Помощники по созданию контента для маркетинговых команд
SDK в настоящее время доступен в TypeScript и Python, с интерфейсом командной строки (CLI) для быстрого прототипирования.
Быстрый старт
Запустите своего первого агента менее чем за 5 минут:
Установите SDK
Установите @anthropic-ai/claude-code
из NPM:
Установите @anthropic-ai/claude-code
из NPM:
Установите @anthropic-ai/claude-code
из NPM:
Установите claude-code-sdk
из PyPI и @anthropic-ai/claude-code
из NPM:
(Опционально) Установите IPython для интерактивной разработки:
Установите ваш API ключ
Получите ваш API ключ из Anthropic Console и установите переменную окружения ANTHROPIC_API_KEY
:
Создайте своего первого агента
Создайте одного из этих примеров агентов:
Запустите агента
Скопируйте и вставьте команду выше прямо в ваш терминал.
Скопируйте и вставьте команду выше прямо в ваш терминал.
- Настройте проект:
-
Добавьте
"type": "module"
в ваш package.json -
Сохраните код выше как
legal-agent.ts
, затем запустите:
Сохраните код выше как legal-agent.py
, затем запустите:
Для IPython/Jupyter notebooks, вы можете запустить код прямо в ячейке:
Каждый пример выше создает работающего агента, который будет:
- Анализировать промпт, используя возможности рассуждения Claude
- Планировать многошаговый подход к решению проблемы
- Выполнять действия, используя инструменты, такие как файловые операции, bash команды и веб-поиск
- Предоставлять практические рекомендации на основе анализа
Основное использование
Обзор
Claude Code SDK позволяет вам взаимодействовать с Claude Code в неинтерактивном режиме из ваших приложений.
Предварительные требования
- Node.js 18+
@anthropic-ai/claude-code
из NPM
Основное использование
Основной интерфейс командной строки для Claude Code - это команда claude
. Используйте флаг --print
(или -p
) для запуска в неинтерактивном режиме и печати окончательного результата:
Конфигурация
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.
Предварительные требования
- Node.js 18+
@anthropic-ai/claude-code
из NPM
Основное использование
Основной интерфейс командной строки для Claude Code - это команда claude
. Используйте флаг --print
(или -p
) для запуска в неинтерактивном режиме и печати окончательного результата:
Конфигурация
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.
Предварительные требования
- Node.js 18+
@anthropic-ai/claude-code
из NPM
Чтобы просмотреть исходный код TypeScript SDK, посетите страницу @anthropic-ai/claude-code
на NPM.
Основное использование
Основной интерфейс через TypeScript SDK - это функция query
, которая возвращает асинхронный итератор, который передает сообщения по мере их поступления:
Конфигурация
TypeScript SDK принимает все аргументы, поддерживаемые командной строкой, а также следующие дополнительные опции:
Аргумент | Описание | По умолчанию |
---|---|---|
abortController | Контроллер прерывания | new AbortController() |
cwd | Текущий рабочий каталог | process.cwd() |
executable | Какую среду выполнения JavaScript использовать | node при запуске с Node.js, bun при запуске с Bun |
executableArgs | Аргументы для передачи исполняемому файлу | [] |
pathToClaudeCodeExecutable | Путь к исполняемому файлу Claude Code | Исполняемый файл, который поставляется с @anthropic-ai/claude-code |
permissionMode | Режим разрешений для сессии | "default" (опции: "default" , "acceptEdits" , "plan" , "bypassPermissions" ) |
Предварительные требования
- Python 3.10+
claude-code-sdk
из PyPI- Node.js 18+
@anthropic-ai/claude-code
из NPM
Чтобы просмотреть исходный код Python SDK, смотрите репозиторий claude-code-sdk
.
Для интерактивной разработки используйте IPython: pip install ipython
Основное использование
Python SDK предоставляет два основных интерфейса:
- Класс
ClaudeSDKClient
(Рекомендуется)
Лучше всего подходит для потоковых ответов, многооборотных разговоров и интерактивных приложений:
SDK также поддерживает передачу структурированных сообщений и входных изображений:
Примеры Python на этой странице используют asyncio
, но вы также можете использовать anyio
.
- Функция
query
Для простых одноразовых запросов:
Конфигурация
Поскольку Python SDK принимает все аргументы, поддерживаемые командной строкой через класс ClaudeCodeOptions
.
Аутентификация
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 анализировать код без внесения изменений, полезен для проверки кода и планирования изменений.
Режим планирования ограничивает редактирование, создание файлов и выполнение команд. Смотрите режимы разрешений для деталей.
Пользовательские системные промпты
Системные промпты определяют роль, экспертизу и поведение вашего агента. Здесь вы указываете, какого типа агента вы создаете:
Расширенное использование
Пользовательские инструменты через MCP
Model Context Protocol (MCP) позволяет вам предоставлять вашим агентам пользовательские инструменты и возможности. Это критически важно для создания специализированных агентов, которым нужны доменно-специфичные интеграции.
Примеры конфигураций инструментов агентов:
Примеры использования:
При использовании инструментов MCP вы должны явно разрешить их, используя флаг --allowedTools
. Имена инструментов MCP следуют шаблону mcp__<serverName>__<toolName>
, где:
serverName
- это ключ из вашего файла конфигурации MCPtoolName
- это конкретный инструмент, предоставляемый этим сервером
Эта мера безопасности гарантирует, что инструменты MCP используются только при явном разрешении.
Если вы указываете только имя сервера (т.е., mcp__<serverName>
), все инструменты с этого сервера будут разрешены.
Шаблоны glob (например, mcp__go*
) не поддерживаются.
Пользовательский инструмент промпта разрешений
Опционально используйте --permission-prompt-tool
для передачи инструмента MCP, который мы будем использовать для проверки того, предоставляет ли пользователь модели разрешения на вызов данного инструмента. Когда модель вызывает инструмент, происходит следующее:
- Сначала мы проверяем настройки разрешений: все файлы settings.json, а также
--allowedTools
и--disallowedTools
, переданные в SDK; если одна из этих настроек разрешает или запрещает вызов инструмента, мы продолжаем с вызовом инструмента - В противном случае мы вызываем инструмент MCP, который вы предоставили в
--permission-prompt-tool
Инструмент MCP --permission-prompt-tool
получает имя инструмента и входные данные, и должен вернуть JSON-строковую полезную нагрузку с результатом. Полезная нагрузка должна быть одной из:
Примеры реализации:
Примечания по использованию:
- Используйте
updatedInput
, чтобы сказать модели, что промпт разрешений изменил ее входные данные; в противном случае установитеupdatedInput
на оригинальные входные данные, как в примере выше. Например, если инструмент показывает пользователю diff редактирования файла и позволяет ему редактировать diff вручную, инструмент промпта разрешений должен вернуть этот обновленный diff. - Полезная нагрузка должна быть JSON-строковой
Форматы вывода
SDK поддерживает несколько форматов вывода:
Текстовый вывод (по умолчанию)
JSON вывод
Возвращает структурированные данные, включая метаданные:
Формат ответа:
Потоковый JSON вывод
Передает каждое сообщение по мере его получения:
Каждый разговор начинается с начального системного сообщения init
, за которым следует список сообщений пользователя и помощника, за которым следует финальное системное сообщение result
со статистикой. Каждое сообщение выдается как отдельный JSON объект.
Схема сообщений
Сообщения, возвращаемые из JSON API, строго типизированы согласно следующей схеме:
Мы скоро опубликуем эти типы в JSONSchema-совместимом формате. Мы используем семантическое версионирование для основного пакета Claude Code для сообщения о критических изменениях в этом формате.
Типы Message
и MessageParam
доступны в Anthropic SDK. Например, смотрите Anthropic TypeScript и Python SDK.
Форматы ввода
SDK поддерживает несколько форматов ввода:
Текстовый ввод (по умолчанию)
Потоковый JSON ввод
Поток сообщений, предоставляемый через stdin
, где каждое сообщение представляет оборот пользователя. Это позволяет несколько оборотов разговора без перезапуска бинарного файла claude
и позволяет предоставлять руководство модели во время обработки запроса.
Каждое сообщение является JSON объектом ‘Сообщение пользователя’, следующим тому же формату, что и схема выходных сообщений. Сообщения форматируются с использованием формата jsonl, где каждая строка ввода является полным JSON объектом. Потоковый JSON ввод требует -p
и --output-format stream-json
.
В настоящее время это ограничено только текстовыми сообщениями пользователя.
Примеры интеграции агентов
Бот реагирования на инциденты SRE
Автоматизированная проверка безопасности
Многооборотный юридический помощник
Лучшие практики для Python
Ключевые паттерны
Советы для IPython/Jupyter
Лучшие практики
-
Используйте формат вывода JSON для программного разбора ответов:
-
Обрабатывайте ошибки грациозно - проверяйте коды выхода и stderr:
-
Используйте управление сессиями для поддержания контекста в многооборотных разговорах
-
Учитывайте таймауты для долго выполняющихся операций:
-
Соблюдайте ограничения скорости при выполнении нескольких запросов, добавляя задержки между вызовами
Связанные ресурсы
- Использование CLI и элементы управления - Полная документация CLI
- Интеграция с GitHub Actions - Автоматизируйте ваш рабочий процесс GitHub с Claude
- Общие рабочие процессы - Пошаговые руководства для общих случаев использования