Инструкция

Инструкции/Чат-бот/MCP инструменты

 

Раздел "MCP инструменты" (Model Context Protocol) предназначен для создания и управления внешними функциями, которые могут использоваться ИИ-агентами для выполнения различных действий и получения данных из внешних систем.

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

 

  • MCP-инструмент — внешняя функция, доступная для вызова ИИ-агентом через Model Context Protocol.
  • Внешний HTTPS — инструмент, реализованный в виде HTTP-запроса к внешнему API.
  • Внутренний — инструмент, реализованный внутри системы (например, получение текущей даты).
  • Функция — конкретное действие, которое выполняет инструмент (например, "Получение информации по ЛС").
  • Промпт инструмента — описание для ИИ-агента, объясняющее, когда и как использовать данный инструмент.
  • Параметры инструмента — входные данные, необходимые для выполнения функции (например, номер ЛС).
  • Действие — операция, выполняемая MCP-инструментом (например, отправка сообщения ИИ-агенту или запись значения в произвольное поле).
  • Условие действия — логическое выражение, определяющее, при каких условиях действие будет выполнено.
  • Параметры ответа — пары «имя — значение», которые сохраняются из ответа ИИ-агента и могут использоваться в условиях выполнения последующих действий.

 

 

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

В таблице отображаются все созданные MCP-инструменты с колонками:

  • Название инструмента — понятное имя, идентифицирующее функцию.
  • Тип — способ реализации инструмента ("Внешний HTTPS" или "Внутренний").
  • Статус — включен или отключен.
  • Действие — кнопка редактирования.

 

Таблица списка MCP инструментов

 

1. Выделение инструментов: Установите флажки в первом столбце таблицы или используйте главный флажок в заголовке для выделения всех.

2. Добавление нового инструмента: Нажмите синюю кнопку "Добавить" в верхней панели.

3. Удаление инструментов: Выделите инструменты и нажмите красную кнопку "Удалить" (потребуется подтверждение).

 

 

Вкладки редактирования

При создании или редактировании MCP-инструмента доступны две вкладки:

1. "Общее" — основная информация об инструменте и его базовые настройки.

2. "Настройки" — детальные параметры функции, включая название функции, промпт, URL, метод, параметры, заголовки, параметры HTTP-запроса и блок «Действия».

 

Вкладка 'Общее' MCP инструмента

Основные настройки инструмента:

1. Название инструмента — имя инструмента (обязательное поле). Должно быть понятным и отражать суть функции.

2. Описание функции — подробное описание того, что делает инструмент, для администраторов системы.

3. Тип инструмента — выбор способа реализации:

  • Вызов внешней функции по HTTPS (Внешний HTTPS) — инструмент обращается к внешнему API через HTTP-запросы.
  • Вызов внутренней функции (Внутренний) — инструмент использует встроенные функции системы (например, получение текущей даты).

При выборе типа «Внутренний» на вкладке «Настройки» автоматически скрываются разделы, относящиеся к HTTPS-запросам (URL, метод, заголовки, параметры HTTP-запроса). Остаются только основные настройки функции, параметры инструмента и действия. При переключении на «Внешний HTTPS» эти разделы появляются снова.

4. Статус — включение/отключение инструмента.

 

Вкладка 'Настройки' MCP инструмента

Основные настройки функции:

1. Название функции — техническое имя функции (обязательное поле). Используется для идентификации в коде и логах.

2. Описание-инструкции, когда использовать инструмент (Промпт) — текстовое описание для ИИ-агента, объясняющее назначение инструмента и условия его применения.

Пример: "Используй этот инструмент, когда пользователь спрашивает информацию по лицевому счету. Для работы требуется номер ЛС, который нужно извлечь из вопроса пользователя."

 

Состав вкладки «Настройки» зависит от выбранного типа инструмента:

  • Для типа «Внешний HTTPS» отображаются все разделы: «Параметры HTTPS-инструмента» (URL, метод), «Заголовки запроса», «Параметры для передачи в HTTP-запрос», а также «Параметры инструмента» и «Действия».
  • Для типа «Внутренний» разделы, связанные с HTTPS, скрываются. Остаются только «Основные настройки инструмента», «Параметры инструмента» и «Действия».

 

Раздел отображается только для типа «Вызов внешней функции по HTTPS (Внешний HTTPS)».

Параметры HTTPS-инструмента

Настройки HTTP-запросов:

1. URL — адрес эндпоинта внешнего API (обязательное поле). Например: https://api.example.com/v1/account/info.

2. Метод — выбор HTTP-метода для запроса:

  • GET — получение данных.
  • POST — создание данных или выполнение действия.
  • PUT — полное обновление данных.
  • DELETE — удаление данных.
  • PATCH — частичное обновление данных.
  • OPTIONS — получение информации о доступных методах.
  • HEAD — получение только заголовков ответа.

 

Параметры инструмента

Здесь определяются входные параметры, которые ИИ-агент должен передать в инструмент.

Поля параметра:

  • Имя — название параметра (например, "account_number", "date_from") (обязательное поле).
  • Тип — тип данных: string, number, boolean, object.
  • Обязательное — флажок, указывающий, является ли параметр обязательным для передачи.
  • Описание — пояснение для ИИ-агента, что означает этот параметр и как его получить.

Управление параметрами:

1. Нажмите кнопку "+" в нижней части таблицы для создания нового параметра.

2. Для удаления параметра нажмите кнопку "✕" в строке параметра.

Примечание: Поле "Описание" помогает ИИ-агенту правильно извлекать значения из запросов пользователей.

 

Раздел отображается только для типа «Вызов внешней функции по HTTPS (Внешний HTTPS)».

Заголовки запроса

Настройка HTTP-заголовков, которые будут отправляться вместе с запросом к внешнему API.

Поля заголовка:

  • Имя — название заголовка (например, "Authorization", "Content-Type").
  • Значение параметра — значение заголовка (например, "Bearer token123", "application/json").

Управление заголовками:

1. Нажмите кнопку "+" в нижней части таблицы для создания нового заголовка.

2. Для удаления заголовка нажмите кнопку "✕" в строке заголовка.

Часто используемые заголовки: Authorization (аутентификация), Content-Type (формат данных), Accept (ожидаемый формат ответа).

 

Раздел отображается только для типа «Вызов внешней функции по HTTPS (Внешний HTTPS)».

Здесь настраиваются параметры, которые будут переданы в HTTP-запросе (для GET-запросов — в URL, для POST — в теле запроса).

Поля параметра запроса:

  • Имя — название параметра запроса (например, "limit", "offset").
  • Значение параметра — значение, которое будет передано.

Управление параметрами запроса:

1. Нажмите кнопку "+" в нижней части таблицы для создания нового параметра.

2. Для удаления параметра нажмите кнопку "✕" в строке параметра.

Для GET-запросов параметры автоматически добавляются в URL в формате ?param1=value1&param2=value2. Для POST/PUT запросов параметры передаются в теле запроса.

 

В нижней части вкладки «Настройки» расположен блок «Действия». Он позволяет задать последовательность операций, которые выполняет MCP-инструмент после вызова или в рамках своей внутренней логики.

Таблица списка MCP инструментов

Таблица действий содержит колонки:

  • № — порядок действия. Строки можно перетаскивать за иконку сортировки.
  • Тип действия / Данные — выбранное действие и его параметры.
  • Кнопки управления — копирование и удаление действия.

Для каждого действия можно раскрыть блок «Условия для действия». Если условия не заданы, отображается «Нет». Нажмите «Добавить условие», чтобы настроить выполнение действия только при определённых условиях.

Доступные типы действий:

  • Отправить и получить ответ ИИ-агента — передаёт сообщение указанному ИИ-агенту и получает ответ. Настройки:
    • Укажите сообщение для ИИ-агента — текст запроса. Можно использовать шаблоны: параметры инструмента, основные параметры, параметры чата, параметры пользователей, произвольные поля и др.
    • ИИ-агент — выбор агента, который обработает сообщение.
    • Добавочная инструкция для ИИ-агента — дополнительное указание, используется при необходимости различных условий.
    • Состояние после ответа LLM — состояние, которое будет выполнено после получения ответа.
    • Параметры ответа — пары «Имя» и «Значение параметра», которые нужно сохранить из ответа. Значения можно вставлять из шаблонов, например {question_id}.
  • Установить значение в произвольном поле — записывает значение в выбранное произвольное поле. Настройки:
    • Выберите произвольное поле — поле пользователя, клиента или временное поле.
    • Укажите значение — значение для записи. Поддерживаются шаблоны, например {q_id}.

Для добавления нового действия нажмите кнопку «+» в строке «Добавить действие». Для копирования действия используйте кнопку с иконкой копирования, для удаления — с иконкой минуса.

Примечание: порядок действий в таблице определяет последовательность их выполнения. Используйте перетаскивание строк, чтобы изменить порядок.

 

1. Сохранить: Нажмите синюю кнопку "Сохранить" в верхней панели для сохранения всех настроек и создания/обновления инструмента.

2. Назад: Нажмите серую кнопку "Назад" для возврата к списку без сохранения изменений.

При нажатии "Назад" система предупредит о несохраненных изменениях.

 

 

Связь между модулями

Созданные MCP-инструменты используются ИИ-агентами для расширения их функциональности.

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

1. Вы создаете MCP-инструмент и настраиваете его параметры (URL, метод, заголовки, параметры).

2. В настройках ИИ-агента на вкладке "Настройки" в разделе "Интеграция MCP инструментов" отмечаете нужные инструменты.

3. ИИ-агент получает доступ к инструменту и понимает, когда и как его использовать через описание в промпте.

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

 

Что настраивается в ИИ-агенте:

В разделе ИИ-Агенты → Вкладка "Настройки" для каждого агента можно подключить:

  • Выбор MCP-инструментов — отмечаются флажками доступные инструменты.
  • Описание использования — в системных инструкциях (промпте) агента можно уточнить, когда и как использовать инструменты.

Важно: Без правильного описания в промпте агент может не понять, в каких случаях следует вызывать инструмент, или может использовать его некорректно.

 

 

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

2. Единый стиль: Используйте единый стиль именования для всех инструментов в системе.

3. Функциональное описание: В поле "Описание функции" подробно описывайте, что делает инструмент и для каких задач предназначен.

4. Группировка: Логически группируйте инструменты по функциональности (получение данных, создание, обновление, удаление).

 

1. Четкое описание: Указывайте точные условия, когда инструмент должен использоваться.

2. Примеры использования: Приводите примеры запросов пользователей, при которых нужно вызывать инструмент.

3. Параметры: Описывайте, какие параметры и как извлекать из запроса пользователя.

4. Обработка ошибок: Указывайте, что делать, если инструмент вернул ошибку или недоступен.

Пример: "Используй этот инструмент, когда пользователь спрашивает статус заказа. Извлеки номер заказа из запроса и передай его как параметр 'order_id'. Если заказ не найден, сообщи пользователю об этом и предложи проверить номер."

 

1. Безопасность: Используйте HTTPS для защиты передаваемых данных. Никогда не передавайте чувствительные данные в открытом виде.

2. Аутентификация: Для защищенных API используйте заголовки с токенами (Authorization). Храните токены в безопасном месте.

3. Таймауты: Убедитесь, что внешний API отвечает достаточно быстро, чтобы агент не зависал в ожидании.

4. Обработка ошибок: Настройте корректную обработку HTTP-ошибок (4xx, 5xx) в логике агента.

 

1. Минимализм: Добавляйте только необходимые параметры. Избыточность усложняет использование.

2. Понятные имена: Называйте параметры так, чтобы их назначение было очевидно (account_number, user_id, date_from).

3. Типизация: Указывайте корректные типы параметров (string, number, boolean) для правильной обработки.

4. Обязательность: Отмечайте обязательные параметры, чтобы ИИ-агент понимал, без каких данных инструмент не сможет работать.

5. Описания: Заполняйте поле "Описание" параметра — это помогает ИИ-агенту правильно извлекать значения из запросов.

 

1. Последовательность: Выстраивайте действия в логическом порядке — сначала подготовка данных, затем отправка запросов и обработка ответов.

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

3. Параметры ответа: Сохраняйте из ответов ИИ-агента только те значения, которые действительно нужны для дальнейшей логики.

4. Произвольные поля: Для сохранения промежуточных данных используйте временные поля, чтобы не засорять поля пользователя.

5. Тестирование: Проверяйте сценарии с несколькими действиями и условиями — так проще выявить ошибки в порядке выполнения.

 

 

Инструмент не вызывается ИИ-агентом:

1. Проверьте статус инструмента — должен быть "Включено".

2. Убедитесь, что инструмент отмечен флажком в настройках ИИ-агента (вкладка "Настройки", раздел "Интеграция MCP инструментов").

3. Проверьте промпт инструмента — возможно, описание недостаточно четкое для ИИ-агента.

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

 

Инструмент вызывается, но возвращает ошибку:

1. Проверьте URL — убедитесь, что адрес корректный и доступен.

2. Проверьте метод — соответствует ли он тому, что ожидает API.

3. Проверьте параметры инструмента — все ли обязательные параметры передаются и правильного ли они типа.

4. Проверьте заголовки — корректно ли настроена аутентификация (Authorization).

5. Проверьте логи системы на наличие деталей ошибки HTTP-запроса.

 

Инструмент работает медленно:

1. Проверьте задержку ответа внешнего API — возможно, проблема на стороне поставщика.

2. Оптимизируйте количество параметров в запросе.

3. Рассмотрите возможность кэширования часто запрашиваемых данных.

4. Убедитесь, что инструмент выполняет только необходимые действия, без лишних операций.

 

Инструмент не видит переданные параметры:

1. Проверьте имена параметров — они должны совпадать с теми, которые ожидает внешний API.

2. Убедитесь, что параметры настроены с правильным типом (string, number, boolean).

3. Проверьте, что в промпте правильно указано, как извлекать параметры из запроса пользователя.

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

 

Действия не выполняются:

1. Проверьте порядок действий — возможно, нужное действие расположено после действия, которое прерывает выполнение.

2. Проверьте условия для действия — если условие не выполняется, действие будет пропущено.

3. Убедитесь, что для действия «Отправить и получить ответ ИИ-агента» выбран корректный ИИ-агент и состояние после ответа LLM.

4. Проверьте параметры ответа — имена и шаблоны должны быть указаны без ошибок.

5. Для действия «Установить значение в произвольном поле» проверьте выбранное поле и корректность значения.

6. Проверьте логи выполнения инструмента и ИИ-агента.

 

Ошибки при сохранении настроек:

1. Проверьте, что заполнены все обязательные поля (Название инструмента, Название функции, URL).

2. Убедитесь, что URL корректен и содержит протокол (http:// или https://).

3. Проверьте, что имена параметров не содержат специальных символов и пробелов.

4. Если ошибка сохраняется — попробуйте сохранить настройки по одной вкладке за раз.