Создание ассистента API с агентными возможностями: от хакатона до бета-версии.
Ассистент LangGraph, который объясняет API, пишет код и выполняет только чтение запросов: два режима, самовосстанавливающийся цикл OData, память артефактов, оценка с помощью LLM-судьи, самостоятельный доступ.
Источники: From hackathon spark to production reality: building an agentic API assistant
Команда, разрабатывающая API для управления флотом для платежной компании, превратила прототип, созданный на хакатоне, в бета-ассистента, работающего внутри их портала для разработчиков. Идея заключается в том, чтобы избавить интеграторов от необходимости читать справочные страницы и переводить их в код, позволяя вместо этого конверсационному агенту самостоятельно обеспечивать интеграцию. Здесь рассматривается, как создается такой ассистент, что он намеренно не делает, и как оценивается его качество.
Ассистент объясняет спецификации конечных точек, пишет код на любом языке, который использует разработчик, планирует многоэтапные рабочие процессы и выполняет запросы к данным с правами только на чтение в реальных системах. Он заменяет собой статическую документацию, привязанную к конкретному языку, и поисковые индексы, которые указывают лишь на страницы.
Почему статическая документация уже недостаточна
Программное обеспечение для управления флотом и мобильности обрабатывает огромный объем данных: информацию о деятельности водителей, заправочные станции, транзакции карт и данные телеметрии транспортных средств. Любой, кто внедряет такое решение, должен овладеть сложными REST-концовками, синтаксисом фильтрации, специфической лексикой и длинными цепочками взаимосвязанных запросов. Все эти сложности затрудняли партнерам развитие вместе с платформой.
Разработчики использовали готовые инструменты документации для просмотра определений концовок и тестовые утилиты для ручной проверки запросов. Команда также вела «рецепты» — фиксированные последовательности запросов, показывающие, как выполнить многократные действия, такие как создание учетной записи, привлечение водителя и привязка карты. Эти методы срабатывали, но постоянно проявлялись три слабости:
- Зависимость от конкретного языка. Представление каждого рабочего процесса в форматах cURL, Python, .NET, Java и Go требовало постоянных усилий от авторов документации и инженеров.
- Хрупкость по краям. Невозможно задокументировать все варианты каждого рабочего процесса, поэтому инструкции часто не учитывают конкретную ситуацию пользователя.
- Постоянные расходы на техническое обслуживание. Как только менялась схема API, страницы становились устаревшими, что замедляло процесс адаптации и увеличивало нагрузку на службу поддержки.
От идеи хакатона до двух режимов работы
Концепция была разработана в ходе внутреннего хакатона в декабре 2025 года на основе одного вопроса: зачем просить разработчиков преобразовывать документацию в код, если модель может напрямую понимать их намерения? Результат работает как постоянно доступный консультант по интеграциям, а не просто поисковая строка.
Для обеспечения операционной безопасности дизайн разделяет ассистента на два отдельных пути обработки.
Режим советника обеспечивает объяснения по отдельным вопросам, углублённое изучение документации и генерацию кода для любой платформы, включая операции изменения данных, такие как POST, PUT и DELETE. Он генерирует код, но никогда не запускает его, поэтому человек остаётся в процессе для любых действий, влияющих на данные.
Режим планирования и выполнения обрабатывает сложные многоэтапные запросы на чтение и выполняет их на живой платформе с использованием инструментов с протоколом Model Context Protocol (MCP) с ограниченными правами доступа.
Что видят партнёры
Если запросить у режима советника фрагмент кода на Python для создания драйвера, он вернёт вызов функции requests с соответствующим конечным пунктом, заголовками, структурой тела и примечанием о необходимых диапазонах доступа. Ничто не влияет на производственный API.
Режим планирования и выполнения запрашивает информацию о пяти водителях с именем Джон, и планировщик сводит множественные фильтры к одной задаче — получению данных о водителях, отфильтрованных по имени. Выполняющий модуль выбирает соответствующий инструмент MCP, формирует аргументы OData ($filter=first_name eq 'John', $top=5), выполняет операцию чтения без изменений и сохраняет полный ответ в хранилище объектов. Модель видит только краткое резюме: идентификатор объекта, количество элементов — пять — и краткий превью. Затем синтезатор формирует аккуратный список пяти соответствующих водителей.
Архитектура: цикл взаимодействующих агентов
Помощник построен на LangGraph в виде циклической машины состояний. Планировщик, выполняющие модули, верификаторы и синтезатор по очереди планируют действия, выполняют их и проверяют каждый шаг, передавая общее состояние и память до завершения работы. Выделяются четыре основных принципа проектирования.
1. Только для чтения прокси в целях безопасности
С самого начала дизайн был ориентирован на безопасность. Ассистент не может выполнять операции изменения данных в своей собственной среде выполнения. Когда пользователь просит «создать новую карточку для водителя X», маршрутизатор отправляет запрос на узел-советчика, который возвращает структурированный фрагмент, который разработчик может скопировать, изучить и запустить локально. Любые действия, выполняемые на самом деле, ограничиваются запросами типа GET. В коде сервера MCP существуют инструменты для записи, но они фильтруются до того, как модель сможет их увидеть.
2. Оркестрация в стиле супервайзера
Логика принятия решений и выполнение находятся на разных уровнях и координируются единственным супервайзером, который определяет, какой специалист будет действовать дальше в рамках одного глобального цикла:
- Класс mode router классифицирует намерение пользователя и отправляет каждое сообщение либо на узел-советчика, либо на узел для планирования и выполнения.
- Планировщик разбивает сложную задачу на список заданий, связанных с целевыми параметрами.
- Исполнитель выбирает инструмент MCP для каждого задания, собирает аргументы (включая фильтры OData) и работает с этим инструментом до завершения задания или исчерпания попыток.
- Синтезатор объединяет результаты всех заданий, включая данные из реальных источников и фрагменты кода на случай сбоев, в один ответ.
3. Цикл, восстанавливающий структуру OData
Модели склонны создавать нестандартные опции запросов или искажать синтаксис при работе с структурированными языками фильтрации, такими как OData. Команда выбрала OData потому, что он позволяет выполнять гибкие запросы с частичным совпадением для сложных объектов мобильности без необходимости вручную кодировать каждую комбинацию, однако такая гибкость приводит к ошибкам, поэтому был добавлен многоуровневый цикл для их устранения.
Если анализатор предполетного тестирования выявляет проблему синтаксиса или запрос в реальном времени возвращает ошибку API, система фиксирует это событие, увеличивает счетчик попыток повтора для конкретной задачи и передает точное сообщение об ошибке обратно в контекст модели. Выполняющий компонент считывает информацию об ошибке и формирует исправленный запрос. Когда все попытки повтора исчерпаны, задача переходит в режим советника, чтобы пользователь всё равно получил полезную информацию.
4. Разделение памяти на артефакты
Передача большого объема данных в формате JSON, например тысяч записей активов, в ход разговора истощает лимит токенов, снижает точность выводов модели и увеличивает затраты. Поэтому первоначальные ответы хранятся в изолированном хранилище артефактов на сервере, а модели предоставляются только краткие метаданные с идентификаторами артефактов. Для дальнейших вопросов система обращается к конкретным элементам по этим идентификаторам на уровне приложения, что позволяет сохранять контекст модели компактным и сфокусированным.
Оценка качества
Для изменения промпта или модели без ухудшения качества необходим автоматизированный критерий оценки. В рамках используемой командой системы в качестве оценщика выступает большая языковая модель, которая отвечает на один вопрос после каждого изменения: стало ли лучше или хуже, чем раньше?
Набор данных представляет собой вручную созданный набор тестовых случаев, разделенных на четыре категории: генерация кода, фактические знания, рассуждения и безопасность. Каждый тестовый случай сопровождается четкой шкалой оценки, а не просто вопросом, поэтому оценщик оценивает суть ответа, а не просто его соответствие предустановленному шаблону. Оценщиком всегда выступает другая модель, отличная от той, которая проходит тестирование, и оценка ставится по трехбалльной шкале: 10 за правильный ответ, 5 за частично правильный и 0 за неправильный. Каждая попытка тестирования добавляет строку в файл истории, помеченную идентификатором коммита Git, именем тестируемой модели, именем модели-оценщика, хешем OpenAPI, хешем набора данных и версией запроса, так что любая оценка можно отследить до конкретного кода, спецификаций и запроса, лежащих в ее основе.
По словам команды, помощник в среднем набирает около 9,4 из 10 баллов по этой шкале в ходе различных тестов, и эта цифра служит отправной точкой для обоснования изменений перед их внедрением. Однако точность — не единственный критерий. В ходе каждого теста также фиксируется время отклика, чтобы обеспечить быструю работу приложения, а также объём использованных токенов, который напрямую связан с расходами на модель. Любые изменения, ухудшающие один из этих показателей, отмечаются заранее перед выпуском.
Защита бюджета и ресурсов
Помощник, работающий круглосуточно и имеющий доступ к производственному API, требует ограничений, защищающих как бюджет на использование модели, так и внешние сервисы. Для этого предусмотрены три уровня защиты:
- Квоты на пользователя. У демо-аккаунтов разрешено отправлять 10 сообщений в день, что позволяет заинтересованным партнёрам попробовать сервис без неограниченных расходов на модель и побуждает их перейти на партнёрский аккаунт, когда они начинают использовать сервис в реальных задачах.
- Звонки с четким определением источника и привязкой к пользователю. Трафик партнеров обрабатывается с использованием их собственных учетных данных, поэтому каждый звонок учитывается в их квоте и отражается в их личном журнале аудита. Ассистент никогда не выдаёт себя за общий счет аккаунта, что позволяет точно определять источник использования ресурсов и выявлять злоупотребления.
- Повторные попытки с учётом причин сбоев. При сбое запроса, включая временный ответ о ограничении скорости, цикл восстановления передаёт ошибку обратно в модель, увеличивает счётчик повторных попыток и планирует их выполнение до установленного максимума. После исчерпания всех возможных попыток система переходит в режим советника.
Упрощение доступа
Создание ассистента — это лишь половина работы. Не менее важен был безопасный и простой доступ к нему.
API платформы традиционно использовали стандартные учетные данные клиента, что означало необходимость ручной настройки каждого нового клиента. Для помощника, предназначенного для внешних партнеров, подход «подать заявку и ждать одобрения от инженеров» был неприемлем. Прошение у разработчиков вставить токены в чат тоже не решало проблемы, поскольку это делало невозможным отличить вызовы, сделанные помощником, от ручных, а также затрудняло отслеживание использования ресурсов и контроль безопасности. Команде требовалась единая стратегия, подходящая для двух типов пользователей: партнеров, желающих работать в среде без лишних ограничений, и тех, кто готов использовать реальные данные, без необходимости оформления ручных заявок на настройку.
Решением стала двухуровневая модель самообслуживания, дополняющая обычный вход для разработчиков.
- Режим демо является стандартным. Новые пользователи могут сразу общаться с помощником с использованием синтетических данных, без необходимости настройки, ожидания или оформления заявок.
- Режим партнера включается тогда, когда разработчик хочет осуществить прямую интеграцию. Учетные данные получаются в ходе однократной процедуры авторизации самостоятельного типа, связанной с собственным аккаунтом и правами разработчика. После подключения каждый запрос привязывается к этой идентичности и полностью отслеживается, поэтому ясно, кто и по какому пути выполняет запрос.
Это устранило основное препятствие на этапе ввода в эксплуатацию. Переход от состояния «Мне интересно» к состоянию «Я осуществляю интеграцию» больше не требует ожидания в очереди инженеров.
Как дальше
Проект начинался как внутренний эксперимент, а теперь представляет собой бета-версию, сокращающую время интеграции для корпоративных команд разработчиков. Он работает в портале разработчиков и уже привлек первую группу партнеров.
Оркестратор работает с стандартными схемами OpenAPI, поэтому архитектура предназначена для горизонтального масштабирования. В настоящее время усилия сосредоточены на проверке данных в рамках сферы мобильности, однако ядро маршрутизации специально разработано как универсальное решение. В планах — внедрение того же слоя взаимодействия в другие подразделения, такие как системы корпоративных платежей и программ льгот, добавление более сложных детерминистичных механизмов проверки OData для блокировки некорректных запросов ещё до их отправки ассистенту, а также изучение возможности подтверждения операций записи человеком, чтобы в будущем ассистент мог безопасно помогать с изменением рабочих процессов.
Связанные материалы
- От прототипа к производству: агентные ИИ-системы с использованием LangChain, LangGraph и Azure — гибридный поиск, кэширование эмбеддингов, маршрутизация через LangGraph, механизмы защиты от сбоев, тесты на регрессию с использованием «золотого набора» данных и отслеживание действий агента для обработки налоговых документов, включая представленные результаты.
- Графы знаний для агентных ИИ: четыре подхода, выходящих за рамки технологии Vector RAG — векторный поиск находит похожий текст, но не связанные между собой факты. Четыре паттерна использования графов для агентов: формулировка запросов с учетом контекста, планирование, проверка выполнения задач и самокоррекция.