Инструкция

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

 

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

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

 

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

 

 

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

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

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

 

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

 

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

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

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

 

 

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

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

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

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

 

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

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

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

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

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

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

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

 

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

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

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

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

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

 

Параметры 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. Для удаления параметра нажмите кнопку "✕" в строке параметра.

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

 

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

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

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

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

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

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

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

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

 

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

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

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

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

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

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

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

 

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. Убедитесь, что инструмент отмечен флажком в настройках ИИ-агента (вкладка "Настройки", раздел "Интеграция 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. Проверьте, что заполнены все обязательные поля (Название инструмента, Название функции, URL).

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

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

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