База знаний a25a

Провайдеры ИИ

Памятка: создание интеграции и навыка для использования в ИИ-чате

В a25a навыки чата реализуются как процессы из шагов, а каждый шаг — это вызов метода конкретной интеграции. Ниже краткая инструкция: где хранить файлы, как устроена схема, и каркас интеграции.

Структура файлов

• protected_files/client_files/integrations/<integration_slug>/schema.json — схема интеграции (описание действий и входов/выходов).
• protected_files/client_files/integrations/<integration_slug>/<ClassName>Integration.php — PHP-класс интеграции.
• Навык создаётся как команда канала с привязкой к process; шаги процесса используют действия интеграций.

Схема интеграции (schema.json)

Минимальный каркас:

{
  "name": "My Integration",
  "slug": "my_integration",
  "actions": [
    {
      "name": "doSomething",
      "title": "Сделать действие",
      "requires_ai": false,
      "inputs": [
        { "name": "query", "type": "text", "label": "Запрос", "required": true, "for_ai": true },
        { "name": "mode", "type": "select", "label": "Режим", "options": [
          {"value":"fast","label":"Быстро"}, {"value":"accurate","label":"Точно"}
        ], "default": "fast", "required": false, "for_ai": false }
      ],
      "provides": ["result"]
    }
  ]
}

• requires_ai: если true — провайдер ИИ подберётся системой автоматически.
• inputs:
  • name — ключ параметра; label — человекочитаемая подпись.
  • required — обязательность параметра.
  • for_ai — если true, параметр попадает в промпт и ожидается от пользователя/ИИ; если false — берётся из настроек/шагов и не запрашивается у пользователя.
  • type: text, number, textarea, select, checkbox.
  • default и options — для select/checkbox.
• provides — какие ключи вернёт действие в result.

Каркас PHP интеграции

<?php
class MyIntegration extends AbstractIntegration {
    public function __construct($settings = array()) {
        parent::__construct($settings);
    }

    public function getType() { return 'my_integration'; }

    public function execute($action, $params = array()) {
        switch ($action) {
            case 'doSomething':
                $query = isset($params['query']) ? trim($params['query']) : '';
                $mode  = isset($params['mode']) ? $params['mode'] : 'fast';
                if ($query === '') {
                    return array('success' => false, 'message' => 'query is required');
                }
                // ... логика ...
                return array('success' => true, 'result' => array('content' => 'ok'));
        }
        return array('success' => false, 'message' => 'Unknown action');
    }
}

Структура результата интеграции

• Базовый формат: { success: true|false, result?: object, message?: string }
• Рекомендуемые ключи в result:
  • content — текстовый ответ (plain text) для пользователя.
  • html — HTML-версия ответа (если нужно форматирование).
  • attachments — массив файлов/ссылок, если есть вложения.
  • Любые доменные данные: order, items, stats и т.д.
• Если возвращается только доменная структура — оркестратор может сформировать финальный текст через шаблон/ИИ.

Как оркестратор использует результаты

1. ИИ анализирует запрос пользователя и выбирает команду (навык) + собирает входы с for_ai=true.
2. Команда запускает процесс (pipeline шагов). Каждый шаг вызывает интеграцию и пишет свой промежуточный результат.
3. Финальный шаг возвращает { success, result }. Если есть result.content/html — они идут в ответ. Иначе — оркестратор формирует итог через подсказку ИИ, основываясь на result и логах.
4. Ответ сохраняется в историю сообщений и отправляется пользователю.

Создание навыка (команды) для чата

1. Создайте интеграцию и её schema.json.
2. Создайте процесс с шагами, где каждый шаг вызывает нужное действие интеграции.
3. Заведите команду канала (binding_type = process) и укажите input_schema_json или используйте схему шагов.
4. Для параметров, которые должен дать пользователь, ставьте for_ai: true — они попадут в промпт ИИ.

Где отображается и используется

• Оркестратор автоматически подставит описание канала, список команд и входы с for_ai=true в системный промпт.
• Параметры из настроек/предыдущих шагов (без for_ai) не будут требоваться у пользователя.

Интеграции

Создание интеграции и навыка (для ИИ-чата)

Навыки чата реализуются как процессы из шагов, где каждый шаг — вызов метода интеграции. Ниже — где хранить файлы, как устроена схема, каркас интеграции и как оркестратор использует результаты.

Структура файлов

• protected_files/client_files/integrations/<integration_slug>/schema.json — схема интеграции.
• protected_files/client_files/integrations/<integration_slug>/<ClassName>Integration.php — PHP-класс интеграции.
• Навык создаётся как команда канала с привязкой к process; шаги процесса используют интеграции.

Схема интеграции (schema.json)

{
  "name": "My Integration",
  "slug": "my_integration",
  "actions": [
    {
      "name": "doSomething",
      "title": "Сделать действие",
      "requires_ai": false,
      "inputs": [
        { "name": "query", "type": "text", "label": "Запрос", "required": true, "for_ai": true },
        { "name": "mode", "type": "select", "label": "Режим", "options": [
          {"value":"fast","label":"Быстро"}, {"value":"accurate","label":"Точно"}
        ], "default": "fast", "required": false, "for_ai": false }
      ],
      "provides": ["result"]
    }
  ]
}

Каркас PHP интеграции

<?php
class MyIntegration extends AbstractIntegration {
    public function __construct($settings = array()) { parent::__construct($settings); }
    public function getType() { return 'my_integration'; }
    public function execute($action, $params = array()) {
        switch ($action) {
            case 'doSomething':
                $query = isset($params['query']) ? trim($params['query']) : '';
                $mode  = isset($params['mode']) ? $params['mode'] : 'fast';
                if ($query === '') { return array('success' => false, 'message' => 'query is required'); }
                return array('success' => true, 'result' => array('content' => 'ok'));
        }
        return array('success' => false, 'message' => 'Unknown action');
    }
}

Структура результата интеграции

• Базовый формат: { success: true|false, result?: object, message?: string }
• Рекомендуемые ключи внутри result: content (plain text), html (форматированный вывод), attachments (вложения), а также доменные данные (например, items, stats).

Как это работает в навыке (процессе)

• Шаги процесса выполняются последовательно; каждый шаг пишет свой ответ в контекст процесса.
• Результаты предыдущих шагов доступны в следующих шагах через подстановки, например {{step1.result.product_id}} или {{step2.result}}.
• Поля for_ai=true попадают в системный промпт и ожидаются от пользователя/ИИ. Остальные берутся из настроек/контекста.
• Финальный ответ шага/процесса используется оркестратором: если есть result.content/result.html — они идут пользователю; иначе оркестратор формирует ответ на основе данных результата.

Навыки

Каналы

Чаты

Общие настройки

Раздел: Поддержка и информация

На этой странице собраны инструменты для связи с нашей службой поддержки, а также важная информация о вашей версии продукта и доступных обновлениях.

Частые вопросы (FAQ)

Здесь мы собрали ответы на самые популярные вопросы о работе a25a.