# Что Claude Agent SDK меняет во внутренних инструментах?

> Разбираем, что скрывает Claude Agent SDK, какая инженерная работа остается вашей и как выбрать безопасный первый внутренний инструмент.

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

От этого различия зависит, выпустит ли команда полезный инструмент за две недели или создаст дорогое окно чата, которому никто не доверяет. Считайте SDK средой выполнения возможностей Claude Code, а не готовой платформой внутренних инструментов. Договор между агентом и бизнесом по-прежнему определяете вы.

## SDK скрывает агентный цикл, но не ваш продукт

SDK дает приложению работающий агентный цикл и требует гораздо меньше связующего кода, чем прямая интеграция с моделью. Код может отправить задачу, передавать типизированные сообщения потоком, разрешить Claude вызывать встроенные или пользовательские инструменты, продолжать разговор, прерывать его и возобновлять сессию. В Python функция `query()` подходит для ограниченных задач, входные данные которых известны с самого начала. `ClaudeSDKClient` нужен для интерактивной работы в несколько ходов, когда приложение отправляет дополнительные данные во время активной сессии.

Это намного больше, чем клиент для API. Обычный клиент модели отправляет сообщения и получает содержимое. Без SDK вам пришлось бы писать цикл, который распознает запросы инструментов, вызывает функции, упаковывает результаты, хранит состояние разговора, ограничивает число ходов и передает ход работы. SDK уже понимает протокол Claude Code, а пакет для Python содержит его среду командной строки. В официальном README пакета Python сказано, что по умолчанию используется встроенный инструмент командной строки, а параметр `cli_path` позволяет выбрать другую установку. Такая упаковка убирает отдельный этап настройки, но одновременно требует закреплять и тестировать версию SDK как среду выполнения, а не считать его безобидным набором типов.

Среди доступных возможностей есть операции с файлами, запуск команд оболочки, поиск, доступ к интернету при соответствующей настройке, хуки, сессии, субагенты и подключения через Model Context Protocol. Пользовательские инструменты Python работают внутри процесса как MCP-серверы. Это удобная абстракция: модель видит единый интерфейс инструментов, а приложение открывает через него обычные бизнес-функции. Получение задачи, запрос статуса развертывания и проверка политики выглядят для агента одинаково, хотя за ними стоят совершенно разные системы.

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

Ответственность удобно разделить просто. Оставьте SDK взаимодействие с моделью, протокол инструментов, поток сообщений и механику сессий. Идентификацию, авторизацию, разделение клиентов, бизнес-состояние, постоянный журнал аудита и действия с последствиями держите в коде приложения. Модель может предложить возврат денег по счету. До вызова метода возврата детерминированный сервис должен проверить пользователя, сумму, счет и состояние одобрения.

## Граница абстракции полезна, но остается заметной

SDK экономит время разработки, однако его внутренние детали проявятся при отладке стоимости, задержек, прав доступа и неудачных вызовов инструментов. Учитывайте это заранее и не стройте внутренний API, который изображает каждый запуск агента одним текстовым запросом.

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

Во-вторых, у сессий есть состояние. Повторное использование одного клиента сохраняет активный разговор, возобновление по идентификатору восстанавливает контекст с диска, а ветвление создает новый путь из прежней сессии. Это удобно, но состояние сессии не заменяет бизнес-запись. Решение о релизе должно храниться в системе релизов. Записывайте туда одобренные входные данные и окончательный структурированный результат, а идентификатор сессии SDK оставляйте только как диагностические метаданные. Исчезновение файлов сессии не должно нарушить целостность бизнес-состояния.

В-третьих, названия и схемы инструментов влияют на поведение агента. Расплывчатый инструмент `manage_release` заставляет модель слишком многое додумывать. Отдельные инструменты `get_ci_status`, `list_blocking_reviews` и `propose_release_note` дают более ясный выбор и позволяют назначить разные правила доступа. Хорошее описание объясняет, когда вызывать инструмент, что означают его идентификаторы и как выглядит ошибка. Не пытайтесь уместить весь рабочий процесс в описании одного параметра.

В-четвертых, модель способна выдать уверенный текст при неполных доказательствах. Структурированный вывод упрощает разбор, но корректный объект еще не означает верное решение. Добавьте поля для доказательств и недостающих входных данных, а также явный набор результатов вроде `ready`, `blocked` и `needs_review`. Затем проверьте объект и сопоставьте каждый указанный идентификатор с данными, которые приложение действительно передало.

Команды часто смешивают оркестрацию и политику. Оркестрация отвечает на вопрос: «Какой инструмент вызвать следующим?» Политика отвечает на другой вопрос: «Может ли этот пользователь сейчас выполнить данную операцию над этим ресурсом?» Claude помогает с первым. На второй должен отвечать ваш код. Если спрятать оба решения в промпте, инъекция в промпт или неверно понятая инструкция пересечет границу, которая вообще не должна зависеть от естественного языка.

Для результатов инструментов тоже нужен отдельный договор. Не передавайте модели всю историю задачи, строку базы данных или полный ответ системы мониторинга только потому, что коннектор уже их возвращает. Выберите необходимые поля, ограничьте размер коллекций, обозначьте время и единицы измерения, отличайте «записей нет» от «запрос завершился ошибкой». Модель не исправит неоднозначный пустой массив. Она может принять отсутствие данных за доказательство отсутствия проблемы, а для процесса одобрения это ровно противоположный нужному вывод.

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

Задержка тоже выходит за границу абстракции. Один запуск агента может включать несколько ходов модели и сетевых вызовов, поэтому он не похож на обычную отправку формы. Дайте каждому инструменту срок меньше общего срока задачи. Показывайте простой прогресс на основе настоящих событий, например «читаю сводку тестов» или «жду сервис политик», но не выдумывайте проценты. Если пользовательское действие требует ответа за одну или две секунды, выполните его детерминированным кодом, а агента запускайте до или после.

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

## Права доступа не заменяют изоляцию

Настройки прав в SDK управляют доступностью и одобрением инструментов, но не уменьшают права процесса в операционной системе. Ограниченный набор инструментов необходим. Изоляцию он не создает.

Официальный README пакета Python указывает на различие, которое легко пропустить. `allowed_tools` автоматически одобряет перечисленные инструменты, но не удаляет все остальные из набора. Неперечисленные инструменты проходят по настроенному пути принятия решения о доступе. В текущих версиях SDK также есть параметр `tools` для выбора базового набора, а `disallowed_tools` блокирует конкретные инструменты. Если вы строите инструмент только для чтения, оставьте в `tools` только операции чтения, а затем добавьте политику одобрения как второй уровень контроля. Не считайте, что параметр с успокаивающим названием уже создал нужную границу.

У рабочей директории есть такое же ограничение. Параметр `cwd` направляет агента в проект, но не создает закрытую среду. Инструмент оболочки, запущенный под сервисной учетной записью, получает ее доступ к файлам и сети, если хост, контейнер или операционная система его не ограничивает. То же относится к пользовательскому инструменту внутри процесса: он умеет все, что умеет ваша функция.

Для внутреннего развертывания проведите границу вне процесса модели:

- Запускайте агента под отдельной учетной записью с минимальными правами на файлы и сервисы.
- Монтируйте только нужную для задачи рабочую папку, желательно в виде одноразовой копии.
- Ограничьте исходящий сетевой доступ конкретными сервисами или полностью его отключите.
- Размещайте операции записи за узкими API, которые повторно проверяют права.
- Записывайте имя инструмента, нормализованные входные данные, статус результата, пользователя и идентификатор связи.

Внутри этой границы полезны хуки. Хук `PreToolUse` может отклонить команду оболочки, изменить входные данные инструмента или запросить решение приложения до выполнения. Хук `PostToolUse` может привести журналы к единому виду и проверить результаты. Хуки исполняют детерминированный код вокруг цикла, поэтому правила вроде «никогда не читать папку с секретами» лучше держать в них, чем в промпте. Но сопоставление строки команды с шаблоном остается слабой защитой. У синтаксиса оболочки слишком много равнозначных форм, а будущий инструмент может обойти фильтр, написанный для сегодняшних названий. Сначала удалите опасные возможности, затем применяйте хуки для контекстных проверок и записи доказательств.

Одобрение человеком тоже нужно разместить правильно. Просьба одобрять каждое чтение вызывает усталость, а автоматическое разрешение каждой записи ведет к инцидентам. Запрашивайте подтверждение там, где возникает бизнес-последствие, например при публикации релиза или изменении права пользователя, и показывайте точное предлагаемое изменение вместе с доказательствами. Одобрение непрозрачной фразы «продолжить задачу агента» не означает осознанного согласия.

## Решение о создании или покупке зависит от места принятия решений

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

Популярный совет строить свое решение, потому что первая демонстрация занимает день, ошибочен. Демонстрация измеряет качество промпта и доступ к API. Производственные расходы скрыты в проверках доступа, изменениях коннекторов, тестовых примерах, поддержке пользователей, реакции на инциденты, правилах хранения данных и всех странных входных данных, которые появляются после запуска. SDK снижает стоимость агентного цикла. Остальные обязательства никуда не уходят.

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

Собственная разработка разумна при четырех условиях:

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

Не сводите решение к сравнению цены лицензии с часами разработчика. Сравнивайте стоимость изменений. Поставщик берет на себя изменения внешних API, но может не поддержать ваш особый путь одобрения. Ваша команда быстро меняет собственное поведение, однако ей придется чинить его после изменений SDK, модели, структуры репозитория или внутреннего сервиса. Оцените оба пути на год с учетом проверки безопасности и дежурств.

Есть и промежуточный путь: купить системы учета и построить тонкого агента, который читает их через одобренные API. Агент не должен становиться теневой системой задач или еще одним источником истины. Такой подход сохраняет постоянное состояние в зрелых продуктах и позволяет рассуждать по правилам компании на основе нескольких систем. Для внутреннего инструмента это часто лучший способ применить SDK.

## Первый проект должен иметь узкие последствия

Лучший первый проект выдает полезную рекомендацию на основе данных только для чтения, а решение с последствиями оставляет человеку. Он должен запускаться достаточно часто для накопления обратной связи, явно сообщать о сбоях и иметь уже знакомый сотрудникам ручной запасной путь.

Не начинайте с универсального внутреннего помощника. Его область растет с каждым вопросом, поэтому вы не сможете определить успех, предсказать требования к доступу или собрать представительный набор тестов. Также не начинайте с агента, чья первая обязанность состоит в записи производственных данных. Даже когда каждое действие кажется обратимым, сочетание широких входных данных и полномочий затрудняет оценку.

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

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

Определите успех до написания промпта. Отслеживайте, находит ли проверяющий известные блокеры, ссылается ли каждое утверждение на переданные данные, как часто люди принимают его рекомендацию, сколько длится запуск, сколько он стоит и как часто пользователи его бросают. Одной удовлетворенности пользователей недостаточно. Людям нравятся гладкие сводки, даже если в них пропущен упавший тест. Добавьте в набор оценки неудобные случаи: пропущенный тест, показанный как успешный, исключение из политики с истекшей датой, сгенерированные файлы, которые заполняют большую часть изменений, переименованный сервис и пустой отчет тестов из-за ошибки парсера.

Заранее установите условие удаления. Если за ограниченный пробный период инструмент не экономит достаточно времени проверки или не находит достаточно пропущенных данных, удалите его. Внутренние инструменты с ИИ накапливаются, потому что дополнительные расходы на размещение кажутся небольшими. Настоящая цена состоит из доверия, которое пользователи тратят на проверку ненадежных выводов, и поверхности доступа, которую службе безопасности приходится регулярно пересматривать.

## Соберите проверяющего как ограниченную задачу

Первая версия должна принимать подготовленную директорию и возвращать структурированную рекомендацию. Сбор данных оставьте вне агента. Обычный сервис может получить запрос на изменение, результаты CI и файл политики, удалить секреты, а затем записать временную рабочую папку. Так агент получает стабильный договор входных данных, а тестовые запуски можно воспроизводить.

Минимальный исполнитель на Python может выглядеть так:

```python
import anyio
from pathlib import Path
from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query

PROMPT = """
Review the supplied release packet. Read only files in this workspace.
Return one JSON object with: outcome, blockers, missing_evidence,
and evidence. Every blocker must cite a file path and a short excerpt.
Use outcome needs_review when evidence conflicts or is incomplete.
Do not propose commands and do not modify files.
"""

async def review(packet_dir: str) -> None:
    options = ClaudeAgentOptions(
        cwd=Path(packet_dir),
        tools=["Read", "Glob", "Grep"],
        allowed_tools=["Read", "Glob", "Grep"],
        max_turns=12,
        max_budget_usd=1.00,
        system_prompt="You are a release evidence reviewer.",
    )

    async for message in query(PROMPT, options=options):
        if isinstance(message, ResultMessage):
            print(message.result)
            print({
                "session_id": message.session_id,
                "cost_usd": message.total_cost_usd,
                "turns": message.num_turns,
            })

anyio.run(review, "./release_packet")
```

Ожидаемый бизнес-результат должен быть уже свободного текста:

```json
{
  "outcome": "needs_review",
  "blockers": [
    {
      "rule": "database migration has rollback evidence",
      "evidence": "policy.md:42",
      "reason": "No rollback result appears in ci_summary.json"
    }
  ],
  "missing_evidence": ["rollback test result"],
  "evidence": ["changes.txt:18", "ci_summary.json:7"]
}
```

В рабочей версии используйте структурированный вывод SDK, а не доверяйте `print(message.result)`, затем еще раз проверьте возвращенную схему в приложении. Вторая проверка должна отклонять неизвестные значения результата, несуществующие пути доказательств, цитаты, которых нет в указанных файлах, и ответ о готовности при непустом `missing_evidence`. Такие проверки ловят уверенные ошибки формата без привлечения второй модели для оценки первой.

В примере есть два разных средства контроля, которые команды часто путают. `tools` ограничивает встроенные возможности, показанные агенту. `allowed_tools` разрешает выбранным операциям чтения выполняться без повторного одобрения. Контейнеру и сервисной учетной записи все равно нужны собственные ограничения. Параметр `cwd`, указывающий на `release_packet`, не помешает скомпрометированному процессу читать другие места.

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

## Проверяемый результат лучше умной автономности

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

Для проверки релиза сначала покажите результат, затем блокеры и ссылки на доказательства. Разместите недостающие данные рядом с рекомендацией, а не прячьте их в стенограмме. Укажите версию проверенного пакета и время создания снимка исходных данных. Дайте пользователю открыть указанный локальный материал через приложение, но не позволяйте агенту придумывать ссылки в своем ответе.

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

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

Спроектируйте отмену до запуска. Пользователи закрывают вкладки, развертывания меняются во время проверки, а новый пакет может сделать старый запуск ненужным. Приложение должно отменить сессию SDK, отметить ее запись и отбросить поздний результат. Для действий с последствиями также нужны идемпотентность и сверка, поскольку остановка разговора не всегда останавливает вызов инструмента, уже принятый другим сервисом.

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

## Эксплуатация остается инженерной работой

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

Помещайте запуски в очередь, если они могут длиться дольше обычного запроса. Назначайте каждой задаче идентификатор приложения, а идентификаторы сессий SDK считайте деталями реализации. Ограничивайте параллелизм на клиента или команду, чтобы одно массовое действие не съело весь бюджет. Установите лимит ходов и денег. Денежный предел защищает от одной сбившейся с пути сессии, а дневной бюджет приложения защищает от цикла, который запускает тысячи формально корректных сессий.

Закрепляйте версии пакетов и записывайте их с каждым результатом. Пакет Python содержит определенную версию командной строки Claude Code, а журнал изменений Anthropic отдельно отслеживает обновления пакета и встроенной среды. Читайте этот журнал как примечания к выпуску движка выполнения. До развертывания проверяйте обновления на наборе своих пакетов, особенно поведение прав, типы сообщений, возобновление сессий и разбор результатов инструментов.

К изменениям модели относитесь так же. Новая модель может лучше рассуждать в целом и при этом иначе выбирать инструменты или формулировать ответ, нарушая скрытые предположения. Держите парсеры строгими, промпты явными, а примеры для оценки независимыми от точной формулировки. Развертывайте по группам, сравнивайте категории ошибок и сохраняйте возможность вернуть новые запуски на последнюю проверенную комбинацию.

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

Назначьте ответственность обычными операционными словами. Одна команда владеет приложением, конкретный человек может его приостановить, дежурные видят текущие сбои, а специалисты по безопасности знают, каких классов данных оно касается. Fractional CTO может помочь создать такую модель работы и определить, где Claude Code, Codex, MCP-инструменты или несколько агентов оправдывают свою сложность. Название фреймворка менее важно, чем понятный владелец и измеримый процесс.

## Принимайте решение после измеримого испытания

Двухнедельное испытание должно дать данные для решения «строить, купить или остановиться», а не более красивую демонстрацию. Запустите проверяющего параллельно с существующим процессом на настоящих, но контролируемых пакетах релиза. Оставьте решения людям и сравните находки агента с окончательной записью проверки.

В конце изучите четыре вещи. Находил ли агент значимые блокеры? Придумывал или неверно указывал ли он доказательства? Сократил ли он активное время проверки с учетом перепроверки? Может ли команда эксплуатировать его с приемлемой стоимостью и нагрузкой на поддержку? Разделите результаты по типам пакетов, потому что хорошее среднее способно скрыть полный провал на изменениях базы данных или монорепозиториях.

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

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