Создание своих агентов

Свой агент – это помощник, которого вы пишете сами: ваши инструкции, момент запуска и то, что ему разрешено менять. Собирайте его, когда ни один агент для скачивания не делает того, что вам нужно. Если установленный агент близок к задуманному, наведите курсор на его карточку в панели Agents (агенты) и нажмите Copy agent (копировать агента), чтобы получить редактируемую копию.

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

Создание своего агента

  1. Откройте панель Agents.
  2. Нажмите New (иконка плюса) в верхней части. Откроется редактор агента на всю страницу.
  3. Введите название в поле заголовка, например Weather Reporter.
  4. Заполните поля Description (описание) и Author (автор).
  5. Выберите Pipeline Phase (фаза конвейера). См. раздел Pipeline Phase.
  6. Включите нужные ему возможности в разделе Custom Agent Abilities (возможности своего агента).
  7. Выберите Result Type (тип результата), который соответствует тому, что выдает агент. Если не уверены, выберите Context Injection. Этому типу не нужны ни возможности, ни строгий формат вывода.
  8. Впишите инструкции агента в поле Prompt Template (шаблон промпта).
  9. Нажмите Save (сохранить) в верхней панели. Появится зеленый значок Saved.

Теперь агент виден в разделе Custom Agents (свои агенты) панели Agents. Чтобы его использовать, откройте чат, перейдите в Chat Settings (настройки чата), включите Enable Agents (включить агентов) и добавьте агента из раздела Custom Agents.

Pipeline Phase

Параметр Pipeline Phase задает, когда работает агент.

Некоторые типы результата задают фазу принудительно. Text Rewrite переключает ее на Post-Processing. Prompt Patch и Character Activity переключают ее на Pre-Generation.

У агентов в фазе Post-Processing есть еще раздел Turn Data Access (доступ к данным хода) с двумя переключателями: Pre-generation injections и Parallel agent results. Включите их, чтобы агент мог читать то, что другие агенты выдали за тот же ход.

Custom Agent Abilities

Возможности включаются вручную. Каждая остается заблокированной, пока вы не включите ее переключатель.

Если включить Edit lorebooks, появится раздел Lorebook Writer. Включите Allow lorebook entry writes (разрешить запись в лорбук) и выберите один лорбук в Target lorebook (целевой лорбук). Писать агент сможет только в этот лорбук.

Result Type

Параметр Result Type сообщает Marinara, как читать ответ агента. Большинство типов ожидают JSON – текстовый формат с фигурными скобками и кавычками. Тип остается серым, пока вы не включите нужную ему возможность.

Типы, которым не нужна возможность:

Типы, которым нужна возможность Edit messages:

Типы, которым нужна возможность Edit trackers:

Остальные типы, у каждого своя возможность:

Элементы управления агентов изображений в чате

Агент с возможностью Image generation получает два дополнительных элемента управления в Chat Settings → Agents → Custom Agents.

Activation Keywords

По умолчанию агент работает со своей обычной периодичностью (то есть с той частотой, с какой он запускается). Activation Keywords (ключевые слова активации) пропускают агента, если сцена к нему не относится, и так экономят токены.

  1. В поле Activation Keywords впишите по одному ключевому слову или фразе на строку, например tavern или secret door.
  2. В поле Scan Depth (глубина сканирования) укажите, сколько последних сообщений просматривать. По умолчанию 5, максимум 200.

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

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

Агент может вызывать инструменты – функции, которые ИИ запускает, чтобы что-то получить или изменить, а затем читает результат. Это также называют вызовом функций.

  1. В редакторе агента откройте Tools / Function Calling (инструменты и вызов функций) и включите каждый нужный инструмент. В списке есть встроенные инструменты и ваши собственные. Как собрать свой инструмент, читайте в руководстве Собственные инструменты и вызов функций.
  2. В Chat Settings откройте Function Calling и включите Enable Tool Use (разрешить использование инструментов). Без этого инструменты агента остаются выключенными.

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

Агент получает не больше 16 кругов вызова инструментов за один запуск (меньше, если MAX_TOOL_ROUNDS на сервере ниже), а затем отвечает с тем, что у него есть. Модель, которая вызывает инструменты по одному, тратит на каждый вызов отдельный круг, поэтому агенту, который сохраняет много записей, стоит делать несколько вызовов в одном ответе. Запуск дозаполнения лорбука получает до 64 кругов.

Named prompt options

Агент может хранить несколько вариантов промпта, и каждый чат выбирает один из них без правки самого агента.

  1. В разделе Prompt Template найдите Named prompt options (именованные варианты промпта).
  2. Нажмите Add option (добавить вариант).
  3. Дайте варианту название и короткое описание, затем впишите его полный промпт.

Когда агента добавляют в чат, раскрывающийся список Prompt Mode (режим промпта) показывает ваши варианты. Если вариантов нет, виден только промпт по умолчанию.

Другие настройки

Макросы вроде {{user}} и {{char}} работают в поле Prompt Template. См. Макросы промптов.

Разобранный пример

Этот агент переписывает каждый ответ на британский английский.

  1. Назовите его British English Editor.
  2. В разделе Custom Agent Abilities включите Edit messages.
  3. В разделе Result Type выберите Text Rewrite. Фаза переключится на Post-Processing.
  4. Вставьте это в поле Prompt Template:
   You are a copy editor. Rewrite the latest reply into British English.
   Change spelling and vocabulary only. Do not change the meaning, tone, or events.
   Return JSON with an "editedText" field holding the full rewritten reply,
   and a "changes" array of short notes describing what you changed.
  1. Нажмите Save.
  2. Откройте чат Roleplay, включите Enable Agents в Chat Settings и добавьте агента из раздела Custom Agents.

После каждого ответа агент возвращает такой JSON:

{"editedText":"The colour of the harbour caught her eye.","changes":[{"description":"color to colour, harbor to harbour"}]}

Marinara подставляет editedText в ответ. Заметки из changes показываются как короткая сводка.

Импорт и экспорт агентов

Чтобы экспортировать одного агента, нажмите Export agent (иконка загрузки) в верхней панели редактора. Файл содержит промпт и настройки агента, но никогда не содержит описаний своих инструментов. Чтобы экспортировать несколько агентов, нажмите Select agents (выбрать агентов) в панели Agents, отметьте нужных и экспортируйте их.

Импорт внешних агентов по умолчанию заблокирован.

  1. Откройте Settings → Advanced → Danger Zone (настройки → дополнительно → опасная зона) и включите Allow custom Agent imports (разрешить импорт своих агентов). Править .env не нужно.
  2. В панели Agents нажмите Import agents (импортировать агентов) и выберите файлы агентов или папку.
  3. Проверьте список разрешений, который показывает Marinara. Одобряйте только то, что агенту нужно. Неотмеченные возможности остаются заблокированными.

Эта блокировка касается только агентов из файлов, папок и своих репозиториев. Агенты, которых вы создали сами, и официальные агенты из Agent Organizer (организатор агентов) работают как обычно. Каждый импортированный файл получает новый собственный идентификатор, поэтому не может заменить официального агента.

Для безопасности Marinara игнорирует вложенные функции, стирает выбор инструментов, очищает временный CSS и проверяет одобренные возможности, прежде чем импортированный агент сможет менять сообщения, трекеры, лорбуки, фоны, спрайты, медиа, тактильные устройства, данные About Me, промпты или изображения. Доверенные функции импортируйте отдельно, проверьте их и сами подключите к агенту. Если выключить переключатель в Danger Zone, импортированные агенты перестанут работать.

Вопросы активации

Вопрос активации спрашивает, нужен ли ваш агент в последней сцене. Он ловит перефразировки, которые пропускают ключевые слова. Для него нужна Decision model (модель решений) – небольшая модель, которая отвечает на вопросы "да или нет". Выберите ее в панели Connections. См. Модели решений. Если у Decision model стоит значение None (нет), как по умолчанию, поля вопроса остаются недоступными, а агент с вопросом работает так, будто вопроса нет.

  1. Откройте своего агента.
  2. Введите Question (вопрос) длиной до 500 символов. В нем работают макросы {{user}} и {{char}}.
  3. В поле Run when probability is at least (запускать при вероятности не ниже) задайте порог для этого агента. Агент запускается, когда вероятность ответа "да" достигает порога, поэтому чем выше значение, тем больше запусков пропускается. Редактор показывает рекомендуемое значение для вашей модели: 0,5 для локальных моделей чата и аккаунтов Decision или 0,1 для встроенных моделей Open-Jev. После смены модели проверьте порог на своих чатах. См. Пороги.
  4. Необязательно: задайте Bypass the question after this many messages without a successful run (пропустить вопрос после такого числа сообщений без успешного запуска). После этого числа сообщений вопрос пропускается, поэтому модель, которая все время отвечает "нет", не сможет заглушить агента навсегда. Ключевые слова и периодичность продолжают действовать.

Пишите вопрос как утверждение о последнем сообщении, например The latest message moves the scene to a new place. Небольшая модель отвечала на такую формулировку надежнее, чем на Did the scene change? См. Как писать утверждения.

Как это работает:

Вопросы активации есть только у своих агентов.

Утверждения решений в промпте агента

Вопрос активации решает, запускать ли агента. Утверждение решения в Prompt Template решает, какие инструкции получит работающий агент. Синтаксис описан в руководстве Условные промпты:

{{#if decision:"In the latest message, the characters move to a different location"}}
Update the location field.
{{else}}
Leave the location as it is.
{{/if}}

С их помощью в спокойные моменты можно отправлять промпт поменьше. Трекер может обновлять место действия, только когда оно изменилось. Агент изображений может описывать новую картинку, только когда изменилась сцена. Музыкальный агент может менять трек, только когда сменилось настроение. Чтобы выбрать один из нескольких наборов инструкций, используйте {{#if decision_choice:"The kind of scene in the latest message" == "combat"}}, затем {{else if decision_choice:"The kind of scene in the latest message" == "dialogue"}} и так далее. См. Условные промпты.

Агенты, установленные из Marinara-Agents, обрабатывают промпты так же.

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