Паттерн
Крупный маркетплейс открыл инструменты для продавцов внешним агентам, начав с одного поставщика моделей. Платформы бронирования, коммерции и налогообложения следуют за ним, создавая собственные поверхности, ориентированные на агентов. Это новый класс интерфейсов: основной потребитель — планировщик, а не человек с браузером. Различие не косметическое. Человек может вывести недостающие предусловия из контекста, терпеть неоднозначные ошибки и повторить неудачное действие вручную. Планировщик не может. Ему нужен контракт, который является явным, детерминированным и машиночитаемым.
Что нужно машинным вызывающим сторонам, но упускается в человеческих API
Большинство публичных API были спроектированы для разработчиков, пишущих код против них, но во время выполнения потребителем всё ещё остаётся человек, который читает документацию, изучает ответы и пишет защитную логику. Агенты-вызывающие стороны убирают этого человека из цикла. Им нужно три вещи, которых часто не хватает.
Машиночитаемые предусловия
Какие поля требуются для каких переходов состояний, должно быть указано в виде схемы, а не прозы. Например, эндпоинт бронирования может требовать guest_count только когда status равен confirmed, или tax_id только для деловых бронирований. Если это скрыто в абзаце, планировщик будет угадывать. Опубликуйте конечный автомат с обязательными полями для каждого перехода, допустимыми значениями и побочными эффектами. JSON Schema или эквивалентное формальное описание не опционально; это и есть интерфейс.
Детерминированная таксономия ошибок
Ошибки должны классифицироваться по коду, а не по сообщению. Планировщику нужно различать:
- Повторяемые: временный сбой сети, ограничение скорости, конфликт блокировок. Агент может подождать и повторить.
- Терминальные: неверный ввод, отсутствие разрешения, неподдерживаемый переход состояния. Повтор не поможет.
- Требующие человека: неоднозначное бизнес-правило, требуется ручная проверка, спор. Агент должен эскалировать.
Если единственный сигнал — это сообщение в свободной форме, планировщик должен либо жёстко закодировать хрупкое сопоставление строк, либо сдаться. И то, и другое — провал. Опубликуйте стабильный набор кодов ошибок с документированным сопоставлением этим трём классам и включите класс в тело ответа, чтобы его можно было разобрать без таблицы поиска.
Ключи идемпотентности для каждого мутирующего вызова
Планировщик может повторить шаг после тайм-аута, сбоя или частичной ошибки. Без ключа идемпотентности повторный POST /bookings может привести к двойному бронированию или двойному списанию. Ключ должен генерироваться клиентом, быть уникальным для каждой логической операции и соблюдаться сервером в течение определённого окна. Сервер должен возвращать тот же ответ для повторного ключа, а не новый ресурс. Это не новая идея, но она применяется непоследовательно. Для поверхностей, ориентированных на агентов, она обязательна для каждого мутирующего вызова, включая отмены и возвраты.
Квоты как часть контракта
Ограничения скорости часто остаются операционной запоздалой мыслью. Для агентов-вызывающих сторон они являются частью интерфейса. Публикуйте ограничения скорости и допустимые всплески в документе обнаружения, чтобы планировщики могли планировать. Возвращайте заголовки с оставшейся квотой, чтобы агент мог отступить до отказа. Разделяйте интерактивные и пакетные полосы; агент, выполняющий сверку, не должен конкурировать с оформлением заказа.
Конкретный механизм: предоставьте эндпоинт GET /limits, который возвращает текущие квоты, окна всплесков и время сброса в машиночитаемом формате. Включайте X-RateLimit-Remaining и X-RateLimit-Reset в каждый ответ. Тогда планировщик может реализовать планировщик с токенным ведром, котор
Компромисс: поддержка отдельных полос добавляет операционную сложность и может привести к недоиспользованию ёмкости в пакетной полосе в периоды пиковой интерактивной нагрузки. Альтернатива — единая полоса с подсказками приоритета — проще в эксплуатации, но сложнее для рассуждений планировщика, потому что приоритет не является гарантией. Честный выбор зависит от того, может ли платформа терпеть occasional starvation пакетной работы.
Последствия для управления
Каждый эндпоинт, ориентированный на агентов, нуждается во владельце, политике устаревания и версионированном журнале изменений. Относитесь к ломающим изменениям в интерфейсе агента как к производственному инциденту для нижестоящих систем. В отличие от изменения UI, ориентированного на человека, агент не может адаптироваться, прочитав баннер. Он откажет молча или, что хуже, предпримет неверное действие.
Ведите воспроизводимый журнал запросов, чтобы споры о том, что сделал агент, можно было разрешить на основе доказательств. Журнал должен включать ключ идемпотентности, полный запрос и ответ, идентификатор агента и временную метку. Это не только для отладки; это основа доверия. Когда продавец утверждает, что агент дважды забронировал слот, платформа должна иметь возможность показать точно, что было запрошено и что было возвращено.
Замечание об обнаружении
Поверхности, ориентированные на агентов, должны быть обнаруживаемы без вмешательства человека. Машиночитаемый манифест по общеизвестному пути (например, /.well-known/agent-api), который перечисляет эндпоинты, схемы, коды ошибок, ограничения скорости и методы аутентификации, — это минимум. Это агентский эквивалент карты сайта. Без него каждая интеграция является индивидуальной.
Заключение
Проектирование в первую очередь для машинных вызывающих сторон не означает игнорирование человеческих разработчиков. Это означает сделать контракт достаточно явным, чтобы планировщик мог рассуждать о нём, не угадывая. Идемпотентность, квоты и семантика ошибок — это не функции; это интерфейс. Платформы, которые относятся к ним как к запоздалой мысли, обнаружат, что агенты отказывают способами, которые трудно отлаживать и ещё труднее доверять. Те, кто публикует их как часть контракта, откроют новый класс автоматизации, который является надёжным, проверяемым и безопасным для повторных попыток.