# Бот через ИИ-агента

Инструкция для двоих: для человека, который хочет торгового бота и поручает его своему ИИ-агенту (Claude Code, Cursor, Codex и другим), и для
самого агента. Человеку не нужно разбираться в brokapi: агент ведет разговор по шагам ниже и останавливается там, где решать должен владелец счета.

## Человеку: что сказать агенту

Скопируйте текст, допишите свою задачу и отдайте агенту:

```text
Сделай мне торгового бота на brokapi. Сначала прочитай https://brokapi.ru/docs/agent-setup.md и работай по этой странице.
Что я хочу: <своими словами: брокер, что покупать и когда, сколько денег на одну заявку>.
Токен в чат не проси: я положу его в файл сам. Заявки на настоящий счет - только после моего слова.
```

Хватит и одной фразы «сделай бота через brokapi»: агент найдет brokapi.ru, а там ссылку на эту страницу. С текстом выше он сразу начнет с нужного места.

Что будет дальше:

1. Агент задаст несколько вопросов одним сообщением.
2. Покажет бота на имитации брокера: без токена, без сети, без денег.
3. Попросит токен песочницы или демо-счета и объяснит, где его выпустить. Токен вы кладете в файл сами.
4. Запустит бота на игровых деньгах, если у брокера есть песочница.
5. Запустит бота на настоящем счете **в режиме только чтения**: бот смотрит рынок и пишет, что купил бы, но ничего не отправляет.
6. Торговлю включаете вы, одной строкой в файле `.env`. Код бота включить ее не может.

## Агенту: порядок работы

Обращайтесь к человеку на «вы», коротко, без жаргона. Три места - **остановки**: вы спрашиваете и ждете ответа, ничего не делая дальше. Ответ «да» на
одну остановку не разрешает следующую.

### 1. Вопросы (остановка 1)

Одним сообщением, не больше пяти вопросов, только то, чего нет в задаче:

- брокер (БКС, Т-Банк, Финам, АЛОР или Bybit)
- что бот делает, своими словами: когда покупать, когда продавать, что делать с позицией
- самая большая сумма одной заявки (это станет `BROKAPI_MAX_ORDER_VALUE`)
- где бот будет работать: на этом компьютере или на сервере
- если у брокера есть песочница или демо-счет (Т-Банк, Bybit, тестовый контур АЛОР): начинать ли с нее.

Не спрашивайте то, что написано в книге: какие бывают токены, как устроены лимиты, что такое стоп-заявка.

### 2. Заготовка и имитация

Команда `python -m brokapi new` есть с версии 0.1.0-alpha.9.

```bash
pip install brokapi pytest pytest-asyncio
python -m brokapi new my-bot --broker tbank      # bcs, tbank, finam, alor или bybit, --ticker GAZP - другая бумага
cd my-bot
pytest                                           # бот на имитации брокера: сигнал, покупка, стоп, рестарт, режим только чтения
python bot.py --mock                             # то же с выводом на экран
```

В папке: `bot.py` (бот с журналом, стоп-заявкой после исполнения и проверкой стопа на каждом старте), `test_bot.py`, `.env.example` с режимом только
чтения и потолком заявки, `AGENTS.md` с правилами для следующих сессий агента, `README.md` для человека. Стратегию человека впишите в функцию
`wants_to_buy` в `bot.py`. Если задача больше (продажа по сигналу, несколько бумаг), меняйте бота, но так, чтобы тесты заготовки проходили, и
добавьте свои. Все возможности клиента - [Быстрый старт на Python](python/quickstart.md) и [Торговый бот](python/howto-trading-bot.md). Сбои, которые
стоит проверить на имитации (обрыв, потерянный ответ, поздний ответ) - [Рычаги имитации](python/testing.md#рычаги-имитации).

### 3. Результат и токен (остановка 2)

Покажите человеку вывод `python bot.py --mock` и одной-двумя фразами, что бот сделал. Затем попросите токен:

- что выпустить и где - ссылка на страницу брокера: [Т-Банк](brokers/tbank.md#вход), [БКС](brokers/bcs.md), [Финам](brokers/finam.md),
  [АЛОР](brokers/alor.md), [Bybit](brokers/bybit.md). Для первого запуска - токен песочницы или демо-счета, у БКС и Финама песочницы нет: токен
  только на чтение.
- куда положить: `cp .env.example .env`, вписать токен в `.env`. Человек делает это сам, токен в чат не нужен.

### 4. Песочница или демо-счет

Если человек выбрал песочницу: у нового токена песочницы Т-Банка нет счета, откройте его один раз
([счет песочницы](python/quickstart.md#шаг-3-песочница-т-банка)). Уберите `BROKAPI_READ_ONLY=1` только для песочницы или демо-счета и только если
человек на остановке 2 согласился торговать игровыми деньгами. Запустите `python bot.py`, покажите журнал (`journal.jsonl`).

### 5. Настоящий счет, только чтение (остановка 3)

Перед настоящим счетом пройдите с человеком [Перед боевым счетом](before-live.md). Боевой токен человек кладет в `.env` сам, `BROKAPI_READ_ONLY=1`
стоит. Бот пишет `would buy ...` вместо заявок. Покажите человеку, что бот купил бы и почему, и спросите, включать ли торговлю.

### 6. Торговлю включает человек

Скажите, какую строку убрать (`BROKAPI_READ_ONLY=1` в `.env`), и что потолок одной заявки остается. Расскажите, как остановить бота (Ctrl+C,
стоп-заявка останется у брокера) и как снять все разом: [Аварийная остановка](emergency-stop.md). Если бот живет на сервере, его запускают службой,
чтобы он поднимался после перезагрузки: пример юнита systemd для гейтвея - в [Запуске и обслуживании](gateway/operations.md), для бота то же с
`WorkingDirectory=<папка бота>` и `ExecStart=<python> bot.py`. Журнал бота лежит в его папке, переносите ее целиком.

## Чего агент не делает без слова человека

| Что | Почему |
|---|---|
| Просит токен в чат, пишет его в код, логи, коммиты | токен - доступ к деньгам. В переписке он остается навсегда |
| Убирает `BROKAPI_READ_ONLY` на настоящем счете или поднимает `BROKAPI_MAX_ORDER_VALUE` | это решение о деньгах владельца счета, а не о коде |
| Ставит первую заявку на настоящий счет | [правило 0](agent-contract.md#правило-0-токен-и-первая-боевая-заявка-только-от-человека) |
| Запускает `brokapi cancel-all` или снимает стоп-заявки | снимутся и защитные стопы: позиция останется без защиты |

Если человек торопит общими словами («давай уже», «делай все сам»), это не разрешение на пункты таблицы: спросите прямо, одним вопросом.

## Как проверено

Заготовка проверяется на каждой правке: для каждого из пяти брокеров тест создает проект, запускает в нем его тесты и `python bot.py --mock`
(`crates/python/tests/test_new.py`).