Към съдържанието
ПРАКТИЧЕСКО РЪКОВОДСТВО

Проектирай API за агенти около бизнес операции, не таблици

Предостави малък полезен набор действия, като запазиш правилата и правата на приложението.

Редакция на Yepsy·4 мин четенеПубликувано:

Избирай операции с ясен резултат

Общ инструмент за промяна на запис оставя бизнес логиката на агента. Операция за подготовка на оферта или свободни часове описва резултата директно. Определи вход, валидация, изход и грешки. Предпочитай малък набор смислени операции пред излагане на всеки съществуващ endpoint.

Използвай правата вътре в приложението

Агентът действа за конкретна идентичност и организация. API ключът му не трябва да става администратор на всички клиенти. Използвай същите бизнес услуги и права като приложението. Провери чужди записи и действие извън обхвата. Името „безопасен endpoint“ не налага ограничение.

Планирай повторения и неясни резултати

Заявката може да изтече след успешно действие. Без стабилна идентичност повторението може да удвои резервация. Определи кои операции приемат ключ за идемпотентност и как връщат стар резултат. Разграничавай невалидни данни от неизвестен изход. Клиентът трябва да проверява статуса, вместо сляпо да повтаря запис.

Добави протокола след договора

HTTP API и MCP могат да обслужват различни нужди. Нито едно от двете не трябва да дублира или отслабва бизнес логиката. Във Forge проект първо опиши клиента, действията и примерите за приемане. После реализирай адаптера и документацията. Клиентът пази софтуера и контролира кой получава достъп след внедряване.

Предостави бизнес операция, не свободна база

Асистент за часове има нужда от „намери свободни часове“ и „подготви чернова за преместване“. Няма нужда от общ SQL инструмент. Определи всяка операция според задачата с типизиран вход, смислен резултат и обхват. Приложението трябва да използва съществуващите си права и бизнес услуги.

Отдели четене, чернова и окончателно действие. Черновата връща предложените промени и нужните одобрения. Финалното действие проверява наличността и правото върху актуалните данни. Документацията обяснява повторенията и разпознаването на неизвестен резултат.

РешениеПолезно изискванеДоказателство
Чети часовеРазрешен офис и дата.Без чужди записи.
ЧерноваПредложение без промяна на резервация.Без запис и известие.
ПотвърдиНова проверка на права и актуалност.Един проследим ефект със защита от повторение.
Пример: от запитване до оферта

Къде възникват грешките

MCP интерфейсът не премахва тези отговорности. Той описва откриване и извикване на инструменти, а не разрешава заобикаляне на правилата. Ограничи токените до нужните операции и ги отнемай независимо.

Добрият интерфейс улеснява разрешеното и отказва забраненото на сървъра.

Превърни го в работен списък

  • Назовавай бизнес резултати.
  • Ограничавай всеки ключ.
  • Тествай забранени операции.
  • Обработвай повторен и неизвестен резултат.

Конкретна следваща стъпка

Предай каталог на операции, матрица на права, примерни заявки и отрицателни тестове. Пази версии на интерфейса, така че външните агенти да използват ясно описано и съвместимо поведение.

Гледай свързан казус

Превърни ръчните запитвания в контролиран процес с AI2:26 · английски