Claude Agent SDK: как собрать первого ИИ-агента, который сам чинит файл. Пошагово
Содержание
- Что получится в итоге
- Что понадобится
- Если вы работаете из России
- Что важно знать до старта
- Шаг 1. Делаем точку возврата и пишем план
- Шаг 2. Просим Claude Code написать код и проверяем пакет
- Шаг 3. Читаем код и просим убрать лишнее
- Шаг 4. Ставим Claude Code и входим в аккаунт
- Шаг 5. Ставим Agent SDK
- Шаг 6. Первый агент
- Шаг 7. Если запуск молчит
- Шаг 8. Делаем вывод читаемым
- Шаг 9. Включаем журнал запусков
- Что дальше
Claude Code умеет читать файлы, запускать команды и править код. Но это готовое приложение: вы сидите в терминале и вручную даёте ему задачи. А если нужен агент, который делает такую работу сам, внутри вашей программы, по расписанию или по событию?
Для этого есть Claude Agent SDK, библиотека для Python и TypeScript. По документации, она даёт те же инструменты, цикл работы агента и управление контекстом, что и Claude Code, только ими можно управлять из своего кода. Раньше она называлась Claude Code SDK, потом её переименовали. Из-за этого путается даже сам ИИ: в примере он сначала поставил не тот пакет.
Разберём, как установить SDK, запустить первого агента и настроить рабочее место так, чтобы потом не гадать, что агент сделал.
Что получится в итоге
Короткий скрипт на Python, который ставит агенту задачу: найти и исправить ошибку в файле. Агент сам читает файл, правит его и отчитывается. Дальше вы добавляете читаемый вывод и логи каждого запуска, чтобы разбирать сбои.
Для примера возьмём файл hello_world.rb на языке Ruby с двумя ошибками: неверное имя метода и несовпадающие кавычки. Задача простая специально. На ней видно весь путь, а язык файла для агента не важен.
Что понадобится
- Компьютер с Python 3. В примере это Ubuntu в WSL2 на Windows и редактор VS Code. Для других систем способы установки Claude Code есть в документации.
- Claude Code. В примере он помогает писать код, а вход в его аккаунт используется и для запуска SDK. Установим его в шаге 4.
- Доступ к Claude. В примере вход сделан по подписке Claude Pro. По документации, есть и другой путь: ключ API в переменной окружения
ANTHROPIC_API_KEY. Для рабочих систем обычно берут ключ, а не личную подписку. - Git. Он пригодится как точка возврата перед экспериментами.
Если вы работаете из России
Claude и Claude Code из России напрямую не работают: нужен доступ, который есть не у всех. Сам Agent SDK в примере работает именно с моделями Claude. В журнале запуска виден claude-sonnet-4-6.
Что можно сделать. Если доступа нет, не нужно переписывать подход. Перенесите саму схему: план задачи в файле, один маленький агент, читаемый вывод, журнал каждого запуска. Агента с такой же структурой можно собрать на открытой модели, которая работает на вашем сервере или компьютере, например на Ollama и Python. Тогда ни ключи, ни данные не уходят за границу. Возможности открытых моделей слабее, поэтому начинайте с простых задач.
Что важно знать до старта
- ИИ путает названия. Claude Code сначала создал
requirements.txtс пакетомanthropic, хотя нуженclaude-agent-sdk. Всегда проверяйте, какие пакеты он поставил. - Он делает лишнее. В первой версии кода был ненужный сервер MCP, выдуманные данные вместо настоящего источника и длинные пояснения в выводе. Читайте результат, а не только запускайте.
- Список инструментов не ограничивает агента. В примере в параметре
allowed_toolsуказаны толькоRead,EditиBash, но агент использовал ещё иGlob. По ответу Claude Code, этот параметр не сужает встроенные инструменты, для этого нужны права вsettings.json. Не рассчитывайте, что список вас защитит. - Агент правит настоящие файлы. Перед началом сделайте коммит в git.
- Вывод ИИ тоже нужно проверять. В конце примера ИИ по логам ответил, что правка уже сработала, а файл исправлен. Это противоречило ожиданиям, пока файл не открыли и не увидели, что он действительно уже исправлен. Проверяйте глазами.
- Расход. Каждый запуск стоит денег или лимита подписки. В выводе примера виден итог запуска: 4 хода, 0,0348 доллара и 14 секунд.
Шаг 1. Делаем точку возврата и пишем план
Перед работой создаём репозиторий и первый коммит, чтобы можно было откатиться:
git init && git add . && git commit -m "hello world"
Потом создаём папку stop_reason и в ней файл plan.md. План задачи лучше написать самому, но простыми словами и по пунктам. Так Claude Code получает цель, а не догадывается. Для примера цель сформулирована так:
Показать, как работает stop_reason в Claude Agent SDK. Нужно увидеть stop_reason для вызова инструмента, для конечного результата и то, как добавляются результаты. Пример с инструментом погоды. Пишем на Python. Для форматирования журнала используем нашу библиотеку из папки lib/sdk_parser.

Шаг 2. Просим Claude Code написать код и проверяем пакет
В терминале запускаем claude и даём короткую команду: выполни план из plan.md и положи код в папку stop_reason.
Claude Code работает сам, но требует подтверждений. Пока он трудился, стало видно ошибку: в requirements.txt попал пакет anthropic, а при запуске пришла ошибка ModuleNotFoundError. Нужно было остановить его и поправить. Для этого в окне подтверждения выбираем третий вариант и сразу пишем причину: разве не нужно использовать claude-agent-sdk? Клавиша Tab открывает поле для такой правки.
Заодно добавляем в план раздел с требованиями: использовать именно Claude Agent SDK, Python 3, нашу библиотеку для журнала и только локальный Python без лишних сред.

Шаг 3. Читаем код и просим убрать лишнее
Запускать сразу не стоит. Откройте сгенерированный main.py и прочитайте. В примере код получился такой: настройки клиента, блоки вызова инструмента и результата, а сам инструмент get_weather помечен декоратором @tool. Это функция, которой агент может пользоваться.

В примере нашлось три замечания, и каждое отправляется Claude Code как просьба:
- Выдуманная погода. Данные были зашиты в код. Просим взять открытый API.
- Лишний сервер MCP. Для такого примера он не нужен. Просим сделать проще.
- Пояснения в выводе. Программа сама рассказывала, как она работает. Просим выводить только ключевые значения.
И ещё одно правило: не стоит верить, что ИИ идеально знает собственный SDK. Он знает его примерно. Сверяйтесь с документацией: раздел про инструменты и справочник по API.
Шаг 4. Ставим Claude Code и входим в аккаунт
Если Claude Code ещё не стоит, берём установку из его документации. Для разных систем способы разные: родная установка, Homebrew или winget. Лучше выбирать родную установку: она берёт самую свежую версию, а в других способах версия может оказаться старой и давать странные ошибки API. На Linux и в WSL2 это одна команда из документации. В конце программа сообщает версию. В примере это 2.1.85.

Запускаем claude. Он открывает браузер для входа в аккаунт. Если браузер не открылся, терминал покажет ссылку: открываем её сами, нажимаем «Authorize», копируем код и вставляем обратно в терминал. Если вход не предложили, пишем /login. Проверить, вошли ли вы, можно командой:
claude auth status
Для проверки просим создать пустой файл README.md. Модель в примере была Sonnet, внизу окна её можно поменять.
Шаг 5. Ставим Agent SDK
Открываем страницу Agent SDK в документации. Вверху сразу видно, что Claude Code SDK переименован. Там же короткий пример на Python: запрос, который говорит агенту найти и исправить ошибку в файле, и список разрешённых инструментов. Установка одной командой:
pip install claude-agent-sdk

Заранее было неясно, подхватит ли SDK вход по подписке. В примере подхватил: скрипт запустился при входе через Claude Code. Для разработки это удобно. Для настоящих систем берите ключ API.
Шаг 6. Первый агент
Создаём папку hello_world, в ней main.py, и вставляем пример из документации. Меняем задачу: найти и исправить ошибку в hello_world.rb. Рядом кладём сам файл с двумя ошибками. Агенту разрешены инструменты чтения, правки и командной строки: Read, Edit и Bash.

Список зависимостей тоже можно поручить Claude Code: попросите составить requirements.txt для main.py. В примере в файле оказался один пакет, но проверить стоило.
Шаг 7. Если запуск молчит
Запускаем python main.py, а вывода нет. Причина в том, что агент работает асинхронно. В коде была функция main(), но её никто не вызывал. Решение простое: нужна строка asyncio.run(main()) в конце файла.
Чтобы найти причину, в примере задан вопрос Claude Code: почему запуск ничего не печатает. Он прочитал файл и предложил правку. Выбираем «Yes, allow all edits during this session», если доверяете ему на время сессии.

Шаг 8. Делаем вывод читаемым
После исправления скрипт заработал, но печатал сырые объекты Python. Человеку это читать трудно. Переключаем Claude Code в режим плана, сочетанием Shift+Tab, и просим: сделать вывод понятным и вынести форматирование в отдельную библиотеку.
В режиме плана он ничего не меняет, а сначала показывает план. Читайте его: если хотите хорошего кода, план надо проверять. В примере предложили положить библиотеку внутрь проекта, но нужна она в нескольких папках. Поэтому попросили поместить её в lib в корне и добавить инструкцию по подключению.
В результате появилась папка lib/sdk_parser: файл formatter.py, файл __init__.py и README. А в main.py вместо print(message) теперь print(format_message(message)).

README в библиотеке лучше переименовать в CLAUDE.md. Это файл, который Claude Code читает сам, поэтому ИИ будет знать, как пользоваться вашей библиотекой.
Запускаем снова. Теперь видно ход мысли агента: размышление, вызов поиска файла, чтение, правка и итог. С первого раза агент не нашёл файл, потому что в его названии была опечатка. После исправления имени он нашёл две ошибки: неверный метод и несовпадающие кавычки. Исправил их и показал таблицу «было, стало».

Шаг 9. Включаем журнал запусков
Вывод в терминале пропадает. Поэтому просим дополнить библиотеку: писать журнал в папку logs рядом с проектом, который её использует. Для каждого запуска нужен новый файл с понятной меткой времени в названии.
После запуска в hello_world появляется папка logs. В ней файл вида 2026-03-27T10-59-26.log: сессия, модель, каждый вызов инструмента и результат.

Теперь отладка устроена так. Когда агент работает не так, как ждали, даём Claude Code путь к журналу и описываем проблему: агент должен был править файл, но не правит, проверь журнал. Он видит все шаги и может сказать, где сбой. В примере он ответил, что правка прошла успешно, а файл уже исправлен. Так оно и было.
Что дальше
Теперь у вас есть рабочее место для агентов на SDK: план в файле, код, который можно читать, вывод для человека и журнал для отладки. Следующий шаг: давать агенту свои инструменты, например поиск по вашим документам или запрос к вашей системе. Каждый раз сначала план, потом чтение кода, а не слепой запуск.
Мы в Агентехе учим сотрудников собирать таких агентов под задачи своего отдела, настраивать им права и разбирать сбои по журналам. Как устроено обучение.