Шаг 1. Подготовить проект и установить SDK
Создайте отдельную папку для проекта. На Python самый быстрый путь - через uv (менеджер пакетов, который сам управляет виртуальным окружением): команды uv init, затем uv add claude-agent-sdk. Альтернатива - обычный pip: создать виртуальное окружение (python3 -m venv .venv, затем source .venv/bin/activate на macOS и Linux, или py -m venv .venv и .venv\Scripts\Activate.ps1 на Windows), а затем pip install claude-agent-sdk. Важная деталь из документации: оба SDK - и Python, и TypeScript - уже включают в себя нативный бинарник Claude Code, поэтому отдельно устанавливать сам Claude Code в большинстве случаев не требуется.
Шаг 2. Задать API-ключ
API-ключ берётся в Claude Console и передаётся через переменную окружения ANTHROPIC_API_KEY - на macOS и Linux через export ANTHROPIC_API_KEY=ваш-ключ, на Windows в PowerShell через $env:ANTHROPIC_API_KEY = "ваш-ключ". SDK читает ключ из окружения того процесса, который запускает агента, и не подгружает .env-файлы автоматически - если ключ хранится в .env, его нужно загрузить самостоятельно, например через пакет dotenv, до вызова SDK.
Шаг 3. Создать файл с намеренными багами
Официальный пример - функция для подсчёта среднего значения в списке чисел, которая падает на пустом списке (деление на ноль), и функция получения имени пользователя, которая падает, если передать None вместо словаря пользователя. Такой файл создаётся отдельно как учебная цель для будущего агента.
Шаг 4. Написать минимальный код агента
Ядро агента - функция query() из библиотеки. В неё передаётся prompt - задача обычным текстом, например «просмотри файл на баги, которые вызывают падения, и почини найденные проблемы» - и параметр options с двумя ключевыми настройками. allowed_tools - список заранее разрешённых инструментов, например Read, Edit, Glob, чтобы агент их не переспрашивал по одному. permission_mode со значением acceptEdits автоматически подтверждает правки файлов без ручного подтверждения на каждый шаг. Ответ приходит через асинхронный цикл (async for в Python), который стримит сообщения по мере работы модели: рассуждение, конкретный вызов инструмента или итоговый результат.
Шаг 5. Запустить и проверить результат
Агент запускается командой uv run agent.py (или python agent.py при pip-установке). По ходу работы он печатает своё рассуждение и каждый вызываемый инструмент, завершаясь строкой «Done: success». После запуска в исходном файле уже будет защитный код для пустых списков и пустых значений пользователя - агент самостоятельно прочитал файл, проанализировал логику, нашёл граничные случаи, которые вызывали бы падение, и внёс правки.
Как настроить уровень автономности агента
Официальная документация даёт три готовых уровня набора инструментов. Только Read, Glob, Grep - агент способен лишь на анализ кода без права что-либо менять. Read, Edit, Glob - агент может анализировать и редактировать код. Полный набор Read, Edit, Bash, Glob, Grep даёт агенту возможность ещё и выполнять команды в терминале - например, самостоятельно написать юнит-тесты, прогнать их и исправить упавшие. Также можно задать собственный системный промпт через параметр system_prompt, например «Ты - опытный Python-разработчик, всегда следуй стилю PEP 8», чтобы задать конкретный стиль работы агента.