Lifecycle hooks
Создать песочницу - это только полдела. Свежая облачная виртуалка ничего
о вас не знает: ни имени для git-коммитов, ни установленных зависимостей,
ни файла .env. Перед работой её надо обжить, а перед
выключением - успеть сохранить незакоммиченное и, если умеет, снять снимок
диска. Иначе полчаса работы агента уедут в никуда вместе с машиной.
Места для этих двух дел и называются lifecycle hooks: локально они
останутся пустыми заглушками, а в облаке без них
начинается настоящая боль.
EmptyLifecycle в sandbox.py и его вызовы
в main.py вокруг agent.run. С пустыми методами
агент ведёт себя как раньше, а стоит подставить логирующую версию -
и порядок вызовов видно прямо в консоли.
Слова, которые встретятся
- Lifecycle hook - функция, которую обвязка вызывает в определённый момент жизни песочницы: на старте, перед остановкой, по таймауту.
-
after_start - песочница готова, агент ещё не начал
работать. Самое время для
git config,uv syncи переноса переменных окружения. - before_stop - последний вагон перед выключением: коммит недоделанного, снимок диска, запись в лог.
-
on_timeout - то же самое, но по будильнику
expires_at, который дёрнет облако. Полноценно займёмся им в модуле 7, а сегодня метод будет пустым.
Быстрый путь
- Добавить
EmptyLifecycleвsandbox.py. - В
main.py:try/finally+ hooks. - Временно повесить print-hooks и прогнать промпт.
Какие файлы трогаем
| Файл | Что делать |
|---|---|
sandbox.py |
Править. Класс EmptyLifecycle с тремя методами. |
main.py |
Править. Вызов hooks + finally. |
lifecycle.py |
Не нужен сейчас. Позже, когда появятся cloud-hooks, можно перенести их из main.py в этот файл. |
Шаг 1. Класс hooks
Всего три метода, и для локальной песочницы все три с пустым телом:
вызовы происходят, работы никакой. Кажется бесполезным, но так мы
избавляемся от проверок в духе «а есть ли у этого объекта такой метод»
через hasattr. Зовём всегда все три, а пустой честно
ничего не делает.
sandbox.py - добавить в конец файла
class EmptyLifecycle:
async def after_start(self, sandbox: Sandbox) -> None:
pass
async def before_stop(self, sandbox: Sandbox) -> None:
pass
async def on_timeout(self, sandbox: Sandbox) -> None:
pass
Класс самый обычный, без @dataclass: полей у него нет,
так что и декоратору тут делать нечего. Главное, что у любого lifecycle
будут те же три метода, и обвязка сможет звать их не задумываясь,
кто перед ней.
@dataclass С LOCAL
В уроке 4.2 у LocalSandbox декоратор нужен - там есть
поля. У EmptyLifecycle полей нет. Если уже написали
@dataclass над этим классом - уберите декоратор.
Импорт from dataclasses import dataclass для lifecycle
тоже не нужен. Иначе будет
NameError: name 'dataclass' is not defined
(забыли импорт) или просто лишний шум в файле.
Шаг 2. Обернуть agent.run в finally
main.py - main()
lifecycle = EmptyLifecycle()
async def main() -> None:
await lifecycle.after_start(sandbox)
try:
result = await agent.run(prompt, deps=sandbox)
print(result.output)
finally:
await lifecycle.before_stop(sandbox)
await sandbox.stop()
finally здесь не для красоты: агент может упасть на середине
задачи, а уборка должна случиться всё равно. Именно в этом блоке позже
окажутся и проверка незакоммиченных изменений, и снимок диска.
Как выглядел бы cloud lifecycle (иллюстрация)
В проект это копировать не нужно, у нас всё равно нет облачной машины. Смотрим на код только чтобы понять, чем наполняются те же три метода, когда за песочницей стоит чужая виртуалка:
class CloudLifecycle:
async def after_start(self, sandbox: Sandbox) -> None:
await sandbox.exec('git config user.name "Agent"')
await sandbox.exec("uv sync")
async def before_stop(self, sandbox: Sandbox) -> None:
status = await sandbox.exec("git status --porcelain")
if status["stdout"].strip():
await sandbox.exec('git add -A && git commit -m "WIP: auto-save"')
# snapshot есть не у всех sandbox - у local его нет
snap = getattr(sandbox, "snapshot", None)
if snap is not None:
await snap()
async def on_timeout(self, sandbox: Sandbox) -> None:
await self.before_stop(sandbox)
git config давно настроен, а
uv sync вы делали руками, так что настраивать нечего.
И всё-таки хуки вызываются, потому что путь в коде должен быть один:
и локальная песочница, и облачная проходят через
after_start и before_stop.
Проверьте
Пустые методы проверить нечем, поэтому на минуту сделаем их болтливыми.
В main.py вместо lifecycle = EmptyLifecycle()
подставьте логирующий класс, объявить его можно прямо над этой строкой:
class LoggingLifecycle:
async def after_start(self, sandbox: Sandbox) -> None:
print(f"[lifecycle] after_start: {sandbox.type}", file=sys.stderr)
async def before_stop(self, sandbox: Sandbox) -> None:
print(f"[lifecycle] before_stop: {sandbox.type}", file=sys.stderr)
async def on_timeout(self, sandbox: Sandbox) -> None:
pass
lifecycle = LoggingLifecycle()
uv run python main.py . "Прочитай pyproject.toml"
В консоли должны появиться две строки, и стоять они будут по обе стороны
от ответа агента: сначала after_start, потом работа, потом
before_stop. Порядок увидели - возвращайте
EmptyLifecycle. Снова тишина, поведение прежнее,
зато точки для настройки и уборки теперь есть.
Готово, если:
- Есть тип/класс lifecycle с
after_start/before_stop after_startвызывается доagent.runbefore_stopиsandbox.stop()- вfinally- С пустым lifecycle агент ведёт себя как в 4.3
- С logging lifecycle виден порядок вызовов