Подключение внешнего агента вместо обычной модели

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

Для такой работы к Open WebUI можно подключить внешнего агента через привычное административное соединение, совместимое с форматом OpenAI Chat Completions. Разберём этот маршрут на примере Hermes Agent. Он принимает сообщения из интерфейса и сам управляет шагами языковой модели и вызовами разрешённых инструментов. В окне чата такой агент выбирается почти так же, как обычная модель, однако чтение заметок, права доступа и история его работы устроены иначе.

Для упражнения нужен уже подготовленный защищённый шлюз Hermes, доступный серверу Open WebUI. Внесём реквизиты подключения и проверим обычное текстовое сообщение. Если инструмент чтения тоже подготовлен, отдельно проверим работу с учебными заметками. Установка агента, настройка сети и расширение полномочий выполняются заранее.

Кто читает заметки и выполняет действия

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

Обычные языковые модели в Open WebUI тоже могут работать с подключаемыми инструментами (Tools), когда сам веб-интерфейс или настроенные в нём расширения передают модели описания функций и обрабатывают их вызов. При подключении внешнего агента меняется место, где организован этот рабочий цикл. Open WebUI здесь выступает знакомым окном ввода и чтения ответа, но не управляет пошаговым выполнением инструментов.

В этой цепочке у среды, шлюза и модели разные роли:

• Среда выполнения агента (runtime) организует цикл работы на своей стороне: передаёт задачу своей языковой модели, принимает от неё решение о следующем шаге, запускает разрешённый инструмент и возвращает полученное наблюдение обратно модели.
• API-шлюз агента (gateway) принимает сетевые запросы Open WebUI в формате OpenAI Chat Completions и возвращает готовый ответ или поток сообщений.
• Модель внутри агента предлагает следующий шаг на основе вашей задачи и данных, которые ей вернула среда выполнения. Администратор настраивает её в Hermes; системные операции выполняет код среды, а не сама модель.

Когда вы выбираете внешнего агента в списке моделей и отправляете запрос, цепочка выглядит так:

1. Вы формулируете задачу в браузере, и сервер Open WebUI пересылает сообщения текущего диалога на API-шлюз (gateway) агента.
2. Запущенная среда (runtime) передаёт этот запрос своей внутренней модели. Если для ответа нужен инструмент и он разрешён в настройках среды, модель запрашивает действие, например чтение первой учебной заметки.
3. Исполняющий код на стороне Hermes проверяет доступ, выполняет чтение и передаёт текст заметки обратно модели. Увидев в тексте отсылку ко второй заметке, модель может запросить следующий шаг, прежде чем сформулировать окончательный ответ для Open WebUI.

Вся работа с файлами или командами в таком маршруте происходит там, где запущен сервер Hermes, а не в вашем браузере и не внутри контейнера Open WebUI. Если в запросе упоминается папка с учебными заметками, речь идёт о пути в файловой системе хоста или изолированного окружения самого агента. При этом обычный текстовый вопрос, не требующий чтения материалов, агент может обработать за один шаг и сразу вернуть ответ в чат. Какие именно действия возможны на практике, зависит от того, какие наборы инструментов (toolsets) и права учётной записи операционной системы подготовил администратор внешней среды.

Что нужно получить от администратора агента

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

Если готовой среды пока нет, подготовьте её отдельно по официальному руководству по быстрому старту Hermes Agent. По умолчанию API-сервер в Hermes выключен, а при стандартном включении слушает локальный интерфейс 127.0.0.1 и порт 8642.

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

• Базовый адрес API (Base URL), заканчивающийся на /v1, который проверен именно со стороны сервера (backend) Open WebUI.
• Ключ доступа к шлюзу (API Key), который в настройках Hermes задаётся как API_SERVER_KEY и передаётся в заголовке Authorization: Bearer …. Это ключ для входа в сам шлюз агента; у него другое назначение, чем у ключа провайдера языковой модели внутри Hermes. Используйте отдельный ключ доступа к шлюзу. Даже при локальном размещении на современном API-сервере Hermes требуется непустой надёжный ключ, в том числе для чтения списка моделей через /v1/models. Никогда не пересылайте этот ключ в тексте обычных сообщений чата и не публикуйте его на снимках экрана.
• Фактический идентификатор агента (Model ID), который возвращает этот шлюз, а также краткое описание того, какие инструменты сейчас включены и как оператор может подтвердить приём запроса по своим журналам.

Адрес шлюза должен быть достижим из серверной части Open WebUI. Проверки в браузере для этого недостаточно. Когда Open WebUI и Hermes работают в одном сетевом пространстве на одной машине, в документации встречается пример http://127.0.0.1:8642/v1. Но если Open WebUI запущен в Docker-контейнере, адрес localhost или 127.0.0.1 внутри настроек укажет на сам этот контейнер, а не на хост-систему с агентом. Замена имени на host.docker.internal не поможет сама по себе, если шлюз слушает только 127.0.0.1 или маршрут между контейнером и хостом не настроен. В этом уроке мы не перестраиваем сеть и не ослабляем защиту порта, а используем готовый адрес, который администратор уже проверил из среды Open WebUI.

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

Подключим Hermes к Open WebUI

Для выбранного маршрута нам не понадобятся специальные плагины, функции Pipes или установка отдельных сред вроде Open WebUI Computer и Open Terminal: готовый шлюз Hermes подключается через стандартное административное меню OpenAI-совместимых соединений, как описано в руководстве по подключению Hermes Agent в документации Open WebUI. Подписи кнопок и значки в интерфейсе могут немного различаться в зависимости от версии и выбранного языка локализации, поэтому будем ориентироваться на названия разделов и полей.

Откройте панель администратора Settings → Admin → Connections. В блоке соединений, совместимых с OpenAI (OpenAI / Manage OpenAI API Connections), нажмите кнопку добавления нового соединения (Add Connection, обычно со значком плюса) и заполните основные поля:

1. Включённое состояние соединения. Убедитесь, что переключатель активности нового подключения находится во включённом положении (Enabled).
2. Поле URL. Вставьте точный базовый адрес со стороны сервера Open WebUI, полученный от администратора, обязательно с суффиксом /v1 на конце.
3. Поле Auth и API Key. Оставьте способ авторизации Bearer и вставьте в поле ключа выданный вам API_SERVER_KEY от шлюза Hermes.
4. Поле API Type. Оставьте стандартное значение Chat Completions.
5. Поле Model IDs. Оставьте это поле пустым, чтобы Open WebUI автоматически запросил список доступных записей у шлюза через /v1/models. Поле Prefix ID в нашем минимальном примере тоже оставляем пустым.

На маршруте /v1/models шлюз публикует виртуальный идентификатор агента. Поэтому в Model IDs не нужно вписывать название языковой модели его провайдера. Для профиля по умолчанию в документации приводится пример hermes-agent, но если администратор настроил именованный профиль или собственные псевдонимы API, шлюз вернёт другое имя. Это не название модели для скачивания, а точка входа в конкретную конфигурацию агента. Если же вписать произвольный идентификатор в Model IDs вручную, Open WebUI просто подставит ваш ручной список вместо автоматического обнаружения. Когда на сервере много подключений и нужно развести совпадающие имена или настроить ручной каталог, используйте приёмы из урока про управление списком моделей и их источниками.

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

Проверим и сохраним подключение:

1. В окне редактирования соединения нажмите кнопку проверки связи (Verify Connection). При этой проверке сервер Open WebUI отправляет авторизованный запрос GET <Base URL>/models (то есть /v1/models для нашего адреса) и читает ответ шлюза. Успешное уведомление само по себе не гарантирует корректный каталог: проверьте, появилась ли ожидаемая запись агента.
2. Нажмите Save, чтобы сохранить настройки. Сохранение через интерфейс администратора записывает конфигурацию в базу данных Open WebUI и сбрасывает внутренний кэш списка моделей; перезапускать контейнер, удалять тома данных или менять переменные окружения для этого не нужно.
3. Сразу после сохранения снова откройте только что созданную запись в разделе Connections. Убедитесь, что соединение остаётся включённым, параметры не сбросились, и посмотрите, какое значение отображается в поле Connection Type (Local или External). Не пытайтесь угадать этот тип по названию агента или виду IP-адреса: проверяйте именно фактическое значение в сохранённом окне.
4. Прежде чем открывать чат с агентом, перейдите в Settings → Admin → Interface → Tasks. В поле, которое соответствует фактическому Connection Type вашего нового соединения (Local Task Model или External Task Model), выберите уже проверенную обычную языковую модель и сохраните страницу. Не оставляйте здесь Current Model и не выбирайте запись самого агента Hermes в качестве фоновой модели.

Успешное уведомление при нажатии Verify Connection подтверждает только то, что сервер Open WebUI достучался до маршрута /v1/models с вашим ключом. Оно ещё не доказывает, что внутренняя модель агента отвечает на сообщения или что инструменты настроены верно. Проверим сам диалог на следующем шаге.

Убедимся, что запрос дошёл до агента

Соединение сохранено, а служебные задачи в Tasks закреплены за обычной моделью. Теперь проверим, что выбранная запись возвращает полный ответ и запрос принимает нужный шлюз Hermes. Никакие файлы и папки в этой обязательной проверке не участвуют.

Выполним проверку в новом диалоге:

1. Откройте новый обычный текстовый чат и в выпадающем списке моделей выберите фактический идентификатор агента, который появился после подключения шлюза (например, hermes-agent или то имя профиля, которое сообщил вам администратор).
2. Отправьте короткое проверочное сообщение, связанное с подготовкой к нашей встрече, и добавьте в него простую несекретную метку, чтобы запрос было легко узнать по времени. Например: «Проверка связи перед встречей, метка Маршрут-1. Ответь одним коротким предложением, что сообщение получено.»
3. Дождитесь, пока ответ полностью отобразится в окне чата. Во время ожидания Hermes может передавать в поток промежуточные пометки о ходе работы, но полагаться только на появление первого кадра потока или на то, что собеседник в тексте назвал себя Hermes, нельзя. Нам нужен полностью завершённый ответ без сообщения об ошибке выполнения.

Разделим то, что мы видим на экране, и то, что можно считать подтверждением маршрута:

• Что подтверждает экран браузера. Полный ответ в чате показывает, что выбранная запись в списке моделей принимает сообщения Chat Completions и возвращает текст обратно в Open WebUI.
• Как подтвердить приём на целевом шлюзе. Чтобы убедиться, что запрос обработал именно подготовленный экземпляр Hermes, попросите администратора сопоставить время вашего сообщения (и несекретную метку, если используемый способ наблюдения её показывает) с доступными журналами или другими записями самого шлюза. Стандартный журнал сервера не обязан сохранять полный текст вашего сообщения, и специально включать отладочное логирование содержимого чатов для этого урока не нужно: достаточно любого штатного наблюдения оператора, подтверждающего приём запроса этим шлюзом в нужный момент. Если доступ к журналам оператора сейчас отсутствует, зафиксируйте более скромный вывод: мы подтвердили получение полного текстового ответа через выбранное подключение в интерфейсе, но не проверяли внутреннюю трассировку на стороне шлюза.

При ошибке определите, на каком уровне остановилась проверка. Удалять данные Open WebUI не требуется:

• Не проходит Verify Connection или список моделей пуст. Возможны проблемы сетевого доступа от сервера Open WebUI к /v1/models, ключа API_SERVER_KEY или формата каталога. Пустой список также может быть связан с выключенным соединением, ручным каталогом или ограничениями видимости записи. Исправьте опечатку в URL или API Key прямо в окне соединения администратора либо уточните у оператора, запущен ли процесс шлюза и доступен ли адрес из сети сервера Open WebUI.
• Запись агента выбрана, но в чате возвращается ошибка генерации. Возможны проблемы внутренней модели, провайдера или выполнения на стороне Hermes, но также проверьте фактический ID, адрес, ключ и доступность соединения: успешное чтение каталога раньше не гарантирует успешного следующего запроса. Сопоставьте сообщение об ошибке с наблюдением оператора шлюза.

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

Проверим чтение учебных заметок, если инструмент уже готов

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

Границы доступа задаются в среде агента. Дополнительные указания из системного промпта Open WebUI добавляются к собственным инструкциям Hermes, но не отключают его инструменты, память или навыки. Фраза в чате «ничего не изменяй» выражает ваше намерение, но не создаёт техническую песочницу. В упражнении мы работаем с одним доверенным тестовым окружением.

Ограничения API описаны в руководстве по интеграции Hermes Agent с Open WebUI. Совместимость с Chat Completions не означает одинаковую поддержку всех функций интерфейса. Например, текущий API-сервер Hermes принимает текст и встроенные изображения, но не поддерживает прямую передачу файлов и документов (file / input_file / document uploads) в сам запрос к этому шлюзу. У Open WebUI есть собственные механизмы обработки документов. В этом упражнении агент читает файлы, которые уже лежат в его рабочей среде Hermes. Поэтому прикреплять файлы к сообщению в чате не нужно.

Отправьте в чат с выбранным агентом учебный запрос (при необходимости подставьте точное название подготовленной папки, которое дал администратор):

«Прочитай разрешённые учебные заметки в папке, которую указал администратор агента. Собери открытые вопросы к встрече и для каждого назови исходную заметку. Ничего не изменяй и не отправляй».

Проверим действие отдельно от текста ответа:

1. Цикл с обратной связью. В описанном учебном сценарии результат чтения первой заметки даёт модели основание запросить вторую. Проверьте именно эту связь: повлияли ли полученные материалы на дальнейший шаг и итоговые вопросы.
2. Проверка фактического действия. Уверенный тон ответа, перечисление похожих на правду вопросов и даже промежуточные статусы в потоке чата сами по себе не доказывают, что инструмент чтения действительно вызывался. С другой стороны, отсутствие подробной визуальной трассировки или кнопок подтверждения в интерфейсе Open WebUI тоже не означает, что агент ничего не делал, так как веб-интерфейс отображает не все специфические события внешнего сервера. Чтобы подтвердить само действие, сначала сверьте вместе с оператором по доступным наблюдениям среды Hermes, что во время запроса действительно выполнялись обращения к инструменту чтения для этой папки, а затем вручную сопоставьте итоговые вопросы и названные источники с текстом самих учебных заметок. Если чтение не состоялось, отдельно выясните по наблюдениям оператора, вызывался ли инструмент и завершилось ли чтение успешно. Неудачный вызов не равен отсутствию вызова. Сообщение агента о недоступном материале не следует выдавать за выполненное чтение.

История диалога и границы доступа также требуют отдельного внимания:

• История чата и память агента живут раздельно. При каждом сообщении Open WebUI передаёт шлюзу историю текущего диалога. При этом собственные профили, долговременная память, подключённые наборы инструментов (toolsets) и внутреннее состояние сессий находятся на стороне Hermes. Новый чат начинает отдельный диалог в Open WebUI. Ни создание нового чата, ни удаление старой беседы в интерфейсе не доказывают, что все следы работы или память удалены во внешней среде агента.
• Общее соединение само по себе не создаёт изоляцию пользователей на стороне агента. Административное подключение подчиняется правилам доступа к моделям Open WebUI. Однако общий ключ API_SERVER_KEY не создаёт каждому пользователю отдельный профиль, учётную запись ОС или песочницу Hermes. Эти границы задаются в конфигурации внешней среды.

Теперь мы умеем различать три разных уровня проверки: появление записи агента в каталоге после /v1/models, получение полного текстового ответа через шлюз и подтверждённое выполнение инструмента во внешней среде. Оставьте настроенное соединение для согласованных задач, а любые изменения доступных папок, инструментов или прав всегда начинайте с настройки самой среды агента у её администратора. В следующем уроке мы посмотрим, чем от таких серверных настроек отличаются личные и прямые подключения, которые настраиваются на стороне браузера.