Собственные инструменты и вызов функций

Собственный инструмент (его также называют функцией) позволяет ИИ выполнить небольшое действие во время чата. Действие может вернуть заранее заданный текст, обратиться к веб-адресу или выполнить короткий скрипт на сервере. Используйте инструмент, когда хотите, чтобы ИИ что-то нашел или посчитал, а не угадывал.

Вызов функций означает, что ИИ просит приложение выполнить действие, а затем использует результат в ответе. В Marinara уже есть встроенные инструменты: бросок кубика, поиск по лорбукам и обновление состояния игры. Ваши собственные инструменты работают рядом с ними. Собственный инструмент не привязан к карточке персонажа. Его включают для чата или подключают к агенту (помощнику, который работает параллельно с чатом).

Примечание: инструментам нужно подключение, которое их поддерживает. Подключения по подписке Claude и Grok игнорируют определения инструментов, поэтому Chat Settings (настройки чата) показывает уведомление и отключает для них элементы управления инструментами. Текстовые команды и теги бросков по-прежнему работают.

Создание инструмента

Перед началом откройте панель Presets (пресеты) кнопкой на верхней панели. Инструменты находятся в ее разделе Functions (функции; значок гаечного ключа). Если вы открываете Marinara с другого устройства, сначала сохраните секрет администратора в разделе Settings → Advanced → Admin Access (настройки → дополнительно → доступ администратора). Он должен совпадать с ADMIN_SECRET на сервере; см. Настройки сервера: справочник.

Для первой попытки выберите Static Result: ему больше ничего не нужно.

Как создать инструмент

  1. Откройте Presets и найдите Functions.
  2. Нажмите Create function (создать функцию; значок плюса). Откроется пустой редактор инструмента.
  3. Введите название в нижнем регистре в стиле snake_case, например check_weather. Именно этим названием ИИ вызывает инструмент. Оно начинается со строчной буквы, дальше идут строчные буквы, цифры и подчеркивания.
  4. Заполните поле Description (описание). Пишите его как инструкцию для ИИ, потому что ИИ читает его, чтобы решить, когда вызвать инструмент. Пример: Get the current weather for a city the user names.
  5. Добавьте параметры, которые нужны инструменту (см. Добавление параметров).
  6. Выберите Execution Type (тип выполнения): Static Result, Webhook или Script.
  7. Заполните поле для этого типа (см. Выбор типа выполнения).
  8. Нажмите Save (сохранить). Рядом с кнопкой мигнет зеленая надпись Saved.

Правила для названий и описаний:

В заголовке раздела Functions три кнопки со значками:

У каждого инструмента в списке видны:

Перетаскивайте инструмент за ручку, чтобы менять порядок списка. Порядок влияет только на отображение. Пока инструментов нет, в списке написано No functions yet.

Добавление параметров

Параметры – это входные данные, которые ИИ передает, когда вызывает ваш инструмент. У каждого параметра есть название, тип, признак обязательности и описание.

  1. В группе Parameters (параметры) нажмите Add Parameter (добавить параметр).
  2. Введите название, например city.
  3. Выберите тип: string, number, boolean, array или object.
  4. Включите Required (обязательный), если ИИ обязан всегда присылать это значение.
  5. Напишите описание, которое объясняет ИИ смысл значения, например The city name to look up, such as Tokyo.

Добавляйте строки кнопкой Add Parameter, а убирайте строку ее кнопкой с минусом. Строка с пустым названием при сохранении отбрасывается.

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

Выбор типа выполнения

Static Result

Инструмент типа Static Result каждый раз возвращает один и тот же текст. Внешний сервис ему не нужен. На его карточке написано Returns a fixed string when called.

Единственное поле – Static Result, многострочное. Если оставить его пустым, инструмент вернет OK.

Пример: инструмент с названием store_hours без параметров и с таким Static Result:

We are open Monday to Friday, 9am to 5pm. We are closed on weekends.

Когда ИИ вызывает store_hours, он получает этот текст вместе с названием инструмента и отправленными аргументами и может сообщить пользователю часы работы.

Webhook

Инструмент типа Webhook отправляет вызов на веб-адрес и возвращает ИИ ответ этого сервиса. Вебхук – это адрес, который принимает данные и отправляет данные обратно. На его карточке написано Sends a POST request to an external URL.

Единственное поле – Webhook URL. Приложение отправляет запрос POST – способ передать данные веб-сервису. Тело запроса – JSON, простой текстовый формат для структурированных данных, такого вида:

{ "tool": "your_tool_name", "arguments": { ... } }

Если включить Include hidden chat context (передавать скрытый контекст чата), в теле будет еще значение context. Сервис отвечает в формате JSON или обычным текстом, и этот ответ возвращается ИИ.

Пример: инструмент с названием check_weather с одним обязательным строковым параметром city и таким Webhook URL:

https://api.example.com/weather

Когда ИИ вызывает его со значением city, равным Tokyo, ваш сервис узнает погоду и отвечает, а ИИ использует ответ в своем сообщении.

Ограничения:

Если не получилось: проверьте, что адрес начинается с https:// и доступен. Локальный адрес остается заблокированным, пока администратор его не разрешит. Медленный сервис может упереться в предел 60 секунд.

Script

Инструмент типа Script выполняет на сервере короткий фрагмент кода на JavaScript и возвращает результат. JavaScript – это распространенный язык программирования. На его карточке написано Runs a JavaScript expression server-side.

Скриптовые инструменты по умолчанию выключены. Если на вашем сервере они не включены, карточка Script неактивна и видна янтарная плашка Script disabled. Чтобы включить их, администратор сервера добавляет эту строку в файл .env на сервере и перезапускает Marinara:

CUSTOM_TOOL_SCRIPT_ENABLED=true

Единственное поле – Script Body. Скрипт читает args (значения, присланные ИИ) и обязан вернуть результат через return. Доступны JSON, Math и Date.

Пример: инструмент с названием add_numbers с двумя обязательными числовыми параметрами x и y и таким Script Body:

const result = args.x + args.y;
return { sum: result };

Когда ИИ вызывает его со значением x, равным 2, и y, равным 3, инструмент возвращает сумму 5. Если скрипт выбросит ошибку, ИИ получит результат с ошибкой.

Скрипт выполняет на вашем сервере настоящий код внутри песочницы (отгороженной области, которая ограничивает возможности кода):

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

Если не получилось: когда карточка Script неактивна, попросите администратора задать CUSTOM_TOOL_SCRIPT_ENABLED=true и перезапустить Marinara.

Скрытый контекст чата

Инструменты типов Webhook и Script могут получать дополнительные данные чата, которых ИИ не видит среди входных значений инструмента. Включите Include hidden chat context в редакторе инструмента (по умолчанию выключено). Тогда инструмент получает значение context, в которое могут входить:

Так инструмент подстраивает результат под ситуацию, и ИИ не приходится передавать все эти данные.

Как включить инструменты в чате

Создание инструмента еще не заставляет ИИ им пользоваться. Использование инструментов нужно включить и в чате.

  1. Откройте чат, затем Chat Settings.
  2. Откройте раздел Function Calling (вызов функций; значок гаечного ключа).
  3. Включите Enable Tool Use (разрешить использование инструментов). Его описание гласит Allow AI to call functions (dice rolls, game state, etc.). В новом чате он по умолчанию выключен.
  4. Проверьте, что все работает: спросите ИИ о том, на что отвечает ваш инструмент, например "Какие у вас часы работы?" для примера store_hours. В ответе должен быть текст инструмента.

Если Enable Tool Use включен и ниже ничего не добавлено, чат может использовать все глобально включенные инструменты, которые он поддерживает: встроенные инструменты и каждый собственный инструмент, чей переключатель включен в разделе Functions. Чатам Game для search_lorebook также нужна настройка Let the GM search lore (разрешить GM поиск по лору).

Чтобы ограничить чат выбранным набором:

  1. Нажмите Add Functions (добавить функции). Откроется окно выбора с полем поиска, которое сравнивает только названия инструментов.
  2. Отметьте нужные инструменты. В списке перемешаны встроенные и собственные инструменты.
  3. Нажмите Add Selected (добавить выбранные).

Как только вы добавите хотя бы один инструмент, в этом чате работают только добавленные. Кнопка New Custom Function (новая собственная функция) в окне выбора переходит в редактор инструмента.

Чаты Game могут использовать отдельное подключение для планирования инструментов. Стоимость и поведение описаны в разделе Необязательное планирование инструментов и поиск по лору.

Если не получилось: проверьте, что Enable Tool Use включен, что инструмент есть в списке чата, если вы добавляли конкретные инструменты, и что переключатель инструмента в разделе Functions включен. Более понятные Description и описания параметров помогают ИИ решить, когда вызывать инструмент.

Подключение инструментов к агенту

Инструмент можно также отдать не чату, а агенту.

  1. Откройте панель Agents (агенты) и откройте агента.
  2. Откройте его группу Tools / Function Calling (инструменты и вызов функций).
  3. Включите инструменты, которыми этому агенту можно пользоваться.

Включить Enable Tool Use в разделе Function Calling чата все равно нужно. Об этом напоминает подпись внизу редактора агента. Об агентах в целом см. руководство Создание своих агентов.

Экспорт и импорт инструментов

Импортированные инструменты-вебхуки и скриптовые инструменты всегда сохраняются выключенными, с выключенным Include hidden chat context, даже если файл запрашивает одно или другое. Затем Marinara показывает тип, адрес вебхука и разрешения, которые запросил файл. Откройте каждый импортированный инструмент, изучите его и включайте, только если доверяете ему. Статические инструменты сохраняют импортированное состояние включения.

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

Смежные руководства