AIAgent

Тег AIAgent позволяет создавать и настраивать AI-агентов. Агенты используют LLM, чтобы гибко поддерживать диалог и обрабатывать любые запросы пользователей.

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

state: Start
    q!: $regex</start>
    a: Чем могу помочь?

state: Translation
    q!: * переведи *
    # Агент, который будет переводить текст
    AIAgent:
        id = translator_agent
        # LLM, которую использует агент
        model = gpt-4o
        # Роль в диалоге
        role = Профессиональный переводчик
        # Цель в диалоге
        goal = Переведи текст на другой язык
        # Инструкции для агента
        instructions = Если нужно, уточни у пользователя целевой язык. Дай 3 лучших варианта перевода
        # Агент перейдет в стейт /Start, если у пользователя больше нет вопросов
        nextState = /Start

Чтобы начать работу:

1. Настройте подключение к Caila.
2. Укажите параметры тега.
3. Используйте тег в сценарии.

LLM для агента

Чтобы обращаться к LLM, агент использует сервис openai-proxy на платформе Caila.

предупреждение

Вы можете использовать LLM только в платном тарифе Caila.

Добавьте токен в JAICP, чтобы начать работу.

Токен доступа к Caila

Для использования сервисов и генеративных моделей из Caila в сторонних приложениях, в том числе JAICP, нужен персональный токен доступа. Чтобы выпустить токен:

1. Перейдите в Caila.

   подсказка

   Caila и Conversational Cloud использует общую базу аккаунтов, поэтому если вы зарегистрированы в Conversational Cloud, дополнительно регистрироваться в Caila не нужно.

2. Перейдите на страницу Мое пространство → API-токены.

3. В правом верхнем углу нажмите Создать токен.

4. Придумайте имя токена, сгенерируйте его и скопируйте в буфер обмена.

Далее добавьте токен в JAICP:

1. Перейдите в JAICP.

2. В разделе Токены и переменные добавьте новый токен:

   • Название — LLM_API_KEY.
   • Значение — полученный токен Caila.

   Вы также можете дать токену любое другое название. В этом случае укажите его название в файле chatbot.yaml в секции injector.LLM_API_KEY_SECRET_NAME:

   injector:
     LLM_API_KEY_SECRET_NAME: "MY_API_KEY"

Параметры

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

Параметр	Тип	Описание	Обязательный
id	Строка	Идентификатор агента. Каждый агент в сценарии должен иметь уникальный идентификатор. предупреждение В одном стейте может быть только один тег AIAgent.	Да
model	Строка	Укажите LLM, которую будет использовать агент. Чтобы обращаться к LLM, агент использует сервис openai-proxy на платформе Caila. Вы можете посмотреть доступные модели и их стоимость на странице сервиса. Часть параметров тега можно использовать, только если LLM поддерживает function calling — агент сам может вызвать нужные функции в сценарии. Такие параметры отмечены лейблом function calling. Список моделей, которые поддерживают function calling, смотрите в документации OpenAI. примечание Сайт OpenAI недоступен для российских IP-адресов.	Да
role	Строка	Роль или персона агента в диалоге. Например: Сотрудник банка. Влияет на тон общения и на то, как агент отвечает на вопросы о себе.	Да
goal	Строка	Цель агента. Например: Помоги пользователю сделать заказ. В диалоге агент будет пытаться выполнить цель.	Да
instructions	Строка	Инструкции для агента. Используйте, чтобы задать поведение агента. Пример: Отвечай только на языке пользователя. Сначала уточни, правильно ли ты понял вопрос.	Нет

подсказка

Иногда LLM может давать неожиданные ответы или сообщать неточные данные.

Мы рекомендуем подробно заполнять параметры role, goal и instructions. Так вы сможете получать более предсказуемые и стабильные результаты.

Настройки LLM

Параметр	Тип	Описание	Обязательный
temperature	Число	Регулирует креативность ответов. При высоких значениях результаты будут творческими и менее предсказуемыми. Не рекомендуем менять параметры temperature и topP одновременно. Принимает значения от 0.0 до 2.0. По умолчанию: 1.0. Рекомендуемое: 0.6.	Нет
topP	Число	Регулирует разнообразность ответов. При низких значениях нейросеть выбирает из меньшего количества вероятных слов, а при высоких — ответ может получиться разнообразнее. Не рекомендуем менять параметры topP и temperature одновременно. Принимает значения от 0.0 до 1.0. По умолчанию: 1.0. Рекомендуемое: 1.0.	Нет
frequencyPenalty	Число	Штраф за частоту слов и фраз. Чем выше значение, тем меньше вероятность появления слов и фраз, которые уже встречались в ответе несколько раз. Принимает значения от -2.0 до 2.0. По умолчанию: 0.0. Рекомендуемое: 0.0.	Нет
presencePenalty	Число	Штраф за повтор слов и фраз. Чем выше значение, тем меньше вероятность повторов в ответе. Все повторы штрафуются одинаково, независимо от частоты. Принимает значения от -2.0 до 2.0. По умолчанию: 0.0. Рекомендуемое: 0.0.	Нет
maxTokens	Число	Максимальное количество токенов, которое модель может сгенерировать за одну итерацию. Рекомендуемое значение: 4000.	Нет

Вы можете подробнее узнать об этих параметрах в документации OpenAI.

примечание

Сайт OpenAI недоступен для российских IP-адресов.

Получение данных и вызов функций

Параметр	Тип	Описание	Обязательный
function calling requiredData	Массив объектов	Данные, которые агент должен узнать у пользователя.	Нет
function calling functions	Массив строк	Агент сможет вызывать эти функции в сценарии.	Нет

База знаний RAG

Параметр	Тип	Описание	Обязательный
knowledgeBase	Строка	Название токена для базы знаний. Агент будет получать информацию из этой базы знаний.	Нет
knowledgeBaseConfidence	Число	Уверенность базы знаний. Агент будет получать только те фрагменты текста (чанки) из базы знаний, для которых оценка релевантности выше этого значения. Укажите значение от 0.0 до 1.0. Рекомендуемое: 0.8.	Нет

Подробнее о работе агента и подключении базы знаний смотрите в статье Использование базы знаний.

История и дополнительные данные

С помощью этих параметров вы можете передать историю сообщений и дополнительные данные в агента. Это позволит агенту учитывать контекст диалога.

Параметр	Тип	Описание	Обязательный
chatHistoryEnabled	Логический	Если true, агент получит историю диалога с ботом.	Нет
chatHistoryLimit	Число	Количество последних сообщений, которые агент получит из истории диалога с ботом. По умолчанию: 50.	Нет
context	Объект	Дополнительные данные, которые может использовать агент. Могут быть в любом формате.	Нет

Переход в стейты

Если пользователь находится в диалоге с агентом:

• По умолчанию бот может перейти в другой стейт только по глобальным интентам и паттернам.
• Бот не будет реагировать на события.

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

Параметр	Тип	Описание	Обязательный
function calling nextState	Строка	Бот перейдет в этот стейт, если агент считает цель выполненной и у пользователя больше нет вопросов.	Нет
function calling noMatchState	Строка	Бот перейдет в этот стейт, если агент считает, что запрос пользователя не относится к цели.	Нет
intentConfidence	Число	Пороговое значение для интентов и паттернов в сценарии. Если указано, то для каждого запроса к агенту: Бот выполняет $nlp.match относительно корня сценария /. Если вес совпадения с интентом или паттерном больше порогового значения, то бот переходит в такой стейт.	Нет
function calling llmClassificationEnabled	Логический	Если true, агент сможет сам переводить диалог в другие стейты с тегом AIAgent. При выборе стейта агент учитывает: Роли и цели других агентов — параметры role и goal. Названия стейтов, которые содержат агентов. предупреждение В одном стейте может быть только один тег AIAgent. Мы рекомендуем давать стейтам названия, которые сильно отличаются друг от друга. Агент может чаще ошибаться, если в сценарии есть стейты с похожими названиями, например: NoMatch1 и NoMatch2.	Нет

Использование в сценарии

Аналитика

Агент проставляет следующий комментарий для каждой фразы пользователя: Фраза обработана тегом AIAgent.

В разделе Аналитика → Диалоги → Фразы по этому комментарию вы можете найти фразы, которые были обработаны агентом.

Пример

В этом примере показан бот, который помогает пользователю создать заявку на выпуск карты.

/src/main.sc

theme: /

    state: Start
        q!: $regex</start>
        script:
            // Создаем новую сессию
            $jsapi.startSession();
            // Указываем данные о пользователе
            $session.userData = {
                userId: 111111,
                userName: "Иван"
            };
        # Бот сразу переходит в стейт /Card
        go!: /Card

    state: Card
        # Агент, который оформляет банковские карты
        AIAgent:
            id = card_application
            model = gpt-4o
            role = Сотрудник банка
            goal = Помоги пользователю открыть карту
            instructions = Отвечай на языке пользователя
            # Для открытия карты нужны возраст, город и телефон пользователя
            requiredData =
                [
                  {
                      "name":"userAge",
                      "type":"number",
                      "description":"Возраст пользователя",
                      "reasonForQuestion":"Оформить карту могут только совершеннолетние"
                  },
                  {
                      "name":"userCity",
                      "type":"string",
                      "description":"Город пользователя",
                      "condition":"Только если пользователю уже есть 18 лет",
                      "dependsOn":"userAge"
                  },
                  {
                      "name":"userPhone",
                      "type":"string",
                      "description":"Телефон пользователя",
                      "condition":"Только если пользователю уже есть 18 лет",
                      "dependsOn":"userAge"
                  }
                ]
            # Агент может вызвать функцию, чтобы создать заявку на карту
            functions = ["createCardApplication"]
            # Передаем данные о пользователе в качестве контекста
            context = {{JSON.stringify($session.userData)}}
            chatHistoryEnabled = true
            # Бот перейдет в /Feedback, если агент выполнит цель
            nextState = /Feedback

    state: Feedback
        InputText:
            prompt = Оцените работу бота
            varName = feedback

/src/function-specs.js

import customFunctions from './scripts/custom-functions.js'

export default {
    createCardApplication: {
        description: "Создать заявку на выпуск банковской карты",
        confirmation: {
            confirmationPhrase: "Создать заявку на открытие карты для номера {userPhone}?",
            yesPattern: "* $yes *",
            noPattern: "* $no *"
        },
        parameters: {
            type: "object",
            properties: {
                city: {
                    type: "string",
                    description: "Город, например, Москва",
                },
                age: {
                    type: "number",
                    description: "Возраст пользователя",
                },
                phone: {
                    type: "string",
                    description: "Телефон пользователя",
                }
            },
            required: ["city", "age", "phone"]
        },
        function: customFunctions.createCardApplication
    },
};

/src/scripts/custom-functions.js

export default {
    createCardApplication: ({city, age, phone}) => {
        // …
        $reactions.answer("Номер заявки: 12345")
    }
}

В начале диалога пользователь попадает в стейт Card:

1. Агент спросит у пользователя возраст. Если пользователь моложе 18 лет, агент сообщит, что не может оформить карту.
2. Если пользователю уже есть 18 лет, агент узнает город и телефон пользователя.
3. Агент попросит подтверждение перед созданием заявки на карту.
4. Если пользователь подтвердит, агент вызовет функцию createCardApplication и сообщит о создании заявки.
5. Так как цель достигнута, агент переведет диалог в nextState — в стейт Feedback.

подсказка

В сценарии вы можете использовать сразу несколько агентов. Смотрите пример в статье Продвинутые возможности.