Post #540

Агенту нельзя просто дать backend API и ждать магии Делали простой сценарий: — есть LLM-агент — есть API сервиса поиска круизов — есть клиент, который пишет: “хочу круиз из Казани в июле на 5 дней” Задача агента — вызвать поиск и вернуть подходящие варианты. Казалось бы, всё просто: берем метод API, заворачиваем в MCP tool, описываем параметры и даем агенту. Формально работает. Но на практике быстро выяснилось, что tool получился не “LLM-friendly”, а “backend-friendly”. То есть удобный для кода, но хрупкий для модели. И в какой-то момент стало понятно: проблема не в агенте, а в интерфейсе, который мы ему дали. Антипаттерн 1 — цепочка вызовов вместо одного Проблема: инструмент поиска принимал не человеческие сущности, а внутренние id: города, теплоходы, направления, стоянки. Поэтому агенту приходилось сначала вызывать tool-маппинг “название → id”, а потом уже search_cruises. Что ломалось: — модель забывала вызвать маппинг — вызывала его не для всех сущностей — путала полученные id между параметрами: cityStart, cityEnd, cities Короткий вывод: если пользователь говорит названиями, а инструмент требует id, мы заставляем LLM быть не ассистентом, а glue-code между UI и базой данных. Фикс: принимать в LLM-facing tool названия: — город отправления: Москва — теплоход: Беда — направление: Волга А id-резолвинг делать внутри инструмента. Антипаттерн 2 — непопулярные типы аргументов Проблема: некоторые параметры API были типизированы странно. Например, одиночное значение передавалось как массив: не durationFrom = 7, а durationFrom = [7]. Что ломалось: — модель передавала скаляр вместо массива — массив не там — не тот shape — параметр вообще пропускался Короткий вывод: LLM лучше работает с boring-типами: string, number, boolean, простые объекты вроде min/max. Необычная форма данных — это не нейтральная backend-деталь, а дополнительная когнитивная нагрузка. Фикс: Было: — durationFrom: [7] — durationTo: [10] Стало: — duration_days_min: 7 — duration_days_max: 10 Или один понятный объект: duration_days: от 7 до 10 Антипаттерн 3 — плохие имена параметров Проблема: параметры назывались как поля backend API, а не как понятия из пользовательского запроса: cities, dateTo, costFrom, category_id, motorships. Что ломалось: модель путала семантику. Например, cities может значить город отправления, город прибытия, стоянки, города маршрута или просто направление. dateTo тоже неочевиден: это дата отправления “до” или дата прибытия “до”? Короткий вывод: имя параметра — это часть prompt’а. Если имя требует знания внутренней модели данных, LLM начинает угадывать. Фикс: Было: cities, dateTo, costFrom Стало: must_visit_cities_or_landmarks, departure_before, price_min_rub Да, имена становятся длиннее. Но для LLM это плюс: название параметра одновременно работает как мини-инструкция. Главный вывод Хороший tool для агента — это не thin wrapper над backend API. Backend API проектируется под код: id, внутренние типы, короткие поля, цепочки методов. LLM-facing tool лучше проектировать под модель и пользовательскую задачу: — одно пользовательское действие = один tool — человеческие названия вместо внутренних id — простые boring-типы вместо legacy-форматов — говорящие имена параметров — минимум промежуточного состояния Иначе получается странная ситуация: модель вроде умная, MCP вроде подключили, API вроде рабочий — а агент всё равно хрупкий. Потому что для LLM tool — это не endpoint. Это UX.