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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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