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

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

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

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

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

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

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

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

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

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

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

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