Перейти к основному содержимому

Пользовательские функции

Пользовательские функции — это мощный инструмент для расширения стандартных возможностей платформы. Они позволяют вам писать собственный код на JavaScript или Python для решения уникальных задач: от сложных вычислений до интеграции со сторонними API.

Каждая созданная вами функция становится многоразовым компонентом, который можно использовать в качестве отдельного шага в процессе, в виде инструмента для AI-агента, а также вызывать из кода. Подробнее об этом в разделе Использование функций в процессе.

JavaScript и Python​

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

  • JavaScript-функции и Python-функции не могут вызывать друг друга.
  • Внутри одной пользовательской коллекции все функции должны быть написаны на одном языке.
подсказка
  • Если вам нужен доступ ко всем встроенным коллекциям, используйте JavaScript. В Python пока доступны только reactions и context.
  • Если вам необходимы библиотеки из экосистемы Python, выбирайте Python.

Коллекции​

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

// Вызов функции myFunction из коллекции MyCollection
MyCollection.myFunction();

Пользовательские функции можно добавить только в пользовательские коллекции. Если в проекте еще нет таких коллекций, потребуется создать коллекцию при добавлении функции. Для JavaScript- и Python-функций требуется создать отдельные коллекции.

Вся коллекция на холсте

Чтобы добавить сразу все функции коллекции на холст, просто перетащите туда коллекцию.

Создание и настройка функции​

Создание пользовательской функции включает несколько шагов:

  1. Добавление функции.
  2. Настройка параметров.
  3. Написание кода.
  4. Добавление зависимостей.
  5. Тестирование в редакторе.

Добавление функции​

Добавить функцию можно в левом меню или непосредственно на холсте — эти способы эквивалентны.

  1. В левом меню выберите , затем нажмите Добавить → функцию.

  2. Выберите или создайте коллекцию.

    Для новой коллекции заполните поля:

    • Название коллекции для отображения в интерфейсе. Должно быть уникальным среди пользовательских коллекций.
    • Идентификатор коллекции для использования в коде. Должен быть уникальным в рамках проекта и не может совпадать со встроенными коллекциями.
    • Язык — JavaScript (по умолчанию) или Python. Язык фиксируется для всей коллекции.
    • Описание для отображения на странице Функции.

  3. Для новой функции заполните поля:

    • Название функции для отображения в интерфейсе.
    • Идентификатор функции для использования в коде.
    • Описание — особенно важно, если функция будет использоваться в качестве инструмента для AI-агента. Помогает агенту понять, для чего следует вызывать эту функцию.

  4. Нажмите Сохранить. После сохранения откроется окно настроек функции.

Настройка параметров​

Если вы только что создали функцию, редактор параметров откроется автоматически. Чтобы открыть настройки созданной ранее функции, используйте один из способов:

  1. В левом меню выберите
  2. На странице Функции нажмите .

На вкладке Параметры укажите:

  • Параметры функции:

    • Тип параметра. Поддерживаются как простые типы (string, number, boolean), так и структуры (object, array) до 5 уровней вложенности.
    • Название для использования в коде.
    • Описание — помогает AI-агенту понять, что именно следует передавать в параметре.
    подсказка

    Вы можете загрузить параметры в виде JSON-схемы: нажмите Импортировать и скачайте образец.

  • Описание ответа: помогает AI-агенту правильно интерпретировать результат работы функции.

Параметры пользовательской функции

Написание кода​

На вкладке Код напишите тело функции. Встроенный редактор поддерживает подсветку синтаксиса, автодополнение, подсказки при наведении на функцию и отображение ошибок.

Код пользовательской функции

Чтобы быстро добавлять в свой код вызовы функций — как встроенных, так и пользовательских, и MCP, используйте панель функций:

  • Чтобы открыть панель и посмотреть доступные функции, нажмите .
  • Чтобы вставить вызов функции в код, дважды нажмите на ее название в панели.
  • Чтобы посмотреть описание и параметры функции, выберите ее в панели и нажмите .

Особенности и рекомендации:

  • Все пользовательские функции являются асинхронными (async). Это позволяет использовать в их коде await для асинхронных операций, например для выполнения HTTP-запросов с помощью fetch().
  • Не вставляйте учетные данные и другие секреты в код функции. Добавьте их в хранилище и используйте в коде с помощью встроенной функции Credentials.get(). Подробнее смотрите в разделе Учетные данные для интеграций.

Зависимости​

Если для работы вашего кода требуются внешние пакеты npm (например, axios или lodash) или Python (например, requests или pandas), добавьте их на вкладке Зависимости.

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

Подключение внешних npm-пакетов в JavaScript-коллекциях пока поддерживается только для движка версии 1.

Зависимости

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

примечание

Agent Platform использует версию Python 3.12. Библиотеки, которые используют конструкции, удаленные в Python 3.12, могут не работать.

Тестирование функции в редакторе​

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

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

Тестирование функции в редакторе доступно только для JavaScript-функций и только в проектах на движке версии 2.

Чтобы запустить тестирование:

  1. На вкладке Код нажмите .

  2. На вкладке Аргументы укажите входные значения.

  3. На вкладке Данные введите JavaScript-код, который создает мок-данные. Этот код будет выполнен перед тестовым запуском функции.

    Например, если внутри функции вызывается Context.getMessageContent().text, добавьте следующий объект:

    const Context = {
      getMessageContent: function() {
        return { text: "Тестовое сообщение от пользователя" };
      },
    };

    Когда функция вызовет Context.getMessageContent().text, она получит ответ из мок-данных.

  4. Включите опцию Запомнить значения для следующих запусков, чтобы аргументы и данные были доступны при следующем открытии редактора.

  5. Нажмите Запустить.

После тестирования:

  • В панели тестирования появится результат выполнения функции: возвращаемое значение или ошибка.
  • В нижней панели на вкладке Логи будут отображаться записи, которые функция вывела через console.log().