MODULE_04 · УРОК 4.4

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,
    )
ПОЧЕМУ ИНТЕРФЕЙС УЖЕ ПОДХОДИТ Вот теперь пригодилось решение из урока 4.1 сделать все методы async. Локальный бэкенд ставит await над синхронным кодом почти для вида, у облачного за тем же await прячется настоящий сетевой вызов. Одна сигнатура, два совершенно разных мира, и ни строчки правок в инструментах.

Сравнение в одной таблице

local memory cloud
Цена бесплатно бесплатно за минуту работы VM
Скорость вызова мгновенно мгновенно сеть на каждый вызов
Изоляция нет (ваш диск) копия в /tmp отдельная виртуалка
После stop файлы на месте копия удалена снимок - или всё пропало
Таймаут нет нет часто 30-60 минут

Когда что брать

  • local - пишете harness у себя, доверяете машине, нужна скорость.
  • memory - агент может нахулиганить с файлами, оригинал жалко; сеть и деньги не нужны.
  • cloud - CI, несколько пользователей, чужой код, нельзя пускать на хост.
ЗАЧЕМ expires_at И snapshot НЕОБЯЗАТЕЛЬНЫ У локальной песочницы нет ни таймера выключения, ни снимка диска. Соблазн дописать эти методы с пустым телом велик, но тогда любой, кто читает код, решит, что снимок есть, а его нет. Гораздо честнее оставить поля необязательными: у кого умеет, у того есть. А вот облако без expires_at обязательно устроит вам сюрприз на двадцать девятой минуте, когда соединение оборвётся, а обвязка так и не поймёт, что случилось.

Проверьте (без кода)

Запускать нечего, поэтому проверка будет честной беседой с самим собой. Ответьте вслух на три вопроса, этого достаточно:

  1. Почему read_file в cloud медленнее, чем в local? (Два коротких довода.)
  2. Зачем expires_at необязателен на интерфейсе? (Одно предложение.)
  3. Когда вы бы взяли cloud, а не memory, для coding-агента?

Сверимся. В первом случае данные едут по сети, и уже на стороне машины их ещё нужно прочитать с диска, то есть две задержки вместо нуля. Во втором всё просто: у local и memory срока жизни нет, поле к ним не применимо, и притворяться незачем. А третий ответ звучит примерно так: CI или сервис, где агент запускает чужой код и файлы хоста трогать нельзя ни при каких условиях.

Готово, если:

  • Можете объяснить, почему cloud медленнее local
  • Понимаете, зачем expires_at и snapshot
  • Можете назвать задачу, где нужен именно cloud
  • Помните: tools при смене бэкенда не переписывают - они зовут sandbox, а не конкретного провайдера
ЕСЛИ ЗАХОТИТЕ ЖИВОЙ CLOUD Порядок действий короткий: берёте SDK любого провайдера облачных песочниц и оборачиваете его в наш Sandbox примерно так, как в наброске выше. Инструменты при этом трогать не придётся вообще, и это лучшая проверка того, что интерфейс в модуле 4 мы нарезали правильно.