8 принципов проектирования инструментов для ИИ-агентов: что мы узнали из архитектуры Claude Code

Anthropic раскрыла внутреннюю архитектуру инструментов Claude Code. Мы разобрали их подход и собрали принципы, которые пригодятся каждому, кто строит системы на базе LLM — от чат-ботов до автономных агентов.

Когда компания проектирует API, она рассчитывает на разработчика: человек прочитает документацию, изучит примеры, при ошибке пойдёт в Stack Overflow. ИИ-агент работает принципиально иначе. Он видит только JSON-схему инструмента, интерпретирует описание — и за один проход принимает решение о вызове. Без возможности загуглить, уточнить или попросить коллегу.

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

Claude Code работает примерно с 20 инструментами. Они делятся на шесть категорий:

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

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

Почему не сделать один универсальный file_tool с параметром «action: read | write | edit»?

Когда модель видит инструмент с множеством режимов, ей нужно принять решение на двух уровнях — выбрать инструмент и выбрать режим внутри него. Каждый дополнительный уровень выбора увеличивает вероятность ошибки.

Есть и прагматичная причина: разные действия несут разный риск. Чтение безопасно. Редактирование может сломать файл. Полная перезапись — ещё опаснее. Разделение позволяет системе применять разные уровни подтверждения.

Команда Anthropic проверила это эмпирически. Когда они попытались объединить план и вопросы пользователю в одном инструменте, модель путалась. Только выделение в отдельный инструмент дало стабильный результат.

Практический вывод: если вы ловите себя на добавлении параметра mode или action_type — скорее всего, перед вами два разных инструмента.

У человека есть README, Swagger, примеры. У ИИ-агента — только поле description в JSON Schema. Это всё, что модель прочитает перед вызовом.

В Claude Code описания параметров работают как инструкции. Они содержат аналогии с знакомыми концепциями (equivalent to '| head -N'), значения по умолчанию и предупреждения о последствиях (large result sets waste context).

Ещё один приём: enum вместо свободного текста. Когда параметр ограничен тремя значениями, агент не может придумать четвёртый. Меньше свободы в типах данных — меньше галлюцинаций.

Контекстное окно модели — конечный ресурс. У Claude — до 200K токенов, но на практике полезная ёмкость меньше. Каждый инструмент в Claude Code учитывает эту экономику:

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

Для бизнеса это значит: инструмент, способный вернуть мегабайт текста без лимита — архитектурный дефект, который напрямую влияет на качество работы агента и стоимость запросов.

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

В Claude Code ошибки работают иначе. Вместо «error: invalid input» агент получает: «строка не найдена — укажите больше контекста или используйте другой метод». Не сигнал о проблеме, а инструкция по её решению.

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

Claude Code делит инструменты на три уровня:

Для каждого уровня — своя политика подтверждения. Деструктивные операции запрещены без явного запроса пользователя. Force push в основную ветку вызывает предупреждение даже при прямом запросе.

Для тех, кто строит агентные системы: если агент может удалить production-базу одним вызовом без подтверждения — это вопрос вероятности, не времени.

Один из самых интересных инструментов Claude Code — Agent. Он запускает отдельного агента с собственным контекстным окном и набором инструментов.

Зачем это нужно? Задача, требующая глубокого погружения — анализ большого файла, поиск по документации — может «съесть» контекст основного агента. Субагент берёт эту задачу на себя и возвращает только результат.

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

Интересный факт: изначально Claude Code строил контекст через RAG — векторную базу, которая индексировала код. Но пассивное получение контекста оказалось менее эффективным, чем активный поиск. RAG заменили на инструменты поиска, и по мере роста способностей моделей этот подход стал работать лучше.

Вот что ИИ-агент принципиально не умеет — и не научится с ростом моделей:

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

Эти 8 принципов — не академическая теория. Они извлечены из системы, которая обрабатывает миллионы агентных сессий, и отражают год итераций команды Anthropic.

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

Claude Code — не единственный способ строить агентные инструменты, но один из немногих публичных примеров, где дизайн-решения можно изучить в деталях.

Подписывайся на Телеграм VibeLab, чтобы наблюдать за тем, как мы строим AI-first компанию.

Напишите нам напрямую · vibelab.ru