> For the complete documentation index, see [llms.txt](https://doc.nextbot.ru/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.nextbot.ru/functional/python-script/nastroika-i-testirovanie-skripta.md).

# Настройка и тестирование скрипта

Как подготовить функцию, сценарий или форму, добавить Python Script, получить код и проверить его тестом и в живом диалоге.

В этой статье вы пройдёте весь путь: подготовите функцию, сценарий или форму, добавите действие Python Script, получите код и проверите его тестом и в живом диалоге. Писать код самому не обязательно: его можно получить с помощью ИИ.

## Где добавить скрипт

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

{% tabs %}
{% tab title="Функция" %}

1. Создайте функцию и задайте её параметры — данные, которые агент передаст скрипту, например номер заказа. Как это сделать — в статьях [«Создание функции»](https://doc.nextbot.ru/functional/functions/create-function.md) и [«Параметры функций»](https://doc.nextbot.ru/functional/functions/function-parameters.md). Если функция уже есть, откройте её.
2. Прокрутите страницу до блока **«Действия»** и нажмите **«Добавить действие»**.
3. В разделе **«Интеграции и внешние сервисы»** выберите **Python Script**.
4. Нажмите на добавленное действие. Откроется окно **«Выберите шаблон Python Script»** — о нём в разделе [«Выберите шаблон»](#vyberite-shablon).

<figure><img src="https://2593311972-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fef2EBU68XAlye1NtG8DF%2Fuploads%2Fgit-blob-8feea61e7cb52962bc5eb8834957263bf4021c79%2Fpython-script-v-funkcii.png?alt=media" alt="Окно «Выберите действие» в функции, действие Python Script в группе «Интеграции и внешние сервисы» выделено рамкой"><figcaption><p>В функции действие называется «Python Script»</p></figcaption></figure>

Пока код не сохранён, рядом с действием стоит отметка **«Ошибка»**.

В функцию можно добавить только один Python Script. Если он уже есть, в списке действий его не будет.

{% hint style="warning" %}
**В функции скрипт выполняется после её интеграций:** CRM, календаря, счёта. Поэтому то, что посчитал скрипт, в эти интеграции в том же вызове не попадёт. Если в CRM нужно значение, которое считает скрипт, разделите работу на две функции: первая считает и записывает результат в переменную диалога, вторая оформляет заказ и берёт значение из этой переменной.
{% endhint %}
{% endtab %}

{% tab title="Сценарий" %}

1. Создайте сценарий или откройте существующий. Как это сделать — в статье [«Как настроить сценарий»](https://doc.nextbot.ru/functional/scenarii/kak-nastroit-scenarii.md).
2. Прокрутите страницу до блока **«Действия»** и нажмите **«Добавить действие»**.
3. В разделе **«Интеграции и внешние сервисы»** выберите **«Python скрипт»**.
4. Откроется окно **«Выберите шаблон Python Script»** — о нём в разделе [«Выберите шаблон»](#vyberite-shablon).

<figure><img src="https://2593311972-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fef2EBU68XAlye1NtG8DF%2Fuploads%2Fgit-blob-8ae4bb9a10d70f86979dbdf493ec5182a2264687%2Fpython-script-v-scenarii.png?alt=media" alt="Окно «Выберите действие» в сценарии, действие «Python скрипт» в группе «Интеграции и внешние сервисы» выделено рамкой"><figcaption><p>В сценарии действие называется «Python скрипт»</p></figcaption></figure>

Когда код будет готов, сохраните его, а затем сам сценарий: без сохранения сценария скрипт в нём не появится.

Скрипт выполнится, когда сработает сценарий, в порядке действий ветки.
{% endtab %}

{% tab title="Форма персональных данных" %}

1. Добавьте в функцию действие **«Форма персональных данных»** или откройте функцию, где оно уже есть. Как настроить форму — в статье [«Форма персональных данных»](https://doc.nextbot.ru/functional/functions/sending-result/forma-personalnykh-dannykh.md).
2. Внизу действия найдите блок **«Действия после отправки формы»**.
3. Нажмите **«Добавить действие»** и выберите **Python Script**.
4. Откроется окно **«Выберите шаблон Python Script»** — о нём в разделе [«Выберите шаблон»](#vyberite-shablon).

<figure><img src="https://2593311972-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fef2EBU68XAlye1NtG8DF%2Fuploads%2Fgit-blob-cd23e0a3b5ab06213d7bacd204594bf06cd6cefe%2Fpython-script-v-forme.png?alt=media" alt="Окно «Выберите действие после отправки формы», действие Python Script выделено рамкой"><figcaption><p>Python Script среди действий после отправки формы</p></figcaption></figure>

Пока код не сохранён, рядом с действием стоит отметка **«Не настроено»**.

Скрипт выполнится, когда клиент отправит форму, до сохранения данных.
{% endtab %}
{% endtabs %}

## Выберите шаблон <a href="#vyberite-shablon" id="vyberite-shablon"></a>

Шаблон — стартовый код, которым заполнится редактор. Так не придётся начинать с пустого поля.

<figure><img src="https://2593311972-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fef2EBU68XAlye1NtG8DF%2Fuploads%2Fgit-blob-cd841817fb3f9562ef8d5dc7b7e498b6dff8d264%2Fpython-script-vybor-shablona.webp?alt=media" alt="Окно «Выберите шаблон Python Script»: список шаблонов, выбран «Базовый скрипт», внизу кнопка «Использовать шаблон»"><figcaption><p>Окно выбора шаблона: 1 — шаблон, 2 — кнопка «Использовать шаблон»</p></figcaption></figure>

1. Найдите в списке шаблон под свою задачу (1). Если подходящего нет или код у вас уже есть, выберите **«Базовый скрипт»**.
2. Нажмите **«Использовать шаблон»** (2). Код появится в редакторе.

Какие шаблоны есть и для каких задач они подходят — в статье [«Шаблоны Python Script»](https://doc.nextbot.ru/functional/python-script/shablony-python-script.md).

## Из чего состоит редактор

<figure><img src="https://2593311972-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fef2EBU68XAlye1NtG8DF%2Fuploads%2Fgit-blob-950ee685ee756ca671440fde43d74a86ec10d0d6%2Fpython-script-redaktor-nomera.png?alt=media" alt="Редактор Python Script, элементы отмечены цифрами 1–8: поле кода, «Версия», «Сгенерировать с ИИ», «Инструкция для AI», «Запросить библиотеку», «Сбросить код», «Сохранить», «Тестовые аргументы»"><figcaption><p>Редактор Python Script. Цифры 1–8 соответствуют строкам таблицы ниже</p></figcaption></figure>

| Элемент                       | Для чего нужен                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **1. Поле кода**              | Сюда вставляют код скрипта                                                                                                                                                                                                                                                                                                                                                                        |
| **2. «Версия»**               | Среда выполнения. Для новых скриптов оставьте **«Новый v2»**: он выбран по умолчанию. Если старый скрипт работает на версии **«Устаревший»**, не переключайте его без необходимости: код для старой версии может не заработать в новой. Инструкции к старой версии — в разделе [«Python Script v1 (Устаревшее)»](https://doc.nextbot.ru/functional/python-script/python-script-v1-ustarevshee.md) |
| **3. «Сгенерировать с ИИ»**   | Открывает панель **«Генерация кода с ИИ»**: опишите задачу словами, и ИИ предложит код. Подробнее — в статье [«Создание Python-скриптов с помощью ИИ»](https://doc.nextbot.ru/functional/python-script/sozdanie-python-skriptov-s-pomoshchyu-ii.md)                                                                                                                                               |
| **4. «Инструкция для AI»**    | Файл с описанием Python Script для внешней нейросети, например ChatGPT или Claude                                                                                                                                                                                                                                                                                                                 |
| **5. «Запросить библиотеку»** | Заявка на пакет, которого нет в среде выполнения. Подробнее — в статье [«Запрос библиотеки»](https://doc.nextbot.ru/functional/python-script/zapros-biblioteki.md)                                                                                                                                                                                                                                |
| **6. «Сбросить код»**         | Заменяет код в редакторе шаблоном по умолчанию. Несохранённые изменения пропадут, поэтому платформа сначала спросит подтверждение                                                                                                                                                                                                                                                                 |
| **7. «Сохранить»**            | Сохраняет код. Без сохранения скрипт в диалоге не сработает                                                                                                                                                                                                                                                                                                                                       |
| **8. «Тестовые аргументы»**   | Значения для тестового запуска и кнопка **«Запустить тест»**                                                                                                                                                                                                                                                                                                                                      |

Над полем кода показана стоимость вызова. Подробнее о ценах — в разделе [«Сколько это стоит»](https://doc.nextbot.ru/functional/python-script.md#skolko-eto-stoit) статьи «Python Script».

## Получите код <a href="#poluchite-kod" id="poluchite-kod"></a>

Теперь доработайте код шаблона под свою задачу. Выберите удобный способ:

* **С помощью ИИ.** Опишите задачу словами, и ИИ напишет код прямо в редакторе. Подходит, если вы не пишете на Python. Как это сделать — в статье [«Создание Python-скриптов с помощью ИИ»](https://doc.nextbot.ru/functional/python-script/sozdanie-python-skriptov-s-pomoshchyu-ii.md).
* **Самостоятельно.** Если вы знаете Python, правьте код в редакторе. Какие данные получает скрипт и что он может вернуть — в статье [«Как устроен Python-скрипт»](https://doc.nextbot.ru/functional/python-script/spravochnik-python-script-v2.md).
* **Готовым кодом.** Если код у вас уже есть, вставьте его вместо кода шаблона.

Когда код готов, нажмите **«Сохранить»** и переходите к тесту.

## Как протестировать скрипт <a href="#kak-protestirovat-skript" id="kak-protestirovat-skript"></a>

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

{% stepper %}
{% step %}

### Укажите тестовые аргументы

Под редактором раскройте блок **«Тестовые аргументы»**. В нём две группы полей:

* **«Свойства функции»** — параметры функции. Впишите значения, которые мог бы передать агент. Эта группа есть только у скрипта в функции.
* **«Системные переменные»** — данные диалога: даты, ссылка, мессенджер и другие. Они уже заполнены примерами. Меняйте их, только если скрипт их использует.

Кнопка **«Сбросить»** возвращает значения по умолчанию.
{% endstep %}

{% step %}

### Запустите тест

Нажмите **«Запустить тест»**. Скрипт выполнится полностью: если он отправляет запрос в CRM или другой сервис, запрос уйдёт. Тест оплачивается так же, как обычный вызов скрипта.
{% endstep %}

{% step %}

### Прочитайте результат

Ниже появится блок **«Результаты выполнения»**:

* **«Статус: success»** — скрипт выполнился. Под статусом — то, что скрипт вернул в `result`.
* **«stdout (print)»** — всё, что скрипт вывел через `print()`.
* **«stderr»** — сообщения, которые скрипт вывел через `print(..., file=sys.stderr)`. Блок появляется, только если такие сообщения есть.
  {% endstep %}
  {% endstepper %}

<figure><img src="https://2593311972-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fef2EBU68XAlye1NtG8DF%2Fuploads%2Fgit-blob-b38c2a1c15deb16896fbfd81d4844f1e6ca8aac2%2Fpython-script-test-uspeh.png?alt=media" alt="Блок «Тестовые аргументы» со значением параметра city и блок «Результаты выполнения» со статусом success"><figcaption><p>Успешный тест: аргументы, результат и вывод print()</p></figcaption></figure>

### Если тест завершился ошибкой

Статус будет **«error»**, а под ним — сообщение:

* **«Ошибка синтаксиса Python. Проверьте правильность написания кода»** — в коде опечатка: лишняя или пропущенная скобка, кавычка, отступ. Скрипт не запустился вообще.
* **«Ошибка при выполнении кода»** — код запустился, но упал на одной из строк.

<figure><img src="https://2593311972-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fef2EBU68XAlye1NtG8DF%2Fuploads%2Fgit-blob-f9de0f7d29041293fc5ac7b21dd58c4b77ff02bb%2Fpython-script-test-oshibka.png?alt=media" alt="Результаты выполнения со статусом error и сообщением «Ошибка при выполнении кода»"><figcaption><p>Тест завершился ошибкой</p></figcaption></figure>

Тест не показывает, на какой строке и почему упал скрипт. Чтобы это найти, используйте `print()`: блок **«stdout (print)»** покажет всё, что скрипт успел вывести до ошибки. Последнее сообщение подскажет, где остановилось выполнение.

```python
city = args.get("city")
print("Получен город:", city)
```

### Что проверить кроме удачного случая

Один успешный тест не значит, что скрипт готов. Проверьте, что он ведёт себя понятно, когда что-то идёт не так:

* **параметр пустой** — очистите поле в «Свойствах функции» и запустите тест;
* **внешний сервис недоступен** — например, укажите неверный адрес API;
* **данные в неожиданном формате** — текст вместо числа, лишние пробелы.

В каждом случае скрипт должен вернуть понятный `result`, а не упасть с ошибкой. Как это сделать — в статье [«Как устроен Python-скрипт»](https://doc.nextbot.ru/functional/python-script/spravochnik-python-script-v2.md).

## Если скрипт упал в диалоге

Ошибки скрипта всегда записываются в диалог, где он выполнялся. В истории диалога появляется красное служебное сообщение **«Ошибка при выполнении python скрипта»**. В нём:

* текст ошибки — например, `invalid literal for int() with base 10: 'Казань'`;
* **«Логи выполнения скрипта»** — всё, что скрипт успел вывести через `print()`.

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

<figure><img src="https://2593311972-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fef2EBU68XAlye1NtG8DF%2Fuploads%2Fgit-blob-d3cdd4e82f4ca79ce0c29739aa1849a933df4187%2Fpython-script-oshibka-v-dialoge.png?alt=media" alt="Служебное сообщение «Ошибка при выполнении python скрипта» с текстом ошибки и логами в истории диалога"><figcaption><p>Ошибка скрипта в истории диалога</p></figcaption></figure>

Успешные запуски в историю диалога не записываются.

## Проверьте скрипт в живом диалоге <a href="#proverte-skript-v-zhivom-dialoge" id="proverte-skript-v-zhivom-dialoge"></a>

Тест проверяет только код. Он не показывает, вызовет ли агент функцию и какие значения передаст. Поэтому после теста проверьте скрипт в живом диалоге.

1. Убедитесь, что функция или сценарий включены, а код сохранён.
2. Откройте **«Тестовый чат»** и напишите сообщение, на которое агент должен вызвать функцию. Для сценария создайте событие, которое его запускает.
3. Сверьте результат: что получил клиент, изменились ли переменные, теги, данные в CRM.

Если агент не вызывает функцию или передаёт не те значения, дело не в коде, а в описании функции и её параметров. Подробнее — в статьях [«Создание функции»](https://doc.nextbot.ru/functional/functions/create-function.md) и [«Параметры функций»](https://doc.nextbot.ru/functional/functions/function-parameters.md).

## Если что-то не так

| Что происходит                              | Причина                                          | Что сделать                                                                                                                                                                                                                            |
| ------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| В диалоге ошибка «Не указан codeId»         | Код не сохранён                                  | Откройте действие и нажмите **«Сохранить»**                                                                                                                                                                                            |
| Агент не вызывает функцию                   | ИИ-модель не понимает, когда она нужна           | Уточните описание функции и параметров                                                                                                                                                                                                 |
| В сценарии агент не видит результат скрипта | В сценарии `tool_result` ИИ-модели не передаётся | Верните `system_message` или добавьте после скрипта действие [«Добавить контекст в диалог»](https://doc.nextbot.ru/functional/functions/sending-result/dobavit-kontekst-v-dialog.md) со значением `{{system_data_pythonScriptResult}}` |
| В CRM нет данных, которые посчитал скрипт   | Скрипт выполняется после интеграций функции      | Разделите работу на две функции: первая считает и записывает результат в переменную диалога, вторая оформляет заказ и берёт значение из этой переменной                                                                                |

Другие ошибки разобраны в статье [«Как устроен Python-скрипт»](https://doc.nextbot.ru/functional/python-script/spravochnik-python-script-v2.md).

## Что дальше

* [«Шаблоны Python Script»](https://doc.nextbot.ru/functional/python-script/shablony-python-script.md) — готовые заготовки для типовых задач.
* [«Создание Python-скриптов с помощью ИИ»](https://doc.nextbot.ru/functional/python-script/sozdanie-python-skriptov-s-pomoshchyu-ii.md) — как получить и исправить код с помощью нейросети.
* [«Как устроен Python-скрипт»](https://doc.nextbot.ru/functional/python-script/spravochnik-python-script-v2.md) — какие данные получает скрипт, что он может вернуть и какие у него ограничения.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://doc.nextbot.ru/functional/python-script/nastroika-i-testirovanie-skripta.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
