Инструменты и модель
Как инструменты интеграции попадают модели, почему пишущие не попадают никогда и где это видно.
Интеграция объявляет инструменты — то, что модель может вызвать в вашей системе: найти задачи, прочитать тикет, взять diff pull request. Эта страница о том, как они доходят до модели и что их ограничивает.
Регистрирует коннектор, а не вы
Ничего настраивать не нужно. Подключение, которое запустилось, само сообщает платформе свой список инструментов и то, какие из них только читают. Платформа поднимает по одному инструментальному серверу на подключение, а не на коннектор: у команды с двумя трекерами модель должна видеть, к какому из них обращается.
Обращаться из трекера или со страницы не обязательно. Как только в поле «Проект разработки» подключения стоит имя вашего проекта (или пространства), модель видит его инструменты в каждом вопросе «Спросить» и в каждом глубоком исследовании этого проекта — в том числе заданных из приложения, рядом с кодом. Трекер при этом становится источником: модель сама найдёт тикет, прочитает обсуждение или diff pull request, если это нужно для ответа. Этапы разработки задач — формулировка, разработка, ревью — инструменты подключения не получают.
Имя подключения (слаг) попадает в имя сервера — connector_<слаг> — а значит и в
имена инструментов, которые видит модель. Поэтому слаг стоит держать говорящим:
jira_prod и jira_sandbox читаются в логе прогона лучше, чем два jira.
Пишущие инструменты не отдаются модели никогда
У режима «модель может писать в трекер» нет. Стадиям, где модель работает с вашими системами («Спросить», глубокое исследование), отдаются только инструменты, помеченные как читающие; остальным стадиям не отдаётся ничего.
Проверяется это дважды и с двух сторон: платформа просит только читающие, а коннектор у себя сверяет запрошенный инструмент со списком и отказывает, если он пишущий. Решение не должно зависеть от того, что вызывающая сторона попросила правильно.
Почему так строго: стадия, которая может изменить трекер, — это стадия, куда дошёл текст, написанный в этом трекере кем угодно. Правило «читать можно, писать нельзя» существует ровно для того, чтобы эти две вещи не встретились.
Тогда кто пишет ответ в тикет
Ответ в трекер пишет коннектор, по отдельной команде платформы, а не модель своим инструментом. Разница принципиальная: модель не решает, что и куда записать — она отвечает на вопрос, а платформа отправляет готовый ответ туда, откуда он пришёл, в тот же тикет и в ту же ветку обсуждения.
Поэтому в списке инструментов интеграции есть add_comment, но модели он не
достаётся ни на одной стадии.
Пояснения для ИИ
Описания инструментов говорят, что инструмент делает, но не что такое ваша система: какой проект — биллинг, а какой — эксплуатация; как у вас называют релизы; куда смотреть в первую очередь. Это знаете вы, поэтому у каждого подключения есть поле «Пояснения для ИИ» — свободный текст, который вы пишете на коннекторе (на его странице, в командной строке или в YAML).
Текст уходит модели вместе с инструментами подключения, двумя путями: как инструкции
инструментального сервера connector_<слаг> — они попадают в системный промпт прогона —
и в начале описания каждого инструмента этого подключения. Так модель видит ваши
пояснения и когда планирует, и в момент, когда выбирает инструмент. Пустое поле не
добавляет в промпт ничего.
По умолчанию пояснения ограничены 2048 символами. Предел можно снять галочкой, но только подтвердив, что вы понимаете последствия: избыточный текст в промпте ухудшает следование инструкциям, увеличивает стоимость каждого прогона и не делает модель умнее. Пока предел снят, подключение помечено предупреждением — и на коннекторе, и в приложении. Коннектор ничего не обрезает: объём — ваше решение.
Пояснения — чужой текст в системном промпте, поэтому коннектор и платформа вычищают из них служебную разметку, которую модель могла бы принять за речь самого прогона; слова остаются, теги — нет.
Ограничения и учёт
- Не чаще 120 вызовов в минуту на подключение. Предел держит коннектор: превышение — это ошибка вызывающему, а не тихо отброшенные вызовы.
- Каждый вызов записан: инструмент, длительность, ошибка — видно в журнале подключения на коннекторе; платформа ведёт учёт вызовов по подключению. Внутри подключения журналируется и то, какой исходящий запрос инструмент сделал: метод, адрес, код ответа и имя учётных данных (не значение).
- Списания идут на подключение, а не на человека: пользователи вашего трекера — не пользователи Buff.
Инструмент, который отвечает картинкой
Не каждая модель читает изображения — большинство моделей, на которых работает Buff,
текстовые. Поэтому инструмент, чей ответ — картинка (например, render_node у Figma),
объявляется в манифесте отдельно (vision: true), и платформа отдаёт его только модели,
которая читает изображения. Признак берётся из описания модели — у провайдера или у выделенной машины, — что она
принимает на вход — без ручной настройки. Текстовой модели такой инструмент не показывается
вовсе: названный инструмент — это вызванный инструмент, а картинка, отданная модели, которая
не умеет смотреть, — это уверенный ответ по ничему. Всё остальное интеграция даёт
параметрами и работает с любой моделью. Сейчас картинку получает только «Спросить»;
глубокое исследование работает по параметрам макета.
Что видно в приложении
В разделе «Коннекторы» у каждого подключения показаны: статус, интеграция и её версия, проект разработки, разрешённые адреса, полный список инструментов с пометкой «чтение» (и «картинка» — у того, что отвечает изображением), пояснения для ИИ (в свёрнутом виде — только для чтения, правятся они на коннекторе) и время последнего отчёта. Если предел длины пояснений снят, рядом со статусом стоит та же пометка-предупреждение, что и на странице коннектора. Это тот же список, который видит модель, — не описание из документации, а то, что фактически отдано.