Інтеграція AI API не готова, коли перший запит повернув 200. Вона готова, коли контракти, права, збої, повтори та збережені результати поводяться передбачувано.
Розглядайте модель як один компонент контрольованої бізнес-транзакції.
Спочатку контракт, потім промпт
Зафіксуйте endpoint, метод, авторизацію, схеми запиту й відповіді, коди, timeout, rate limits та версіонування.
Промпт не є API-контрактом. Перевіряйте вихід моделі за суворою схемою до запису.
Розділіть identity, authentication та authorisation
Використовуйте окрему service identity і мінімальні scopes. Розділіть читання та запис; не давайте видалення процесу оновлення.
OWASP відносить broken object-level authorisation і broken authentication до головних ризиків. Звіряйтеся зі статтею про захист даних.
Зберігайте секрети поза контентом
Токени мають бути в secret manager або захищеній конфігурації, не в промптах, логах, Trello чи коді.
Не передавайте конфіденційні дані до перевірки мети, умов постачальника, регіону, retention і прав.
Зробіть записи безпечними й повторюваними
Використовуйте idempotency key або transaction ID, якщо retry може створити дублікат. Після запису перечитайте ресурс.
Уточніть, чи оновлення часткове, чи повна заміна. Read-before-write потрібен для повного PUT.
- перевіряти власника об'єкта
- відхиляти зайві поля
- розділяти тимчасові та постійні помилки
- обмежувати retry і застосовувати backoff
- зберігати before/after важливих записів
Валідуйте кожну межу
Перевіряйте файли й URL, вихід моделі, tool arguments, API response і збережений запис. Дозволяйте лише потрібні адреси проти SSRF.
Для важливих дій застосовуйте human approval.
Спроєктуйте timeout, fallback і reconciliation
Розділіть timeout підключення й операції. Після timeout віддалений запис міг відбутися.
До повтору перевірте стан за transaction ID. Зіставляйте очікуване і фактичне.
Тестуйте систему цілком
Застосуйте сценарії з передзапускової перевірки: хибна схема, пропущене поле, прострочений токен, rate limit, timeout, дублікати, часткова відповідь і чужий об'єкт.
Приймання — правильний бізнес-стан, а не успішний HTTP.
Реальна пастка повного оновлення
В одному API PATCH відсутній, а PUT вимагає повний об'єкт статті. Оновлення лише status могло стерти інші поля.
Я виконую GET, зберігаю всі поля, змінюю одне значення, надсилаю повний PUT, знову роблю GET і порівнюю всі 21 поле. DELETE виключено, хоча токен має право.
Безпеку дала явна семантика методу та перевірка результату, а не код успіху.
Питання та відповіді
Чи має AI звертатися до API напряму?
Краще через контрольований tool-layer із валідацією й політиками.
Коли повторювати запит?
Лише за визначених тимчасових помилок і з лімітом. Невизначений запис спочатку звіряють.
Що таке idempotency?
Повтор одного логічного запиту не створює додаткових ефектів. Потрібен стабільний ключ.
Чи достатньо 200?
Ні. Перевірте збережений стан і бізнес-результат.
Що логувати?
ID, версію контракту, рішення політики, виклик, результат, помилку, retry і before/after без секретів.
Операційний аркуш контролю
До погодження внесіть кожен контроль у таблицю: власник, доказ, поріг і дата наступної перевірки. Фраза «контролювати якість» не є виконуваною. Правило «операційний власник щопонеділка перевіряє частку суттєвих виправлень і ставить процес на паузу вище погодженого порога» можна перевірити.
Пов'яжіть контроль із наслідком для бізнесу. Якщо помилка схеми може пошкодити запис клієнта, опишіть containment і reconciliation. Якщо стрибок вартості пояснюється сезонним обсягом, задайте контекст проти хибної ескалації.
Версіонуйте промпти, схеми, політики, інструменти та зовнішні залежності. Результат без конфігурації неможливо відтворити. Винятки повинні мати причину, власника і строк завершення.
Відрепетируйте людський шлях. Власник має знайти докази, зупинити або обмежити workflow, увімкнути fallback і пояснити стан без прохання до AI діагностувати себе.