В цикле · S1E03 Жизненный цикл агента
Интерфейс агент–компьютер: инструменты, которыми удобно пользоваться
Как описывать инструменты, проектировать схемы и возвращать результаты, чтобы модель меньше угадывала и реже ошибалась.
Когда агент выбирает не тот инструмент или путает аргументы, хочется дописать ещё одно правило в системный промпт. Иногда это помогает. Но часто проблема находится в интерфейсе: названия неоднозначны, схема допускает противоречия, а результат возвращает больше шума, чем полезных данных.
Третий выпуск «В цикле» посвящён ACI — agent–computer interface. Это набор способов, которыми модель наблюдает среду и действует в ней. Для агента он играет такую же практическую роль, какую для человека играют формы, подписи и навигация приложения.
Определение инструмента — часть промпта
Модель обычно не видит реализацию функции. Решение о вызове она принимает по имени, описанию, схеме и доступному контексту. Если инструмент называется process и принимает строку data, модель вынуждена догадываться о смысле обоих.
Хорошее описание отвечает на четыре вопроса: что делает операция, когда она подходит, когда её применять нельзя и что вернётся. Для действий с последствиями нужно прямо описать эффект: создаётся черновик или отправляется письмо, резервируется сумма или проводится платёж.
Полезная проверка — дать интерфейс новому разработчику без доступа к реализации. Если он не может уверенно выбрать функцию и заполнить параметры, модели тоже не хватает информации. Ответы на его вопросы должны стать частью контракта.
Один инструмент: до и после
Учебный пример — поиск заказа в системе поддержки. Слабая версия называется find, принимает произвольный query и обещает «найти данные». Непонятно, ищет ли она по клиенту, номеру заказа или содержимому товаров и в каких пределах разрешён поиск.
Более точный контракт может выглядеть так. Это описание интерфейса, а не готовое определение для конкретного SDK:
{
"name": "orders_get_status",
"description": "Возвращает статус одного заказа текущего пользователя. Не изменяет заказ и не выполняет возврат. Если номер неизвестен, сначала запросите его у пользователя.",
"parameters": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "Номер заказа из обращения, без догадок и подстановок"
}
},
"required": ["order_id"],
"additionalProperties": false
}
}Учётную запись пользователя подставляет сервер из авторизованной сессии. Её не нужно просить у модели. Проверка доступа к заказу тоже остаётся на сервере: слова «текущего пользователя» в описании помогают выбрать инструмент, но не обеспечивают изоляцию данных.
Сделайте ошибочные состояния непредставимыми
Вместо пары флагов turn_on и turn_off, которые можно одновременно выставить в true, используйте одно поле с допустимыми значениями. Вместо даты в произвольной строке задайте ожидаемый формат и валидируйте его кодом. Вместо неизвестного модели внутреннего ID передайте уже известный приложению контекст самостоятельно.
В исходном материале Anthropic приводит пример с путями к файлам: после изменения рабочей директории относительные пути стали причиной ошибок. Требование абсолютного пути убрало неоднозначность. Это пример защиты от ошибочного использования на уровне интерфейса, а не дополнительного уговора модели быть внимательной.
Строгий режим структурированного вывода помогает соблюдать поддерживаемую схему. Однако корректный JSON может содержать неверный номер заказа или недопустимую бизнес-операцию. Проверка схемы, проверка смысла и авторизация — разные уровни.
Выбор инструмента и форма аргументов — разные настройки
Режим выбора инструмента отвечает на вопрос, должна ли модель вообще сделать вызов и какие инструменты доступны на этом шаге. Строгая схема отвечает на вопрос, как должны выглядеть аргументы. Одно не заменяет другое.
Имена режимов и их совместимость зависят от API и модели. Не переносите настройки между провайдерами механически. Проверьте именно используемое сочетание: поддерживается ли принудительный вызов, как ведут себя параллельные вызовы и что происходит при отказе или обрыве генерации.
Иногда задача требует не действия, а только данных заданной формы. Тогда отдельный структурированный ответ проще, чем фиктивный инструмент, который ничего не исполняет. А для больших фрагментов кода может оказаться удобнее свободный текстовый вход с ограничениями, чем код внутри JSON с множеством экранированных символов.
Результат должен помогать следующему решению
Если инструмент возвращает весь объект CRM, контекст заполняется полями, которые агенту не нужны. Лучше вернуть статус, ожидаемую дату доставки и стабильный идентификатор, по которому можно выполнить следующий разрешённый шаг.
При этом сокращение не должно скрывать существенную неопределённость. Если данные устарели, часть источников недоступна или результат неполон, укажите это явно. Пустой массив, отказ в доступе и сбой внешнего API не должны выглядеть одинаково.
Ошибка тоже часть интерфейса. Безопасное объяснение «обязательный номер заказа не указан» даёт возможность исправить запрос. Внутренний stack trace создаёт шум и может раскрывать лишние сведения.
Большой каталог — отдельная архитектурная задача
Определения инструментов занимают контекст и оплачиваются вместе со входом модели. Похожие названия осложняют выбор, даже когда токенов достаточно. Начинайте с небольшого набора под текущую задачу и измеряйте качество при его расширении.
Для больших интеграций полезно постепенное обнаружение: сначала список возможностей, затем полная схема выбранного инструмента, затем вызов. Пространства имён разделяют домены — например, orders_* и billing_*. Они помогают ориентироваться, но сами по себе не ограничивают права.
Не стоит автоматически объединять все операции в одну универсальную функцию. Иногда это уменьшает каталог, но превращает схему в сложный язык команд. Сравнивайте варианты на реальных ошибках: выбор инструмента, заполнение аргументов, число повторов и успешность всей задачи.
Как проводить ревью ACI
- Понятен ли эффект операции без чтения её реализации?
- Различимы ли соседние инструменты и явно ли описаны ограничения?
- Может ли код подставить известные значения вместо модели?
- Отсекает ли схема противоречивые состояния?
- Можно ли по результату понять, что делать дальше?
- Есть ли примеры из трейсов, показывающие улучшение после изменения интерфейса?
Когда интерфейс готов, возникает следующий вопрос: как переиспользовать его в разных AI-приложениях? Этому посвящён разбор Model Context Protocol.
Источники
Статья основана на главе 4 материалов «Жизненный цикл агента» и сценарии S1E03. Конкретные ограничения API проверяйте по документации выбранной модели.
