MODULE_04 · УРОК 4.1

Интерфейс песочницы

Посмотрите, как сейчас каждый инструмент добирается до данных: read дёргает Path.read_text, grep поднимает subprocess, bash ходит через LocalBashOps. Все трое отлично знают, где живёт диск, и на ноутбуке это никому не мешает. Проблема вылезет, когда агента понадобится отправить в копию проекта или в облачную виртуалку: править придётся все три инструмента, и каждый по-своему. Поэтому сегодня мы не пишем реализацию, а всего лишь договариваемся, что среда умеет делать. Сам двигатель подставим в следующем уроке.

ЧТО ПОЛУЧИТСЯ Файл sandbox.py с Protocol Sandbox. read, grep и bash вызывают sandbox.read_file / sandbox.exec, а не файловую систему напрямую. Агент пока не запустится: настоящей песочницы ещё нет, её пишем в 4.2. На этом уроке достаточно, чтобы файлы компилировались.
НЕ ЗАПУСКАЙТЕ АГЕНТА С ПРОМПТОМ Урок целиком про интерфейс, живого запуска здесь не будет: настоящую песочницу мы напишем в 4.2, а пока agent.run выключим и вместо диска подставим заглушку. Проверять будем py_compile, а не «прочитай AGENTS.md». Если всё-таки запустите main.py с промптом, получите либо тишину, либо NotImplementedError от заглушки. Так и задумано.

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

  • Sandbox (песочница) - среда, в которой агент читает файлы и запускает команды. Сразу уточним: речь не про Docker, а про интерфейс в вашем коде, который говорит «вот этими методами пользоваться можно, других нет».
  • Protocol - уже знакомый из урока 2.2 контракт без наследования: есть у объекта нужные методы - значит подходит. Крякает как утка, и этого достаточно.
  • Бэкенд - конкретная реализация контракта, у нас их будет три: local, memory и cloud. Прелесть в том, что инструменты так и не узнают, какой именно им подставили.

Быстрый путь

  1. Создать sandbox.py - Protocol и тип ExecResult.
  2. В tools_bash.py - фабрика принимает Sandbox, не BashOperations.
  3. В main.py - deps_type=Sandbox, tools вызывают ctx.deps.
  4. Проверить синтаксис: 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_filetool read
execgrep, bash
stopmain.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
ПОЧЕМУ TOOLS СТАЛИ async def sandbox.read_file и sandbox.exec - async. Внутри tool нужен await, а значит сам tool тоже async def. Pydantic AI так умеет.
АГЕНТ ОСТАНЕТСЯ ПРЕЖНИМ Никаких новых умений мы ему не даём, только вытаскиваем файловую систему за интерфейс, чтобы бэкенд можно было подменить. Когда в 4.2 появится локальная песочница, на тех же промптах ответы должны совпасть с модулем 3. Не совпали - значит какой-то инструмент по-прежнему тайком зовёт 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 и ExecResult
  • read / grep / bash ходят через sandbox
  • В main.py нет LocalBashOps; grep/read - async через sandbox
  • agent.run закомментирован до урока 4.2
  • py_compile проходит
  • Агент на этом уроке не отвечает на промпт - так и должно быть