Как запустить агента Claude на Python: установка claude-agent-sdk 0.2.176 со встроенным Claude CLI 2.1.316

Пошаговое руководство по установке пакета из PyPI, настройке системных требований и запуску первого автономного агента со встроенным CLI.

Компания Anthropic 31 октября 2026 года опубликовала релиз библиотеки claude-agent-sdk 0.2.176 для Python. Пакет размещен в каталоге PyPI под лицензией MIT. Главное отличие этой библиотеки от стандартного клиента anthropic заключается в наличии готового контура Claude Code. В дистрибутив пакета упакован бинарный движок Claude CLI версии 2.1.316, благодаря чему для запуска агента не требуется предварительно настраивать среду Node.js или вручную поднимать фоновый процесс интерфейса командной строки.

Страница релиза v0.2.176 в репозитории anthropics/claude-agent-sdk-python на GitHub. Источник: Anthropic

Базовый клиент anthropic выполняет единичные синхронные или асинхронные запросы к языковой модели. Разработку цикла рассуждений, вызовы инструментов, сохранение состояния и обработку ошибок разработчик реализует вручную.
Пакет claude-agent-sdk запускает автономный агентный цикл на базе Claude Code. Модель самостоятельно формирует шаги, вызывает утилиты операционной системы, считывает контекст файлов, проверяет промежуточный результат и завершает сессию при достижении цели.
Исполняемый файл Claude CLI 2.1.316 встроен непосредственно в платформенные архивы wheel для Linux, macOS и Windows. Python управляет этим процессом через внутренний протокол взаимодействия.
Репозиторий проекта anthropics/claude-agent-sdk-python на GitHub на 2 ноября 2026 года насчитывает 8409 звёзд и 1390 форков при 610 открытых обращениях issues.

Для работы библиотеки требуется интерпретатор Python версии 3.10 или новее. В число базовых зависимостей входят библиотека асинхронного ввода-вывода anyio версии 4.0.0+, протокол взаимодействия с инструментами mcp в диапазоне от 1.23.0 до 3.0.0, а также валидатор jsonschema 4.20.0+. Дополнительно для отправки запросов к языковым моделям Claude необходим ключ Anthropic API Console.

Перед началом работы ключ задается в переменной окружения операционной системы:

export ANTHROPIC_API_KEY="sk-ant-api03-..."

Установка пакета с точной фиксацией версии 0.2.176 выполняется штатным менеджером pip:

pip install claude-agent-sdk==0.2.176

При установке колеса wheel пакет распаковывает бинарник Claude CLI в изолированную директорию внутри окружения Python, поэтому ставить глобальный пакет claude через npm не требуется.

Для разовых задач в библиотеке предусмотрена высокоуровневая функция query. Она возвращает асинхронный генератор событий. Текстовые ответы модели приходят в виде объектов AssistantMessage, содержащих блоки TextBlock:

import anyio from claude_agent_sdk import AssistantMessage, TextBlock, query async def main(): async for message in query(prompt="Назови три закона робототехники в одном предложении."): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, TextBlock): print(block.text) if __name__ == "__main__": anyio.run(main)

При выполнении скрипта библиотека запускает встроенный бинарник CLI, передает текстовую инструкцию и передает структурированный поток сообщений обратно в Python.

Параметры выполнения передаются через конфигурационный класс ClaudeAgentOptions. Через поле system_prompt задаются инструкции по поведению модели, а поле max_turns определяет максимальное число итераций агента:

import anyio from claude_agent_sdk import AssistantMessage, ClaudeAgentOptions, TextBlock, query async def main(): options = ClaudeAgentOptions( system_prompt="Отвечай кратко и строго техническим языком.", max_turns=1, ) async for message in query( prompt="Что делает Claude Code CLI?", options=options, ): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, TextBlock): print(block.text) if __name__ == "__main__": anyio.run(main)

Главная особенность автономных агентов заключается в работе с окружением и файлами проекта. Встроенный Claude CLI поддерживает инструменты Read, Write, Edit и Bash. Для автоматического выполнения без интерактивного подтверждения права тулов перечисляются в списке allowed_tools:

import anyio from claude_agent_sdk import AssistantMessage, ClaudeAgentOptions, ResultMessage, TextBlock, query async def main(): options = ClaudeAgentOptions( allowed_tools=["Read", "Write"], system_prompt="Генератор файлов конфигурации проекта.", ) prompt = "Создай файл config.json с параметрами debug=False и port=8080." async for message in query(prompt=prompt, options=options): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, TextBlock): print(block.text) elif isinstance(message, ResultMessage) and message.total_cost_usd > 0: print(f"Расход: ${message.total_cost_usd:.4f}") if __name__ == "__main__": anyio.run(main)

Объект ResultMessage завершает сессию и передает итоговую статистику, включая затраты на вызовы API в долларах США через атрибут total_cost_usd.

Когда требуется поддерживать непрерывный диалог с агентом и отправлять серии связанных команд с сохранением состояния, применяется клиент ClaudeSDKClient:

import anyio from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient async def main(): options = ClaudeAgentOptions(allowed_tools=["Read"]) async with ClaudeSDKClient(options=options) as client: await client.query("Прочитай README.md и выдели главную цель библиотеки.") async for msg in client.receive_response(): print(msg) if __name__ == "__main__": anyio.run(main)

Библиотека развивается на основе проекта Claude Code SDK. При переходе к ветке 0.1.0 разработчики объединили параметры системного промпта и ввели строгую изоляцию пользовательских настроек.
Для выполнения терминальных команд агенту требуется инструмент Bash. Если инструмент не включен в allowed_tools, исполнение прерывается до подтверждения прав пользователем.
При развертывании в контейнерах Docker без графического окружения необходимо обеспечить права записи в рабочий каталог проекта.
Официальная документация по архитектуре агентных SDK опубликована в разделе документации Anthropic.
В сентябре 2026 года в нашем блоге на vc.ru разбиралось масштабное обновление SDK с режимом autoMode и аннотациями.