> 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/sozdanie-python-skriptov-s-pomoshchyu-ii.md).

# Создание Python-скриптов с помощью ИИ

Как получить рабочий Python-скрипт с помощью встроенного ИИ Nextbot или внешней нейросети и исправить его по ошибкам.

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

Есть два способа:

* **Встроенная генерация кода** — ИИ создаёт и редактирует скрипты прямо в редакторе Nextbot.
* **Внешняя нейросеть** — вы используете ChatGPT, Claude или другой ИИ-инструмент, передаёте ему файл-инструкцию Nextbot и описание своей задачи, а затем вставляете полученный код в Nextbot.

Оба способа подходят для создания новых скриптов, доработки существующих и исправления ошибок.

## Сформулируйте задачу <a href="#sformuliruite-zadachu" id="sformuliruite-zadachu"></a>

Прежде чем просить ИИ о коде, опишите, что именно должен делать скрипт.

Зафиксируйте:

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

Например:

*Задача: агент должен проверять статус заказа в CRM.*

* Входные данные: номер заказа.
* Действия: отправить запрос в CRM, найти заказ, получить его статус.
* Результат: вернуть статус агенту, чтобы он сообщил его клиенту.
* Ошибки: если заказ не найден, сообщить, что заказа нет; если API недоступен, сообщить о технической ошибке.

Если задача сложная и вы не знаете, с чего начать, используйте [универсальный алгоритм разработки кастомных интеграций](https://doc.nextbot.ru/functional/python-script/kastomnye-integracii/universalnyi-algoritm-po-razrabotke-kastomnykh-integracii.md). Он поможет сформулировать требования и составить технический план.

Это описание вы передадите встроенному ИИ или внешней нейросети.

## Способ 1. Генерация кода внутри Nextbot

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

### Как создать скрипт

1. Откройте редактор Python Script с выбранным шаблоном. Если действия ещё нет, откройте функцию, сценарий или форму, нажмите **«Добавить действие»** и выберите **Python Script** (в сценарии — **«Python скрипт»**). Затем выберите шаблон и нажмите **«Использовать шаблон»**.
2. В правом нижнем углу редактора нажмите **«Сгенерировать с ИИ»**. Откроется панель **«Генерация кода с ИИ»**.
3. В поле запроса (1) опишите задачу, которую вы сформулировали в разделе [«Сформулируйте задачу»](#sformuliruite-zadachu).
4. Отправьте запрос. В панели появится ответ ИИ: что он изменил в коде (3). Сами изменения подсвечиваются в редакторе.
5. Проверьте изменения и нажмите **«Принять»** (зелёная галочка) или **«Отклонить»** (красный крестик) рядом с ними (4).
6. Сохраните код.

<figure><img src="https://2593311972-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fef2EBU68XAlye1NtG8DF%2Fuploads%2Fgit-blob-bbe8069b65d7a331e60462aa66121231261a4e3e%2Fpython-script-generaciya-koda-s-ii.webp?alt=media" alt="Редактор Python Script с открытой панелью «Генерация кода с ИИ»: шестерёнка настроек и поле «Уровень рассуждений», внизу поле запроса"><figcaption><p>Панель «Генерация кода с ИИ»: 1 — поле запроса, 2 — настройки генерации</p></figcaption></figure>

<figure><img src="https://2593311972-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fef2EBU68XAlye1NtG8DF%2Fuploads%2Fgit-blob-280c4c2bbdfbab006b098785920516f8e5e2a250%2Fpython-script-generaciya-koda-s-ii-prinyat.webp?alt=media" alt="Ответ ИИ в панели «Генерация кода с ИИ» с пометкой «Изменения показаны в редакторе» и кнопки «Принять» и «Отклонить» в коде"><figcaption><p>Ответ ИИ: 3 — что изменено, 4 — кнопки «Принять» и «Отклонить»</p></figcaption></figure>

Например, если нужно получать статус заказа из внешнего сервиса, можно написать:

> Напиши Python-скрипт, который получает номер заказа из параметра order\_id, отправляет GET-запрос во внешнюю систему по адресу \[URL API], получает статус заказа и возвращает его ИИ-агенту. Если заказ не найден или API недоступен, верни понятное сообщение об ошибке.

Чем конкретнее вы опишете входные данные, действия, результат и ошибки, тем меньше уточнений и исправлений потребуется.

### Настройка уровня рассуждений

Нажмите на шестерёнку рядом с заголовком панели (2) и выберите значение в поле **«Уровень рассуждений»**. По умолчанию стоит **«Низкий»**.

| Уровень | Когда использовать                                |
| ------- | ------------------------------------------------- |
| Нет     | Простые однострочные изменения                    |
| Низкий  | Небольшие скрипты и обычные правки                |
| Средний | Задачи с несколькими действиями и условиями       |
| Высокий | Сложные вычисления, условия и внешние API         |
| Макс.   | Самые сложные задачи, требующие глубокого анализа |

Чем выше уровень рассуждений, тем больше времени и BotCoin может потребоваться на генерацию. Для большинства задач начните с низкого или среднего уровня.

## Способ 2. Создание скрипта с помощью внешней нейросети

Внешняя нейросеть не знает, как устроен Python Script в Nextbot, поэтому вместе с задачей ей нужно передать описание платформы.

Для этого в редакторе есть **файл-инструкция**. Это полное руководство по Python Script от самой платформы: какие данные получает скрипт, что он может вернуть, какие библиотеки доступны и чем отличаются функция, сценарий и форма. С этим файлом нейросеть берёт поля и возможности из руководства, а не придумывает их.

### Шаг 1. Скачайте файл-инструкцию

1. Откройте редактор Python Script в функции, сценарии или форме.
2. В правом верхнем углу редактора нажмите **«Инструкция для AI»**. Откроется окно **«Файл-инструкция для AI-ассистента»**.
3. Нажмите **«Скачать файл»** (1).
4. Скопируйте содержимое блока **«Аргументы текущего контекста»** (2).

<figure><img src="https://2593311972-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fef2EBU68XAlye1NtG8DF%2Fuploads%2Fgit-blob-f81ee05eb3a516685cc6fe5c837366b328b34c68%2Fpython-script-instrukciya-dlya-ai.webp?alt=media" alt="Окно «Файл-инструкция для AI-ассистента»: кнопка «Скачать файл» и блок «Аргументы текущего контекста» отмечены цифрами 1–2"><figcaption><p>Окно с файлом-инструкцией: 1 — кнопка «Скачать файл», 2 — аргументы текущего контекста</p></figcaption></figure>

Файл-инструкция описывает Python Script целиком и одинаков для всех скриптов. Аргументы текущего контекста показывают, где вы открыли редактор: у функции это её название, описание и параметры.

Передайте нейросети оба материала, чтобы она подготовила код по правилам Nextbot.

### Шаг 2. Подготовьте документацию внешнего сервиса

Если скрипт будет взаимодействовать с CRM, геосервисом, платёжной системой или другим внешним сервисом, понадобится его API-документация.

Попросите нейросеть найти её прямо в чате или найдите сами на сайте сервиса либо через его техподдержку.

В зависимости от задачи вам могут понадобиться:

* адрес API (endpoint);
* метод запроса — GET, POST, PUT или другой;
* способ авторизации;
* параметры и формат передаваемых данных;
* структура ответа сервиса.

Если скрипт не обращается к внешним сервисам, этот шаг можно пропустить.

### Шаг 3. Передайте задачу нейросети

Откройте ChatGPT, Claude или другой ИИ-инструмент и передайте ему:

1. Файл-инструкцию из Nextbot.
2. Аргументы текущего контекста.
3. Описание задачи из раздела [«Сформулируйте задачу»](#sformuliruite-zadachu).
4. API-документацию, если требуется интеграция с внешним сервисом.

**Пример запроса:**

> Я создаю ИИ-агента на платформе Nextbot. Мне нужно написать Python-скрипт для следующей задачи:
>
> \[Описание задачи]
>
> Скрипт будет запускаться в \[функции, сценарии или форме персональных данных]. Учти, в каком месте он запускается.
>
> Я приложил файл-инструкцию по работе с Python Script в Nextbot, аргументы текущего контекста и документацию внешнего API.
>
> На основе этих материалов подготовь готовый код для Python Script v2.
>
> Используй доступные аргументы, обрабатывай возможные ошибки и возвращай результат через переменную result.
>
> Если информации недостаточно, сначала задай уточняющие вопросы. Не придумывай отсутствующие параметры API или возможности платформы.
>
> После написания кода кратко объясни, какие значения мне нужно заменить или настроить перед запуском.

Место запуска важно указать: от него зависит, что получит скрипт и кто увидит результат. Например, в сценарии ИИ-модель не получает `tool_result`. Поэтому в коде для сценария данные модели передают через `system_message` либо ставят после скрипта действие [«Добавить контекст в диалог»](https://doc.nextbot.ru/functional/functions/sending-result/dobavit-kontekst-v-dialog.md). Оба способа описаны в файле-инструкции, и нейросеть применит нужный, если вы скажете, где будет работать скрипт.

### Шаг 4. Добавьте код в Nextbot

1. Вернитесь в редактор Python Script.
2. Вставьте полученный код.
3. Проверьте значения, которые нужно настроить: адреса API, параметры, названия переменных и другие данные.
4. Сохраните скрипт.

Если код создавался для функции агента, проверьте её описание и параметры. Агент должен понимать, когда вызывать функцию и какие данные передавать.

## Где хранить ключи и токены <a href="#gde-khranit-klyuchi-i-tokeny" id="gde-khranit-klyuchi-i-tokeny"></a>

Для подключённых к агенту Битрикс24, amoCRM и Kommo ключ не нужен. Токен и адрес уже лежат в `args`: `bitrixToken` и `bitrixDomain`, `amoToken` и `amoDomain`, `kommoToken` и `kommoDomain`. Nextbot обновляет токен сам. Если CRM к агенту не подключена, в этих полях будет `"none"`.

Для других сервисов ключ можно хранить в коде скрипта или в [пользовательской переменной](https://doc.nextbot.ru/functional/setting-up-agent/polzovatelskie-peremennye.md) агента.

{% tabs %}
{% tab title="В коде скрипта" %}
Ключ записан прямо в коде:

```python
API_KEY = "ваш_ключ"
```

**Плюсы:**

* проще всего: ничего не нужно создавать заранее;
* всё, что нужно скрипту, находится в одном месте.

**Минусы:**

* ключ виден всем, у кого есть доступ к агенту и редактору скрипта;
* код нельзя отдать нейросети как есть: каждый раз нужно вручную убирать из него ключ;
* если ключ меняется, его придётся исправить в каждом скрипте, где он записан;
* при копировании агента ключ уходит вместе со скриптом. Если вы передаёте агента другому пользователю через код копирования, ключ получит и он.

Подходит, если ключ нужен одному скрипту и код вы не передаёте во внешние сервисы.
{% endtab %}

{% tab title="В переменной агента" %}
Ключ хранится в переменной агента, а скрипт читает его из `args`:

```python
variables = args.get("variables") or {}
api_key = (variables.get("agent") or {}).get("geo_api_key")

if not api_key:
    result = "Не задан ключ geo_api_key в переменных агента"
```

Эти строки ставят в начало скрипта, а `api_key` потом подставляют в запрос к сервису. Переменную `geo_api_key` нужно заранее создать в настройках агента. Как это сделать — в статье [«Создание и редактирование переменных»](https://doc.nextbot.ru/functional/setting-up-agent/polzovatelskie-peremennye/sozdanie-i-redaktirovanie-peremennykh.md).

**Плюсы:**

* в коде нет ключа, поэтому его можно отдавать нейросети как есть;
* один ключ можно использовать в нескольких скриптах;
* сменить ключ можно в одном месте, не открывая код.

**Минусы:**

* значение видно в настройках агента всем, у кого есть к ним доступ;
* при копировании агента или его переменных ключ копируется вместе с ними. Если вы передаёте агента другому пользователю через код копирования, ключ получит и он;
* если подставить переменную в промпт, ключ увидит ИИ-модель. Не используйте её в промпте;
* скрипт или действие «Управление переменными» могут случайно перезаписать значение.

Подходит, если ключ нужен нескольким скриптам или вы часто отдаёте код нейросети.
{% endtab %}
{% endtabs %}

Не передавайте ключ через параметр функции: значения параметров заполняет ИИ-модель.

{% hint style="warning" %}
Перед передачей кода или логов во внешнюю нейросеть удалите из них реальные API-ключи, токены, пароли и персональные данные клиентов. Для примеров используйте тестовые значения.
{% endhint %}

## Тестирование и исправление ошибок

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

Поэтому, когда код готов, вернитесь в статью «Настройка и тестирование скрипта» и проверьте его — раздел [«Как протестировать скрипт»](https://doc.nextbot.ru/functional/python-script/nastroika-i-testirovanie-skripta.md#kak-protestirovat-skript).

Если скрипт работает с внешним сервисом, одного статуса **«success»** мало. Откройте сам сервис и убедитесь, что данные дошли: заявка создалась, запись обновилась, ответ пришёл.

### Как исправлять ошибки с помощью ИИ

Если скрипт завершился с ошибкой, найдите её текст и вывод `print()`. Они есть в двух местах.

**В тесте.** Под редактором появится блок **«Результаты выполнения»** со статусом **«error»** и сообщением об ошибке (1). Всё, что скрипт успел вывести через `print()`, показано в блоке **«stdout (print)»** (2).

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

**В истории диалога.** Если скрипт упал во время разговора, в диалоге появится красное служебное сообщение **«Ошибка при выполнении python скрипта»**. В нём текст ошибки (1) и **«Логи выполнения скрипта»** (2) — то, что скрипт вывел через `print()`. Клиент это сообщение не видит.

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

Скопируйте текст ошибки и вывод `print()` и передайте их нейросети вместе с кодом.

**Пример запроса:**

> Я протестировал Python-скрипт в Nextbot, но при выполнении возникла ошибка.
>
> Код скрипта:
>
> \[Вставьте код]
>
> Лог ошибки:
>
> \[Вставьте лог]
>
> Объясни простым языком, почему возникла ошибка. Исправь код с учётом файла-инструкции Python Script v2 в Nextbot и пришли полную исправленную версию.

Если вы работаете во встроенном редакторе Nextbot, используйте для исправления ошибок панель **«Генерация кода с ИИ»**.

После каждого исправления запускайте тест заново.

## Что делать, если для скрипта не хватает библиотеки

Python Script v2 поддерживает стандартную библиотеку Python и набор предустановленных внешних пакетов. Установить пакет из самого скрипта нельзя.

Если нужной библиотеки нет, запросите её через редактор. Подробнее — в статье [«Запрос библиотеки»](https://doc.nextbot.ru/functional/python-script/zapros-biblioteki.md).

## Что дальше

Когда тест проходит, проверьте скрипт в живом диалоге — раздел [«Проверьте скрипт в живом диалоге»](https://doc.nextbot.ru/functional/python-script/nastroika-i-testirovanie-skripta.md#proverte-skript-v-zhivom-dialoge) статьи «Настройка и тестирование скрипта».

Если вы хотите разобраться на практическом примере, изучите [кейс поиска ближайшего филиала сети кафе](https://doc.nextbot.ru/functional/python-script/kastomnye-integracii/keis-poisk-blizhaishego-filiala-seti-kafe.md). В нём показано, как с помощью Python Script и внешнего геосервиса агент определяет ближайшую точку обслуживания по адресу клиента.


---

# 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/sozdanie-python-skriptov-s-pomoshchyu-ii.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.
