Как подключить агента к системам компании: опыт Redmine CLI и GraphQL — Блог Skillum.AI

В наших компаниях GitLab и Redmine — ключевые системы разработки. Когда агент умеет менять код, довольно быстро хочется поручить ему и соседние действия: прочитать задачу с обсуждением, оформить результат, подготовить merge request. Для этого нужны удобные инструменты доступа. Под Redmine я сделал отдельный CLI.

Почему прямых запросов к API стало мало

До появления CLI мы описывали в корпоративном скилле работу с Redmine через REST API. Агент справлялся, но взаимодействие получалось многословным: приходилось собирать запросы, передавать параметры, разбираться с ответами. По моему наблюдению, на это уходило слишком много контекста. Количественного сравнения расхода токенов я в анонсе инструмента не приводил.

Для GitLab уже был glab. С Redmine подходящего мне инструмента тогда не нашлось, поэтому появился redmine-cli. Он построен на OpenAPI-описании Redmine. В опубликованном наборе возможностей есть установка через Homebrew, работа с задачами и профили для нескольких серверов.

У CLI здесь понятная роль: собрать повторяющиеся технические действия в короткие команды. Агенту по-прежнему нужно понимать задачу пользователя, выбирать нужную операцию и оценивать результат. Обёртка упрощает обращение к системе, но сама по себе этого понимания не даёт.

Что агент получает от Redmine CLI

В исходной публикации я показал команды проверки авторизации, чтения списка задач и получения задачи с историей обсуждения. Например:

redmine auth status
redmine --profile client issue list --limit 20
redmine issue show 123 --include journals

Профиль позволяет явно выбрать сервер. Это удобно, когда работаешь с внутренним Redmine и системой клиента: адрес назначения становится частью команды. Получение journals помогает прочитать историю задачи вместе с её текущим состоянием. Для агента это существенная разница: последние договорённости часто находятся в комментариях.

Рядом с кодом лежат документация команд и готовый скилл. В документации описан синтаксис команд. Корпоративные инструкции должны дополнить её правилами команды: какие поля обязательны, когда менять статус, как связывать задачу с MR. Такие правила у каждой компании свои.

Где помогает GraphQL

Другой вопрос возникает, когда агенту приходится читать большие объекты. Представим заказ, у которого много полей, а для ответа нужны только номер, дата, статус и сумма. Если инструмент каждый раз возвращает весь объект, модель получает данные, которые никак не помогают текущей задаче.

В заметке о GraphQL мне были интересны три свойства: описание типов и полей в схеме, выбор полей в запросе и получение связанных объектов. Эти возможности определены в спецификации GraphQL. В упрощённом примере запрос может выглядеть так:

{
  orders {
    number
    createdAt
    status { name }
    totalSum { amount currency }
  }
}

Это иллюстрация формы запроса, а не готовая команда для любого CRM API. Названия полей, обязательные аргументы и пагинация зависят от конкретной схемы. Если схема связывает заказы с задачами менеджеров, клиент может запросить эти данные вместе. При этом число внутренних обращений сервера к базе определяется его реализацией.

Я бы оценивал пользу на конкретных ответах: сколько лишнего текста попадает в контекст, сколько вызовов делает агент, хватает ли ему данных для вывода. Само наличие GraphQL ещё не даёт фиксированного процента экономии. Небольшой REST-ответ может быть вполне достаточным для рабочего сценария.

MCP, GraphQL и CLI решают разные задачи

Заголовок моего поста о GraphQL был категоричным. Для инженерного выбора нужно уточнение: MCP — протокол подключения инструментов и других возможностей к AI-приложению; GraphQL — язык запросов к API; CLI — интерфейс программы в командной строке. Они совместимы.

MCP-инструмент может принимать GraphQL-запрос и возвращать его результат. CLI тоже может обращаться к GraphQL. Более того, уже спецификация MCP от 18 июня 2025 года предусматривает необязательный outputSchema для описания структуры ответа. Утверждение, что MCP в принципе скрывает от модели формат результата, было бы слишком широким.

Размер ответа зависит от дизайна инструмента. Через MCP можно предоставить операцию с выбором полей, а через CLI — вернуть огромный документ. Поэтому я бы начинал с устройства конкретной интеграции: как найти нужную операцию, как ограничить выдачу и как понять ошибку.

Что стоит описать в корпоративном скилле

Ниже — рекомендации для подключения новой системы. Они дополняют описание команд правилами работы команды.

Порядок чтения. Где искать задачу, как получить обсуждение и связанные документы, какие идентификаторы сохранить.
Правила изменений. Какие поля агент вправе обновлять по поручению пользователя и какие действия требуют согласования.
Поведение при ошибке. Как отличить отсутствие доступа от отсутствия объекта и что делать после неясного результата записи.
Проверка результата. Что прочитать повторно после изменения и какую ссылку вернуть человеку.

Права нужно ограничивать на стороне системы. Инструкция для модели помогает выбрать действие, но ограничения учётной записи продолжают действовать независимо от текста скилла. Особенно внимательно я бы отделял обычное чтение от массовых изменений.

Начать с одного законченного сценария

Для первой интеграции я бы взял короткую цепочку: найти задачу, прочитать обсуждение, подготовить изменение и показать результат человеку. На ней видно, где агент тратит время и какой информации ему не хватает. Затем можно добавлять новые операции, сохраняя понятные границы доступа.

Redmine CLI закрывает для меня конкретный разрыв между агентом и одной из основных рабочих систем. GraphQL полезен там, где требуется гибко выбирать связанные данные. Хорошая интеграция получается, когда интерфейс, описание процесса и права доступа согласованы между собой. Тогда агент может пройти рабочую задачу дальше редактирования файлов.