Как начать пользоваться Claude Agent SDK: фреймворк для создания AI-агентов

Claude Agent SDK - это открытая библиотека от Anthropic, которая позволяет разработчикам создавать автономных AI-агентов на Python и TypeScript. Агент, построенный на этом фреймворке, способен самостоятельно читать файлы, запускать терминальные команды, искать информацию в сети, редактировать код и выполнять длинные многошаговые задачи без участия человека на каждом шаге.

Важно сразу понять разницу между Claude Agent SDK и Claude Code, потому что это два разных продукта с разной целевой аудиторией. Claude Code - это готовый инструмент командной строки, который разработчик запускает в своём терминале и сразу начинает работать с кодом. Claude Agent SDK - это строительные блоки, из которых разработчик собирает собственного агента под конкретную задачу: автоматизацию тестирования, генерацию документации, анализ кодовой базы компании или полностью кастомный рабочий процесс с уникальной логикой.

SDK предоставляет тот же агентный цикл и набор инструментов, которые лежат в основе самого Claude Code. Это означает, что разработчик получает проверенную в производстве архитектуру, а не экспериментальный фреймворк, собранный на коленке. SDK был переименован из Claude Code SDK в сентябре 2025 года, когда Anthropic выделила его в самостоятельный продукт с отдельной документацией и поддержкой.

Поисковый интерес к Claude Agent SDK вырос с 50 запросов в месяц в мае 2025 года до 14 800 запросов в апреле 2026 года - рост в 296 раз за год. Это говорит о том, что инструмент стал стандартом для разработчиков, которые хотят строить агентные системы на базе моделей Anthropic.

Кому подойдёт этот инструмент: разработчикам и командам, которые хотят автоматизировать повторяющиеся задачи в своих проектах; инженерам, создающим AI-приложения поверх моделей Anthropic; командам DevOps, которым нужны агенты для мониторинга и реагирования на инциденты; всем, кто строит многоагентные системы, где несколько Claude-агентов взаимодействуют между собой для решения сложных задач. Для работы потребуются базовые знания Python или TypeScript и понимание принципов работы с API.

Первый шаг - создать аккаунт разработчика на console.anthropic.com и получить API-ключ. Перейдите в раздел API Keys в левом меню, нажмите кнопку Create Key, дайте ключу понятное название (например, my-agent-project), скопируйте ключ и сохраните его в надёжном месте: повторно он показан не будет. Новые аккаунты получают небольшой стартовый кредит для тестирования возможностей.

Установите API-ключ как переменную окружения. В macOS и Linux это делается одной командой в терминале: export ANTHROPIC_API_KEY=ваш_ключ. Чтобы ключ сохранялся между сессиями и не нужно было вводить его каждый раз, добавьте эту строку в файл ~/.zshrc или ~/.bashrc. На Windows используйте диалог переменных среды или команду setx в командной строке, запущенной от имени администратора.

Никогда не записывайте API-ключ прямо в код вашего проекта и не публикуйте его в репозитории на GitHub. Anthropic автоматически сканирует публичные репозитории и отзывает скомпрометированные ключи. Используйте файлы .env совместно с библиотекой python-dotenv или аналогами для безопасного хранения.

Для Python потребуется версия 3.10 или выше. Рекомендуется создать виртуальное окружение, чтобы изолировать зависимости проекта: python -m venv venv, затем source venv/bin/activate (на Windows: venv\Scripts\activate). После активации окружения установите библиотеку: pip install claude-agent-sdk. Для удобства добавьте зависимость в requirements.txt вашего проекта.

Для TypeScript и Node.js нужна версия Node.js 18 или выше. Создайте новую папку проекта, инициализируйте npm и установите пакет: mkdir my-agent && cd my-agent && npm init -y && npm install @anthropic-ai/claude-agent-sdk. Если вы используете TypeScript, дополнительно установите npm install -D typescript ts-node @types/node.

Для проверки успешной установки Python-версии запустите: python -c "import claude_agent_sdk; print('Установка успешна')". Вы должны увидеть сообщение без ошибок. Для Node.js проверка аналогична: node -e "require('@anthropic-ai/claude-agent-sdk'); console.log('OK')".

Самый простой способ начать - запустить агента с конкретной небольшой задачей. Создайте файл agent_example.py. Импортируйте asyncio и из claude_agent_sdk функции query и ClaudeAgentOptions. В асинхронной функции main создайте объект options с параметром allowed_tools равным списку инструментов Read, Bash и Grep, затем итерируйтесь по генератору query с нужным промптом. Запустите asyncio.run(main()) в конце файла.

Запустите скрипт командой python agent_example.py. Агент сам разберётся, как выполнить поставленную задачу: найдёт файлы через инструмент Glob, прочитает их содержимое и обработает данные через Bash или Grep. Вы увидите пошаговый процесс работы агента прямо в терминале - каждый вызов инструмента будет виден в режиме реального времени.

Попробуйте усложнить задачу: попросите агента найти все функции без документации в вашем проекте и предложить шаблоны docstring для каждой. SDK поддерживает потоковый вывод, поэтому вы будете видеть результат по мере работы агента, не дожидаясь итогового ответа. Это особенно ценно для длинных задач, занимающих несколько минут.

Полезно начать с режима интерактивного подтверждения: установите allowed_tools в пустой список и задайте параметр permission_mode равным interactive. В этом режиме агент будет запрашивать разрешение перед каждым действием, которое затрагивает файловую систему или выполняет команды. Так вы сможете увидеть логику работы агента и убедиться, что он действует именно так, как вы задумали.

Хорошие стартовые задачи для первого агента: анализ кодовой базы на предмет устаревших зависимостей, автоматическое написание тестов для существующих функций, генерация changelog из git-истории проекта, или проверка соответствия кода корпоративному стайлгайду. Все эти задачи имеют чёткий результат и не требуют внешних API, поэтому идеальны для знакомства с SDK.

Встроенные инструменты - главное преимущество SDK по сравнению с написанием агентов вручную через базовый Anthropic API. Агент получает доступ к набору инструментов без написания дополнительного кода: Read (чтение файлов с поддержкой разных кодировок), Write (создание и перезапись файлов), Edit (редактирование с поиском и заменой конкретных строк), Bash (выполнение любых терминальных команд), Glob (поиск файлов по паттерну типа **/*.py) и Grep (поиск по содержимому с поддержкой регулярных выражений). Можно разрешить агенту использовать все инструменты или ограничить список для большей безопасности в конкретном сценарии.

Субагенты - механизм для создания многоагентных систем любой сложности. Родительский агент может запускать дочерних агентов для параллельного или последовательного выполнения подзадач. Каждый субагент работает в своём изолированном контексте и возвращает результат родителю. Это позволяет строить сложные рабочие процессы: один агент-координатор управляет общим процессом, другие специализируются на конкретных задачах - тестировании, документировании, развёртывании.

Персистентные сессии позволяют агенту помнить предыдущие взаимодействия в рамках одного проекта. Если задача прерывается из-за ошибки, сетевого сбоя или была намеренно остановлена, можно продолжить ту же сессию, не теряя контекст наработанных шагов. Это критично для длинных задач разработки, которые могут занимать часы или даже дни.

Поддержка MCP (Model Context Protocol) открывает доступ к внешним источникам данных и инструментам без написания кода интеграции с нуля. Агент может подключиться к MCP-серверу базы данных и работать с ней напрямую, к серверу корпоративной Wiki, к системам управления задачами или к API сторонних сервисов. Экосистема готовых MCP-серверов активно растёт, и в большинстве случаев нужная интеграция уже существует.

Режимы прав доступа дают гибкий контроль над тем, что агент может делать без явного разрешения. Default - агент запрашивает подтверждение на потенциально опасные действия. AcceptEdits - автоматически разрешает редактирование файлов. BypassPermissions - полная автономия без каких-либо подтверждений. Последний режим используйте только в изолированных окружениях: контейнерах Docker, виртуальных машинах или специально подготовленных sandbox-окружениях.

Кастомные системные промпты позволяют задать агенту конкретную роль, ограничения поведения и формат вывода. Можно создать агента-ревьюера кода, который всегда следует внутреннему стайлгайду компании; агента-тестировщика, который никогда не изменяет продуктовый код без явного указания; или агента-онбордера, который помогает новым разработчикам разобраться в кодовой базе.

Claude Agent SDK как программная библиотека распространяется бесплатно и является открытым исходным кодом на GitHub. Вы платите только за токены при использовании Anthropic API. На момент написания стоимость работы с Claude Sonnet 4.6 (рекомендуемая модель для большинства агентных задач из-за баланса цены и возможностей) составляла несколько долларов за миллион токенов. Claude Opus 4.8 значительно дороже, но существенно мощнее для особо сложных задач, требующих глубокого рассуждения.

Агентные задачи потребляют токены активнее, чем обычные диалоги. Это происходит потому, что на каждом шаге агент отправляет в контексте всю историю предыдущих действий и результатов инструментов. Задача, которая занимает 50 шагов, может потребить в 10-20 раз больше токенов, чем одиночный запрос с тем же вопросом. Начинайте с небольших задач и отслеживайте расход токенов в разделе Usage на console.anthropic.com перед запуском длинных агентных сессий.

Существуют ограничения на количество запросов в минуту (rate limits), которые зависят от уровня вашего аккаунта и типа использования. Новые аккаунты с бесплатным стартовым кредитом имеют самые строгие лимиты. Для серьёзного продуктового использования потребуется пополнить баланс, что автоматически повышает лимиты. Enterprise-клиенты Anthropic получают выделенные лимиты по отдельному договору.

Ограничение по длине контекста определяется выбранной моделью. Claude Sonnet 4.6 поддерживает до 200 тысяч токенов в одном запросе. Для агентов с длинными задачами это означает, что история действий может достичь предела контекстного окна. SDK включает автоматическое управление компактизацией контекста, но опытные разработчики рекомендуют проектировать агентов так, чтобы они сохраняли промежуточные результаты в файлы, а не держали всё в памяти.

Да, VPN необходим для регистрации и пополнения баланса. Anthropic официально не работает с российскими банковскими картами и ограничивает регистрацию с российских IP-адресов на console.anthropic.com. Это стандартное ограничение, связанное с санкционной политикой западных технологических компаний.

Для создания аккаунта используйте VPN с сервером в США, западной Европе или Сингапуре. Большинство российских пользователей успешно регистрируются через серверы в Нидерландах, Германии или Польше. После успешной регистрации работа с API в большинстве случаев не требует VPN: API-запросы к api.anthropic.com проходят без блокировок с большинства российских IP-адресов.

Для оплаты наиболее распространённые решения: зарубежные карты (карты армянских, казахстанских или грузинских банков), виртуальные карты через специализированные сервисы, оплата через корпоративные аккаунты зарубежных юридических лиц. Некоторые разработчики используют криптовалюту через посреднические сервисы.

Установка самой библиотеки не требует VPN: PyPI (pip install) и npm доступны в России без ограничений. Также без VPN работает просмотр официальной документации на docs.anthropic.com и чтение кода SDK на GitHub. Ограничения касаются исключительно регистрации аккаунта разработчика и проведения платежей через веб-интерфейс.

Этот материал подготовлен командой AI-агентов AravanaAI и проверен главным редактором.