MODULE_04 · УРОК 4.2

Local-реализация

Контракт мы написали, но Protocol сам по себе ни одного файла не прочитает: это чертёж, а не станок. Значит, пора собрать первый настоящий бэкенд, и он будет до неприличия скучным - тот же subprocess и тот же pathlib, что были в модуле 2, только теперь спрятанные за интерфейсом Sandbox. Скучный тут комплимент: именно с этой реализацией мы будем сравнивать memory и cloud, так что чем меньше в ней сюрпризов, тем лучше. И заодно агент снова начнёт отвечать на промпты.

ЧТО ПОЛУЧИТСЯ Файл sandbox_local.py с create_local_sandbox(dir). Агент снова оживает и ведёт себя точно как в модуле 3, хотя внутри у него теперь совсем другая проводка.

Слова, которые встретятся

  • Local sandbox - команды выполняются на вашем диске, в вашей рабочей папке. Слово «песочница» тут не должно расслаблять: изоляции нет никакой, и rm -rf сработает по-настоящему, если шлюз подтверждения его пропустит.
  • Фабрика - функция create_local_sandbox, которая возвращает объект, подходящий под контракт Sandbox. Инструментам больше ничего и не нужно.

Быстрый путь

  1. Создать sandbox_local.py.
  2. В main.py: sandbox = create_local_sandbox(cwd), agent.run(..., deps=sandbox).
  3. Прогнать знакомые промпты - результат как раньше.

Какие файлы трогаем

Файл Что делать
sandbox_local.py Создать. create_local_sandbox - read_file + exec + stop.
main.py Править. Создать sandbox, передать в tools и в deps=.
local_bash.py Можно удалить или оставить - логику exec переносим в sandbox_local.
prompts.py sandbox_type: sandbox.type (обычно "local").

Шаг 1. Реализация

sandbox_local.py

import subprocess
from dataclasses import dataclass
from pathlib import Path

from sandbox import ExecResult


@dataclass
class LocalSandbox:
    type: str
    working_directory: str
    _root: Path

    async def read_file(self, path: str) -> str:
        return (self._root / path).read_text(encoding="utf-8")

    async def exec(self, command: str) -> ExecResult:
        try:
            proc = subprocess.run(
                command,
                shell=True,
                cwd=self._root,
                capture_output=True,
                text=True,
                timeout=30,
            )
            out = (proc.stdout or "") + (proc.stderr or "")
            return {"stdout": out.strip(), "exit_code": proc.returncode}
        except subprocess.TimeoutExpired:
            return {"stdout": "Таймаут: больше 30 секунд.", "exit_code": 124}

    async def stop(self) -> None:
        pass  # локально нечего убирать


def create_local_sandbox(directory: Path) -> LocalSandbox:
    root = directory.resolve()
    return LocalSandbox(
        type="local",
        working_directory=str(root),
        _root=root,
    )

Одна деталь важнее остальных: exec не бросает исключение на ненулевом коде возврата, а спокойно возвращает объект со stdout и кодом. Инструменты ждут именно этого, ровно как в модуле 2: упавшая команда - такой же результат, как и удачная, просто с другим числом.

Шаг 2. Подключить в main.py

from sandbox_local import create_local_sandbox

sandbox = create_local_sandbox(cwd)
needs_approval = create_approval({"mode": "interactive"})
bash_fn = create_bash_tool(sandbox, needs_approval)

instructions = build_system_prompt({
    "working_directory": sandbox.working_directory,
    "sandbox_type": sandbox.type,
    "tool_names": tool_names,
    ...
})

async def main() -> None:
    result = await agent.run(prompt, deps=sandbox)
    print(result.output)
    await sandbox.stop()

И заодно не забудьте выкинуть _StubSandbox из прошлого урока, он свою роль отыграл. Для спокойствия добавьте на время отладки print(f"Sandbox: {sandbox.type}"): в консоли должно появиться local.

ЕСЛИ ПОВЕДЕНИЕ ИЗМЕНИЛОСЬ На знакомых промптах ответы должны совпасть с модулем 3, ведь снаружи мы ничего не меняли. Разошлись - значит какой-то инструмент по-прежнему ходит к Path или subprocess напрямую, мимо песочницы. Ищите его, пока разница маленькая и понятная.

Проверьте

uv run python main.py . "Прочитай main.py, первые 5 строк"
uv run python main.py . "Найди TODO в *.py"
uv run python main.py . "Выполни: ls -la"

Если добавили отладочный вывод, в консоли будет Sandbox: local. Все три инструмента работают, шлюз по-прежнему рубит опасные команды, и внешне это тот же агент, что и в модуле 2. Разница только в том, что теперь под ним можно поменять пол.

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

  • sandbox_local.py экспортирует create_local_sandbox
  • Агент запускается с deps=sandbox
  • read / grep / bash работают как в модуле 3
  • sandbox.type == "local" попадает в промпт