Cloud-реализация
Два бэкенда у нас уже есть: локальный работает на вашем диске быстро и
бесплатно, memory крутится на копии в /tmp и не трогает
оригинал. Третий вариант принципиально другой: чужая виртуальная машина
где-то в интернете, с настоящим git и pip, но с сетью на каждый
read_file, счётом за минуты работы и привычкой выключаться
через полчаса. API у провайдеров меняются подозрительно часто, так что
конкретный SDK учить смысла нет. Урок чисто теоретический, код писать не
нужно: разберёмся с идеей и посмотрим, почему наш интерфейс к такому
бэкенду уже готов.
create_cloud_sandbox, зачем
песочнице поля expires_at и snapshot и в каких
задачах облако выигрывает у local и memory. Урок чисто теоретический,
код писать не нужно.
Слова, которые встретятся
- Cloud sandbox - виртуальная машина в облаке, где агент читает файлы и запускает команды вместо вашего ноутбука. Ваши файлы при этом в полной безопасности, а платите вы сетью и деньгами.
- Задержка (latency) - время ожидания ответа на один вызов. У локального бэкенда она практически нулевая, у облачного это десятки, а то и сотни миллисекунд в каждую сторону. На одном вызове незаметно, на сотне tool-call за сессию - вполне.
- expires_at - момент, когда виртуалку погасят. Зная его заранее, обвязка успеет сохранить работу, а не узнает о конце по внезапно оборвавшемуся соединению.
- snapshot - снимок диска машины, из которого потом поднимают новую «с того же места». Подробно займёмся этим в модуле 7.
Какие файлы трогаем
| Файл | Что делать |
|---|---|
| всё в проекте | Не трогать. Урок чисто теоретический - код писать не нужно. |
sandbox_cloud.py |
Только читать набросок ниже - в проект не копировать. |
Зачем вообще cloud
Дома local и memory закрывают почти всё. Картина меняется, когда агент становится сервисом: десяток пользователей, задачи из CI, чужой код, который совсем не хочется запускать на своём хосте. Тогда каждому дают отдельную виртуалку по принципу «сломал - выбросили машину», и ваш ноутбук в этой истории вообще не участвует.
Плата за это честная и заранее известная: сеть на каждый вызов, счёт за минуты, жёсткий таймаут в конце. Так что облако не «лучше» локальной песочницы, оно просто для других задач - тех, где изоляция дороже скорости и мелочи в кошельке.
Как это выглядело бы в коде
Самое приятное, что методы те же самые, что у local и memory. Внутри
вместо subprocess будут HTTP-запросы к провайдеру, но
инструменты об этом не узнают: они как раньше зовут
sandbox.exec, а кто сидит на другом конце,
их не касается.
sandbox_cloud.py - набросок, не запускаем
import time
from dataclasses import dataclass
from typing import Any
from sandbox import ExecResult
@dataclass
class CloudSandbox:
type: str
working_directory: str
expires_at: int # unix-время, когда VM выключат
_vm: Any # клиент облачного API песочниц
async def read_file(self, path: str) -> str:
# каждый вызов - сеть
return await self._vm.read_file(f"{self.working_directory}/{path}")
async def exec(self, command: str) -> ExecResult:
result = await self._vm.run(command, cwd=self.working_directory)
return {
"stdout": result.stdout + result.stderr,
"exit_code": result.exit_code,
}
async def stop(self) -> None:
await self._vm.close()
async def snapshot(self) -> dict[str, str]:
snap = await self._vm.snapshot()
return {"snapshot_id": snap.id}
async def create_cloud_sandbox(config: dict) -> CloudSandbox:
vm = await ProviderSandbox.create(config)
return CloudSandbox(
type="cloud",
working_directory="/workspace",
expires_at=int(time.time()) + 30 * 60, # типично ~30 минут
_vm=vm,
)
async. Локальный бэкенд ставит await над
синхронным кодом почти для вида, у облачного за тем же
await прячется настоящий сетевой вызов. Одна сигнатура,
два совершенно разных мира, и ни строчки правок в инструментах.
Сравнение в одной таблице
| local | memory | cloud | |
|---|---|---|---|
| Цена | бесплатно | бесплатно | за минуту работы VM |
| Скорость вызова | мгновенно | мгновенно | сеть на каждый вызов |
| Изоляция | нет (ваш диск) | копия в /tmp |
отдельная виртуалка |
| После stop | файлы на месте | копия удалена | снимок - или всё пропало |
| Таймаут | нет | нет | часто 30-60 минут |
Когда что брать
- local - пишете harness у себя, доверяете машине, нужна скорость.
- memory - агент может нахулиганить с файлами, оригинал жалко; сеть и деньги не нужны.
- cloud - CI, несколько пользователей, чужой код, нельзя пускать на хост.
expires_at И snapshot НЕОБЯЗАТЕЛЬНЫ
У локальной песочницы нет ни таймера выключения, ни снимка диска.
Соблазн дописать эти методы с пустым телом велик, но тогда любой, кто
читает код, решит, что снимок есть, а его нет. Гораздо честнее оставить
поля необязательными: у кого умеет, у того есть. А вот облако без
expires_at обязательно устроит вам сюрприз на двадцать
девятой минуте, когда соединение оборвётся, а обвязка так
и не поймёт, что случилось.
Проверьте (без кода)
Запускать нечего, поэтому проверка будет честной беседой с самим собой. Ответьте вслух на три вопроса, этого достаточно:
-
Почему
read_fileв cloud медленнее, чем в local? (Два коротких довода.) -
Зачем
expires_atнеобязателен на интерфейсе? (Одно предложение.) - Когда вы бы взяли cloud, а не memory, для coding-агента?
Сверимся. В первом случае данные едут по сети, и уже на стороне машины их ещё нужно прочитать с диска, то есть две задержки вместо нуля. Во втором всё просто: у local и memory срока жизни нет, поле к ним не применимо, и притворяться незачем. А третий ответ звучит примерно так: CI или сервис, где агент запускает чужой код и файлы хоста трогать нельзя ни при каких условиях.
Готово, если:
- Можете объяснить, почему cloud медленнее local
- Понимаете, зачем
expires_atиsnapshot - Можете назвать задачу, где нужен именно cloud
- Помните: tools при смене бэкенда не переписывают - они зовут sandbox, а не конкретного провайдера
Sandbox примерно так, как в наброске
выше. Инструменты при этом трогать не придётся вообще, и это лучшая
проверка того, что интерфейс в модуле 4 мы нарезали правильно.