Встроенные функции

Agent Platform предоставляет встроенные функции, которые позволяют управлять диалогом, взаимодействовать с базами данных и интеграциями, отправлять HTTP-запросы и многое другое.

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

Встроенные коллекции

Коллекция	Назначение
AgentContext	Управлять общим контекстом и отдельными контекстами агентов
Asr и Tts	Распознавать и синтезировать речь
Context	Получать метаданные, подробную информацию о запросе пользователя, отслеживать состояние процесса
Credentials	Получать учетные данные для интеграций
Db и SessionDb	Работать с базами данных
Dialer	Управлять входящими звонками
Email	Отправлять email-сообщения
Http	Выполнять HTTP-запросы
Llm	Взаимодействовать с языковыми моделями
Log	Записывать сообщения в журнал
ProjectRouter	Взаимодействовать с другими проектами Agent Platform и JAICP
Rag	Работать с базами знаний RAG
Reactions	Отправлять ответы клиенту в подключенном канале
Telegram	Отправлять сообщения в Telegram без подключения канала

AgentContext

Функции для работы с контекстом. Подробнее смотрите в статье Управление контекстом агента.

• addNote(text, [agentId]) — добавляет текстовую заметку в контекст указанного агента, а если агент не указан — в общий контекст. Заметка должна быть непустой: если она состоит только из пробельных символов, то добавлена не будет.
• getNotes([agentId]) — возвращает все заметки из общего контекста и контекста агента (если указан), объединенные в одну строку, в порядке добавления.
• deleteNotes([agentId]) — удаляет все заметки из контекста указанного агента, если указано all — из всех контекстов, а если параметр не указан — из общего контекста.
• putValue(key, value, [agentIds]) — сохраняет значение по ключу в контекст каждого из указанных агентов, а если агенты не указаны — в общий контекст.
• getValue(key, [agentId]) — получает значение по ключу. Если указан агент, сначала ищет в его контексте, затем в общем.
• deleteValue(key, [agentId]) — удаляет значение по ключу из контекста указанного агента, если указано all — из всех контекстов, а если параметр не указан — из общего контекста.
• clearContext([agentId]) — удаляет контекст (все ключи и заметки) указанного агента, если указано all — все контексты, а если параметр не указан — общий контекст.

Asr и Tts

Для работы этих функций нужно подключить интеграции: Модель ASR и Голос TTS.

• Asr.recognize — получает файл по URL и распознает речь в нем.
• Tts.synthesize — синтезирует речь из текста и возвращает URL, по которому можно скачать аудиофайл.

Подробнее о работе с этими функциями читайте в статье ASR и TTS в текстовых каналах.

Context

• Получайте различные метаданные процесса:

  JavaScript	Python	Описание
  getAccountId	get_account_id	ID вашего аккаунта Agent Platform.
  getProjectShortName	get_project_short_name	Короткое имя проекта.
  getBotId getChannelType isAsyncChannel isTestChannel	get_bot_id get_channel_type is_async_channel is_test_channel	ID и тип канала.
  getChatId	get_chat_id	Идентификатор диалога.
  getSessionId	get_session_id	Идентификатор текущей сессии.
  getClientInfo	get_client_info	Информация о пользователе, который взаимодействует с процессом.

• Получайте подробную информацию о запросе пользователя:

  JavaScript	Python	Описание
  getRequestId	get_request_id	ID запроса.
  getMessageContent	get_message_content	Контент сообщения.
  getRawRequest	get_raw_request	Полные данные запроса.
  getEmailContent	get_email_content	Данные письма при использовании триггера IMAP Email.

• Управляйте диалогом:

  JavaScript	Python	Описание
  getChatHistory	get_chat_history	История сообщений в диалоге.
  getLastFunctionResult	get_last_function_result	Результат последнего вызова функции в процессе.
  getLastStateError	—	Информация о последней ошибке в рамках сессии. Используйте для обработки ошибок (не поддерживается для движка версии 1).
  resetSession	reset_session	Запустить новую сессию, очистить данные SessionDb и историю сообщений (не поддерживается для движка версии 1).

• Сохраняйте и получайте значения по ключу (не поддерживаются для движка версии 1):

  JavaScript	Python	Описание
  set	set	Сохраняет значение по ключу. Ключ можно затем использовать в подстановках.
  get	get	Возвращает сохраненное значение по ключу.

примечание

В пользовательских Python-функциях и блоке Код доступны встроенные функции sdk.context.*. Названия функций соответствуют используемым в JavaScript с переводом в snake_case.

Пример: sdk.context.get_channel_type().

Credentials

Получайте учетные данные для интеграций из хранилища с помощью функции get вместо непосредственной вставки в код.

Db и SessionDb

С помощью Db вы можете работать с базами данных, которые вы добавили в разделе Интеграции или Базы данных.

Функции из коллекции SessionDb работают аналогично, но не требуют настройки интеграции с БД и обрабатывают данные только в рамках текущей сессии. При вызове Context.resetSession() данные SessionDb очищаются.

• Получайте данные:

  • get — получить запись по ключу.
  • findByFilters — найти одну или несколько записей по заданным фильтрам.
  • countByFilters — получить количество записей, которые соответствуют фильтрам.

• Добавляйте и изменяйте данные:

  • put — добавить новую запись в базу.
  • updateByFilters — обновить поля в записях, которые соответствуют фильтрам.

• Удаляйте данные:

  • delete — удалить запись по ключу.
  • deleteByFilters — удалить все записи, которые соответствуют фильтрам.

Dialer

Функции для входящих звонков:

• Получение данных:

  • getCaller — получить номер телефона клиента.
  • getSipHeaders — получить SIP-заголовки звонка.
  • getTransferStatus — получить статус перевода на оператора.

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

  • hangUp — завершить вызов. Если ассистент общается в текстовом канале, вы можете отправить клиенту сообщение через необязательный параметр text.
  • setNoInputTimeout — задать время ожидания ответа от клиента.
  • transferCall — перевести вызов на оператора.

примечание

Остальные функции Dialer предназначены для исходящих звонков и сейчас не поддерживаются.

Email

Отправляйте email-сообщения с помощью функции send.

Http

• Функции для вызова HTTP-методов:

  • get
  • post
  • put
  • delete
  • patch

• execute — функция, в которой вы можете выбрать HTTP-метод сами.

Llm

• getChatHistory — получайте историю сообщений в специальном формате для LLM.

• sendRequest — отправляйте запрос в LLM. В качестве аргументов передайте модель, историю сообщений, доступные инструменты и параметры генерации. Если модель поддерживает структурированный вывод, передайте в параметре responseFormat JSON-схему в формате OpenAI Structured Outputs.

  примечание

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

  Пример responseFormat

  {
    "type": "object",
    "properties": {
      "priority": {
        "type": "string",
        "enum": ["low", "medium", "high", "critical"]
      },
      "issue_description": { "type": "string" },
      "device": {
        "type": "string",
        "enum": ["web", "android", "ios", "unknown"]
      }
    },
    "required": ["priority", "issue_description", "device"],
    "additionalProperties": false
  }

• sendText — отправляйте простые текстовые запросы к LLM.

• summarizeText — сокращайте длинные тексты до заданного размера с сохранением ключевой информации. Поддерживаются тексты до 200 000 символов.

Log

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

Вы можете добавлять в журнал сообщения разных уровней. Смотрите результаты на вкладке Выполнение.

ProjectRouter

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

• callProject — вызов другого проекта и JAICP. Ответ другого проекта не отправляется клиенту, а обрабатывается в исходном проекте. Подробнее смотрите в разделе Вызов другого проекта.
• switchTo — передача управления в другой проект и JAICP. Позволяет другому боту вести диалог с клиентом. Новый бот может вернуть диалог исходному боту с помощью backToOriginalProject. Подробнее смотрите в разделе Передача управления в другой проект.
• backToOriginalProject — вернуть управление в исходный проект.
• getCustomData — извлечь данные, полученные при передаче или возврате управления.

к сведению

JAICP (Just AI Conversational Platform) — платформа для разработки диалоговых решений любой сложности. Подробнее о JAICP можно узнать на нашем сайте или в документации.

Rag

Используйте интеграцию с базой знаний RAG:

• retrieveChunks — получить фрагменты документов, релевантные запросу пользователя.
• generateAnswer — сгенерировать ответ на вопрос пользователя с помощью RAG.

Reactions

Отправляйте сообщения клиентам в подключенных каналах:

JavaScript	Python	Описание
sendText	send_text	Текстовое сообщение.
sendHtml	send_html	Сообщение в разметке HTML.
sendAudio	send_audio	Аудио.
sendImage	send_image	Изображение.
sendVideo	send_video	Видео.
sendFile	send_file	Файл.
sendLocation	send_location	Геолокация.
sendRawRequest	send_raw_request	Данные для ответа в формате, который поддерживает канал.

примечание

В пользовательских Python-функциях и блоке Код доступны встроенные функции sdk.reactions.*. Названия функций соответствуют используемым в JavaScript с переводом в snake_case.

Параметры передаются в виде Python-словаря, ключи указываются в кавычках.

Пример: await sdk.reactions.send_text({"text": "Привет!"}).

примечание

Функции Reactions предназначены для коммуникационных процессов с триггером Сообщение. В workflow-триггерах (Вебхук, Планировщик, IMAP Email) сессия не привязана к каналу или клиенту, поэтому Reactions не доставят сообщение.

Подробнее о работе триггеров читайте в соответствующей статье документации.

Telegram

Отправляйте сообщения в Telegram без подключения канала. В каждой функции укажите учетные данные с токеном Telegram-бота. Эти функции можно использовать вместо Reactions, например, в следующих случаях:

• Вы в процессе динамически определяете, какой Telegram-бот должен написать пользователю.
• Вы получили запрос от пользователя в одном Telegram-боте, но хотите отправить ответ из другого бота.
• Вы используете workflow-триггер (Вебхук, Планировщик, IMAP Email) и хотите отправить уведомление в конкретный Telegram-чат.

Функции:

• sendText — отправить текстовое сообщение.
• sendImage, sendAudio, sendVoice — отправить изображение, аудио или голосовое сообщение.
• sendButtons — отправить сообщение с кнопками.

Синхронность функций

JavaScript

Синхронность или асинхронность встроенных функций зависит от версии движка в проекте.

Версия 2

Встроенные функции являются:

• синхронными, если вызываются из блока Код или из пользовательских функций в коллекциях без npm-зависимостей;
• асинхронными, если вызываются из пользовательских функций в тех коллекциях, где подключены npm-зависимости.

Версия 1

Большинство встроенных функций являются асинхронными. Вы можете вызывать их с помощью await.

Синхронными являются только следующие функции:

• Context:

  • getAccountId
  • getProjectShortName
  • getBotId
  • getChannelType
  • isAsyncChannel
  • isTestChannel
  • getChatId
  • getSessionId
  • getClientInfo
  • getRequestId
  • getMessageContent
  • getRawRequest
  • getEmailContent
  • getLastFunctionResult

• Dialer:

  • getCaller
  • getSipHeaders
  • hangUp
  • setNoInputTimeout
  • transferCall
  • getTransferStatus

Python

• Функции sdk.context.*, кроме get_chat_history(), являются синхронными.
• Функции sdk.reactions.* и sdk.context.get_chat_history() являются асинхронными. Вы можете вызывать их с помощью await.