Как инструменты интеграции попадают модели, почему пишущие не попадают никогда и где это видно.

Интеграция объявляет инструменты — то, что модель может вызвать в вашей системе: найти задачи, прочитать тикет, взять diff pull request. Эта страница о том, как они доходят до модели и что их ограничивает.

Регистрирует коннектор, а не вы

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

Имя подключения (слаг) попадает в имя сервера — connector_<слаг> — а значит и в имена инструментов, которые видит модель. Поэтому слаг стоит держать говорящим: jira_prod и jira_sandbox читаются в логе прогона лучше, чем два jira.

В приложении видно, что запущено, какие инструменты отданы модели и куда подключению разрешено ходить.

Пишущие инструменты не отдаются модели никогда

У режима «модель может писать в трекер» нет. Стадиям, где модель работает с вашими системами («Спросить», глубокое исследование), отдаются только инструменты, помеченные как читающие; остальным стадиям не отдаётся ничего.

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

Почему так строго: стадия, которая может изменить трекер, — это стадия, куда дошёл текст, написанный в этом трекере кем угодно. Правило «читать можно, писать нельзя» существует ровно для того, чтобы эти две вещи не встретились.

Тогда кто пишет ответ в тикет

Ответ в трекер пишет коннектор, по отдельной команде платформы, а не модель своим инструментом. Разница принципиальная: модель не решает, что и куда записать — она отвечает на вопрос, а платформа отправляет готовый ответ туда, откуда он пришёл, в тот же тикет и в ту же ветку обсуждения.

Поэтому в списке инструментов интеграции есть add_comment, но модели он не достаётся ни на одной стадии.

Ограничения и учёт

Не чаще 120 вызовов в минуту на подключение. Предел держит коннектор: превышение — это ошибка вызывающему, а не тихо отброшенные вызовы.
Каждый вызов записан: инструмент, длительность, ошибка — видно в приложении и в журнале подключения. Внутри подключения журналируется и то, какой исходящий запрос инструмент сделал: метод, адрес, код ответа и имя учётных данных (не значение).
Списания идут на подключение, а не на человека: пользователи вашего трекера — не пользователи Buff.

Инструмент, который отвечает картинкой

Не каждая модель читает изображения — большинство моделей, на которых работает Buff, текстовые. Поэтому инструмент, чей ответ — картинка (например, render_node у Figma), объявляется в манифесте отдельно (vision: true), и платформа отдаёт его только модели, которая читает изображения. Признак берётся из описания модели у провайдера — что она принимает на вход — без ручной настройки. Текстовой модели такой инструмент не показывается вовсе: названный инструмент — это вызванный инструмент, а картинка, отданная модели, которая не умеет смотреть, — это уверенный ответ по ничему. Всё остальное интеграция даёт параметрами и работает с любой моделью.

Что видно в приложении

В разделе «Коннекторы» у каждого подключения показаны: статус, интеграция и её версия, проект разработки, разрешённые адреса, полный список инструментов с пометкой «чтение» (и «картинка» — у того, что отвечает изображением) и время последнего отчёта. Это тот же список, который видит модель, — не описание из документации, а то, что фактически отдано.

Инструменты и модель