Инструменты и MCP

В предыдущем уроке по взаимодействию с API мы рассмотрели, как заставить большую языковую модель (LLM) вызывать внешние API. Чтобы улучшить пользовательский опыт, OSMI-AI предоставляет список готовых инструментов. Полный список доступных интеграций можно найти в разделе Инструменты .

Если нужный вам инструмент еще отсутствует, вы можете создать настраиваемый инструмент Пользовательский инструмент, чтобы соответствовать вашим требованиям.

Настраиваемый инструмент

Предположим, мы используем тот же сервер управления событиями Сервер управления событиями и создаем на его базе настраиваемый инструмент, который будет осуществлять POST-запрос на /events.

• Название инструмента: create_event
• Описание инструмента: Используйте этот инструмент, когда нужно создать новое событие.
• Схема ввода: JSON-схема тела запроса API, которая позволяет LLM автоматически генерировать правильное JSON-уведомление.
• JavaScript-функция:: Это реальная функция, которая выполняется, когда вызывается данный инструмент:

const fetch = require('node-fetch');
const url = 'http://localhost:5566/events';
const options = {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: $name,
      location: $location,
      date: $date
    })
};
try {
    const response = await fetch(url, options);
    const text = await response.text();
    return text;
} catch (error) {
    console.error(error);
    return '';
}

Как использовать функцию::

• Можно использовать любые библиотеки, импортированные в OSMI-AI.
• Вы можете использовать свойства, указанные в Входной схеме, как переменные с префиксом $:
  • Свойство из Входной схемы = name
  • Переменная, используемая в функции = $name
• Вы можете получить значение конфигурации по умолчанию для потока:
  • $flow.sessionId
  • $flow.chatId
  • $flow.chatflowId
  • $flow.input
  • $flow.state
• Дополнительные переменные:: $vars.<variable-name>
• Обязательно: функция должна возвращать строковое значение.

Использовать пользовательского инструмента в Агенте

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

В выпадающем списке Tool выберите созданный инструмент. Можно включить опцию Return Direc, чтобы сразу возвращать вывод инструмента.

Использование как Инструмента

Также инструмент можно применить как узел Tool в заданном сценарии. В этом случае:

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

MCP

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

Настраиваемый MCP

Помимо предустановленных MCP-инструментов, можно подключиться к любому MCP-серверу по выбору. Архитектура MCP:

• Хосты: LLM-приложения (например, OSMI-AI), инициирующие соединения.
• Клиенты: поддерживают 1:1 соединения внутри хост-приложения (например, через собственный MCP).
• Сервера: предоставляют контекст, инструменты и подсказки для клиентов.

Поддерживаемые механизмы передачи данных:

1. Stdio (стандартные ввод/вывод):

• Использует стандартный ввод/вывод для коммуникации
• Идеально для локальных процессов

2. Streamable HTTP:

• Использует HTTP с опциональными серверными событиями для потоковой передачи данных
• HTTP POST для сообщений от клиента к серверу

Stdio

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

Используйте его только при работе с OSMI-AI-AI локально, а не при развертывании в облачных сервисах. Это связано с тем, что при запуске команд, таких как npx, будет устанавливаться пакет MCP-сервера (например,@modelcontextprotocol/server-sequential-thinking) локально, и это занимает много времени.

Этот механизм больше подходит для настольных приложений, таких как Claude Desktop, VS Code и др.

Команда для NPX

{
  "command": "npx",
  "args": [
    "-y",
    "@modelcontextprotocol/server-sequential-thinking"
  ]
}

Для Windows смотрите руководство.

Docker (контейнеризация)

Подходит, если у машины с OSMI-AI есть доступ к Docker. Не рекомендуется для облачных развертываний с ограниченным или отсутствующим доступом к Docker.

{
  "command": "docker",
  "args": [
    "run",
    "-i",
    "--rm",
    "mcp/sequentialthinking"
  ]
}

Docker предоставляет список MCP-серверов, который можно найти здесь. Вот как это работает:

1. Убедитесь, что Docker запущен.
2. Найдите конфигурацию MCP-сервера и добавьте ее в Custom MCP.
3. При первой попытке запустить, Docker автоматически загрузит последнюю версию образа. После загрузки, у вас появится список доступных действий.

Unable to find image 'mcp/sequentialthinking:latest' locally
latest: Pulling from mcp/sequentialthinking
f18232174bc9: Already exists
cb2bde55f71f: Pull complete
9d0e0719fbe0: Pull complete
6f063dbd7a5d: Pull complete
93a0fbe48c24: Pull complete
e2e59f8d7891: Pull complete
96ec0bda7033: Pull complete
4f4fb700ef54: Pull complete
d0900e07408c: Pull complete
Digest: sha256:cd3174b2ecf37738654cf7671fb1b719a225c40a78274817da00c4241f465e5f
Status: Downloaded newer image for mcp/sequentialthinking:latest
Sequential Thinking MCP Server running on stdio

Когда использовать MCP

• Создание командных утилит
• Локальные интеграции
• Простое межпроцессное взаимодействие
• Работа с shell-скриптами
• streamable HTTP (рекомендуется)

Потоковый HTTP (рекомендуется)

Мы будем использовать Github Remote MCP в качестве примера. Прелесть удалённого сервера MCP на GitHub в том, что его не нужно устанавливать или запускать локально — обновления внедряются автоматически.

Шаг 1: Создайте переменную для PAT (личного токена доступа) GitHub

Чтобы получить доступ к серверу MCP, необходимо создать персональный токен доступа (PAT) на GitHub. См. руководство. После создания PAT создайте переменную для хранения этого токена. Эта переменная будет использоваться в Custom MCP.

Step 2: Создание Custom MCP

Создайте узел агента, и добавьте новый инструмент Custom MCP. Для потокового HTTP нам нужно просто ввести URL и другие необходимые заголовки. В конфигурации сервера MCP вы можете использовать параметры, заключённые в двойные фигурные скобки {{ }}, а также префикс $vars.<variableName>

{
  "url": "https://api.githubcopilot.com/mcp/",
  "headers": {
    "Authorization": "Bearer {{$vars.githubPAT}}",
  }
}

Шаг 3: Выберите действия

Если конфигурация сервера MCP работает правильно, вы можете обновить список Доступных действий, и OSMI-AI-AI автоматически подтянет все доступные действия с сервера MCP.

Пример взаимодействий:

Сделайте запрос: «Расскажи мне о самой последней проблеме»

Агент способен определить подходящие действия из MCP и использовать их для ответа на запрос пользователя.

Когда использовать

Используйте потоковый HTTP, когда:

• Создаёте веб-ориентированные интеграции
• Нужно взаимодействие клиент-сервер по протоколу HTTP
• Требуются сессионные состояния
• Поддерживаются несколько одновременных клиентов
• Реализуются возобновляемые соединения