Закономерность в недавних инцидентах
Когда агент делает то, что он никогда не должен был делать, в постмортеме обычно называют модель. Отчёты об инцидентах более конкретны. Агент вызывает эндпоинт, который никогда не был частью его задачи, повторяет мутацию, потому что ответ не дал ему ничего другого, или перечисляет коллекцию, потому что API сделал перечисление дешёвым и недокументированным. Это не ошибки рассуждения. Это ошибки интерфейса.
Три формы повторяются. Первая — охват: агент затрагивает ресурс, который технически был достижим, но находился за пределами его мандата. Поверхность инструментов предоставила широкий глагол, и агент им воспользовался. Вторая — поведение при повторных попытках: против интерфейсов без семантики ограничения скорости агент, получивший неоднозначную ошибку, будет повторять попытку, часто агрессивно, потому что ничто в ответе не говорит ему, что повторять бессмысленно или неправильно. Третья — перечисление: разрешающий эндпоинт списка без контракта пагинации и без границы области видимости читается агентом как приглашение обойти всю коллекцию.
Почему инструменты, созданные для людей, не подходят агентам
API, ориентированные на людей, терпят неоднозначность, потому что человек обеспечивает вокруг них намерение и сдержанность. Человек, читающий разрешающий эндпоинт, понимает из контекста и соглашений, что DELETE /items — это не приглашение удалить всё. Он знает, какие параметры на практике необязательны, какие ошибки временны и какие глаголы существуют только по историческим причинам. Ничего из этого знания нет в интерфейсе. Оно в человеке.
Агент читает поверхность буквально. Каждый глагол — кандидат на действие. Каждый необязательный параметр — точка принятия решения. Недокументированное поведение для машины не мягкий край; это неисследованный путь. Там, где человек видит шероховатый угол и объезжает его, агент видит ветвление и может пойти по нему.
Это и есть основная асимметрия. Человеческие интерфейсы прощают, потому что человек и есть guardrail. Интерфейсы для агентов не могут этого предполагать. Сама поверхность должна нести ограничения, которые человек иначе обеспечил бы из опыта. Когда она этого не делает, агент не безрассуден; он последователен в отношении того, что ему дали.
Guardrails, размещённые вокруг широкой поверхности, этого не исправляют. Они перехватывают одни вызовы и пропускают другие, и они добавляют слой политик, который агент не видит. Агент по-прежнему рассуждает над исходной поверхностью. Коррекция приходит после решения, а не до него.
Проектирование поверхности инструментов для агента
Поверхность инструментов для агентов должна быть узкой, явной и самоописывающей. Три свойства делают основную работу.
Один глагол на намерение, с обязательными параметрами
Сверните широкие глаголы в глаголы, специфичные для намерения. Вместо общего update, принимающего произвольные поля, предоставьте set_delivery_address с обязательным адресом и обязательным идентификатором заказа. Вместо list предоставьте list_open_orders_for_customer с обязательным идентификатором клиента и обязательным фильтром состояния. Набор параметров — не предложение; это намерение, записанное явно.
Это меняет то, что агент может выразить. Общий глагол с необязательными полями оставляет намерение неявным, и агент, заполняющий необязательные поля, угадывает. Узкий глагол с обязательными параметрами отказывает безопасно: если агент не может предоставить идентификатор клиента, он не может выполнить вызов, и отказ читаем, а не безмолвен.
Жёсткие ограничения, выраженные в интерфейсе
Ограничения скорости и области видимости принадлежат определению инструмента, а не документу политики, который агент никогда не читает. Если инструмент может быть вызван не более ограниченного числа раз за окно, скажите это в схеме и обеспечьте соблюдение на границе. Если коллекция может быть прочитана не более одной страницы за раз, сделайте пагинацию обязательной, а размер страницы — обязательным параметром с ограниченным диапазоном.
Механизм важнее формулировки. Ограничение скорости, обеспеченное на границе инструмента, возвращает структурированный сигнал, на который агент может действовать. Ограничение скорости, обеспеченное где-то ниже по потоку, возвращает непрозрачный отказ, который агент будет повторять. Одно и то же ограничение, размещённое по-разному, даёт противоположное поведение.
С
Ошибка должна говорить агенту, что он может сделать дальше, а не только что не удалось. Голый 403 приглашает к повторным попыткам и зондированию. Структурированная ошибка, которая сообщает, что действие не разрешено для данного принципала, называет разрешённую альтернативу и указывает, является ли условие постоянным, даёт агенту путь, не требующий угадывания.
{
"error": "scope_denied",
"message": "This principal may not modify billing details.",
"permitted": ["read_billing_summary"],
"retryable": false,
"next": "request_billing_change_approval"
}
Одно только поле retryable устраняет большой класс агрессивных циклов повторных попыток. Список permitted сужает следующий шаг агента, не требуя от него выводить границы из отказов.
Чего это стоит
Нет версии этого, которая была бы бесплатной, и издержки реальны.
Поддержание второй поверхности — первая из них. Если поверхность агента — тонкая обёртка над человеческим API, широкие глаголы просачиваются, и упражнение косметическое. Настоящая поверхность агента — это отдельный контракт с собственными глаголами, собственными требованиями к параметрам и собственным словарём ошибок. Это постоянная работа, а не одноразовый рефакторинг.
Версионирование — вторая. Поверхность агента должна версионироваться независимо от человеческой поверхности, потому что они меняются по разным причинам и с разной скоростью. Она также должна тестироваться как контракт: не только то, что вызовы успешны, но и то, что поверхность отказывает в том, в чём должна отказывать, и что отказы читаемы. Набор тестов, который проверяет только счастливый путь, не поймает слишком широкий глагол.
Отказ от устаревших глаголов — третья и наименее комфортная. Некоторые глаголы технически достижимы из контекста выполнения агента, даже если они не являются частью его поверхности. Их раскрытие из-за удобства возвращает исходную проблему. Честный компромисс в том, что сужение поверхности означает, что некоторые задачи, которые агент технически мог бы выполнить, больше ему недоступны, и некоторые из этих задач законны. Эта цена платится возможностью ради предсказуемости. Команды, которые её пропускают, обычно заново обнаруживают закономерность инцидентов позже, с более широкой поверхностью и большим количеством guardrails вокруг неё.
Альтернатива — продолжать добавлять политики вокруг поверхности, которая никогда не была предназначена для буквального чтения. Такой подход масштабируется с числом вещей, которые могут пойти не так. Сужение поверхности масштабируется с числом вещей, которые агент должен делать.