Интерфейс песочницы
Посмотрите, как сейчас каждый инструмент добирается до данных:
read дёргает Path.read_text, grep
поднимает subprocess, bash ходит через
LocalBashOps. Все трое отлично знают, где живёт диск, и на
ноутбуке это никому не мешает. Проблема вылезет, когда агента понадобится
отправить в копию проекта или в облачную виртуалку: править придётся
все три инструмента, и каждый по-своему. Поэтому сегодня мы не пишем
реализацию, а всего лишь договариваемся, что среда умеет делать.
Сам двигатель подставим в следующем уроке.
sandbox.py с Protocol Sandbox.
read, grep и bash вызывают
sandbox.read_file / sandbox.exec, а не
файловую систему напрямую. Агент пока не запустится: настоящей
песочницы ещё нет, её пишем в 4.2. На этом уроке достаточно,
чтобы файлы компилировались.
agent.run выключим и вместо
диска подставим заглушку. Проверять будем py_compile, а не
«прочитай AGENTS.md». Если всё-таки запустите main.py
с промптом, получите либо тишину, либо NotImplementedError
от заглушки. Так и задумано.
Слова, которые встретятся
- Sandbox (песочница) - среда, в которой агент читает файлы и запускает команды. Сразу уточним: речь не про Docker, а про интерфейс в вашем коде, который говорит «вот этими методами пользоваться можно, других нет».
- Protocol - уже знакомый из урока 2.2 контракт без наследования: есть у объекта нужные методы - значит подходит. Крякает как утка, и этого достаточно.
- Бэкенд - конкретная реализация контракта, у нас их будет три: local, memory и cloud. Прелесть в том, что инструменты так и не узнают, какой именно им подставили.
Быстрый путь
- Создать
sandbox.py- Protocol и типExecResult. - В
tools_bash.py- фабрика принимаетSandbox, неBashOperations. - В
main.py-deps_type=Sandbox, tools вызываютctx.deps. - Проверить синтаксис:
uv run python -m py_compile …. Промпт пока не гоняйте - ответа не будет.
Какие файлы трогаем
| Файл | Что делать |
|---|---|
sandbox.py |
Создать. Protocol Sandbox, ExecResult. |
tools_bash.py |
Править. create_bash_tool(sandbox, needs_approval) → sandbox.exec. |
main.py |
Править. Tools через sandbox; deps_type=Sandbox. Пока без create_local_sandbox - агент целиком не запустится. |
local_bash.py |
Не удалять - станет деталью local-бэкенда в 4.2. |
Шаг 1. Контракт в sandbox.py
sandbox.py
from typing import Protocol, TypedDict
class ExecResult(TypedDict):
stdout: str
exit_code: int
class Sandbox(Protocol):
type: str
working_directory: str
async def read_file(self, path: str) -> str: ...
async def exec(self, command: str) -> ExecResult: ...
async def stop(self) -> None: ...
...) в Protocol - нормальный Python:
«такой метод должен быть», без тела. Реализация живёт в
LocalSandbox / memory / cloud. Сам
Sandbox ничего не запускает - это чертёж, не
станок. Если написать pass вместо
..., смысл тот же; ... так принято
в typing.
Все методы объявлены async, хотя внутри локального бэкенда
будет обычный синхронный код. Так сделано на будущее: облачная песочница
асинхронная по-настоящему, и одна общая сигнатура сейчас дешевле, чем
развилка в каждом инструменте потом.
Заметьте, как мало тут методов. Поля expires_at и
snapshot приедут в уроке 4.4 и только для облака, а на
сегодня всё сводится к трём действиям: прочитать файл, выполнить
команду, остановить среду.
Зачем каждый метод
| Метод | Кто зовёт |
|---|---|
read_file | tool read |
exec | grep, bash |
stop | main.py в конце (пока no-op) |
type, working_directory | логи, промпт (sandbox_type) |
Шаг 2. Фабрика bash
В tools_bash.py замените BashOperations на Sandbox:
tools_bash.py - суть
from sandbox import Sandbox, ExecResult
def create_bash_tool(
sandbox: Sandbox,
needs_approval: Callable[[str], bool],
) -> Callable[..., str]:
async def bash(command: str) -> str:
"""… тот же docstring …"""
if needs_approval(command):
return (
f'Заблокировано: "{command}" требует подтверждения '
f"(режим политики в main.py)."
)
result = await sandbox.exec(command)
return result["stdout"] or "(нет вывода)"
return bash
Тело функции почти не изменилось, поменялось только имя того, у кого
спрашивают. И не забудьте: ExecResult теперь живёт в
sandbox.py, так что в local_bash.py импорт
стоит переключить на sandbox сразу или уже в 4.2.
Шаг 3. Правки в main.py - по порядку
Здесь правок больше всего, поэтому идём строго сверху вниз: импорты
завязаны на то, что появится ниже, и если прыгать, легко получить
непонятную ошибку на середине. Исходная точка - main.py
в том виде, в каком он остался после модуля 3.
3.1. Импорты
Убрать:
from local_bash import LocalBashOps
Добавить:
from sandbox import Sandbox
Path, create_bash_tool, approval,
prompts - оставить.
3.2. Вместо LocalBashOps - объект sandbox
Было (модуль 3):
local_ops = LocalBashOps(cwd)
needs_approval = create_approval({"mode": "interactive"})
bash_fn = create_bash_tool(local_ops, needs_approval)
Станет (урок 4.1 - заглушка, урок 4.2 - настоящий local):
needs_approval = create_approval({"mode": "interactive"})
# ВРЕМЕННО до урока 4.2 - чтобы main.py компилировался и bash_fn собрался.
# В 4.2 замените на: sandbox = create_local_sandbox(cwd)
class _StubSandbox:
type = "stub"
working_directory: str
def __init__(self, root: Path) -> None:
self.working_directory = str(root.resolve())
async def read_file(self, path: str) -> str:
raise NotImplementedError("Сделайте урок 4.2: create_local_sandbox")
async def exec(self, command: str):
raise NotImplementedError("Сделайте урок 4.2: create_local_sandbox")
async def stop(self) -> None:
pass
sandbox = _StubSandbox(cwd)
bash_fn = create_bash_tool(sandbox, needs_approval)
Заглушка тут не от лени: фабрика bash уже требует
Sandbox, а у LocalBashOps есть только
exec, и без read_file под контракт он
не пролезает. Так что _StubSandbox проживёт ровно один
урок, до 4.2, и будет удалён без сожалений.
3.3. Агент: deps_type=Sandbox
Было:
agent = Agent(
"deepseek:deepseek-chat",
deps_type=Path,
tools=[Tool(bash_fn, takes_ctx=False)],
instructions=instructions,
)
Станет:
agent = Agent(
"deepseek:deepseek-chat",
deps_type=Sandbox,
tools=[Tool(bash_fn, takes_ctx=False)],
instructions=instructions,
)
Промпт (build_system_prompt, AGENTS.md) в этом уроке
не трогаем - sandbox_type: "local" поправите
в 4.2, когда будет sandbox.type.
3.4. Tool grep - async + sandbox.exec
Три изменения: def → async def,
RunContext[Path] → RunContext[Sandbox],
убрать import subprocess и блок proc = subprocess.run(...).
grep - целиком после правки
@agent.tool
async def grep(
ctx: RunContext[Sandbox],
pattern: str,
path: str | None = None,
glob: str | None = None,
) -> str:
"""… docstring без изменений …"""
import shlex
root = Path(ctx.deps.working_directory) / (path or ".")
root = root.resolve()
include = glob or "*.py"
cmd = (
f"grep -rn --exclude-dir=.venv --exclude-dir=__pycache__ "
f"--exclude-dir=.git --include={shlex.quote(include)} "
f"-E {shlex.quote(pattern)} {shlex.quote(str(root))}"
)
result = await ctx.deps.exec(cmd)
lines = [ln for ln in result["stdout"].strip().splitlines() if ln]
if not lines:
return "Совпадений нет."
MAX_MATCHES = 50
truncated = len(lines) > MAX_MATCHES
shown = lines[:MAX_MATCHES]
body = "\n".join(shown)
if truncated:
body += f"\n... ({len(lines)} всего, показаны первые {MAX_MATCHES})"
return body
Разница в одной строчке, но принципиальная: раньше корень получался как
ctx.deps / path, потому что в deps лежал
Path. Теперь там песочница, и корень мы спрашиваем
у неё через working_directory.
3.5. Tool read - async + sandbox.read_file
Снова: async def, RunContext[Sandbox].
Проверки пути - через working_directory, содержимое -
через sandbox, не read_text.
read - целиком после правки
@agent.tool
async def read(
ctx: RunContext[Sandbox],
path: str,
offset: int | None = None,
limit: int | None = None,
) -> str:
"""… docstring без изменений …"""
root = Path(ctx.deps.working_directory).resolve()
abs_path = (root / path).resolve()
if not str(abs_path).startswith(str(root)):
return "Ошибка: путь вне рабочей директории."
if not abs_path.is_file():
return f"Ошибка: файл не найден: {path}"
content = await ctx.deps.read_file(path)
lines = content.splitlines()
start = (offset or 1) - 1
lines = lines[start:]
if limit is not None:
lines = lines[:limit]
truncated = len(lines) > MAX_LINES
if truncated:
lines = lines[:MAX_LINES]
numbered = [
f"{(offset or 1) + i}: {line}" for i, line in enumerate(lines)
]
body = "\n".join(numbered)
if truncated:
body += f"\n... (обрезано на {MAX_LINES} строках)"
return body
3.6. main() - пока не запускаем агента
Было:
async def main() -> None:
result = await agent.run(prompt, deps=cwd)
print(result.output)
На время 4.1 (до create_local_sandbox):
async def main() -> None:
# Заглушка не умеет читать файлы и гонять команды.
# В 4.2 раскомментируете:
# result = await agent.run(prompt, deps=sandbox)
# print(result.output)
# await sandbox.stop()
pass
Оставите agent.run - модель дойдёт до заглушки и получит
NotImplementedError. Ничего не сломалось, просто запускать
пока нечего. После этой правки main.py с любым промптом
честно промолчит, потому что main() пустой,
и это нормальный финал урока.
Сводка по main.py
| Место | Было (модуль 3) | Стало (урок 4.1) |
|---|---|---|
| импорт | LocalBashOps |
Sandbox |
| верх файла | local_ops = LocalBashOps(cwd) |
sandbox = _StubSandbox(cwd) |
| bash | create_bash_tool(local_ops, …) |
create_bash_tool(sandbox, …) |
| Agent | deps_type=Path |
deps_type=Sandbox |
| grep / read | def, RunContext[Path] |
async def, RunContext[Sandbox] |
| grep тело | subprocess.run |
await ctx.deps.exec(cmd) |
| read тело | abs_path.read_text() |
await ctx.deps.read_file(path) |
| main() | deps=cwd |
закомментировано до 4.2; deps=sandbox |
async def
sandbox.read_file и sandbox.exec -
async. Внутри tool нужен await, а значит
сам tool тоже async def. Pydantic AI так умеет.
subprocess или read_text.
Проверьте
Единственная проверка этого урока - компиляция. Запускать
uv run python main.py . "Прочитай…" смысла нет: за диском
там сидит заглушка, которой нечего ответить.
uv run python -m py_compile sandbox.py tools_bash.py main.py
Прошло без ошибок синтаксиса - урок закрыт. Заодно пробегитесь глазами
по read, grep и bash: прямых
read_text и subprocess там остаться не должно,
все эти вызовы в 4.2 переедут внутрь локального бэкенда.
Готово, если:
sandbox.pyэкспортируетSandboxиExecResultread/grep/bashходят через sandbox- В
main.pyнетLocalBashOps; grep/read -asyncчерез sandbox agent.runзакомментирован до урока 4.2py_compileпроходит- Агент на этом уроке не отвечает на промпт - так и должно быть