Python v.2

Python v.2 — обновлённая версия Python Script

Скрипт, как и раньше, получает входные данные через args, а результат работы передаёт через переменную result, но теперь код стал ближе к обычному Python и лучше подходит для написания и поддержки пользовательских скриптов.

Основные изменения:

• Убраны дополнительные ограничения на импорт;

• Для логов можно использовать print(...);

• Добавлена возможность генерировать и редактировать Python Script с помощью ИИ (подробнее по ссылке);

• Скрипт может выполнять действия внутри Nextbot, а не только возвращать текстовый результат (подробнее);

• Добавлена инструкция для ИИ при работе с генерацией кода (подробнее по ссылке).

Скрипт позволяет:

• обращаться к внешним API через библиотеку requests;

• читать данные диалога, заявки и пользовательские переменные;

• управлять диалогом: отправлять сообщения, ставить на паузу, переключать агентов, уведомлять администратора и многое другое;

• изменять переменные и поля формы сбора данных (ссылка на документацию по форме сбора данных, ссылка на документацию по переменным).

Где подключается скрипт

Скрипт можно подключить в трёх контекстах:

Контекст	Где настраивается	Когда вызывается
function	Действие функции агента	Когда LLM вызывает tool
scenario	Шаг сценария	При срабатывании триггера сценария
personal_data_form	Обработка формы данных	При отправке формы пользователем

Что доступно

В среде выполнения доступны стандартная библиотека Python и следующие внешние пакеты:

• requests

• jsonpath-ng

• python-dateutil

• pytz

• jsonschema

• supabase==1.2.0

• gspread==5.12.0

• oauth2client==4.1.3

Подключение сторонних библиотек по согласованию (напишите в тех поддержку)

Как импортировать модули

Если Вам нужен модуль, импортируйте его стандартным способом:

import requests
import json
import re
from datetime import datetime, timezone

Состав полей в args зависит от:

• канала связи;

• подключённых интеграций;

• контекста вызова скрипта;

Для безопасного чтения всегда используйте args.get("ключ").

name = args.get("name")
city = args.get("city") or "Москва"

Всегда используйте args.get(...), а не args["ключ"].

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

Пользовательские переменные доступны в args.get("variables").

variables = args.get("variables") or {}
agent_vars = variables.get("agent") or {}
dialog_vars = variables.get("dialog") or {}

lead_score = dialog_vars.get("lead_score") or 0
client_name = dialog_vars.get("ClientName") or ""

Данные формы

Раздел актуален только для контекста personal_data_form.

form = dict(args.get("form_data") or {})
phone = form.get("phone")
email = form.get("email")

Обязательная переменная result

Для корректной работы скрипта, рекомендуем присвоить переменную result на каждой ветке выполнения.

Список доступных действий внутри Nextbot

Скрипт может вернуть простое значение, например строку, число, список или словарь. Такое значение будет использовано как результат функции.

Если нужен расширенный сценарий управления диалогом, верните structured contract — словарь со служебными полями.

Поле	Тип	Назначение
tool_result	str	Результат для LLM — модель строит ответ клиенту на его основе
send_message	str или dict	Прямое сообщение клиенту, минуя LLM
info_message	str	Служебная запись в диалоге
system_message	str	Контекст для модели с тегом python_script_context
variables	dict	Плоский патч переменных: {"ключ": значение}
form_data	dict	Патч полей формы, только для personal_data_form
silent	bool	Применить side-effects без ответа клиенту
pause	bool	Поставить диалог на паузу
resume	bool	Снять диалог с паузы
block_user	bool	Заблокировать пользователя
clear_dialog	bool	Очистить и перезапустить диалог
switch_agent	str или dict	Переключить на другого агента
handoff_to_operator	bool	Передать диалог оператору, только для Bitrix24
delayed_message	dict	Запланировать отложенное сообщение
cancel_delayed_messages	bool	Отменить все отложенные сообщения диалога
notify_admin	dict	Уведомить администратора
tags	list[str]	Добавить теги к диалогу

Примеры скриптов

Безопасный запрос к внешнему API

import requests

print("Начало выполнения функции")
print(f"Получены аргументы: {args}")

api_url = args.get("api_url") or "https://jsonplaceholder.typicode.com/posts/1"

try:
    print(f"Отправка HTTP-запроса к API: {api_url}")
    response = requests.get(api_url, timeout=10)
    response.raise_for_status()
    data = response.json()
    print(f"Получен ответ от API: {data}")

    processed_data = {
        "post_info": f"Заголовок: {data.get('title', '')}",
        "word_count": len((data.get("body") or "").split()),
    }

    print(f"Данные обработаны: {processed_data}")

    result = {
        "status": "success",
        "message": "Функция выполнена успешно",
        "processed_data": processed_data,
    }

except requests.RequestException as e:
    print(f"Ошибка при выполнении запроса: {str(e)}")
    result = {
        "status": "error",
        "message": str(e),
    }

print("Выполнение функции завершено")

Фоновое действие без ответа

result = {
    "silent": True,
    "variables": {"lead_checked": True},
    "tags": ["checked"],
}

Отложенное сообщение через 1 час

result = {
    "send_message": {"text": "Заявка принята! Менеджер свяжется с вами."},
    "delayed_message": {
        "message": "Напоминаем о вашей заявке. Чем можем помочь?",
        "delay_ms": 60 * 60 * 1000,
        "delete_after_user_message": True,
        "restriction_policy": "next_window_start",
        "restriction_policy_time": "09:00",
    },
    "tags": ["follow_up_scheduled"],
}

Передача оператору

result = {
    "handoff_to_operator": True,
    "pause": True,
    "tags": ["operator_handoff"],
    "notify_admin": {
        "messager": "telegram",
        "message": "Клиент запросил оператора.",
    },
}

Смена агента

result = {
        "switch_agent": {
            "agent_hash": "88725312-2b64-4bd2-8aaf-1e0c2fc571c5",
        },
        "tags": ["switched_by_python"],
        "tool_result": "Диалог переключён на другого агента"
}

Приоритет ответа клиенту

Платформа определяет ответ в следующем порядке:

1. Если задан send_message, сообщение отправляется напрямую, LLM не запускается.

2. Если задано silent: true, либо используется block_user или clear_dialog, клиенту ничего не отправляется, LLM не запускается.

3. Во всех остальных случаях tool_result передаётся в LLM для генерации ответа.

Типичные ошибки и решения

Ошибка	Причина	Решение
Не указан codeId для выполнения Python-скрипта	Скрипт не сохранён или не привязан к шагу	Откройте настройки функции или сценария, вставьте код и нажмите Сохранить
result не определён	Ветка кода не присваивает result	Добавьте присваивание result во все ветки if/else и try/except
KeyError: 'phone'	Используется args["phone"] вместо args.get("phone")	Всегда используйте args.get(...)
send_message не работает, клиент видит ответ LLM	Поле send_message не задано, используется tool_result	Проверьте, что используете именно send_message
Переменная не обновляется	Ключ переменной не существует в каталоге агента	Создайте пользовательскую переменную в Настройках агента
handoff_to_operator не работает	Bitrix24 не подключён	Действие работает только при подключённом Bitrix24
subprocess вызывает ошибку	Shell-команды запрещены в RestrictedPython	Используйте только встроенные модули Python
SyntaxError при сохранении или запуске	Ошибка в синтаксисе Python: лишняя/пропущенная скобка, кавычка или отступ	Проверьте код на наличие незакрытых скобок, кавычек и корректность отступов. Используйте «Генерацию кода с ИИ» — она подсветит проблему и предложит исправление.