Local-реализация
Контракт мы написали, но Protocol сам по себе ни одного файла не прочитает:
это чертёж, а не станок. Значит, пора собрать первый настоящий бэкенд, и он
будет до неприличия скучным - тот же subprocess и тот же
pathlib, что были в модуле 2, только теперь спрятанные за
интерфейсом Sandbox. Скучный тут комплимент: именно с этой
реализацией мы будем сравнивать memory и cloud, так что чем меньше в ней
сюрпризов, тем лучше. И заодно агент снова начнёт отвечать на промпты.
sandbox_local.py с create_local_sandbox(dir).
Агент снова оживает и ведёт себя точно как в модуле 3, хотя внутри
у него теперь совсем другая проводка.
Слова, которые встретятся
-
Local sandbox - команды выполняются на вашем диске,
в вашей рабочей папке. Слово «песочница» тут не должно расслаблять:
изоляции нет никакой, и
rm -rfсработает по-настоящему, если шлюз подтверждения его пропустит. -
Фабрика - функция
create_local_sandbox, которая возвращает объект, подходящий под контрактSandbox. Инструментам больше ничего и не нужно.
Быстрый путь
- Создать
sandbox_local.py. - В
main.py:sandbox = create_local_sandbox(cwd),agent.run(..., deps=sandbox). - Прогнать знакомые промпты - результат как раньше.
Какие файлы трогаем
| Файл | Что делать |
|---|---|
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.
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работают как в модуле 3sandbox.type == "local"попадает в промпт